castrum 0.9.0 → 0.9.2

package/src/rust-ffi/packed.ts

@@ -3,22 +3,32 @@
 // `rust.packed.*` is the zero-copy API: callers pass already-packed buffers and
 // receive the raw packed output, plus the batch metadata/count helpers.
 
-import { asNumber } from './options'
-import { resolvePoolNative, type RustClientContext } from './context'
 import type { PasswordHashOptions } from '../native'
+import { type RustClientContext, resolvePoolNative } from './context'
+import { asNumber } from './options'
 
 /** Raw packed-wire FFI namespace. */
 export interface RustPacked {
   // ── Sync batch (packed in → packed out) ──
+  /** Packed CRC32 batch: packed `[u8[]]` items → packed u32 results. */
   crc32BatchPacked(input: Uint8Array): Uint8Array
+  /** Packed JSON-validity batch: packed `[u8[]]` items → packed 0/1 bitset. */
   jsonValidBatchPacked(input: Uint8Array): Uint8Array
+  /** Packed email-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
   validateEmailBatchPacked(input: Uint8Array): Uint8Array
+  /** Packed UUID-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
   validateUuidBatchPacked(input: Uint8Array): Uint8Array
+  /** Packed IPv4-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
   validateIpv4BatchPacked(input: Uint8Array): Uint8Array
+  /** Packed IPv6-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
   validateIpv6BatchPacked(input: Uint8Array): Uint8Array
+  /** Packed JSON-sum batch: packed `[{id}]` docs → packed `[ok u8][sum i64 LE]`. */
   jsonSumBatchPacked(input: Uint8Array): Uint8Array
+  /** Packed query-string parser batch: packed `[u8[]]` queries → packed pair lists. */
   queryParseBatchPacked(input: Uint8Array): Uint8Array
+  /** Packed cookie-header parser batch: packed `[u8[]]` headers → packed pair lists. */
   cookieParseBatchPacked(input: Uint8Array): Uint8Array
+  /** Packed HTTP-request parser batch: packed `[u8[]]` requests → packed request sections. */
   httpParseRequestBatchPacked(input: Uint8Array): Uint8Array
   /** Batch RFC 6902 JSON Patch (two packed lists, zipped) → packed results. */
   jsonPatchBatchPacked(docs: Uint8Array, patches: Uint8Array): Uint8Array
@@ -26,24 +36,39 @@ export interface RustPacked {
   fnv1A64BatchPacked(input: Uint8Array): Uint8Array
   /** Packed ETag batch (10 strong / 12 weak bytes per item). */
   etagBatchPacked(input: Uint8Array, weak?: boolean | null): Uint8Array
+  /** Packed percent-encoding batch: packed `[u8[]]` items → packed hex-percent bytes. */
   urlEncodeBatchPacked(input: Uint8Array): Uint8Array
+  /** Packed percent-decoding batch: packed `[u8[]]` items → packed decoded bytes (string-safe). */
   urlDecodeBatchPacked(input: Uint8Array): Uint8Array
+  /** Packed percent-decoding batch returning raw bytes (`%FF` preserved). */
   urlDecodeBytesBatchPacked(input: Uint8Array): Uint8Array
+  /** Packed MIME-lookup batch: packed `[u8[]]` extensions → packed media-type strings. */
   mimeFromExtensionBatchPacked(input: Uint8Array): Uint8Array
+  /** Packed WebSocket accept-key batch: packed `[u8[]]` keys → packed base64 SHA-1 results. */
   wsAcceptKeyBatchPacked(input: Uint8Array): Uint8Array
 
   // ── Batch metadata / counts ──
+  /** Valid JSON count in a packed JSON batch (0..n; invalid items not counted). */
   jsonValidBatchCountPacked(input: Uint8Array): number
+  /** Valid-email count in a packed email batch. */
   validateEmailBatchCountPacked(input: Uint8Array): number
+  /** Valid-UUID count in a packed UUID batch. */
   validateUuidBatchCountPacked(input: Uint8Array): number
+  /** Valid-IPv4 count in a packed IPv4 batch. */
   validateIpv4BatchCountPacked(input: Uint8Array): number
+  /** Valid-IPv6 count in a packed IPv6 batch. */
   validateIpv6BatchCountPacked(input: Uint8Array): number
+  /** Total `id` sum across a packed JSON batch (valid items only). */
   jsonSumBatchTotalPacked(input: Uint8Array): number
+  /** Total packed-output length (bytes) a query batch will produce. */
   queryParseBatchTotalLenPacked(input: Uint8Array): number
+  /** Total packed-output length (bytes) a cookie batch will produce. */
   cookieParseBatchTotalLenPacked(input: Uint8Array): number
+  /** Total packed-output length (bytes) an HTTP-request batch will produce. */
   httpParseRequestBatchTotalLenPacked(input: Uint8Array): number
 
   // ── Backend-framework features ──
+  /** Packed Argon2id-hash batch: packed `[u8[]]` passwords + shared salt → packed PHC strings. */
   passwordHashBatchPacked(
     input: Uint8Array,
     salt: Uint8Array,
@@ -53,47 +78,60 @@ export interface RustPacked {
   passwordVerifyBatchPacked(passwords: Uint8Array, phcs: Uint8Array): Uint8Array
   /** Packed URL-resolve batch (two packed lists, zipped) → packed results. */
   urlResolveBatchPacked(bases: Uint8Array, references: Uint8Array): Uint8Array
+  /** Packed AEAD-encrypt batch (packed inputs + shared key/nonce) → packed ciphertexts. */
   aeadEncryptBatchPacked(
     input: Uint8Array,
     key: Uint8Array,
     nonce: Uint8Array,
     algorithm?: string | null,
   ): Uint8Array
+  /** Packed AEAD-decrypt batch (packed inputs + shared key/nonce) → packed plaintexts. */
   aeadDecryptBatchPacked(
     input: Uint8Array,
     key: Uint8Array,
     nonce: Uint8Array,
     algorithm?: string | null,
   ): Uint8Array
+  /** Packed gzip-compress batch: packed `[u8[]]` items → packed gzip streams. */
   gzipCompressBatchPacked(input: Uint8Array, level?: number | null): Uint8Array
+  /** Packed gzip-decompress batch (64 MiB cap per item) → packed plaintexts. */
   gzipDecompressBatchPacked(input: Uint8Array): Uint8Array
+  /** Packed brotli-compress batch: packed `[u8[]]` items → packed brotli streams. */
   brotliCompressBatchPacked(input: Uint8Array, quality?: number | null): Uint8Array
+  /** Packed brotli-decompress batch (64 MiB cap per item) → packed plaintexts. */
   brotliDecompressBatchPacked(input: Uint8Array): Uint8Array
+  /** Packed HS256 JWT-sign batch (packed claims + shared secret) → packed tokens. */
   jwtSignBatchPacked(
     input: Uint8Array,
     secret: Uint8Array,
     ttlSeconds: number | null,
     nowSeconds: number,
   ): Uint8Array
+  /** Packed HS256 JWT-verify batch (packed tokens + shared secret) → packed claims/validity. */
   jwtVerifyBatchPacked(input: Uint8Array, secret: Uint8Array, nowSeconds: number): Uint8Array
   /** Batch HMAC-SHA256 sign (packed in → hex-signature byte results). */
   hmacSha256BatchPacked(input: Uint8Array, key: Uint8Array): Uint8Array
   /** Batch HMAC-SHA256 verify (two packed lists: data + hex sigs, zipped) → bitset. */
   hmacSha256VerifyBatchPacked(input: Uint8Array, sigs: Uint8Array, key: Uint8Array): Uint8Array
+  /** Packed multipart/form-data parser batch (packed bodies + shared boundary) → packed parts. */
   multipartParseBatchPacked(input: Uint8Array, boundary: Uint8Array): Uint8Array
+  /** Packed minijinja template batch: packed contexts + shared source → packed renders. */
   templateRenderBatchPacked(input: Uint8Array, source: string): Uint8Array
+  /** Packed SSE-frame batch: packed data + shared event/id/retry → packed frames. */
   sseEncodeBatchPacked(
     input: Uint8Array,
     event: string | null,
     id: string | null,
     retry: number | null,
   ): Uint8Array
+  /** Packed WebSocket-frame encode batch: packed payloads + shared opcode/mask/fin → packed frames. */
   wsFrameEncodeBatchPacked(
     input: Uint8Array,
     opcode: number,
     mask: boolean,
     fin: boolean,
   ): Uint8Array
+  /** Packed WebSocket-frame decode batch: packed frames → packed (fin, opcode, payload) results. */
   wsFrameDecodeBatchPacked(input: Uint8Array): Uint8Array
 }
 

package/src/rust-ffi/proven.ts

@@ -1,42 +1,28 @@
-// src/rust-ffi/proven.ts — The performance-annotated export surface.
+// src/rust-ffi/proven.ts — the baked "proven selection" surface.
 //
-// `proven` exposes the FULL `rust.*` surface. Each exported function's JSDoc
-// carries its measured performance vs the native JS baseline, annotated from
-// the CPU benchmark report by `scripts/annotate-performance.ts` (run via
-// `bun run check:annotate`). Functions that are SLOWER than the JS baseline
-// (e.g. `jsonParse` vs Bun's JSON.parse, or schema validation vs ajv) are
-// marked `@deprecated`.
-//
-// The registry (`src/shared/proven.ts`) is the single source of truth for the
-// annotations; `bun run check:proven` audits it against the latest benchmark
-// report (with `--fail` to gate CI).
+// `proven` re-exposes the FULL `rust.*` surface (identical object) alongside
+// the pure-data registry (`src/shared/proven.ts`) that states which
+// implementation is the benchmark-proven winner for every op: 'native',
+// 'js', or 'bun' (Bun built-in delegation). The winners are BAKED (committed,
+// benchmark-derived) and verified by `test/unit/shared/proven.test.ts` — no
+// live benchmark audit and no `@deprecated` JSDoc machinery (the old
+// `check:proven` / `check:annotate` friction, intentionally not re-added).
 
 import { rust, type RustClient } from './client'
 
-/**
- * The performance-annotated client: the full {@link RustClient} surface.
- * Each exported function's JSDoc notes its measured performance vs the JS
- * baseline; functions slower than the baseline carry `@deprecated`.
- */
+/** The full `rust.*` surface — identical to `rust`; the proven wiring is baked (see {@link ../shared/proven}). */
 export type ProvenClient = RustClient
 
-/**
- * The full `rust.*` surface with benchmark-annotated JSDoc. Identical to
- * `rust` — the annotations and `@deprecated` markers are what communicate
- * performance now, not a curated subset.
- */
+/** The full `rust.*` surface, exposed for audit. Same object as `rust`. */
 export const proven: ProvenClient = rust
 
-// Re-export the registry + helpers so consumers can audit the surface.
 export {
-  PROVEN_SURFACE,
-  provenStatus,
+  PROVEN_SELECTION,
   isProven,
-  provenSurface,
+  provenEntry,
+  provenImpl,
+  provenStatus,
   provenSummary,
+  provenSurface,
 } from '../shared/proven'
-export type {
-  PerformanceStatus,
-  ProvenEntry,
-  ProvenKey,
-} from '../shared/proven'
+export type { ProvenEntry, ProvenImpl, ProvenStatus } from '../shared/proven'

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

@@ -2,48 +2,71 @@
 //
 // Mirrors rust/crypto/*: base64/hex codecs, signed cookies, CSRF, random
 // tokens, JWT, password hashing and AEAD.
+//
+// Runtime dispatch is centralized in the adapter (`ctx.runtime`): Bun built-in
+// delegations (randomToken/base64*/hexEncode) come from `builtins.has(op)` and
+// the native call from `transport.resolve(op)` / `transport.ffi` (bun:ffi
+// first, napi fallback) — no inline `isBun()` / `getBunFFI()`.
 
 import type { PasswordHashOptions } from '../../native'
-import { getBunFFI } from '../../native/ffi'
-import { isBun } from '../../shared/runtime'
-import type { RustClientContext } from '../context'
-
-const encoder = new TextEncoder()
-const decoder = new TextDecoder()
+import { encoder } from '../../shared/bytes'
+import { writeInto } from '../into'
+import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
 
 /** Auth / crypto scalar methods (`Pick<RustScalar, ...>`). */
 export function buildCrypto(ctx: RustClientContext) {
   const { addon } = ctx
+  const { builtins, transport } = ctx.runtime
+  // Hoist the immutable per-runtime builtin-delegation decisions into a
+  // bind-time map (BUILTIN_OPS is a module constant — never mutated after
+  // load) so the hot path reads object properties instead of `Set.has`.
+  const HAS = {
+    randomToken: builtins.has('randomToken'),
+    base64Encode: builtins.has('base64Encode'),
+    base64UrlEncode: builtins.has('base64UrlEncode'),
+    hexEncode: builtins.has('hexEncode'),
+  }
+  // Lazy-memoized ffi surface: binds on first call, single local read after.
+  const ffi = memoizeFfi(transport)
 
   return {
-    randomToken(byteLen: number): Uint8Array {
+    randomToken(byteLen: number): Uint8Array | string {
       // Optimal by default under Bun: `crypto.getRandomValues` + native hex
-      // beats the rust+FFI crossing for token-sized draws (decision matrix).
-      // Preserves the native 16 MiB allocation guard and the hex format
-      // (2n bytes). Node keeps the addon.
-      if (isBun()) {
-        if (byteLen > 16 * 1024 * 1024) {
-          throw new RangeError('randomToken: byteLen exceeds 16 MiB limit')
-        }
-        return encoder.encode(
-          Buffer.from(crypto.getRandomValues(new Uint8Array(byteLen))).toString('hex'),
-        )
+      // beats the rust+FFI crossing for token-sized draws (decision matrix);
+      // the builtin carries the 16 MiB guard and returns the hex STRING. Node
+      // keeps the addon.
+      if (HAS.randomToken) return builtins.randomToken(byteLen)
+      return resolveNative(ctx, 'randomToken')(byteLen) as Uint8Array | string
+    },
+    randomTokenInto(byteLen: number, output: Uint8Array): number {
+      // Pooled sibling — writes `byteLen*2` hex chars into `output`. FFI path
+      // uses the native `_into` (no cstring round-trip); without ffi the Bun
+      // builtin (or addon) hex is written into the caller buffer.
+      const f = ffi()
+      if (f) return f.randomTokenInto(byteLen, output)
+      if (HAS.randomToken) {
+        const need = byteLen * 2
+        if (output.length < need) throw new Error('random token: output buffer too small')
+        output.set(encoder.encode(builtins.randomToken(byteLen) as string))
+        return need
       }
-      const ffi = getBunFFI()
-      if (ffi) return ffi.randomToken(byteLen)
-      return addon.randomToken(byteLen)
+      const bytes = addon.randomToken(byteLen)
+      return writeInto('random token', output, bytes)
     },
-    base64Encode(input: Uint8Array, urlSafe?: boolean, padding?: boolean): Uint8Array {
+    base64Encode(input: Uint8Array, urlSafe?: boolean, padding?: boolean): Uint8Array | string {
       // Bun's Buffer base64 (SIMD) beats the rust+FFI crossing (~2x, measured)
-      // for the standard (url-safe=false, padded) case; byte-parity pinned by
-      // test/unit/features/encoding.test.ts. url-safe/unpadded falls through to
-      // the native path (Buffer can't express base64url without string surgery).
-      if (isBun() && !urlSafe && padding !== false) {
-        return encoder.encode(Buffer.from(input).toString('base64'))
+      // for the standard (url-safe=false, padded) case; the builtin returns
+      // `undefined` for url-safe/unpadded so those fall through to native.
+      // Parity pinned by test/unit/features/encoding.test.ts.
+      if (HAS.base64Encode) {
+        const encoded = builtins.base64Encode(input, urlSafe, padding)
+        if (encoded !== undefined) return encoded
       }
-      const ffi = getBunFFI()
-      if (ffi) return ffi.base64Encode(input, urlSafe, padding)
-      return addon.base64Encode(input, urlSafe ?? undefined, padding ?? undefined)
+      return resolveNative(ctx, 'base64Encode')(
+        input,
+        urlSafe ?? undefined,
+        padding ?? undefined,
+      ) as Uint8Array | string
     },
     base64EncodeInto(
       input: Uint8Array,
@@ -51,14 +74,19 @@ export function buildCrypto(ctx: RustClientContext) {
       urlSafe?: boolean,
       padding?: boolean,
     ): number {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.base64EncodeInto(input, output, urlSafe, padding)
-      return addon.base64EncodeInto(input, output, urlSafe ?? undefined, padding ?? undefined)
+      return resolveNative(ctx, 'base64EncodeInto')(
+        input,
+        output,
+        urlSafe ?? undefined,
+        padding ?? undefined,
+      ) as number
     },
     base64Decode(input: Uint8Array, urlSafe?: boolean, padding?: boolean): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.base64Decode(input, urlSafe, padding)
-      return addon.base64Decode(input, urlSafe ?? undefined, padding ?? undefined)
+      return resolveNative(ctx, 'base64Decode')(
+        input,
+        urlSafe ?? undefined,
+        padding ?? undefined,
+      ) as Uint8Array
     },
     base64DecodeInto(
       input: Uint8Array,
@@ -66,69 +94,73 @@ export function buildCrypto(ctx: RustClientContext) {
       urlSafe?: boolean,
       padding?: boolean,
     ): number {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.base64DecodeInto(input, output, urlSafe, padding)
-      return addon.base64DecodeInto(input, output, urlSafe ?? undefined, padding ?? undefined)
+      return resolveNative(ctx, 'base64DecodeInto')(
+        input,
+        output,
+        urlSafe ?? undefined,
+        padding ?? undefined,
+      ) as number
     },
-    base64UrlEncode(input: Uint8Array): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.base64Encode(input, true, false)
+    base64UrlEncode(input: Uint8Array): Uint8Array | string {
+      // Bun's native `Buffer.toString('base64url')` (SIMD) beats the rust+FFI
+      // crossing — same delegation rationale as `base64Encode`; verified
+      // byte-parity with the Rust `URL_SAFE_NO_PAD` engine
+      // (test/unit/features/encoding.test.ts). The ffi path reuses
+      // `base64Encode(input, true, false)` (no dedicated base64UrlEncode symbol).
+      if (HAS.base64UrlEncode) return builtins.base64UrlEncode(input)
+      const f = ffi()
+      if (f) return f.base64Encode(input, true, false)
       return addon.base64UrlEncode(input)
     },
     base64UrlDecode(input: Uint8Array): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.base64Decode(input, true, false)
+      const f = ffi()
+      if (f) return f.base64Decode(input, true, false)
       return addon.base64UrlDecode(input)
     },
-    hexEncode(input: Uint8Array): Uint8Array {
-      // Bun fast path writes straight into a fresh buffer — no napi Buffer
-      // alloc + copy (~13x cheaper crossing for small inputs).
-      const ffi = getBunFFI()
-      if (ffi) return ffi.hexEncode(input)
-      return addon.hexEncode(input)
+    hexEncode(input: Uint8Array): Uint8Array | string {
+      // Bun's native `Buffer.toString('hex')` (SIMD) beats the rust+FFI
+      // crossing, especially for large inputs. Verified byte-parity with the
+      // Rust hex encoder. Bun returns the hex STRING; Node keeps the addon bytes.
+      if (HAS.hexEncode) return builtins.hexEncode(input)
+      return resolveNative(ctx, 'hexEncode')(input) as Uint8Array | string
     },
     hexEncodeInto(input: Uint8Array, output: Uint8Array): number {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.hexEncodeInto(input, output)
-      return addon.hexEncodeInto(input, output)
+      return resolveNative(ctx, 'hexEncodeInto')(input, output) as number
     },
     hexDecode(input: Uint8Array): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.hexDecode(input)
-      return addon.hexDecode(input)
+      return resolveNative(ctx, 'hexDecode')(input) as Uint8Array
     },
     hexDecodeInto(input: Uint8Array, output: Uint8Array): number {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.hexDecodeInto(input, output)
-      return addon.hexDecodeInto(input, output)
+      return resolveNative(ctx, 'hexDecodeInto')(input, output) as number
     },
-    signCookie(value: Uint8Array, secret: Uint8Array): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.signCookie(value, secret)
-      return addon.signCookie(value, secret)
+    signCookie(value: Uint8Array, secret: Uint8Array): Uint8Array | string {
+      return resolveNative(ctx, 'signCookie')(value, secret) as Uint8Array | string
     },
     signCookieInto(value: Uint8Array, secret: Uint8Array, output: Uint8Array): number {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.signCookieInto(value, secret, output)
-      const bytes = addon.signCookie(value, secret)
-      if (output.length < bytes.length) throw new Error('sign cookie: output buffer too small')
-      output.set(bytes)
-      return bytes.length
+      const f = ffi()
+      if (f) return f.signCookieInto(value, secret, output)
+      return writeInto('sign cookie', output, addon.signCookie(value, secret))
+    },
+    verifyCookie(signed: Uint8Array, secret: Uint8Array): Uint8Array | string | null {
+      return resolveNative(ctx, 'verifyCookie')(signed, secret) as Uint8Array | string | null
+    },
+    verifyCookieInto(signed: Uint8Array, secret: Uint8Array, output: Uint8Array): number | null {
+      const f = ffi()
+      if (f) return f.verifyCookieInto(signed, secret, output)
+      const value = addon.verifyCookie(signed, secret)
+      if (value === null) return null
+      return writeInto('verify cookie', output, value)
     },
-    verifyCookie(signed: Uint8Array, secret: Uint8Array): Uint8Array | null {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.verifyCookie(signed, secret)
-      return addon.verifyCookie(signed, secret)
+    csrfToken(secret: Uint8Array): Uint8Array | string {
+      return resolveNative(ctx, 'csrfToken')(secret) as Uint8Array | string
     },
-    csrfToken(secret: Uint8Array): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.csrfToken(secret)
-      return addon.csrfToken(secret)
+    csrfTokenInto(secret: Uint8Array, output: Uint8Array): number {
+      const f = ffi()
+      if (f) return f.csrfTokenInto(secret, output)
+      return writeInto('csrf token', output, addon.csrfToken(secret))
     },
     csrfVerify(token: Uint8Array, secret: Uint8Array): boolean {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.csrfVerify(token, secret)
-      return addon.csrfVerify(token, secret)
+      return resolveNative(ctx, 'csrfVerify')(token, secret) as boolean
     },
     jwtSign(
       claims: Record<string, unknown>,
@@ -136,6 +168,23 @@ export function buildCrypto(ctx: RustClientContext) {
       ttlSeconds?: number | null,
       nowSeconds?: number,
     ): Uint8Array {
+      // FFI-first: route the object claims through the C-ABI `jwtSignBytes`
+      // (pre-serialized JSON). The engine returns the token as a string
+      // (native transfer); re-encode to bytes to keep the public BYTE contract
+      // (batch/benchmark consumers compare bytes). NOTE: JSON.stringify
+      // preserves JS insertion order while napi's serde_json sorts keys — for
+      // multi-key claims the two transports emit different-but-equally-valid
+      // tokens (both verify; parity tests cross-verify semantically).
+      const f = ffi()
+      if (f) {
+        const token = f.jwtSignBytes(
+          encoder.encode(JSON.stringify(claims)),
+          secret,
+          ttlSeconds ?? 0,
+          nowSeconds ?? Math.floor(Date.now() / 1000),
+        )
+        return encoder.encode(token)
+      }
       return addon.jwtSign(
         claims,
         secret,
@@ -148,12 +197,12 @@ export function buildCrypto(ctx: RustClientContext) {
       secret: Uint8Array,
       ttlSeconds?: number | null,
       nowSeconds?: number,
-    ): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) {
+    ): Uint8Array | string {
+      const f = ffi()
+      if (f) {
         // The C-ABI `ttl <= 0` sentinel matches napi's Option<i64> (inject only
         // when positive), and nowSeconds defaults identically.
-        return ffi.jwtSignBytes(
+        return f.jwtSignBytes(
           claimsJson,
           secret,
           ttlSeconds ?? 0,
@@ -167,19 +216,55 @@ export function buildCrypto(ctx: RustClientContext) {
         nowSeconds ?? Math.floor(Date.now() / 1000),
       )
     },
+    jwtSignBytesInto(
+      claimsJson: Uint8Array,
+      secret: Uint8Array,
+      output: Uint8Array,
+      ttlSeconds?: number | null,
+      nowSeconds?: number,
+    ): number {
+      const f = ffi()
+      if (f) {
+        return f.jwtSignBytesInto(
+          claimsJson,
+          secret,
+          ttlSeconds ?? 0,
+          nowSeconds ?? Math.floor(Date.now() / 1000),
+          output,
+        )
+      }
+      return writeInto(
+        'jwt sign',
+        output,
+        addon.jwtSignBytes(
+          claimsJson,
+          secret,
+          ttlSeconds ?? null,
+          nowSeconds ?? Math.floor(Date.now() / 1000),
+        ),
+      )
+    },
     jwtVerify(token: Uint8Array, secret: Uint8Array, nowSeconds?: number): unknown {
+      const f = ffi()
+      if (f) {
+        // Verify via the FFI cstring path (castrum_jwt_verify): the engine
+        // clones the claims JSON string at return (zero decode), and `null` =
+        // invalid signature / expired / malformed → null (napi Option parity).
+        const claims = f.jwtVerify(token, secret, nowSeconds ?? Math.floor(Date.now() / 1000))
+        return claims === null ? null : (JSON.parse(claims) as unknown)
+      }
       return addon.jwtVerify(token, secret, nowSeconds ?? Math.floor(Date.now() / 1000))
     },
     passwordHash(
       password: Uint8Array,
       salt: Uint8Array,
       options?: PasswordHashOptions | null,
-    ): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) {
+    ): Uint8Array | string {
+      const f = ffi()
+      if (f) {
         // Resolve the napi defaults (rust/crypto/argon2.rs resolve_opts).
         const o = options ?? {}
-        return ffi.passwordHash(
+        return f.passwordHash(
           password,
           salt,
           o.mCost ?? 19456,
@@ -191,18 +276,16 @@ export function buildCrypto(ctx: RustClientContext) {
       return addon.passwordHash(password, salt, options ?? null)
     },
     passwordVerify(password: Uint8Array, phc: Uint8Array): boolean {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.passwordVerify(password, phc)
-      return addon.passwordVerify(password, phc)
+      return resolveNative(ctx, 'passwordVerify')(password, phc) as boolean
     },
     passwordHashBcrypt(password: Uint8Array, cost: number): string {
-      const ffi = getBunFFI()
-      if (ffi) return decoder.decode(ffi.passwordHashBcrypt(password, cost))
-      return addon.passwordHashBcrypt(password, cost)
+      return resolveNative(ctx, 'passwordHashBcrypt')(password, cost) as string
     },
     passwordVerifyBcrypt(password: Uint8Array, hash: string): boolean {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.passwordVerifyBcrypt(password, encoder.encode(hash))
+      // FFI-first: `hash` is a `cstring` ARG (the engine transcodes the PHC
+      // string in-engine — no JS encode); `password` stays `(ptr,len)` bytes.
+      const f = ffi()
+      if (f) return f.passwordVerifyBcrypt(password, hash)
       return addon.passwordVerifyBcrypt(password, hash)
     },
     pbkdf2Sha256(
@@ -211,9 +294,7 @@ export function buildCrypto(ctx: RustClientContext) {
       rounds: number,
       dkLen: number,
     ): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.pbkdf2Sha256(password, salt, rounds, dkLen)
-      return addon.pbkdf2Sha256(password, salt, rounds, dkLen)
+      return resolveNative(ctx, 'pbkdf2Sha256')(password, salt, rounds, dkLen) as Uint8Array
     },
     aeadEncrypt(
       key: Uint8Array,
@@ -221,9 +302,9 @@ export function buildCrypto(ctx: RustClientContext) {
       plaintext: Uint8Array,
       algorithm?: string | null,
     ): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) {
-        return ffi.aeadEncrypt(key, nonce, plaintext, algorithm === 'chacha20-poly1305' ? 1 : 0)
+      const f = ffi()
+      if (f) {
+        return f.aeadEncrypt(key, nonce, plaintext, algorithm === 'chacha20-poly1305' ? 1 : 0)
       }
       return addon.aeadEncrypt(key, nonce, plaintext, algorithm ?? null)
     },
@@ -234,9 +315,9 @@ export function buildCrypto(ctx: RustClientContext) {
       output: Uint8Array,
       algorithm?: string | null,
     ): number {
-      const ffi = getBunFFI()
-      if (ffi) {
-        return ffi.aeadEncryptInto(
+      const f = ffi()
+      if (f) {
+        return f.aeadEncryptInto(
           key,
           nonce,
           plaintext,
@@ -255,9 +336,9 @@ export function buildCrypto(ctx: RustClientContext) {
       ciphertext: Uint8Array,
       algorithm?: string | null,
     ): Uint8Array | null {
-      const ffi = getBunFFI()
-      if (ffi) {
-        return ffi.aeadDecrypt(key, nonce, ciphertext, algorithm === 'chacha20-poly1305' ? 1 : 0)
+      const f = ffi()
+      if (f) {
+        return f.aeadDecrypt(key, nonce, ciphertext, algorithm === 'chacha20-poly1305' ? 1 : 0)
       }
       return addon.aeadDecrypt(key, nonce, ciphertext, algorithm ?? null)
     },