@dreamforgestudiollc/emet 0.0.0-stage → 0.2.4

package/src/request-log.js

@@ -0,0 +1,124 @@
+/**
+ * EMET - Enduring Memory & Epistemic Tiers
+ * Copyright (c) 2026 Dreamforge Studio LLC
+ *
+ * Licensed under the MIT License - see LICENSE
+ *
+ * Request / auth logging for the HTTP transport (work list H4, 2026-09-07).
+ *
+ * Why: on 2026-09-07 a connector was added at the wrong URL, the browser
+ * authorization ran to completion, the client then POSTed to `/` and got a 404,
+ * and the user saw "an error". Railway's logs held three startup lines and
+ * nothing else. A server that cannot say what it answered cannot be diagnosed
+ * without reproducing the failure by hand - which is what happened.
+ *
+ * What is logged: one line per request on the OAuth and MCP paths, plus any
+ * request anywhere that ends 4xx/5xx (so a POST to a path that does not exist
+ * is visible). Fields: method, path, status, latency, client ip, and the
+ * identifying-but-not-secret parts of the exchange - client_id (a CIMD URL or
+ * an opaque registration id), grant_type, response_type, resource, the JSON-RPC
+ * method, tool name and the NAMES of the tool's parameters on /mcp (never their
+ * values - added 2026-09-27 so parameter use can be measured), and a reason on failures.
+ *
+ * What is never logged: request or response bodies, authorization codes,
+ * tokens, code verifiers, passphrases, or query strings as a whole. The line
+ * is still passed through the redaction scrubber before it is written -
+ * belt and braces; a control that depends on the author remembering is a rule.
+ */
+
+import { redactText } from './redact.js';
+
+// Paths always logged, whatever the status.
+export const LOGGED_PATH = /^\/(?:authorize|token|register|revoke|oauth\/approve|mcp|\.well-known\/[^\s]*)$/;
+
+const CLIP = 160;
+const clip = (v) => String(v).slice(0, CLIP);
+
+/** Whether a finished request should produce a log line. */
+export function shouldLog(path, statusCode) {
+  return LOGGED_PATH.test(path) || statusCode >= 400;
+}
+
+/**
+ * Builds the log entry for one finished request. Pure: takes the request
+ * fields it needs rather than the request object, so it is testable without
+ * express. `body` is whatever the parser left on req.body (may be undefined
+ * on a 401 that stopped before parsing), `query` is req.query.
+ */
+export function requestLogEntry({ method, path, statusCode, ms, ip, query = {}, body, wwwAuthenticate, reason }) {
+  const entry = { t: new Date().toISOString(), req: `${method} ${path}`, status: statusCode, ms: Math.round(ms) };
+  if (ip) entry.ip = ip;
+
+  const q = (query && typeof query === 'object') ? query : {};
+  const b = (body && typeof body === 'object' && !Array.isArray(body)) ? body : {};
+
+  const clientId = q.client_id ?? b.client_id;
+  if (clientId !== undefined) entry.client = clip(clientId);
+  if (b.grant_type) entry.grant = clip(b.grant_type);
+  if (q.response_type) entry.response_type = clip(q.response_type);
+  const resource = q.resource ?? b.resource;
+  if (resource !== undefined && resource !== null && resource !== '') entry.resource = clip(resource);
+  if (q.redirect_uri ?? b.redirect_uri) {
+    try { entry.redirect_host = new URL(q.redirect_uri ?? b.redirect_uri).host; } catch { entry.redirect_host = 'invalid'; }
+  }
+
+  if (path === '/mcp') {
+    if (Array.isArray(body)) entry.rpc = `batch(${body.length})`;
+    else if (b.method) {
+      entry.rpc = clip(b.method);
+      if (b.method === 'tools/call' && b.params && b.params.name) {
+        entry.tool = clip(b.params.name);
+        // Parameter NAMES only (the owner, 2026-09-27, code audit 1.6) - values never.
+        const a = b.params.arguments;
+        if (a && typeof a === 'object' && !Array.isArray(a)) entry.params = Object.keys(a).sort().map(clip);
+      }
+    }
+  }
+
+  if (reason) entry.reason = clip(reason);
+  else if (statusCode === 401 && wwwAuthenticate) {
+    const m = String(wwwAuthenticate).match(/error="([^"]+)"/);
+    if (m) entry.reason = m[1];
+  }
+
+  return entry;
+}
+
+/** The rendered line. Scrubbed even though nothing secret should be in it. */
+export function formatRequestLog(entry) {
+  return '[emet][req] ' + redactText(JSON.stringify(entry));
+}
+
+/**
+ * Express middleware. Installed before the auth router so it sees every
+ * request; logs on `finish`, when the status and any parsed body are known.
+ */
+export function requestLogger({ enabled = true, write = (line) => console.error(line) } = {}) {
+  return function emetRequestLog(req, res, next) {
+    if (!enabled) return next();
+    const t0 = process.hrtime.bigint();
+    // Capture the path NOW. The SDK's auth router mounts /authorize, /token,
+    // /register and the well-known documents as sub-routers, and express
+    // strips the mount prefix from req.path while a sub-router is handling
+    // the request - at `finish` it can read as '/' with status 200, which the
+    // filter would then skip. Found live on the first deploy (2026-09-07): the
+    // /.well-known line was the one missing from the log.
+    const path = String(req.originalUrl || req.url || '/').split('?')[0] || '/';
+    res.on('finish', () => {
+      try {
+        if (!shouldLog(path, res.statusCode)) return;
+        const ms = Number(process.hrtime.bigint() - t0) / 1e6;
+        const entry = requestLogEntry({
+          method: req.method, path, statusCode: res.statusCode, ms, ip: req.ip,
+          query: req.query, body: req.body,
+          wwwAuthenticate: res.getHeader && res.getHeader('www-authenticate'),
+          reason: res.locals && res.locals.reason
+        });
+        write(formatRequestLog(entry));
+      } catch (e) {
+        write('[emet][req] log failed: ' + (e && e.message));
+      }
+    });
+    next();
+  };
+}

package/src/scopes.js

@@ -0,0 +1,97 @@
+/**
+ * Tool scopes. Advertised as emet.read and emet.write.
+ * Empty list = owner / full access (today's tokens).
+ * A guest token will carry only the scopes it was granted.
+ *
+ * The scope is DERIVED from the tool's annotation (2026-09-27, code audit 1.2):
+ * a tool whose readOnlyHint is true needs emet.read, every other tool needs
+ * emet.write. Until then two hand-kept sets lived here beside the annotation
+ * table and the tool list - a third place a tool name had to be added, with no
+ * guard when it was not (an unlisted tool silently fell to emet.write).
+ */
+
+import { TOOL_ANNOTATIONS } from './annotations.js';
+
+// A tool whose scope deliberately differs from its annotation.
+// emet_status without probe is a read, so a guest can see that the store is up.
+// emet_status with probe: true writes a document, so scopeForTool returns
+// emet.write for that call. emet_session_open stamps the drop list a board
+// edit trusts, so it requires emet.write even though a quick read of the
+// annotation table is not the whole story — the override list no longer
+// grants it to a read token.
+const SCOPE_OVERRIDES = Object.freeze({
+  emet_status: 'emet.read',
+  emet_initialize: 'emet.read'
+});
+
+export function scopeForTool(name, args = null) {
+  // Opening a session stamps the drop list the board guard trusts, and the
+  // status probe writes. Both need emet.write. A status call without probe
+  // stays a read.
+  if (name === 'emet_session_open') return 'emet.write';
+  if (name === 'emet_status' && args && args.probe === true) return 'emet.write';
+  if (SCOPE_OVERRIDES[name]) return SCOPE_OVERRIDES[name];
+  const a = TOOL_ANNOTATIONS[name];
+  if (a && a.readOnlyHint === true) return 'emet.read';
+  return 'emet.write';
+}
+
+export function scopesAllow(scopes, name, opts = {}) {
+  // A presented HTTP token with no scopes is not the owner. Stdio (no token)
+  // and a passphrase token that carries emet / * still are.
+  if (opts.http === true && opts.authenticated === true && (!Array.isArray(scopes) || scopes.length === 0)) return false;
+  if (!Array.isArray(scopes) || scopes.length === 0) return true;
+  if (scopes.includes('*') || scopes.includes('emet')) return true;
+  const need = scopeForTool(name, opts.args || null);
+  return scopes.includes(need);
+}
+
+/**
+ * Security audit 2026-09-29: an empty scope list means OWNER / full access
+ * (scopesAllow above), which is right for a passphrase login and wrong for a
+ * guest. An invite that carries no usable scopes must not mint a token, or a
+ * guest would silently become the owner. Returns the invite's scopes when at
+ * least one is a real scope, else null (the caller refuses the login).
+ * Invites are frozen today (invites.js); this holds the line for when they are not.
+ */
+export const KNOWN_SCOPES = Object.freeze(['emet.read', 'emet.write']);
+export function guestScopesOrNull(scopes) {
+  if (!Array.isArray(scopes)) return null;
+  const kept = [...new Set(scopes.filter((s) => KNOWN_SCOPES.includes(s)))];
+  return kept.length ? kept : null;
+}
+
+/**
+ * Refresh may only keep or narrow what was granted (multi-user report v2,
+ * defect 1, 2026-10-01). Until then a refresh grant replaced the stored scopes
+ * with whatever the client asked for, so a read-only invite token - or any
+ * restricted token - could refresh to `emet` or `*` and hold full access.
+ *
+ * Both sides are expanded before comparing, so an alias can never widen:
+ *   - granted [] or containing `emet` / `*` is FULL (what scopesAllow honours):
+ *     every request is within it - a passphrase token keeps refreshing exactly
+ *     as before, with whatever scope its host sends;
+ *   - otherwise a requested `emet` or `*` stands for every known scope
+ *     (KNOWN_SCOPES - all scopeForTool can ask for), and each requested scope
+ *     must already be granted. Any other requested string must be granted
+ *     verbatim.
+ * Returns the scopes that are not covered (empty = the request is within).
+ */
+export const FULL_SCOPE_ALIASES = Object.freeze(['emet', '*']);
+export function isFullScopeList(scopes) {
+  return !Array.isArray(scopes) || scopes.length === 0 || scopes.some((s) => FULL_SCOPE_ALIASES.includes(s));
+}
+export function scopesNotGranted(granted, requested) {
+  if (isFullScopeList(granted)) return [];
+  const have = new Set(granted);
+  const wider = [];
+  for (const r of requested || []) {
+    const needs = FULL_SCOPE_ALIASES.includes(r) ? KNOWN_SCOPES : [r];
+    if (!needs.every((n) => have.has(n))) wider.push(r);
+  }
+  return [...new Set(wider)];
+}
+
+export function deniedMessage(name, scopes, args = null) {
+  return `This login is not allowed to call ${name}. Granted: ${(scopes || []).join(', ') || '(none)'}. Needs ${scopeForTool(name, args)}.`;
+}

package/src/security-headers.js

@@ -0,0 +1,26 @@
+/**
+ * Baseline headers on every HTTP response.
+ *
+ * The consent page sets its own Content-Security-Policy. These four headers
+ * are set again just before the status line is written, so a later handler
+ * cannot drop them, and they do not replace that policy.
+ */
+export const SECURITY_HEADERS = Object.freeze({
+  'X-Content-Type-Options': 'nosniff',
+  'X-Frame-Options': 'DENY',
+  'Referrer-Policy': 'no-referrer',
+  'Strict-Transport-Security': 'max-age=31536000; includeSubDomains'
+});
+
+export function securityHeaders(_req, res, next) {
+  const apply = () => {
+    for (const [name, value] of Object.entries(SECURITY_HEADERS)) res.setHeader(name, value);
+  };
+  apply();
+  const writeHead = res.writeHead;
+  res.writeHead = function writeHeadWithSecurityHeaders(...args) {
+    apply();
+    return writeHead.apply(this, args);
+  };
+  next();
+}