dsh-push-host 0.0.0-stage → 0.3.2

package/lib/pairing-lib.mjs

@@ -0,0 +1,69 @@
+/**
+ * Pairing payload helpers for the DSH push host plugin (pure functions; no I/O).
+ *
+ * `deploy/relay-user-add.sh <user>` already emits the pairing payload the phone needs; this module
+ * emits the *same schema with the same field names* from the host side, so the project has exactly
+ * one payload vocabulary:
+ *
+ *   { "v": 1, "relay": "<relay base>", "host": "<hostId>", "topic": "<ntfy topic>",
+ *     "writeToken": "tk_…",   // host  → ntfy (this plugin publishes with it)
+ *     "readToken":  "tk_…",   // phone → ntfy (the App subscribes with it)
+ *     "hostToken":  "hk_…" }  // host  → relay queue
+ *
+ * `buildPairingPayload` never invents values: every field comes from the credentials file (or, for
+ * `relay`, from the relay base the host will actually use), and a payload with a missing field is
+ * reported through `missing` instead of being emitted half-empty.
+ */
+
+/** Field order, identical to the payload `relay-user-add.sh` prints. */
+export const PAYLOAD_FIELDS = ['v', 'relay', 'host', 'topic', 'writeToken', 'readToken', 'hostToken']
+
+/**
+ * Optional extras (v0.1.1): written only when known. `relay-user-add.sh` cannot know the host's
+ * web base (only the operator knows which address the phone should dial), so these come from
+ * `dsh-push-pair payload --web-base/--web-name` or from the credentials file. Absent = the phone
+ * and the plugin behave exactly as before.
+ */
+export const PAYLOAD_OPTIONAL_FIELDS = ['webBase', 'webName']
+
+/** Payload schema version — the `v` that `relay-user-add.sh` writes. */
+export const PAYLOAD_VERSION = 1
+
+/**
+ * @param sources `{ credentials, relayBase }` (credentials use credentials-file vocabulary).
+ * @returns `{ payload, missing }`; `missing` lists the payload fields that could not be filled.
+ */
+export function buildPairingPayload(sources = {}) {
+  const credentials = sources.credentials ?? {}
+  const candidates = {
+    relay: String(sources.relayBase ?? credentials.relayBase ?? '').replace(/\/+$/, ''),
+    host: String(credentials.host ?? '').trim(),
+    topic: String(credentials.topic ?? '').trim(),
+    writeToken: String(credentials.ntfyToken ?? '').trim(),
+    readToken: String(credentials.phoneToken ?? '').trim(),
+    hostToken: String(credentials.hostToken ?? '').trim(),
+  }
+  const missing = Object.keys(candidates).filter((field) => candidates[field].length === 0)
+  const payload = { v: PAYLOAD_VERSION, ...candidates }
+  for (const field of PAYLOAD_OPTIONAL_FIELDS) {
+    const value = String(credentials[field] ?? '').trim()
+    if (value.length > 0) payload[field] = value
+  }
+  return { payload, missing }
+}
+
+/** Human-readable one-liner for the operator's terminal (tokens shortened). */
+export function summarizePayload(payload) {
+  const short = (value, keep = 10) => {
+    const text = String(value ?? '')
+    return text.length > keep ? text.slice(0, keep) + '…' : text
+  }
+  return (
+    'host=' + String(payload?.host ?? '') +
+    ' topic=' + String(payload?.topic ?? '') +
+    ' relay=' + String(payload?.relay ?? '') +
+    ' writeToken=' + short(payload?.writeToken) +
+    ' readToken=' + short(payload?.readToken) +
+    ' hostToken=' + short(payload?.hostToken)
+  )
+}

package/lib/pairing.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * Pairing tool for the DSH push host plugin — the operator's single command for onboarding one user.
+ *
+ *   dsh-push-pair [payload] [options]     print the pairing payload for one user's phone
+ *   dsh-push-pair verify   [options]      check a credentials file against the live relay + ntfy
+ *
+ * Options (both commands):
+ *   --credentials-file <path>  credentials JSON (default: $DSH_PUSH_CREDENTIALS or
+ *                              ~/.config/dsh-push/credentials.json)
+ *   --relay <url>              relay base to put in the payload (default: credentials.relayBase)
+ *   --host/--topic/--write-token/--read-token/--host-token <value>   one-off overrides
+ *   --web-base/--web-name <value>  optional payload extras (host web link base / instance name)
+ *   --pretty                   indent the JSON output
+ *   --json                     machine-readable result for `verify`
+ *   --help                     usage
+ *
+ * Schema: identical to what `deploy/relay-user-add.sh` prints (`v`, `relay`, `host`, `topic`,
+ * `writeToken`, `readToken`, `hostToken`) — one payload vocabulary in the project, not two. The file
+ * it reads is the same credentials file the plugin reads, so one saved payload configures the host
+ * side and is handed to the phone unchanged.
+ *
+ * `verify` performs read-only checks plus one harmless ntfy test message; it never reads another
+ * host's queue and never changes relay state.
+ */
+import { credentialsPath, loadCredentials } from './credentials.mjs'
+import { PAYLOAD_FIELDS, PAYLOAD_VERSION, buildPairingPayload, summarizePayload } from './pairing-lib.mjs'
+
+const USAGE = `usage:
+  dsh-push-pair [payload] [options]   print the pairing payload for one user's phone
+  dsh-push-pair verify   [options]    check a credentials file against the live relay + ntfy
+
+options:
+  --credentials-file <path>   credentials JSON file (default: $DSH_PUSH_CREDENTIALS or
+                              ~/.config/dsh-push/credentials.json)
+  --relay <url>               relay base written into the payload
+  --host <id> --topic <name>  overrides for a one-off payload
+  --write-token <tk_...> --read-token <tk_...> --host-token <hk_...>
+  --web-base <url>            host-side web base for the #web link (optional; written into the
+                              payload so the credentials file carries it too)
+  --web-name <name>           friendly instance name for #name (optional)
+  --pretty                    indented JSON (payload)
+  --json                      machine-readable JSON (verify)
+  --help                      this text
+
+payload schema (v${PAYLOAD_VERSION}, same field names as deploy/relay-user-add.sh):
+  ${PAYLOAD_FIELDS.join(', ')}
+
+  writeToken = host -> ntfy (this plugin publishes with it)
+  readToken  = phone -> ntfy (the App subscribes with it)
+  hostToken  = host -> relay queue token
+`
+
+/** Tiny `--flag value` / `--flag=value` parser (no dependency, no surprises). */
+export function parseArgs(argv = []) {
+  const options = { command: 'payload', flags: {}, overrides: {} }
+  const aliases = {
+    '--credentials-file': 'credentialsFile',
+    '--relay': 'relayBase',
+    '--host': 'host',
+    '--topic': 'topic',
+    '--write-token': 'ntfyToken',
+    '--read-token': 'phoneToken',
+    '--host-token': 'hostToken',
+    '--web-base': 'webBase',
+    '--web-name': 'webName',
+  }
+  const booleans = { '--pretty': 'pretty', '--json': 'json', '--help': 'help' }
+  const queue = [...argv]
+  while (queue.length > 0) {
+    const raw = queue.shift()
+    if (raw === 'payload' || raw === 'verify') {
+      options.command = raw
+      continue
+    }
+    const equals = raw.indexOf('=')
+    const flag = equals > 0 ? raw.slice(0, equals) : raw
+    if (Object.hasOwn(booleans, flag)) {
+      options.flags[booleans[flag]] = equals > 0 ? raw.slice(equals + 1) !== 'false' : true
+      continue
+    }
+    if (Object.hasOwn(aliases, flag)) {
+      const value = equals > 0 ? raw.slice(equals + 1) : queue.shift()
+      if (value === undefined) throw new Error('missing value for ' + flag)
+      options.overrides[aliases[flag]] = value
+      continue
+    }
+    if (raw === '-h') {
+      options.flags.help = true
+      continue
+    }
+    throw new Error('unknown argument ' + JSON.stringify(raw))
+  }
+  return options
+}
+
+/** Credentials file + per-invocation overrides. */
+export function load(options = {}, env = process.env) {
+  const path = credentialsPath({ credentialsFile: options.overrides?.credentialsFile ?? '' }, env)
+  const file = loadCredentials(path)
+  const credentials = { ...file.value }
+  for (const field of ['host', 'topic', 'ntfyToken', 'phoneToken', 'hostToken', 'relayBase', 'webBase', 'webName']) {
+    const value = options.overrides?.[field]
+    if (typeof value === 'string' && value.trim().length > 0) credentials[field] = value.trim()
+  }
+  return { path, file, credentials }
+}
+
+async function fetchStatus(url, headers = {}) {
+  const response = await fetch(url, { headers })
+  return response.status
+}
+
+/** Read-only relay/ntfy checks; the ntfy test message proves the write token actually publishes. */
+export async function verify(options = {}, env = process.env) {
+  const { path, file, credentials } = load(options, env)
+  const relay = String(credentials.relayBase ?? '').replace(/\/+$/, '')
+  const results = []
+
+  if (!file.present) results.push({ check: 'credentials-file', ok: false, detail: 'missing: ' + path })
+  else if (file.error !== undefined) results.push({ check: 'credentials-file', ok: false, detail: file.error })
+  else results.push({ check: 'credentials-file', ok: true, detail: path })
+
+  const { payload, missing } = buildPairingPayload({ credentials })
+  results.push({
+    check: 'payload-fields',
+    ok: missing.length === 0,
+    detail: missing.length === 0 ? summarizePayload(payload) : 'missing: ' + missing.join(', '),
+  })
+
+  if (relay.length > 0 && payload.host.length > 0 && payload.hostToken.length > 0) {
+    const url = relay + '/answer/pending?host=' + encodeURIComponent(payload.host) + '&_=' + String(Date.now())
+    try {
+      const status = await fetchStatus(url, { 'X-Host-Token': payload.hostToken })
+      results.push({ check: 'relay-host-token', ok: status === 200, detail: 'HTTP ' + String(status) + ' <- ' + url })
+    } catch (error) {
+      results.push({ check: 'relay-host-token', ok: false, detail: String(error?.message ?? error) })
+    }
+  } else {
+    results.push({ check: 'relay-host-token', ok: false, detail: 'no relay base / host / hostToken to probe' })
+  }
+
+  if (relay.length > 0 && payload.topic.length > 0 && payload.readToken.length > 0) {
+    const url = relay + '/' + encodeURIComponent(payload.topic) + '/json?poll=1&since=1h&limit=1'
+    try {
+      const status = await fetchStatus(url, { Authorization: 'Bearer ' + payload.readToken })
+      results.push({ check: 'ntfy-read-token', ok: status === 200, detail: 'HTTP ' + String(status) + ' <- ' + url })
+    } catch (error) {
+      results.push({ check: 'ntfy-read-token', ok: false, detail: String(error?.message ?? error) })
+    }
+  } else {
+    results.push({ check: 'ntfy-read-token', ok: false, detail: 'no relay base / topic / readToken to probe' })
+  }
+
+  if (relay.length > 0 && payload.topic.length > 0 && payload.writeToken.length > 0) {
+    try {
+      const response = await fetch(relay + '/', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + payload.writeToken },
+        body: JSON.stringify({
+          topic: payload.topic,
+          title: 'DSH 配对自检',
+          message: '配对自检成功（字段名与 relay-user-add.sh 一致：' + PAYLOAD_FIELDS.join(', ') + '）',
+          priority: 3,
+          tags: ['white_check_mark'],
+        }),
+      })
+      results.push({
+        check: 'ntfy-write-token',
+        ok: response.status === 200,
+        detail: 'HTTP ' + String(response.status) + ' <- POST / topic=' + payload.topic,
+      })
+    } catch (error) {
+      results.push({ check: 'ntfy-write-token', ok: false, detail: String(error?.message ?? error) })
+    }
+  } else {
+    results.push({ check: 'ntfy-write-token', ok: false, detail: 'no relay base / topic / writeToken to probe' })
+  }
+
+  const failed = results.filter((entry) => entry.ok !== true)
+  return { path, results, failed, payload }
+}
+
+export async function main(argv = process.argv.slice(2), { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const options = parseArgs(argv)
+  if (options.flags.help === true || argv.length === 0) {
+    stdout.write(USAGE)
+    return 0
+  }
+
+  if (options.command === 'verify') {
+    const report = await verify(options)
+    if (options.flags.json === true) {
+      stdout.write(JSON.stringify({ path: report.path, results: report.results }, undefined, 2) + '\n')
+    } else {
+      stdout.write('credentials: ' + report.path + '\n')
+      for (const entry of report.results) {
+        stdout.write((entry.ok === true ? 'PASS  ' : 'FAIL  ') + entry.check + '  -> ' + entry.detail + '\n')
+      }
+      stdout.write('\n' + String(report.results.length - report.failed.length) + '/' + String(report.results.length) + ' checks passed\n')
+    }
+    if (report.failed.length > 0) {
+      stderr.write(
+        '\nnext steps: on the relay host run `bash relay-user-add.sh <user>`, save the payload it prints as ' +
+          report.path + ', then run `dsh-push-pair verify` again (see host-plugin/README.md).\n',
+      )
+      return 1
+    }
+    return 0
+  }
+
+  const { path, file, credentials } = load(options)
+  const { payload, missing } = buildPairingPayload({ credentials })
+  if (missing.length > 0) {
+    stderr.write(
+      'cannot build a complete pairing payload: missing ' + missing.join(', ') + '\n' +
+        (file.present ? '' : 'credentials file not found: ' + path + '\n') +
+        (file.error === undefined ? '' : file.error + '\n') +
+        'provision the user first (on the relay host: `bash relay-user-add.sh <user>`) and save its output as\n' +
+        path +
+        ', or pass --host/--topic/--write-token/--read-token/--host-token explicitly.\n',
+    )
+    return 1
+  }
+  stdout.write(JSON.stringify(payload, undefined, options.flags.pretty === true ? 2 : undefined) + '\n')
+  return 0
+}
+
+/** True when this module is the process entry point (npm bin shim, `node lib/pairing.mjs`, …). */
+function isEntryPoint() {
+  const invoked = process.argv[1]
+  if (typeof invoked !== 'string' || invoked.length === 0) return false
+  const file = invoked.replaceAll('\\', '/').split('/').pop()
+  return file === 'pairing.mjs' && import.meta.url.endsWith('/' + file)
+}
+
+if (isEntryPoint()) {
+  try {
+    process.exitCode = await main()
+  } catch (error) {
+    process.stderr.write('dsh-push-pair: ' + String(error?.message ?? error) + '\n')
+    process.exitCode = 1
+  }
+}

package/lib/relay.js

@@ -0,0 +1,100 @@
+/**
+ * Relay client for the DSH push host plugin.
+ *
+ * Two directions:
+ *  - push:   POST <relay>/            (ntfy JSON publish, write token)
+ *            POST <relay>/answer/register   (tell the relay a question is pending, with hostId)
+ *  - answer: GET  <relay>/answer/pending?host=<id>   (poll, X-Host-Token)
+ *            POST <relay>/answer/ack                (remove delivered answers)
+ *
+ * The poll direction is outbound-only on purpose: a host behind NAT needs no inbound port and the
+ * relay never has to reach it (this replaced the old DSH-cookie bridge).
+ */
+
+export class RelayClient {
+  constructor(config) {
+    this.base = config.relayBase.replace(/\/+$/, '');
+    this.host = config.host;
+    this.hostToken = config.hostToken;
+    this.regToken = config.regToken;
+    this.ntfyToken = config.ntfyToken;
+    this.topic = config.topic;
+    this.fetchImpl = config.fetch ?? globalThis.fetch;
+  }
+
+  async #json(res) {
+    const text = await res.text();
+    try { return JSON.parse(text); } catch { return { ok: false, raw: text.slice(0, 200) }; }
+  }
+
+  /**
+   * Publish a notification to the phone through ntfy (same JSON body shape the app expects).
+   *
+   * `priority` MUST be an integer 1-5. ntfy's JSON body only accepts numbers here: passing the
+   * string 'default' (which is what ntfy's *header* form uses) makes the server answer
+   * 400 `invalid request: request body must be valid JSON` — a message that points nowhere near
+   * the real cause. Callers inside this plugin always pass 1/3/4; the default used to be the
+   * string 'default', which broke every caller that omitted it.
+   */
+  async push({ title, body, click, priority = 3, tags = [] }) {
+    const r = await this.fetchImpl(this.base + '/', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + this.ntfyToken },
+      body: JSON.stringify({ topic: this.topic, title, message: body, priority, click, tags }),
+    });
+    return { status: r.status, ...(await this.#json(r)) };
+  }
+
+  /** Register a pending question so the phone can answer it; the relay queues the reply for us. */
+  async register({ callId, agentId, questions, ttl = 86400 }) {
+    const r = await this.fetchImpl(this.base + '/answer/register', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Reg-Token': this.regToken },
+      body: JSON.stringify({ callId, agentId, questions, hostId: this.host, ttl }),
+    });
+    return { status: r.status };
+  }
+
+  /** Poll for answers addressed to this host. Returns [] when idle. */
+  async pending() {
+    // The `_` cache-buster is not cosmetic: DSH's fetch runs through its own proxy layer, and
+    // an identical GET URL that had been polled before kept coming back as the FIRST response
+    // (observed 2026-10-12: the relay queue grew while the plugin kept seeing one stale item).
+    // A unique query string keeps every poll a distinct request.
+    const url = this.base + '/answer/pending?host=' + encodeURIComponent(this.host) + '&_=' + String(Date.now());
+    const r = await this.fetchImpl(url, { headers: { 'X-Host-Token': this.hostToken } });
+    if (r.status !== 200) return [];
+    const j = await this.#json(r);
+    return Array.isArray(j.items) ? j.items : [];
+  }
+
+  /** Confirm delivery so the relay drops them (at-least-once; the caller dedupes by callId). */
+  async ack(callIds) {
+    const r = await this.fetchImpl(this.base + '/answer/ack', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Host-Token': this.hostToken },
+      body: JSON.stringify({ host: this.host, callIds }),
+    });
+    return { status: r.status, ...(await this.#json(r)) };
+  }
+
+  /** Long-running poll loop; `onAnswer(item)` may throw — the item is acked only when it returns. */
+  async runAnswerLoop(onAnswer, { intervalMs = 3000, log = console.log } = {}) {
+    for (;;) {
+      try {
+        for (const item of await this.pending()) {
+          try {
+            await onAnswer(item);
+            await this.ack([item.callId]);
+            log('[relay] answered ' + item.callId);
+          } catch (e) {
+            log('[relay] answer failed for ' + item.callId + ': ' + (e?.message ?? e));
+          }
+        }
+      } catch (e) {
+        log('[relay] poll failed: ' + (e?.message ?? e));
+      }
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+  }
+}

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "dsh-push-host",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "description": "DSH host-side phone push: question events to ntfy + in-process answering via relay polling (replaces the external notifier + answer bridge)",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "push",
+    "ntfy",
+    "notification"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "cpyh",
+    "url": "https://github.com/thiscp"
+  },
+  "contributors": [
+    {
+      "name": "DeepSeek Harness agents"
+    }
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./credentials": "./lib/credentials.mjs",
+    "./pairing": "./lib/pairing.mjs",
+    "./pairing-lib": "./lib/pairing-lib.mjs",
+    "./relay": "./lib/relay.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "dsh-push-pair": "./lib/pairing.mjs"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thiscp/dsh-push.git",
+    "directory": "host-plugin"
+  },
+  "homepage": "https://github.com/thiscp/dsh-push/tree/main/host-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/thiscp/dsh-push/issues"
+  },
+  "scripts": {
+    "test": "node plugin-selftest.mjs",
+    "pair": "node lib/pairing.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "version": "1",
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  }
+}