Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(phone): push webhook — create, show once, rotate and revoke from Settings → Phone

review3784cbeb70d1
diff --git a/CLAUDE.md b/CLAUDE.md
index a81a8d718..d3ddde96c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7338,6 +7338,61 @@ does not survive a real canvas. `canvas/camera-moving.test.ts` pins the absence.
being packaged (#575, shipped by #579): without that bundle `pty.attach` spawns a new plain shell
instead of joining the node's session, while `sessionExists` still answers "warm".
+## Push webhook (a script or CI job rings the paired phone)
+
+Settings → Phone → **Push webhook** mints a per-host bearer token; anything that can run `curl`
+then pushes a plain-text notification to the phones relay-paired with this machine
+(`POST https://api.nodeterm.dev/v1/push/webhook`, `{"title","body"}`). Agents already push through
+their hooks; this is for the jobs that have no agent in the loop. The backend half lives in
+nodeterm-server (`src/routes/push-webhook.ts`, `src/lib/host-proof.ts`); the desktop half is
+`core/push-webhook.ts` (client), `shared/push-webhook.ts` (types, copy, the example) and
+`PushWebhookPanel.tsx`. Rules a change must keep:
+
+- **Minting, reading and revoking need the relay host SECRET key, not the public identity.** Every
+ other host-authenticated backend route accepts `(hostDeviceId, hostPublicKeyB64)`, and both are
+ known to every paired phone; for a send that only lets the holder reach phones that already
+ trust the host, but a webhook token is DURABLE — whoever can mint or revoke one can keep a live
+ token or silently cut the owner's CI alerts. So each management call is a challenge: the server
+ answers with an ephemeral X25519 key (derived from its own secret + the challenge, so no state
+ and any instance verifies), and main returns `HMAC-SHA256(X25519(hostSecret, ephemeral),
+ context)` with `context` = domain, challenge, action, host device id. The key never leaves main;
+ a proof for `status` cannot be spent on `revoke`; a challenge lives 5 min and is single-use per
+ process. `webhookProofContext` and the server's `proofContext` are ONE wire contract — change
+ both. `core/push-webhook.test.ts` verifies the desktop's NaCl `scalarMult` proof against Node's
+ own X25519 (the server's primitive), so the two cannot drift silently.
+- **The token is shown ONCE and kept nowhere on this side.** 256 random bits (`ntwh_` + 43
+ base64url), stored server-side only as its SHA-256 (a fast hash is right for a high-entropy
+ token), returned `Cache-Control: no-store`. The panel holds it in component state until "Done";
+ it is never written to settings.json, storage or a log (the panel test asserts local/session
+ storage). There is no "show again" — Rotate mints a new one and revokes the old in one
+ transaction (one live token per host).
+- **The example never puts the token on argv.** `pushWebhookCurlExample` reads
+ `$NODETERM_WEBHOOK_TOKEN` and feeds the header to `curl --config -` through `printf` (a shell
+ builtin), the house rule for every credential we generate. `shared/push-webhook.test.ts` runs the
+ example under a real `/bin/sh` with a recording curl and asserts the token reached stdin and not
+ argv.
+- **The push is labelled and inert.** Subtitle `Webhook · <hostname>`, its own `thread-id`, the
+ phone's existing no-action category `AGENT_DONE`, and an `nt` block with `kind: 'webhook'` and no
+ `nodeId`, so a tap opens the Inbox and nothing else: no Allow/Deny buttons, no deep link, no URL
+ opened. Title is one line (≤ 120 code points), body ≤ 500; C0/C1 controls and `\p{Cf}` (bidi,
+ zero-width) are stripped. nodeterm mobile needs no release for it (read against its push handler:
+ unknown `kind` + no `nodeId` routes to a plain Inbox open).
+- **Budgets:** 10 per minute per token, 60 per hour per HOST (keyed by hostId, so rotating does not
+ reset it), 20 mints per host per day, plus per-IP shields. Fan-out = exactly a host-mode
+ `/v1/push/notify`: this host's live relay pairings with a live APNs registration, minus phones
+ that muted this host.
+- **Relay-paired phones only.** An SSH-granted phone (push grants) has no row the backend can tie to
+ this host, so it does not receive webhook pushes; minting with no live pairing answers
+ `no_paired_phone` and the panel says so.
+- **No canvas-control verb.** An agent already has hook-driven pushes, and a verb would need the
+ desktop to hold the token, which it deliberately does not.
+
+Surfaces: Desktop full. **Server Edition: N/A** — it has no relay host key or paired-phone
+registry (same degrade as `push-notify.ts`); the bridge answers `E_UNSUPPORTED` and the row is
+hidden in a browser tab. IPC is under `pairing:` so `HOST_ONLY_CHANNEL_PREFIXES` keeps it off the
+relay. **Mobile:** no change needed; an iOS follow-up could give `kind: 'webhook'` its own Inbox
+row and tap target.
+
## Hosted team relay (Server Edition as a relay host)
A Server Edition core can host a team over the E2EE relay: a standing listener on the tunnel
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index aab67070c..f7a30ec25 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -676,7 +676,9 @@ working sessions. See `docs/shared-codex-node-identity.md`.
command string. `/proc/<pid>/cmdline` is mode 444 on a stock Linux, and a remote command line is argv
on the host too: we shipped the hook bearer that way and any other account on the machine could read
it and open a terminal running an arbitrary command. Pass secrets by 0600 file or by **stdin**
-(`curl --config -`), and never add an argv fallback. See `docs/node-identity.md`.
+(`curl --config -`), and never add an argv fallback. See `docs/node-identity.md`. That includes the
+examples we SHOW users to copy (the push webhook's curl pipes its header on stdin, and a test runs
+it under `/bin/sh` to prove it): a user pastes what we print into a CI job on a shared runner.
**A hook socket path is not ownership proof.** Never unlink a live listener to bind a hook
socket, or overwrite an advertisement whose socket/TCP listener still answers. Local stale cleanup requires `ECONNREFUSED` and an unchanged socket inode; regular files,
diff --git a/src/core/push-webhook.test.ts b/src/core/push-webhook.test.ts
new file mode 100644
index 000000000..e850d408e
--- /dev/null
+++ b/src/core/push-webhook.test.ts
@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest'
+import crypto from 'node:crypto'
+import nacl from 'tweetnacl'
+import { createPushWebhookClient, webhookProofContext, type PushWebhookHost } from './push-webhook'
+
+// A stand-in for the backend's verifier, written against Node's X25519 (the server's primitive) so
+// the test proves the desktop's NaCl `scalarMult` proof interoperates with it — not merely that the
+// client agrees with itself.
+const PKCS8 = Buffer.from('302e020100300506032b656e04220420', 'hex')
+const SPKI = Buffer.from('302a300506032b656e032100', 'hex')
+const priv = (raw: Buffer) => crypto.createPrivateKey({ key: Buffer.concat([PKCS8, raw]), format: 'der', type: 'pkcs8' })
+const pub = (raw: Buffer) => crypto.createPublicKey({ key: Buffer.concat([SPKI, raw]), format: 'der', type: 'spki' })
+const rawPub = (k: crypto.KeyObject) => (k.export({ type: 'spki', format: 'der' }) as Buffer).subarray(12)
+
+function fakeServer(opts: { paired?: boolean; status?: number } = {}) {
+ const eph = new Map<string, Buffer>()
+ const calls: Array<{ path: string; body: any }> = []
+ const verified: string[] = []
+ const f = async (url: string, init: { body: string }) => {
+ const path = new URL(url).pathname
+ const body = JSON.parse(init.body)
+ calls.push({ path, body })
+ const respond = (status: number, json: unknown) =>
+ ({ status, json: async () => json }) as unknown as Response
+ if (path === '/v1/push/webhook/challenge') {
+ const challenge = `${Date.now()}.${crypto.randomBytes(16).toString('base64url')}`
+ const raw = crypto.randomBytes(32)
+ eph.set(challenge, raw)
+ return respond(200, { challenge, serverPublicKeyB64: rawPub(crypto.createPublicKey(priv(raw))).toString('base64') })
+ }
+ if (opts.status) return respond(opts.status, { error: 'x' })
+ const action = path.endsWith('/token') ? 'mint' : path.endsWith('/status') ? 'status' : 'revoke'
+ const shared = crypto.diffieHellman({
+ privateKey: priv(eph.get(body.challenge)!),
+ publicKey: pub(Buffer.from(body.hostPublicKeyB64, 'base64'))
+ })
+ const expected = crypto.createHmac('sha256', shared).update(webhookProofContext(body.challenge, action, body.hostDeviceId)).digest('base64')
+ if (expected !== body.proof) return respond(403, { error: 'forbidden' })
+ verified.push(action)
+ if (action === 'mint') {
+ if (opts.paired === false) return respond(409, { error: 'no_paired_phone' })
+ return respond(200, { token: 'ntwh_' + 'a'.repeat(43), tokenId: 't1', tokenPrefix: 'ntwh_aaaa', createdAt: '2026-09-30T00:00:00.000Z' })
+ }
+ if (action === 'status') return respond(200, { token: null })
+ return respond(200, { ok: true })
+ }
+ return { fetch: f as unknown as typeof fetch, calls, verified }
+}
+
+const kp = nacl.box.keyPair()
+const host: PushWebhookHost = { hostDeviceId: 'desk-1', publicKey: kp.publicKey, secretKey: kp.secretKey, label: 'mac-mini' }
+
+function client(server: ReturnType<typeof fakeServer>, over: Partial<Parameters<typeof createPushWebhookClient>[0]> = {}) {
+ return createPushWebhookClient({
+ fetch: server.fetch,
+ apiBase: 'https://api.test',
+ loadHost: async () => host,
+ isPackaged: () => true,
+ env: {},
+ ...over
+ })
+}
+
+describe('push webhook client', () => {
+ it('proves possession of the host secret key in a form the server’s X25519 accepts', async () => {
+ const s = fakeServer()
+ const c = client(s)
+ const minted = await c.mint()
+ expect(minted).toEqual({
+ ok: true,
+ value: { token: 'ntwh_' + 'a'.repeat(43), tokenId: 't1', tokenPrefix: 'ntwh_aaaa', createdAt: '2026-09-30T00:00:00.000Z', lastUsedAt: null }
+ })
+ expect(await c.status()).toEqual({ ok: true, value: null })
+ expect(await c.revoke()).toEqual({ ok: true, value: true })
+ expect(s.verified).toEqual(['mint', 'status', 'revoke'])
+ // The secret key never goes on the wire.
+ expect(JSON.stringify(s.calls)).not.toContain(Buffer.from(kp.secretKey).toString('base64'))
+ // The label rides only on the mint.
+ expect(s.calls.find((c) => c.path.endsWith('/token'))!.body.label).toBe('mac-mini')
+ expect(s.calls.find((c) => c.path.endsWith('/status'))!.body.label).toBeUndefined()
+ })
+
+ it('a proof made with another key is refused', async () => {
+ const s = fakeServer()
+ const other = nacl.box.keyPair()
+ const c = client(s, { loadHost: async () => ({ ...host, secretKey: other.secretKey }) })
+ expect(await c.mint()).toEqual({ ok: false, error: 'refused' })
+ })
+
+ it('maps each failure to its own reason', async () => {
+ expect(await client(fakeServer({ paired: false })).mint()).toEqual({ ok: false, error: 'no-paired-phone' })
+ expect(await client(fakeServer({ status: 429 })).status()).toEqual({ ok: false, error: 'rate-limited' })
+ expect(await client(fakeServer({ status: 502 })).status()).toEqual({ ok: false, error: 'unreachable' })
+ const throwing = createPushWebhookClient({
+ fetch: (async () => { throw new Error('offline') }) as unknown as typeof fetch,
+ apiBase: 'https://api.test',
+ loadHost: async () => host,
+ isPackaged: () => true
+ })
+ expect(await throwing.status()).toEqual({ ok: false, error: 'unreachable' })
+ const locked = client(fakeServer(), { loadHost: async () => { throw new Error('locked') } })
+ expect(await locked.mint()).toEqual({ ok: false, error: 'no-host-key' })
+ })
+
+ it('an unpackaged build without an API override calls nothing', async () => {
+ const s = fakeServer()
+ const c = createPushWebhookClient({ fetch: s.fetch, loadHost: async () => host, isPackaged: () => false, env: {} })
+ expect(await c.status()).toEqual({ ok: false, error: 'dev-build' })
+ expect(s.calls).toHaveLength(0)
+ })
+})
diff --git a/src/core/push-webhook.ts b/src/core/push-webhook.ts
new file mode 100644
index 000000000..1908deced
--- /dev/null
+++ b/src/core/push-webhook.ts
@@ -0,0 +1,174 @@
+// Desktop client for the push webhook's management routes (mint / status / revoke).
+//
+// The backend accepts these only from the holder of this machine's relay host SECRET key, proved
+// per request without the key leaving this process: the server answers a challenge with an
+// ephemeral X25519 public key, and we return HMAC-SHA256(X25519(hostSecret, ephemeral), context),
+// where context binds the challenge, the action and our device id. The public identity
+// (hostDeviceId + host public key) is known to every paired phone, so it is deliberately NOT
+// enough on its own to mint, read or revoke a durable credential.
+//
+// The context string is the wire contract with nodeterm-server's `src/lib/host-proof.ts`
+// (`proofContext`). Change one, change both.
+//
+// Electron-free (core): the desktop wires it with the relay host key. The Server Edition has no
+// relay host identity and no paired-phone registry, so it does not construct this (its bridge
+// answers E_UNSUPPORTED and the Settings row is hidden) — the same degrade as `push-notify.ts`.
+
+import { createHmac } from 'node:crypto'
+import nacl from 'tweetnacl'
+import {
+ PUSH_WEBHOOK_DEFAULT_API_BASE,
+ type PushWebhookApi,
+ type PushWebhookError,
+ type PushWebhookMinted,
+ type PushWebhookResult,
+ type PushWebhookTokenInfo
+} from '../shared/push-webhook'
+
+const FETCH_TIMEOUT_MS = 10_000
+const PROOF_DOMAIN = 'nodeterm-push-webhook-proof-v1'
+
+export type PushWebhookAction = 'mint' | 'status' | 'revoke'
+
+export interface PushWebhookHost {
+ hostDeviceId: string
+ publicKey: Uint8Array
+ secretKey: Uint8Array
+ /** Shown on the phone as "Webhook · <label>". */
+ label: string
+}
+
+export interface PushWebhookClientDeps {
+ fetch?: typeof fetch
+ apiBase?: string
+ /** Throws when the key cannot be read (keyring locked). */
+ loadHost: () => Promise<PushWebhookHost>
+ /** false ⇒ the call is refused as 'dev-build' unless an api base override is configured. */
+ isPackaged: () => boolean
+ env?: Record<string, string | undefined>
+}
+
+export function webhookProofContext(challenge: string, action: PushWebhookAction, hostDeviceId: string): string {
+ return `${PROOF_DOMAIN}\n${challenge}\n${action}\n${hostDeviceId}`
+}
+
+/** HMAC over the X25519 shared secret. `scalarMult` is raw X25519 — the same function the server
+ * runs with Node's `diffieHellman`. */
+export function webhookProof(input: {
+ secretKey: Uint8Array
+ serverPublicKeyB64: string
+ challenge: string
+ action: PushWebhookAction
+ hostDeviceId: string
+}): string {
+ const serverPub = Uint8Array.from(Buffer.from(input.serverPublicKeyB64, 'base64'))
+ if (serverPub.length !== 32) throw new Error('bad server key')
+ const shared = nacl.scalarMult(input.secretKey, serverPub)
+ return createHmac('sha256', Buffer.from(shared))
+ .update(webhookProofContext(input.challenge, input.action, input.hostDeviceId))
+ .digest('base64')
+}
+
+function isTokenInfo(v: unknown): v is PushWebhookTokenInfo {
+ if (!v || typeof v !== 'object') return false
+ const o = v as Record<string, unknown>
+ return (
+ typeof o.tokenId === 'string' &&
+ typeof o.tokenPrefix === 'string' &&
+ typeof o.createdAt === 'string' &&
+ (o.lastUsedAt === null || typeof o.lastUsedAt === 'string')
+ )
+}
+
+function errorFor(status: number, body: unknown): PushWebhookError {
+ const code = body && typeof body === 'object' ? (body as { error?: unknown }).error : undefined
+ if (status === 409 && code === 'no_paired_phone') return 'no-paired-phone'
+ if (status === 403) return 'refused'
+ if (status === 429) return 'rate-limited'
+ return 'unreachable'
+}
+
+export function createPushWebhookClient(deps: PushWebhookClientDeps): PushWebhookApi {
+ const env = deps.env ?? process.env
+ const fetchImpl = deps.fetch ?? fetch
+ const apiBase = (deps.apiBase ?? env.NODETERM_API_BASE ?? PUSH_WEBHOOK_DEFAULT_API_BASE).replace(/\/+$/, '')
+
+ async function postJson(path: string, body: unknown): Promise<{ status: number; json: unknown } | null> {
+ const ctrl = new AbortController()
+ const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS)
+ try {
+ const res = await fetchImpl(apiBase + path, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify(body),
+ signal: ctrl.signal
+ })
+ const json = await res.json().catch(() => null)
+ return { status: res.status, json }
+ } catch {
+ return null
+ } finally {
+ clearTimeout(timer)
+ }
+ }
+
+ async function call(action: PushWebhookAction, path: string): Promise<PushWebhookResult<unknown>> {
+ if (!deps.isPackaged() && !env.NODETERM_API_BASE && !deps.apiBase) return { ok: false, error: 'dev-build' }
+ let host: PushWebhookHost
+ try {
+ host = await deps.loadHost()
+ } catch {
+ return { ok: false, error: 'no-host-key' }
+ }
+ const ch = await postJson('/v1/push/webhook/challenge', {})
+ if (!ch || ch.status !== 200) return { ok: false, error: ch ? errorFor(ch.status, ch.json) : 'unreachable' }
+ const { challenge, serverPublicKeyB64 } = (ch.json ?? {}) as { challenge?: unknown; serverPublicKeyB64?: unknown }
+ if (typeof challenge !== 'string' || typeof serverPublicKeyB64 !== 'string') return { ok: false, error: 'unreachable' }
+ let proof: string
+ try {
+ proof = webhookProof({ secretKey: host.secretKey, serverPublicKeyB64, challenge, action, hostDeviceId: host.hostDeviceId })
+ } catch {
+ return { ok: false, error: 'unreachable' }
+ }
+ const res = await postJson(path, {
+ hostDeviceId: host.hostDeviceId,
+ hostPublicKeyB64: Buffer.from(host.publicKey).toString('base64'),
+ challenge,
+ proof,
+ ...(action === 'mint' ? { label: host.label } : {})
+ })
+ if (!res) return { ok: false, error: 'unreachable' }
+ if (res.status !== 200) return { ok: false, error: errorFor(res.status, res.json) }
+ return { ok: true, value: res.json }
+ }
+
+ return {
+ async status() {
+ const r = await call('status', '/v1/push/webhook/status')
+ if (!r.ok) return r
+ const t = (r.value as { token?: unknown } | null)?.token
+ if (t === null) return { ok: true, value: null }
+ return isTokenInfo(t) ? { ok: true, value: t } : { ok: false, error: 'unreachable' }
+ },
+ async mint() {
+ const r = await call('mint', '/v1/push/webhook/token')
+ if (!r.ok) return r
+ const v = r.value as Record<string, unknown> | null
+ if (!v || typeof v.token !== 'string' || typeof v.tokenId !== 'string' || typeof v.createdAt !== 'string') {
+ return { ok: false, error: 'unreachable' }
+ }
+ const minted: PushWebhookMinted = {
+ token: v.token,
+ tokenId: v.tokenId,
+ tokenPrefix: typeof v.tokenPrefix === 'string' ? v.tokenPrefix : v.token.slice(0, 9),
+ createdAt: v.createdAt,
+ lastUsedAt: null
+ }
+ return { ok: true, value: minted }
+ },
+ async revoke() {
+ const r = await call('revoke', '/v1/push/webhook/revoke')
+ return r.ok ? { ok: true, value: true } : r
+ }
+ }
+}
diff --git a/src/main/index.ts b/src/main/index.ts
index de78adbea..19fd015f3 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -235,6 +235,8 @@ import { createMemoryPressureMonitor } from '../core/memory-pressure'
import { createPtyPressureMonitor } from '../core/pty-pressure'
import { registerPtmxLimitHandler } from './ptmx-limit'
import { getDeviceId } from '../core/device-id'
+import { createPushWebhookClient } from '../core/push-webhook'
+import { PUSH_WEBHOOK_DEFAULT_API_BASE } from '../shared/push-webhook'
import { initRemoteStatusPush } from './remote-ssh/remote-status-push'
import { initCanvasSync } from '../core/canvas-sync'
import { retainUntilDismissed } from './notifications'
@@ -1752,6 +1754,20 @@ app.whenReady().then(async () => {
})
ipcMain.handle(IPC.pairingListDevices, () => pairingService.listDevices())
ipcMain.handle(IPC.pairingRevokeDevice, (_e, id: string) => pairingService.revokeDevice(id))
+ // Push webhook management. The proof of ownership is made HERE with the relay host secret key,
+ // which never reaches the renderer; the minted token passes through to it exactly once and is
+ // not kept by this process (core/push-webhook.ts).
+ const pushWebhook = createPushWebhookClient({
+ isPackaged: () => app.isPackaged,
+ loadHost: async () => {
+ const kp = await loadOrCreateKeyPair()
+ return { hostDeviceId: getDeviceId(), publicKey: kp.publicKey, secretKey: kp.secretKey, label: hostname() }
+ }
+ })
+ ipcMain.handle(IPC.pairingWebhookStatus, () => pushWebhook.status())
+ ipcMain.handle(IPC.pairingWebhookMint, () => pushWebhook.mint())
+ ipcMain.handle(IPC.pairingWebhookRevoke, () => pushWebhook.revoke())
+ ipcMain.handle(IPC.pairingWebhookEndpoint, () => process.env.NODETERM_API_BASE || PUSH_WEBHOOK_DEFAULT_API_BASE)
// Revoking a bridged PEER must CUT THE LIVE SESSION, not just unpin it (revocation.ts): unpinning
// refuses only the NEXT handshake, while the open relay socket keeps full shell access — "the
diff --git a/src/preload/index.ts b/src/preload/index.ts
index c37047a4e..f9ea8cbce 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -694,7 +694,11 @@ const api: NodeTerminalApi = {
probeSsh: () => ipcRenderer.invoke(IPC.pairingProbeSsh),
openRemoteLoginSettings: () => ipcRenderer.invoke(IPC.pairingOpenRemoteLoginSettings),
listDevices: () => ipcRenderer.invoke(IPC.pairingListDevices),
- revokeDevice: (id) => ipcRenderer.invoke(IPC.pairingRevokeDevice, id)
+ revokeDevice: (id) => ipcRenderer.invoke(IPC.pairingRevokeDevice, id),
+ webhookStatus: () => ipcRenderer.invoke(IPC.pairingWebhookStatus),
+ webhookMint: () => ipcRenderer.invoke(IPC.pairingWebhookMint),
+ webhookRevoke: () => ipcRenderer.invoke(IPC.pairingWebhookRevoke),
+ webhookEndpoint: () => ipcRenderer.invoke(IPC.pairingWebhookEndpoint)
},
// Team presence. `hello` is the only request (its response is how this client learns its OWN
// ClientId, without which it would draw its own cursor as a peer's); the publishers are
diff --git a/src/renderer/bridge/stubs.ts b/src/renderer/bridge/stubs.ts
index 2befe0138..13ca2447b 100644
--- a/src/renderer/bridge/stubs.ts
+++ b/src/renderer/bridge/stubs.ts
@@ -467,7 +467,13 @@ export function buildStubApi(): Omit<
probeSsh: U('pairing.probeSsh'),
openRemoteLoginSettings: U('pairing.openRemoteLoginSettings'),
listDevices: U('pairing.listDevices'),
- revokeDevice: U('pairing.revokeDevice')
+ revokeDevice: U('pairing.revokeDevice'),
+ // The Server Edition has no relay host key and no paired-phone registry, so it cannot own a
+ // push webhook (same degrade as push-notify). The Settings row is hidden in the browser.
+ webhookStatus: U('pairing.webhookStatus'),
+ webhookMint: U('pairing.webhookMint'),
+ webhookRevoke: U('pairing.webhookRevoke'),
+ webhookEndpoint: U('pairing.webhookEndpoint')
},
shortcuts: {
// Deliberate no-op (not a gap): the recording bit exists to stand the DESKTOP's
diff --git a/src/renderer/components/settings/sections/PhoneSection.revoke.test.tsx b/src/renderer/components/settings/sections/PhoneSection.revoke.test.tsx
index ccc8c9df7..c9622e9b7 100644
--- a/src/renderer/components/settings/sections/PhoneSection.revoke.test.tsx
+++ b/src/renderer/components/settings/sections/PhoneSection.revoke.test.tsx
@@ -51,7 +51,10 @@ function stubBridge(result: DeviceRevokeResult | Error): void {
probeSsh: vi.fn(async () => true),
openRemoteLoginSettings: vi.fn(),
listDevices: vi.fn(async () => devices),
- revokeDevice
+ revokeDevice,
+ // The push webhook row mounts in this section too; no token is live here.
+ webhookStatus: vi.fn(async () => ({ ok: true, value: null })),
+ webhookEndpoint: vi.fn(async () => 'https://api.test')
},
remoteHost: { setPhoneAccess: vi.fn() },
shell: { openExternal: vi.fn() }
diff --git a/src/renderer/components/settings/sections/PhoneSection.tsx b/src/renderer/components/settings/sections/PhoneSection.tsx
index 9f9d4480f..673dc6237 100644
--- a/src/renderer/components/settings/sections/PhoneSection.tsx
+++ b/src/renderer/components/settings/sections/PhoneSection.tsx
@@ -16,6 +16,8 @@ import {
relayOnlyExplanation
} from '@shared/pairing-gate'
import { thisMachine } from '../../../lib/machineName'
+import { isBrowserRuntime } from '@renderer/bridge/runtime'
+import { PushWebhookPanel } from './PushWebhookPanel'
const ROWS = {
remote: {
@@ -29,9 +31,17 @@ const ROWS = {
devices: {
title: 'Paired devices',
keywords: ['phone', 'device', 'devices', 'paired', 'revoke', 'ios', 'iphone', 'remove']
+ },
+ webhook: {
+ title: 'Push webhook',
+ keywords: ['webhook', 'push', 'notification', 'notify', 'ci', 'build', 'script', 'curl', 'token']
}
}
const ENTRIES = Object.values(ROWS)
+// The webhook needs this machine's relay host key, which a browser tab on the Server Edition does
+// not have (its bridge answers E_UNSUPPORTED) — so the row and its search entry are desktop-only.
+// Asked at render, not at import: the boot switch marks the browser runtime after modules load.
+const BROWSER_ENTRIES = ENTRIES.filter((r) => r !== ROWS.webhook)
/** Format an epoch-ms pairing time as a short local date. */
function formatPairedAt(ms: number): string {
@@ -55,6 +65,7 @@ export function PhoneSection({ isActive }: { isActive: boolean }): React.JSX.Ele
// in the warning colour would read as a failure.
const [revokeNote, setRevokeNote] = useState<{ text: string; warn: boolean } | null>(null)
+ const showWebhook = !isBrowserRuntime()
const phoneAccessEnabled = useSettings((s) => s.settings.phoneAccessEnabled)
const updateSettings = useSettings((s) => s.update)
@@ -171,7 +182,7 @@ export function PhoneSection({ isActive }: { isActive: boolean }): React.JSX.Ele
title="Phone"
description="Pair the nodeterm iOS app so it can connect to this machine over your local network — no terminal commands needed."
isActive={isActive}
- searchEntries={ENTRIES}
+ searchEntries={showWebhook ? ENTRIES : BROWSER_ENTRIES}
>
<SearchableRow {...ROWS.remote}>
<div className="space-y-3">
@@ -390,6 +401,12 @@ export function PhoneSection({ isActive }: { isActive: boolean }): React.JSX.Ele
</div>
</SearchableRow>
+ {showWebhook ? (
+ <SearchableRow {...ROWS.webhook}>
+ <PushWebhookPanel />
+ </SearchableRow>
+ ) : null}
+
{pendingRevoke ? (
<ConfirmDialog
// Both legs, and the timing of the one that is not instant. "If" rather than a flat
diff --git a/src/renderer/components/settings/sections/PhoneSection.windows.test.tsx b/src/renderer/components/settings/sections/PhoneSection.windows.test.tsx
index 562ff2a83..8824f2670 100644
--- a/src/renderer/components/settings/sections/PhoneSection.windows.test.tsx
+++ b/src/renderer/components/settings/sections/PhoneSection.windows.test.tsx
@@ -30,7 +30,10 @@ function stubBridge(start: Record<string, unknown>): void {
probeSsh: vi.fn(async () => false),
openRemoteLoginSettings: vi.fn(),
listDevices: vi.fn(async () => []),
- revokeDevice: vi.fn()
+ revokeDevice: vi.fn(),
+ // The push webhook row mounts in this section too; no token is live here.
+ webhookStatus: vi.fn(async () => ({ ok: true, value: null })),
+ webhookEndpoint: vi.fn(async () => 'https://api.test')
},
remoteHost: { setPhoneAccess: vi.fn() },
shell: { openExternal: vi.fn() }
diff --git a/src/renderer/components/settings/sections/PushWebhookPanel.test.tsx b/src/renderer/components/settings/sections/PushWebhookPanel.test.tsx
new file mode 100644
index 000000000..6753059bb
--- /dev/null
+++ b/src/renderer/components/settings/sections/PushWebhookPanel.test.tsx
@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { createRoot, type Root } from 'react-dom/client'
+import { act } from 'react'
+import { PushWebhookPanel } from './PushWebhookPanel'
+import type { PushWebhookResult, PushWebhookTokenInfo, PushWebhookMinted } from '@shared/push-webhook'
+
+const TOKEN = 'ntwh_' + 'Z'.repeat(43)
+const INFO: PushWebhookTokenInfo = {
+ tokenId: 't1',
+ tokenPrefix: 'ntwh_ZZZZ',
+ createdAt: '2026-09-30T10:00:00.000Z',
+ lastUsedAt: null
+}
+
+let status: () => Promise<PushWebhookResult<PushWebhookTokenInfo | null>>
+let mint: () => Promise<PushWebhookResult<PushWebhookMinted>>
+let revoke: () => Promise<PushWebhookResult<true>>
+const writeText = vi.fn()
+
+let host: HTMLElement
+let root: Root
+
+async function render(): Promise<void> {
+ host = document.createElement('div')
+ document.body.appendChild(host)
+ root = createRoot(host)
+ await act(async () => {
+ root.render(<PushWebhookPanel />)
+ })
+}
+
+const button = (label: string): HTMLButtonElement =>
+ Array.from(document.body.querySelectorAll('button')).find((b) => b.textContent === label) as HTMLButtonElement
+
+async function click(label: string): Promise<void> {
+ const b = button(label)
+ expect(b, `button "${label}"`).toBeTruthy()
+ await act(async () => {
+ b.click()
+ })
+}
+
+beforeEach(() => {
+ status = vi.fn(async () => ({ ok: true as const, value: null }))
+ mint = vi.fn(async () => ({ ok: true as const, value: { ...INFO, token: TOKEN } }))
+ revoke = vi.fn(async () => ({ ok: true as const, value: true as const }))
+ writeText.mockReset()
+ ;(window as unknown as { nodeTerminal: unknown }).nodeTerminal = {
+ pairing: {
+ webhookStatus: () => status(),
+ webhookMint: () => mint(),
+ webhookRevoke: () => revoke(),
+ webhookEndpoint: async () => 'https://api.test'
+ },
+ clipboard: { writeText }
+ }
+})
+
+afterEach(() => {
+ act(() => root.unmount())
+ host.remove()
+ document.body.innerHTML = ''
+})
+
+describe('PushWebhookPanel', () => {
+ it('shows the minted token once, copies it, and forgets it on Done', async () => {
+ await render()
+ await click('Create webhook token')
+ expect(host.textContent).toContain(TOKEN)
+ expect(host.textContent).toContain('won’t be shown again')
+ await click('Copy')
+ expect(writeText).toHaveBeenCalledWith(TOKEN)
+
+ // The example never embeds the token — it reads the env var and pipes the header on stdin.
+ const pre = host.querySelector('pre')!.textContent!
+ expect(pre).not.toContain(TOKEN)
+ expect(pre).toContain('https://api.test/v1/push/webhook')
+ expect(pre).toContain('--config -')
+
+ await click('Done')
+ expect(document.body.innerHTML).not.toContain(TOKEN)
+ expect(host.textContent).toContain('ntwh_ZZZZ…')
+ // Nothing kept it: not local storage, not session storage.
+ expect(JSON.stringify({ ...localStorage })).not.toContain(TOKEN)
+ expect(JSON.stringify({ ...sessionStorage })).not.toContain(TOKEN)
+ })
+
+ it('lists the live token with its last use, and revokes after confirming', async () => {
+ status = async () => ({ ok: true, value: { ...INFO, lastUsedAt: '2026-09-30T11:00:00.000Z' } })
+ await render()
+ expect(host.textContent).toContain('ntwh_ZZZZ…')
+ expect(host.textContent).not.toContain('Last used never')
+ await click('Revoke')
+ expect(revoke).not.toHaveBeenCalled() // confirm first
+ const confirmBtn = Array.from(document.body.querySelectorAll('button')).filter((b) => b.textContent === 'Revoke').pop()!
+ await act(async () => {
+ confirmBtn.click()
+ })
+ expect(revoke).toHaveBeenCalledOnce()
+ expect(button('Create webhook token')).toBeTruthy()
+ })
+
+ it('rotate mints a new token only after confirming', async () => {
+ status = async () => ({ ok: true, value: INFO })
+ await render()
+ await click('Rotate')
+ expect(mint).not.toHaveBeenCalled()
+ const confirmBtn = Array.from(document.body.querySelectorAll('button')).filter((b) => b.textContent === 'Rotate').pop()!
+ await act(async () => {
+ confirmBtn.click()
+ })
+ expect(mint).toHaveBeenCalledOnce()
+ expect(host.textContent).toContain(TOKEN)
+ })
+
+ it('says why when a mint is refused', async () => {
+ mint = async () => ({ ok: false, error: 'no-paired-phone' })
+ await render()
+ await click('Create webhook token')
+ expect(host.textContent).toContain('Pair a phone with remote access first')
+ })
+})
diff --git a/src/renderer/components/settings/sections/PushWebhookPanel.tsx b/src/renderer/components/settings/sections/PushWebhookPanel.tsx
new file mode 100644
index 000000000..3b794c007
--- /dev/null
+++ b/src/renderer/components/settings/sections/PushWebhookPanel.tsx
@@ -0,0 +1,212 @@
+import { useCallback, useEffect, useState } from 'react'
+import { Button } from '@renderer/ui/Button'
+import { ConfirmDialog } from '../../ConfirmDialog'
+import {
+ PUSH_WEBHOOK_BODY_MAX,
+ PUSH_WEBHOOK_TITLE_MAX,
+ PUSH_WEBHOOK_TOKEN_ENV,
+ pushWebhookCurlExample,
+ pushWebhookErrorText,
+ type PushWebhookError,
+ type PushWebhookTokenInfo
+} from '@shared/push-webhook'
+
+function formatWhen(iso: string | null): string {
+ if (!iso) return 'never'
+ const t = Date.parse(iso)
+ if (!Number.isFinite(t)) return 'unknown'
+ return new Date(t).toLocaleString(undefined, {
+ year: 'numeric',
+ month: 'short',
+ day: 'numeric',
+ hour: '2-digit',
+ minute: '2-digit'
+ })
+}
+
+/**
+ * Settings → Phone → Push webhook. A script or CI job POSTs to one URL with a bearer token and the
+ * paired phone rings. The token is shown exactly once, right after it is minted, and held only in
+ * this component's state until the user dismisses it — it is never written to settings, storage
+ * or logs (the backend keeps only its hash, and there is no way to show it again: rotate instead).
+ */
+export function PushWebhookPanel(): React.JSX.Element {
+ const api = window.nodeTerminal.pairing
+ const [loading, setLoading] = useState(true)
+ const [info, setInfo] = useState<PushWebhookTokenInfo | null>(null)
+ const [error, setError] = useState<PushWebhookError | null>(null)
+ const [busy, setBusy] = useState(false)
+ const [revealed, setRevealed] = useState<string | null>(null)
+ const [copied, setCopied] = useState<'token' | 'example' | null>(null)
+ const [confirm, setConfirm] = useState<'rotate' | 'revoke' | null>(null)
+ const [endpoint, setEndpoint] = useState<string | undefined>(undefined)
+
+ const refresh = useCallback(async (): Promise<void> => {
+ try {
+ const r = await api.webhookStatus()
+ if (r.ok) {
+ setInfo(r.value)
+ setError(null)
+ } else setError(r.error)
+ } catch {
+ setError('unreachable')
+ } finally {
+ setLoading(false)
+ }
+ }, [api])
+
+ useEffect(() => {
+ void refresh()
+ api.webhookEndpoint().then(setEndpoint, () => undefined)
+ }, [api, refresh])
+
+ const mint = async (): Promise<void> => {
+ setConfirm(null)
+ setBusy(true)
+ setCopied(null)
+ try {
+ const r = await api.webhookMint()
+ if (r.ok) {
+ const { token, ...rest } = r.value
+ setRevealed(token)
+ setInfo(rest)
+ setError(null)
+ } else setError(r.error)
+ } catch {
+ setError('unreachable')
+ } finally {
+ setBusy(false)
+ }
+ }
+
+ const revoke = async (): Promise<void> => {
+ setConfirm(null)
+ setBusy(true)
+ try {
+ const r = await api.webhookRevoke()
+ if (r.ok) {
+ setInfo(null)
+ setRevealed(null)
+ setError(null)
+ } else setError(r.error)
+ } catch {
+ setError('unreachable')
+ } finally {
+ setBusy(false)
+ }
+ }
+
+ const copy = (text: string, what: 'token' | 'example'): void => {
+ window.nodeTerminal.clipboard.writeText(text)
+ setCopied(what)
+ }
+
+ const example = pushWebhookCurlExample(endpoint)
+
+ return (
+ <div className="space-y-3">
+ <h4 className="text-[13px] font-medium text-text">Push webhook</h4>
+ <p className="text-sm text-muted">
+ Let a script, a CI job or a long build ring your phone when it finishes. It sends a plain
+ text notification to the phones paired with this machine, marked as coming from a webhook —
+ not from an agent. Title up to {PUSH_WEBHOOK_TITLE_MAX} characters, body up to{' '}
+ {PUSH_WEBHOOK_BODY_MAX}; links are not opened.
+ </p>
+
+ {loading ? <p className="text-sm text-muted">Checking…</p> : null}
+
+ {revealed ? (
+ <div
+ className="space-y-2 rounded-md border border-border px-3 py-2"
+ data-testid="webhook-token-reveal"
+ >
+ <p className="text-sm font-medium text-text">
+ Copy this token now — it won’t be shown again.
+ </p>
+ <div className="flex items-center gap-2">
+ <code className="min-w-0 flex-1 truncate rounded bg-bg px-2 py-1 font-mono text-[12px] text-text">
+ {revealed}
+ </code>
+ <Button onClick={() => copy(revealed, 'token')}>
+ {copied === 'token' ? 'Copied' : 'Copy'}
+ </Button>
+ </div>
+ <p className="text-xs text-muted">
+ Store it as a secret named <code>{PUSH_WEBHOOK_TOKEN_ENV}</code> in your CI or shell
+ environment. Anyone with it can send notifications to your phone.
+ </p>
+ <Button onClick={() => setRevealed(null)}>Done</Button>
+ </div>
+ ) : null}
+
+ {!loading && !revealed ? (
+ info ? (
+ <div className="flex items-center justify-between gap-3 rounded-md border border-border px-3 py-2">
+ <div className="min-w-0">
+ <div className="truncate font-mono text-sm text-text">{info.tokenPrefix}…</div>
+ <div className="text-[12px] text-muted">
+ Created {formatWhen(info.createdAt)} · Last used {formatWhen(info.lastUsedAt)}
+ </div>
+ </div>
+ <div className="flex shrink-0 gap-2">
+ <Button disabled={busy} onClick={() => setConfirm('rotate')}>
+ Rotate
+ </Button>
+ <Button disabled={busy} onClick={() => setConfirm('revoke')}>
+ Revoke
+ </Button>
+ </div>
+ </div>
+ ) : error === null ? (
+ <Button variant="primary" disabled={busy} onClick={() => void mint()}>
+ {busy ? 'Creating…' : 'Create webhook token'}
+ </Button>
+ ) : null
+ ) : null}
+
+ {error ? (
+ <div className="space-y-2">
+ <p className="text-sm" style={{ color: 'var(--warn)' }}>
+ {pushWebhookErrorText(error)}
+ </p>
+ <Button disabled={busy} onClick={() => void refresh()}>
+ Retry
+ </Button>
+ </div>
+ ) : null}
+
+ {info || revealed ? (
+ <div className="space-y-1">
+ <div className="flex items-center justify-between gap-2">
+ <span className="text-xs text-muted">Example (reads the token from ${PUSH_WEBHOOK_TOKEN_ENV})</span>
+ <Button onClick={() => copy(example, 'example')}>
+ {copied === 'example' ? 'Copied' : 'Copy example'}
+ </Button>
+ </div>
+ <pre className="overflow-x-auto rounded bg-bg px-2 py-1 font-mono text-[11px] text-text">
+ {example}
+ </pre>
+ </div>
+ ) : null}
+
+ {confirm === 'rotate' ? (
+ <ConfirmDialog
+ message="Rotate the webhook token? The current token stops working immediately; update every script that uses it with the new one."
+ confirmLabel="Rotate"
+ danger
+ onConfirm={() => void mint()}
+ onCancel={() => setConfirm(null)}
+ />
+ ) : null}
+ {confirm === 'revoke' ? (
+ <ConfirmDialog
+ message="Revoke the webhook token? Scripts using it will no longer reach your phone."
+ confirmLabel="Revoke"
+ danger
+ onConfirm={() => void revoke()}
+ onCancel={() => setConfirm(null)}
+ />
+ ) : null}
+ </div>
+ )
+}
diff --git a/src/shared/ipc.ts b/src/shared/ipc.ts
index 6c5293abe..12d8986c2 100644
--- a/src/shared/ipc.ts
+++ b/src/shared/ipc.ts
@@ -672,6 +672,12 @@ export const IPC = {
pairingProbeSsh: 'pairing:probe-ssh',
pairingOpenRemoteLoginSettings: 'pairing:open-remote-login-settings',
pairingListDevices: 'pairing:listDevices',
+ // Push webhook management (core/push-webhook.ts). Under `pairing:` so HOST_ONLY_CHANNEL_PREFIXES
+ // keeps them off the relay: minting a token that pushes to the host's phones is the host's call.
+ pairingWebhookStatus: 'pairing:webhook-status',
+ pairingWebhookMint: 'pairing:webhook-mint',
+ pairingWebhookRevoke: 'pairing:webhook-revoke',
+ pairingWebhookEndpoint: 'pairing:webhook-endpoint',
pairingRevokeDevice: 'pairing:revokeDevice',
// Dictation (desktop/server). speechProgress is a main/server → renderer broadcast of
// { id, pct } while a whisper model downloads (WhisperModelStore.onProgress).
diff --git a/src/shared/push-webhook.test.ts b/src/shared/push-webhook.test.ts
new file mode 100644
index 000000000..f19a7ccf9
--- /dev/null
+++ b/src/shared/push-webhook.test.ts
@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest'
+import { execFileSync } from 'node:child_process'
+import { PUSH_WEBHOOK_TOKEN_ENV, pushWebhookCurlExample, pushWebhookErrorText, type PushWebhookError } from './push-webhook'
+
+describe('pushWebhookCurlExample', () => {
+ it('reads the token from the environment and hands it to curl on stdin, never argv', () => {
+ const ex = pushWebhookCurlExample('https://api.test/')
+ expect(ex).toContain(`"$${PUSH_WEBHOOK_TOKEN_ENV}"`)
+ expect(ex).toContain('--config -')
+ expect(ex).not.toMatch(/-H ['"]?Authorization/i)
+ expect(ex).not.toContain('ntwh_')
+ expect(ex).toContain('https://api.test/v1/push/webhook')
+ })
+
+ it.skipIf(process.platform === 'win32')('is valid sh, and curl receives the header only through stdin', () => {
+ // Replace curl with a recorder: it prints its argv, then what it read on stdin.
+ const ex = pushWebhookCurlExample('https://api.test').replace('curl ', 'fakecurl ')
+ const out = execFileSync('/bin/sh', ['-c', `fakecurl() { printf 'ARGV:%s\\n' "$*"; cat; }\n${ex}`], {
+ env: { PATH: process.env.PATH, [PUSH_WEBHOOK_TOKEN_ENV]: 'ntwh_secret' },
+ encoding: 'utf8'
+ })
+ const [argvLine, ...stdin] = out.split('\n')
+ expect(argvLine).not.toContain('ntwh_secret')
+ expect(stdin.join('\n')).toContain('header = "Authorization: Bearer ntwh_secret"')
+ })
+})
+
+it('every error has a sentence', () => {
+ const all: PushWebhookError[] = ['dev-build', 'no-host-key', 'no-paired-phone', 'refused', 'rate-limited', 'unreachable']
+ for (const e of all) expect(pushWebhookErrorText(e).length).toBeGreaterThan(10)
+})
diff --git a/src/shared/push-webhook.ts b/src/shared/push-webhook.ts
new file mode 100644
index 000000000..3881b8246
--- /dev/null
+++ b/src/shared/push-webhook.ts
@@ -0,0 +1,84 @@
+/**
+ * The push webhook: a per-host token that lets a script, a CI job or a long build push a plain-text
+ * notification to the phones paired with this machine ("the build is done") without an agent in
+ * the loop. The backend owns the token (it stores only a hash); this machine proves it owns the
+ * relay host key to mint, inspect or revoke one (`core/push-webhook.ts`). Nothing here is secret.
+ */
+
+export const PUSH_WEBHOOK_PATH = '/v1/push/webhook'
+export const PUSH_WEBHOOK_DEFAULT_API_BASE = 'https://api.nodeterm.dev'
+/** The environment variable every example reads the token from — a CI secret, never a literal. */
+export const PUSH_WEBHOOK_TOKEN_ENV = 'NODETERM_WEBHOOK_TOKEN'
+/** Display caps the backend applies after stripping control characters (code points). */
+export const PUSH_WEBHOOK_TITLE_MAX = 120
+export const PUSH_WEBHOOK_BODY_MAX = 500
+
+/** What is live for this machine, as the backend reports it. Never the token itself. */
+export interface PushWebhookTokenInfo {
+ tokenId: string
+ /** The first few characters (`ntwh_abcd`), so the user can tell which token is live. */
+ tokenPrefix: string
+ createdAt: string
+ lastUsedAt: string | null
+}
+
+/** Why a webhook call did not happen. Each has its own sentence in the UI (`pushWebhookErrorText`). */
+export type PushWebhookError =
+ /** Unpackaged build with no NODETERM_API_BASE: the backend is not reachable from here on purpose. */
+ | 'dev-build'
+ /** The relay host key could not be read (keyring locked) — nothing to prove ownership with. */
+ | 'no-host-key'
+ /** The backend knows no live phone pairing for this machine, so a token could only ever send 0. */
+ | 'no-paired-phone'
+ /** The backend refused the ownership proof. */
+ | 'refused'
+ | 'rate-limited'
+ /** Network error, timeout, 5xx or an answer we could not read. */
+ | 'unreachable'
+
+export type PushWebhookResult<T> = { ok: true; value: T } | { ok: false; error: PushWebhookError }
+
+/** A freshly minted token: the ONLY time the full value exists outside the user's own storage. */
+export interface PushWebhookMinted extends PushWebhookTokenInfo {
+ token: string
+}
+
+export interface PushWebhookApi {
+ status(): Promise<PushWebhookResult<PushWebhookTokenInfo | null>>
+ /** Mint a token; revokes the one that was live (that is the rotation). */
+ mint(): Promise<PushWebhookResult<PushWebhookMinted>>
+ revoke(): Promise<PushWebhookResult<true>>
+}
+
+export function pushWebhookErrorText(error: PushWebhookError): string {
+ switch (error) {
+ case 'dev-build':
+ return 'Unavailable in a development build — set NODETERM_API_BASE to test against a backend.'
+ case 'no-host-key':
+ return 'Couldn’t read this machine’s remote-access key (is the keychain locked?). Try again.'
+ case 'no-paired-phone':
+ return 'Pair a phone with remote access first — the webhook pushes to the phones paired with this machine.'
+ case 'refused':
+ return 'The server refused this machine’s identity. Try again; if it keeps failing, re-pair your phone.'
+ case 'rate-limited':
+ return 'Too many requests — wait a minute and try again.'
+ case 'unreachable':
+ return 'Couldn’t reach the nodeterm server. Check the connection and try again.'
+ }
+}
+
+/**
+ * The copyable example. The token is read from an environment variable and handed to curl on
+ * STDIN (`--config -`), never on its command line: argv is readable by every user on the machine
+ * through `ps`, and a CI runner is exactly such a machine. `printf` is a shell builtin in sh, bash
+ * and zsh, so the token is not on its argv either.
+ */
+export function pushWebhookCurlExample(apiBase: string = PUSH_WEBHOOK_DEFAULT_API_BASE): string {
+ const url = apiBase.replace(/\/+$/, '') + PUSH_WEBHOOK_PATH
+ return [
+ `printf 'header = "Authorization: Bearer %s"\\n' "$${PUSH_WEBHOOK_TOKEN_ENV}" |`,
+ ` curl -fsS --config - -H 'Content-Type: application/json' \\`,
+ ` -d '{"title":"Build finished","body":"main is green"}' \\`,
+ ` ${url}`
+ ].join('\n')
+}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 2e32a6b2e..0eee3de46 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1,4 +1,5 @@
import type { TextDeliveryResult } from './text-delivery'
+import type { PushWebhookMinted, PushWebhookResult, PushWebhookTokenInfo } from './push-webhook'
import type { IdentitySeedEntry } from './agent-identity-seed'
import type { PrWaitHold } from './pr-wait'
// Types shared across the main, preload, and renderer processes.
@@ -3938,6 +3939,14 @@ export interface PairingApi {
* entitlement back on the relay backend. Never rejects for a leg that failed — read the result.
*/
revokeDevice(id: string): Promise<DeviceRevokeResult>
+ /** Push webhook (shared/push-webhook.ts): what token is live for this machine — never its value. */
+ webhookStatus(): Promise<PushWebhookResult<PushWebhookTokenInfo | null>>
+ /** Mint (or rotate) the token. The value in the result is the only copy that will ever exist
+ * outside the user's own storage: the backend keeps only its hash, and this app keeps nothing. */
+ webhookMint(): Promise<PushWebhookResult<PushWebhookMinted>>
+ webhookRevoke(): Promise<PushWebhookResult<true>>
+ /** The API base the examples should name (NODETERM_API_BASE or production). */
+ webhookEndpoint(): Promise<string>
}
/** Team presence (docs/team-presence.md). All of it is transient — nothing here is persisted. */