@crabcrop/mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @crabcrop/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A first-party MCP (Model Context Protocol) server for crabcrop, so coding agents can sign URLs, debug them, inspect results, and purge the cache without hand-rolling the scheme. It is a thin wrapper over [`@crabcrop/url`](../typescript) and the server's HTTP surface. The explainer comes from `@crabcrop/url`; the [playground](../../playground) ships its own copy of the same grammar, and both are pinned by a mirrored grammar corpus in their test suites, while signing everywhere runs the canonical `spec/test-vectors.json`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `sign_url` | Build and sign a URL from an operation string and a source (optional expiry). |
+| `explain_url` | Parse a URL back into its signature kind, explained segments, and source; malformed segments are flagged. |
+| `fetch_meta` | Fetch the server's meta JSON for a URL (dimensions, format, bytes, quality, placeholders on request). Only fetches URLs on the configured `CRABCROP_BASE` origin, never follows redirects, and caps the response at 256 KiB. |
+| `purge_result` | Evict a cached result by its URL remainder; a preset URL works as-is (the server expands it before matching). Only purges on the configured `CRABCROP_BASE` origin (a per-call `base` must match it) and refuses paths with dot segments. |
+
+## Setup
+
+The server runs over stdio with Node >= 22. Once published, point your MCP client at the installed package:
+
+```json
+{
+  "mcpServers": {
+    "crabcrop": {
+      "command": "npx",
+      "args": ["-y", "@crabcrop/mcp"],
+      "env": {
+        "CRABCROP_BASE": "https://images.example.com",
+        "CRABCROP_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
+
+From a checkout, it also runs directly from source (Node type-strips the TypeScript):
+
+```json
+{
+  "mcpServers": {
+    "crabcrop": {
+      "command": "node",
+      "args": ["/path/to/crabcrop/sdks/mcp/src/index.ts"],
+      "env": {
+        "CRABCROP_BASE": "https://images.example.com",
+        "CRABCROP_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
+
+For Claude Code:
+
+```bash
+claude mcp add crabcrop \
+  --env CRABCROP_BASE=https://images.example.com \
+  --env CRABCROP_SECRET=your-secret \
+  -- node /path/to/crabcrop/sdks/mcp/src/index.ts
+```
+
+`CRABCROP_BASE` and `CRABCROP_SECRET` are the defaults, and the environment is the recommended home for the secret: `sign_url` and `purge_result` still accept per-call `base`/`secret` overrides, but the per-call secret is deprecated because agentic clients persist tool arguments in their transcripts. With no secret configured, `sign_url` produces `unsafe` URLs for servers that allow them. `purge_result` always requires a secret, and it only ever sends its POST to the configured `CRABCROP_BASE` origin: a per-call `base` must match that origin, with no `CRABCROP_BASE` set the tool refuses outright, and paths carrying dot segments are refused, the same origin discipline `fetch_meta` follows.
+
+Both this package and `@crabcrop/url` ship compiled `dist/` builds (their `prepack` runs `tsc`). The published tarball is self-contained: the declared `@crabcrop/url` dependency is a `file:` path, which no registry install could resolve, so the package bundles it (`bundleDependencies`); the tarball carries the SDK's published form under its own `node_modules`, and installing the package is all a consumer does. In this repository's tests (no install step), a register hook maps `@crabcrop/url` to the SDK sources, and the pack test does the real thing instead of simulating it: `npm pack`, `npm install` the tarball into a fresh project, and a JSON-RPC round trip against the installed bin. The end-to-end test (`npm test`) spawns this server plus a real crabcrop binary and runs sign -> fetch -> meta -> purge against it; it needs `cargo build` to have produced `target/debug/crabcrop` and uses the bench fixture photo as its source.
+
+`server.json` in this directory is the MCP registry manifest (name `io.github.crabcrop/crabcrop`, matching the `mcpName` field in `package.json`); its versions are bumped by the same one-version tooling as every other artifact. The registry submission itself is a separate step and has not been made yet.

package/dist/index.js

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+/**
+ * A first-party MCP server for crabcrop: four tools over
+ * stdio, thin wrappers on the TypeScript SDK and the HTTP
+ * surface. No dependencies.
+ *
+ *   sign_url     build and sign a crabcrop URL
+ *   explain_url  parse a URL back into its segments, flagging errors
+ *   fetch_meta   the server's JSON meta for a URL
+ *   purge_result evict a cached result
+ *
+ * Configuration: CRABCROP_BASE and CRABCROP_SECRET in the
+ * environment are the defaults for sign_url and purge_result,
+ * so agents do not pass the secret on every call. Per-call
+ * secret arguments exist as an override but are deprecated:
+ * agentic clients persist tool arguments in transcripts, so
+ * the environment is the right home for the secret.
+ *
+ * Run: node src/index.ts   (Node >= 22, for type stripping)
+ */
+import { buildURL, explainUrl, purgeSignature } from "@crabcrop/url";
+const SERVER = { name: "crabcrop", version: "0.1.0" };
+const PROTOCOL = "2024-11-05";
+const envBase = process.env.CRABCROP_BASE ?? "";
+const envSecret = process.env.CRABCROP_SECRET ?? null;
+function textResult(text, isError = false) {
+    return { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) };
+}
+/**
+ * Tool arguments arrive as untyped JSON. Validate each one
+ * instead of coercing with String(...): a missing argument
+ * would otherwise be signed into a URL as the literal
+ * segment "undefined", and numbers and objects would
+ * stringify silently.
+ */
+function stringArg(args, name) {
+    const value = args[name];
+    if (typeof value !== "string") {
+        throw new Error(value === undefined
+            ? `missing required argument: ${name}`
+            : `argument ${name} must be a string, got ${typeof value}`);
+    }
+    return value;
+}
+function optionalStringArg(args, name) {
+    const value = args[name];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string") {
+        throw new Error(`argument ${name} must be a string, got ${typeof value}`);
+    }
+    return value;
+}
+function numberArg(args, name) {
+    const value = args[name];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number") {
+        throw new Error(`argument ${name} must be a number, got ${typeof value}`);
+    }
+    return value;
+}
+function boolArg(args, name) {
+    const value = args[name];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean") {
+        throw new Error(`argument ${name} must be a boolean, got ${typeof value}`);
+    }
+    return value;
+}
+/** Read a response body with a hard byte cap; null when exceeded. */
+async function readCapped(resp, cap) {
+    if (!resp.body)
+        return "";
+    const reader = resp.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > cap) {
+            await reader.cancel();
+            return null;
+        }
+        chunks.push(value);
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(merged);
+}
+/**
+ * Whether any path component of `path` is a dot segment.
+ * Mirrors has_dot_segment in the Rust loader: a component
+ * exactly `.` or `..`, with dots inside a name (`a.b`,
+ * `c..d`) counting as ordinary content. Because the string
+ * is later parsed as a WHATWG URL, the percent-encoded
+ * spellings (`%2e`, `.%2e`, `%2e.`, `%2e%2e`) count too, and
+ * backslashes are separators for http(s) URLs, so components
+ * are split on both.
+ */
+function hasDotSegment(path) {
+    return path.split(/[/\\]/).some((segment) => {
+        const decoded = segment.toLowerCase().replaceAll("%2e", ".");
+        return decoded === "." || decoded === "..";
+    });
+}
+const TOOLS = [
+    {
+        name: "sign_url",
+        description: "Build and sign a crabcrop URL from an operation string and a source. " +
+            "Returns the full URL. Uses CRABCROP_BASE / CRABCROP_SECRET from the " +
+            "environment unless base/secret arguments override them; with no secret " +
+            "the URL carries the literal `unsafe` signature segment. Prefer the environment for the secret: per-call secret arguments are deprecated.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                operations: {
+                    type: "string",
+                    description: "Operation string, e.g. \"crop:1200x630:smart/filters:format(webp)\"; may be empty and may contain preset: references.",
+                },
+                source: {
+                    type: "string",
+                    description: "Source locator: an http(s) URL, s3://bucket/key, gs://bucket/key, or file:// path.",
+                },
+                base: { type: "string", description: "crabcrop endpoint origin. Defaults to CRABCROP_BASE." },
+                secret: { type: "string", description: "Signing secret. Defaults to CRABCROP_SECRET; omit for unsafe URLs. Sensitive, deprecated: prefer the CRABCROP_SECRET environment variable; a per-call secret is kept in client transcripts." },
+                expires: { type: "number", description: "Optional unix-seconds expiry, emitted as an exp: segment." },
+                keyId: { type: "string", description: "Optional key ID stamped on the signature segment (`<key-id>:<tag>`) for servers running a secret rotation; they verify a keyed segment against the named key only." },
+            },
+            required: ["operations", "source"],
+            additionalProperties: false,
+        },
+        async run(args) {
+            const base = optionalStringArg(args, "base") ?? envBase;
+            if (!base)
+                throw new Error("no base: pass the base argument or set CRABCROP_BASE");
+            const secret = optionalStringArg(args, "secret") ?? envSecret;
+            const url = buildURL(base, secret, stringArg(args, "operations"), stringArg(args, "source"), {
+                expires: numberArg(args, "expires"),
+                keyId: optionalStringArg(args, "keyId"),
+            });
+            return textResult(url);
+        },
+    },
+    {
+        name: "explain_url",
+        description: "Parse a crabcrop URL back into its pieces: the signature kind, each " +
+            "operation segment with a plain-language explanation, exp: rendered as " +
+            "a UTC instant with an expired verdict, and the source. Malformed " +
+            "segments and unknown filters are reported as errors.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The full crabcrop URL or bare path." },
+            },
+            required: ["url"],
+            additionalProperties: false,
+        },
+        async run(args) {
+            const out = explainUrl(stringArg(args, "url"));
+            const lines = [];
+            if (out.signature) {
+                lines.push(`signature (${out.signature.kind}): ${out.signature.value}`);
+                lines.push(`  ${out.signature.detail}`);
+            }
+            for (const seg of out.segments) {
+                lines.push(`${seg.kind}: ${seg.raw}`);
+                lines.push(`  ${seg.error ? `ERROR: ${seg.error}` : seg.detail ?? ""}`);
+            }
+            if (out.source) {
+                lines.push(`source: ${out.source}`);
+            }
+            for (const error of out.errors) {
+                lines.push(`ERROR: ${error}`);
+            }
+            return textResult(lines.join("\n"), out.errors.length > 0);
+        },
+    },
+    {
+        name: "fetch_meta",
+        description: "Fetch the crabcrop meta JSON for a URL (the processed result's width, " +
+            "height, format, byte size, quality, and placeholder data on request). " +
+            "The URL must already be signed if the server requires signatures. " +
+            "For safety the URL's origin must match CRABCROP_BASE: this tool will " +
+            "not fetch arbitrary URLs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The full crabcrop URL." },
+                placeholders: { type: "boolean", description: "Also request placeholder data (default false)." },
+            },
+            required: ["url"],
+            additionalProperties: false,
+        },
+        async run(args) {
+            if (!envBase) {
+                return textResult("fetch_meta requires CRABCROP_BASE to be set: it only fetches URLs on the configured server's origin", true);
+            }
+            const urlArg = stringArg(args, "url");
+            let target;
+            try {
+                target = new URL(urlArg);
+            }
+            catch {
+                return textResult(`fetch_meta: not a valid URL: ${urlArg}`, true);
+            }
+            if (target.origin !== new URL(envBase).origin) {
+                return textResult(`fetch_meta: refusing to fetch ${target.origin}; only the configured server origin (${new URL(envBase).origin}) is allowed`, true);
+            }
+            const accept = boolArg(args, "placeholders")
+                ? "application/json; placeholders=1"
+                : "application/json";
+            let resp;
+            try {
+                resp = await fetch(target, {
+                    headers: { accept },
+                    redirect: "error",
+                    signal: AbortSignal.timeout(10_000),
+                });
+            }
+            catch (err) {
+                return textResult(`meta request failed: ${err instanceof Error ? err.message : String(err)}`, true);
+            }
+            const body = await readCapped(resp, 256 * 1024);
+            if (body === null) {
+                return textResult("meta request failed: response exceeded the 256 KiB cap", true);
+            }
+            if (!resp.ok) {
+                return textResult(`meta request failed: HTTP ${resp.status}: ${body}`, true);
+            }
+            return textResult(body);
+        },
+    },
+    {
+        name: "purge_result",
+        description: "Evict a cached result from a crabcrop server. The path is the cached " +
+            "URL's remainder after its signature (operations and source; a preset " +
+            "URL works as-is, the server expands it). Requires the signing secret (argument or " +
+            "CRABCROP_SECRET). Returns how many entries were removed. " +
+            "For safety the request only goes to the configured CRABCROP_BASE " +
+            "origin (a base argument must match it) and paths with dot segments " +
+            "are refused: this tool will not POST to arbitrary endpoints.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Remainder of the cached URL, e.g. \"300x200/https://example.com/a.jpg\"." },
+                base: { type: "string", description: "crabcrop endpoint origin. Defaults to CRABCROP_BASE; its origin must match CRABCROP_BASE." },
+                secret: { type: "string", description: "Signing secret. Defaults to CRABCROP_SECRET. Sensitive, deprecated: prefer the CRABCROP_SECRET environment variable; a per-call secret is kept in client transcripts." },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+        async run(args) {
+            // The fetch_meta treatment (audit PL-1, extended by
+            // R2-10): the POST may only ever go to the configured
+            // server's origin. Without the check, a caller-chosen
+            // base made the tool an SSRF oracle: it POSTed to
+            // internal endpoints and read the responses back, and
+            // dot segments in the path resolved out of the
+            // /purge/ prefix onto arbitrary paths on that host.
+            // Refusing before any fetch keeps every disallowed or
+            // unreachable target indistinguishable: no request is
+            // sent, so there is no timing, status, or body signal
+            // to tell them apart.
+            if (!envBase) {
+                return textResult("purge_result requires CRABCROP_BASE to be set: it only purges on the configured server's origin", true);
+            }
+            const configuredOrigin = new URL(envBase).origin;
+            const base = (optionalStringArg(args, "base") ?? envBase).replace(/\/+$/, "");
+            let baseOrigin;
+            try {
+                baseOrigin = new URL(base).origin;
+            }
+            catch {
+                return textResult(`purge_result: not a valid base URL: ${base}`, true);
+            }
+            if (baseOrigin !== configuredOrigin) {
+                return textResult(`purge_result: refusing to purge ${baseOrigin}; only the configured server origin (${configuredOrigin}) is allowed`, true);
+            }
+            const secret = optionalStringArg(args, "secret") ?? envSecret;
+            if (!secret)
+                throw new Error("purge requires a secret: pass the secret argument or set CRABCROP_SECRET");
+            const target = stringArg(args, "path").replace(/^\//, "");
+            if (hasDotSegment(target)) {
+                return textResult("purge_result: refusing a path with dot segments: they would resolve out of the purge prefix", true);
+            }
+            // The SDK's helper: purge signatures are
+            // domain-separated from image signatures (audit P-1),
+            // and the derivation lives in exactly one place.
+            const signature = purgeSignature(secret, target);
+            // The same network hygiene as fetch_meta: no
+            // redirects, a bounded wait, and a capped body, so a
+            // hung or hostile endpoint cannot hang the tool call
+            // or stream an unbounded response.
+            let resp;
+            try {
+                resp = await fetch(`${base}/purge/${signature}/${target}`, {
+                    method: "POST",
+                    redirect: "error",
+                    signal: AbortSignal.timeout(10_000),
+                });
+            }
+            catch (err) {
+                return textResult(`purge request failed: ${err instanceof Error ? err.message : String(err)}`, true);
+            }
+            const body = await readCapped(resp, 256 * 1024);
+            if (body === null) {
+                return textResult("purge failed: response exceeded the 256 KiB cap", true);
+            }
+            if (!resp.ok) {
+                return textResult(`purge failed: HTTP ${resp.status}: ${body.trim()}`, true);
+            }
+            return textResult(body.trim());
+        },
+    },
+];
+async function handle(req) {
+    switch (req.method) {
+        case "initialize":
+            return {
+                protocolVersion: PROTOCOL,
+                capabilities: { tools: {} },
+                serverInfo: SERVER,
+            };
+        case "ping":
+            return {};
+        case "tools/list":
+            return {
+                tools: TOOLS.map(({ name, description, inputSchema }) => ({
+                    name,
+                    description,
+                    inputSchema,
+                })),
+            };
+        case "tools/call": {
+            const params = req.params ?? {};
+            const tool = TOOLS.find((t) => t.name === params.name);
+            if (!tool) {
+                return textResult(`unknown tool: ${String(params.name)}`, true);
+            }
+            try {
+                return await tool.run(params.arguments ?? {});
+            }
+            catch (err) {
+                return textResult(`error: ${err instanceof Error ? err.message : String(err)}`, true);
+            }
+        }
+        default:
+            return undefined; // Notifications and unknown methods: no reply.
+    }
+}
+// Transport: newline-delimited JSON-RPC over stdio. Lines
+// are capped (readline would buffer an unbounded line in
+// memory) and requests are handled one at a time through a
+// promise chain, so side-effecting calls cannot race
+// (audit PL-9).
+const MAX_LINE_BYTES = 1024 * 1024;
+let chain = Promise.resolve();
+let buffered = "";
+let discarding = false;
+function enqueue(line) {
+    chain = chain.then(async () => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let req;
+        try {
+            req = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        if (req.id === undefined || req.id === null) {
+            await handle(req); // A notification: handle silently.
+            return;
+        }
+        const result = await handle(req);
+        process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: req.id, result: result ?? {} })}\n`);
+    });
+}
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+    buffered += chunk;
+    for (;;) {
+        const nl = buffered.indexOf("\n");
+        if (discarding) {
+            if (nl === -1) {
+                buffered = "";
+                return;
+            }
+            buffered = buffered.slice(nl + 1);
+            discarding = false;
+            continue;
+        }
+        if (nl === -1) {
+            if (buffered.length > MAX_LINE_BYTES) {
+                // An over-long line: drop it and everything up to
+                // its newline, and answer with a protocol error.
+                buffered = "";
+                discarding = true;
+                process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32600, message: "request line too large" } })}\n`);
+            }
+            return;
+        }
+        const line = buffered.slice(0, nl);
+        buffered = buffered.slice(nl + 1);
+        enqueue(line);
+    }
+});

package/node_modules/@crabcrop/url/README.md

@@ -0,0 +1,81 @@
+# @crabcrop/url
+
+Build and sign [crabcrop](https://github.com/dayvson/crabcrop) URLs from TypeScript or JavaScript. Standard library only (`node:crypto`); the signing scheme is specified in [`spec/url-signing.md`](../../spec/url-signing.md). Signing is pinned by the canonical [`spec/test-vectors.json`](../../spec/test-vectors.json), which this package runs as tests, and the explainer's verdicts are pinned by a grammar corpus mirrored in the playground's test suite.
+
+## Usage
+
+```ts
+import { buildURL, buildSrcSet, purgeGroupSignature, purgeSignature, sign, uploadSignature, verifyUrlSignature } from "@crabcrop/url";
+
+// A signed URL. The operation string is passed verbatim and may
+// contain several segments and preset: references.
+const url = buildURL(
+  "https://images.example.com",
+  "your-secret",
+  "crop:1200x630:smart/filters:format(webp)",
+  "https://example.com/photo.jpg",
+);
+
+// An expiring URL (unix seconds), emitted as a leading exp: segment.
+const expiring = buildURL(
+  "https://images.example.com",
+  "your-secret",
+  "300x200",
+  "https://example.com/photo.jpg",
+  { expires: 1893456000 },
+);
+
+// A responsive srcset: one {width}x0 URL per width.
+const srcset = buildSrcSet(
+  "https://images.example.com",
+  "your-secret",
+  "https://example.com/photo.jpg",
+  [400, 800, 1200],
+);
+
+// The raw signature for a remainder, if you assemble URLs yourself.
+const signature = sign("your-secret", "300x200/https://example.com/photo.jpg");
+
+// Verify a signed URL's signature locally, in constant time
+// (unsigned or malformed URLs return null).
+const ok = verifyUrlSignature("your-secret", url);
+
+// Purge signatures for the server's /purge and /purge-group endpoints
+// are domain-separated under a derived subkey; the helpers sign the
+// right strings so callers never assemble them by hand.
+const purge = purgeSignature("your-secret", "300x200/https://example.com/photo.jpg");
+const group = purgeGroupSignature("your-secret", "thumb");
+
+// Upload signatures for the server's PUT /upload/<signature>/<name>
+// endpoint live in a third domain, under their own derived subkey.
+const upload = uploadSignature("your-secret", "heroes/photo.jpg");
+```
+
+Pass `null` as the secret to produce the literal `unsafe` signature segment, for servers running with `CRABCROP_ALLOW_UNSAFE` or in presets-only mode.
+
+## Typed operations
+
+The operation string is the spec, and passing it verbatim stays the primary API. For callers who would rather build it, `ops` and `filter` are typed builders that validate each argument against the server's grammar and return the canonical spelling, so the typed and hand-written forms sign byte-identical URLs (the test suite pins this against the canonical corpus):
+
+```ts
+import { buildURL, filter, joinOps, ops } from "@crabcrop/url";
+
+const operations = joinOps(
+  ops.crop(1200, 630, "smart"),
+  ops.filters(filter.format("webp"), filter.quality(80)),
+);
+// operations === "crop:1200x630:smart/filters:format(webp):quality(80)"
+const url = buildURL("https://images.example.com", "your-secret", operations, "https://example.com/photo.jpg");
+```
+
+A value the server would reject (`filter.quality(0)`, `filter.brighten(256)`, `ops.crop(0, 100)`) throws at build time instead of minting a URL that fails at the edge. The closed sets are exported as types (`ImageFormat`, `CropAlign`, `Anchor`, `BlendMode`, `MaskShape`, `Dimension`), and `FILTER_DESCRIPTIONS` is the filter metadata table the explainer uses.
+
+## Runtime
+
+The package is TypeScript and runs directly on Node >= 22 (type stripping), which is also how the tests run:
+
+```bash
+node --test
+```
+
+In this repository the framework loaders and the MCP server resolve `@crabcrop/url` to these sources; a standalone install comes from npm once published, or from the repository with `"@crabcrop/url": "file:../typescript"` as the MCP package in this repo does.

package/node_modules/@crabcrop/url/dist/explain.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Parse a crabcrop URL (or bare path) back into its pieces and
+ * explain each segment, mirroring the server's grammar. This is
+ * the canonical implementation: the playground keeps a plain-JS
+ * copy for its no-build static page, and both are pinned to the
+ * same verdict corpus (audit PL-10, P-3).
+ */
+/** The segment kinds an explanation is made of. */
+export type SegmentKind = "expiry" | "maxage" | "debug" | "preset" | "operation";
+/** The signature kinds an explanation can report. */
+export type SignatureKind = "hmac" | "unsafe" | "invalid";
+export interface ExplainedSegment {
+    raw: string;
+    kind: SegmentKind;
+    title: string;
+    detail?: string;
+    error?: string;
+    expired?: boolean;
+}
+export interface Explanation {
+    signature: {
+        kind: SignatureKind;
+        value: string;
+        detail: string;
+        keyId?: string;
+    } | null;
+    segments: ExplainedSegment[];
+    source: string;
+    remainder: string;
+    errors: string[];
+}
+export declare const FILTER_DESCRIPTIONS: Record<string, string>;
+/**
+ * Parse a crabcrop URL (or bare path) back into its pieces,
+ * explaining each segment. Mirrors the server's dispatch:
+ * segments are operations until the first segment that is not
+ * one; everything from there is the source.
+ *
+ * Returns { signature, segments, source, remainder, errors }
+ * where segments carry { raw, kind, title, detail?, error? }.
+ */
+export declare function explainUrl(input: string, nowSeconds?: number): Explanation;