bmad-kanban 0.2.0 → 0.2.1

package/README.md

@@ -66,6 +66,19 @@ npm run build     # dist/cli.js and dist/web
 npm run test:e2e  # Playwright smoke test; run the build first
 ```
 
+### Releasing
+
+1. `npm version <patch|minor|major>` and `git push --follow-tags`.
+2. Create a GitHub release for the new tag (`gh release create vX.Y.Z`).
+
+3. Approve the staged version on npmjs.com (or `npm stage list` then `npm stage approve <id>`); this asks for your 2FA.
+
+Publishing the release runs `.github/workflows/release.yml`, which tests the package and *stages* it on npm through trusted publishing, so there is no npm token to manage. A staged version is not public until a maintainer approves it, so nothing reaches npm without the maintainer's 2FA. Don't run `npm publish` locally.
+
+## Contributing
+
+Contributions are welcome as pull requests. CI must pass, and the maintainer reviews and merges every change; releases to npm are made by the maintainer only.
+
 ## Acknowledgements
 
 Inspired by [vscode-bmad-kanban](https://github.com/RianKhanafi/vscode-bmad-kanban) by RianKhanafi.

package/dist/instance.js

@@ -1,6 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { newToken, proof, sameSecret } from './token.js';
 export function readLock(file) {
     try {
         const v = JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -33,7 +34,7 @@ export function loadToken(file) {
     catch {
         // missing: create it below
     }
-    const token = randomBytes(32).toString('base64url');
+    const token = newToken();
     fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
     const tmp = `${file}.${process.pid}.tmp`;
     fs.rmSync(tmp, { force: true });
@@ -61,14 +62,13 @@ function pidAlive(pid) {
         return e.code === 'EPERM';
     }
 }
+/** True when the board on the lock's port proves it holds the lock's token; the token itself is not sent. */
 async function answers(lock) {
+    const nonce = randomBytes(16).toString('hex');
     try {
-        const res = await fetch(`http://127.0.0.1:${lock.port}/api/state`, {
-            headers: { Authorization: `Bearer ${lock.token}` },
-            signal: AbortSignal.timeout(1000),
-        });
-        await res.arrayBuffer();
-        return res.status === 200;
+        const res = await fetch(`http://127.0.0.1:${lock.port}/api/hello?nonce=${nonce}`, { signal: AbortSignal.timeout(1000) });
+        const body = (await res.json());
+        return res.status === 200 && typeof body.proof === 'string' && sameSecret(body.proof, proof(lock.token, nonce));
     }
     catch {
         return false;

package/dist/server/app.js

@@ -1,9 +1,9 @@
-import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import { getStoryDetail, listSources, readBoard, UnknownSourceError, UnknownStoryError } from '../readers/detect.js';
 import { NotABmadProjectError } from '../registry.js';
+import { newToken, proof, sameSecret } from '../token.js';
 import { watchProject } from './watch.js';
 class HttpError extends Error {
     status;
@@ -22,8 +22,6 @@ const TYPES = {
     '.ico': 'image/x-icon',
 };
 const isMissing = (p) => !fs.existsSync(path.join(p.path, '_bmad'));
-const digest = (s) => createHash('sha256').update(s).digest();
-const sameToken = (a, b) => timingSafeEqual(digest(a), digest(b));
 async function summarize(p, read) {
     const base = { id: p.id, name: p.name, path: p.path, prefs: { ...p.prefs } };
     if (isMissing(p)) {
@@ -39,7 +37,7 @@ async function summarize(p, read) {
 }
 export function startServer(opts) {
     const { registry, webRoot } = opts;
-    const token = opts.token ?? randomBytes(32).toString('base64url');
+    const token = opts.token ?? newToken();
     const read = { scripts: opts.scripts !== false };
     const watchers = new Map();
     const clients = new Set();
@@ -158,6 +156,13 @@ export function startServer(opts) {
                 throw new HttpError(405, 'Method not allowed');
             return serveStatic(urlPath, res);
         }
+        // needs no token: it proves this board holds one without revealing it
+        if (seg[1] === 'hello' && seg.length === 2 && method === 'GET') {
+            const nonce = new URLSearchParams(query).get('nonce') ?? '';
+            if (!/^[0-9a-f]{32,128}$/.test(nonce))
+                throw new HttpError(400, 'nonce must be 32 to 128 hex characters');
+            return sendJson(res, 200, { proof: proof(token, nonce) });
+        }
         // EventSource cannot send headers, so the event stream also takes ?token=
         const auth = req.headers.authorization;
         const given = auth?.startsWith('Bearer ')
@@ -165,7 +170,7 @@ export function startServer(opts) {
             : seg[1] === 'events'
                 ? new URLSearchParams(query).get('token')
                 : null;
-        if (given === null || !sameToken(given, token)) {
+        if (given === null || !sameSecret(given, token)) {
             throw new HttpError(401, 'Missing or wrong access token: open the board with the bmad-kanban command');
         }
         if (seg[1] === 'events' && seg.length === 2 && method === 'GET') {

package/dist/token.js

@@ -0,0 +1,11 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+export const newToken = () => randomBytes(32).toString('base64url');
+const digest = (s) => createHash('sha256').update(s).digest();
+/** Constant-time string comparison. */
+export const sameSecret = (a, b) => timingSafeEqual(digest(a), digest(b));
+/**
+ * What a board holding `token` answers to the challenge `nonce`. The CLI checks it
+ * before trusting a port from the lock file, so the token is never sent to whatever
+ * else might be listening there.
+ */
+export const proof = (token, nonce) => createHmac('sha256', token).update(`bmad-kanban:${nonce}`).digest('hex');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-kanban",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Read-only local Kanban board for BMAD Method projects (v6 and v7 layouts)",
   "type": "module",
   "license": "MIT",