@c9up/ream 0.2.3 → 0.2.5

package/src/env/Env.ts

@@ -68,6 +68,12 @@ export class Env<Values extends Record<string, unknown>> {
 
   readonly #values: Values
 
+  /**
+   * Private on purpose: an `Env` is only ever built by {@link create}, which is
+   * what validates. `private` and not `#` because a private CONSTRUCTOR has no
+   * native form — this is the one place the keyword carries a meaning `#`
+   * cannot express.
+   */
   private constructor(values: Values) {
     this.#values = values
   }

package/src/events/Emitter.ts

@@ -66,10 +66,10 @@ export type UnsubscribeFunction = () => void
 export type AsyncUnsubscribeFunction = () => Promise<void>
 
 export class Emitter {
-  private bus: EventBus
-  private resolver?: EmitterResolver
-  private classListeners: Map<EventConstructor, Listener[]> = new Map()
-  private stringListeners: Map<string, ListenerFn[]> = new Map()
+  #bus: EventBus
+  #resolver?: EmitterResolver
+  #classListeners: Map<EventConstructor, Listener[]> = new Map()
+  #stringListeners: Map<string, ListenerFn[]> = new Map()
   /** Set while faking; every emission lands here instead of running. */
   #buffer?: EventsBuffer
   /** Which events are faked. `undefined` means all of them. */
@@ -78,8 +78,8 @@ export class Emitter {
   readonly #anySubscriptions = new Map<(eventName: string, data: unknown) => void, Set<number>>()
 
   constructor(bus: EventBus, resolver?: EmitterResolver) {
-    this.bus = bus
-    this.resolver = resolver
+    this.#bus = bus
+    this.#resolver = resolver
   }
 
   // ─── Class-based events ───────────────────────────────────
@@ -102,18 +102,18 @@ export class Emitter {
   on<T>(event: string, listener: ListenerFn<T>): UnsubscribeFunction
   on(event: EventConstructor | string, listener: Listener): UnsubscribeFunction {
     if (typeof event === 'string') {
-      const list = this.stringListeners.get(event) ?? []
+      const list = this.#stringListeners.get(event) ?? []
       list.push(listener as ListenerFn)
-      this.stringListeners.set(event, list)
+      this.#stringListeners.set(event, list)
       return () => {
         this.off(event, listener as ListenerFn)
       }
     }
-    const list = this.classListeners.get(event) ?? []
+    const list = this.#classListeners.get(event) ?? []
     list.push(listener)
-    this.classListeners.set(event, list)
+    this.#classListeners.set(event, list)
     return () => {
-      const current = this.classListeners.get(event)
+      const current = this.#classListeners.get(event)
       if (!current) return
       const index = current.indexOf(listener)
       if (index !== -1) current.splice(index, 1)
@@ -159,11 +159,11 @@ export class Emitter {
 
   /** Remove one listener from an event (AdonisJS `off`). */
   off(event: string, listener: ListenerFn): void {
-    const list = this.stringListeners.get(event)
+    const list = this.#stringListeners.get(event)
     if (!list) return
     const index = list.indexOf(listener)
     if (index !== -1) list.splice(index, 1)
-    if (list.length === 0) this.stringListeners.delete(event)
+    if (list.length === 0) this.#stringListeners.delete(event)
   }
 
   /** Alias of {@link off} (AdonisJS `clearListener`). */
@@ -173,13 +173,13 @@ export class Emitter {
 
   /** Drop every listener of one event (AdonisJS `clearListeners`). */
   clearListeners(event: string): void {
-    this.stringListeners.delete(event)
+    this.#stringListeners.delete(event)
   }
 
   /** Drop every listener of every event (AdonisJS `clearAllListeners`). */
   clearAllListeners(): void {
-    this.stringListeners.clear()
-    this.classListeners.clear()
+    this.#stringListeners.clear()
+    this.#classListeners.clear()
   }
 
   /**
@@ -191,17 +191,17 @@ export class Emitter {
    */
   get eventsListeners(): Map<EventConstructor | string, Listener[]> {
     const all = new Map<EventConstructor | string, Listener[]>()
-    for (const [event, listeners] of this.classListeners) all.set(event, [...listeners])
-    for (const [event, listeners] of this.stringListeners) all.set(event, [...listeners])
+    for (const [event, listeners] of this.#classListeners) all.set(event, [...listeners])
+    for (const [event, listeners] of this.#stringListeners) all.set(event, [...listeners])
     return all
   }
 
   /** How many listeners an event has, or all of them (AdonisJS `listenerCount`). */
   listenerCount(event?: string): number {
-    if (event !== undefined) return this.stringListeners.get(event)?.length ?? 0
+    if (event !== undefined) return this.#stringListeners.get(event)?.length ?? 0
     let total = 0
-    for (const list of this.stringListeners.values()) total += list.length
-    for (const list of this.classListeners.values()) total += list.length
+    for (const list of this.#stringListeners.values()) total += list.length
+    for (const list of this.#classListeners.values()) total += list.length
     return total
   }
 
@@ -216,7 +216,7 @@ export class Emitter {
    */
   async #dispatchListeners(event: string, data: unknown, serial: boolean): Promise<void> {
     const listeners = [
-      ...(this.stringListeners.get(event) ?? []),
+      ...(this.#stringListeners.get(event) ?? []),
       ...this.#wildcardListenersFor(event),
     ]
     if (listeners.length === 0) return
@@ -224,7 +224,7 @@ export class Emitter {
       try {
         await fn(data)
       } catch (err) {
-        this.emitError(event, err)
+        this.#emitError(event, err)
       }
     }
     if (serial) {
@@ -281,17 +281,17 @@ export class Emitter {
     try {
       payload = JSON.stringify(this.#wrapForBus(data))
     } catch (err) {
-      this.emitError(event, err)
+      this.#emitError(event, err)
       return
     }
-    void this.bus.emit(event, payload).catch((err: unknown) => {
-      this.emitError(event, err)
+    void this.#bus.emit(event, payload).catch((err: unknown) => {
+      this.#emitError(event, err)
     })
   }
 
   /** Emit an error event for listener failures. */
-  private emitError(event: string, error: unknown): void {
-    const errorListeners = this.stringListeners.get('emitter:error')
+  #emitError(event: string, error: unknown): void {
+    const errorListeners = this.#stringListeners.get('emitter:error')
     if (errorListeners && errorListeners.length > 0) {
       for (const fn of errorListeners) {
         try {
@@ -314,7 +314,7 @@ export class Emitter {
     // Faked by the class, as AdonisJS does — `fake([TaskDeclared])` catches
     // `new TaskDeclared(...).emit()`.
     if (this.#capture(EventClass, event)) return
-    const listeners = this.classListeners.get(EventClass) ?? []
+    const listeners = this.#classListeners.get(EventClass) ?? []
     const name = (EventClass as { eventName?: string }).eventName ?? classToEventName(EventClass)
 
     // Per-listener error isolation — mirrors the string `emit()` contract.
@@ -326,22 +326,22 @@ export class Emitter {
       try {
         if (isListenerClass(listener)) {
           // Listener class — resolve via container for @inject() support
-          const instance = this.resolver
-            ? await this.resolver.make(listener as ListenerConstructor<T>)
+          const instance = this.#resolver
+            ? await this.#resolver.make(listener as ListenerConstructor<T>)
             : new (listener as ListenerConstructor<T>)()
           await instance.handle(event)
         } else {
           await (listener as ListenerFn<T>)(event)
         }
       } catch (err) {
-        this.emitError(name, err)
+        this.#emitError(name, err)
       }
     }
 
     // Also push through EventBus — same correlation-envelope wrapping as
     // the string-event path so distributed tracing covers class events too.
     // Reached unconditionally: a listener failure above no longer skips it.
-    await this.bus.emit(name, JSON.stringify(this.#wrapForBus(event)))
+    await this.#bus.emit(name, JSON.stringify(this.#wrapForBus(event)))
   }
 
   // ─── Faking (AdonisJS `fake` / `restore`) ─────────────────
@@ -436,7 +436,7 @@ export class Emitter {
     pattern: string,
     listener: (eventName: string, data: unknown) => void,
   ): Promise<number> {
-    return this.bus.subscribe(pattern, (eventJson: string) => {
+    return this.#bus.subscribe(pattern, (eventJson: string) => {
       try {
         const event = JSON.parse(eventJson)
         // The bus delivers a Rust `Event` envelope whose `correlationId`
@@ -471,7 +471,7 @@ export class Emitter {
    */
   async offAny(listenerOrId: number | ((eventName: string, data: unknown) => void)): Promise<this> {
     if (typeof listenerOrId === 'number') {
-      await this.bus.unsubscribe(listenerOrId)
+      await this.#bus.unsubscribe(listenerOrId)
       for (const ids of this.#anySubscriptions.values()) ids.delete(listenerOrId)
       return this
     }
@@ -479,13 +479,13 @@ export class Emitter {
     const ids = this.#anySubscriptions.get(listenerOrId)
     if (!ids) return this
     this.#anySubscriptions.delete(listenerOrId)
-    await Promise.all([...ids].map((id) => this.bus.unsubscribe(id)))
+    await Promise.all([...ids].map((id) => this.#bus.unsubscribe(id)))
     return this
   }
 
   /** Check if a pattern matches an event name (wildcard matching via Rust). */
   matchesPattern(pattern: string, eventName: string): boolean {
-    return this.bus.matchesWildcard(pattern, eventName)
+    return this.#bus.matchesWildcard(pattern, eventName)
   }
 
   // ─── Request / Reply ──────────────────────────────────────
@@ -499,7 +499,7 @@ export class Emitter {
     // Same correlation injection as `emit()` so a `setCorrelationId`
     // preceding a request actually reaches the responder via the
     // top-level `correlationId` field on the parsed payload.
-    const result = await this.bus.request(name, JSON.stringify(this.#wrapForBus(data)), timeoutMs)
+    const result = await this.#bus.request(name, JSON.stringify(this.#wrapForBus(data)), timeoutMs)
     try {
       return JSON.parse(result) as T
     } catch {
@@ -519,7 +519,7 @@ export class Emitter {
     name: string,
     handler: (eventJson: string, reply: (response: string) => void) => void,
   ): void {
-    this.bus.onRequest(name, handler)
+    this.#bus.onRequest(name, handler)
   }
 
   // ─── Correlation context ──────────────────────────────────
@@ -565,13 +565,13 @@ export class Emitter {
     // AdonisJS makes the argument optional: no argument asks whether ANY event
     // has a listener at all.
     if (event === undefined) return this.listenerCount() > 0
-    if (typeof event === 'string') return (this.stringListeners.get(event)?.length ?? 0) > 0
-    return (this.classListeners.get(event)?.length ?? 0) > 0
+    if (typeof event === 'string') return (this.#stringListeners.get(event)?.length ?? 0) > 0
+    return (this.#classListeners.get(event)?.length ?? 0) > 0
   }
 
   /** Get the number of Rust-side subscriptions. */
   async subscriptionCount(): Promise<number> {
-    return this.bus.subscriptionCount()
+    return this.#bus.subscriptionCount()
   }
 }
 
@@ -593,7 +593,10 @@ export class BaseEvent {
   /**
    * Subclasses declare their own payload parameters; this signature only has
    * to be wide enough for `dispatch` to forward them (AdonisJS does the same).
+   * It widens `ConstructorParameters<typeof BaseEvent>` from `[]` to a rest
+   * parameter, which is what lets `dispatch` call `new this(...args)`.
    */
+  // biome-ignore lint/complexity/noUselessConstructor: it widens ConstructorParameters for dispatch — removing it fails to compile
   constructor(..._args: unknown[]) {}
 
   static eventName?: string

package/src/events/native.ts

@@ -10,22 +10,28 @@
 
 import { loadNapi } from '../helpers/napi-loader.js'
 
-/** Rust-backed bus surface (mirrors the napi `#[napi] EventBus` exports). */
-export interface EventBus {
-  emit(name: string, data: string): Promise<string>
-  subscribe(pattern: string, callback: (eventJson: string) => void): number
-  unsubscribe(subscriptionId: number): Promise<void>
-  onRequest(
-    name: string,
-    callback: (eventJson: string, reply: (response: string) => void) => void,
-  ): void
-  request(name: string, data: string, timeoutMs?: number): Promise<string>
-  matchesWildcard(pattern: string, eventName: string): boolean
-  subscriptionCount(): Promise<number>
-}
+/**
+ * Rust-backed bus surface.
+ *
+ * Re-exported from the generated declarations rather than restated here: the
+ * shape is derived from the `#[napi]` items themselves, so it cannot drift
+ * from the Rust. It did before — making `Bus::on_request` synchronous changed
+ * the Rust with nothing on this side to notice.
+ *
+ * Run `pnpm build:napi-types` after touching a `#[napi]` signature.
+ */
+import type { EventBus as NativeEventBus } from '../native/generated.js'
 
+/**
+ * What the `events` binary exports.
+ *
+ * The instance shape comes from the generated declarations — derived from the
+ * `#[napi]` items, so it cannot drift from the Rust without the generated file
+ * changing. Only the constructor is named here, because the binary is a module
+ * object rather than a class the loader can see.
+ */
 interface EventsNative {
-  EventBus: new (requestHandlerTimeoutMs?: number) => EventBus
+  EventBus: new (requestHandlerTimeoutMs?: number) => NativeEventBus
 }
 
 const native = loadNapi<EventsNative>({
@@ -35,3 +41,4 @@ const native = loadNapi<EventsNative>({
 })
 
 export const EventBus = native.EventBus
+export type EventBus = NativeEventBus

package/src/http/HttpContext.ts

@@ -14,7 +14,7 @@ import type { MatchedParams } from '../router/Router.js'
 import type { CookieSigner } from '../security/CookieSigner.js'
 import type { SignedUrl } from '../security/SignedUrl.js'
 import type { Session } from '../session/Session.js'
-import type { Authenticators } from '../types/authenticators.js'
+import type { Authenticators } from '../types/index.js'
 import { Macroable } from '../utils/Macroable.js'
 import type { RouteUrlResolver } from './RedirectBuilder.js'
 import { RedirectBuilder } from './RedirectBuilder.js'

package/src/http/Request.ts

@@ -1004,19 +1004,6 @@ function isIpLiteral(host: string): boolean {
   return /^(\d{1,3}\.){3}\d{1,3}$/.test(host)
 }
 
-/**
- * Decode a percent-encoded segment without throwing on malformed input.
- * Browsers happily send `q=%E0%A4%A` (truncated UTF-8 sequences) — refusing
- * the whole request would let any client knock the route handler offline.
- */
-function safeDecode(value: string): string {
-  try {
-    return decodeURIComponent(value)
-  } catch {
-    return value
-  }
-}
-
 interface AcceptEntry {
   value: string
   q: number

package/src/index.ts

@@ -8,6 +8,7 @@ import 'reflect-metadata'
 
 // ─── Core ───────────────────────────────────────────────────
 
+export type { AppEnvironment, ApplicationMode, ApplicationState } from './Application.js'
 export { Application } from './Application.js'
 export { ConfigStore, configProvider, defineModuleConfig, env } from './ConfigLoader.js'
 export { Container } from './container/Container.js'
@@ -242,7 +243,6 @@ export type {
   FlagMetaData,
 } from './console/types.js'
 export type {
-  AppEnvironment,
   HyperServerLike,
   IgnitorConfig,
   ReamrcConfig,
@@ -371,4 +371,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.3'
+export const VERSION = '0.2.5'

package/src/native/generated.ts

@@ -0,0 +1,291 @@
+// GENERATED FROM THE RUST — do not edit.
+//
+// Produced by scripts/generate-napi-types.mjs from napi-derive's type-def
+// output. Editing this file by hand puts it back where it started: a
+// description that can disagree with the code it describes.
+
+/**
+ * Typed response object crossing the TS→NAPI→Rust boundary.
+ *
+ * Using `#[napi(object)]` (instead of `String` carrying JSON) means napi-rs
+ * walks the JS object tree directly into Rust fields — zero JSON parse overhead.
+ *
+ * When `stream_id` is set, `body` is ignored and the hyper response is fed
+ * from the matching entry in the shared `StreamRegistry`. The handler must
+ * have called [`HyperServer::register_stream`] with that id BEFORE
+ * returning, otherwise the response collapses to a 500 (E_STREAM_UNKNOWN).
+ */
+
+export interface NapiResponse {
+  status: number
+  headers: Record<string, string>
+  body: string
+  streamId?: string
+}
+
+/**
+ * Configuration for the wire-level shield filter. Mirrors the Rust
+ * `ShieldConfig` shape; the JS layer constructs it from `ShieldMiddleware`
+ * options at boot and hands it off to `HyperServer.configureShield`.
+ */
+
+export interface NapiShieldConfig {
+  pathTraversal: boolean
+  paramPollution: boolean
+}
+
+/**
+ * Configuration for the wire-level rate limiter. `windowSecs` is the size
+ * of the fixed window in seconds; `max` is the request budget per key
+ * (resolved client IP) per window.
+ */
+
+export interface NapiRateLimitConfig {
+  max: number
+  windowSecs: number
+}
+
+/**
+ * NAPI-exposed event bus.
+ * Uses shared Tokio runtime (no per-instance runtime).
+ */
+
+export declare class EventBus {
+  constructor(requestHandlerTimeoutMs?: number | undefined | null)
+  /** Emit an event (async — does NOT block Node.js thread). */
+  emit(name: string, data: string): Promise<string>
+  /**
+   * Subscribe to events matching a pattern. Callback receives event JSON string.
+   * Returns subscription ID.
+   *
+   * NOTE: This is `pub fn` (sync) — napi-rs cannot make `async fn` capture
+   * `JsFunction` because JsFunction isn't Send. The block_on here runs on the
+   * JS thread (no async context above), so it doesn't deadlock the runtime.
+   */
+  subscribe(pattern: string, callback: (eventJson: string) => void): number
+  /** Unsubscribe by subscription ID. */
+  unsubscribe(subId: number): Promise<void>
+  /** Register a request handler. */
+  onRequest(
+    name: string,
+    callback: (eventJson: string, reply: (response: string) => void) => void,
+  ): void
+  /** Send a request and get a response (async with timeout). */
+  request(name: string, data: string, timeoutMs?: number | undefined | null): Promise<string>
+  /** Check if a pattern matches an event name (wildcard matching via Rust). */
+  matchesWildcard(pattern: string, eventName: string): boolean
+  /** Get subscription count. */
+  subscriptionCount(): Promise<number>
+}
+
+/** NAPI-exposed Hyper HTTP server. */
+
+export declare class HyperServer {
+  /**
+   * `host` is the bind address: an IPv4 literal (`0.0.0.0` to accept from
+   * every interface) or the `localhost` alias. Omitted → loopback only,
+   * the safe default for a dev machine.
+   */
+  constructor(port?: number | undefined | null, host?: string | undefined | null)
+  /** Register the request handler. Callback receives JSON request string, must return JSON response string. */
+  onRequest(callback: (request: string) => Promise<string> | string): void
+  /**
+   * Configure the trusted-proxy CIDR list used by `request.ip` resolution.
+   * Must be called BEFORE `listen()`. Empty list = legacy permissive mode
+   * (any peer can populate `X-Forwarded-For`).
+   */
+  configureTrustedProxies(cidrs: Array<string>): void
+  /**
+   * Install (or replace) the wire-level rate limiter. Pass `None` to
+   * disable. Must be called BEFORE `listen()`.
+   */
+  configureRateLimit(config?: NapiRateLimitConfig | undefined | null): void
+  /**
+   * Configure the wire-level security shield. Must be called BEFORE
+   * `listen()` — the configuration is captured into the security filter
+   * when the server starts. Calling after `listen()` has no effect.
+   */
+  configureShield(config: NapiShieldConfig): void
+  /** Start the HTTP server. */
+  listen(): Promise<void>
+  /** Get the actual bound port. */
+  port(): Promise<number>
+  /**
+   * Shut down the server and release the handles that keep the host's event
+   * loop alive.
+   *
+   * `listen()` registers the JS callback as a `ThreadsafeFunction` (which
+   * holds a libuv ref so `ream start` stays alive). Three `Arc` clones of the
+   * request handler capture it: this struct's `self.handler`, the inner
+   * `ReamServer.handler`, and the accept-loop task's clone. ALL three must
+   * drop for napi-rs to release the tsfn on `Drop` (refcount → 0). The old
+   * `close()` only signalled shutdown, leaving every clone alive — so an
+   * in-process host (test harness) leaked the handle and never drained.
+   */
+  close(): Promise<void>
+  /**
+   * Reserve a slot in the stream registry. Returns `false` if the id
+   * already exists (caller picked a colliding UUID). Always returns
+   * before `listen()` need have run.
+   */
+  registerStream(streamId: string): Promise<boolean>
+  /**
+   * Push a chunk onto a registered stream. Returns `false` when the
+   * stream has already finished (receiver dropped — client gone or
+   * `closeStream` called) so the caller can bail out of its push
+   * loop. Backpressure is handled silently: a full buffer drops the
+   * frame rather than awaiting — SSE is fire-and-forget by design.
+   */
+  writeStream(streamId: string, chunk: string): Promise<boolean>
+  /**
+   * Push a BINARY chunk onto a registered stream, waiting for room.
+   *
+   * The counterpart of [`write_stream`](Self::write_stream) for a body the
+   * client reassembles — a file, an export, an archive. Two differences,
+   * both required there and both wrong for SSE:
+   *
+   * * it takes bytes, not a `String`, so a payload that is not valid UTF-8
+   *   survives the crossing intact;
+   * * it AWAITS when the channel is full instead of dropping the frame, so
+   *   a slow client slows the producer rather than silently receiving a
+   *   truncated file.
+   *
+   * Returns `false` when the receiver is gone (client disconnected or the
+   * stream was closed), so the caller can stop reading its source.
+   */
+  writeStreamBytes(streamId: string, chunk: Uint8Array): Promise<boolean>
+  /**
+  * Close a stream from the server side. The matching response body
+  * finishes cleanly (hyper writes the final chunk + `0
+  
+  ` for
+  * HTTP/1.1 chunked encoding). Idempotent.
+  */
+  closeStream(streamId: string): Promise<boolean>
+  /**
+   * Install a one-shot callback fired the moment the matching stream
+   * receiver is dropped — i.e. the client disconnected or
+   * `closeStream` was called. Used by the JS SDK to drop subscription
+   * bookkeeping when an SSE viewer leaves.
+   *
+   * The callback runs on the libuv loop via the threadsafe-function
+   * machinery, so JS code in the callback uses regular await /
+   * reentrant container calls without crossing-thread surprises.
+   */
+  onStreamDisconnect(streamId: string, callback: (streamId: string) => void): void
+}
+
+/**
+ * Scheduler instance exposed to TypeScript.
+ *
+ * Usage (from TS):
+ * ```ignore
+ * const scheduler = new RustScheduler();
+ * scheduler.register('cleanup', '0 *\/5 * * *', (payload) => { ... });
+ * scheduler.start();
+ * // later
+ * scheduler.stop();
+ * ```
+ */
+
+export declare class RustScheduler {
+  constructor()
+  /**
+   * Register a task. `cronExpr` is a standard 5-field cron expression
+   * evaluated in UTC.
+   *
+   * Throws with `DUPLICATE_TASK` if `name` already exists, or
+   * `INVALID_CRON` if the expression is malformed.
+   */
+  register(
+    name: string,
+    cronExpr: string,
+    callback: (invocation: { taskName: string; scheduledForMs: number }) => void,
+  ): void
+  /** Remove a task. Idempotent — unknown names are not an error. */
+  unregister(name: string): void
+  /** Launch the tick loop on the shared Tokio runtime. Idempotent. */
+  start(): void
+  /** Cancel the tick loop. Safe to call even if not running. */
+  stop(): void
+  /** Return the next fire time in ms epoch, or `null` if the task is unknown. */
+  nextRun(name: string): number | null
+}
+
+/**
+ * Sign a JWT payload with HMAC-SHA256 (Rust-native).
+ * Returns the complete JWT token string.
+ */
+
+export declare function jwtSign(payload: string, secret: string): string
+
+/**
+ * Verify a JWT token and return the decoded payload JSON string.
+ * Validates signature (constant-time), exp, and nbf claims.
+ */
+
+export declare function jwtVerify(token: string, secret: string): string
+
+/**
+ * Hash a password with Argon2id (Rust-native).
+ * Returns the PHC-formatted hash string.
+ */
+
+export declare function argon2Hash(password: string): string
+
+/** Verify a password against an Argon2id hash. */
+
+export declare function argon2Verify(password: string, hash: string): boolean
+
+/**
+ * Hash a password with bcrypt (Rust-native).
+ * `rounds` defaults to 12 when not supplied — matches the previous
+ * warden-engine default and the OWASP-recommended cost floor enforced
+ * by `sigil-engine`.
+ */
+
+export declare function bcryptHash(password: string, rounds?: number | undefined | null): string
+
+/** Verify a password against a bcrypt hash. */
+
+export declare function bcryptVerify(password: string, hash: string): boolean
+
+/** Constant-time string comparison. */
+
+export declare function constantTimeEq(a: string, b: string): boolean
+
+/** HMAC-SHA256 sign. Returns base64url signature. */
+
+export declare function hmacSign(data: string, secret: string): string
+
+/** HMAC-SHA256 verify (constant-time). */
+
+export declare function hmacVerify(data: string, signature: string, secret: string): boolean
+
+/** Generate cryptographically secure random bytes as base64url. */
+
+export declare function randomBytesBase64(len: number): string
+
+/** Generate cryptographically secure random bytes as hex. */
+
+export declare function randomHex(len: number): string
+
+/**
+ * Parse a GraphQL query using the Rust graphql-parser crate.
+ * Returns JSON: { operationType, operationName, fields: [...], errors: [...] }
+ * Invalid queries are rejected here — they never reach the TypeScript resolver layer.
+ */
+
+export declare function graphqlParse(query: string): string
+
+/** Validate a GraphQL query string. Returns JSON array of error strings (empty = valid). */
+
+export declare function graphqlValidate(query: string): string
+
+/**
+ * Extract argument scalar types from a GraphQL SDL schema.
+ * Returns JSON: `{ "Type.field": { "argName": "ScalarType" } }` for argument
+ * coercion in the TypeScript engine.
+ */
+
+export declare function graphqlSchemaArgTypes(sdl: string): string