zooid 0.12.0 → 0.14.0

package/src/pi-extension-install.test.ts

@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { installPiExtension, resolvePiAgentDir } from './pi-extension-install.js'
+
+const dirs: string[] = []
+const scratch = () => { const dir = mkdtempSync(join(tmpdir(), 'zooid-pi-')); dirs.push(dir); return dir }
+afterEach(() => dirs.splice(0).forEach((dir) => rmSync(dir, { recursive: true, force: true })))
+
+describe('resolvePiAgentDir', () => {
+  it('resolves a relative PI_CODING_AGENT_DIR against each agent workdir', () => {
+    expect(
+      resolvePiAgentDir({
+        agentWorkdir: '/proj/agents/alice',
+        daemonHome: '/home/op',
+        env: { PI_CODING_AGENT_DIR: '.pi-agent' },
+      }),
+    ).toEqual({ dir: '/proj/agents/alice/.pi-agent', scope: 'project' })
+  })
+
+  it('honours an absolute override and falls back to the operator home', () => {
+    expect(
+      resolvePiAgentDir({
+        agentWorkdir: '/proj/agents/alice',
+        daemonHome: '/home/op',
+        env: { PI_CODING_AGENT_DIR: '/shared/pi' },
+      }),
+    ).toEqual({ dir: '/shared/pi', scope: 'project' })
+    expect(
+      resolvePiAgentDir({ agentWorkdir: '/proj/agents/alice', daemonHome: '/home/op', env: {} }),
+    ).toEqual({ dir: '/home/op/.pi/agent', scope: 'home' })
+  })
+})
+
+describe('installPiExtension', () => {
+  it('only installs into an existing Pi home and preserves other extensions', () => {
+    const home = scratch(); const source = join(scratch(), 'bundle.js')
+    writeFileSync(source, '// bundle')
+    const agentDir = join(home, '.pi', 'agent')
+    expect(installPiExtension({ agentDir, bundlePath: source })).toMatchObject({ status: 'skipped' })
+    expect(existsSync(join(home, '.pi'))).toBe(false)
+    const extensions = join(agentDir, 'extensions')
+    mkdirSync(extensions, { recursive: true }); writeFileSync(join(extensions, 'user.js'), '// user')
+    expect(installPiExtension({ agentDir, bundlePath: source })).toMatchObject({ status: 'installed' })
+    expect(readFileSync(join(extensions, 'zooid-tasks.js'), 'utf8')).toBe('// bundle')
+    expect(readFileSync(join(extensions, 'user.js'), 'utf8')).toBe('// user')
+    expect(installPiExtension({ agentDir, bundlePath: source })).toMatchObject({ status: 'unchanged' })
+  })
+
+  it('creates a project agent dir that does not exist yet', () => {
+    const workdir = scratch(); const source = join(scratch(), 'bundle.js')
+    writeFileSync(source, '// bundle')
+    const { dir } = resolvePiAgentDir({
+      agentWorkdir: workdir,
+      daemonHome: '/home/op',
+      env: { PI_CODING_AGENT_DIR: '.pi-agent' },
+    })
+    expect(installPiExtension({ agentDir: dir, bundlePath: source, createMissing: true })).toMatchObject({
+      status: 'installed',
+      target: join(workdir, '.pi-agent', 'extensions', 'zooid-tasks.js'),
+    })
+    expect(readFileSync(join(workdir, '.pi-agent', 'extensions', 'zooid-tasks.js'), 'utf8')).toBe('// bundle')
+  })
+})

package/src/pi-extension-install.ts

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+
+export interface InstallPiExtensionResult {
+  status: 'installed' | 'unchanged' | 'skipped'
+  reason?: string
+  target?: string
+}
+
+export interface PiAgentDir {
+  dir: string
+  /** `project` dirs are ours to create; `home` is the operator's ~/.pi. */
+  scope: 'project' | 'home'
+}
+
+/**
+ * Resolve pi's agent dir the way pi does: PI_CODING_AGENT_DIR when set,
+ * otherwise ~/.pi/agent.  `zooid init` writes that variable as a *relative*
+ * path on purpose (ZOD075) so one value is correct under both runtimes — it
+ * resolves against the agent's cwd, and `agents/<name>` locally and
+ * `/workspace` in a container are the same directory.  We always resolve
+ * against the host workdir, which is the host side of that same mount.
+ */
+export function resolvePiAgentDir(opts: {
+  agentWorkdir: string
+  daemonHome: string
+  env?: { PI_CODING_AGENT_DIR?: string | undefined }
+}): PiAgentDir {
+  const override = opts.env?.PI_CODING_AGENT_DIR
+  if (override) {
+    return {
+      dir: isAbsolute(override) ? override : resolve(opts.agentWorkdir, override),
+      scope: 'project',
+    }
+  }
+  return { dir: join(opts.daemonHome, '.pi', 'agent'), scope: 'home' }
+}
+
+/** Install our bundle without replacing an operator's existing Pi extensions. */
+export function installPiExtension(opts: {
+  agentDir: string
+  bundlePath: string
+  /** Project dirs belong to the workspace, so we may create them. ~/.pi is the
+   *  operator's: install into it only if they already use pi. */
+  createMissing?: boolean
+}): InstallPiExtensionResult {
+  if (!opts.createMissing && !existsSync(opts.agentDir)) {
+    return { status: 'skipped', reason: 'no Pi home' }
+  }
+  const target = join(opts.agentDir, 'extensions', 'zooid-tasks.js')
+  mkdirSync(dirname(target), { recursive: true })
+  const source = readFileSync(opts.bundlePath)
+  if (existsSync(target) && readFileSync(target).equals(source)) return { status: 'unchanged', target }
+  writeFileSync(target, source)
+  return { status: 'installed', target }
+}

package/src/push-gateway/gateway.test.ts

@@ -0,0 +1,150 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const sendNotification = vi.fn()
+class WebPushError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number,
+  ) {
+    super(message)
+  }
+}
+vi.mock('web-push', () => ({
+  default: { sendNotification, WebPushError },
+  sendNotification,
+  WebPushError,
+}))
+
+const { pushGateway } = await import('./gateway.js')
+
+const KEYS = { publicKey: 'pub', privateKey: 'priv' }
+
+function device(over: Record<string, unknown> = {}) {
+  return {
+    app_id: 'dev.zooid.web',
+    pushkey: 'BPk_device_one',
+    data: { endpoint: 'https://fcm.example/one', auth: 'auth1' },
+    ...over,
+  }
+}
+
+function notification(devices: unknown[]) {
+  return {
+    notification: {
+      event_id: '$e:example.org',
+      room_id: '!r:example.org',
+      room_name: 'general',
+      sender_display_name: 'Alice',
+      type: 'm.room.message',
+      content: { msgtype: 'm.text', body: 'hello' },
+      counts: { unread: 1 },
+      devices,
+    },
+  }
+}
+
+async function notify(body: unknown) {
+  const app = pushGateway({ keys: KEYS, subject: 'mailto:ops@example.org' })
+  return app.request('/_matrix/push/v1/notify', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+}
+
+beforeEach(() => {
+  sendNotification.mockReset()
+  sendNotification.mockResolvedValue({ statusCode: 201 })
+})
+
+describe('pushGateway', () => {
+  it('encrypts to the device subscription reassembled from pushkey + data', async () => {
+    const res = await notify(notification([device()]))
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ rejected: [] })
+
+    const [subscription, payload, options] = sendNotification.mock.calls[0]!
+    expect(subscription).toEqual({
+      endpoint: 'https://fcm.example/one',
+      keys: { p256dh: 'BPk_device_one', auth: 'auth1' },
+    })
+    expect(JSON.parse(payload as string).room_name).toBe('general')
+    expect((options as { vapidDetails: unknown }).vapidDetails).toEqual({
+      subject: 'mailto:ops@example.org',
+      publicKey: 'pub',
+      privateKey: 'priv',
+    })
+  })
+
+  it('fans out to every matching device', async () => {
+    await notify(
+      notification([
+        device(),
+        device({ pushkey: 'BPk_two', data: { endpoint: 'https://fcm.example/two', auth: 'a2' } }),
+      ]),
+    )
+    expect(sendNotification).toHaveBeenCalledTimes(2)
+  })
+
+  it('skips a foreign app_id silently — never rejects it', async () => {
+    const res = await notify(notification([device({ app_id: 'im.vector.app.ios' })]))
+    expect(sendNotification).not.toHaveBeenCalled()
+    // Rejecting would make the homeserver permanently delete another client's pusher.
+    expect(await res.json()).toEqual({ rejected: [] })
+  })
+
+  it('rejects a pushkey on 410 Gone so the homeserver garbage-collects it', async () => {
+    sendNotification.mockRejectedValueOnce(new WebPushError('gone', 410))
+    const res = await notify(notification([device()]))
+    expect(await res.json()).toEqual({ rejected: ['BPk_device_one'] })
+  })
+
+  it('rejects a pushkey on 404 too', async () => {
+    sendNotification.mockRejectedValueOnce(new WebPushError('not found', 404))
+    expect(await (await notify(notification([device()]))).json()).toEqual({
+      rejected: ['BPk_device_one'],
+    })
+  })
+
+  it('does NOT reject on a transient 429 or 5xx', async () => {
+    sendNotification.mockRejectedValueOnce(new WebPushError('slow down', 429))
+    expect(await (await notify(notification([device()]))).json()).toEqual({ rejected: [] })
+
+    sendNotification.mockRejectedValueOnce(new WebPushError('bad gateway', 502))
+    expect(await (await notify(notification([device()]))).json()).toEqual({ rejected: [] })
+  })
+
+  it('does not let one dead device stop delivery to a live one', async () => {
+    sendNotification
+      .mockRejectedValueOnce(new WebPushError('gone', 410))
+      .mockResolvedValueOnce({ statusCode: 201 })
+    const res = await notify(
+      notification([
+        device(),
+        device({ pushkey: 'BPk_two', data: { endpoint: 'https://fcm.example/two', auth: 'a2' } }),
+      ]),
+    )
+    expect(sendNotification).toHaveBeenCalledTimes(2)
+    expect(await res.json()).toEqual({ rejected: ['BPk_device_one'] })
+  })
+
+  it('skips a device missing endpoint or auth without rejecting it', async () => {
+    const res = await notify(notification([device({ data: { endpoint: 'https://x' } })]))
+    expect(sendNotification).not.toHaveBeenCalled()
+    expect(await res.json()).toEqual({ rejected: [] })
+  })
+
+  it('400s on a malformed body instead of throwing', async () => {
+    expect((await notify({ nope: true })).status).toBe(400)
+  })
+
+  it('logs receipt and outcome — the only way to see a Tuwunel call in the daemon log', async () => {
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    await notify(notification([device()]))
+    expect(log).toHaveBeenCalledWith(
+      expect.stringContaining('notify room=!r:example.org type=m.room.message devices=1'),
+    )
+    expect(log).toHaveBeenCalledWith(expect.stringContaining('delivered=1 rejected=0'))
+    log.mockRestore()
+  })
+})

package/src/push-gateway/gateway.ts

@@ -0,0 +1,78 @@
+import { Hono } from 'hono'
+import webpush from 'web-push'
+import { buildPushPayload, ZOOID_APP_ID } from './payload.js'
+import type { PushNotification } from './types.js'
+import type { VapidKeys } from './vapid.js'
+
+export interface PushGatewayOpts {
+  keys: VapidKeys
+  /** VAPID `sub` claim — a mailto: or https: the push service can complain to. */
+  subject: string
+}
+
+function parseNotifyBody(raw: unknown): PushNotification | null {
+  if (!raw || typeof raw !== 'object') return null
+  const notification = (raw as { notification?: unknown }).notification
+  if (!notification || typeof notification !== 'object') return null
+  const n = notification as Record<string, unknown>
+  if (typeof n.event_id !== 'string' || typeof n.room_id !== 'string' || typeof n.type !== 'string')
+    return null
+  if (!Array.isArray(n.devices)) return null
+  return n as unknown as PushNotification
+}
+
+export function pushGateway(opts: PushGatewayOpts): Hono {
+  const app = new Hono()
+
+  app.post('/_matrix/push/v1/notify', async (c) => {
+    const parsed = parseNotifyBody(await c.req.json().catch(() => null))
+    if (!parsed) {
+      console.warn('[push] notify: malformed body')
+      return c.json({ error: 'malformed notification' }, 400)
+    }
+    // Logged unconditionally: this is the only way to tell "Tuwunel never
+    // called us" (nothing below appears at all — check ip_range_denylist)
+    // apart from "it called us and here's what happened."
+    console.log(
+      `[push] notify room=${parsed.room_id} type=${parsed.type} devices=${parsed.devices.length}`,
+    )
+
+    let delivered = 0
+    const rejected: string[] = []
+    await Promise.all(
+      parsed.devices.map(async (device) => {
+        // An app_id we don't own belongs to some other client sharing this
+        // gateway URL. Skipping is mandatory: naming it in `rejected` makes the
+        // homeserver PERMANENTLY DELETE that client's pusher (spec §4).
+        if (device.app_id !== ZOOID_APP_ID) return
+        const endpoint = device.data?.endpoint
+        const auth = device.data?.auth
+        if (typeof endpoint !== 'string' || typeof auth !== 'string') return
+
+        try {
+          await webpush.sendNotification(
+            { endpoint, keys: { p256dh: device.pushkey, auth } },
+            JSON.stringify(buildPushPayload(parsed, device)),
+            {
+              vapidDetails: { subject: opts.subject, ...opts.keys },
+              TTL: 60 * 60 * 12,
+              urgency: device.tweaks?.sound !== undefined ? 'high' : 'normal',
+            },
+          )
+          delivered++
+        } catch (err) {
+          const status = (err as { statusCode?: number }).statusCode
+          // 404/410 are the ONLY statuses that mean "this device is gone".
+          // 429 and 5xx are transient; rejecting on those deletes live pushers.
+          if (status === 404 || status === 410) rejected.push(device.pushkey)
+          else console.warn(`[push] delivery to ${device.pushkey} failed (${status ?? '?'}):`, err)
+        }
+      }),
+    )
+
+    console.log(`[push] notify done: delivered=${delivered} rejected=${rejected.length}`)
+    return c.json({ rejected })
+  })
+
+  return app
+}

package/src/push-gateway/index.ts

@@ -0,0 +1,17 @@
+import type { Hono } from 'hono'
+import { pushGateway } from './gateway.js'
+import { loadOrCreateVapidKeys } from './vapid.js'
+
+export interface MountPushGatewayOpts {
+  /** Directory the VAPID keypair is persisted under (`<dataDir>/vapid.json`). */
+  dataDir: string
+  /** VAPID `sub` claim — a mailto: or https: the push service can complain to. */
+  subject: string
+}
+
+/** Mount the push gateway's routes onto an existing Hono app. */
+export function mountPushGateway(app: Hono, opts: MountPushGatewayOpts): { publicKey: string } {
+  const keys = loadOrCreateVapidKeys(opts.dataDir)
+  app.route('/', pushGateway({ keys, subject: opts.subject }))
+  return { publicKey: keys.publicKey }
+}

package/src/push-gateway/payload.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import { buildPushPayload, MAX_BODY } from './payload.js'
+import type { PushNotification } from './types.js'
+
+const base: PushNotification = {
+  event_id: '$evt:example.org',
+  room_id: '!room:example.org',
+  room_name: 'general',
+  sender_display_name: 'Alice',
+  type: 'm.room.message',
+  content: { msgtype: 'm.text', body: 'hello there' },
+  counts: { unread: 3 },
+  devices: [],
+}
+
+describe('buildPushPayload', () => {
+  it('carries the fields the service worker renders', () => {
+    expect(buildPushPayload(base)).toEqual({
+      event_id: '$evt:example.org',
+      room_id: '!room:example.org',
+      room_name: 'general',
+      sender_display_name: 'Alice',
+      type: 'm.room.message',
+      body: 'hello there',
+      unread: 3,
+      sound: false,
+    })
+  })
+
+  it("forwards turn.end's last_message as the preview the worker renders", () => {
+    const out = buildPushPayload({
+      ...base,
+      type: 'dev.zooid.turn.end',
+      content: { body: 'claude finished', last_message: 'the deploy is green' },
+    })
+    expect(out.preview).toBe('the deploy is green')
+  })
+
+  it('truncates a long preview too — push payloads are size-capped', () => {
+    const out = buildPushPayload({
+      ...base,
+      type: 'dev.zooid.turn.end',
+      content: { body: 'claude finished', last_message: 'y'.repeat(MAX_BODY + 50) },
+    })
+    expect(out.preview!.length).toBe(MAX_BODY)
+    expect(out.preview!.endsWith('…')).toBe(true)
+  })
+
+  it('omits preview when the event carries no last_message', () => {
+    expect(buildPushPayload(base).preview).toBeUndefined()
+  })
+
+  it('truncates a long body rather than shipping the whole message', () => {
+    const long = 'x'.repeat(MAX_BODY + 50)
+    const out = buildPushPayload({ ...base, content: { msgtype: 'm.text', body: long } })
+    expect(out.body!.length).toBe(MAX_BODY)
+    expect(out.body!.endsWith('…')).toBe(true)
+  })
+
+  it('omits body for an agent event that carries no prose', () => {
+    const out = buildPushPayload({
+      ...base,
+      type: 'dev.zooid.turn.end',
+      content: { produced_output: true },
+    })
+    expect(out.type).toBe('dev.zooid.turn.end')
+    expect(out.body).toBeUndefined()
+  })
+
+  it('sets sound from the push rule tweak, not from the event type', () => {
+    const device = { app_id: 'dev.zooid.web', pushkey: 'pk', tweaks: { sound: 'default' } }
+    const out = buildPushPayload({ ...base, type: 'dev.zooid.turn.end', content: {} }, device)
+    expect(out.sound).toBe(true)
+  })
+
+  it('tolerates a notification with no counts and no display name', () => {
+    const out = buildPushPayload({
+      event_id: '$e',
+      room_id: '!r:example.org',
+      type: 'm.room.message',
+      content: { msgtype: 'm.text', body: 'hi' },
+      devices: [],
+    })
+    expect(out.unread).toBe(0)
+    expect(out.room_name).toBe('!r:example.org')
+    expect(out.sender_display_name).toBeUndefined()
+  })
+})

package/src/push-gateway/payload.ts

@@ -0,0 +1,39 @@
+import type { PushDevice, PushNotification, PushPayload } from './types.js'
+
+export const MAX_BODY = 140
+export const ZOOID_APP_ID = 'dev.zooid.web'
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s
+}
+
+/**
+ * Trim a homeserver notification down to what the service worker renders.
+ *
+ * Full content, not `event_id_only`: rooms are unencrypted, so the homeserver
+ * already holds plaintext and the gateway is ours. `event_id_only` would force
+ * the worker to hold an access token and fetch each event before it could show
+ * anything (spec §7). RFC 8291 means the browser vendor sees ciphertext either
+ * way.
+ */
+export function buildPushPayload(n: PushNotification, device?: PushDevice): PushPayload {
+  const body =
+    typeof n.content?.body === 'string' ? truncate(n.content.body as string, MAX_BODY) : undefined
+  const preview =
+    typeof n.content?.last_message === 'string'
+      ? truncate(n.content.last_message as string, MAX_BODY)
+      : undefined
+  return {
+    event_id: n.event_id,
+    room_id: n.room_id,
+    room_name: n.room_name ?? n.room_id,
+    ...(n.sender_display_name !== undefined ? { sender_display_name: n.sender_display_name } : {}),
+    type: n.type,
+    ...(body !== undefined ? { body } : {}),
+    ...(preview !== undefined ? { preview } : {}),
+    unread: n.counts?.unread ?? 0,
+    // Whether this makes a noise is a push-rule property the server evaluated,
+    // not a second decision made here (spec §12).
+    sound: device?.tweaks?.sound !== undefined,
+  }
+}

package/src/push-gateway/types.ts

@@ -0,0 +1,37 @@
+/** Mirrors the Matrix Push Gateway API notify request body — the subset the gateway reads. */
+
+export interface PushDevice {
+  app_id: string
+  pushkey: string
+  data?: {
+    endpoint?: string
+    auth?: string
+  }
+  tweaks?: {
+    sound?: string
+  }
+}
+
+export interface PushNotification {
+  event_id: string
+  room_id: string
+  room_name?: string
+  sender_display_name?: string
+  type: string
+  content?: Record<string, unknown>
+  counts?: { unread?: number }
+  devices: PushDevice[]
+}
+
+export interface PushPayload {
+  event_id: string
+  room_id: string
+  room_name: string
+  sender_display_name?: string
+  type: string
+  body?: string
+  /** The agent's final message on a turn.end — the prose itself never pushes. */
+  preview?: string
+  unread: number
+  sound: boolean
+}

package/src/push-gateway/vapid.test.ts

@@ -0,0 +1,45 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { loadOrCreateVapidKeys, VAPID_FILENAME } from './vapid.js'
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'zooid-vapid-'))
+})
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+describe('loadOrCreateVapidKeys', () => {
+  it('generates a keypair on first call and persists it', () => {
+    const keys = loadOrCreateVapidKeys(dir)
+    expect(keys.publicKey).toMatch(/^[A-Za-z0-9_-]+$/)
+    expect(keys.privateKey).toMatch(/^[A-Za-z0-9_-]+$/)
+    // base64url-encoded uncompressed P-256 point: 65 bytes → 87 chars
+    expect(keys.publicKey.length).toBe(87)
+
+    const onDisk = JSON.parse(readFileSync(join(dir, VAPID_FILENAME), 'utf8'))
+    expect(onDisk).toEqual({ publicKey: keys.publicKey, privateKey: keys.privateKey })
+  })
+
+  it('is stable across calls — regenerating would invalidate every subscription', () => {
+    const first = loadOrCreateVapidKeys(dir)
+    const second = loadOrCreateVapidKeys(dir)
+    expect(second).toEqual(first)
+  })
+
+  it('creates the directory when it does not exist yet', () => {
+    const nested = join(dir, 'a', 'b')
+    const keys = loadOrCreateVapidKeys(nested)
+    expect(readFileSync(join(nested, VAPID_FILENAME), 'utf8')).toContain(keys.publicKey)
+  })
+
+  it('regenerates rather than throwing when the file is corrupt', () => {
+    writeFileSync(join(dir, VAPID_FILENAME), 'not json')
+    const keys = loadOrCreateVapidKeys(dir)
+    expect(keys.publicKey.length).toBe(87)
+  })
+})

package/src/push-gateway/vapid.ts

@@ -0,0 +1,34 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import webpush from 'web-push'
+
+export const VAPID_FILENAME = 'vapid.json'
+
+export interface VapidKeys {
+  publicKey: string
+  privateKey: string
+}
+
+/**
+ * Load the daemon's VAPID keypair, generating it on first call.
+ *
+ * Regenerating invalidates every existing browser subscription — every device
+ * has to re-enable notifications by hand. It is a one-way door, so this never
+ * regenerates over a readable file; only over a missing or corrupt one, and it
+ * says so on the way past.
+ */
+export function loadOrCreateVapidKeys(dataDir: string): VapidKeys {
+  const path = join(dataDir, VAPID_FILENAME)
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<VapidKeys>
+    if (typeof parsed.publicKey === 'string' && typeof parsed.privateKey === 'string')
+      return { publicKey: parsed.publicKey, privateKey: parsed.privateKey }
+    console.warn(`[push] ${path} is malformed; generating a new VAPID keypair.`)
+  } catch {
+    // Missing file on first start is the normal path — say nothing.
+  }
+  const keys = webpush.generateVAPIDKeys()
+  mkdirSync(dataDir, { recursive: true })
+  writeFileSync(path, JSON.stringify(keys, null, 2), { mode: 0o600 })
+  return keys
+}

package/src/services/tuwunel.ts

@@ -52,9 +52,28 @@ export class TuwunelService {
   async stop(): Promise<void> {
     // Foregrounded container: kill the engine process; --rm cleans up after.
     if (this.child && this.child.exitCode === null) {
-      this.child.kill('SIGTERM')
+      const child = this.child
+      child.kill('SIGTERM')
+      // Bounded: `docker stop` below is the real cleanup and is a no-op if the
+      // container is already gone, so a wedged engine process must not be able
+      // to hang shutdown forever. Measured ~450ms for a healthy Tuwunel.
       await new Promise<void>((resolve) => {
-        this.child!.on('exit', () => resolve())
+        let done = false
+        const finish = (): void => {
+          if (done) return
+          done = true
+          clearTimeout(timer)
+          resolve()
+        }
+        const timer = setTimeout(() => {
+          try {
+            child.kill('SIGKILL')
+          } catch {
+            // already gone
+          }
+          finish()
+        }, 5000)
+        child.once('exit', finish)
       })
     }
     this.child = null