@forumone/throughline 0.0.0-stage → 1.0.0-next.0

package/dist/mcp/payload-mcp.js

@@ -0,0 +1,175 @@
+import { z } from 'zod';
+import { defaultLogger } from '../logger/index.js';
+import { auditContext } from './audit-context.js';
+import { McpMetaSchema } from './meta.js';
+/**
+ * Wraps one Throughline tool so Payload's MCP plugin can serve it.
+ *
+ * Three things are being translated, and none of them is the tool's logic:
+ *
+ * - **The schema.** `plugin-mcp` wants the raw shape; `withMeta` produces a
+ *   `z.object` around it. `.shape` is the whole conversion, which is why tools
+ *   must build their input with `withMeta` or `z.object` rather than an
+ *   arbitrary `ZodType`.
+ * - **The context.** Payload hands the handler a request. Throughline's tools
+ *   take a `McpToolContext`, so one is built from it.
+ * - **The result.** Payload wants MCP content blocks; Throughline's tools
+ *   return their own objects, exactly as they do through this package's own
+ *   handler, which does the same wrapping a layer up.
+ */
+/*
+Whether a tool answered with a refusal, and so whether MCP's `isError` belongs
+on the result.
+
+Every server in the suite refuses the same way — `deniedEnvelope`, or a bare
+`{ error }` built in the tool — and returns it as an ordinary value rather than
+throwing, so a denial reads to the model as a denial rather than as a server
+fault. What none of them did was set `isError`, so a refusal arrived as a
+**successful** tool result carrying `{"error": …}`. An agent that checks the
+protocol's flag instead of parsing the body read every refusal as a success —
+including "Must be authenticated to use the publishing tools", which is the one
+every `Bearer` call gets, because `plugin-mcp` assigns no `req.user`.
+
+Found exercising `04` F-02 with a real MCP key, and recorded in the consuming
+repository's #614. It is a reporting defect rather than an access one: nothing
+was permitted that should not have been, and everything that was refused stayed
+refused.
+
+Here rather than in each tool for the reason the audit wrap below is here. This
+is the one place every tool in the suite passes through, so a tool written
+tomorrow is covered without its author knowing this file exists.
+
+**The test is a non-empty string `error`, not a sole `error` key.** A refusal
+that later grows a second field — a code, a retry hint — keeps its flag, which
+is the likelier shape to drift. It costs the inverse risk: a *success* payload
+carrying an `error` string would be flagged wrongly. Nothing in the suite does
+that today — the healthy shapes report through `ok`, `healthy`, `message` and
+`details` — and `payload-mcp.test.ts` pins it so a new one has to argue with a
+test rather than slip past.
+*/
+function isRefusal(result) {
+    if (typeof result !== 'object' || result === null)
+        return false;
+    const error = result['error'];
+    return typeof error === 'string' && error.trim() !== '';
+}
+export function toPayloadMcpTool(tool, options = {}) {
+    const shape = shapeOf(tool);
+    return {
+        name: tool.name,
+        description: tool.description,
+        parameters: shape,
+        handler: async (args, req) => {
+            const context = contextFrom(req, options);
+            try {
+                const result = await tool.handler(args, context);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                    ...(isRefusal(result) ? { isError: true } : {}),
+                };
+            }
+            catch (error) {
+                await recordToolFailure(tool.name, error, args, context, options);
+                throw error;
+            }
+        },
+    };
+}
+/*
+The one place a tool's crash becomes a row, and the reason `system.error` had a
+name in the taxonomy and no writer.
+
+Audit 12 H3: `'system.error'` was declared in `audit/types.ts`, present in the
+Postgres enum, and written by nothing — while `observability.md` opened with
+"the audit log is the single most useful debugging tool" and listed errors among
+what lands there. A tool that returns `deniedEnvelope` or an `{ error }` result
+audits itself; a tool that *throws* did not, so the failures most worth reading
+were the only ones absent.
+
+This is the choke point every tool in the suite passes through — all six
+servers, every tool — so wrapping here is one wrap rather than one per tool,
+and a tool added tomorrow is covered without its author knowing this file
+exists. It also covers the tools that audit nothing else: `list_components`,
+`get_contract`, `get_variants`, `get_tokens` and the five audit reads write no
+row on success, so a crash is the only thing they have ever recorded.
+
+Three properties it has to have, in order:
+
+**The original error still propagates.** `plugin-mcp` turns a throw into a
+JSON-RPC error and the client needs that. Recording is a side effect, not a
+handler.
+
+**Recording cannot itself fail the call.** `createAuditWriter` already swallows
+its own write failures, but `options.audit` is an interface and a caller may
+pass something less careful, so the `await` is wrapped too. An audit miss is a
+gap in a log; a throw from here would replace the tool's real error with this
+file's, which is the one outcome that would make debugging worse rather than
+better.
+
+**The message is the error's, and nothing else.** No stack: `errorMessage` is a
+`varchar` on a table admins and editors can read through the admin UI, and a
+stack names file paths and sometimes argument values. The arguments are not
+recorded either — a tool's input can carry a form submission or a draft — but
+`_meta` is, because the agent's own prompt and reasoning are what make a crash
+row legible, and they are already recorded on every successful write.
+*/
+async function recordToolFailure(toolName, error, args, context, options) {
+    const { audit, auditServer } = options;
+    const logger = context.logger ?? defaultLogger;
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(`MCP tool "${toolName}" threw`, { tool: toolName, error: message });
+    if (!audit || !auditServer)
+        return;
+    try {
+        const meta = McpMetaSchema.safeParse(args['_meta']);
+        await audit({
+            ...auditContext(context, meta.success ? meta.data : undefined),
+            action: 'system.error',
+            mcpServer: auditServer,
+            mcpTool: toolName,
+            summary: `${toolName} threw: ${message}`,
+            success: false,
+            errorMessage: message,
+        });
+    }
+    catch (recordError) {
+        logger.error('Recording an MCP tool failure failed', {
+            tool: toolName,
+            error: String(recordError),
+        });
+    }
+}
+/** Every tool in a server, in one call. */
+export function toPayloadMcpTools(tools, options = {}) {
+    return tools.map(tool => toPayloadMcpTool(tool, options));
+}
+function shapeOf(tool) {
+    const schema = tool.inputSchema;
+    if (schema instanceof z.ZodObject)
+        return schema.shape;
+    throw new Error(`Tool "${tool.name}" has an input schema that is not a z.object, so it has no shape to hand ` +
+        `Payload's MCP plugin. Build tool inputs with \`withMeta({ … })\` or \`z.object({ … })\`.`);
+}
+function contextFrom(req, options) {
+    const user = req.user
+        ? {
+            id: String(req.user.id ?? ''),
+            email: String(req.user.email ?? ''),
+            name: String(req.user.name ?? req.user.email ?? ''),
+            roles: Array.isArray(req.user.roles) ? req.user.roles : [],
+            groups: Array.isArray(req.user.groups) ? req.user.groups : [],
+        }
+        : null;
+    return {
+        user,
+        /*
+        The strategy name is the honest fallback. `plugin-mcp` resolves a key to its
+        linked user and does not carry the key document forward, so "which key" is
+        not a question the request can answer — and an audit row saying
+        `mcp-api-key` is better than one asserting a name nothing checked.
+        */
+        apiKeyName: options.apiKeyName ?? (req.payloadAPI === 'MCP' ? 'mcp-api-key' : ''),
+        logger: options.logger ?? req.payload?.logger ?? defaultLogger,
+    };
+}
+//# sourceMappingURL=payload-mcp.js.map

package/dist/mcp/payload-mcp.js.map

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

package/dist/media/hooks.d.ts

@@ -0,0 +1,70 @@
+import { type CollectionAfterChangeHook, type CollectionBeforeChangeHook } from 'payload';
+/**
+ * `beforeChange`: refuse a type not on the list, on create. The list is the
+ * same one given to `upload.mimeTypes`, which does not run on a client upload.
+ */
+export declare function refuseMimeTypesOutside(allowed: readonly string[], message?: (mimeType: string) => string): CollectionBeforeChangeHook;
+/**
+ * `beforeChange`: refuse a client upload whose stored key and recorded key
+ * disagree, so its link would not resolve.
+ *
+ * A client upload picks two names independently: the browser PUTs under the
+ * name it has, and `generateFileData` may record a different one, say
+ * `hero-1.mp4` for a name the collection already holds. Compared against
+ * `req.file.name` and the prefix the browser reports back through
+ * `clientUploadContext`, which are facts rather than reconstructions. Only where
+ * the browser did the uploading: a server-side write is stored under the name
+ * Payload chose, and renaming around a collision is right there.
+ */
+export declare function refuseStorageKeyMismatch(collectionPrefix?: string): CollectionBeforeChangeHook;
+/**
+ * `afterChange`: re-read an SVG that reached storage, run it through
+ * `sanitizeSvg`, and write the clean version over it if anything was removed.
+ *
+ * After the write because that is the first moment the bytes exist where this
+ * code can read them. There is a window between the browser's upload and this
+ * finishing during which the original is reachable by URL; closing it means
+ * giving up client uploads. Failures are logged and swallowed: a logo that could
+ * not be re-read is not a reason to fail a save that has already happened.
+ */
+export declare function sanitizeStoredSvg(options?: {
+    collectionPrefix?: string;
+    token?: string;
+}): CollectionAfterChangeHook;
+/** What the store says it is holding. */
+export interface StoredObject {
+    size: number;
+    contentType?: string | undefined;
+}
+/** What a media document claims about its own file. */
+export interface RecordedFacts {
+    filesize?: number | null | undefined;
+    mimeType?: string | null | undefined;
+}
+/**
+ * The fields that contradict the stored object, or `undefined` for none.
+ * `mimeType` is corrected only towards a type the collection accepts: a browser
+ * that sent `application/octet-stream` would otherwise have that written.
+ */
+export declare function factsToCorrect(recorded: RecordedFacts, stored: StoredObject, mimeTypes: readonly string[]): Partial<{
+    filesize: number;
+    mimeType: string;
+}> | undefined;
+/**
+ * `afterChange`: make `filesize` and `mimeType` describe the object actually in
+ * the store.
+ *
+ * With client uploads, Payload records them from a conversion it ran in memory
+ * (it re-fetches the object to apply the default focal point, runs it through
+ * sharp, and measures *that* buffer), which was never uploaded: forumone-2026
+ * found records wrong by as much as 60%. Nothing before the write can know, so
+ * the store is asked, with one `head()` per create. Written through
+ * `payload.db.updateOne` so it re-enters no hooks. Failures are logged and
+ * swallowed. Skipped for a non-URL `url`, which is local disk, where the file
+ * did go through the server and the fields are right.
+ */
+export declare function recordStoredFacts(options: {
+    mimeTypes: readonly string[];
+    token?: string;
+}): CollectionAfterChangeHook;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/media/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/media/hooks.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAChC,MAAM,SAAS,CAAA;AA6BhB;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,GAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MACiB,GAC/C,0BAA0B,CAS5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,gBAAgB,SAAK,GAAG,0BAA0B,CAuC1F;AAOD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1D,yBAAyB,CA0C3B;AAED,yCAAyC;AACzC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACjC;AAED,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CACrC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,CAQ7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,GAAG,yBAAyB,CAmC5B"}

package/dist/media/hooks.js

@@ -0,0 +1,200 @@
+import { head, put } from '@vercel/blob';
+import { ValidationError, } from 'payload';
+import { isRenderableSvg, sanitizeSvg } from './svg.js';
+import { storageKey } from './uploadKey.js';
+/*
+The hooks that make client uploads to Vercel Blob safe. From forumone-2026's
+`collections/Media.ts` and `media/recordStoredFacts.ts` (#486 F-05, #635, #691
+there).
+
+**Why hooks, when Payload has `upload.mimeTypes` and `validateSvg`.** With
+`clientUploads: true` the browser PUTs straight to Blob and the document
+arrives with metadata and no bytes. `generateFileData` returns before
+`checkFileRestrictions` for an upload with no buffer, so neither of Payload's own
+checks runs. These are the checks that do: two on the way in, two after the
+write, when the bytes finally exist somewhere this code can read.
+
+Mount them on the upload collection:
+
+```ts
+hooks: {
+  beforeChange: [refuseMimeTypesOutside(MIME_TYPES), refuseStorageKeyMismatch()],
+  afterChange: [sanitizeStoredSvg(), recordStoredFacts({ mimeTypes: MIME_TYPES })],
+}
+```
+
+with `uploadPrefixField()` among its fields. The two `afterChange` hooks in that
+order: a sanitised SVG is written back over the object and changes its size.
+*/
+/**
+ * `beforeChange`: refuse a type not on the list, on create. The list is the
+ * same one given to `upload.mimeTypes`, which does not run on a client upload.
+ */
+export function refuseMimeTypesOutside(allowed, message = (mimeType) => `${mimeType} is not a type this site accepts.`) {
+    return ({ data, operation }) => {
+        if (operation !== 'create')
+            return data;
+        const mimeType = typeof data?.['mimeType'] === 'string' ? data['mimeType'] : '';
+        if (mimeType && !allowed.includes(mimeType)) {
+            throw new ValidationError({ errors: [{ path: 'mimeType', message: message(mimeType) }] });
+        }
+        return data;
+    };
+}
+/**
+ * `beforeChange`: refuse a client upload whose stored key and recorded key
+ * disagree, so its link would not resolve.
+ *
+ * A client upload picks two names independently: the browser PUTs under the
+ * name it has, and `generateFileData` may record a different one, say
+ * `hero-1.mp4` for a name the collection already holds. Compared against
+ * `req.file.name` and the prefix the browser reports back through
+ * `clientUploadContext`, which are facts rather than reconstructions. Only where
+ * the browser did the uploading: a server-side write is stored under the name
+ * Payload chose, and renaming around a collision is right there.
+ */
+export function refuseStorageKeyMismatch(collectionPrefix = '') {
+    return ({ data, operation, req }) => {
+        if (operation !== 'create')
+            return data;
+        const file = req?.file;
+        const context = file?.clientUploadContext;
+        if (!file || !context)
+            return data;
+        const written = storageKey({
+            prefix: context.prefix,
+            filename: file.name,
+        }, collectionPrefix);
+        const recorded = storageKey({
+            prefix: typeof data?.['prefix'] === 'string' ? data['prefix'] : '',
+            filename: typeof data?.['filename'] === 'string' ? data['filename'] : '',
+        }, collectionPrefix);
+        if (!written || !recorded || written === recorded)
+            return data;
+        const sameFolder = written.replace(/[^/]+$/, '') === recorded.replace(/[^/]+$/, '');
+        throw new ValidationError({
+            errors: [
+                {
+                    path: 'filename',
+                    message: sameFolder
+                        ? `A file called ${file.name} is already in the library. This upload was stored under ` +
+                            `that same name but would have been recorded as ${String(data?.['filename'])}, so its ` +
+                            `link would not resolve. Rename your file and upload it again.`
+                        : `This upload was stored at ${written} but the document would have recorded ${recorded}, ` +
+                            `so its link would not resolve. Nothing is wrong with the file: this is a fault in the ` +
+                            `upload path itself, and it will affect every upload until it is fixed. Please report it.`,
+                },
+            ],
+        });
+    };
+}
+const tokenOf = (token) => {
+    const value = token ?? process.env['BLOB_READ_WRITE_TOKEN'];
+    return value ? { token: value } : {};
+};
+/**
+ * `afterChange`: re-read an SVG that reached storage, run it through
+ * `sanitizeSvg`, and write the clean version over it if anything was removed.
+ *
+ * After the write because that is the first moment the bytes exist where this
+ * code can read them. There is a window between the browser's upload and this
+ * finishing during which the original is reachable by URL; closing it means
+ * giving up client uploads. Failures are logged and swallowed: a logo that could
+ * not be re-read is not a reason to fail a save that has already happened.
+ */
+export function sanitizeStoredSvg(options = {}) {
+    return async ({ doc, operation, req }) => {
+        if (operation !== 'create')
+            return doc;
+        const record = doc;
+        if (record.mimeType !== 'image/svg+xml' || typeof record.url !== 'string')
+            return doc;
+        try {
+            const response = await fetch(record.url);
+            if (!response.ok) {
+                req.payload.logger.warn(`[media] could not re-read ${record.filename} to sanitise it: ${response.status}`);
+                return doc;
+            }
+            const { svg, removed } = sanitizeSvg(await response.text());
+            if (removed.length === 0)
+                return doc;
+            if (!isRenderableSvg(svg)) {
+                req.payload.logger.error(`[media] ${record.filename} was not an SVG once cleaned; leaving it and flagging`);
+                return doc;
+            }
+            await put(storageKey(record, options.collectionPrefix), svg, {
+                access: 'public',
+                addRandomSuffix: false,
+                allowOverwrite: true,
+                contentType: 'image/svg+xml',
+                ...tokenOf(options.token),
+            });
+            req.payload.logger.info(`[media] sanitised ${record.filename}, removed: ${removed.join(', ')}`);
+        }
+        catch (error) {
+            req.payload.logger.warn({ err: error, msg: `[media] sanitising ${record.filename} failed` });
+        }
+        return doc;
+    };
+}
+/**
+ * The fields that contradict the stored object, or `undefined` for none.
+ * `mimeType` is corrected only towards a type the collection accepts: a browser
+ * that sent `application/octet-stream` would otherwise have that written.
+ */
+export function factsToCorrect(recorded, stored, mimeTypes) {
+    const correction = {};
+    if (stored.size > 0 && stored.size !== recorded.filesize)
+        correction.filesize = stored.size;
+    const contentType = stored.contentType?.split(';')[0]?.trim();
+    if (contentType && contentType !== recorded.mimeType && mimeTypes.includes(contentType)) {
+        correction.mimeType = contentType;
+    }
+    return Object.keys(correction).length > 0 ? correction : undefined;
+}
+/**
+ * `afterChange`: make `filesize` and `mimeType` describe the object actually in
+ * the store.
+ *
+ * With client uploads, Payload records them from a conversion it ran in memory
+ * (it re-fetches the object to apply the default focal point, runs it through
+ * sharp, and measures *that* buffer), which was never uploaded: forumone-2026
+ * found records wrong by as much as 60%. Nothing before the write can know, so
+ * the store is asked, with one `head()` per create. Written through
+ * `payload.db.updateOne` so it re-enters no hooks. Failures are logged and
+ * swallowed. Skipped for a non-URL `url`, which is local disk, where the file
+ * did go through the server and the fields are right.
+ */
+export function recordStoredFacts(options) {
+    return async ({ doc, operation, req, collection }) => {
+        if (operation !== 'create')
+            return doc;
+        const record = doc;
+        const { url } = record;
+        if (typeof url !== 'string' || !/^https?:\/\//i.test(url))
+            return doc;
+        try {
+            const stored = await head(url, tokenOf(options.token));
+            const correction = factsToCorrect(record, stored, options.mimeTypes);
+            if (!correction || record.id === undefined)
+                return doc;
+            await req.payload.db.updateOne({
+                collection: collection.slug,
+                id: record.id,
+                data: correction,
+                req,
+            });
+            req.payload.logger.info(`[media] ${record.filename}: recorded ${record.mimeType} ${record.filesize}, stored ` +
+                `${stored.contentType} ${stored.size}; corrected ${Object.keys(correction).join(' and ')}`);
+            return { ...doc, ...correction };
+        }
+        catch (error) {
+            req.payload.logger.warn({
+                err: error,
+                msg: `[media] could not read ${record.filename} back to check its recorded size`,
+            });
+            return doc;
+        }
+    };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/media/hooks.js.map

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

package/dist/media/index.d.ts

@@ -0,0 +1,8 @@
+export { isRenderableSvg, sanitizeSvg } from './svg.js';
+export type { SanitizedSvg } from './svg.js';
+export { storageKey, uniqueUploadPrefix, uploadPrefixField } from './uploadKey.js';
+export type { KeyParts } from './uploadKey.js';
+export { factsToCorrect, recordStoredFacts, refuseMimeTypesOutside, refuseStorageKeyMismatch, sanitizeStoredSvg, } from './hooks.js';
+export type { RecordedFacts, StoredObject } from './hooks.js';
+export * from '../references/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/media/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/media/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AACvD,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAClF,YAAY,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAI7D,cAAc,wBAAwB,CAAA"}

package/dist/media/index.js

@@ -0,0 +1,7 @@
+export { isRenderableSvg, sanitizeSvg } from './svg.js';
+export { storageKey, uniqueUploadPrefix, uploadPrefixField } from './uploadKey.js';
+export { factsToCorrect, recordStoredFacts, refuseMimeTypesOutside, refuseStorageKeyMismatch, sanitizeStoredSvg, } from './hooks.js';
+// Reference tracking: what refers to a document, the guards that refuse to
+// delete or trash it while something does, and the "Used on" panel.
+export * from '../references/index.js';
+//# sourceMappingURL=index.js.map

package/dist/media/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/media/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAEvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAElF,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,YAAY,CAAA;AAGnB,2EAA2E;AAC3E,oEAAoE;AACpE,cAAc,wBAAwB,CAAA"}

package/dist/media/svg.d.ts

@@ -0,0 +1,17 @@
+export interface SanitizedSvg {
+    /** The cleaned document. */
+    svg: string;
+    /** What was taken out, for a message somebody can act on. Empty when nothing was. */
+    removed: string[];
+}
+/**
+ * Rewrite an SVG to the allowlist above.
+ *
+ * `removed` is a set of short labels — `<script>`, `onload`, `href` — rather
+ * than the offending source, because the caller puts them in front of an editor
+ * and a truncated payload is neither reassuring nor useful.
+ */
+export declare function sanitizeSvg(source: string): SanitizedSvg;
+/** Whether a sanitised document still contains an `<svg>` root worth storing. */
+export declare function isRenderableSvg(svg: string): boolean;
+//# sourceMappingURL=svg.d.ts.map

package/dist/media/svg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"svg.d.ts","sourceRoot":"","sources":["../../src/media/svg.ts"],"names":[],"mappings":"AAwGA,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,qFAAqF;IACrF,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAqJxD;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD"}