@chrischall/mcp-utils 2.10.0 → 2.12.0

package/dist/session/login-page.d.ts

@@ -0,0 +1,73 @@
+/**
+ * "Did the site just hand me its login page?" — the session-expiry predicate
+ * for sites that answer an expired cookie session with an HTTP 200 (or a
+ * redirect) rather than a 401.
+ *
+ * Three fleet servers decided this locally, each differently (fleet-audit#1155):
+ * artsonia-mcp's `looksUnauthenticated` (final URL, a manual 3xx `Location`, or
+ * the login form rendered in place), signupgenius-mcp's `isSessionExpired`
+ * (401, or a non-JSON 200 carrying the login form's markers), and
+ * canvas-parent-mcp (401 only). artsonia's first version matched body PROSE and
+ * a fan comment reading "You need to log in…" forced a needless re-login on
+ * every read of that artwork — so the rules here are STRUCTURAL only:
+ *
+ *  - a configured status (default `401`);
+ *  - the response's final URL, or its `Location`, whose path+search matches
+ *    `url` — a login URL merely mentioned in an (encoded) query parameter of
+ *    another page does not count;
+ *  - a `<form>` whose `action` matches `form.action`, containing (before its
+ *    `</form>` or the next `<form>`) an input named `form.field` — or, with no
+ *    field named, any `type=password` input. User-generated text arrives
+ *    HTML-escaped, so it cannot forge that structure. The body is only scanned
+ *    when the response is HTML (or says nothing about its type): JSON carries
+ *    user text too (signupgenius' lesson).
+ *
+ * Every scan is linear in the body — this runs on every response of the
+ * session — and the body considered is capped at {@link LOGIN_PAGE_SCAN_MAX}.
+ */
+/** A response as {@link looksLikeLoginPage} sees it. Every field is optional. */
+export interface LoginPageView {
+    status?: number;
+    /** The final URL (after any followed redirects). */
+    url?: string;
+    /** A `Location` header, for a redirect that was not followed. */
+    location?: string | null;
+    /** The body text, when the caller has it. */
+    body?: string;
+    /** The `content-type`; a non-HTML type skips the form scan. */
+    contentType?: string | null;
+}
+/** What identifies a site's login page. Omitted rules are not checked. */
+export interface LoginPageSignals {
+    /** Matched against the path + search of the final URL and of `Location`. */
+    url?: RegExp;
+    /**
+     * The login form. `action` filters forms by their `action` attribute (any
+     * form when omitted); `field` names the input that must sit inside it
+     * (case-insensitive), defaulting to any `type=password` input.
+     */
+    form?: {
+        action?: RegExp;
+        field?: string;
+    };
+    /** Statuses that mean expired by themselves. Default `[401]`; `[]` for none. */
+    statuses?: readonly number[];
+}
+/** Bytes of body {@link looksLikeLoginPage} considers. A login page is small. */
+export declare const LOGIN_PAGE_SCAN_MAX: number;
+/**
+ * Whether `page` is the site's login page by `signals` — sync and pure, for a
+ * caller that already has the pieces (a custom transport, a fetchproxy result,
+ * a signed-out check outside the session manager).
+ */
+export declare function looksLikeLoginPage(page: LoginPageView, signals: LoginPageSignals): boolean;
+/**
+ * An `isExpired` for {@link CookieSessionManager}: true when the response is
+ * the login page by `signals` (see {@link looksLikeLoginPage}).
+ *
+ * Takes a web `Response` — its body read from a CLONE, and only when a `form`
+ * rule needs it, so the caller can still read the original — or any object
+ * with the {@link LoginPageView} fields (artsonia's `{ url, location, body }`).
+ */
+export declare function expiredByLoginPage(signals: LoginPageSignals): (res: Response | LoginPageView) => Promise<boolean>;
+//# sourceMappingURL=login-page.d.ts.map

package/dist/session/login-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login-page.d.ts","sourceRoot":"","sources":["../../src/session/login-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,QAAa,CAAC;AA0D9C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAe1F;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,gBAAgB,GACxB,CAAC,GAAG,EAAE,QAAQ,GAAG,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAqBrD"}

package/dist/session/login-page.js

@@ -0,0 +1,143 @@
+/**
+ * "Did the site just hand me its login page?" — the session-expiry predicate
+ * for sites that answer an expired cookie session with an HTTP 200 (or a
+ * redirect) rather than a 401.
+ *
+ * Three fleet servers decided this locally, each differently (fleet-audit#1155):
+ * artsonia-mcp's `looksUnauthenticated` (final URL, a manual 3xx `Location`, or
+ * the login form rendered in place), signupgenius-mcp's `isSessionExpired`
+ * (401, or a non-JSON 200 carrying the login form's markers), and
+ * canvas-parent-mcp (401 only). artsonia's first version matched body PROSE and
+ * a fan comment reading "You need to log in…" forced a needless re-login on
+ * every read of that artwork — so the rules here are STRUCTURAL only:
+ *
+ *  - a configured status (default `401`);
+ *  - the response's final URL, or its `Location`, whose path+search matches
+ *    `url` — a login URL merely mentioned in an (encoded) query parameter of
+ *    another page does not count;
+ *  - a `<form>` whose `action` matches `form.action`, containing (before its
+ *    `</form>` or the next `<form>`) an input named `form.field` — or, with no
+ *    field named, any `type=password` input. User-generated text arrives
+ *    HTML-escaped, so it cannot forge that structure. The body is only scanned
+ *    when the response is HTML (or says nothing about its type): JSON carries
+ *    user text too (signupgenius' lesson).
+ *
+ * Every scan is linear in the body — this runs on every response of the
+ * session — and the body considered is capped at {@link LOGIN_PAGE_SCAN_MAX}.
+ */
+/** Bytes of body {@link looksLikeLoginPage} considers. A login page is small. */
+export const LOGIN_PAGE_SCAN_MAX = 512 * 1024;
+/** Longest form open tag read for its `action` (a real one is far shorter). */
+const MAX_TAG = 4096;
+const FORM_OPEN = /<form\b/gi;
+const FORM_CLOSE = /<\/form\s*>/gi;
+const ACTION_ATTR = /\baction\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>"']+))/i;
+const PASSWORD_INPUT = /\btype\s*=\s*["']?password(?=["'\s/>])/i;
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Path + search of `u` (relative values resolved against a dummy origin); `u` itself if unparseable. */
+function pathAndSearch(u) {
+    try {
+        const parsed = new URL(u, 'http://localhost');
+        return parsed.pathname + parsed.search;
+    }
+    catch {
+        return u;
+    }
+}
+function indicesOf(re, body) {
+    const out = [];
+    re.lastIndex = 0;
+    for (let m = re.exec(body); m !== null; m = re.exec(body))
+        out.push(m.index);
+    return out;
+}
+function rendersLoginForm(body, form) {
+    const fieldRe = form.field !== undefined
+        ? new RegExp(`\\bname\\s*=\\s*["']?${escapeRegExp(form.field)}(?=["'\\s/>])`, 'i')
+        : PASSWORD_INPUT;
+    const opens = indicesOf(FORM_OPEN, body);
+    const closes = indicesOf(FORM_CLOSE, body);
+    let c = 0;
+    for (let i = 0; i < opens.length; i++) {
+        const start = opens[i];
+        // Forms do not nest: a form's content ends at its `</form>` or the next `<form>`.
+        while (c < closes.length && closes[c] < start)
+            c++;
+        const nextOpen = opens[i + 1] ?? body.length;
+        const end = Math.min(closes[c] ?? body.length, nextOpen);
+        const region = body.slice(start, end);
+        if (form.action !== undefined) {
+            const tagEnd = region.indexOf('>');
+            const tag = region.slice(0, tagEnd === -1 ? Math.min(region.length, MAX_TAG) : Math.min(tagEnd, MAX_TAG));
+            const m = ACTION_ATTR.exec(tag);
+            const action = m === null ? undefined : (m[1] ?? m[2] ?? m[3]);
+            if (action === undefined || !form.action.test(action))
+                continue;
+        }
+        if (fieldRe.test(region))
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether `page` is the site's login page by `signals` — sync and pure, for a
+ * caller that already has the pieces (a custom transport, a fetchproxy result,
+ * a signed-out check outside the session manager).
+ */
+export function looksLikeLoginPage(page, signals) {
+    const statuses = signals.statuses ?? [401];
+    if (page.status !== undefined && statuses.includes(page.status))
+        return true;
+    if (signals.url !== undefined) {
+        const re = signals.url;
+        if (page.url && re.test(pathAndSearch(page.url)))
+            return true;
+        if (page.location && re.test(pathAndSearch(page.location)))
+            return true;
+    }
+    if (signals.form !== undefined && page.body) {
+        const ct = page.contentType;
+        if (ct && !/html/i.test(ct))
+            return false;
+        const body = page.body.length > LOGIN_PAGE_SCAN_MAX ? page.body.slice(0, LOGIN_PAGE_SCAN_MAX) : page.body;
+        return rendersLoginForm(body, signals.form);
+    }
+    return false;
+}
+/**
+ * An `isExpired` for {@link CookieSessionManager}: true when the response is
+ * the login page by `signals` (see {@link looksLikeLoginPage}).
+ *
+ * Takes a web `Response` — its body read from a CLONE, and only when a `form`
+ * rule needs it, so the caller can still read the original — or any object
+ * with the {@link LoginPageView} fields (artsonia's `{ url, location, body }`).
+ */
+export function expiredByLoginPage(signals) {
+    return async (res) => {
+        if (res instanceof Response) {
+            const view = {
+                status: res.status,
+                url: res.url,
+                location: res.headers.get('location'),
+                contentType: res.headers.get('content-type'),
+            };
+            if (looksLikeLoginPage(view, { ...signals, form: undefined }))
+                return true;
+            if (signals.form === undefined || res.body === null)
+                return false;
+            if (view.contentType && !/html/i.test(view.contentType))
+                return false;
+            try {
+                view.body = await res.clone().text();
+            }
+            catch {
+                return false;
+            }
+            return looksLikeLoginPage(view, signals);
+        }
+        return looksLikeLoginPage(res, signals);
+    };
+}
+//# sourceMappingURL=login-page.js.map

package/dist/session/login-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"login-page.js","sourceRoot":"","sources":["../../src/session/login-page.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/mcp-utils",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "Shared scaffolding for the chrischall MCP fleet — server bootstrap, tool-result formatting, helpful errors, hardened env/config, a bearer API-client kit, zod atoms, session registries, a fetchproxy transport adapter, auth resolver skeletons, an in-memory test harness, and opt-in HTML helpers. The generic MCP glue hoisted out of ~19 sibling servers.",
   "type": "module",
   "license": "MIT",
@@ -39,6 +39,10 @@
     "./healthcheck": {
       "import": "./dist/healthcheck/index.js",
       "types": "./dist/healthcheck/index.d.ts"
+    },
+    "./graphql": {
+      "import": "./dist/graphql/index.js",
+      "types": "./dist/graphql/index.d.ts"
     }
   },
   "files": [