@fabiofiorita/porcelain 0.57.0

package/README.md

@@ -0,0 +1,118 @@
+# @fabiofiorita/porcelain (0.57.0)
+
+Headless **Porcelain** backend — the Electron-free daemon + renderer, packaged for
+plain Node on any machine (Linux mini-PC, cloud VM, laptop). Same credential-gated
+HTTP/WS surface the Mac app and browser clients already talk to.
+
+## Quick start (recommended)
+
+On the remote host (Node ≥ 22, git, and a C toolchain for `node-pty`):
+
+```sh
+npx @fabiofiorita/porcelain@latest serve --lan --cloudflare
+```
+
+That:
+
+1. Fetches the **latest** published package (use `@latest` so you don't stick on a
+   stale npx cache of an older version).
+2. Compiles `node-pty` for this host on first install.
+3. Starts the daemon on port **43117**, with LAN access and opt-in
+   public HTTPS through a Cloudflare tunnel.
+4. Keeps host administration local; it never prints the administrator credential.
+
+Leave the process in the foreground while you work (Termius / tmux / SSH session).
+Ctrl+C stops it — **no systemd required**. Start it when you sit down; stop it
+when you're done.
+
+### Pair a device
+
+```sh
+npx @fabiofiorita/porcelain@latest access issue --name "My phone"
+```
+
+Open the printed connection link in a browser, or paste it into the Mac app's
+**Settings → Remotes**. The link expires in 15 minutes, works once, and becomes
+an individually revocable device credential. Manage access only on the host:
+
+```sh
+npx @fabiofiorita/porcelain@latest access list
+npx @fabiofiorita/porcelain@latest access revoke <id>
+npx @fabiofiorita/porcelain@latest share status
+```
+
+## Host launcher
+
+```text
+porcelain serve [options]
+porcelain access issue --name <device> [--base-url <url>]
+porcelain access list | revoke <id>
+porcelain share status
+
+  --port <n>           Port (default 43117)
+  --user-data <path>   Config dir (default ~/.local/share/porcelain)
+  --tailnet            Bind Tailscale interface too
+  --lan                Bind RFC1918 LAN addresses too
+  --cloudflare         Publish loopback over Cloudflare (named or quick)
+  --allowed-origin <origin>
+                       Trust a browser Hub origin (repeat for more than one)
+  --no-watchdog        For systemd / supervisors (stdin is /dev/null)
+```
+
+Porcelain always binds loopback, never `0.0.0.0`. Private listeners are explicit.
+Cloudflare is public HTTPS but still credential-gated. Tailscale and Cloudflare are
+exclusive; LAN can combine with either.
+
+## Always-on (optional)
+
+If you *do* want a supervised process, use `--no-watchdog` and a unit like:
+
+```ini
+[Service]
+Environment=PORCELAIN_USER_DATA=%h/.local/share/porcelain
+Environment=PORCELAIN_DAEMON_PORT=43117
+Environment=PORCELAIN_ALLOWED_ORIGIN=http://hub-host:43118
+Environment=PORCELAIN_TAILNET_BIND=1
+Environment=PORCELAIN_NO_STDIN_WATCHDOG=1
+ExecStart=/usr/bin/npx --yes @fabiofiorita/porcelain@latest serve --no-watchdog --tailnet
+Restart=on-failure
+```
+
+Prefer a real `node` binary over Volta/fnm/nvm shims in `ExecStart` when pinning
+a global install instead of npx.
+
+For a browser Hub served from another origin, set `PORCELAIN_ALLOWED_ORIGIN` to that Hub's
+bare `http(s)` origin (repeat `--allowed-origin` for multiple Hubs; comma-separated values
+are accepted). Paths, credentials, wildcards, and `null` are rejected. This setting only
+controls CORS response headers; every API and WebSocket request remains token-gated.
+
+## Agent access (MCP)
+
+The daemon serves the Model Context Protocol at `POST /mcp` for direct loopback agent
+clients without an admin token. LAN, Tailscale, Cloudflare, and proxied requests receive
+404. Install the plugin through your client's native plugin manager. For an Agent Plugin client,
+add the repository `FabioFiorita/porcelain`; for Claude Code, use:
+
+```text
+/plugin marketplace add FabioFiorita/porcelain
+/plugin install porcelain@porcelain
+```
+
+Installing the plugin is the opt-in. The endpoint is always served, so upgrading the
+daemon ships new tools with no per-agent configuration to rewrite.
+
+## Requirements
+
+- **Node ≥ 22**
+- **git** on PATH
+- A **C toolchain** (make, g++, python3) — first install compiles `node-pty`
+
+## Develop / ship from the monorepo
+
+```sh
+pnpm build && pnpm daemon:dist
+cd dist-daemon && npm publish --access public
+```
+
+Assembled by `pnpm daemon:dist` from a completed `pnpm build`. Do not edit
+`dist-daemon/` by hand — regenerate.

package/bin/porcelain.js

@@ -0,0 +1,405 @@
+#!/usr/bin/env node
+// Narrow host launcher for the published @fabiofiorita/porcelain package.
+// Copied into dist-daemon/bin/ by scripts/build-daemon-dist.mjs — not run from
+// the monorepo root (paths resolve relative to the installed package layout).
+//
+// Goal: t3-style one-liner on a remote box —
+//   npx @fabiofiorita/porcelain@latest serve --tailnet
+// instead of scp'ing a dist tarball and wiring systemd.
+
+const { randomBytes } = require('node:crypto')
+const {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} = require('node:fs')
+const { homedir } = require('node:os')
+const { dirname, join } = require('node:path')
+const { createTRPCUntypedClient, httpLink } = require('@trpc/client')
+
+const DEFAULT_PORT = 43117
+const DEFAULT_USER_DATA = join(homedir(), '.local', 'share', 'porcelain')
+// PORCELAIN_HOME redirects token + channels (dev stack uses ~/.porcelain-dev).
+const porcelainHome = () => process.env.PORCELAIN_HOME ?? join(homedir(), '.porcelain')
+const ADMIN_TOKEN_PATH = () =>
+  process.env.PORCELAIN_ADMIN_TOKEN_FILE ?? join(porcelainHome(), 'admin-token')
+
+const HELP = `porcelain — headless Porcelain backend (plain Node, no Electron)
+
+Usage:
+  porcelain serve [options]
+  porcelain [options]              (same as serve)
+  porcelain access issue --name <device> [--base-url <url>]
+  porcelain access list
+  porcelain access revoke <id>
+  porcelain share status
+
+Options:
+  --port <n>           Listen port for loopback AND LAN/tailnet (default ${DEFAULT_PORT})
+  --user-data <path>   Config dir (default ${DEFAULT_USER_DATA})
+  --lan                Also bind RFC1918 LAN addresses (same --port)
+  --tailnet            Also bind the Tailscale interface (same --port)
+  --cloudflare         Publish loopback over Cloudflare (named tunnel if
+                       PORCELAIN_CLOUDFLARE_TOKEN is set, else a quick tunnel)
+  --cloudflare-hostname <host>
+                       Public https hostname of a named tunnel
+  --allowed-origin <origin>
+                       Trust a browser Hub origin for cross-origin API/WS (repeatable)
+  --no-watchdog        Disable stdin parent-death watchdog (required under systemd)
+  -h, --help           Show this help
+
+Host-management options:
+  --daemon-url <url>   Loopback daemon URL when not using the default port
+  --base-url <url>     Reachable URL to embed in a new connection link
+
+Examples:
+  npx @fabiofiorita/porcelain@latest serve --lan
+  npx @fabiofiorita/porcelain@latest serve --lan --tailnet
+  npx @fabiofiorita/porcelain@latest serve --lan --cloudflare --cloudflare-hostname review.example.com
+  npx @fabiofiorita/porcelain@latest access issue --name "My phone"
+  npx @fabiofiorita/porcelain@latest serve --port 43118 --lan
+
+Env (same as the raw daemon; flags set these when passed):
+  PORCELAIN_USER_DATA, PORCELAIN_DAEMON_PORT, PORCELAIN_ADMIN_TOKEN,
+  PORCELAIN_ALLOWED_ORIGIN (comma-separated), PORCELAIN_ALLOWED_ORIGINS (comma-separated),
+  PORCELAIN_TAILNET_BIND, PORCELAIN_LAN_BIND, PORCELAIN_CLOUDFLARE_BIND,
+  PORCELAIN_CLOUDFLARE_HOSTNAME, PORCELAIN_CLOUDFLARE_TOKEN,
+  PORCELAIN_NO_STDIN_WATCHDOG
+
+Notes:
+  • Always binds 127.0.0.1; --tailnet / --lan add private interfaces only
+    (never 0.0.0.0). Cloudflare uses a separate loopback ingress without MCP.
+  • Named tunnels: set PORCELAIN_CLOUDFLARE_TOKEN (never a flag) and
+    --cloudflare-hostname. Without a token, --cloudflare is a quick tunnel
+    whose URL changes every start.
+  • --tailnet and --cloudflare are mutually exclusive. LAN can combine with either.
+  • Host administration lives at ~/.porcelain/admin-token (0600) and is never shared.
+  • Pairing links are one-time credentials; clients receive individually revocable access.
+  • Use @latest so each invoke can pick up a newer published package.
+  • First install compiles node-pty for this host (needs a C toolchain).
+`
+
+function fail(message) {
+  console.error(`[porcelain] ${message}`)
+  process.exit(1)
+}
+
+/**
+ * Minimal argv parse — no deps in the published package beyond the daemon's.
+ * Unknown flags / missing values exit non-zero with a short message.
+ */
+function parseArgs(argv) {
+  const opts = {
+    command: 'serve',
+    port: DEFAULT_PORT,
+    userData: DEFAULT_USER_DATA,
+    tailnet: false,
+    lan: false,
+    cloudflare: false,
+    cloudflareHostname: null,
+    noWatchdog: false,
+    allowedOrigins: [],
+    help: false,
+  }
+
+  let i = 0
+  // Bare invocation and explicit `serve` both mean serve (t3-compatible).
+  if (argv[0] === 'serve') {
+    i = 1
+  } else if (argv[0] === 'help' || argv[0] === '--help' || argv[0] === '-h') {
+    opts.help = true
+    return opts
+  }
+
+  while (i < argv.length) {
+    const arg = argv[i]
+    if (arg === '-h' || arg === '--help') {
+      opts.help = true
+      i += 1
+      continue
+    }
+    if (arg === '--tailnet') {
+      opts.tailnet = true
+      i += 1
+      continue
+    }
+    if (arg === '--lan') {
+      opts.lan = true
+      i += 1
+      continue
+    }
+    if (arg === '--cloudflare') {
+      opts.cloudflare = true
+      i += 1
+      continue
+    }
+    if (arg === '--cloudflare-hostname') {
+      const raw = argv[i + 1]
+      if (raw === undefined) fail('--cloudflare-hostname requires a hostname')
+      opts.cloudflareHostname = raw
+      opts.cloudflare = true
+      i += 2
+      continue
+    }
+    if (arg === '--funnel') {
+      fail('Tailscale Funnel was removed. Use --cloudflare for public HTTPS.')
+    }
+    if (arg === '--no-watchdog') {
+      opts.noWatchdog = true
+      i += 1
+      continue
+    }
+    if (arg === '--allowed-origin' || arg === '--allowed-origins') {
+      const raw = argv[i + 1]
+      if (raw === undefined) fail(`${arg} requires a value`)
+      opts.allowedOrigins.push(raw)
+      i += 2
+      continue
+    }
+    if (arg === '--port') {
+      const raw = argv[i + 1]
+      if (raw === undefined) fail('--port requires a value')
+      const port = Number(raw)
+      if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        fail(`--port must be an integer 1–65535 (got ${raw})`)
+      }
+      opts.port = port
+      i += 2
+      continue
+    }
+    if (arg === '--user-data') {
+      const raw = argv[i + 1]
+      if (raw === undefined) fail('--user-data requires a path')
+      opts.userData = raw
+      i += 2
+      continue
+    }
+    fail(`unknown argument: ${arg}\n\n${HELP}`)
+  }
+
+  return opts
+}
+
+/** Same semantics as apps/daemon/src/net/admin-token.ts (plain CJS copy). */
+function ensureAdminToken(path = ADMIN_TOKEN_PATH()) {
+  try {
+    const existing = readFileSync(path, 'utf8').trim()
+    if (existing !== '') {
+      chmodSync(path, 0o600)
+      return existing
+    }
+  } catch {
+    // absent — mint
+  }
+  const token = randomBytes(32).toString('hex')
+  mkdirSync(dirname(path), { recursive: true })
+  const tmp = `${path}.tmp`
+  writeFileSync(tmp, token, { encoding: 'utf8', mode: 0o600 })
+  renameSync(tmp, path)
+  return token
+}
+
+// The built contracts module (scripts/build-node.mjs), in the two layouts this script
+// ships in: the installed package (bin/ beside main/) and the monorepo checkout (scripts/
+// beside apps/desktop/out/main/). Same relative-resolution mechanism the serve path already
+// uses for main/daemon/server.js.
+const PROTOCOL_MODULES = [
+  join(__dirname, '..', 'main', 'contracts', 'protocol.js'),
+  join(__dirname, '..', 'apps', 'desktop', 'out', 'main', 'contracts', 'protocol.js'),
+]
+
+/**
+ * The daemon refuses any request that does not announce its exact wire protocol, so this
+ * CLI announces it too — read from the built contracts, never a literal copied here, which
+ * would silently become a lie the day the protocol moves.
+ */
+function protocolHeaders() {
+  const modulePath = PROTOCOL_MODULES.find((candidate) => existsSync(candidate))
+  if (modulePath === undefined) {
+    fail('protocol contracts missing — run `pnpm build` in the monorepo, or reinstall the package')
+  }
+  const { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } = require(modulePath)
+  return { [PROTOCOL_VERSION_HEADER]: String(PROTOCOL_VERSION) }
+}
+
+function adminClient(daemonUrl, token) {
+  return createTRPCUntypedClient({
+    links: [
+      httpLink({
+        url: `${daemonUrl}/trpc`,
+        headers: { authorization: `Bearer ${token}`, ...protocolHeaders() },
+      }),
+    ],
+  })
+}
+
+function adminCommandOptions(argv) {
+  const result = {
+    args: [],
+    daemonUrl: `http://127.0.0.1:${process.env.PORCELAIN_DAEMON_PORT || DEFAULT_PORT}`,
+    baseUrl: null,
+    name: null,
+  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--daemon-url' || arg === '--base-url' || arg === '--name') {
+      const value = argv[i + 1]
+      if (!value) fail(`${arg} requires a value`)
+      if (arg === '--daemon-url') result.daemonUrl = value.replace(/\/+$/, '')
+      else if (arg === '--base-url') result.baseUrl = value
+      else result.name = value
+      i += 1
+    } else {
+      result.args.push(arg)
+    }
+  }
+  return result
+}
+
+async function suggestedBaseUrl(client) {
+  const lan = await client.query('lanStatus').catch(() => null)
+  if (lan?.numericUrl || lan?.url) return lan.numericUrl || lan.url
+  const tailnet = await client.query('tailnetStatus').catch(() => null)
+  if (tailnet?.url) return tailnet.url
+  const cloudflare = await client.query('cloudflareStatus').catch(() => null)
+  return cloudflare?.url || null
+}
+
+async function runAccessCommand(argv) {
+  const options = adminCommandOptions(argv)
+  const [action, id] = options.args
+  const client = adminClient(options.daemonUrl, ensureAdminToken())
+  if (action === 'issue') {
+    if (!options.name) fail('access issue requires --name <device>')
+    const baseUrl = options.baseUrl || (await suggestedBaseUrl(client))
+    if (!baseUrl) fail('no reachable endpoint is enabled; pass --base-url explicitly')
+    const result = await client.mutation('issuePairingLink', {
+      label: options.name,
+      baseUrl,
+    })
+    process.stdout.write(`${result.url}\n`)
+    return
+  }
+  if (action === 'list') {
+    const status = await client.query('accessStatus')
+    process.stdout.write(`${JSON.stringify(status, null, 2)}\n`)
+    return
+  }
+  if (action === 'revoke' && id) {
+    const status = await client.query('accessStatus')
+    if (status.clients.some((entry) => entry.id === id)) {
+      await client.mutation('revokeAuthorizedClient', id)
+    } else if (status.pairings.some((entry) => entry.id === id)) {
+      await client.mutation('revokePairingLink', id)
+    } else {
+      fail(`no device or pairing link has id ${id}`)
+    }
+    process.stdout.write(`Revoked ${id}\n`)
+    return
+  }
+  fail('usage: porcelain access issue --name <device> | list | revoke <id>')
+}
+
+async function runShareCommand(argv) {
+  const options = adminCommandOptions(argv)
+  const [target] = options.args
+  const client = adminClient(options.daemonUrl, ensureAdminToken())
+  if (target === 'status') {
+    const [lan, tailnet, cloudflare] = await Promise.all([
+      client.query('lanStatus'),
+      client.query('tailnetStatus'),
+      client.query('cloudflareStatus'),
+    ])
+    process.stdout.write(`${JSON.stringify({ lan, tailnet, cloudflare }, null, 2)}\n`)
+    return
+  }
+  fail('usage: porcelain share status')
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  if (argv[0] === 'access') {
+    await runAccessCommand(argv.slice(1))
+    return
+  }
+  if (argv[0] === 'share') {
+    await runShareCommand(argv.slice(1))
+    return
+  }
+  const opts = parseArgs(argv)
+  if (opts.help) {
+    process.stdout.write(HELP)
+    process.exit(0)
+  }
+
+  // Prefer an already-set env (systemd unit, shell export) over flag defaults.
+  if (!process.env.PORCELAIN_USER_DATA) {
+    process.env.PORCELAIN_USER_DATA = opts.userData
+  }
+  if (!process.env.PORCELAIN_DAEMON_PORT) {
+    process.env.PORCELAIN_DAEMON_PORT = String(opts.port)
+  }
+  // Preserve an explicitly supplied service environment. A flag supplies the same
+  // comma-separated format as PORCELAIN_ALLOWED_ORIGIN and is repeated for several Hubs.
+  if (
+    opts.allowedOrigins.length > 0 &&
+    !process.env.PORCELAIN_ALLOWED_ORIGIN &&
+    !process.env.PORCELAIN_ALLOWED_ORIGINS
+  ) {
+    process.env.PORCELAIN_ALLOWED_ORIGIN = opts.allowedOrigins.join(',')
+  }
+  if (opts.tailnet && opts.cloudflare) {
+    fail('--tailnet and --cloudflare cannot be used together. Pick one off-network route.')
+  }
+  if (opts.tailnet) process.env.PORCELAIN_TAILNET_BIND = '1'
+  if (opts.lan) process.env.PORCELAIN_LAN_BIND = '1'
+  if (opts.cloudflare) process.env.PORCELAIN_CLOUDFLARE_BIND = '1'
+  if (opts.cloudflareHostname && !process.env.PORCELAIN_CLOUDFLARE_HOSTNAME) {
+    process.env.PORCELAIN_CLOUDFLARE_HOSTNAME = opts.cloudflareHostname
+  }
+  if (opts.noWatchdog) process.env.PORCELAIN_NO_STDIN_WATCHDOG = '1'
+
+  const token = process.env.PORCELAIN_ADMIN_TOKEN || ensureAdminToken()
+  process.env.PORCELAIN_ADMIN_TOKEN = token
+
+  const userData = process.env.PORCELAIN_USER_DATA
+  const port = process.env.PORCELAIN_DAEMON_PORT
+  const binds = ['127.0.0.1']
+  if (process.env.PORCELAIN_TAILNET_BIND === '1') binds.push('tailnet')
+  if (process.env.PORCELAIN_LAN_BIND === '1') binds.push('lan')
+  if (process.env.PORCELAIN_CLOUDFLARE_BIND === '1') binds.push('cloudflare')
+  const allowedOriginValue =
+    process.env.PORCELAIN_ALLOWED_ORIGINS || process.env.PORCELAIN_ALLOWED_ORIGIN || ''
+  const allowedOriginCount = allowedOriginValue
+    .split(',')
+    .map((origin) => origin.trim())
+    .filter(Boolean).length
+
+  // Human-facing status on stderr; the daemon still owns the one stdout port line.
+  console.error(`[porcelain] user data  ${userData}`)
+  console.error(`[porcelain] port       ${port}`)
+  console.error(`[porcelain] binds      ${binds.join(', ')}`)
+  console.error(
+    `[porcelain] cors       ${allowedOriginCount === 0 ? 'same-origin only' : `${allowedOriginCount} trusted Hub origin(s) configured`}`,
+  )
+  console.error(`[porcelain] admin file ${ADMIN_TOKEN_PATH()}`)
+  console.error('[porcelain] pair with: porcelain access issue --name <device>')
+  console.error('[porcelain] starting…  Ctrl+C to stop')
+
+  const serverEntry = [
+    join(__dirname, '..', 'main', 'daemon', 'server.js'),
+    // Monorepo fallback used by the composed proof; the published package uses
+    // the first layout above after `daemon:dist` assembles it.
+    join(__dirname, '..', 'apps', 'desktop', 'out', 'main', 'daemon', 'server.js'),
+  ].find((candidate) => existsSync(candidate))
+  if (serverEntry === undefined) {
+    fail('daemon entry missing — package is corrupt; reinstall')
+  }
+  // Side-effect entry: boots the HTTP/WS listeners (same as `node main/daemon/server.js`).
+  require(serverEntry)
+}
+
+main().catch((error) => fail(error instanceof Error ? error.message : String(error)))