@qontinui/ui-bridge-native 0.9.0 → 0.11.0

package/dist/server/index.mjs

@@ -332,6 +332,12 @@ var UI_BRIDGE_NATIVE_ROUTES = {
     method: "GET",
     path: "/ui-bridge/health",
     description: "Health check"
+  },
+  // Device pairing
+  PAIR: {
+    method: "POST",
+    path: "/ui-bridge/pair",
+    description: "Get the pairing token: loopback with no code, otherwise body { code }. Direct HTTP only"
   }
 };
 
@@ -445,8 +451,7 @@ function utf8Bytes(input) {
   return Uint8Array.from(out);
 }
 var rotr = (x, n) => x >>> n | x << 32 - n;
-function sha256Hex(input) {
-  const bytes = utf8Bytes(input);
+function sha256Bytes(bytes) {
   const blockBytes = Math.ceil((bytes.length + 9) / 64) * 64;
   const buffer = new Uint8Array(blockBytes);
   buffer.set(bytes);
@@ -490,7 +495,38 @@ function sha256Hex(input) {
     h[6] = h[6] + g | 0;
     h[7] = h[7] + hh | 0;
   }
-  return h.map((word) => (word >>> 0).toString(16).padStart(8, "0")).join("");
+  const digest = new Uint8Array(32);
+  const digestView = new DataView(digest.buffer);
+  h.forEach((word, i) => digestView.setUint32(i * 4, word >>> 0));
+  return digest;
+}
+function bytesToHex(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) out += bytes[i].toString(16).padStart(2, "0");
+  return out;
+}
+function sha256Hex(input) {
+  return bytesToHex(sha256Bytes(utf8Bytes(input)));
+}
+var SHA256_BLOCK_BYTES = 64;
+function hmacSha256(key, message) {
+  const normalizedKey = key.length > SHA256_BLOCK_BYTES ? sha256Bytes(key) : key;
+  const inner = new Uint8Array(SHA256_BLOCK_BYTES + message.length);
+  const outer = new Uint8Array(SHA256_BLOCK_BYTES + 32);
+  for (let i = 0; i < SHA256_BLOCK_BYTES; i++) {
+    const keyByte = i < normalizedKey.length ? normalizedKey[i] : 0;
+    inner[i] = keyByte ^ 54;
+    outer[i] = keyByte ^ 92;
+  }
+  inner.set(message, SHA256_BLOCK_BYTES);
+  outer.set(sha256Bytes(inner), SHA256_BLOCK_BYTES);
+  return sha256Bytes(outer);
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
 }
 
 // src/core/vision-fields.ts
@@ -1520,7 +1556,7 @@ var NATIVE_PAGE_HEALTH_PRODUCER_ID = "sdk-native/page-health";
 function defaultProducer() {
   return {
     id: NATIVE_PAGE_HEALTH_PRODUCER_ID,
-    version: "0.9.0" 
+    version: "0.11.0" 
   };
 }
 function pageHealthUnknown(code, detail, options = {}) {
@@ -2423,6 +2459,16 @@ function createServerHandlers(registry, executor, config) {
     // the envelope agree; an unmounted path answers 404 instead. Each error
     // message names an in-tree mobile replacement so operators aren't left
     // guessing what to use instead.
+    // The real pairing route lives in the server's network entry, ahead of this
+    // table, because only that entry knows the socket peer. This answer is what
+    // JSON-RPC over a WebSocket and the cloud relay get, so neither can mint a
+    // token or spend a code attempt.
+    pair: async () => {
+      return error2(
+        "Pairing is served only on a direct HTTP connection to the device, not over JSON-RPC or the cloud relay.",
+        "NOT_SUPPORTED"
+      );
+    },
     aiForms: async () => {
       return error2(
         'ai/forms (form discovery) is runner-only; mobile React Native has no DOM to walk. Use GET /ui-bridge/control/snapshot and filter for type === "input" instead.',
@@ -2817,7 +2863,7 @@ function createServerHandlers(registry, executor, config) {
       };
       if (config?.appInfo) {
         response.uiBridge = {
-          version: "0.9.0",
+          version: "0.11.0",
           ...config.appInfo,
           capabilities: ["elements", "components", "actions", "design"],
           elementCount: stats.elements,
@@ -2829,6 +2875,527 @@ function createServerHandlers(registry, executor, config) {
   };
 }
 
+// src/server/pairing.ts
+var UI_BRIDGE_AUTH_HEADER = "X-UI-Bridge-Auth";
+var SIGNATURE_WINDOW_MS = 3e5;
+var PAIRING_CODE_TTL_MS = 12e4;
+var PAIRING_CODE_MAX_ATTEMPTS = 5;
+var SIGNED_BODY_MAX_CHARS = 256 * 1024;
+var SIGNED_METHOD_MAX_CHARS = 16;
+var SIGNED_TARGET_MAX_CHARS = 8192;
+var TOKEN_BYTES = 32;
+var NONCE_CACHE_MAX = 4096;
+var STORE_TIMEOUT_MS = 1e4;
+var CODE_SAMPLE_ATTEMPTS = 32;
+var CODE_SAMPLE_LIMIT = Math.floor(4294967296 / 1e6) * 1e6;
+var CLOCK_STEP_TOLERANCE_MS = 5e3;
+function monotonicNow() {
+  const clock = globalThis.performance;
+  return typeof clock?.now === "function" ? clock.now() : null;
+}
+var PairingError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "PairingError";
+  }
+};
+function canonicalSignatureInput(parts) {
+  return [parts.method, parts.pathAndQuery, parts.ts, parts.nonce, parts.bodySha256Hex].join("\n");
+}
+function signatureHex(token, parts) {
+  const input = canonicalSignatureInput({
+    method: parts.method,
+    pathAndQuery: parts.pathAndQuery,
+    ts: parts.ts,
+    nonce: parts.nonce,
+    bodySha256Hex: sha256Hex(parts.body)
+  });
+  return bytesToHex(hmacSha256(utf8Bytes(token), utf8Bytes(input)));
+}
+function signUIBridgeRequest(token, request) {
+  const ts = String(request.ts);
+  const sig = signatureHex(token, {
+    method: request.method,
+    pathAndQuery: request.pathAndQuery,
+    ts,
+    nonce: request.nonce,
+    body: request.body ?? ""
+  });
+  return `${ts}.${request.nonce}.${sig}`;
+}
+function headerValues(headers, name) {
+  if (!headers) return [];
+  const wanted = name.toLowerCase();
+  return Object.keys(headers).filter((key) => key.toLowerCase() === wanted).map((key) => headers[key]);
+}
+function ipv4Octets(address) {
+  const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(address);
+  if (!match) return null;
+  const octets = match.slice(1).map(Number);
+  return octets.every((octet) => octet <= 255) ? octets : null;
+}
+function isLoopbackIpv4(address) {
+  return ipv4Octets(address)?.[0] === 127;
+}
+function parseIpv6(address) {
+  if (!address.includes(":")) return null;
+  let text = address;
+  const trailing = [];
+  const lastColon = text.lastIndexOf(":");
+  const tail = text.slice(lastColon + 1);
+  if (tail.includes(".")) {
+    const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(tail);
+    if (!match) return null;
+    const octets = match.slice(1).map(Number);
+    if (octets.some((octet) => octet > 255)) return null;
+    trailing.push(octets[0] << 8 | octets[1], octets[2] << 8 | octets[3]);
+    text = text.slice(0, lastColon + 1);
+    if (!text.endsWith("::")) text = text.slice(0, -1);
+  }
+  const groupsOf = (part) => {
+    if (part === "") return [];
+    const groups = [];
+    for (const group of part.split(":")) {
+      if (!/^[0-9a-fA-F]{1,4}$/.test(group)) return null;
+      groups.push(parseInt(group, 16));
+    }
+    return groups;
+  };
+  const gapAt = text.indexOf("::");
+  if (gapAt !== text.lastIndexOf("::")) return null;
+  const width = 8 - trailing.length;
+  if (gapAt === -1) {
+    const groups = groupsOf(text);
+    return groups && groups.length === width ? [...groups, ...trailing] : null;
+  }
+  const head = groupsOf(text.slice(0, gapAt));
+  const rest = groupsOf(text.slice(gapAt + 2));
+  if (!head || !rest || head.length + rest.length >= width) return null;
+  const zeros = new Array(width - head.length - rest.length).fill(0);
+  return [...head, ...zeros, ...rest, ...trailing];
+}
+function isLoopbackIpv6(address) {
+  const zone = address.indexOf("%");
+  const groups = parseIpv6(zone === -1 ? address : address.slice(0, zone));
+  if (!groups) return false;
+  const leadingZeros = (count) => groups.slice(0, count).every((g) => g === 0);
+  if (leadingZeros(7) && groups[7] === 1) return true;
+  return leadingZeros(5) && groups[5] === 65535 && groups[6] >> 8 === 127;
+}
+function isLoopbackAddress(address) {
+  return isLoopbackIpv4(address) || isLoopbackIpv6(address);
+}
+function isLoopbackHost(host) {
+  const value = host.trim().toLowerCase();
+  const bracketed = /^\[([^\]]+)\](?::(\d{1,5}))?$/.exec(value);
+  if (bracketed) {
+    return isLoopbackIpv6(bracketed[1]) && isValidPort(bracketed[2]);
+  }
+  const plain = /^([^:]+)(?::(\d{1,5}))?$/.exec(value);
+  if (!plain) return false;
+  return (plain[1] === "localhost" || isLoopbackIpv4(plain[1])) && isValidPort(plain[2]);
+}
+function isValidPort(port) {
+  return port === void 0 || Number(port) <= 65535;
+}
+function isUnrebindableHost(host) {
+  const value = host.trim().toLowerCase();
+  const bracketed = /^\[([^\]%]+)(?:%[^\]]*)?\](?::(\d{1,5}))?$/.exec(value);
+  if (bracketed) return parseIpv6(bracketed[1]) !== null && isValidPort(bracketed[2]);
+  const plain = /^([^:]+)(?::(\d{1,5}))?$/.exec(value);
+  if (!plain) return false;
+  const named = plain[1] === "localhost" || plain[1].endsWith(".local") || ipv4Octets(plain[1]) !== null;
+  return named && isValidPort(plain[2]);
+}
+function carriesWebContext(request) {
+  const { headers } = request;
+  if (headerValues(headers, "origin").length > 0) return true;
+  if (headerValues(headers, "referer").length > 0) return true;
+  return headerValues(headers, "sec-fetch-site").some(
+    (site) => site.trim().toLowerCase() !== "none"
+  );
+}
+function isTrustedLoopbackRequest(request) {
+  if (!request.remoteAddress || !isLoopbackAddress(request.remoteAddress)) return false;
+  if (carriesWebContext(request)) return false;
+  const hosts = headerValues(request.headers, "host");
+  return hosts.length > 0 && hosts.every(isLoopbackHost);
+}
+function isWebReachableRequest(request) {
+  if (carriesWebContext(request)) return true;
+  const hosts = headerValues(request.headers, "host");
+  return hosts.length === 0 || !hosts.every(isUnrebindableHost);
+}
+async function bounded(work) {
+  let timer;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(work),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("store call timed out")), STORE_TIMEOUT_MS);
+      })
+    ]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+var UNAVAILABLE = {
+  ok: false,
+  code: "PAIRING_UNAVAILABLE",
+  error: "The pairing store is not available yet. Try again."
+};
+var TOKEN_NOT_LOADED = /* @__PURE__ */ Symbol("token-not-loaded");
+var PairingAuthority = class {
+  constructor(store) {
+    this.store = store;
+    this.armedCode = null;
+    /** A correct code waiting on the store step, restored if that step fails. */
+    this.heldCode = null;
+    this.disarmReason = null;
+    this.consumedBy = null;
+    this.consumedAt = null;
+    this.lastWrite = Promise.resolve();
+    /** Nonce to its timestamp, oldest insertion first. */
+    this.nonces = /* @__PURE__ */ new Map();
+    /**
+     * The oldest timestamp still accepted. A nonce this process did not record
+     * cannot be checked for a replay, so a signature from before it existed is
+     * refused: otherwise an app restart, which empties the cache, would reopen
+     * the whole window to a captured request. Eviction raises it for the same
+     * reason. A clock step re-bases it to the new now, or a clock set back past it
+     * would refuse every signature until the app restarted. That leaves one gap with
+     * two arms: a request captured before a step back can replay once, if its
+     * timestamp is at or above the new now and this process does not remember its
+     * nonce, because it has forgotten it, or because the app restarted since and it
+     * never recorded it. Without `performance.now` no step is seen, and the floor
+     * holds until the clock passes it.
+     */
+    this.oldestAcceptedTs = Date.now();
+    /**
+     * The wall clock minus the monotonic clock at the last re-base. It moves only
+     * then, so small steps add up until they cross the tolerance, and a clock step
+     * leaves the floor at most twice the tolerance ahead of the clock: the clock can
+     * swing from just over the baseline to just under it without crossing it.
+     */
+    this.clockOffset = this.readClockOffset();
+    /** Moves when a revoke ends, so a read of the old token that spans one cannot admit. */
+    this.tokenGeneration = 0;
+    /** Revokes under way. The old token may already be dying, so nothing verifies. */
+    this.revokesInFlight = 0;
+    /** A revoke failed in a way that may have left the old token in the store. */
+    this.storeSuspect = false;
+  }
+  /**
+   * The stored token, `null` when there is none, or `TOKEN_NOT_LOADED`. Only
+   * `readStore` tells these apart: an empty or non-string value is never a
+   * token, because an empty key would verify anything signed with it.
+   */
+  async readToken() {
+    return this.storeSuspect ? TOKEN_NOT_LOADED : this.readStore();
+  }
+  async readStore() {
+    try {
+      const token = await bounded(() => this.store.get());
+      if (token === null) return null;
+      return typeof token === "string" && token.length > 0 ? token : TOKEN_NOT_LOADED;
+    } catch {
+      return TOKEN_NOT_LOADED;
+    }
+  }
+  async randomBytes(n) {
+    const unusable = new PairingError(
+      "PAIRING_UNAVAILABLE",
+      "The secure random source returned no usable bytes."
+    );
+    let bytes;
+    try {
+      bytes = await bounded(() => this.store.randomBytes(n));
+    } catch {
+      throw unusable;
+    }
+    if (!ArrayBuffer.isView(bytes) || bytes.length !== n || bytes.every((byte) => byte === 0)) {
+      throw unusable;
+    }
+    return bytes;
+  }
+  async mintAndStoreToken() {
+    const token = bytesToHex(await this.randomBytes(TOKEN_BYTES));
+    await bounded(() => this.store.set(token));
+    return token;
+  }
+  /** Run token writes one at a time, so two first pairs cannot mint two tokens. */
+  exclusive(work) {
+    const run = this.lastWrite.then(work, work);
+    this.lastWrite = run.catch(() => void 0);
+    return run;
+  }
+  /** Check a `<ts>.<nonce>.<sig>` value against this request and the stored token. */
+  async verifySignature(request, header) {
+    const match = /^(\d{1,16})\.([A-Za-z0-9_-]{16,64})\.([0-9a-f]{64})$/.exec(header);
+    if (!match) return "refused";
+    const [, ts, nonce, sig] = match;
+    const tsMs = Number(ts);
+    this.noticeClockStep();
+    if (Math.abs(Date.now() - tsMs) > SIGNATURE_WINDOW_MS) return "timestamp_refused";
+    if (tsMs < this.oldestAcceptedTs) return "timestamp_refused";
+    const pathAndQuery = signedTarget(request);
+    const body = signedBody(request);
+    if (pathAndQuery === null || body === null) return "refused";
+    if (body.length > SIGNED_BODY_MAX_CHARS) return "body_too_large";
+    if (request.method.length > SIGNED_METHOD_MAX_CHARS) return "target_too_long";
+    if (pathAndQuery.length > SIGNED_TARGET_MAX_CHARS) return "target_too_long";
+    const generation = this.tokenGeneration;
+    const token = await this.readToken();
+    if (this.revokesInFlight > 0) return "refused";
+    if (token === TOKEN_NOT_LOADED) return "store_unavailable";
+    if (token === null) return "refused";
+    const expected = signatureHex(token, { method: request.method, pathAndQuery, ts, nonce, body });
+    if (!constantTimeEqual(expected, sig)) return "refused";
+    if (generation !== this.tokenGeneration) return "refused";
+    if (this.nonces.has(nonce)) return "refused";
+    this.rememberNonce(nonce, tsMs);
+    return "valid";
+  }
+  readClockOffset() {
+    const monotonic = monotonicNow();
+    return monotonic === null ? null : Date.now() - monotonic;
+  }
+  /**
+   * Re-base the floor when the wall clock has stepped against the monotonic one.
+   * A nonce remembered from above the new now is clamped to just below the new
+   * floor. Left as it is, forgetting it later would raise the floor back to a time
+   * before the step, and the lockout would return when the cache overflowed.
+   */
+  noticeClockStep() {
+    const offset = this.readClockOffset();
+    if (offset === null || this.clockOffset === null) return;
+    if (Math.abs(offset - this.clockOffset) > CLOCK_STEP_TOLERANCE_MS) {
+      this.clockOffset = offset;
+      this.oldestAcceptedTs = Date.now();
+      for (const [nonce, tsMs] of this.nonces) {
+        if (tsMs >= this.oldestAcceptedTs) this.nonces.set(nonce, this.oldestAcceptedTs - 1);
+      }
+    }
+  }
+  rememberNonce(nonce, tsMs) {
+    if (this.nonces.size >= NONCE_CACHE_MAX) {
+      const now = Date.now();
+      for (const [seen, seenTs] of this.nonces) {
+        if (seenTs + SIGNATURE_WINDOW_MS < now) this.forgetNonce(seen, seenTs);
+      }
+    }
+    while (this.nonces.size >= NONCE_CACHE_MAX) {
+      const [seen, seenTs] = this.nonces.entries().next().value;
+      this.forgetNonce(seen, seenTs);
+    }
+    this.nonces.set(nonce, tsMs);
+  }
+  /** Forgetting a nonce must not readmit it, so its timestamp stops being accepted. */
+  forgetNonce(nonce, tsMs) {
+    this.nonces.delete(nonce);
+    this.oldestAcceptedTs = Math.max(this.oldestAcceptedTs, tsMs + 1);
+  }
+  /**
+   * The route's decision. A trusted loopback caller needs no code. Anyone else
+   * spends the armed code, and an unarmed one refuses without comparing.
+   */
+  async pair(input) {
+    if (!input.trustedLoopback) {
+      const refusal = this.spendCode(input.body);
+      if (refusal) return refusal;
+    }
+    const spent = input.trustedLoopback ? null : this.heldCode;
+    const outcome = await this.exclusive(async () => {
+      const existing = await this.readToken();
+      if (existing === TOKEN_NOT_LOADED) return UNAVAILABLE;
+      if (existing !== null) return { ok: true, token: existing };
+      try {
+        return { ok: true, token: await this.mintAndStoreToken() };
+      } catch {
+        return UNAVAILABLE;
+      }
+    });
+    if (spent) this.settleSpentCode(spent, outcome.ok, input.peer);
+    return outcome;
+  }
+  /**
+   * The store step has answered. A failure gives the code back, since the user
+   * typed the right one and the phone let them down, unless the app has since
+   * cancelled it or armed another.
+   */
+  settleSpentCode(spent, paired, peer) {
+    const stillHeld = this.heldCode === spent;
+    if (stillHeld) this.heldCode = null;
+    if (paired) {
+      if (stillHeld) this.disarmReason = "consumed";
+      this.consumedBy = peer ?? "unknown";
+      this.consumedAt = Date.now();
+    } else if (stillHeld) {
+      this.armedCode = spent;
+    }
+  }
+  /** No await in here: the attempt count has to move with the comparison. */
+  spendCode(body) {
+    this.expireCode();
+    const armed = this.armedCode;
+    if (!armed) {
+      return {
+        ok: false,
+        code: "PAIRING_NOT_ARMED",
+        error: "No pairing code is armed. Arm one in the app, or pair over a cable."
+      };
+    }
+    const code = body?.code;
+    if (typeof code !== "string" || !/^\d{6}$/.test(code)) {
+      return {
+        ok: false,
+        code: "PAIRING_CODE_REQUIRED",
+        error: 'Send the 6-digit code shown in the app, as { "code": "123456" }.'
+      };
+    }
+    if (constantTimeEqual(armed.code, code)) {
+      this.armedCode = null;
+      this.heldCode = armed;
+      return null;
+    }
+    armed.wrongAttempts += 1;
+    if (armed.wrongAttempts >= PAIRING_CODE_MAX_ATTEMPTS) {
+      this.armedCode = null;
+      this.disarmReason = "attempts_exhausted";
+    }
+    return { ok: false, code: "PAIRING_CODE_INVALID", error: "That code is not correct." };
+  }
+  /** Either clock ends the code, so a clock set back cannot extend it. */
+  expireCode() {
+    if (!this.armedCode) return;
+    const { expiresAt, monotonicDeadline } = this.armedCode;
+    const monotonic = monotonicNow();
+    const monotonicExpired = monotonic !== null && monotonicDeadline !== null && monotonic >= monotonicDeadline;
+    if (Date.now() >= expiresAt || monotonicExpired) {
+      this.armedCode = null;
+      this.disarmReason = "expired";
+    }
+  }
+  /** Arm a fresh code, replacing any live one. */
+  async arm() {
+    const stored = await this.readToken();
+    if (stored === TOKEN_NOT_LOADED) {
+      throw new PairingError("PAIRING_UNAVAILABLE", "The pairing store is not available yet.");
+    }
+    const code = await this.drawCode();
+    const expiresAt = Date.now() + PAIRING_CODE_TTL_MS;
+    const monotonic = monotonicNow();
+    this.armedCode = {
+      code,
+      expiresAt,
+      monotonicDeadline: monotonic === null ? null : monotonic + PAIRING_CODE_TTL_MS,
+      wrongAttempts: 0
+    };
+    this.heldCode = null;
+    this.disarmReason = null;
+    this.consumedBy = null;
+    this.consumedAt = null;
+    return { code, expiresAt };
+  }
+  /** A uniform 6-digit code, by rejection sampling so that no digit is favoured. */
+  async drawCode() {
+    for (let attempt = 0; attempt < CODE_SAMPLE_ATTEMPTS; attempt++) {
+      const bytes = await this.randomBytes(4);
+      const value = new DataView(bytes.buffer, bytes.byteOffset, 4).getUint32(0);
+      if (value < CODE_SAMPLE_LIMIT) return String(value % 1e6).padStart(6, "0");
+    }
+    throw new PairingError(
+      "PAIRING_UNAVAILABLE",
+      "The secure random source returned no usable bytes."
+    );
+  }
+  /** Cancel a live code. */
+  disarm() {
+    this.dropCode("cancelled");
+  }
+  dropCode(reason) {
+    if (this.armedCode || this.heldCode) {
+      this.armedCode = null;
+      this.heldCode = null;
+      this.disarmReason = reason;
+    }
+  }
+  /**
+   * Replace the token, so every signature made with the old one stops verifying.
+   * If it cannot be replaced it is cleared. If that fails too, signatures and
+   * pairing stay refused until a revoke succeeds: the user asked for the old
+   * token to die, and a store that would not say so cannot be trusted to have
+   * done it.
+   *
+   * Nothing verifies from the moment this starts until it ends. The generation
+   * moves when it ends, whichever way, so a check that read the old token before
+   * then cannot admit its request afterwards. A request a check has already
+   * admitted runs to its end.
+   */
+  async revoke() {
+    this.revokesInFlight += 1;
+    this.dropCode("revoked");
+    try {
+      await this.exclusive(async () => {
+        const stored = await this.readStore();
+        if (stored === TOKEN_NOT_LOADED) {
+          throw new PairingError("PAIRING_UNAVAILABLE", "The pairing store is not available yet.");
+        }
+        try {
+          await this.mintAndStoreToken();
+          this.storeSuspect = false;
+        } catch {
+          try {
+            await bounded(() => this.store.clear());
+            this.storeSuspect = false;
+          } catch {
+            this.storeSuspect = true;
+          }
+          throw new PairingError("PAIRING_UNAVAILABLE", "The pairing token could not be replaced.");
+        }
+      });
+    } finally {
+      this.revokesInFlight -= 1;
+      this.tokenGeneration += 1;
+    }
+  }
+  /** What Settings shows. */
+  getState() {
+    this.expireCode();
+    return {
+      configured: true,
+      armed: this.armedCode !== null,
+      expiresAt: this.armedCode?.expiresAt ?? null,
+      attemptsRemaining: this.armedCode ? PAIRING_CODE_MAX_ATTEMPTS - this.armedCode.wrongAttempts : null,
+      consumedBy: this.consumedBy,
+      consumedAt: this.consumedAt,
+      disarmReason: this.disarmReason
+    };
+  }
+};
+var UNCONFIGURED_PAIRING_STATE = {
+  configured: false,
+  armed: false,
+  expiresAt: null,
+  attemptsRemaining: null,
+  consumedBy: null,
+  consumedAt: null,
+  disarmReason: null
+};
+function signedTarget(request) {
+  if (request.rawTarget === void 0) {
+    return Object.keys(request.query ?? {}).length === 0 ? request.path : null;
+  }
+  const queryAt = request.rawTarget.indexOf("?");
+  const path = queryAt === -1 ? request.rawTarget : request.rawTarget.slice(0, queryAt);
+  return path === request.path ? request.rawTarget : null;
+}
+function signedBody(request) {
+  if (request.rawBody !== void 0) return request.rawBody;
+  return request.body === void 0 ? "" : null;
+}
+
 // src/server/observability.ts
 var RingBuffer = class {
   constructor(capacity) {
@@ -3159,7 +3726,20 @@ function isUnsubscribe(msg) {
 var ERROR_CODE_HTTP_STATUS = /* @__PURE__ */ new Map([
   ["NOT_SUPPORTED", 501],
   ["NOT_FOUND", 404],
-  ["METHOD_NOT_ALLOWED", 405]
+  ["METHOD_NOT_ALLOWED", 405],
+  // Device pairing, all answered by the network entry. A 401 means this caller
+  // has not proved it may act; a 403 means proving it would change nothing; a 503
+  // means the phone cannot check yet.
+  ["PAIRING_REQUIRED", 401],
+  ["PAIRING_UNCONFIGURED", 401],
+  ["PAIRING_NOT_ARMED", 401],
+  ["PAIRING_CODE_INVALID", 401],
+  ["PAIRING_TIMESTAMP_REFUSED", 401],
+  ["PAIRING_WS_LOOPBACK_ONLY", 403],
+  ["PAIRING_WEB_CALLER_REFUSED", 403],
+  ["PAIRING_BODY_TOO_LARGE", 413],
+  ["PAIRING_TARGET_TOO_LONG", 414],
+  ["PAIRING_UNAVAILABLE", 503]
 ]);
 function httpStatusForResponse(response) {
   if (response.success) return 200;
@@ -3185,6 +3765,10 @@ function parsePath(pattern, actual) {
 var WS_ROUTES = [
   // Health
   { pattern: "health", handler: "health", httpMethods: ["GET"] },
+  // Device pairing. Always NOT_SUPPORTED from this table: the real route is in
+  // `handleNetworkRequest`, because route context carries no peer, and this
+  // entry is what JSON-RPC and the relay reach instead.
+  { pattern: "pair", handler: "pair", httpMethods: ["POST"] },
   // Elements
   { pattern: "control/elements", handler: "getElements", httpMethods: ["GET"] },
   // Flat alias — matches the runner UI Bridge's `/ui-bridge/elements` path so
@@ -3347,6 +3931,7 @@ function allowedMethodsForPath(path, testHooks) {
 }
 var HANDLER_DESCRIPTIONS = {
   health: "Liveness probe; returns app metadata + element count",
+  pair: "Get the pairing token: loopback with no code, otherwise body { code }. Direct HTTP only",
   getElements: "Flat list of registered UI elements",
   getElement: "Single element by id",
   getElementState: "Dynamic state (value, focused, checked) for one element",
@@ -3448,10 +4033,24 @@ function buildHelpPayload(testHooks) {
     ]
   };
 }
+var HEALTH_PATH = "/ui-bridge/health";
+var PAIR_PATH = "/ui-bridge/pair";
+function jsonRpcIdOf(rawMessage) {
+  try {
+    const id = JSON.parse(rawMessage)?.id;
+    return typeof id === "number" || typeof id === "string" ? id : 0;
+  } catch {
+    return 0;
+  }
+}
 var NativeUIBridgeServer = class {
   constructor(registry, executor, config = {}) {
     this.registry = registry;
     this.executor = executor;
+    /** Whether this run's adapter has called `onWebSocketUpgrade` at all. */
+    this.upgradeGateSeen = false;
+    /** Warned once per run rather than per request, which would flood the error ring. */
+    this.warnedMissingPeer = false;
     this.running = false;
     /**
      * Per-connection cleanup thunks for in-flight waiters (waitForElement,
@@ -3464,6 +4063,9 @@ var NativeUIBridgeServer = class {
       cors: true,
       ...config
     };
+    if (this.config.pairingStore) {
+      this.pairing = new PairingAuthority(this.config.pairingStore);
+    }
     this.consoleErrorBuffer = new ConsoleErrorBuffer();
     this.networkRequestBuffer = new NetworkRequestBuffer();
     if (this.config.appInfo) {
@@ -3509,6 +4111,14 @@ var NativeUIBridgeServer = class {
   setAdapter(adapter) {
     this.adapter = adapter;
   }
+  /**
+   * Set the device's stable id. An app usually loads it from storage after the
+   * server has started, and this spares it a restart that would drop every
+   * socket and any armed code.
+   */
+  setDeviceId(deviceId) {
+    this.config.deviceId = deviceId;
+  }
   /**
    * Set a navigation provider for programmatic route navigation.
    * This enables `control/page/navigate` and `control/page/back` on native.
@@ -3742,7 +4352,18 @@ var NativeUIBridgeServer = class {
       this.consoleErrorBuffer.install();
       this.networkRequestBuffer.install();
     }
-    await this.adapter.start(this.config.serverPort, this.handleRequest.bind(this));
+    this.upgradeGateSeen = false;
+    this.warnedMissingPeer = false;
+    if (this.config.allowUnauthenticatedNetwork) {
+      console.warn(
+        "[ui-bridge-native] allowUnauthenticatedNetwork is on: anyone who can reach this port can drive the app over HTTP."
+      );
+    } else if (!this.pairing) {
+      console.warn(
+        "[ui-bridge-native] No pairingStore configured: non-loopback callers are refused with PAIRING_UNCONFIGURED."
+      );
+    }
+    await this.adapter.start(this.config.serverPort, this.handleNetworkRequest.bind(this));
     this.running = true;
     console.log(`[ui-bridge-native] HTTP server started on port ${this.config.serverPort}`);
   }
@@ -3771,6 +4392,26 @@ var NativeUIBridgeServer = class {
   setEventBridge(bridge) {
     this.eventBridge = bridge;
   }
+  /**
+   * The entry a socket's messages come through. An adapter that never called
+   * `onWebSocketUpgrade` admitted the socket with no check, and a message carries
+   * no peer to check now, so it is refused: the same fail-closed reading as a
+   * missing peer address. An adapter that gates sees a call before its first socket.
+   */
+  async handleNetworkWebSocketMessage(connId, rawMessage) {
+    if (!this.upgradeGateSeen) {
+      return JSON.stringify({
+        id: jsonRpcIdOf(rawMessage),
+        result: {
+          success: false,
+          error: "This server adapter does not gate WebSocket upgrades (onWebSocketUpgrade).",
+          code: "PAIRING_UNCONFIGURED",
+          timestamp: Date.now()
+        }
+      });
+    }
+    return this.handleWebSocketMessage(connId, rawMessage);
+  }
   /**
    * Handle a JSON-RPC message from a WebSocket client.
    * Parses the message, routes to the appropriate handler, and returns
@@ -4299,21 +4940,272 @@ var NativeUIBridgeServer = class {
       timestamp: Date.now()
     };
   }
+  // ── Device pairing ──────────────────────────────────────────────────────
   /**
-   * Handle incoming HTTP request
+   * What `start()` hands the adapter: every request off the socket comes through
+   * here, and `handleRequest` sits behind it.
+   *
+   * | Caller                                                   | Admitted |
+   * |----------------------------------------------------------|----------|
+   * | Loopback peer, no web context, loopback `Host`           | yes      |
+   * | Anyone with a valid `X-UI-Bridge-Auth` signature         | yes      |
+   * | Anyone, `GET /ui-bridge/health` (trimmed)                | yes      |
+   * | Anyone with no web context, `POST /ui-bridge/pair`       | yes      |
+   * | A web page, `POST /ui-bridge/pair`                       | 403 `PAIRING_WEB_CALLER_REFUSED` |
+   * | Signature outside the window or below the floor          | 401 `PAIRING_TIMESTAMP_REFUSED` |
+   * | Signed body over `SIGNED_BODY_MAX_CHARS`                 | 413 `PAIRING_BODY_TOO_LARGE` |
+   * | Signed method or target over its cap                     | 414 `PAIRING_TARGET_TOO_LONG` |
+   * | Everyone else                                            | 401 `PAIRING_REQUIRED` |
+   * | No store configured, not loopback                        | 401 `PAIRING_UNCONFIGURED` |
+   * | Under `allowUnauthenticatedNetwork`, a web page or a rebindable `Host` | 403 `PAIRING_WEB_CALLER_REFUSED` |
+   *
+   * The gate is here rather than in `handleRequest` because `CloudRelayClient`
+   * calls that directly and must keep working: relay access already means the
+   * same user account, checked by the backend.
+   */
+  async handleNetworkRequest(request) {
+    try {
+      if (request.method === "POST" && request.path === PAIR_PATH) {
+        return await this.handlePair(request);
+      }
+      const admission = await this.admit(request);
+      if (request.method === "GET" && request.path === HEALTH_PATH) {
+        return await this.handleNetworkHealth(request, admission);
+      }
+      if (!admission.admitted) {
+        return this.refusal(admission.code, admission.error, { data: admission.data });
+      }
+      return await this.handleRequest(request);
+    } catch {
+      return this.refusal("INTERNAL_ERROR", "Internal server error", { status: 500 });
+    }
+  }
+  /**
+   * The WebSocket door: trusted loopback or nothing, whatever else the request
+   * carries. A signature covers no upgrade intent, so one swallowed GET re-sent
+   * with `Upgrade: websocket` would become a permanent control socket, and a socket
+   * outlives the signature's window. `allowUnauthenticatedNetwork` opens HTTP only,
+   * and no runner dials a device's socket.
+   */
+  handleWebSocketUpgrade(request) {
+    this.upgradeGateSeen = true;
+    if (this.isTrustedLoopback(request)) return { admit: true };
+    return {
+      admit: false,
+      response: this.refusal(
+        "PAIRING_WS_LOOPBACK_ONLY",
+        "WebSocket upgrades are accepted only from this machine. Use signed HTTP from anywhere else."
+      )
+    };
+  }
+  isTrustedLoopback(request) {
+    if (!request.remoteAddress && !this.warnedMissingPeer) {
+      this.warnedMissingPeer = true;
+      console.warn(
+        "[ui-bridge-native] A request arrived with no peer address and is treated as not loopback. The server adapter must pass remoteAddress."
+      );
+    }
+    return isTrustedLoopbackRequest(request);
+  }
+  async admit(request) {
+    if (this.isTrustedLoopback(request)) return { admitted: true, as: "loopback" };
+    if (this.config.allowUnauthenticatedNetwork) {
+      if (isWebReachableRequest(request)) {
+        return {
+          admitted: false,
+          code: "PAIRING_WEB_CALLER_REFUSED",
+          error: "A web page cannot drive this device."
+        };
+      }
+      return { admitted: true, as: "unauthenticated-network" };
+    }
+    if (!this.pairing) {
+      return {
+        admitted: false,
+        code: "PAIRING_UNCONFIGURED",
+        error: "This app has not configured device pairing, so it accepts only local callers."
+      };
+    }
+    const required = {
+      admitted: false,
+      code: "PAIRING_REQUIRED",
+      error: "This device requires pairing. Sign the request with the token from POST /ui-bridge/pair."
+    };
+    const signatures = headerValues(request.headers, UI_BRIDGE_AUTH_HEADER);
+    if (signatures.length !== 1) return required;
+    const verdict = await this.pairing.verifySignature(request, signatures[0]);
+    if (verdict === "valid") return { admitted: true, as: "signed" };
+    if (verdict === "store_unavailable") {
+      return {
+        admitted: false,
+        code: "PAIRING_UNAVAILABLE",
+        error: "The pairing store is not available yet. Try again."
+      };
+    }
+    if (verdict === "timestamp_refused") {
+      return {
+        admitted: false,
+        code: "PAIRING_TIMESTAMP_REFUSED",
+        error: "The signature timestamp is not acceptable. Re-sync to data.serverTime and sign again.",
+        data: { serverTime: Date.now() }
+      };
+    }
+    if (verdict === "body_too_large") {
+      return {
+        admitted: false,
+        code: "PAIRING_BODY_TOO_LARGE",
+        error: `A signed body may be at most ${SIGNED_BODY_MAX_CHARS} characters.`
+      };
+    }
+    if (verdict === "target_too_long") {
+      return {
+        admitted: false,
+        code: "PAIRING_TARGET_TOO_LONG",
+        error: `A signed target may be at most ${SIGNED_TARGET_MAX_CHARS} characters.`
+      };
+    }
+    return required;
+  }
+  corsHeaders() {
+    if (!this.config.cors) return {};
+    return {
+      "Access-Control-Allow-Origin": this.config.allowedOrigins ? this.config.allowedOrigins.join(",") : "*",
+      "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type, Authorization"
+    };
+  }
+  /** No CORS header: a page must not be able to read what the gate says. */
+  refusal(code, error3, extra = {}) {
+    const body = {
+      success: false,
+      error: error3,
+      code,
+      timestamp: Date.now(),
+      ...extra.data ? { data: extra.data } : {}
+    };
+    return {
+      status: extra.status ?? httpStatusForResponse(body),
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    };
+  }
+  /**
+   * Open health. An admitted caller gets the full answer. Anyone else gets what
+   * discovery needs and nothing about the app's contents, and that answer is
+   * built without going through `handleRequest`, whose keep-awake auto-arm is no
+   * business of an anonymous LAN probe. It carries no CORS header, so a web page
+   * cannot read the stable device id.
+   */
+  async handleNetworkHealth(request, admission) {
+    const pairing = {
+      required: !(admission.admitted && (admission.as === "loopback" || admission.as === "unauthenticated-network")),
+      authenticated: admission.admitted && admission.as !== "unauthenticated-network"
+    };
+    const identity = {
+      deviceId: this.config.deviceId ?? null,
+      serverTime: Date.now(),
+      pairing
+    };
+    if (admission.admitted) {
+      const response = await this.handleRequest(request);
+      const parsed = JSON.parse(response.body);
+      if (!parsed.success || !parsed.data) return response;
+      return {
+        ...response,
+        body: JSON.stringify({ ...parsed, data: { ...parsed.data, ...identity } })
+      };
+    }
+    const health = await this.handlers.health({ params: {}, query: {}, body: void 0 });
+    const full = health.data ?? {};
+    const trimmed = { status: full.status, ...identity };
+    if (full.uiBridge) {
+      const { version, appId, appName, appType, framework } = full.uiBridge;
+      trimmed.uiBridge = { version, appId, appName, appType, framework };
+    }
+    return {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ success: true, data: trimmed, timestamp: Date.now() })
+    };
+  }
+  /**
+   * `POST /ui-bridge/pair`, the only way to a token, and only ever from here.
+   * Its answer carries no CORS header, because no web page has any business
+   * reading a token, and it answers only after the store write has finished. A web
+   * page is refused first of all, so it cannot burn an attempt or the armed code.
+   */
+  async handlePair(request) {
+    if (carriesWebContext(request)) {
+      return this.refusal("PAIRING_WEB_CALLER_REFUSED", "A web page cannot pair with this device.");
+    }
+    if (!this.pairing) {
+      return this.refusal(
+        "PAIRING_UNCONFIGURED",
+        "This app has not configured device pairing, so it cannot issue a token."
+      );
+    }
+    const deviceId = this.config.deviceId;
+    if (!deviceId) {
+      return this.refusal("PAIRING_UNAVAILABLE", "The device id is not available yet. Try again.");
+    }
+    const outcome = await this.pairing.pair({
+      trustedLoopback: this.isTrustedLoopback(request),
+      peer: request.remoteAddress,
+      body: request.body
+    });
+    if (!outcome.ok) return this.refusal(outcome.code, outcome.error);
+    const body = {
+      success: true,
+      data: { token: outcome.token, deviceId, serverTime: Date.now() },
+      timestamp: Date.now()
+    };
+    return {
+      status: 200,
+      headers: { "Content-Type": "application/json", "Cache-Control": "no-store" },
+      body: JSON.stringify(body)
+    };
+  }
+  /**
+   * Arm a 6-digit code for a LAN pairing. In memory and single use. It stops
+   * working after about 2 minutes, or after 5 wrong attempts from anyone. Rejects
+   * with a `PairingError` when no store is configured or it has not loaded.
+   */
+  async armPairingCode() {
+    return this.requirePairing().arm();
+  }
+  /** Cancel a live code. */
+  disarmPairingCode() {
+    this.pairing?.disarm();
+  }
+  /** What Settings shows, including the peer that consumed the last code. */
+  getPairingState() {
+    return this.pairing?.getState() ?? UNCONFIGURED_PAIRING_STATE;
+  }
+  /**
+   * Replace the token, so every signature made with the old one stops verifying.
+   * There are no network sockets to close, because none is ever admitted.
+   */
+  async revokePairing() {
+    await this.requirePairing().revoke();
+  }
+  requirePairing() {
+    if (!this.pairing) {
+      throw new PairingError("PAIRING_UNCONFIGURED", "No pairingStore is configured.");
+    }
+    return this.pairing;
+  }
+  /**
+   * Handle incoming HTTP request, past the gate.
    *
    * Exposed as public so that CloudRelayClient can call it directly (without
-   * loopback TCP overhead) when processing tunneled requests.
+   * loopback TCP overhead) when processing tunneled requests. Anything reached
+   * from a socket goes through `handleNetworkRequest` first.
    */
   async handleRequest(request) {
     const headers = {
-      "Content-Type": "application/json"
+      "Content-Type": "application/json",
+      ...this.corsHeaders()
     };
-    if (this.config.cors) {
-      headers["Access-Control-Allow-Origin"] = this.config.allowedOrigins ? this.config.allowedOrigins.join(",") : "*";
-      headers["Access-Control-Allow-Methods"] = "GET, POST, PUT, DELETE, OPTIONS";
-      headers["Access-Control-Allow-Headers"] = "Content-Type, Authorization";
-    }
     if (request.method === "OPTIONS") {
       return { status: 204, headers, body: "" };
     }
@@ -5107,6 +5999,6 @@ async function bindWithRetry(attempt, options = {}) {
   }
 }
 
-export { ConsoleErrorBuffer, NATIVE_PAGE_HEALTH_PRODUCER_ID, NativeUIBridgeServer, NetworkRequestBuffer, OPCODE_BINARY, OPCODE_CLOSE, OPCODE_CONTINUATION, OPCODE_PING, OPCODE_PONG, OPCODE_TEXT, Observation, ObservationError, UI_BRIDGE_NATIVE_ROUTES, UNKNOWN_CODES, WebSocketConnection, WebSocketEventBridge, bindWithRetry, buildUpgradeResponse, computeAcceptKey, createDesignHandlers, createNativeServer, createServerHandlers, decodeFrames, decodeTextPayload, diagnosePageHealth, encodeCloseFrame, encodePingFrame, encodePongFrame, encodeTextFrame, httpStatusForResponse, isAddrInUseError, isBatchRequest, isSubscribe, isUnknownCode, isUnsubscribe, pageHealthUnknown };
+export { ConsoleErrorBuffer, NATIVE_PAGE_HEALTH_PRODUCER_ID, NativeUIBridgeServer, NetworkRequestBuffer, OPCODE_BINARY, OPCODE_CLOSE, OPCODE_CONTINUATION, OPCODE_PING, OPCODE_PONG, OPCODE_TEXT, Observation, ObservationError, PAIRING_CODE_MAX_ATTEMPTS, PAIRING_CODE_TTL_MS, PairingAuthority, PairingError, SIGNATURE_WINDOW_MS, SIGNED_BODY_MAX_CHARS, SIGNED_METHOD_MAX_CHARS, SIGNED_TARGET_MAX_CHARS, UI_BRIDGE_AUTH_HEADER, UI_BRIDGE_NATIVE_ROUTES, UNCONFIGURED_PAIRING_STATE, UNKNOWN_CODES, WebSocketConnection, WebSocketEventBridge, bindWithRetry, buildUpgradeResponse, canonicalSignatureInput, carriesWebContext, computeAcceptKey, createDesignHandlers, createNativeServer, createServerHandlers, decodeFrames, decodeTextPayload, diagnosePageHealth, encodeCloseFrame, encodePingFrame, encodePongFrame, encodeTextFrame, headerValues, httpStatusForResponse, isAddrInUseError, isBatchRequest, isLoopbackAddress, isLoopbackHost, isSubscribe, isTrustedLoopbackRequest, isUnknownCode, isUnrebindableHost, isUnsubscribe, isWebReachableRequest, pageHealthUnknown, signUIBridgeRequest };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map