@linxin666/dsh-remote-web-ui 0.3.12 → 0.3.13

package/src/index.ts

@@ -32,6 +32,8 @@ import { claimPostureKey, postureTargets, probePosture, releasePostureKey } from
 import { lanIPv4Addresses } from './lan.ts'
 import { ensureFirewallRule, firewallSummary, removeFirewallRule } from './firewall.ts'
 import { lanBindState, writeLanBind } from './lan-bind.ts'
+import { isHttpUrl, tunnelPlanOf } from './tunnel-plan.ts'
+import { loadRelayIdentity, RelayRegistrar, type RelayState } from './relay-registry.ts'
 import { desiredBindHost, desiredBindPort, firewallActionNeeded, pendingRestartOf, type AppliedFirewallState, type StartupFacts } from './lan-bind-plan.ts'
 import { createInnerAuth } from './inner-auth.ts'
 import { TunnelManager, type TunnelInfo } from './tunnel.ts'
@@ -136,9 +138,34 @@ export interface Config {
    * cloudflared binary ships with the package — no user-side install) and
    * feeds the minted public URL into the QR base and the phone-facing
    * pairing fence dynamically, so phones anywhere can pair without any manual
-   * tunnel setup. The manual `publicBaseUrl` is ignored while this is on.
+   * tunnel setup. The minted hostname changes on every start, so a paired
+   * phone must re-pair after each restart. The manual `publicBaseUrl` and
+   * `tunnelToken` are ignored while this is on.
    */
   autoTunnel?: boolean
+  /**
+   * Cloudflare named-tunnel token (`cloudflared tunnel run --token <t>`).
+   * When set (and `autoTunnel` is off), the plugin runs the named tunnel
+   * itself — same binary, same lifecycle management — toward the fixed
+   * public hostname configured in the Cloudflare dashboard. Because that
+   * hostname never changes, a paired phone keeps its bookmark and its
+   * pairing cookie across `dsh web` restarts: pair once, never again.
+   * Requires `publicBaseUrl` to name that same hostname (the token does not
+   * carry it); without a valid `publicBaseUrl` the tunnel stays off and a
+   * warning explains what is missing. Treated as a secret: the settings
+   * surface stores it redacted.
+   */
+  tunnelToken?: string
+  /**
+   * Stable-origin relay: when on (default), the quick tunnel is fronted by a
+   * fixed `https://<id>.dsh-market.com` subdomain (the dsh-market worker's
+   * registry), so the phone's bookmark and pairing cookie survive `dsh web`
+   * restarts without any user setup. Traffic transits the dsh-market edge
+   * (the same trust point as the quick tunnel itself); turn off to fall back
+   * to the raw ephemeral quick URL. Named tunnels keep their dashboard
+   * hostname and never touch the relay.
+   */
+  relay?: boolean
   /**
    * LAN bind toggle. When the user flips it (true or false) the plugin
    * writes the managed webserver block into the profile patch — true pins
@@ -174,6 +201,8 @@ export const Config: z<Config> = z.object({
   publicBaseUrl: z.string(),
   devicesFile: z.string(),
   autoTunnel: z.boolean().default(false),
+  tunnelToken: z.string().role('secret'),
+  relay: z.boolean().default(true),
   lanBind: z.boolean(),
   profile: z.string().pattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
   enabled: z.boolean().default(true),
@@ -187,11 +216,12 @@ const SWEEP_INTERVAL_MS = 10_000
  * which legitimately resolves to `undefined` when unset (the schema keeps it
  * optional, so `Required` alone would over-narrow it to `string`).
  */
-type ResolvedConfig = Required<Omit<Config, 'publicBaseUrl' | 'devicesFile' | 'lanBind' | 'profile'>> & {
+type ResolvedConfig = Required<Omit<Config, 'publicBaseUrl' | 'devicesFile' | 'lanBind' | 'profile' | 'tunnelToken'>> & {
   publicBaseUrl: string | undefined
   devicesFile: string
   /** undefined until the user flips the toggle once; undefined never writes the patch. */
   lanBind: boolean | undefined
+  tunnelToken: string | undefined
   profile: string
 }
 
@@ -231,6 +261,8 @@ const DEFAULTS: ResolvedConfig = {
   publicBaseUrl: undefined,
   devicesFile: defaultDevicesFile(),
   autoTunnel: false,
+  tunnelToken: undefined,
+  relay: true,
   lanBind: undefined,
   profile: process.env.DSH_PROFILE ?? 'web',
   enabled: true,
@@ -254,6 +286,8 @@ function applyImpl(ctx: Context, config?: Config): void {
     publicBaseUrl: config?.publicBaseUrl,
     devicesFile: config?.devicesFile ?? DEFAULTS.devicesFile,
     autoTunnel: config?.autoTunnel ?? DEFAULTS.autoTunnel,
+    tunnelToken: config?.tunnelToken,
+    relay: config?.relay ?? DEFAULTS.relay,
     lanBind: config?.lanBind,
     profile: config?.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
     enabled: config?.enabled ?? DEFAULTS.enabled,
@@ -274,6 +308,8 @@ function applyImpl(ctx: Context, config?: Config): void {
       publicBaseUrl: value.publicBaseUrl,
       devicesFile: value.devicesFile ?? DEFAULTS.devicesFile,
       autoTunnel: value.autoTunnel ?? DEFAULTS.autoTunnel,
+      tunnelToken: value.tunnelToken,
+      relay: value.relay ?? DEFAULTS.relay,
       lanBind: value.lanBind,
       profile: value.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
       enabled: value.enabled ?? DEFAULTS.enabled,
@@ -288,24 +324,89 @@ function applyImpl(ctx: Context, config?: Config): void {
   // mutation is needed here (a distributable plugin must not change the
   // harness's connection plugin).
   const tunnel = new TunnelManager()
-  let autoTunnel = resolved.autoTunnel
+  // Relay registry: one stable `<id>.dsh-market.com` subdomain per profile
+  // in front of the quick tunnel. The QR base prefers the relay origin once
+  // it is registered; until then (or when the registry is unreachable) the
+  // raw quick URL is used, exactly as before. Named tunnels keep their fixed
+  // dashboard hostname and never touch the relay.
+  let relayRegistrar: RelayRegistrar | undefined
+  let relayUrl: string | undefined
+  let rawTunnelUrl: string | undefined
+  /** The tunnel target the registrar last announced (dedupes sync re-runs). */
+  let relayAnnouncedFor: string | undefined
+  const setPublicBase = (): void => {
+    service.setPublicBaseUrl(relayUrl ?? rawTunnelUrl)
+  }
+  const disposeRelayRegistrar = (unregister: boolean = false): void => {
+    const registrar = relayRegistrar
+    relayRegistrar = undefined
+    relayUrl = undefined
+    relayAnnouncedFor = undefined
+    if (registrar === undefined) return
+    // Toggle-off removes the registry row so the stable origin stops
+    // proxying; teardown/mode changes keep the row (the phone then sees the
+    // relay's offline page instead of a dangling claim, and re-enabling
+    // reuses the same identity).
+    if (unregister) void registrar.unregister().catch(() => undefined)
+    registrar.dispose()
+  }
+  const ensureRelayRegistrar = (): RelayRegistrar | undefined => {
+    if (resolve().relay === false) return undefined
+    if (relayRegistrar === undefined) {
+      try {
+        const identity = loadRelayIdentity(resolve().profile)
+        relayRegistrar = new RelayRegistrar(identity, (state: RelayState) => {
+          service.setRelayStatus(state.state === 'off' ? undefined : state)
+          if (state.state === 'running') {
+            relayUrl = state.url
+          } else if (state.state === 'off') {
+            relayUrl = undefined
+          } else if (state.state === 'failed') {
+            // Keep the last relay URL on failures: the phone origin only
+            // breaks when the mapping itself goes stale, not when one
+            // refresh call fails. The registrar retries with backoff.
+            console.warn(`remote-web-ui: relay registration failed (${state.error}) — the stable origin may serve its offline page until the retry lands`)
+          }
+          setPublicBase()
+        })
+      } catch (error) {
+        console.warn(`remote-web-ui: relay registry unavailable (${error instanceof Error ? error.message : String(error)}) — the quick URL is the QR base`)
+      }
+    }
+    return relayRegistrar
+  }
+  const announceRelay = (registrar: RelayRegistrar, target: string): void => {
+    if (relayAnnouncedFor === target) return
+    relayAnnouncedFor = target
+    void registrar.announce(target)
+  }
+  // 'off' until a sync pass turns a mode on; the phase listener only feeds
+  // the public base while a plugin-managed tunnel (quick or named) runs.
+  let tunnelMode: 'off' | 'quick' | 'named' = resolved.autoTunnel ? 'quick' : 'off'
   tunnel.onPhase((info: TunnelInfo) => {
-    if (!autoTunnel) return
+    if (tunnelMode === 'off') return
     if (info.phase === 'running' && info.url !== undefined) {
-      service.setPublicBaseUrl(info.url)
+      rawTunnelUrl = info.url
+      setPublicBase()
       service.setTunnelStatus({ state: 'running', url: info.url })
+      const registrar = tunnelMode === 'quick' ? ensureRelayRegistrar() : undefined
+      if (registrar !== undefined) announceRelay(registrar, info.url)
       runPostureProbe()
     } else if (info.phase === 'starting') {
       // A restart mints a NEW hostname: the previous URL dies with the old
       // process, so clear it now rather than advertising a dead link.
-      service.setPublicBaseUrl(undefined)
+      rawTunnelUrl = undefined
+      relayUrl = undefined
+      setPublicBase()
       service.setTunnelStatus({ state: 'starting' })
     } else if (info.phase === 'failed') {
-      service.setPublicBaseUrl(undefined)
+      rawTunnelUrl = undefined
+      setPublicBase()
       service.setTunnelStatus(info.error === undefined ? { state: 'failed' } : { state: 'failed', error: info.error })
     }
   })
   ctx.effect(() => () => {
+    disposeRelayRegistrar()
     tunnel.dispose()
   }, 'remote-web-ui: auto tunnel')
   // The bind facts are known by now (webServer is an inject edge): the LAN
@@ -639,17 +740,54 @@ function applyImpl(ctx: Context, config?: Config): void {
         }
       }
     }
-    // The auto tunnel owns the public base while enabled: the minted URL
-    // lands in the service through the tunnel's phase listener. The manual
-    // publicBaseUrl applies only when the auto tunnel is off.
-    autoTunnel = value.autoTunnel === true
-    if (autoTunnel) {
-      if (value.publicBaseUrl !== undefined) {
-        console.warn('remote-web-ui: autoTunnel is on — ignoring the manually configured publicBaseUrl')
+    // The plugin-managed tunnels own the public base while one runs: the URL
+    // lands in the service through the tunnel's phase listener (the minted
+    // quick URL, or the named tunnel's fixed public hostname). The manual
+    // publicBaseUrl applies only when no tunnel runs.
+    const plan = tunnelPlanOf(value, ctx.webServer.port)
+    tunnelMode = plan.mode
+    if (plan.mode !== 'quick') {
+      // The relay only fronts the quick tunnel; named mode owns its fixed
+      // dashboard hostname and the off mode has no public base at all.
+      disposeRelayRegistrar()
+      if (plan.mode !== 'named') setPublicBase()
+    } else if (value.relay === false) {
+      // The relay toggle is off: no stable origin, the raw quick URL is the
+      // QR base exactly as before the relay existed.
+      disposeRelayRegistrar(true)
+      setPublicBase()
+    } else if (rawTunnelUrl !== undefined) {
+      // The relay just turned on (or the registrar is new) while the tunnel
+      // already runs: announce now — no phase event will fire for an
+      // unchanged target.
+      const registrar = ensureRelayRegistrar()
+      if (registrar !== undefined) announceRelay(registrar, rawTunnelUrl)
+    }
+    if (plan.mode === 'quick') {
+      for (const ignored of plan.ignored) {
+        console.warn(`remote-web-ui: autoTunnel is on — ignoring the configured ${ignored}`)
       }
-      tunnel.start(`http://127.0.0.1:${String(ctx.webServer.port)}`)
+      // With the relay on, the connector stamps the stable origin as the
+      // origin-side Host (`--http-host-header`): the plugin fence and the
+      // harness browser-auth are Host-bound to the relay origin, and the
+      // Workers relay cannot control the origin-side Host (fetch forces it
+      // to the URL authority). The target identity change is also what
+      // restarts a running tunnel on a relay toggle.
+      const registrar = ensureRelayRegistrar()
+      const originHostHeader = registrar === undefined ? undefined : new URL(registrar.baseUrl).host
+      tunnel.start(originHostHeader === undefined
+        ? plan.targetUrl
+        : { kind: 'quick', targetUrl: plan.targetUrl, originHostHeader })
+    } else if (plan.mode === 'named') {
+      tunnel.start({ kind: 'named', token: plan.token, publicUrl: plan.publicUrl })
     } else {
       tunnel.stop()
+      // A named-tunnel token without a usable public hostname cannot serve
+      // the QR: stay off and say exactly what is missing instead of running
+      // a tunnel nothing points at.
+      if (value.tunnelToken !== undefined && value.tunnelToken !== '') {
+        console.warn('remote-web-ui: tunnelToken is set but publicBaseUrl is missing or not a valid URL — fill the fixed public hostname of the named tunnel (e.g. https://dsh.example.com) to run it')
+      }
       // A malformed public base is ignored with a warning — LAN-only behavior
       // stays intact rather than silently minting unusable QR links.
       if (value.publicBaseUrl !== undefined && !isHttpUrl(value.publicBaseUrl)) {
@@ -724,13 +862,3 @@ function applyImpl(ctx: Context, config?: Config): void {
   })
   sync()
 }
-
-/** Whether a configured public base is a parseable http(s) URL with a host. */
-function isHttpUrl(value: string): boolean {
-  try {
-    const url = new URL(value)
-    return (url.protocol === 'http:' || url.protocol === 'https:') && url.hostname !== ''
-  } catch {
-    return false
-  }
-}

package/src/pairing.ts

@@ -103,6 +103,19 @@ export interface TunnelStatus {
   error?: string
 }
 
+/**
+ * One relay-registry status frame (undefined while the stable-origin relay
+ * is not in play: autoTunnel off, or the relay toggle disabled).
+ */
+export interface RelayStatus {
+  /** registering: a sync is in flight; running: the mapping is accepted. */
+  state: 'off' | 'registering' | 'running' | 'failed'
+  /** The stable relay origin (`https://<id>.dsh-market.com`). */
+  url?: string
+  /** Human-readable failure detail of the last sync attempt. */
+  error?: string
+}
+
 /** One snapshot frame pushed to desktop status streams. */
 export interface PairingSnapshot {
   phase: PairingPhase
@@ -114,6 +127,8 @@ export interface PairingSnapshot {
   publicUrl?: string
   /** Auto-tunnel status, while the auto-tunnel feature is active. */
   tunnel?: TunnelStatus
+  /** Relay-registry status, while the stable-origin relay is in play. */
+  relay?: RelayStatus
   /** Latest /api posture probe (undefined until the first round completes). */
   posture?: PostureSnapshot
   /** Opaque (non-secret) id of the active token (undefined when stopped/lan-required). */
@@ -202,6 +217,7 @@ export class PairingService {
   private publicBase: string | undefined
   /** Auto-tunnel status, while the auto-tunnel feature is active. */
   private tunnelStatus: TunnelStatus | undefined
+  private relayStatus: RelayStatus | undefined
   private posture: PostureSnapshot | undefined
   /** True when lastSeenAt changed since the last persist (flushed on sweep). */
   private dirty = false
@@ -339,6 +355,12 @@ export class PairingService {
     this.notify()
   }
 
+  /** Set or clear the relay-registry status frame (undefined when not in play). */
+  setRelayStatus(status: RelayStatus | undefined): void {
+    this.relayStatus = status
+    this.notify()
+  }
+
   /** Set the latest /api posture probe result (see posture.ts). */
   setPosture(snapshot: PostureSnapshot | undefined): void {
     this.posture = snapshot
@@ -497,6 +519,7 @@ export class PairingService {
       lanAddresses: [...this.lanBases.keys()],
       ...(this.publicBase !== undefined ? { publicUrl: this.publicBase } : {}),
       ...(this.tunnelStatus !== undefined ? { tunnel: this.tunnelStatus } : {}),
+      ...(this.relayStatus !== undefined ? { relay: this.relayStatus } : {}),
       ...(this.posture !== undefined ? { posture: this.posture } : {}),
       ...(token !== undefined ? { tokenId: token.record.id, tokenExpiresAt: token.record.expiresAt } : {}),
       deviceCount: this.devices.size,
@@ -588,6 +611,7 @@ function snapshotsEqual(a: PairingSnapshot, b: PairingSnapshot): boolean {
     && sameStrings(a.lanAddresses, b.lanAddresses)
     && a.publicUrl === b.publicUrl
     && tunnelEqual(a.tunnel, b.tunnel)
+    && relayEqual(a.relay, b.relay)
     && a.tokenId === b.tokenId
     && a.tokenExpiresAt === b.tokenExpiresAt
     && a.deviceCount === b.deviceCount
@@ -614,6 +638,12 @@ function tunnelEqual(a: TunnelStatus | undefined, b: TunnelStatus | undefined):
     && a.state === b.state && a.url === b.url && a.error === b.error)
 }
 
+/** Relay frame equality (same shape as the tunnel frame). */
+function relayEqual(a: RelayStatus | undefined, b: RelayStatus | undefined): boolean {
+  return a === b || (a !== undefined && b !== undefined
+    && a.state === b.state && a.url === b.url && a.error === b.error)
+}
+
 /** Element-wise string list equality (interface order is meaningful). */
 function sameStrings(a: readonly string[], b: readonly string[]): boolean {
   return a.length === b.length && a.every((value, index) => value === b[index])

package/src/relay-registry.ts

@@ -0,0 +1,232 @@
+/**
+ * Relay registry client: a stable `https://<id>.dsh-market.com` origin in
+ * front of the plugin-managed quick tunnel, so a paired phone keeps one
+ * bookmark and one cookie context across `dsh web` restarts.
+ *
+ * The plugin mints an id + secret on first run and persists them per profile
+ * under `$DSH_HOME/remote-web-ui-registry/`; every tunnel (re)start
+ * re-registers the current quick URL with the market worker. Registration is
+ * best-effort: a registry outage never blocks the tunnel — the QR just falls
+ * back to the raw quick URL for that session (the pre-relay behavior).
+ */
+
+import { randomBytes } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { dshHome } from './dsh-home.ts'
+
+/** The market worker's registration endpoints (dsh-market.com edge API). */
+export const RELAY_REGISTER_URL = 'https://dsh-market.com/api/relay/register'
+export const RELAY_UNREGISTER_URL = 'https://dsh-market.com/api/relay/unregister'
+/**
+ * The public origin template: one stable single-label subdomain per
+ * registration id. Single label on purpose — Universal SSL covers exactly
+ * one subdomain level, so a two-level hostname would get no certificate.
+ */
+export const RELAY_BASE_SUFFIX = '.dsh-market.com'
+
+export const RELAY_ID_RE = /^[a-z0-9]{16}$/
+export const RELAY_SECRET_RE = /^[A-Za-z0-9_-]{43}$/
+
+/** Persisted per-profile relay identity. */
+export interface RelayIdentity {
+  id: string
+  secret: string
+  /**
+   * True only for an identity minted in this process that has never been
+   * accepted by the registry: the first register carries `new_secret` so
+   * the endpoint may create the row; refreshes authenticate with `secret`
+   * alone and must not re-claim an id that already exists.
+   */
+  fresh?: boolean
+}
+
+/** The observable relay lifecycle the settings card renders. */
+export type RelayState =
+  | { state: 'off' }
+  | { state: 'registering' }
+  | { state: 'running'; url: string }
+  | { state: 'failed'; error: string }
+
+/** Registry storage layout: one file per profile under the relay directory. */
+export function relayIdentityFile(profile: string, home: string = dshHome()): string {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(profile)) {
+    throw new Error(`relay registry: profile ${JSON.stringify(profile)} is not a safe path segment`)
+  }
+  return join(home, 'remote-web-ui-registry', `${profile}.json`)
+}
+
+/** Generate one identity pair (id: 8-byte hex slug; secret: 32-byte base64url). */
+export function generateRelayIdentity(random: (size: number) => Buffer = randomBytes): RelayIdentity {
+  return {
+    id: random(8).toString('hex'),
+    secret: random(32).toString('base64url'),
+    fresh: true,
+  }
+}
+
+/**
+ * Load (or lazily mint) the per-profile relay identity. The file is written
+ * owner-only on first mint; a corrupt file is reminted (the phone then
+ * re-pairs once — the same cost as losing the devices file).
+ */
+export function loadRelayIdentity(profile: string, home: string = dshHome(), random: (size: number) => Buffer = randomBytes): RelayIdentity {
+  const file = relayIdentityFile(profile, home)
+  try {
+    if (existsSync(file)) {
+      const parsed = JSON.parse(readFileSync(file, 'utf8')) as Partial<RelayIdentity>
+      if (typeof parsed.id === 'string' && RELAY_ID_RE.test(parsed.id)
+        && typeof parsed.secret === 'string' && RELAY_SECRET_RE.test(parsed.secret)) {
+        // A persisted identity has certainly been registered before.
+        return { id: parsed.id, secret: parsed.secret }
+      }
+      console.warn(`relay registry: ${file} is malformed — reminting the identity (paired devices must scan the QR once more)`)
+    }
+  } catch (error) {
+    console.warn(`relay registry: could not read ${file} (${error instanceof Error ? error.message : String(error)}) — reminting`)
+  }
+  const identity = generateRelayIdentity(random)
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, JSON.stringify({ id: identity.id, secret: identity.secret }, null, 2) + '\n', { mode: 0o600 })
+  return identity
+}
+
+/** Build the registration request body for one identity + tunnel target. */
+function registrationBody(identity: RelayIdentity, target: string): string {
+  return JSON.stringify({
+    id: identity.id,
+    secret: identity.secret,
+    new_secret: identity.fresh === true ? identity.secret : undefined,
+    target,
+  })
+}
+
+/** Best-effort removal of the mapping (used on disable; errors are swallowed). */
+export async function unregisterRelay(
+  identity: RelayIdentity,
+  endpoint: string = RELAY_UNREGISTER_URL,
+  fetchFn: typeof fetch = fetch,
+): Promise<void> {
+  await fetchFn(endpoint, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ id: identity.id, secret: identity.secret }),
+  })
+}
+
+/**
+ * The stable relay base for one identity — the origin the QR and the phone
+ * bookmark use while (or after) the registration is accepted.
+ */
+export function relayBaseOf(identity: RelayIdentity): string {
+  return `https://${identity.id}${RELAY_BASE_SUFFIX}`
+}
+
+/**
+ * Registration loop with capped exponential backoff. Re-registration happens
+ * on every tunnel start (the quick URL can change after a crash-restart);
+ * failures retry with backoff and surface the last error to the card.
+ */
+export class RelayRegistrar {
+  private timer: NodeJS.Timeout | undefined
+  private attempts = 0
+  private lastError: string | undefined
+  private disposed = false
+
+  constructor(
+    private readonly identity: RelayIdentity,
+    private readonly setState: (state: RelayState) => void,
+    private readonly options: {
+      fetchFn?: typeof fetch
+      registerUrl?: string
+      unregisterUrl?: string
+      baseDelayMs?: number
+      maxDelayMs?: number
+      timerFn?: (fn: () => void, ms: number) => NodeJS.Timeout
+    } = {},
+  ) {}
+
+  /** The stable relay base for the QR while registered. */
+  get baseUrl(): string {
+    return relayBaseOf(this.identity)
+  }
+
+  /** The last registration failure detail (undefined while healthy). */
+  get error(): string | undefined {
+    return this.lastError
+  }
+
+  /** Push one tunnel target; resolves the stable base once accepted. */
+  async announce(target: string): Promise<string | undefined> {
+    // A disposed registrar stays disposed: a pending retry timer must not
+    // resurrect it (re-enabling creates a fresh registrar instead).
+    if (this.disposed) return undefined
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer)
+      this.timer = undefined
+    }
+    this.setState({ state: 'registering' })
+    try {
+      const fetchFn = this.options.fetchFn ?? fetch
+      const response = await fetchFn(this.options.registerUrl ?? RELAY_REGISTER_URL, {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json' },
+        body: registrationBody(this.identity, target),
+      })
+      if (!response.ok) {
+        const detail = await response.json().catch(() => undefined)
+        const error = detail && typeof detail.error === 'string' ? detail.error : `HTTP ${String(response.status)}`
+        throw new Error(error)
+      }
+      // The row exists now: never claim a fresh id twice.
+      this.identity.fresh = false
+      this.attempts = 0
+      this.lastError = undefined
+      this.setState({ state: 'running', url: this.baseUrl })
+      return this.baseUrl
+    } catch (error) {
+      this.lastError = error instanceof Error ? error.message : String(error)
+      if (this.lastError === 'invalid-params' && this.identity.fresh !== true) {
+        // The registry lost the row (a D1 restore or manual wipe): re-claim
+        // the id with a fresh claim on the next retry. A 403 auth-failed
+        // means the id is owned by another secret and stays failed.
+        this.identity.fresh = true
+      }
+      this.setState({ state: 'failed', error: this.lastError })
+      this.scheduleRetry(target)
+      return undefined
+    }
+  }
+
+  /** Best-effort removal of the registry row (the relay toggle turned off). */
+  async unregister(): Promise<void> {
+    await unregisterRelay(this.identity, this.options.unregisterUrl, this.options.fetchFn)
+  }
+
+  private scheduleRetry(target: string): void {
+    if (this.disposed) return
+    const base = this.options.baseDelayMs ?? 5_000
+    const max = this.options.maxDelayMs ?? 60_000
+    const delay = Math.min(base * 2 ** this.attempts, max)
+    this.attempts += 1
+    const timerFn = this.options.timerFn ?? ((fn: () => void, ms: number) => {
+      const timer = setTimeout(fn, ms)
+      timer.unref?.()
+      return timer
+    })
+    this.timer = timerFn(() => {
+      this.timer = undefined
+      void this.announce(target)
+    }, delay)
+  }
+
+  /** Stop retrying and clear the card state (tunnel stopped or disabled). */
+  dispose(): void {
+    this.disposed = true
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer)
+      this.timer = undefined
+    }
+    this.setState({ state: 'off' })
+  }
+}

package/src/tunnel-plan.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure planner for the settings-sync tunnel branch: given the resolved
+ * settings slice, decide which tunnel mode runs and with what target. Kept
+ * free of cordis types so the precedence matrix is unit-testable without a
+ * host context.
+ */
+
+/** Whether a configured public base is a parseable http(s) URL with a host. */
+export function isHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value)
+    return (url.protocol === 'http:' || url.protocol === 'https:') && url.hostname !== ''
+  } catch {
+    return false
+  }
+}
+
+/** How the settings sync should drive the tunnel for one resolved value. */
+export type TunnelPlan =
+  | { mode: 'off' }
+  | { mode: 'quick'; targetUrl: string; ignored: Array<'tunnelToken' | 'publicBaseUrl'> }
+  | { mode: 'named'; token: string; publicUrl: string }
+
+/**
+ * Decide the tunnel mode and target from one resolved settings value.
+ * Precedence: the quick tunnel wins when `autoTunnel` is on (anything else
+ * configured is reported as ignored); the named tunnel runs only with a
+ * token AND a valid public hostname (the token does not carry the hostname,
+ * so the QR base and the fence trust would have no source without it);
+ * otherwise no tunnel and the manual public base applies.
+ * @param value - the resolved settings slice that drives the tunnel.
+ * @param port - the local webServer port the tunnel forwards to.
+ */
+export function tunnelPlanOf(
+  value: { autoTunnel?: boolean; tunnelToken?: string; publicBaseUrl?: string },
+  port: number,
+): TunnelPlan {
+  if (value.autoTunnel === true) {
+    const ignored: Array<'tunnelToken' | 'publicBaseUrl'> = []
+    if (value.tunnelToken !== undefined && value.tunnelToken !== '') ignored.push('tunnelToken')
+    if (value.publicBaseUrl !== undefined && value.publicBaseUrl !== '') ignored.push('publicBaseUrl')
+    return { mode: 'quick', targetUrl: `http://127.0.0.1:${String(port)}`, ignored }
+  }
+  if (value.tunnelToken !== undefined && value.tunnelToken !== '') {
+    if (value.publicBaseUrl !== undefined && isHttpUrl(value.publicBaseUrl)) {
+      return { mode: 'named', token: value.tunnelToken, publicUrl: value.publicBaseUrl }
+    }
+    return { mode: 'off' }
+  }
+  return { mode: 'off' }
+}