@reddb-io/client 1.0.1

package/src/embedded-rejection.js

@@ -0,0 +1,90 @@
+/**
+ * Embedded-URI rejection for the thin remote-only client.
+ *
+ * The `@reddb-io/client` package ships only the `red_client` binary,
+ * which has no embedded engine. Any URI that asks for an in-memory
+ * or file-backed database must be rejected at parse time with the
+ * same wording the Rust `red_client` binary prints, so users get a
+ * uniform error across language drivers and the CLI.
+ *
+ * Mirrors `is_embedded_uri` in
+ * `crates/reddb-client/src/bin/red_client.rs` (the rejected forms):
+ *
+ *   "red://"          — bare red:// with no host
+ *   "red:"            — degenerate
+ *   "red:///"         — explicit empty path
+ *   "red:///<path>"   — any red:// URL with a leading-slash path
+ *   "red://:memory"   — SQLite-style alias
+ *   "red://:memory:"  — SQLite-style alias
+ *
+ * The legacy `memory://`, `memory:`, and `file://<path>` schemes are
+ * also rejected because they were always shorthand for the embedded
+ * engine.
+ */
+
+import { RedDBError } from './protocol.js'
+
+/** Wording is intentionally identical to the Rust binary stderr message. */
+export const EMBEDDED_REJECTION_MESSAGE =
+  'embedded schemes (memory:// / file://) are not supported.\n'
+  + 'Use the full `red` binary for in-memory or file-backed engines.'
+
+/**
+ * Specialised error raised when an embedded URI is passed to the
+ * thin client. Always carries `code === 'EmbeddedNotSupported'` and
+ * the wording from `EMBEDDED_REJECTION_MESSAGE`, surfacing the same
+ * actionable hint as the underlying Rust binary.
+ */
+export class EmbeddedNotSupported extends RedDBError {
+  constructor(uri) {
+    super('EmbeddedNotSupported', EMBEDDED_REJECTION_MESSAGE, { uri })
+    this.name = 'EmbeddedNotSupported'
+    this.uri = uri
+  }
+}
+
+/**
+ * Return true when `uri` selects the embedded engine.
+ *
+ * @param {string} uri
+ * @returns {boolean}
+ */
+export function isEmbeddedUri(uri) {
+  if (typeof uri !== 'string') return false
+  const trimmed = uri.trim()
+  if (
+    trimmed === 'red://'
+    || trimmed === 'red:'
+    || trimmed === 'red:/'
+    || trimmed === 'red:///'
+    || trimmed === 'red://:memory'
+    || trimmed === 'red://:memory:'
+  ) {
+    return true
+  }
+  // Any `red:///<path>` form is the embedded persistent engine.
+  if (trimmed.startsWith('red:///')) return true
+  // Legacy shorthands that always meant embedded.
+  if (trimmed === 'memory://' || trimmed === 'memory:') return true
+  if (trimmed.startsWith('file://')) return true
+  return false
+}
+
+/**
+ * Throws `EmbeddedNotSupported` if `uri` is an embedded shape.
+ * Otherwise returns the trimmed URI for downstream consumption.
+ *
+ * @param {string} uri
+ * @returns {string}
+ */
+export function rejectEmbeddedUri(uri) {
+  if (typeof uri !== 'string' || uri.length === 0) {
+    throw new TypeError(
+      "connect() requires a URI string (e.g. 'red://localhost:5050' or 'grpc://host:5055')",
+    )
+  }
+  if (isEmbeddedUri(uri)) {
+    throw new EmbeddedNotSupported(uri)
+  }
+  return uri.trim()
+}

package/src/http.js

@@ -0,0 +1,200 @@
+/**
+ * HTTP transport for the JS driver.
+ *
+ * Mirrors the public surface of `RpcClient` (call, close) but talks
+ * straight to the RedDB HTTP server via fetch() — no binary spawn.
+ * Each `RedDB` method is mapped to a REST endpoint; method names
+ * stay identical to the JSON-RPC ones so `RedDB` doesn't need to
+ * know which transport it's using.
+ *
+ * Endpoint mapping (server-side defined in src/server/routing.rs):
+ *
+ *   query / explain     → POST /query, POST /query/explain
+ *   insert              → POST /collections/:name/rows
+ *   bulk_insert         → POST /collections/:name/bulk/rows
+ *   get                 → GET  /collections/:name/{id}      (entity scan + filter)
+ *   delete              → DELETE /collections/:name/{id}
+ *   health              → GET  /health
+ *   version             → GET  /admin/version
+ *   auth.login          → POST /auth/login
+ *   auth.whoami         → GET  /auth/whoami
+ *   auth.create_api_key → POST /auth/api-keys
+ *   auth.revoke_api_key → DELETE /auth/api-keys/:key
+ *   auth.change_password→ POST /auth/change-password
+ *
+ *   cache.get               → GET    /cache/ns/:ns/:key
+ *   cache.put               → PUT    /cache/ns/:ns/:key
+ *   cache.exists            → GET    /cache/ns/:ns/:key/exists
+ *   cache.invalidate        → DELETE /cache/ns/:ns/:key
+ *   cache.invalidate_prefix → DELETE /cache/ns/:ns?prefix=...
+ *   cache.invalidate_tags   → DELETE /cache/ns/:ns/tags  (body: {tags})
+ *   cache.flush_namespace   → POST   /admin/blob_cache/flush_namespace
+ *
+ * Auth: every request after construction carries `Authorization:
+ * Bearer <token>` (when set). `setToken(token)` updates it in
+ * place — used by the login flow that exchanges credentials for
+ * a fresh bearer.
+ */
+
+import { RedDBError } from './protocol.js'
+
+export class HttpRpcClient {
+  /**
+   * @param {object} opts
+   * @param {string} opts.baseUrl   Server origin, e.g. 'https://reddb.example.com:8443'
+   * @param {string} [opts.token]   Bearer token / API key
+   */
+  constructor({ baseUrl, token }) {
+    if (typeof baseUrl !== 'string' || baseUrl.length === 0) {
+      throw new TypeError('HttpRpcClient: baseUrl required')
+    }
+    this.baseUrl = baseUrl.replace(/\/$/, '')
+    this.token = token ?? null
+  }
+
+  setToken(token) {
+    this.token = token
+  }
+
+  async close() {
+    // HTTP is stateless — nothing to close.
+  }
+
+  /**
+   * Generic RPC entry point. Routes the named method to the
+   * corresponding HTTP endpoint and returns the parsed JSON body.
+   */
+  async call(method, params = {}) {
+    const route = ROUTES[method]
+    if (!route) {
+      throw new RedDBError(
+        'UNKNOWN_METHOD',
+        `HTTP transport has no route for method '${method}'`,
+      )
+    }
+    const { url, init } = route(this.baseUrl, params)
+    const response = await fetch(url, this.attachAuth(init))
+    return parseResponse(response)
+  }
+
+  attachAuth(init) {
+    const headers = new Headers(init.headers || {})
+    if (this.token && !headers.has('authorization')) {
+      headers.set('authorization', `Bearer ${this.token}`)
+    }
+    if (init.body && !headers.has('content-type')) {
+      headers.set('content-type', 'application/json')
+    }
+    return { ...init, headers }
+  }
+}
+
+async function parseResponse(response) {
+  const text = await response.text()
+  let body = null
+  if (text) {
+    try {
+      body = JSON.parse(text)
+    } catch {
+      body = { raw: text }
+    }
+  }
+  if (!response.ok) {
+    const code = body?.error_code || `HTTP_${response.status}`
+    const message = body?.error || body?.message || `request failed with status ${response.status}`
+    throw new RedDBError(code, message, body)
+  }
+  // RedDB envelope is `{ ok, result, error? }` for some endpoints
+  // and bare JSON for others. Unwrap the envelope when present.
+  if (body && typeof body === 'object' && 'ok' in body) {
+    if (body.ok === false) {
+      const code = body.error_code || 'RPC_ERROR'
+      throw new RedDBError(code, body.error || 'unknown error', body)
+    }
+    return body.result ?? body
+  }
+  return body
+}
+
+// ---------------------------------------------------------------------------
+// Method → HTTP route mapping
+// ---------------------------------------------------------------------------
+
+const ROUTES = {
+  health: (base) => ({ url: `${base}/health`, init: { method: 'GET' } }),
+  version: (base) => ({ url: `${base}/admin/version`, init: { method: 'GET' } }),
+  query: (base, { sql }) => ({
+    url: `${base}/query`,
+    init: { method: 'POST', body: JSON.stringify({ query: sql }) },
+  }),
+  insert: (base, { collection, payload }) => ({
+    url: `${base}/collections/${encodeURIComponent(collection)}/rows`,
+    init: { method: 'POST', body: JSON.stringify(payload) },
+  }),
+  bulk_insert: (base, { collection, payloads }) => ({
+    url: `${base}/collections/${encodeURIComponent(collection)}/bulk/rows`,
+    init: { method: 'POST', body: JSON.stringify({ rows: payloads }) },
+  }),
+  get: (base, { collection, id }) => ({
+    url: `${base}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`,
+    init: { method: 'GET' },
+  }),
+  delete: (base, { collection, id }) => ({
+    url: `${base}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`,
+    init: { method: 'DELETE' },
+  }),
+  'auth.login': (base, { username, password }) => ({
+    url: `${base}/auth/login`,
+    init: { method: 'POST', body: JSON.stringify({ username, password }) },
+  }),
+  'auth.whoami': (base) => ({
+    url: `${base}/auth/whoami`,
+    init: { method: 'GET' },
+  }),
+  'auth.create_api_key': (base, params = {}) => ({
+    url: `${base}/auth/api-keys`,
+    init: { method: 'POST', body: JSON.stringify(params) },
+  }),
+  'auth.revoke_api_key': (base, { key }) => ({
+    url: `${base}/auth/api-keys/${encodeURIComponent(key)}`,
+    init: { method: 'DELETE' },
+  }),
+  'auth.change_password': (base, { current_password, new_password }) => ({
+    url: `${base}/auth/change-password`,
+    init: {
+      method: 'POST',
+      body: JSON.stringify({
+        current_password,
+        new_password,
+      }),
+    },
+  }),
+  'cache.get': (base, { namespace, key }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
+    init: { method: 'GET' },
+  }),
+  'cache.put': (base, { namespace, key, value, ttl_ms, tags, policy }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
+    init: { method: 'PUT', body: JSON.stringify({ value, ttl_ms, tags, policy }) },
+  }),
+  'cache.exists': (base, { namespace, key }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}/exists`,
+    init: { method: 'GET' },
+  }),
+  'cache.invalidate': (base, { namespace, key }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
+    init: { method: 'DELETE' },
+  }),
+  'cache.invalidate_prefix': (base, { namespace, prefix }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}?prefix=${encodeURIComponent(prefix)}`,
+    init: { method: 'DELETE' },
+  }),
+  'cache.invalidate_tags': (base, { namespace, tags }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/tags`,
+    init: { method: 'DELETE', body: JSON.stringify({ tags }) },
+  }),
+  'cache.flush_namespace': (base, { namespace }) => ({
+    url: `${base}/admin/blob_cache/flush_namespace`,
+    init: { method: 'POST', body: JSON.stringify({ namespace }) },
+  }),
+}

package/src/index.js

@@ -0,0 +1,336 @@
+/**
+ * @reddb-io/client — thin remote-only RedDB driver.
+ *
+ * Public API:
+ *   import { connect } from '@reddb-io/client'
+ *   const db = await connect('red://reddb.example.com:5050')
+ *   const result = await db.query('SELECT * FROM users LIMIT 10')
+ *   await db.close()
+ *
+ * Accepted URIs:
+ *   - 'red://host:port'        — RedWire TCP (default)
+ *   - 'reds://host:port'       — RedWire over TLS
+ *   - 'grpc://host:port'       — gRPC
+ *   - 'grpcs://host:port'      — gRPC over TLS
+ *   - 'http://host:port'       — HTTP JSON-RPC
+ *   - 'https://host:port'      — HTTPS JSON-RPC
+ *
+ * Rejected URIs (use @reddb-io/sdk for these):
+ *   - 'memory://', 'memory:'   — in-memory embedded engine
+ *   - 'file:///abs/path'       — file-backed embedded engine
+ *   - 'red://', 'red:///path'  — same shapes via the unified scheme
+ *   - 'red://:memory[:]'       — SQLite-style embedded alias
+ *
+ * The thin `red_client` binary does not bundle the storage engine —
+ * the package is roughly 10x smaller than `@reddb-io/sdk`. If you
+ * need an embedded engine, install `@reddb-io/sdk` instead.
+ */
+
+import { RedDBError } from './protocol.js'
+import { HttpRpcClient } from './http.js'
+import { connectRedwire } from './redwire.js'
+import { parseUri, deriveLoginUrl } from './url.js'
+import {
+  EmbeddedNotSupported,
+  EMBEDDED_REJECTION_MESSAGE,
+  isEmbeddedUri,
+  rejectEmbeddedUri,
+} from './embedded-rejection.js'
+import { CacheClient } from './cache.js'
+import { KvClient } from './kv.js'
+import { ConfigClient } from './config.js'
+import { VaultClient } from './vault.js'
+
+export { RedDBError, EmbeddedNotSupported, EMBEDDED_REJECTION_MESSAGE, isEmbeddedUri }
+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 remote RedDB instance.
+ *
+ * @param {string} uri Connection URI. See module docstring for accepted schemes.
+ * @param {object} [options]
+ * @param {object} [options.auth] Authentication credentials.
+ * @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.
+ * @param {string} [options.auth.loginUrl] Override URL for the password
+ *   exchange (defaults to deriving `/auth/login` from `uri`).
+ * @param {object} [options.tls] TLS / mTLS options for redwire(s)://.
+ * @returns {Promise<RedDB>}
+ */
+export async function connect(uri, options = {}) {
+  // Reject embedded shapes upfront with the same wording the Rust
+  // binary uses, before the URL parser would map them to kind=embedded.
+  rejectEmbeddedUri(uri)
+
+  const parsed = parseUri(uri)
+
+  // Belt-and-braces: if the parser still produced an embedded kind
+  // (e.g. via a URI shape we forgot to enumerate above), reject it.
+  if (parsed.kind === 'embedded') {
+    throw new EmbeddedNotSupported(uri)
+  }
+
+  const merged = mergeAuthFromUri(parsed, options.auth)
+
+  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 })
+    await client.call('health', {})
+    return new RedDB(client)
+  }
+
+  if (
+    parsed.kind === 'red'
+    || parsed.kind === 'reds'
+    || 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
+    }
+    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)
+  }
+
+  if (parsed.kind === 'pg') {
+    throw new RedDBError(
+      'PG_TRANSPORT_NOT_WIRED',
+      "PostgreSQL wire (proto=pg) requires a node-pg-style client; "
+        + "the JS thin client doesn't bundle one. Use a separate `pg` "
+        + 'package against the same host:port.',
+    )
+  }
+
+  throw new RedDBError(
+    'UNSUPPORTED_KIND',
+    `internal: parsed kind '${parsed.kind}' has no transport`,
+  )
+}
+
+/**
+ * Resolve TLS options for a redwire(s) connection. Source order:
+ *   1. caller-supplied `options.tls` object.
+ *   2. `parsed.kind === 'reds' | 'grpcs'`.
+ *   3. `?tls=true` URL param.
+ *   4. `?ca=`, `?cert=`, `?key=`, `?servername=`, `?rejectUnauthorized=false`
+ *      URL params (path or PEM string).
+ */
+function buildTlsOpts(parsed, callerTls) {
+  if (callerTls && typeof callerTls === 'object') {
+    return callerTls
+  }
+  const params = parsed.params
+  const wantsTls =
+    parsed.kind === 'reds'
+    || 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 via the server's
+ * `POST /auth/login` HTTP endpoint. Same flow used by `connect()` when
+ * the caller passes `auth: { username, password }`.
+ *
+ * @param {string} loginUrl Full URL of the server's auth endpoint.
+ * @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
+}
+
+/**
+ * Connection handle. Methods map 1:1 to JSON-RPC methods on the server.
+ * Identical surface to `@reddb-io/sdk`'s `RedDB`, minus the local-spawn
+ * lifecycle.
+ */
+export class RedDB {
+  /** @param {HttpRpcClient | import('./redwire.js').RedWireClient} 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', {})
+  }
+
+  /** Exchange username + password for a bearer token. */
+  login(username, password) {
+    return this.client.call('auth.login', { username, password })
+  }
+
+  /** Identify the current caller. */
+  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. */
+  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 underlying transport. */
+  close() {
+    return this.client.close()
+  }
+}

package/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/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)
+  }
+}