@dxj.jp/md-embed 0.1.0 → 0.2.0

package/README.md

@@ -45,10 +45,49 @@ Any `text/html` response passing through the middleware gets its `<md-embed>` el
 ```ts
 render(markdown, options?)            // Markdown → HTML string (wrapped in <article class="prose">)
 r2Resolver(bucket, { prefix? })       // MarkdownResolver backed by an R2 bucket
+urlResolver({ allow, ... })           // opt-in: fetch Markdown from allowlisted external URLs
+combineResolvers(...resolvers)        // try resolvers in order; first non-null wins
 transform(response, resolver, opts?)  // stream-resolve <md-embed> in a Response
 mdEmbed(env => resolver, opts?)       // Hono-compatible middleware (no hono dependency)
 ```
 
+### Embedding from other sites (opt-in)
+
+By default `src` is resolved **locally only** (an R2 key) — external URLs are never
+fetched. To allow `<md-embed src="https://…">`, opt in with `urlResolver`, which is
+**default-deny**: it fetches nothing until you supply an `allow` rule, and only ever
+touches absolute URLs, so it composes with `r2Resolver`:
+
+```ts
+app.use(mdEmbed<Env>((env) => combineResolvers(
+  urlResolver({ allow: "https://raw.githubusercontent.com/DXJ-LLC/" }),
+  r2Resolver(env.CONTENT),
+)));
+```
+
+Now `<md-embed src="https://raw.githubusercontent.com/DXJ-LLC/md-embed/main/README.md">`
+renders, while a URL outside the allowlist falls through to R2 and ends up `not-found`.
+
+`allow` accepts a string (matched by **origin + path prefix**, so `"https://host"` and
+`"https://host/dir/"` are both host-boundary-safe — a bare prefix can't be spoofed by
+`https://host.evil.com`), a `RegExp` (tested against `href` — anchor it), a predicate
+`(url: URL) => boolean`, or an array of these. Only `https:` is fetched by default
+(`protocols` to change), and `init` is forwarded to `fetch`.
+
+**Two independent gates** guard resolution: the element-level `allowSrc` option runs
+first and shows a visible `data-md-error="not-allowed"`; the fetch-level `urlResolver`
+`allow` silently falls through (so a rejected URL ends up `not-found` via the next
+resolver, revealing nothing about the allowlist).
+
+> **Security.** External Markdown is untrusted, unsanitized third-party input — an
+> allowlisted host that gets compromised can inject HTML into your page. `urlResolver`
+> is default-deny and does not follow redirects by default (`redirect: "manual"`, so
+> a 3xx resolves to nothing) so a host can't 302 off-allowlist; if you opt back in,
+> the landing URL is re-checked. Keep
+> `allow` tight and prefer hosts you control. On Workers the edge has no private
+> network, so this is an XSS/abuse surface rather than a classic internal-SSRF one —
+> but treat it as a real trust boundary regardless.
+
 ### Options
 
 | Option | Default | Meaning |

package/dist/index.d.ts

@@ -24,6 +24,36 @@ export declare function render(markdown: string, options?: MdEmbedOptions): stri
 export declare function r2Resolver(bucket: R2Bucket, opts?: {
     prefix?: string;
 }): MarkdownResolver;
+/** A rule deciding whether a URL may be fetched: a prefix string, a RegExp (tested against href), or a predicate. */
+export type UrlAllowRule = string | RegExp | ((url: URL) => boolean);
+export interface UrlResolverOptions {
+    /**
+     * Allowlist of fetchable URLs — REQUIRED to fetch anything. With no rule the
+     * resolver fetches nothing (default-deny), so external embedding is strictly opt-in.
+     */
+    allow?: UrlAllowRule | UrlAllowRule[];
+    /** Permitted URL protocols. Default `["https:"]` (no plaintext `http:`). */
+    protocols?: string[];
+    /** Extra options for the outbound `fetch` (headers, cf options, `redirect`, …). */
+    init?: RequestInit;
+}
+/**
+ * Opt-in resolver that fetches Markdown from **absolute URLs** on other sites.
+ * Off by default and default-deny: it only fetches URLs matching `allow`, and
+ * no-ops (returns null) for relative `src` values so it composes cleanly with
+ * {@link r2Resolver} via {@link combineResolvers}.
+ *
+ *   urlResolver({ allow: "https://raw.githubusercontent.com/DXJ-LLC/" })
+ *
+ * Security: fetched Markdown is third-party, unsanitized input — only allowlist
+ * hosts you trust. Redirects are not followed by default (`redirect: "manual"`,
+ * so a 3xx becomes a non-ok response that resolves to nothing) — an allowlisted
+ * host therefore can't 302 off-allowlist. If you opt into following, the final
+ * URL is re-checked against `allow`.
+ */
+export declare function urlResolver(opts?: UrlResolverOptions): MarkdownResolver;
+/** Try resolvers in order; the first non-null result wins. Returns null if all miss. */
+export declare function combineResolvers(...resolvers: MarkdownResolver[]): MarkdownResolver;
 /**
  * Resolve every `<md-embed>` in an HTML response via HTMLRewriter (streaming —
  * the page is never fully buffered). Non-HTML responses pass through untouched.

package/dist/index.js

@@ -40,6 +40,83 @@ export function r2Resolver(bucket, opts = {}) {
         return { markdown: await object.text(), etag: object.httpEtag };
     };
 }
+const compileAllow = (allow) => {
+    const rules = allow == null ? [] : Array.isArray(allow) ? allow : [allow];
+    if (rules.length === 0)
+        return () => false; // default-deny
+    const tests = rules.map((rule) => {
+        if (typeof rule === "string") {
+            // Match on parsed origin + path prefix — never a raw `href.startsWith`,
+            // which would let "https://ok.example" match "https://ok.example.evil.com"
+            // or "https://ok.example@evil.example/". Throws now if `rule` isn't a URL.
+            const base = new URL(rule);
+            return (url) => url.origin === base.origin && url.pathname.startsWith(base.pathname);
+        }
+        if (rule instanceof RegExp)
+            return (url) => rule.test(url.href);
+        return rule;
+    });
+    return (url) => tests.some((t) => t(url));
+};
+/**
+ * Opt-in resolver that fetches Markdown from **absolute URLs** on other sites.
+ * Off by default and default-deny: it only fetches URLs matching `allow`, and
+ * no-ops (returns null) for relative `src` values so it composes cleanly with
+ * {@link r2Resolver} via {@link combineResolvers}.
+ *
+ *   urlResolver({ allow: "https://raw.githubusercontent.com/DXJ-LLC/" })
+ *
+ * Security: fetched Markdown is third-party, unsanitized input — only allowlist
+ * hosts you trust. Redirects are not followed by default (`redirect: "manual"`,
+ * so a 3xx becomes a non-ok response that resolves to nothing) — an allowlisted
+ * host therefore can't 302 off-allowlist. If you opt into following, the final
+ * URL is re-checked against `allow`.
+ */
+export function urlResolver(opts = {}) {
+    const allow = compileAllow(opts.allow);
+    const protocols = opts.protocols ?? ["https:"];
+    // Don't follow redirects: one could leave the allowlisted host. "manual" (not
+    // "error", which Workers' fetch rejects) surfaces a 3xx as a non-ok response.
+    const init = { redirect: "manual", ...opts.init };
+    return async (src) => {
+        let url;
+        try {
+            url = new URL(src);
+        }
+        catch {
+            return null; // relative src → not a URL this resolver handles
+        }
+        if (!protocols.includes(url.protocol) || !allow(url))
+            return null;
+        const res = await fetch(url.href, init);
+        if (!res.ok)
+            return null;
+        // If the caller opted into following redirects, the landing URL must still pass.
+        if (res.redirected) {
+            let final;
+            try {
+                final = new URL(res.url);
+            }
+            catch {
+                return null;
+            }
+            if (!protocols.includes(final.protocol) || !allow(final))
+                return null;
+        }
+        return { markdown: await res.text(), etag: res.headers.get("etag") ?? undefined };
+    };
+}
+/** Try resolvers in order; the first non-null result wins. Returns null if all miss. */
+export function combineResolvers(...resolvers) {
+    return async (src) => {
+        for (const resolve of resolvers) {
+            const out = await resolve(src);
+            if (out)
+                return out;
+        }
+        return null;
+    };
+}
 class MdEmbedHandler {
     resolve;
     options;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxj.jp/md-embed",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -38,7 +38,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kyutarou/md-embed.git"
+    "url": "git+https://github.com/DXJ-LLC/md-embed.git"
   },
   "pnpm": {
     "onlyBuiltDependencies": [