@andespindola/brainlink 1.6.11 → 1.6.13

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.6.13
+
+- **Admin impersonation for the exposed graph.** New opt-in `GET /api/admin-session?token=<jwt>` on `brainlink server --expose`: a control-plane can open a tenant's graph authenticated WITHOUT the web password by presenting a short-lived HS256 JWT signed with `BRAINLINK_ADMIN_SESSION_SECRET` (claims bind `sub`/`aud` to the server's web user; `exp` ≤ 600s). Off by default — when the secret is unset the endpoint 404s and nothing changes. On success it mints the same session cookie as `/api/login` and redirects to `/`.
+
+## 1.6.12
+
+- **Wiki links keep a `#` that is part of the title.** A link target such as `[[note (PR #34)]]` was truncated at the `#` — the parser always treated `#` as the start of a heading anchor (`[[Note#Heading]]`) — so the link resolved to a non-existent `note (PR ` title and surfaced as a broken link. A `#` is now treated as a heading anchor only when it directly follows the note name with no whitespace before it; a `#` preceded by a space is kept as part of the title. Existing `[[Note#Heading]]` anchor links keep resolving to `Note`.
+
 ## 1.6.1
 
 - **Fix the broken README logo on npm.** The logo was referenced via a `raw.githubusercontent.com` URL, which returns 404 for anonymous requests because the source repository is private — so it never rendered on the npm package page. Point it at the public npm CDN (`cdn.jsdelivr.net/npm/...`), which serves the published package's assets regardless of repository visibility, and refresh the brain-as-a-graph artwork.

package/dist/application/server/admin-session.js

@@ -0,0 +1,125 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+// Admin impersonation for the exposed graph server.
+//
+// An external control-plane (the brainlink-saas admin) can open a tenant's
+// graph authenticated WITHOUT the tenant's web password by redirecting the
+// admin's browser to `GET /api/admin-session?token=<jwt>`. The token is a
+// short-lived, compact HS256 JWT that the server verifies against a shared
+// secret. This is OPT-IN and OFF by default: with no secret configured the
+// endpoint is disabled and nothing about the existing auth changes.
+//
+// Token contract (so the SaaS can mint compatible tokens):
+//   - Format: compact JWT `base64url(header).base64url(payload).base64url(sig)`.
+//   - Header:  { "alg": "HS256", "typ": "JWT" } — alg MUST be HS256.
+//   - Payload claims:
+//       - `sub` and/or `aud`: MUST equal the server's configured web user
+//         (BRAINLINK_WEB_USER). At least one must be present and match — this
+//         binds the token to THIS tenant so it cannot be replayed elsewhere.
+//       - `iat`: issued-at, seconds since epoch.
+//       - `exp`: expiry, seconds since epoch. REQUIRED, must be in the future,
+//         and MUST be within `maxTtlSeconds` (600s) of `iat` — long-lived
+//         tokens are rejected server-side.
+//   - Signature: HMAC-SHA256 over `base64url(header).base64url(payload)` using
+//     the raw UTF-8 bytes of BRAINLINK_ADMIN_SESSION_SECRET.
+export const ADMIN_SESSION_SECRET_ENV = 'BRAINLINK_ADMIN_SESSION_SECRET';
+// Server-side cap on how far in the future an admin token may be valid. A token
+// whose lifetime (exp - iat) exceeds this is rejected regardless of signature.
+export const adminSessionMaxTtlSeconds = 600;
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+// The signing secret for admin impersonation, or null when the feature is
+// disabled (no secret configured). Read from env exactly like the other
+// exposed-server auth material, so no new wiring through the CLI is required.
+export const getAdminSessionSecret = () => {
+    const secret = process.env[ADMIN_SESSION_SECRET_ENV]?.trim();
+    return isNonEmptyString(secret) ? secret : null;
+};
+const constantTimeEqual = (a, b) => {
+    const actual = Buffer.from(a, 'utf8');
+    const expected = Buffer.from(b, 'utf8');
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+};
+const parseHeader = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return null;
+    }
+    const candidate = value;
+    return isNonEmptyString(candidate.alg) ? { alg: candidate.alg } : null;
+};
+const parseClaims = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return null;
+    }
+    const candidate = value;
+    if (typeof candidate.iat !== 'number' || typeof candidate.exp !== 'number') {
+        return null;
+    }
+    if (!Number.isFinite(candidate.iat) || !Number.isFinite(candidate.exp)) {
+        return null;
+    }
+    const sub = isNonEmptyString(candidate.sub) ? candidate.sub : undefined;
+    const aud = isNonEmptyString(candidate.aud) ? candidate.aud : undefined;
+    return {
+        ...(sub === undefined ? {} : { sub }),
+        ...(aud === undefined ? {} : { aud }),
+        iat: candidate.iat,
+        exp: candidate.exp
+    };
+};
+const decodeSegment = (segment) => {
+    const json = Buffer.from(segment, 'base64url').toString('utf8');
+    return JSON.parse(json);
+};
+// Verify a compact HS256 admin-session token. Returns true only when the
+// signature is valid, the algorithm is HS256, the token is bound to
+// `expectedUser` via `sub`/`aud`, it is unexpired, and its lifetime is within
+// the server-side cap. Never throws and never leaks token/secret detail.
+export const verifyAdminSessionToken = (token, secret, expectedUser, nowMs, maxTtlSeconds = adminSessionMaxTtlSeconds) => {
+    try {
+        if (!isNonEmptyString(token) || !isNonEmptyString(secret) || !isNonEmptyString(expectedUser)) {
+            return false;
+        }
+        const parts = token.split('.');
+        if (parts.length !== 3) {
+            return false;
+        }
+        const [headerB64, payloadB64, signature] = parts;
+        if (!isNonEmptyString(headerB64) || !isNonEmptyString(payloadB64) || !isNonEmptyString(signature)) {
+            return false;
+        }
+        const header = parseHeader(decodeSegment(headerB64));
+        if (header === null || header.alg !== 'HS256') {
+            return false;
+        }
+        const expectedSignature = createHmac('sha256', secret)
+            .update(`${headerB64}.${payloadB64}`)
+            .digest('base64url');
+        if (!constantTimeEqual(signature, expectedSignature)) {
+            return false;
+        }
+        const claims = parseClaims(decodeSegment(payloadB64));
+        if (claims === null) {
+            return false;
+        }
+        // Bind the token to this server's web user: at least one of sub/aud must be
+        // present and equal to the configured user, so a token minted for one tenant
+        // cannot authenticate a different tenant's server.
+        const audienceMatches = (claims.sub !== undefined && constantTimeEqual(claims.sub, expectedUser)) ||
+            (claims.aud !== undefined && constantTimeEqual(claims.aud, expectedUser));
+        if (!audienceMatches) {
+            return false;
+        }
+        // exp must be present, in the future, and the token lifetime must not exceed
+        // the server-side cap (reject long-lived tokens even if correctly signed).
+        const nowSeconds = Math.floor(nowMs / 1000);
+        if (claims.exp <= nowSeconds) {
+            return false;
+        }
+        if (claims.exp - claims.iat > maxTtlSeconds) {
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+};

package/dist/application/server/routes.js

@@ -24,6 +24,7 @@ import { createClientWorkerJs } from '../frontend/client-worker-js.js';
 import { createClientRenderWorkerJs } from '../frontend/client-render-worker-js.js';
 import { createLoginPageHtml, createChangePasswordPageHtml } from '../frontend/login-page.js';
 import { buildClearSessionCookie, buildSessionSetCookie, changeWebPassword, createSessionToken, parseCookies, resolveWebAuth, SESSION_COOKIE_NAME, verifySessionToken, verifyWebPassword } from './web-auth.js';
+import { getAdminSessionSecret, verifyAdminSessionToken } from './admin-session.js';
 import { getGraphVersion } from './graph-version.js';
 import { readAuthStatus, readEditableSettings, updateEditableSettings } from './settings-store.js';
 import { connectVaultRemote, ensureDeployKey, readVersioningStatus } from './versioning.js';
@@ -124,6 +125,26 @@ const runAuthGate = async (request, url) => {
         }
         return createResponse(createJsonResponse({ error: 'Invalid username or password' }), 401, contentTypes['.json']);
     }
+    // Admin impersonation (opt-in, off by default). When BRAINLINK_ADMIN_SESSION_SECRET
+    // is configured, an external control-plane can open this tenant's graph by
+    // redirecting the admin's browser to /api/admin-session?token=<jwt>. A valid,
+    // short-lived, audience-bound token mints a normal session cookie — identical
+    // to /api/login — and 302-redirects to the graph. Without the secret the
+    // endpoint is disabled and indistinguishable from any other unknown path.
+    if (isReadMethod(request) && url.pathname === '/api/admin-session') {
+        const secret = getAdminSessionSecret();
+        if (secret === null) {
+            return createResponse(createJsonResponse({ error: 'Not found' }), 404, contentTypes['.json']);
+        }
+        const token = url.searchParams.get('token') ?? '';
+        if (!verifyAdminSessionToken(token, secret, auth.user, Date.now())) {
+            return createResponse(createJsonResponse({ error: 'Unauthorized' }), 401, contentTypes['.json']);
+        }
+        const sessionToken = createSessionToken(auth, sessionTtlMs, Date.now());
+        return withHeaders(redirectResponse('/'), {
+            'set-cookie': buildSessionSetCookie(sessionToken, { secure: requestIsSecure(request), ttlMs: sessionTtlMs })
+        });
+    }
     if (request.method === 'POST' && url.pathname === '/api/logout') {
         return withHeaders(createResponse(createJsonResponse({ ok: true }), 200, contentTypes['.json']), {
             'set-cookie': buildClearSessionCookie()

package/dist/domain/markdown.js

@@ -3,7 +3,11 @@ import { resolveAgentIdFromPath, sanitizeAgentId } from './agents.js';
 import { createStableId } from './ids.js';
 import { estimateTokenCount } from './tokens.js';
 const frontmatterPattern = /^---\n([\s\S]*?)\n---\n?/;
-const wikiLinkPattern = /\[\[([^\]|#]+)(?:#[^\]|]+)?(?:\|[^\]]+)?\]\]/g;
+// Target captures everything up to an optional "|alias" or the closing "]]",
+// INCLUDING "#" — the heading anchor is stripped later, and only when it is a
+// real anchor (see stripHeadingAnchor). Keeping "#" here means a title such as
+// "note (PR #34)" is not truncated at the "#".
+const wikiLinkPattern = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
 const tagPattern = /(^|\s)#([A-Za-z0-9][A-Za-z0-9_-]*)/g;
 const headingPattern = /^#\s+(.+)$/m;
 const contextLinksHeadingPattern = /^(#{1,6})\s+(?:context\s+links?|links?\s+de\s+contexto)\b/i;
@@ -30,7 +34,16 @@ const priorityPatterns = [
     ['low', /\b(?:priority|prioridade|importance|importancia|importância)\s*[:=]\s*(?:low|baixa|p3)\b/i],
     ['low', /#(?:low-priority|baixa-prioridade|p3)\b/i]
 ];
-const normalizeTitle = (title) => title.trim().replace(/\.md$/i, '');
+// A "#" starts a heading anchor ([[Note#Heading]]) only when it directly
+// follows the note name with NO whitespace before it. A "#" preceded by a space
+// (e.g. "note (PR #34)") is part of the title itself and must not be stripped,
+// otherwise the link target is truncated and can never resolve.
+const headingAnchorPattern = /(?<!\s)#[^\]|]*$/;
+const stripHeadingAnchor = (title) => {
+    const stripped = title.replace(headingAnchorPattern, '');
+    return stripped.trim().length > 0 ? stripped : title;
+};
+const normalizeTitle = (title) => stripHeadingAnchor(title.trim()).trim().replace(/\.md$/i, '');
 const unique = (values) => Array.from(new Set(values.map((value) => value.trim()).filter(Boolean)));
 const maxPriority = (left, right) => priorityRanks[left] >= priorityRanks[right] ? left : right;
 const parseFrontmatter = (content) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "1.6.11",
+  "version": "1.6.13",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",
@@ -64,9 +64,10 @@
     "zod": "^4.3.6"
   },
   "overrides": {
-    "hono": "4.12.26",
+    "hono": "4.12.28",
     "qs": "6.15.2",
-    "fast-uri": "^4.1.0"
+    "fast-uri": "^4.1.0",
+    "body-parser": "2.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.2",