@reddb-io/cli 1.0.1

package/drivers/js/src/index.js

@@ -0,0 +1,432 @@
+/**
+ * RedDB JavaScript driver.
+ *
+ * Public API:
+ *   import { connect } from '@reddb-io/sdk'
+ *   const db = await connect('file:///data.rdb')
+ *   const result = await db.query('SELECT * FROM users LIMIT 10')
+ *   const inserted = await db.insert('users', { name: 'Alice' })
+ *   await db.bulkInsert('users', [{ name: 'Bob' }, { name: 'Carol' }])
+ *   const row = await db.get('users', '42')
+ *   await db.delete('users', '42')
+ *   await db.close()
+ *
+ * Connection URIs:
+ *   - 'memory://'                — ephemeral in-memory database (embedded)
+ *   - 'file:///absolute/path'    — embedded, persisted to disk
+ *   - 'grpc://host:port'         — remote server via gRPC
+ *
+ * Authentication (only meaningful for `grpc://`; embedded modes ignore
+ * auth options because the spawned binary inherits the caller's
+ * filesystem privileges):
+ *
+ *   await connect('grpc://host:5051', {
+ *     auth: { token: 'sk-...' }                     // raw bearer / api key
+ *   })
+ *   await connect('grpc://host:5051', {
+ *     auth: { apiKey: 'ak-...' }                    // alias for token
+ *   })
+ *   await connect('grpc://host:5051', {
+ *     auth: { username: 'admin', password: 'x' }    // login flow — driver
+ *                                                   // calls /auth/login,
+ *                                                   // caches the bearer
+ *   })
+ *
+ * Username/password requires the server to expose the `auth.login`
+ * JSON-RPC method (proxied through the gRPC bridge).
+ */
+
+import { spawnRed } from './spawn.js'
+import { resolveSdkBinary } from './binary.js'
+import { RpcClient, RedDBError } from './protocol.js'
+import { HttpRpcClient } from './http.js'
+import { connectRedwire } from './redwire.js'
+import { parseUri, deriveLoginUrl } from './url.js'
+import { CacheClient } from './cache.js'
+import { KvClient } from './kv.js'
+import { ConfigClient } from './config.js'
+import { VaultClient } from './vault.js'
+
+export { RedDBError }
+export { CacheClient } from './cache.js'
+export { KvClient } from './kv.js'
+export { ConfigClient } from './config.js'
+export { VaultClient } from './vault.js'
+export { parseUri, deriveLoginUrl } from './url.js'
+
+/**
+ * Connect to a RedDB instance.
+ *
+ * @param {string} uri Connection URI. See module docstring for accepted schemes.
+ * @param {object} [options]
+ * @param {string} [options.binary] Override the path to the `red` binary.
+ * @param {object} [options.auth] Authentication credentials. See module docstring.
+ * @param {string} [options.auth.token] Bearer / API-key token.
+ * @param {string} [options.auth.apiKey] Alias for `token`.
+ * @param {string} [options.auth.username] Username for password login.
+ * @param {string} [options.auth.password] Password for password login.
+ * @returns {Promise<RedDB>}
+ */
+export async function connect(uri, options = {}) {
+  const parsed = parseUri(uri)
+  const merged = mergeAuthFromUri(parsed, options.auth)
+
+  // Embedded modes: spawn the binary with stdio JSON-RPC. Auth is
+  // not applicable (caller already has filesystem privileges).
+  if (parsed.kind === 'embedded') {
+    if (merged.token || merged.username) {
+      throw new RedDBError(
+        'AUTH_NOT_APPLICABLE',
+        'auth is only meaningful for remote connections; embedded modes inherit caller privileges.',
+      )
+    }
+    const args = embeddedArgs(parsed)
+    const binary = options.binary ?? resolveSdkBinary()
+    const child = await spawnRed(binary, args)
+    const client = new RpcClient(child)
+    await client.call('version', {})
+    return new RedDB(client)
+  }
+
+  // HTTP / HTTPS: speak directly to the server via fetch().
+  if (parsed.kind === 'http' || parsed.kind === 'https') {
+    const baseUrl = `${parsed.kind}://${parsed.host}:${parsed.port}`
+    let token = merged.token
+    if (!token && merged.username && merged.password) {
+      const loginUrl = merged.loginUrl ?? `${baseUrl}/auth/login`
+      const session = await login(loginUrl, {
+        username: merged.username,
+        password: merged.password,
+      })
+      token = session.token
+    }
+    const client = new HttpRpcClient({ baseUrl, token })
+    // Sanity check before returning the handle.
+    await client.call('health', {})
+    return new RedDB(client)
+  }
+
+  // gRPC / gRPCs / RedWire (default for grpc-shaped URIs):
+  // speak the RedWire binary protocol natively via TCP. No spawn, no
+  // gRPC bridge. Resolves bearer auth from username/password via
+  // HTTP /auth/login first when needed.
+  //
+  // The server multiplexes RedWire on the same port as gRPC and HTTP
+  // via the service router's 0xFE detector, so pure grpc:// URLs
+  // still flow through RedWire because it wins on perf and parity.
+  if (parsed.kind === 'grpc' || parsed.kind === 'grpcs') {
+    let token = merged.token
+    if (!token && merged.username && merged.password) {
+      const loginUrl = merged.loginUrl ?? deriveLoginUrl(parsed)
+      const session = await login(loginUrl, {
+        username: merged.username,
+        password: merged.password,
+      })
+      token = session.token
+    }
+
+    // Honour `proto=spawn-grpc` as an escape hatch for callers that
+    // explicitly want the legacy stdio→gRPC bridge. Default is the
+    // RedWire transport.
+    const protoOverride = parsed.params?.get?.('proto') ?? ''
+    if (protoOverride === 'spawn-grpc') {
+      const args = grpcArgs(parsed, token)
+      const binary = options.binary ?? resolveSdkBinary()
+      const child = await spawnRed(binary, args)
+      const legacy = new RpcClient(child)
+      await legacy.call('version', {})
+      return new RedDB(legacy)
+    }
+
+    const auth = token ? { kind: 'bearer', token } : { kind: 'anonymous' }
+    const tls = buildTlsOpts(parsed, options.tls)
+    const client = await connectRedwire({
+      host: parsed.host,
+      port: parsed.port,
+      auth,
+      ...(tls ? { tls } : {}),
+    })
+    return new RedDB(client)
+  }
+
+  // Postgres wire: not yet wired in the driver. Document the gap
+  // so users get a clear actionable error instead of a silent
+  // unsupported transport.
+  if (parsed.kind === 'pg') {
+    throw new RedDBError(
+      'PG_TRANSPORT_NOT_WIRED',
+      "PostgreSQL wire (proto=pg) requires a node-pg-style client; "
+        + "the JS driver doesn't bundle one yet. Use a separate `pg` package "
+        + 'against the same host:port for now, or open an issue if you want it built in.',
+    )
+  }
+
+  throw new RedDBError(
+    'UNSUPPORTED_KIND',
+    `internal: parsed kind '${parsed.kind}' has no transport`,
+  )
+}
+
+function embeddedArgs(parsed) {
+  if (parsed.path) return ['rpc', '--stdio', '--path', parsed.path]
+  return ['rpc', '--stdio']
+}
+
+function grpcArgs(parsed, token) {
+  const scheme = parsed.kind === 'grpcs' ? 'grpcs' : 'grpc'
+  const url = `${scheme}://${parsed.host}:${parsed.port}${parsed.path ?? ''}`
+  const args = ['rpc', '--stdio', '--connect', url]
+  if (token) args.push('--token', token)
+  return args
+}
+
+/**
+ * Merge `options.auth` (legacy `{ token, apiKey, username, password }`
+ * shape) with credentials lifted from the URI itself. Explicit
+ * `options.auth` always wins to keep behaviour predictable.
+ */
+/**
+ * Resolve TLS options for a redwire(s) connection.
+ *
+ * Sources, in priority order:
+ *   - `options.tls` from the caller (object form), wins everything
+ *   - `parsed.kind === 'grpcs'` (i.e. `redwires://` or `?proto=grpcs`)
+ *   - `?tls=true` in the URL params
+ *   - `?ca=`, `?cert=`, `?key=`, `?servername=`,
+ *     `?rejectUnauthorized=false` URL params (paths or PEM strings)
+ *
+ * Returns `null` when TLS isn't requested.
+ */
+function buildTlsOpts(parsed, callerTls) {
+  if (callerTls && typeof callerTls === 'object') {
+    return callerTls
+  }
+  const params = parsed.params
+  const wantsTls =
+    parsed.kind === 'grpcs'
+    || params?.get?.('tls') === 'true'
+    || params?.get?.('tls') === '1'
+  if (!wantsTls) return null
+  return {
+    ca: params?.get?.('ca') ?? undefined,
+    cert: params?.get?.('cert') ?? undefined,
+    key: params?.get?.('key') ?? undefined,
+    servername: params?.get?.('servername') ?? undefined,
+    rejectUnauthorized:
+      params?.get?.('rejectUnauthorized') === 'false' ? false : true,
+  }
+}
+
+function mergeAuthFromUri(parsed, optionAuth) {
+  const out = {
+    token: parsed.token ?? parsed.apiKey ?? null,
+    username: parsed.username ?? null,
+    password: parsed.password ?? null,
+    loginUrl: parsed.loginUrl ?? null,
+  }
+  if (optionAuth == null) return out
+  if (typeof optionAuth !== 'object') {
+    throw new TypeError('options.auth must be an object')
+  }
+  if (optionAuth.token != null) {
+    if (typeof optionAuth.token !== 'string' || optionAuth.token.length === 0) {
+      throw new TypeError('options.auth.token must be a non-empty string')
+    }
+    out.token = optionAuth.token
+  }
+  if (optionAuth.apiKey != null) {
+    if (typeof optionAuth.apiKey !== 'string' || optionAuth.apiKey.length === 0) {
+      throw new TypeError('options.auth.apiKey must be a non-empty string')
+    }
+    out.token = optionAuth.apiKey
+  }
+  if (optionAuth.username != null) {
+    if (typeof optionAuth.username !== 'string' || optionAuth.username.length === 0) {
+      throw new TypeError('options.auth.username must be a non-empty string')
+    }
+    out.username = optionAuth.username
+  }
+  if (optionAuth.password != null) {
+    if (typeof optionAuth.password !== 'string' || optionAuth.password.length === 0) {
+      throw new TypeError('options.auth.password must be a non-empty string')
+    }
+    out.password = optionAuth.password
+  }
+  if (optionAuth.loginUrl != null) {
+    out.loginUrl = optionAuth.loginUrl
+  }
+  return out
+}
+
+/**
+ * Exchange username + password for a bearer token by hitting the
+ * server's `POST /auth/login` HTTP endpoint, then return that token
+ * for use with subsequent `connect({ auth: { token } })` calls.
+ *
+ * Why a separate function: the gRPC surface does not currently
+ * expose `auth.login` as an RPC, so the driver can't piggyback on
+ * the binary spawn for password auth. The HTTP listener does
+ * expose it, and is the canonical login site (the same endpoint
+ * the dashboard uses).
+ *
+ * @param {string} loginUrl Full URL of the server's auth endpoint
+ *                          (e.g. `https://reddb.example.com/auth/login`).
+ * @param {{ username: string, password: string }} credentials
+ * @returns {Promise<{ token: string, username: string, role: string, expires_at: number }>}
+ */
+export async function login(loginUrl, { username, password }) {
+  if (typeof loginUrl !== 'string' || !loginUrl.startsWith('http')) {
+    throw new TypeError("login() requires an http(s):// URL pointing at /auth/login")
+  }
+  if (typeof username !== 'string' || username.length === 0) {
+    throw new TypeError('login() requires a non-empty username')
+  }
+  if (typeof password !== 'string' || password.length === 0) {
+    throw new TypeError('login() requires a non-empty password')
+  }
+  const response = await fetch(loginUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ username, password }),
+  })
+  const body = await response.json().catch(() => ({}))
+  if (!response.ok || body.ok === false) {
+    const code = body.error_code || `HTTP_${response.status}`
+    const message = body.error || `auth/login returned ${response.status}`
+    throw new RedDBError(code, message, body)
+  }
+  if (typeof body.token !== 'string') {
+    throw new RedDBError(
+      'AUTH_LOGIN_BAD_RESPONSE',
+      'auth/login response missing string token',
+      body,
+    )
+  }
+  return body
+}
+
+/**
+ * Backwards-compatible shim: translate a URI into argv for
+ * `red rpc --stdio`. New code should call `parseUri` directly and
+ * route via `connect`. Kept exported for tests that pre-date the
+ * `red://` parser.
+ */
+export function uriToArgs(uri, auth = null) {
+  const parsed = parseUri(uri)
+  if (parsed.kind === 'embedded') return embeddedArgs(parsed)
+  if (parsed.kind === 'grpc' || parsed.kind === 'grpcs') {
+    const token = auth?.kind === 'token' ? auth.token : (parsed.token ?? parsed.apiKey ?? null)
+    return grpcArgs(parsed, token)
+  }
+  throw new RedDBError(
+    'UNSUPPORTED_SCHEME',
+    `uriToArgs() supports embedded + grpc kinds; for '${parsed.kind}' use connect() directly.`,
+  )
+}
+
+
+/**
+ * Connection handle. Methods map 1:1 to JSON-RPC methods on the binary.
+ */
+export class RedDB {
+  /** @param {RpcClient} client */
+  constructor(client) {
+    this.client = client
+    this.cache = new CacheClient(client)
+    const defaultKv = new KvClient(client)
+    this.kv = Object.assign((collection = 'kv_default') => new KvClient(client, collection), {
+      put: defaultKv.put.bind(defaultKv),
+      invalidateTags: defaultKv.invalidateTags.bind(defaultKv),
+      watch: defaultKv.watch.bind(defaultKv),
+      watchPrefix: defaultKv.watchPrefix.bind(defaultKv),
+    })
+    this.config = (collection = 'red.config') => new ConfigClient(client, collection)
+    this.vault = (collection = 'red.vault') => new VaultClient(client, collection)
+  }
+
+  /** Execute a SQL query. Returns `{ statement, affected, columns, rows }`. */
+  query(sql) {
+    return this.client.call('query', { sql })
+  }
+
+  /** Insert one row. Returns `{ affected, id? }`. */
+  insert(collection, payload) {
+    return this.client.call('insert', { collection, payload })
+  }
+
+  /** Insert many rows in one call. Returns `{ affected }`. */
+  bulkInsert(collection, payloads) {
+    return this.client.call('bulk_insert', { collection, payloads })
+  }
+
+  /** Get an entity by id. Returns `{ entity }` (entity is `null` if not found). */
+  get(collection, id) {
+    return this.client.call('get', { collection, id: String(id) })
+  }
+
+  /** Delete an entity by id. Returns `{ affected }`. */
+  delete(collection, id) {
+    return this.client.call('delete', { collection, id: String(id) })
+  }
+
+  /** Probe the server. Returns `{ ok: true, version }`. */
+  health() {
+    return this.client.call('health', {})
+  }
+
+  /** Server version + protocol version. */
+  version() {
+    return this.client.call('version', {})
+  }
+
+  // ---------------------------------------------------------------
+  // Auth surface — these are no-ops in embedded mode because the
+  // bridge layer doesn't expose `auth.*` JSON-RPC methods locally.
+  // They forward to the server when the connection is grpc://.
+  // ---------------------------------------------------------------
+
+  /**
+   * Exchange username + password for a bearer token. Returns
+   * `{ token, username, role, expires_at }`. Server-side this
+   * routes to `POST /auth/login`.
+   *
+   * Prefer the `auth: { username, password }` form on `connect()`
+   * — it does the same exchange + caches the token transparently.
+   */
+  login(username, password) {
+    return this.client.call('auth.login', { username, password })
+  }
+
+  /** Identify the current caller. Returns `{ username, role }`. */
+  whoami() {
+    return this.client.call('auth.whoami', {})
+  }
+
+  /** Change the current caller's password. */
+  changePassword(currentPassword, newPassword) {
+    return this.client.call('auth.change_password', {
+      current_password: currentPassword,
+      new_password: newPassword,
+    })
+  }
+
+  /**
+   * Mint a long-lived API key for the caller (or a sub-user, when
+   * the caller has `Admin` role). Returns `{ key, role, created_at }`.
+   * Pass the returned `key` back via `auth: { apiKey: key }` on
+   * future `connect()` calls.
+   */
+  createApiKey({ username, role } = {}) {
+    return this.client.call('auth.create_api_key', { username, role })
+  }
+
+  /** Revoke an API key by its public id. */
+  revokeApiKey(key) {
+    return this.client.call('auth.revoke_api_key', { key })
+  }
+
+  /** Close the connection and wait for the binary to exit. */
+  close() {
+    return this.client.close()
+  }
+}

package/drivers/js/src/internal/asset-fetcher/asset-name.js

@@ -0,0 +1,37 @@
+/**
+ * Resolve the GitHub release asset filename for a given Node
+ * `process.platform` / `process.arch` pair and binary base name.
+ *
+ * Mapping is the existing scheme from `drivers/js/postinstall.js`:
+ *   linux  + x64       → <bin>-linux-x86_64
+ *   linux  + arm64     → <bin>-linux-aarch64
+ *   linux  + arm/armv7l→ <bin>-linux-armv7
+ *   darwin + x64       → <bin>-macos-x86_64
+ *   darwin + arm64     → <bin>-macos-aarch64
+ *   win32  + x64       → <bin>-windows-x86_64.exe
+ *
+ * Throws `UnsupportedPlatformError` for any other combination.
+ */
+
+export class UnsupportedPlatformError extends Error {
+  constructor(platform, arch) {
+    super(`unsupported platform/arch combination: ${platform}/${arch}`)
+    this.name = 'UnsupportedPlatformError'
+    this.code = 'UNSUPPORTED_PLATFORM'
+    this.platform = platform
+    this.arch = arch
+  }
+}
+
+export function composeAssetName({ platform, arch, binName }) {
+  if (typeof binName !== 'string' || binName === '') {
+    throw new TypeError('composeAssetName: `binName` must be a non-empty string')
+  }
+  if (platform === 'linux' && arch === 'x64') return `${binName}-linux-x86_64`
+  if (platform === 'linux' && arch === 'arm64') return `${binName}-linux-aarch64`
+  if (platform === 'linux' && (arch === 'arm' || arch === 'armv7l')) return `${binName}-linux-armv7`
+  if (platform === 'darwin' && arch === 'x64') return `${binName}-macos-x86_64`
+  if (platform === 'darwin' && arch === 'arm64') return `${binName}-macos-aarch64`
+  if (platform === 'win32' && arch === 'x64') return `${binName}-windows-x86_64.exe`
+  throw new UnsupportedPlatformError(platform, arch)
+}

package/drivers/js/src/internal/asset-fetcher/checksum.js

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto'
+
+export class ChecksumMismatchError extends Error {
+  constructor(expected, actual) {
+    super(`checksum mismatch: expected sha256=${expected}, got sha256=${actual}`)
+    this.name = 'ChecksumMismatchError'
+    this.code = 'CHECKSUM_MISMATCH'
+    this.expected = expected
+    this.actual = actual
+  }
+}
+
+export function sha256Hex(buf) {
+  return createHash('sha256').update(buf).digest('hex')
+}
+
+export function verifySha256(buf, expected) {
+  const expectedNorm = String(expected).trim().toLowerCase()
+  const actual = sha256Hex(buf)
+  if (actual !== expectedNorm) {
+    throw new ChecksumMismatchError(expectedNorm, actual)
+  }
+}

package/drivers/js/src/internal/asset-fetcher/download.js

@@ -0,0 +1,89 @@
+import { request as httpsRequest } from 'node:https'
+import { request as httpRequest } from 'node:http'
+
+const MAX_REDIRECTS = 5
+
+export class AssetNotFoundError extends Error {
+  constructor(url) {
+    super(`asset not found (HTTP 404) at ${url}`)
+    this.name = 'AssetNotFoundError'
+    this.code = 'ASSET_NOT_FOUND'
+    this.url = url
+  }
+}
+
+export class HttpError extends Error {
+  constructor(status, url) {
+    super(`HTTP ${status} fetching ${url}`)
+    this.name = 'HttpError'
+    this.code = 'HTTP_ERROR'
+    this.status = status
+    this.url = url
+  }
+}
+
+export class TooManyRedirectsError extends Error {
+  constructor(url) {
+    super(`too many redirects (>${MAX_REDIRECTS}) starting at ${url}`)
+    this.name = 'TooManyRedirectsError'
+    this.code = 'TOO_MANY_REDIRECTS'
+    this.url = url
+  }
+}
+
+function pickRequest(url) {
+  return url.startsWith('http://') ? httpRequest : httpsRequest
+}
+
+function resolveLocation(currentUrl, location) {
+  if (/^https?:\/\//i.test(location)) return location
+  return new URL(location, currentUrl).toString()
+}
+
+export function downloadFollowingRedirects(url, { userAgent, originalUrl } = {}, depth = 0) {
+  const startUrl = originalUrl || url
+  if (depth > MAX_REDIRECTS) {
+    return Promise.reject(new TooManyRedirectsError(startUrl))
+  }
+  const request = pickRequest(url)
+  return new Promise((resolve, reject) => {
+    const req = request(
+      url,
+      {
+        method: 'GET',
+        headers: {
+          'User-Agent': userAgent || 'reddb-internal-asset-fetcher',
+          Accept: 'application/octet-stream',
+        },
+      },
+      (res) => {
+        const status = res.statusCode || 0
+        if (status >= 300 && status < 400 && res.headers.location) {
+          res.resume()
+          const next = resolveLocation(url, res.headers.location)
+          downloadFollowingRedirects(next, { userAgent, originalUrl: startUrl }, depth + 1).then(
+            resolve,
+            reject,
+          )
+          return
+        }
+        if (status === 404) {
+          res.resume()
+          reject(new AssetNotFoundError(startUrl))
+          return
+        }
+        if (status < 200 || status >= 300) {
+          res.resume()
+          reject(new HttpError(status, url))
+          return
+        }
+        const chunks = []
+        res.on('data', (chunk) => chunks.push(chunk))
+        res.on('end', () => resolve(Buffer.concat(chunks)))
+        res.on('error', reject)
+      },
+    )
+    req.on('error', reject)
+    req.end()
+  })
+}

package/drivers/js/src/internal/asset-fetcher/index.js

@@ -0,0 +1,52 @@
+/**
+ * @reddb-io/internal-asset-fetcher — fetch a `red`/`red_client` binary
+ * from a GitHub release.
+ *
+ * Public surface: one function.
+ *
+ *   fetchReleaseAsset({ repo, tag, platform, arch, binName, sha256? }) → Buffer
+ *
+ * Steps:
+ *   1. Map (platform, arch, binName) → asset filename.
+ *   2. Compose the GitHub download URL: `https://github.com/<repo>/releases/download/<tag>/<asset>`.
+ *   3. Follow up to 5 redirects, returning the final body as a Buffer.
+ *   4. If `sha256` was supplied, verify before returning.
+ *
+ * Errors carry distinct `.code` values so callers can differentiate:
+ *   - UNSUPPORTED_PLATFORM   — no asset for this platform/arch
+ *   - ASSET_NOT_FOUND        — HTTP 404 (release/tag/asset name wrong)
+ *   - CHECKSUM_MISMATCH      — body downloaded but sha256 mismatched
+ *   - HTTP_ERROR             — any other non-2xx status
+ *   - TOO_MANY_REDIRECTS     — redirect chain longer than 5 hops
+ *
+ * Internal modules (`./asset-name.js`, `./download.js`, `./checksum.js`)
+ * are not part of the public contract — only `fetchReleaseAsset` is.
+ * They are imported directly in tests for focused coverage.
+ */
+
+import { composeAssetName } from './asset-name.js'
+import { downloadFollowingRedirects } from './download.js'
+import { verifySha256 } from './checksum.js'
+
+export async function fetchReleaseAsset({ repo, tag, platform, arch, binName, sha256 } = {}) {
+  if (typeof repo !== 'string' || repo === '') {
+    throw new TypeError('fetchReleaseAsset: `repo` must be a non-empty string (e.g. "reddb-io/reddb")')
+  }
+  if (typeof tag !== 'string' || tag === '') {
+    throw new TypeError('fetchReleaseAsset: `tag` must be a non-empty string (e.g. "v0.2.9")')
+  }
+  if (typeof platform !== 'string' || platform === '') {
+    throw new TypeError('fetchReleaseAsset: `platform` must be a non-empty string')
+  }
+  if (typeof arch !== 'string' || arch === '') {
+    throw new TypeError('fetchReleaseAsset: `arch` must be a non-empty string')
+  }
+
+  const assetName = composeAssetName({ platform, arch, binName })
+  const url = `https://github.com/${repo}/releases/download/${tag}/${assetName}`
+  const body = await downloadFollowingRedirects(url)
+  if (sha256) {
+    verifySha256(body, sha256)
+  }
+  return body
+}

package/drivers/js/src/internal/bin-resolver/index.js

@@ -0,0 +1,57 @@
+/**
+ * @reddb-io/internal-bin-resolver — runtime lookup for a pinned binary.
+ *
+ * Precedence:
+ *   1. `process.env[envVar]` if set and non-empty → returned verbatim.
+ *      No existence probe: the env var is the user's "I know what I'm
+ *      doing" override.
+ *   2. `<packageRoot>/bin/<name>` if it exists.
+ *   3. Otherwise throw an actionable error naming the env var, the
+ *      expected local path, and a one-line `pnpm install` hint.
+ *
+ * `PATH` is deliberately never consulted. SDK/client wire formats are
+ * version-coupled to the binary; silent fallback to a stale `PATH`
+ * binary fails as misframed RPC, not "command not found". See ADR 0006.
+ */
+
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * @param {{ name: string, packageRoot: string, envVar: string }} opts
+ * @returns {string} absolute path to the binary
+ * @throws {Error} when neither env override nor local binary is usable
+ */
+export function resolveBin(opts) {
+  if (!opts || typeof opts !== 'object') {
+    throw new TypeError('resolveBin: options object required')
+  }
+  const { name, packageRoot, envVar } = opts
+  if (typeof name !== 'string' || name === '') {
+    throw new TypeError('resolveBin: `name` must be a non-empty string')
+  }
+  if (typeof packageRoot !== 'string' || packageRoot === '') {
+    throw new TypeError('resolveBin: `packageRoot` must be a non-empty string')
+  }
+  if (typeof envVar !== 'string' || envVar === '') {
+    throw new TypeError('resolveBin: `envVar` must be a non-empty string')
+  }
+
+  const override = process.env?.[envVar]
+  if (typeof override === 'string' && override !== '') {
+    return override
+  }
+
+  const local = join(packageRoot, 'bin', name)
+  if (existsSync(local)) {
+    return local
+  }
+
+  throw new Error(
+    `reddb: binary "${name}" not found.\n` +
+      `  expected at: ${local}\n` +
+      `  override:    set ${envVar}=/path/to/${name}\n` +
+      `  fix:         re-run \`pnpm install\` (the postinstall script downloads it),\n` +
+      `               or check the postinstall log for a download error.`,
+  )
+}