socketduct 0.1.15

package/scripts/deploy-gateway.js

@@ -0,0 +1,194 @@
+import {spawn} from "node:child_process"
+import {readFile} from "node:fs/promises"
+import {delimiter, dirname, join, resolve} from "node:path"
+import {fileURLToPath, pathToFileURL} from "node:url"
+import {parseEnv} from "node:util"
+
+const IMMUTABLE_IMAGE_PATTERN = /^ghcr\.io\/kaspernj\/socketduct@sha256:[0-9a-f]{64}$/
+const PROJECT_DIRECTORY = dirname(dirname(fileURLToPath(import.meta.url)))
+
+/** @typedef {Record<string, string | undefined>} ProcessEnvironment */
+
+/**
+ * @typedef {object} CommandOptions
+ * @property {boolean} [captureStdout] - Capture stdout instead of inheriting it.
+ * @property {ProcessEnvironment} env - Child process environment.
+ */
+
+/**
+ * @callback CommandRunner
+ * @param {string} command
+ * @param {string[]} args
+ * @param {CommandOptions} options
+ * @returns {Promise<string> | string}
+ */
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {CommandOptions} options
+ * @returns {Promise<string>} Captured stdout, or an empty string.
+ */
+function runCommand(command, args, {captureStdout = false, env}) {
+  return new Promise((resolve, reject) => {
+    let stdout = ""
+    const child = spawn(command, args, {
+      env,
+      stdio: captureStdout ? ["ignore", "pipe", "inherit"] : "inherit"
+    })
+    if (captureStdout) {
+      child.stdout?.setEncoding("utf8")
+      child.stdout?.on("data", (chunk) => { stdout += chunk })
+    }
+    child.once("error", reject)
+    child.once("close", (code, signal) => {
+      if (code === 0) {
+        resolve(stdout)
+        return
+      }
+      const result = signal === null ? `exit code ${code}` : `signal ${signal}`
+      reject(new Error(`${command} failed with ${result}`))
+    })
+  })
+}
+
+/**
+ * @param {string | undefined} image
+ * @returns {string} Validated immutable image reference.
+ */
+export function validateGatewayImage(image) {
+  if (image === undefined || !IMMUTABLE_IMAGE_PATTERN.test(image)) {
+    throw new Error(
+      "SOCKETDUCT_IMAGE must be an immutable GHCR image in the form " +
+      "ghcr.io/kaspernj/socketduct@sha256:<64 lowercase hex characters>"
+    )
+  }
+  return image
+}
+
+/**
+ * @param {string} renderedJson - Rendered Compose JSON held only in memory.
+ * @param {string} image - Validated immutable image reference.
+ * @returns {void}
+ */
+export function validateRenderedGatewayModel(renderedJson, image) {
+  /** @type {unknown} */
+  let model
+  try {
+    model = JSON.parse(renderedJson)
+  } catch {
+    throw new Error("Rendered Compose model is not valid JSON")
+  }
+  if (typeof model !== "object" || model === null || !("services" in model)) {
+    throw new Error("Rendered Compose model does not define socketduct-relay")
+  }
+  const services = /** @type {{services?: unknown}} */ (model).services
+  if (typeof services !== "object" || services === null || !("socketduct-relay" in services)) {
+    throw new Error("Rendered Compose model does not define socketduct-relay")
+  }
+  const serviceMap = /** @type {Record<string, unknown>} */ (services)
+  const relay = serviceMap["socketduct-relay"]
+  if (typeof relay !== "object" || relay === null) {
+    throw new Error("Rendered Compose model has an invalid socketduct-relay service")
+  }
+  const relayConfig = /** @type {Record<string, unknown>} */ (relay)
+  if (Object.hasOwn(relayConfig, "build")) {
+    throw new Error("Rendered socketduct-relay service must not contain a build source")
+  }
+  if (relayConfig.image !== image) {
+    throw new Error("Rendered socketduct-relay image does not exactly match validated SOCKETDUCT_IMAGE")
+  }
+}
+
+/**
+ * @param {ProcessEnvironment} environment - Host environment.
+ * @param {string} image - Validated immutable image reference.
+ * @param {string} composeFile - Fixed production Compose file.
+ * @param {string} envFile - Fixed production interpolation environment file.
+ * @returns {ProcessEnvironment} Environment with deterministic Compose selectors.
+ */
+function composeEnvironment(environment, image, composeFile, envFile) {
+  return {
+    ...environment,
+    COMPOSE_DISABLE_ENV_FILE: "false",
+    COMPOSE_ENV_FILES: envFile,
+    COMPOSE_FILE: composeFile,
+    COMPOSE_IGNORE_ORPHANS: "false",
+    COMPOSE_PATH_SEPARATOR: delimiter,
+    COMPOSE_PROFILES: "",
+    COMPOSE_PROJECT_NAME: "socketduct-gateway",
+    COMPOSE_REMOVE_ORPHANS: "false",
+    SOCKETDUCT_IMAGE: image
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {string | undefined} options.image
+ * @param {boolean} [options.dockerHost]
+ * @param {ProcessEnvironment} [options.environment]
+ * @param {string} [options.projectDirectory]
+ * @param {CommandRunner} [options.run]
+ * @returns {Promise<void>}
+ */
+export async function deployGateway({
+  image,
+  dockerHost = false,
+  environment = process.env,
+  projectDirectory = PROJECT_DIRECTORY,
+  run = runCommand
+}) {
+  const validatedImage = validateGatewayImage(image)
+  const projectPath = resolve(projectDirectory)
+  const composeFile = join(projectPath, "docker-compose.yml")
+  const envFile = join(projectPath, ".env")
+  const env = composeEnvironment(environment, validatedImage, composeFile, envFile)
+  const compose = [
+    "compose",
+    "--file", composeFile,
+    "--env-file", envFile,
+    "--project-directory", projectPath,
+    "--project-name", "socketduct-gateway",
+    ...(dockerHost ? ["--profile", "docker-host"] : [])
+  ]
+  const renderedJson = await run("docker", [...compose, "config", "--format", "json"], {captureStdout: true, env})
+  validateRenderedGatewayModel(renderedJson, validatedImage)
+  await run("docker", [...compose, "pull"], {env})
+  await run("docker", [...compose, "up", "-d", "--wait", "--no-build"], {env})
+}
+
+/**
+ * @returns {Promise<string | undefined>} Configured image reference, if present.
+ */
+async function loadGatewayImage() {
+  if (Object.hasOwn(process.env, "SOCKETDUCT_IMAGE")) return process.env.SOCKETDUCT_IMAGE
+  try {
+    const environment = parseEnv(await readFile(join(PROJECT_DIRECTORY, ".env"), "utf8"))
+    return environment.SOCKETDUCT_IMAGE
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined
+    throw error
+  }
+}
+
+/**
+ * @returns {Promise<void>}
+ */
+async function main() {
+  const arguments_ = process.argv.slice(2)
+  const unsupported = arguments_.filter((argument) => argument !== "--docker-host")
+  if (unsupported.length > 0 || arguments_.filter((argument) => argument === "--docker-host").length > 1) {
+    throw new Error("Usage: npm run gateway:deploy -- [--docker-host]")
+  }
+  await deployGateway({
+    dockerHost: arguments_.includes("--docker-host"),
+    image: await loadGatewayImage()
+  })
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error)
+    process.exitCode = 1
+  })
+}

package/scripts/test.js

@@ -0,0 +1,28 @@
+import {spawnSync} from "node:child_process"
+import {globSync} from "node:fs"
+
+const migrated = ["test/unit/logging/structured-logger.test.js", "test/integration/logging-recovery.test.js"]
+const files = globSync("test/**/*.test.js").sort()
+for (const path of migrated) {
+  if (!files.includes(path)) throw new Error(`Missing migrated test module: ${path}`)
+}
+const legacy = files.filter((path) => !migrated.includes(path))
+if (legacy.length === 0) throw new Error("No legacy test modules discovered")
+const commands = [
+  {runner: process.execPath, args: ["--test", ...legacy]},
+  ...migrated.map((path) => ({runner: "velocious-test", args: [path]}))
+]
+
+if (process.argv.length === 3 && process.argv[2] === "--list") {
+  console.log(JSON.stringify({legacy, migrated, commands}, null, 2))
+} else {
+  if (process.argv.length !== 2) throw new Error("Only --list is supported; use the owning runner for focused tests")
+  for (const command of commands) {
+    const result = spawnSync(command.runner, command.args, {stdio: "inherit"})
+    if (result.error) throw result.error
+    if (result.status !== 0) {
+      process.exitCode = result.status ?? 1
+      break
+    }
+  }
+}

package/src/auth/passwords.js

@@ -0,0 +1,38 @@
+import {randomBytes, scrypt as scryptCallback, timingSafeEqual} from "node:crypto"
+import {promisify} from "node:util"
+
+const scrypt = promisify(scryptCallback)
+const KEY_LENGTH = 64
+
+/**
+ * @param {string} password - password value.
+ * @returns {Promise<string>} - Result value.
+ */
+export async function createPasswordHash(password) {
+  const salt = randomBytes(16).toString("base64url")
+  const key = await scrypt(password, salt, KEY_LENGTH)
+  return `scrypt$${salt}$${Buffer.from(key).toString("base64url")}`
+}
+
+/**
+ * @param {string} password - password value.
+ * @param {string} storedHash - storedHash value.
+ * @returns {Promise<boolean>} - Result value.
+ */
+export async function verifyPassword(password, storedHash) {
+  const parts = storedHash.split("$")
+  if (parts.length !== 3 || parts[0] !== "scrypt") {
+    return false
+  }
+
+  const [, salt, expectedKey] = parts
+  if (!salt || !expectedKey) {
+    return false
+  }
+
+  const actual = await scrypt(password, salt, KEY_LENGTH)
+  const actualBuffer = Buffer.from(actual)
+  const expectedBuffer = Buffer.from(expectedKey, "base64url")
+
+  return actualBuffer.length === expectedBuffer.length && timingSafeEqual(actualBuffer, expectedBuffer)
+}

package/src/auth/static-token-store.js

@@ -0,0 +1,41 @@
+import {createHash} from "node:crypto"
+
+/**
+ * @typedef {object} StaticTokenPrincipal
+ * @property {string} userId - Stable user identifier derived from the username.
+ * @property {string} username - Authenticated username.
+ * @typedef {object} StaticTokenInput
+ * @property {string} username - Username associated with the token.
+ * @property {string} token - Opaque bearer token.
+ */
+
+export class StaticTokenStore {
+  /** @type {Map<string, StaticTokenPrincipal>} */
+  #principalsByToken = new Map()
+
+  /** @param {StaticTokenInput[]} tokens - Static bearer tokens. */
+  constructor(tokens) {
+    for (const token of tokens) {
+      this.#principalsByToken.set(token.token, {
+        userId: createStableUserId(token.username),
+        username: token.username
+      })
+    }
+  }
+
+  /**
+   * @param {string} value - Bearer token value.
+   * @returns {StaticTokenPrincipal | undefined} Authenticated principal.
+   */
+  authenticate(value) {
+    return this.#principalsByToken.get(value)
+  }
+}
+
+/**
+ * @param {string} username - Username to hash.
+ * @returns {string} Stable user identifier.
+ */
+function createStableUserId(username) {
+  return `static:${createHash("sha256").update(username).digest("base64url")}`
+}

package/src/auth/user-store.js

@@ -0,0 +1,139 @@
+import {randomBytes} from "node:crypto"
+
+import {createPasswordHash, verifyPassword} from "./passwords.js"
+
+/**
+ * @typedef {object} User
+ * @property {string} id - id value.
+ * @property {string} username - username value.
+ * @property {string} passwordHash - passwordHash value.
+ * @typedef {object} CreateUserInput
+ * @property {string} username - username value.
+ * @property {string} password - password value.
+ * @typedef {object} LoginInput
+ * @property {string} username - username value.
+ * @property {string} password - password value.
+ * @typedef {object} TokenPrincipal
+ * @property {string} userId - userId value.
+ * @property {string} username - username value.
+ * @typedef {TokenPrincipal & {value: string, expiresAt: number}} AuthToken
+ * @typedef {object} TokenStoreOptions
+ * @property {() => number} [now] - now value.
+ * @property {number} [tokenTtlMs] - tokenTtlMs value.
+ */
+
+export class InMemoryUserStore {
+  /** @type {Map<string, User>} */
+  #usersByUsername = new Map()
+
+  /**
+   * @param {CreateUserInput} input - input value.
+   * @returns {Promise<User>} - Result value.
+   */
+  async createUser(input) {
+    if (this.#usersByUsername.has(input.username)) {
+      throw new Error(`User already exists: ${input.username}`)
+    }
+
+    const user = {
+      id: generateOpaqueToken(),
+      username: input.username,
+      passwordHash: await createPasswordHash(input.password)
+    }
+    this.#usersByUsername.set(input.username, user)
+    return user
+  }
+
+  /**
+   * @param {string} username - username value.
+   * @returns {User | undefined} - Result value.
+   */
+  findByUsername(username) {
+    return this.#usersByUsername.get(username)
+  }
+}
+
+export class TokenStore {
+  /** @type {Map<string, AuthToken>} */
+  #tokens = new Map()
+
+  /** @type {() => number} */
+  #now
+
+  /** @type {number} */
+  #tokenTtlMs
+
+  /** @param {TokenStoreOptions} [options] - Token store options. */
+  constructor(options = {}) {
+    this.#now = options.now ?? Date.now
+    this.#tokenTtlMs = options.tokenTtlMs ?? 60 * 60 * 1000
+  }
+
+  /**
+   * @param {TokenPrincipal} principal - principal value.
+   * @returns {AuthToken} - Result value.
+   */
+  issue(principal) {
+    const token = {
+      ...principal,
+      value: generateOpaqueToken(),
+      expiresAt: this.#now() + this.#tokenTtlMs
+    }
+    this.#tokens.set(token.value, token)
+    return token
+  }
+
+  /**
+   * @param {string} value - value value.
+   * @returns {TokenPrincipal | undefined} - Result value.
+   */
+  authenticate(value) {
+    const token = this.#tokens.get(value)
+    if (!token) {
+      return undefined
+    }
+
+    if (token.expiresAt <= this.#now()) {
+      this.#tokens.delete(value)
+      return undefined
+    }
+
+    return {
+      userId: token.userId,
+      username: token.username
+    }
+  }
+
+  /**
+   * @param {string} value - value value.
+   * @returns {boolean} - Result value.
+   */
+  revoke(value) {
+    return this.#tokens.delete(value)
+  }
+}
+
+/**
+ * @param {InMemoryUserStore} users - users value.
+ * @param {TokenStore} tokens - tokens value.
+ * @param {LoginInput} input - input value.
+ * @returns {Promise<AuthToken>} - Result value.
+ */
+export async function login(users, tokens, input) {
+  const user = users.findByUsername(input.username)
+  if (!user) {
+    throw new Error("Invalid username or password")
+  }
+
+  const passwordValid = await verifyPassword(input.password, user.passwordHash)
+  if (!passwordValid) {
+    throw new Error("Invalid username or password")
+  }
+
+  return tokens.issue({userId: user.id, username: user.username})
+}
+
+/** @returns {string} - Opaque token. */
+function generateOpaqueToken() {
+  return randomBytes(32).toString("base64url")
+}

package/src/client/connect.js

@@ -0,0 +1,76 @@
+import {SessionSpool as SessionSpoolStorage} from "../spool/spool-file.js"
+import {connectSocketduct} from "./socketduct-socket.js"
+
+/**
+ * @typedef {import('./socketduct-socket.js').ConnectSocketductOptions} ConnectSocketductOptions
+ * @typedef {import('./socketduct-socket.js').SocketductSocket} SocketductSocket
+ * @typedef {import('./socketduct-socket.js').SocketductTlsOptions} SocketductTlsOptions
+ * @typedef {{host?: string, port?: number, target?: {host: string, port: number}, sessionName?: string, spoolDirectory?: string, tls?: SocketductTlsOptions, logger?: import('../logging/structured-logger.js').DiagnosticLogger}} SocketductConnectionOptions
+ * @typedef {object} SocketductConnectionFactoryOptions
+ * @property {{host: string, port: number, token: string}} relay - Relay connection options.
+ * @property {string} spoolDirectory - Default spool directory.
+ * @property {{initialDelayMs?: number}} [reconnect] - Reconnect options.
+ * @property {string} [sessionNamePrefix] - Session name prefix for generated sessions.
+ * @property {string} [sessionName] - Default session name.
+ * @property {SocketductTlsOptions} [tls] - TLS client options.
+ * @property {number} [maxBytes] - Maximum total spool bytes per session.
+ * @property {number} [maxAgeMs] - Maximum age of a spool session before operations are rejected.
+ * @property {import('../logging/structured-logger.js').DiagnosticLogger} [logger] - Optional privacy-safe structured diagnostic logger.
+ */
+
+/**
+ * @param {SocketductConnectionFactoryOptions} baseOptions - Shared Socketduct options.
+ * @returns {(options: SocketductConnectionOptions, listener?: () => void) => SocketductSocket} - Socket factory.
+ */
+export function createSocketductConnectionFactory(baseOptions) {
+  let connectionId = 0
+  return (options, listener) => {
+    connectionId += 1
+    const target = options.target ?? normalizeTarget(options)
+    const sessionName = options.sessionName
+      ?? baseOptions.sessionName
+      ?? `${baseOptions.sessionNamePrefix ?? "socketduct"}-${connectionId}`
+
+    /** @type {ConnectSocketductOptions} */
+    const socketductOptions = {
+      relay: baseOptions.relay,
+      sessionName,
+      target,
+      spoolDirectory: options.spoolDirectory ?? baseOptions.spoolDirectory
+    }
+    if (baseOptions.reconnect !== undefined) {
+      socketductOptions.reconnect = baseOptions.reconnect
+    }
+    if (options.tls !== undefined) {
+      socketductOptions.tls = options.tls
+    } else if (baseOptions.tls !== undefined) {
+      socketductOptions.tls = baseOptions.tls
+    }
+    if (baseOptions.maxBytes !== undefined) {
+      socketductOptions.maxBytes = baseOptions.maxBytes
+    }
+    if (baseOptions.maxAgeMs !== undefined) {
+      socketductOptions.maxAgeMs = baseOptions.maxAgeMs
+    }
+    if (options.logger !== undefined) {
+      socketductOptions.logger = options.logger
+    } else if (baseOptions.logger !== undefined) {
+      socketductOptions.logger = baseOptions.logger
+    }
+
+    return connectSocketduct(socketductOptions, listener)
+  }
+}
+
+/**
+ * @param {SocketductConnectionOptions} options - Per-connection options.
+ * @returns {{host: string, port: number}} - Normalized target.
+ */
+function normalizeTarget(options) {
+  if (options.host === undefined || options.port === undefined) {
+    throw new Error("Socketduct connection requires target or host and port")
+  }
+  return {host: options.host, port: options.port}
+}
+
+export {SessionSpoolStorage}