@mulmoclaude/common 0.1.0 → 1.1.0

package/README.md

@@ -29,5 +29,38 @@ duplicated," so they live here once.
 | `hasStringProp(v, k)` | `Record<k, string>` | key present with a string value |
 | `hasNumberProp(v, k)` | `Record<k, number>` | key present with a number value |
 
+Plus CSV/env helpers `parseCsvList(raw, { lowercase? })` and
+`parseCsvSet(raw, { lowercase? })` (empty set = "allow all" sentinel), and the
+helpers below.
+
+| Helper | Returns | Notes |
+|---|---|---|
+| `errorMessage(v, fallback?)` | `string` | unknown caught value → human-readable string; **isomorphic**, so Vue/browser surfaces use it too |
+| `toUtcIsoDate(timestamp)` | `string` | `Date` → `YYYY-MM-DD` in UTC — for dates that must not shift with the host's local timezone |
+
+`errorMessage` surfaces a non-empty string `details` (gRPC convention) or
+`message` field of a non-Error object (`details` wins) instead of
+`[object Object]`; `fallback` covers a thrown non-Error at an error boundary.
+This is the single home the #2217 consolidation could not reach, because
+`@mulmoclaude/core/utils` is server-only — core now re-exports this one.
+
 `isRecord` vs `isObj`: use `isRecord` whenever you go on to index string keys —
 `isObj` lets arrays through, which is rarely what you want for a JSON payload.
+
+## Shared types
+
+`src/logger.ts` (re-exported from the root entry) holds the canonical logger
+interface family:
+
+| Type | Shape | Notes |
+|---|---|---|
+| `StructuredLogger` | `error`/`warn`/`info`/`debug` `(prefix, message, data?)` | The host logger, and every engine/plugin logger injected from it |
+| `MinimalLogger` | `info`/`warn`/`error` `(message, data?)` | For a package that already namespaces its own entries |
+
+They live here because the shape spans all three tiers — host `server/`, the
+plugins, and `@mulmoclaude/core` — so no tier above the leaf can own the
+declaration without becoming an uphill import for the others (#2486). Domains
+keep their own exported name by **aliasing** rather than re-declaring
+(`export type FeedsLogger = StructuredLogger`, or a
+`Pick<MinimalLogger, "warn" | "error">` subset): TypeScript is structurally
+typed, so the alias preserves the public name and the emitted `.d.ts` exactly.

package/dist/envScan.d.ts

@@ -0,0 +1,11 @@
+export interface ScanEnvOptionsConfig {
+    /** Ordered LOW → HIGH precedence — on a key clash the later prefix wins. */
+    prefixes: readonly string[];
+    /** Closed set of emitted keys (lowerCamel). Absent = emit every key. */
+    allowKeys?: ReadonlySet<string>;
+}
+/** Convert `UPPER_SNAKE_CASE` → `lowerCamelCase`. Adjacent underscores
+ *  collapse to a single word break; empty / all-underscore input → `""`. */
+export declare function snakeToLowerCamel(snake: string): string;
+/** Scrape prefixed env vars into a lowerCamel-keyed string bag. */
+export declare function scanEnvOptions(env: Readonly<Record<string, string | undefined>>, config: ScanEnvOptionsConfig): Record<string, string>;

package/dist/envScan.js

@@ -0,0 +1,62 @@
+// The one env-scrape algorithm (#2487) behind the prefixed options bags:
+// `readBridgeEnvOptions` (@mulmobridge/client) and the host's
+// `resolveRelayBridgeOptions` are thin wrappers over `scanEnvOptions`.
+//
+// Semantics both wrappers rely on:
+// - `prefixes` are ordered LOW → HIGH precedence: when two vars yield the
+//   same key, the value from the later prefix wins.
+// - The highest-precedence prefix that matches a name CLAIMS it. A claimed
+//   name with an empty tail is dropped outright — never retried against a
+//   lower-precedence prefix.
+// - Empty-string values are dropped so a stray `FOO=""` doesn't shadow
+//   another var's match.
+// - Tails convert `UPPER_SNAKE` → `lowerCamel`; an all-underscore tail
+//   camelises to `""` and is dropped.
+// - `allowKeys` (lowerCamel form), when present, drops every other key.
+//   This is how the relay wrapper keeps `RELAY_TOKEN` / `RELAY_URL`
+//   infrastructure secrets out of a bag that is forwarded to the agent
+//   and may be logged — treat the filter as a security boundary.
+/** Convert `UPPER_SNAKE_CASE` → `lowerCamelCase`. Adjacent underscores
+ *  collapse to a single word break; empty / all-underscore input → `""`. */
+export function snakeToLowerCamel(snake) {
+    const parts = snake
+        .toLowerCase()
+        .split("_")
+        .filter((segment) => segment.length > 0);
+    if (parts.length === 0)
+        return "";
+    const [head, ...rest] = parts;
+    return head + rest.map((part) => part[0].toUpperCase() + part.slice(1)).join("");
+}
+function claimByHighestPrefix(name, prefixes) {
+    const claimed = prefixes
+        .map((prefix, precedence) => ({ prefix, precedence }))
+        .reverse()
+        .find(({ prefix }) => name.startsWith(prefix));
+    if (claimed === undefined)
+        return null;
+    return { precedence: claimed.precedence, tail: name.slice(claimed.prefix.length) };
+}
+function scanEnvEntry(name, value, config) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    const claim = claimByHighestPrefix(name, config.prefixes);
+    if (claim === null || claim.tail.length === 0)
+        return null;
+    const key = snakeToLowerCamel(claim.tail);
+    if (key.length === 0)
+        return null;
+    if (config.allowKeys !== undefined && !config.allowKeys.has(key))
+        return null;
+    return { precedence: claim.precedence, key, value };
+}
+/** Scrape prefixed env vars into a lowerCamel-keyed string bag. */
+export function scanEnvOptions(env, config) {
+    return Object.entries(env)
+        .flatMap(([name, value]) => {
+        const scanned = scanEnvEntry(name, value, config);
+        return scanned === null ? [] : [scanned];
+    })
+        .sort((left, right) => left.precedence - right.precedence)
+        .reduce((bag, { key, value }) => ({ ...bag, [key]: value }), {});
+}

package/dist/index.d.ts

@@ -22,3 +22,45 @@ export declare function isErrorWithCode(value: unknown): value is {
 export declare function hasStringProp<K extends string>(value: unknown, key: K): value is Record<K, string> & Record<string, unknown>;
 /** Check that a record has a specific key with a number value. */
 export declare function hasNumberProp<K extends string>(value: unknown, key: K): value is Record<K, number> & Record<string, unknown>;
+/** Split a comma-separated env value into trimmed, non-empty entries.
+ *  `lowercase` folds case for identifiers compared case-insensitively
+ *  (JIDs, email addresses, hex pubkeys). Absent/empty input → empty list. */
+export declare function parseCsvList(raw: string | undefined, opts?: {
+    lowercase?: boolean;
+}): string[];
+/** A comma-separated env value as a Set — the canonical allowlist shape,
+ *  where an empty set is the "allow all" sentinel (`set.size === 0`). */
+export declare function parseCsvSet(raw: string | undefined, opts?: {
+    lowercase?: boolean;
+}): Set<string>;
+/** Normalise an unknown thrown value into a human-readable string. Isomorphic
+ *  (host, bridges, plugins, Vue) — this is the single home for the helper that
+ *  #2217 could only consolidate for server code, since `@mulmoclaude/core/utils`
+ *  is server-only.
+ *
+ *  A non-Error object with a non-empty string `details` (gRPC convention) or
+ *  `message` field surfaces that field — `details` wins — instead of the
+ *  `[object Object]` a bare `String(err)` would print; an empty-string field
+ *  falls through. `fallback` covers the error-boundary idiom where a thrown
+ *  non-Error should read as a descriptive message rather than `String(err)`
+ *  noise; omit it in logging contexts where `String(err)` is fine. */
+export declare function errorMessage(err: unknown, fallback?: string): string;
+/** `Date` → `YYYY-MM-DD` in UTC — for dates that must not shift with the
+ *  host's local timezone (tool-trace search dirs, API date keys). Isomorphic
+ *  single source (#2480): the host re-exports it from `server/utils/date.ts`,
+ *  x-plugin imports it directly. The `@receptron/task-scheduler` copy stays
+ *  local on purpose — that leaf package is published independently and kept
+ *  dependency-free. Wall-clock questions use the host's `toLocalIsoDate`. */
+export declare function toUtcIsoDate(timestamp: Date): string;
+/** HTML-escape text destined for markup or an attribute value — the fixed
+ *  five-character map, nothing more. Lives here rather than in
+ *  `@mulmoclaude/core/wiki` (#2483) because `@mulmoclaude/markdown-utils` is a
+ *  leaf that core depends on and so cannot import back up; core/wiki
+ *  re-exports this, keeping its consumers' import path unchanged.
+ *
+ *  Escaping `&` first is what makes a single pass safe — the entities this
+ *  introduces contain none of the other four characters, so nothing is
+ *  double-escaped. Not a sanitiser: it neither strips tags nor validates URLs. */
+export declare function escapeHtml(value: string): string;
+export { scanEnvOptions, snakeToLowerCamel, type ScanEnvOptionsConfig } from "./envScan.js";
+export type { MinimalLogger, StructuredLogger } from "./logger.js";

package/dist/index.js

@@ -46,3 +46,74 @@ export function hasStringProp(value, key) {
 export function hasNumberProp(value, key) {
     return isRecord(value) && typeof value[key] === "number";
 }
+/** Split a comma-separated env value into trimmed, non-empty entries.
+ *  `lowercase` folds case for identifiers compared case-insensitively
+ *  (JIDs, email addresses, hex pubkeys). Absent/empty input → empty list. */
+export function parseCsvList(raw, opts) {
+    return (raw ?? "")
+        .split(",")
+        .map((entry) => (opts?.lowercase ? entry.trim().toLowerCase() : entry.trim()))
+        .filter(Boolean);
+}
+/** A comma-separated env value as a Set — the canonical allowlist shape,
+ *  where an empty set is the "allow all" sentinel (`set.size === 0`). */
+export function parseCsvSet(raw, opts) {
+    return new Set(parseCsvList(raw, opts));
+}
+/** Normalise an unknown thrown value into a human-readable string. Isomorphic
+ *  (host, bridges, plugins, Vue) — this is the single home for the helper that
+ *  #2217 could only consolidate for server code, since `@mulmoclaude/core/utils`
+ *  is server-only.
+ *
+ *  A non-Error object with a non-empty string `details` (gRPC convention) or
+ *  `message` field surfaces that field — `details` wins — instead of the
+ *  `[object Object]` a bare `String(err)` would print; an empty-string field
+ *  falls through. `fallback` covers the error-boundary idiom where a thrown
+ *  non-Error should read as a descriptive message rather than `String(err)`
+ *  noise; omit it in logging contexts where `String(err)` is fine. */
+export function errorMessage(err, fallback) {
+    if (err instanceof Error)
+        return err.message;
+    if (hasStringProp(err, "details") && err.details)
+        return err.details;
+    if (hasStringProp(err, "message") && err.message)
+        return err.message;
+    if (fallback !== undefined)
+        return fallback;
+    return String(err);
+}
+/** `Date` → `YYYY-MM-DD` in UTC — for dates that must not shift with the
+ *  host's local timezone (tool-trace search dirs, API date keys). Isomorphic
+ *  single source (#2480): the host re-exports it from `server/utils/date.ts`,
+ *  x-plugin imports it directly. The `@receptron/task-scheduler` copy stays
+ *  local on purpose — that leaf package is published independently and kept
+ *  dependency-free. Wall-clock questions use the host's `toLocalIsoDate`. */
+export function toUtcIsoDate(timestamp) {
+    const year = timestamp.getUTCFullYear();
+    const month = String(timestamp.getUTCMonth() + 1).padStart(2, "0");
+    const day = String(timestamp.getUTCDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+// A Map, not an object literal: `{}[char]` reads through the prototype chain,
+// so a future caller widening the regex would silently get `[object Object]`
+// for keys like `constructor`.
+const HTML_ESCAPES = new Map([
+    ["&", "&"],
+    ["<", "&lt;"],
+    [">", "&gt;"],
+    ['"', "&quot;"],
+    ["'", "&#39;"],
+]);
+/** HTML-escape text destined for markup or an attribute value — the fixed
+ *  five-character map, nothing more. Lives here rather than in
+ *  `@mulmoclaude/core/wiki` (#2483) because `@mulmoclaude/markdown-utils` is a
+ *  leaf that core depends on and so cannot import back up; core/wiki
+ *  re-exports this, keeping its consumers' import path unchanged.
+ *
+ *  Escaping `&` first is what makes a single pass safe — the entities this
+ *  introduces contain none of the other four characters, so nothing is
+ *  double-escaped. Not a sanitiser: it neither strips tags nor validates URLs. */
+export function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => HTML_ESCAPES.get(char) ?? char);
+}
+export { scanEnvOptions, snakeToLowerCamel } from "./envScan.js";

package/dist/logger.d.ts

@@ -0,0 +1,14 @@
+/** 4-method host-logger shape — `(prefix, message, data?)`. */
+export interface StructuredLogger {
+    error: (prefix: string, message: string, data?: Record<string, unknown>) => void;
+    warn: (prefix: string, message: string, data?: Record<string, unknown>) => void;
+    info: (prefix: string, message: string, data?: Record<string, unknown>) => void;
+    debug: (prefix: string, message: string, data?: Record<string, unknown>) => void;
+}
+/** 3-method pre-namespaced logger — `(message, data?)`; the logging package
+ *  binds its own prefix, so hosts only supply the transport. */
+export interface MinimalLogger {
+    info: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+}

package/dist/logger.js

@@ -0,0 +1,6 @@
+// Canonical logger interface family. Lives in this zero-dep leaf — the only
+// tier the host, @mulmoclaude/core domains, and plugins can all reach — so each
+// consumer aliases ONE declaration (`export type CollectionLogger =
+// StructuredLogger`) instead of re-declaring the shape: structural typing keeps
+// every alias's public name and d.ts surface identical to a re-declaration.
+export {};

package/dist/meta-webhook.d.ts

@@ -0,0 +1,16 @@
+export interface MessengerTextMessage {
+    senderId: string;
+    text: string;
+}
+/** Every text message across all `entry[].messaging[]` events in a Messenger
+ *  webhook body, skipping non-text / empty / malformed events. */
+export declare function extractMessengerMessages(body: unknown): MessengerTextMessage[];
+export interface WhatsAppTextMessage {
+    from: string;
+    text: {
+        body: string;
+    };
+}
+/** Every inbound text message across all `entry[].changes[].value.messages[]`
+ *  in a WhatsApp Cloud API webhook body, skipping non-text / malformed. */
+export declare function extractWhatsAppMessages(body: unknown): WhatsAppTextMessage[];

package/dist/meta-webhook.js

@@ -0,0 +1,58 @@
+// Pure inbound-payload parsers for the Meta messaging platforms (Facebook
+// Messenger, WhatsApp Cloud API). Both the Node/Express bridges and the
+// Cloudflare Workers relay receive the same webhook JSON shapes and used to
+// carry byte-identical copies of these extractors. They live here — a
+// zero-dependency, no-node leaf — because that is the only tier both runtimes
+// can import: no crypto, no fetch, no Node built-ins, just `isRecord`.
+//
+// Signature verification is deliberately NOT here: the bridges use node:crypto
+// and the relay uses Web Crypto (`crypto.subtle`), so it cannot be shared.
+import { isRecord, isUnknownArray } from "./index.js";
+function parseMessengerEvent(event) {
+    if (!isRecord(event) || !isRecord(event.sender) || typeof event.sender.id !== "string")
+        return null;
+    if (!isRecord(event.message) || typeof event.message.text !== "string")
+        return null;
+    const text = event.message.text.trim();
+    if (!text)
+        return null;
+    return { senderId: event.sender.id, text };
+}
+function messengerEventsOf(entry) {
+    return isRecord(entry) && isUnknownArray(entry.messaging) ? entry.messaging : [];
+}
+/** Every text message across all `entry[].messaging[]` events in a Messenger
+ *  webhook body, skipping non-text / empty / malformed events. */
+export function extractMessengerMessages(body) {
+    if (!isRecord(body) || !isUnknownArray(body.entry))
+        return [];
+    return body.entry
+        .flatMap(messengerEventsOf)
+        .map(parseMessengerEvent)
+        .filter((msg) => msg !== null);
+}
+function parseWhatsAppMessage(msg) {
+    if (!isRecord(msg) || msg.type !== "text" || typeof msg.from !== "string")
+        return null;
+    if (!isRecord(msg.text) || typeof msg.text.body !== "string" || !msg.text.body.trim())
+        return null;
+    return { from: msg.from, text: { body: msg.text.body } };
+}
+function whatsAppMessagesOf(change) {
+    if (!isRecord(change) || !isRecord(change.value) || !isUnknownArray(change.value.messages))
+        return [];
+    return change.value.messages;
+}
+function whatsAppRawMessagesOf(entry) {
+    return isRecord(entry) && isUnknownArray(entry.changes) ? entry.changes.flatMap(whatsAppMessagesOf) : [];
+}
+/** Every inbound text message across all `entry[].changes[].value.messages[]`
+ *  in a WhatsApp Cloud API webhook body, skipping non-text / malformed. */
+export function extractWhatsAppMessages(body) {
+    if (!isRecord(body) || !isUnknownArray(body.entry))
+        return [];
+    return body.entry
+        .flatMap(whatsAppRawMessagesOf)
+        .map(parseWhatsAppMessage)
+        .filter((msg) => msg !== null);
+}

package/dist/ssrf.d.ts

@@ -0,0 +1,28 @@
+/** IPv4 ranges that must never be fetched, as [firstAddress, prefixLength].
+ *  The union of the pre-#2459 per-guard tables — removing an entry weakens
+ *  every guard in the repo at once, so treat edits as security changes. */
+export declare const BLOCKED_IPV4_RANGES: readonly (readonly [string, number])[];
+/** Dotted-decimal IPv4 → unsigned 32-bit value; null for anything else
+ *  (hex / octal octets, whitespace, wrong part count). */
+export declare function ipv4ToInt(address: string): number | null;
+/** True when this parses as IPv4 AND falls inside a blocked range. Non-IPv4
+ *  input is false — "not a blocked literal", not "safe"; a caller that must
+ *  reject non-IP input entirely does so at its own boundary. */
+export declare function isBlockedIpv4(address: string): boolean;
+/** `URL.hostname` keeps the brackets on an IPv6 literal (`[::1]`); strip them
+ *  so the address checks see the bare address. */
+export declare function stripIpv6Brackets(hostname: string): string;
+/** Blocks loopback/unspecified, fc00::/7 unique-local, fe80::/10 link-local,
+ *  and IPv4-mapped forms of blocked v4 addresses. Mask-based on the leading
+ *  group — prefix string matching would miss e.g. fe9a:: (inside fe80::/10). */
+export declare function isBlockedIpv6(address: string): boolean;
+/** True when this literal address must never be fetched. Non-IP input is
+ *  false — see `isBlockedIpv4`. */
+export declare function isBlockedIp(address: string): boolean;
+/** Names that are internal by convention (localhost, *.local, *.internal…),
+ *  rejected without waiting for DNS to prove it. */
+export declare function isBlockedHostname(hostname: string): boolean;
+/** Parse and apply every check that doesn't need the network: shape, scheme,
+ *  obviously-internal hostname, and literal addresses. Returns null on reject.
+ *  Callers must still vet what non-literal hostnames resolve to. */
+export declare function parseSafeUrlShape(raw: string): URL | null;

package/dist/ssrf.js

@@ -0,0 +1,139 @@
+// The single SSRF deny-list for the monorepo: address classification and
+// URL-shape checks shared by every guard that fetches model-authored /
+// remote-user-supplied URLs (mastodon bridge urlGuard, core feeds httpClient).
+// Before #2459 the CIDR table was hand-copied per guard and had drifted.
+//
+// Everything here is pure and isomorphic — no `node:` builtins. The parts that
+// need the network (DNS resolution, per-redirect re-checks) stay in each
+// consumer's thin wrapper.
+/* eslint-disable sonarjs/no-hardcoded-ip -- the blocked ranges ARE this module's
+   specification; writing them as literals is the point, not an oversight. */
+const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);
+const BLOCKED_HOSTNAMES = new Set(["localhost", "ip6-localhost", "ip6-loopback"]);
+const BLOCKED_HOSTNAME_SUFFIXES = [".localhost", ".local", ".internal"];
+/** IPv4 ranges that must never be fetched, as [firstAddress, prefixLength].
+ *  The union of the pre-#2459 per-guard tables — removing an entry weakens
+ *  every guard in the repo at once, so treat edits as security changes. */
+export const BLOCKED_IPV4_RANGES = [
+    ["0.0.0.0", 8], // "this network"
+    ["10.0.0.0", 8], // RFC1918
+    ["100.64.0.0", 10], // CGNAT
+    ["127.0.0.0", 8], // loopback
+    ["169.254.0.0", 16], // link-local — includes the 169.254.169.254 metadata endpoint
+    ["172.16.0.0", 12], // RFC1918
+    ["192.0.0.0", 24], // IETF protocol assignments
+    ["192.168.0.0", 16], // RFC1918
+    ["198.18.0.0", 15], // benchmarking
+    ["224.0.0.0", 4], // multicast
+    ["240.0.0.0", 4], // reserved / broadcast
+];
+/** Dotted-decimal IPv4 → unsigned 32-bit value; null for anything else
+ *  (hex / octal octets, whitespace, wrong part count). */
+export function ipv4ToInt(address) {
+    const parts = address.split(".");
+    if (parts.length !== 4)
+        return null;
+    const octets = parts.map((part) => (/^\d{1,3}$/.test(part) ? Number(part) : Number.NaN));
+    if (octets.some((octet) => Number.isNaN(octet) || octet > 255))
+        return null;
+    return octets.reduce((value, octet) => value * 256 + octet, 0);
+}
+function isBlockedIpv4Value(value) {
+    return BLOCKED_IPV4_RANGES.some(([base, prefix]) => {
+        const baseValue = ipv4ToInt(base);
+        if (baseValue === null)
+            return false;
+        // `>>> 0` keeps the mask unsigned; a /0 shift would be a no-op anyway.
+        const mask = prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0;
+        return (value & mask) === (baseValue & mask);
+    });
+}
+/** True when this parses as IPv4 AND falls inside a blocked range. Non-IPv4
+ *  input is false — "not a blocked literal", not "safe"; a caller that must
+ *  reject non-IP input entirely does so at its own boundary. */
+export function isBlockedIpv4(address) {
+    const value = ipv4ToInt(address);
+    if (value === null)
+        return false;
+    return isBlockedIpv4Value(value);
+}
+/** `URL.hostname` keeps the brackets on an IPv6 literal (`[::1]`); strip them
+ *  so the address checks see the bare address. */
+export function stripIpv6Brackets(hostname) {
+    return hostname.replace(/^\[|\]$/g, "");
+}
+/** The 32-bit value inside an IPv4-mapped IPv6 literal, or null when the
+ *  address is not v4-mapped. The hex spelling matters: WHATWG URL serializes
+ *  `[::ffff:127.0.0.1]` as `::ffff:7f00:1`, so matching only the dotted form
+ *  would wave the mapped loopback through any URL-sourced check. */
+function mappedIpv4Value(lower) {
+    const dotted = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(lower);
+    if (dotted)
+        return ipv4ToInt(dotted[1]);
+    const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(lower);
+    if (hex)
+        return Number.parseInt(hex[1], 16) * 0x10000 + Number.parseInt(hex[2], 16);
+    return null;
+}
+/** Blocks loopback/unspecified, fc00::/7 unique-local, fe80::/10 link-local,
+ *  and IPv4-mapped forms of blocked v4 addresses. Mask-based on the leading
+ *  group — prefix string matching would miss e.g. fe9a:: (inside fe80::/10). */
+export function isBlockedIpv6(address) {
+    const lower = stripIpv6Brackets(address.toLowerCase());
+    if (lower === "::1" || lower === "::")
+        return true;
+    // IPv4-mapped re-enters the v4 rules.
+    const mapped = mappedIpv4Value(lower);
+    if (mapped !== null)
+        return isBlockedIpv4Value(mapped);
+    const [head] = lower.split(":");
+    if (head.length === 0)
+        return false;
+    const leading = Number.parseInt(head, 16);
+    if (Number.isNaN(leading))
+        return false;
+    if ((leading & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 unique-local
+    if ((leading & 0xffc0) === 0xfe80)
+        return true; // fe80::/10 link-local
+    return false;
+}
+/** True when this literal address must never be fetched. Non-IP input is
+ *  false — see `isBlockedIpv4`. */
+export function isBlockedIp(address) {
+    return address.includes(":") ? isBlockedIpv6(address) : isBlockedIpv4(address);
+}
+/** Names that are internal by convention (localhost, *.local, *.internal…),
+ *  rejected without waiting for DNS to prove it. */
+export function isBlockedHostname(hostname) {
+    const lower = hostname.toLowerCase().replace(/\.$/, "");
+    if (BLOCKED_HOSTNAMES.has(lower))
+        return true;
+    return BLOCKED_HOSTNAME_SUFFIXES.some((suffix) => lower.endsWith(suffix));
+}
+function parseUrl(raw) {
+    try {
+        return new URL(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse and apply every check that doesn't need the network: shape, scheme,
+ *  obviously-internal hostname, and literal addresses. Returns null on reject.
+ *  Callers must still vet what non-literal hostnames resolve to. */
+export function parseSafeUrlShape(raw) {
+    const url = parseUrl(raw);
+    if (url === null)
+        return null;
+    if (!ALLOWED_PROTOCOLS.has(url.protocol))
+        return null;
+    const hostname = stripIpv6Brackets(url.hostname);
+    if (hostname.length === 0)
+        return null;
+    if (isBlockedHostname(hostname))
+        return null;
+    if (isBlockedIp(hostname))
+        return null;
+    return url;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmoclaude/common",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "General-purpose pure utilities (type guards, etc.) shared across the MulmoClaude host, bridges, and plugins",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,18 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./meta-webhook": {
+      "types": "./dist/meta-webhook.d.ts",
+      "import": "./dist/meta-webhook.js",
+      "require": "./dist/meta-webhook.js",
+      "default": "./dist/meta-webhook.js"
+    },
+    "./ssrf": {
+      "types": "./dist/ssrf.d.ts",
+      "import": "./dist/ssrf.js",
+      "require": "./dist/ssrf.js",
+      "default": "./dist/ssrf.js"
     }
   },
   "files": [