@riceawa/dsh-lan-gateway 0.3.0

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@riceawa/dsh-lan-gateway",
+  "description": "LAN/internet reverse-proxy gateway for the DeepSeek Harness web GUI: binds 0.0.0.0, forwards to the loopback dsh web server with header rewrite to pass the /api trust fence. LAN sources are password-free; non-LAN sources get a login page + HMAC cookie. Optional TLS with auto-generated self-signed or user-supplied certificates, and a Settings → Plugins card for live adjustment of port, CIDRs, auth, and TLS. Includes an insecure-origin UUID shim client bundle: on gateway-served plain-HTTP origins browsers lack crypto.randomUUID, so the client half patches a getRandomValues-backed randomUUID onto the Crypto prototype, fixing workspace open over LAN without touching DSH source.",
+  "version": "0.3.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./client": {
+      "default": "./lib/client.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src",
+    "skills",
+    "cordis.patch.yml"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "test": "vitest run",
+    "build:client": "tsdown",
+    "prepack": "tsdown"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6 || ^0.1.0",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.1.0",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-client-runtime": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "3.18.1",
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "tsx": "^4.23.12",
+    "typescript": "^5.9.3",
+    "unrun": "^0.3.1",
+    "vitest": "^4.1.1"
+  },
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "lan",
+    "gateway",
+    "reverse-proxy",
+    "uuid",
+    "secure-context",
+    "shim"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rice-awa/dsh-lan-gateway.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rice-awa/dsh-lan-gateway/issues"
+  },
+  "homepage": "https://github.com/rice-awa/dsh-lan-gateway#readme"
+}

package/skills/lan-gateway.md

@@ -0,0 +1,56 @@
+---
+name: lan-gateway
+description: Manage remote (non-LAN) access to the DeepSeek Harness web GUI through the dsh-lan-gateway plugin. Use when the user asks to open the web GUI to the LAN/internet, set or change the remote-access password, rotate the session secret, or check whether remote access is currently enabled and what it is listening on.
+whenToUse: The user wants the web GUI reachable from their LAN or the wider internet, wants to enable/disable that, set the login password for remote visitors, rotate the session cookie secret, or learn the current gateway status (port, target, password state, trusted CIDRs).
+user-invocable: true
+---
+
+# dsh-lan-gateway
+
+The `dsh-lan-gateway` plugin lets the DeepSeek Harness web GUI be reached from the
+LAN and the wider internet. dsh itself binds only to loopback (the web CLI
+hard-refuses `0.0.0.0`), so this plugin runs its own reverse-proxy gateway on
+`0.0.0.0` that forwards to the loopback web server while rewriting Host/Origin so
+the `/api` trust fence still passes.
+
+## Access tiers
+
+- **Loopback** (`127.0.0.1`, `::1`) — no password.
+- **LAN** (RFC1918 `10/8`, `172.16/12`, `192.168/16`, link-local `169.254/16`, `fe80::/10`)
+  — no password.
+- **Anything else** (the public internet, CGNAT, Tailscale) — must sign in at the
+  login page and receive the session cookie.
+
+You can extend the trusted LAN ranges by editing the plugin's `lanCidrs` config.
+
+## Drive it through the `lan_gateway` tool
+
+Do not edit state files by hand — use the `lan_gateway` tool. The gateway refuses
+to listen until a password is set (unless `authRequired` is explicitly false).
+
+- `lan_gateway` with `command: "status"` — is it listening, on which port, toward
+  which dsh port, password set?, trusted CIDRs, cookie lifetime.
+- `lan_gateway` with `command: "set-password"` and `password: "<new pass>"`
+  (min 8 chars) — set the remote-access password. Pass an empty password to clear.
+- `lan_gateway` with `command: "enable"` — start listening on the gateway port.
+- `lan_gateway` with `command: "disable"` — stop listening (dsh itself stays up).
+- `lan_gateway` with `command: "rotate-secret"` — invalidate every issued login
+  cookie (users must sign in again).
+
+## After enabling
+
+Tell the user the gateway URL they can share:
+
+- On the LAN: `http://<lan-ip>:<gatewayPort>/` (default port `3081`).
+- From outside: the machine's public address or a Tailscale IP on port
+  `3081` — that path requires the password.
+
+## Troubleshooting
+
+- Gateway won't start: set a password first (`lan_gateway set-password`), check
+  the port is free, confirm `ctx.webServer.port` (default dsh web port `3080`)
+  is where dsh is actually listening.
+- Remote visitors see a redirect loop or 403: check the login cookie
+  (`dsh_gw_auth`) and that their source is classified as `internet`. A `403` on
+  `/api` from a browser is the gateway's own origin/CSRF fence — a real page
+  load carries the right Origin; a hand-crafted cross-site request does not.

package/src/auth.ts

@@ -0,0 +1,182 @@
+/**
+ * Authentication primitives for the LAN gateway: source-IP classification
+ * (loopback / lan / internet), HMAC-signed session cookies, and an in-memory
+ * per-source login rate limiter. Pure functions where possible so the tests
+ * can exercise them without a live server. No runtime dependencies beyond
+ * node:crypto.
+ *
+ * @module @riceawa/dsh-lan-gateway/auth
+ */
+
+import {
+  createHmac,
+  timingSafeEqual,
+} from 'node:crypto'
+
+/** The three trust tiers a request source can fall into. */
+export type SourceClass = 'loopback' | 'lan' | 'internet'
+
+/** One CIDR range: an IPv4 address and its prefix length. */
+export interface Cidr {
+  addr: number
+  prefix: number
+}
+
+const DEFAULT_LAN_CIDRS: readonly string[] = [
+  '10.0.0.0/8',
+  '172.16.0.0/12',
+  '192.168.0.0/16',
+  '169.254.0.0/16', // link-local
+]
+
+/** Default LAN CIDRs: RFC1918 + link-local, IPv4. */
+export const DEFAULT_LAN_CIDR_STRINGS: readonly string[] = [...DEFAULT_LAN_CIDRS]
+
+/** Parse a dotted-quad IPv4 string to its 32-bit integer, or undefined. */
+export function parseIpv4(text: string): number | undefined {
+  const parts = text.split('.')
+  if (parts.length !== 4) return undefined
+  let out = 0
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return undefined
+    const byte = Number(part)
+    if (byte > 255) return undefined
+    out = (out << 8) | byte
+  }
+  return out >>> 0
+}
+
+/** Parse `a.b.c.d/len` into a {@link Cidr}, or undefined on malformed input. */
+export function parseCidr(text: string): Cidr | undefined {
+  const slash = text.indexOf('/')
+  const addrText = slash === -1 ? text : text.slice(0, slash)
+  const prefixText = slash === -1 ? '32' : text.slice(slash + 1)
+  const addr = parseIpv4(addrText)
+  if (addr === undefined) return undefined
+  if (!/^\d{1,2}$/.test(prefixText)) return undefined
+  const prefix = Number(prefixText)
+  if (prefix < 0 || prefix > 32) return undefined
+  return { addr, prefix }
+}
+
+/** Whether a 32-bit IPv4 address falls inside one CIDR range. */
+export function inCidr(ip: number, cidr: Cidr): boolean {
+  if (cidr.prefix === 0) return true
+  const mask = cidr.prefix === 32 ? 0xffffffff : (0xffffffff << (32 - cidr.prefix)) >>> 0
+  return (ip & mask) === (cidr.addr & mask)
+}
+
+/** Normalize a raw socket address to a bare IPv4/6 string we classify on. */
+function normalizeAddress(raw: string): string {
+  const value = raw.trim()
+  // IPv4-mapped IPv6: ::ffff:a.b.c.d
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(value)
+  if (mapped !== null) return mapped[1]!
+  return value
+}
+
+/**
+ * Classify a source address string into one of the three trust tiers.
+ * @param remoteAddress - the raw value of `req.socket.remoteAddress`.
+ * @param lanCidrs - CIDR strings treated as trusted LAN space (IPv4).
+ * @returns the classification. IPv4-mapped IPv6 addresses are unwrapped.
+ */
+export function classifySource(
+  remoteAddress: string | undefined,
+  lanCidrs: readonly string[] = DEFAULT_LAN_CIDR_STRINGS,
+): SourceClass {
+  const address = normalizeAddress(remoteAddress ?? '')
+  if (address === '') return 'internet'
+
+  // Loopback: IPv4 127/8, ::1, or mapped 127.x.
+  const ipv4 = parseIpv4(address)
+  if (ipv4 !== undefined) {
+    if (ipv4 >>> 24 === 127) return 'loopback'
+    for (const cidrText of lanCidrs) {
+      const cidr = parseCidr(cidrText)
+      if (cidr !== undefined && inCidr(ipv4, cidr)) return 'lan'
+    }
+    return 'internet'
+  }
+
+  if (address === '::1') return 'loopback'
+  // Link-local IPv6 fe80::/10.
+  if (address.toLowerCase().startsWith('fe80:')) return 'lan'
+  return 'internet'
+}
+
+/** Encode a byte buffer as URL-safe base64 without padding. */
+function base64url(input: Buffer): string {
+  return input.toString('base64url')
+}
+
+/**
+ * Issue a signed session cookie value.
+ * @param secret - the HMAC signing secret (base64 string).
+ * @param expiresMs - epoch millis at which the session expires.
+ * @returns a `payload.signature` string suitable for the cookie value.
+ */
+export function signCookie(secret: string, expiresMs: number): string {
+  const payload = base64url(Buffer.from(JSON.stringify({ exp: expiresMs })))
+  const sig = createHmac('sha256', secret).update(payload).digest('base64url')
+  return `${payload}.${sig}`
+}
+
+/** Whether a cookie value is a valid, unexpired session signed with `secret`. */
+export function verifyCookie(secret: string, value: string | undefined, now: number): boolean {
+  if (value === undefined) return false
+  const dot = value.indexOf('.')
+  if (dot === -1) return false
+  const payload = value.slice(0, dot)
+  const sig = value.slice(dot + 1)
+  const expected = createHmac('sha256', secret).update(payload).digest()
+  let actual: Buffer
+  try {
+    actual = Buffer.from(sig, 'base64url')
+  } catch {
+    return false
+  }
+  if (expected.length !== actual.length) return false
+  if (!timingSafeEqual(expected, actual)) return false
+  try {
+    const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as { exp?: unknown }
+    return typeof decoded.exp === 'number' && decoded.exp > now
+  } catch {
+    return false
+  }
+}
+
+/** A token bucket limiter keyed by source address. */
+export class RateLimiter {
+  private readonly buckets = new Map<string, { tokens: number; resetAt: number }>()
+  constructor(
+    private readonly maxTokens: number,
+    private readonly windowMs: number,
+  ) {}
+
+  /**
+   * Attempt to consume one token for `key`.
+   * @returns true when the attempt is allowed, false when the source is
+   * temporarily rate-limited.
+   */
+  allow(key: string): boolean {
+    const now = Date.now()
+    const bucket = this.buckets.get(key)
+    if (bucket === undefined || bucket.resetAt <= now) {
+      this.buckets.set(key, { tokens: this.maxTokens - 1, resetAt: now + this.windowMs })
+      return true
+    }
+    if (bucket.tokens > 0) {
+      bucket.tokens -= 1
+      return true
+    }
+    return false
+  }
+
+  /** Drop expired buckets to bound memory. */
+  prune(now: number = Date.now()): void {
+    for (const [key, bucket] of this.buckets) {
+      if (bucket.resetAt <= now) this.buckets.delete(key)
+    }
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,89 @@
+/**
+ * @riceawa/dsh-lan-gateway — browser half.
+ *
+ * Two jobs:
+ * 1. Insecure-origin UUID shim: the gateway can serve the GUI over plain HTTP
+ *    on LAN addresses, where browsers lack `crypto.randomUUID()`. This bundle
+ *    installs a getRandomValues-backed `randomUUID` on the Crypto prototype at
+ *    module scope. With TLS enabled the origin is secure and the shim is a
+ *    no-op.
+ * 2. Settings card: registers the LAN gateway card into the official
+ *    Settings → Plugins page (`settings.plugin.item` slot), editing the
+ *    `lan-gateway` settings namespace so port, CIDRs, auth, and TLS are
+ *    adjustable from the GUI.
+ */
+
+/** RFC 4122 v4 UUID from crypto.getRandomValues (available on insecure origins). */
+function uuidFromRandomValues(): string {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16))
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  view.setUint8(6, (view.getUint8(6) & 0x0f) | 0x40)
+  view.setUint8(8, (view.getUint8(8) & 0x3f) | 0x80)
+  const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+/**
+ * Install `randomUUID` on the browser Crypto prototype when the platform
+ * lacks it. Idempotent; re-checks every call.
+ * @returns `true` when the shim was installed by this call.
+ */
+export function installRandomUuidShim(): boolean {
+  const cryptoObj = globalThis.crypto
+  if (cryptoObj === undefined) return false
+  if (typeof cryptoObj.randomUUID === 'function') return false
+  if (typeof cryptoObj.getRandomValues !== 'function') return false
+  try {
+    // Browsers expose crypto.randomUUID through the Crypto prototype; patching
+    // the prototype (not the instance) covers `crypto.randomUUID()` everywhere.
+    const proto = Object.getPrototypeOf(cryptoObj) as { randomUUID?: unknown } | null
+    if (proto !== null && typeof proto.randomUUID !== 'function') {
+      Object.defineProperty(proto, 'randomUUID', {
+        value: uuidFromRandomValues,
+        writable: true,
+        configurable: true,
+      })
+      return true
+    }
+    // Fallback: direct instance property (sandboxed/odd environments).
+    Object.defineProperty(cryptoObj, 'randomUUID', {
+      value: uuidFromRandomValues,
+      writable: true,
+      configurable: true,
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+// Module scope: the shim is live as soon as this bundle is evaluated, before
+// any RPC/session code runs. apply() re-runs it as a belt-and-braces re-check.
+installRandomUuidShim()
+
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import { LanGatewayCard } from './lan-gateway-card.tsx'
+
+export const name = 'dsh-lan-gateway'
+
+/** Only the slots service: the card itself is self-loading (ModLens-style). */
+export const inject = ['slots']
+
+/**
+ * Mount the settings card and the UUID shim.
+ * @param ctx - the browser plugin context.
+ */
+export function apply(ctx: ClientContext): void {
+  installRandomUuidShim()
+
+  // The card rides the official Plugins → Configurable tab. Like ModLens, it
+  // registers with no inject face and fetches its own loopback config route,
+  // so it has no settings/locale/connection service dependencies.
+  ctx.slots.inject('settings.plugin.item', function* () {
+    yield ctx.slots.register({
+      name: 'settings.plugin.item',
+      id: 'lan-gateway',
+      order: 30,
+    }, LanGatewayCard)
+  })
+}