@twinsearth/w2m-dsh-plugin 1.1.2 → 1.1.14

package/src/relay/join-challenge.mjs

@@ -0,0 +1,92 @@
+/**
+ * The exchange that lets an UNPAIRED machine prove an account it cannot authenticate as a device.
+ *
+ * ## The shape
+ *
+ *   1. the machine asks for a challenge, naming the account fingerprint;
+ *   2. the relay answers with a one-time nonce and an expiry;
+ *   3. the machine signs \`challenge|nonce|fingerprint|machine_id\` with the account's derived private key;
+ *   4. the relay verifies with the public key registered when that account's first machine paired.
+ *
+ * ## The three properties, and why each is a test
+ *
+ * - **One-time.** A challenge is consumed by the first attempt, success or failure, because a retryable nonce is a replay
+ *   window. Consuming on failure means an attacker who guessed wrong must fetch a new challenge -- which is rate limited.
+ * - **Expiring.** Five minutes, on the relay's clock. A nonce that lives for ever is a signature that can be reused at
+ *   leisure.
+ * - **Rate limited per fingerprint.** Not per address: the thing being protected is a fingerprint, and an attacker with
+ *   many addresses must not get many guesses.
+ *
+ * The signature payload binds the machine_id as well as the fingerprint: a valid signature harvested for one machine must
+ * not admit another.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { verifyChallenge } from '../util/account-identity.mjs';
+
+export const CHALLENGE_TTL_MS = 5 * 60 * 1000;
+export const CHALLENGE_MAX_PER_MINUTE = 5;
+
+/**
+ * @param {{now?: () => number, ttlMs?: number, maxPerMinute?: number,
+ *          publicKeyFor: (fingerprint: string) => (string|null)}} options
+ */
+export function createJoinChallenges(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now();
+  const ttlMs = Number.isInteger(options.ttlMs) ? options.ttlMs : CHALLENGE_TTL_MS;
+  const maxPerMinute = Number.isInteger(options.maxPerMinute) ? options.maxPerMinute : CHALLENGE_MAX_PER_MINUTE;
+  const publicKeyFor = typeof options.publicKeyFor === 'function' ? options.publicKeyFor : () => null;
+
+  /** challenge_id -> { fingerprint, nonce, expires_at_ms } */
+  const open = new Map();
+  /** fingerprint -> [issue times] */
+  const issued = new Map();
+
+  const prune = () => {
+    const t = now();
+    for (const [id, c] of open) if (c.expires_at_ms <= t) open.delete(id);
+  };
+
+  /** The exact bytes signed. Exported so the client and the tests cannot drift from the relay. */
+  const signingPayload = (challenge) => [challenge.challenge_id, challenge.nonce, challenge.fingerprint, challenge.machine_id].join('|');
+
+  function issue(fingerprint, machineId = '') {
+    if (typeof fingerprint !== 'string' || fingerprint === '') return { ok: false, code: 'BAD_FINGERPRINT' };
+    if (publicKeyFor(fingerprint) === null) return { ok: false, code: 'FINGERPRINT_UNREGISTERED' };
+    prune();
+    const recent = (issued.get(fingerprint) ?? []).filter((at) => now() - at < 60_000);
+    if (recent.length >= maxPerMinute) { issued.set(fingerprint, recent); return { ok: false, code: 'RATE_LIMITED' }; }
+    recent.push(now());
+    issued.set(fingerprint, recent);
+    const challenge_id = createHash('sha256').update(fingerprint).update(String(randomBytes(16).toString('hex'))).update(String(now())).digest('hex').slice(0, 32);
+    const challenge = {
+      challenge_id, nonce: randomBytes(16).toString('hex'), fingerprint,
+      machine_id: typeof machineId === 'string' ? machineId : '', expires_at_ms: now() + ttlMs,
+    };
+    open.set(challenge_id, challenge);
+    return { ok: true, challenge_id, nonce: challenge.nonce, expires_at_ms: challenge.expires_at_ms };
+  }
+
+  /**
+   * Verify a signed challenge. Consumes the challenge on ANY attempt.
+   *
+   * @param {{challenge_id: string, machine_id: string, signature: string}} request
+   * @returns {{ok: true, fingerprint: string} | {ok: false, code: string}}
+   */
+  function consume(request) {
+    prune();
+    const challenge = open.get(request?.challenge_id);
+    if (challenge === undefined) return { ok: false, code: 'CHALLENGE_INVALID' };
+    open.delete(challenge.challenge_id);   // one attempt, success or not
+    if (challenge.expires_at_ms <= now()) return { ok: false, code: 'CHALLENGE_EXPIRED' };
+    if (typeof request.machine_id !== 'string' || request.machine_id === '') return { ok: false, code: 'BAD_REQUEST' };
+    // The machine that signs must be the machine that asked: issuing for one id and signing for another is a forgery.
+    if (challenge.machine_id !== '' && challenge.machine_id !== request.machine_id) return { ok: false, code: 'MACHINE_MISMATCH' };
+    const pem = publicKeyFor(challenge.fingerprint);
+    if (pem === null) return { ok: false, code: 'FINGERPRINT_UNREGISTERED' };
+    const payload = signingPayload({ ...challenge, machine_id: request.machine_id });
+    if (verifyChallenge(pem, payload, request.signature) !== true) return { ok: false, code: 'SIGNATURE_INVALID' };
+    return { ok: true, fingerprint: challenge.fingerprint };
+  }
+
+  return { issue, consume, signingPayload, _open: open };
+}

package/src/relay/server.mjs

@@ -22,6 +22,8 @@ import {
   RabbitState,
   rfc3339,
 } from './state.mjs';
+import { createJoinChallenges } from './join-challenge.mjs';
+import { createAdmission } from './admission.mjs';
 import { Persistence } from './persistence.mjs';
 import { PeerRegistry } from './peers.mjs';
 import { aggregateTask, buildReport } from './report.mjs';
@@ -733,6 +735,25 @@ export class RelayServer {
       return sendJson(res, 200, result);
     }
 
+    /* ---- v1.1.6: reachable WITHOUT a device token ---- */
+    this.joinChallenges ??= createJoinChallenges({
+      now: () => this.state.nowMs(),
+      publicKeyFor: (fingerprint) => this.state.accountKeyFor(fingerprint),
+    });
+    if (method === 'GET' && path === '/v1/fleet/admission/challenge') {
+      const issued = this.joinChallenges.issue(url.searchParams.get('fingerprint') ?? '', url.searchParams.get('machine_id') ?? '');
+      if (issued.ok !== true) throw new ProtocolError('BAD_REQUEST', 'challenge refused: ' + issued.code, { code: issued.code });
+      return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...issued });
+    }
+    if (method === 'POST' && path === '/v1/fleet/admission/request') {
+      const body = takeJson();
+      this.admission ??= createAdmission({ now: () => this.state.nowMs() });
+      const proof = this.joinChallenges.consume({ challenge_id: body.challenge_id, machine_id: body.machine_id, signature: body.signature });
+      if (proof.ok !== true) throw new ProtocolError('UNAUTHORIZED', 'join proof refused: ' + proof.code, { code: proof.code });
+      const result = this.admission.requestAdmission({ machine_id: body.machine_id, machine_name: body.machine_name ?? null, account_fingerprint: proof.fingerprint });
+      return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...result });
+    }
+
     /* ---- everything below requires `Authorization: Bearer <device_token>` ---- */
     const token = bearerToken(req);
     const device = token ? this.state.authenticate(token) : null;
@@ -889,6 +910,11 @@ export class RelayServer {
     // v0.3.9: P2P candidate rendezvous. `/announce` is checked before the read route
     // so that a machine literally named "announce" cannot shadow it.
     const peerReadMatch = /^\/v1\/peer\/([^/]+)$/.exec(path);
+    /* ---- v1.1.6 admission ---- */
+    const admissionDecideMatch = /^\/v1\/fleet\/admission\/([^/]+)\/decide$/.exec(path);
+    const admissionOneMatch = /^\/v1\/fleet\/admission\/([^/]+)$/.exec(path);
+    const memberRemoveMatch = /^\/v1\/fleet\/members\/([^/]+)\/remove$/.exec(path);
+    const removalVoteMatch = /^\/v1\/fleet\/removals\/([^/]+)\/vote$/.exec(path);
 
     /* ---- v0.3.9 P2P signalling ---- */
     if (method === 'POST' && path === '/v1/peer/announce') {
@@ -967,6 +993,50 @@ export class RelayServer {
       });
     }
 
+
+    /* ---- v1.1.6 admission: the caller is always `device.machine_id`, never a body field ---- */
+    this.admission ??= createAdmission({ now: () => this.state.nowMs() });
+
+    if (method === 'GET' && path === '/v1/fleet/admission/pending') {
+      return sendJson(res, 200, {
+        protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(),
+        pending: this.admission.pendingFor(),
+      });
+    }
+
+    if (method === 'POST' && admissionDecideMatch) {
+      const body = takeJson();
+      const result = this.admission.decide(decodeURIComponent(admissionDecideMatch[1]), {
+        decision: body.decision, decided_by: device.machine_id, auto: body.auto === true,
+      });
+      if (result.ok !== true) throw new ProtocolError('BAD_REQUEST', 'admission decision refused: ' + result.code, result);
+      return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...result });
+    }
+
+    if (method === 'GET' && admissionOneMatch) {
+      const request = this.admission.getRequest(decodeURIComponent(admissionOneMatch[1]));
+      if (request === null) throw new ProtocolError('NOT_FOUND', 'unknown admission request');
+      return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), request });
+    }
+
+    if (method === 'POST' && memberRemoveMatch) {
+      const body = takeJson();
+      const result = this.admission.remove(decodeURIComponent(memberRemoveMatch[1]), {
+        requested_by: device.machine_id, reason: typeof body.reason === 'string' ? body.reason : null,
+      });
+      if (result.ok !== true) throw new ProtocolError('BAD_REQUEST', 'removal refused: ' + result.code, result);
+      return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...result });
+    }
+
+    if (method === 'POST' && removalVoteMatch) {
+      const body = takeJson();
+      const result = this.admission.vote(decodeURIComponent(removalVoteMatch[1]), {
+        machine_id: device.machine_id, vote: body.vote,
+      });
+      if (result.ok !== true) throw new ProtocolError('BAD_REQUEST', 'vote refused: ' + result.code, result);
+      return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...result });
+    }
+
     throw new ProtocolError('NOT_FOUND', `no route for ${method} ${path}`, { method, path });
   }
 

package/src/relay/state.mjs

@@ -876,6 +876,31 @@ export class RabbitState {
   }
 
   /** §2.2 step 3: validate a one-time code. */
+  /**
+   * The account fingerprint -> public key registry (v1.1.6).
+   *
+   * Keyed by the FINGERPRINT, not by machine: every machine on one account shares the derived keypair, and the point of
+   * the registry is to answer "which key speaks for this account", once, for all of them.
+   *
+   * @returns {{registered: boolean, reason?: string}}
+   */
+  registerAccountKey(fingerprint, publicKeyPem) {
+    if (typeof fingerprint !== 'string' || fingerprint === '') return { registered: false, reason: 'BAD_FINGERPRINT' };
+    if (typeof publicKeyPem !== 'string' || publicKeyPem === '') return { registered: false, reason: 'BAD_PUBLIC_KEY' };
+    this.accountKeys ??= new Map();
+    const existing = this.accountKeys.get(fingerprint);
+    if (existing !== undefined) {
+      return { registered: false, reason: existing === publicKeyPem ? 'ALREADY_REGISTERED' : 'KEY_MISMATCH' };
+    }
+    this.accountKeys.set(fingerprint, publicKeyPem);
+    return { registered: true };
+  }
+
+  /** @returns {string|null} the key that speaks for this account, or null if no machine ever paired for it. */
+  accountKeyFor(fingerprint) {
+    return this.accountKeys?.get(fingerprint) ?? null;
+  }
+
   validatePairingCode(code) {
     if (typeof code !== 'string' || code.length === 0) {
       throw new ProtocolError('PAIRING_INVALID', 'pairing_code is required');
@@ -987,6 +1012,27 @@ export class RabbitState {
     };
     this.devices.set(machineId, device);
     this.tokens.set(token, machineId);
+
+    /**
+     * v1.1.6: register the account's signing key while we have proof of the account.
+     *
+     * A machine that failed the old joining path must later prove the account to the relay. It can only do that against
+     * a key the relay already trusts, and the only moment the relay has real proof ("this machine holds the account
+     * material") is a successful pairing. So this is the trust anchor, and it is written HERE rather than at
+     * registration time to keep the two paths honest: no pairing, no key.
+     *
+     * Idempotent on purpose: the first machine to pair for a fingerprint fixes the key. A second machine claiming the
+     * same fingerprint with a DIFFERENT key is not silently accepted -- the registration is refused and reported, and
+     * changing a key needs the fleet vote the removal flow already provides.
+     */
+    const accountFingerprint = typeof request.account_fingerprint === 'string' ? request.account_fingerprint : '';
+    const accountPublicKey = typeof request.account_public_key === 'string' ? request.account_public_key : '';
+    const accountKey = accountFingerprint !== '' && accountPublicKey !== ''
+      ? this.registerAccountKey(accountFingerprint, accountPublicKey)
+      : null;
+    // Recorded on the device, not just discarded: a second machine claiming the same account with a different key is
+    // refused, and the refusal must be visible in devices.json rather than looking like a successful registration.
+    device.account_key = accountKey;
     rec.used = true;
 
     // A group has more than one machine, and a single-use code would leave the

package/src/util/account-identity.mjs

@@ -0,0 +1,75 @@
+/**
+ * The account's own signing key.
+ *
+ * ## Why this exists
+ *
+ * A fleet key is a **symmetric** secret: it proves "this machine is allowed into the fleet derived from this account",
+ * and it is the only account material the system had. That is enough for the old joining path and not enough for the
+ * new one -- a machine that failed to pair must *prove the account* to a relay that has never met it, and proof of that
+ * kind is a signature.
+ *
+ * So the account gains an asymmetric identity. It is DERIVED, not generated: the same account material yields the same
+ * keypair on every machine, which is what makes "zero configuration" possible at all -- a fresh install can sign with
+ * an identity nobody had to copy onto it. The matching public key is registered with the relay when the account's first
+ * machine pairs (see the relay's account-key registry), and later machines are verified against it.
+ *
+ * ## Ed25519 from a seed, without a new dependency
+ *
+ * Node can import an Ed25519 private key from PKCS#8 DER, and PKCS#8 for Ed25519 is a fixed 16-byte prefix followed by
+ * the 32-byte seed. That is the whole construction; no library, and the output is the standard RFC 8032 key, so any
+ * other verifier accepts it.
+ *
+ * The derivation domain-separates with a label, so a seed reused elsewhere cannot accidentally produce this key.
+ */
+import { createHash, createPrivateKey, createPublicKey, sign as signWith, verify as verifyWith } from 'node:crypto';
+
+/** PKCS#8 prefix for Ed25519: OID 1.3.101.112 inside a OneAsymmetricKey with the seed as the private key. */
+const ED25519_PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+/** Domain separation: this key exists only for fleet joining. */
+const LABEL = 'w2m-account-identity-v1';
+
+/**
+ * @param {string|Buffer} accountMaterial the account's stable material (never sent anywhere by this function)
+ * @returns {{privateKey: import('node:crypto').KeyObject, publicKey: import('node:crypto').KeyObject,
+ *            publicKeyPem: string, fingerprint: string}}
+ */
+export function deriveAccountKeypair(accountMaterial) {
+  if (typeof accountMaterial !== 'string' && !Buffer.isBuffer(accountMaterial)) {
+    throw new TypeError('accountMaterial must be a string or a Buffer');
+  }
+  const material = Buffer.isBuffer(accountMaterial) ? accountMaterial : Buffer.from(accountMaterial, 'utf8');
+  if (material.length === 0) throw new TypeError('accountMaterial must not be empty');
+  // Derive a 32-byte seed; the label is part of the input so this cannot collide with another use of the same material.
+  const seed = createHash('sha256').update(LABEL).update(Buffer.from([0x00])).update(material).digest();
+  const privateKey = createPrivateKey({
+    key: Buffer.concat([ED25519_PKCS8_PREFIX, seed]),
+    format: 'der',
+    type: 'pkcs8',
+  });
+  const publicKey = createPublicKey(privateKey);
+  const publicKeyDer = publicKey.export({ type: 'spki', format: 'der' });
+  return {
+    privateKey,
+    publicKey,
+    publicKeyPem: publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+    // The fingerprint IS the public key, identified by hash: a relay can verify a signature against the key it holds
+    // and check that the hash matches, with no registration of the account anywhere.
+    fingerprint: createHash('sha256').update(publicKeyDer).digest('hex'),
+  };
+}
+
+/** Sign the challenge payload. The relay verifies; nothing here decides policy. */
+export function signChallenge(identity, payload) {
+  const data = typeof payload === 'string' ? Buffer.from(payload, 'utf8') : Buffer.from(payload);
+  return signWith(null, data, identity.privateKey).toString('base64');
+}
+
+/** Verify a signature against a PEM public key. Returns a boolean: a thrown error here would be a 500 for a bad login. */
+export function verifyChallenge(publicKeyPem, payload, signatureBase64) {
+  const data = typeof payload === 'string' ? Buffer.from(payload, 'utf8') : Buffer.from(payload);
+  try {
+    return verifyWith(null, data, createPublicKey(publicKeyPem), Buffer.from(String(signatureBase64), 'base64'));
+  } catch {
+    return false;
+  }
+}