@makolabs/ripple 3.8.0 → 3.9.1

package/dist/elements/text-viewer/TextViewer.svelte

@@ -0,0 +1,141 @@
+<script lang="ts">
+	import { onDestroy } from 'svelte';
+	import { cn } from '../../helper/cls.js';
+	import { buildTestId } from '../../helper/testid.js';
+	import { isSafeHttpUrl, redactUrl } from '../../helper/is-safe-http-url.js';
+	import { MAX_TEXT_BYTES } from '../../helper/resource-limits.js';
+	import Spinner from '../spinner/Spinner.svelte';
+	import UnsupportedPreview from '../viewer-shared/UnsupportedPreview.svelte';
+	import { Color, Size } from '../../variants.js';
+	import type { TextViewerProps } from './text-viewer-types.js';
+
+	let {
+		url,
+		maxBytes = MAX_TEXT_BYTES,
+		loadingLabel = 'Loading file...',
+		errorTitle = 'Unable to display file',
+		errorActionLabel = 'Open in new tab',
+		class: className = '',
+		testId
+	}: TextViewerProps = $props();
+
+	// Allow same-origin (incl. dev localhost) OR a public cross-origin host.
+	// Block cross-origin private/loopback/metadata hosts (SSRF read-exfil).
+	const urlAllowed = $derived(
+		isSafeHttpUrl(url, { sameOrigin: true, allowPrivateHosts: true }) ||
+			isSafeHttpUrl(url, { allowPrivateHosts: false })
+	);
+
+	let status = $state<'loading' | 'ready' | 'error'>('loading');
+	let content = $state('');
+	let truncated = $state(false);
+	let controller: AbortController | null = null;
+
+	async function load(active: AbortController) {
+		if (!urlAllowed) {
+			status = 'error';
+			return;
+		}
+
+		try {
+			const res = await fetch(url, {
+				signal: active.signal,
+				redirect: 'error',
+				credentials: 'same-origin'
+			});
+			if (!res.ok || !res.body) throw new Error('bad response');
+
+			const reader = res.body.getReader();
+			const chunks: Uint8Array[] = [];
+			let received = 0;
+			let didTruncate = false;
+
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				if (!value) continue;
+				chunks.push(value);
+				received += value.byteLength;
+				if (received > maxBytes) {
+					await reader.cancel();
+					didTruncate = true;
+					break;
+				}
+			}
+
+			const total = chunks.reduce((n, c) => n + c.byteLength, 0);
+			const buffer = new Uint8Array(total);
+			let offset = 0;
+			for (const chunk of chunks) {
+				buffer.set(chunk, offset);
+				offset += chunk.byteLength;
+			}
+
+			// A newer load() may have superseded this one while we were reading;
+			// never write state for a stale (aborted) request.
+			if (active.signal.aborted) return;
+			content = new TextDecoder().decode(buffer.subarray(0, maxBytes));
+			truncated = didTruncate;
+			status = 'ready';
+		} catch (err) {
+			if (err instanceof Error && err.name === 'AbortError') return;
+			if (active.signal.aborted) return;
+			console.error(
+				'Error loading text:',
+				redactUrl(url),
+				err instanceof Error ? err.name : 'unknown'
+			);
+			status = 'error';
+		}
+	}
+
+	$effect(() => {
+		// re-run when url changes
+		void url;
+		// Abort any in-flight load before starting a new one so a late-resolving
+		// previous request can't write content for the wrong file.
+		controller?.abort();
+		status = 'loading';
+		content = '';
+		truncated = false;
+		const active = new AbortController();
+		controller = active;
+		load(active);
+		return () => active.abort();
+	});
+
+	onDestroy(() => {
+		controller?.abort();
+	});
+</script>
+
+<div
+	class={cn('bg-default-100 flex h-full flex-col', className)}
+	data-testid={buildTestId('text-viewer', undefined, testId)}
+>
+	{#if status === 'error'}
+		<UnsupportedPreview
+			url={urlAllowed ? url : undefined}
+			title={errorTitle}
+			actionLabel={errorActionLabel}
+			variant="error"
+			{testId}
+		/>
+	{:else if status === 'loading'}
+		<div class="flex flex-1 items-center justify-center">
+			<Spinner size={Size.LG} color={Color.PRIMARY} label={loadingLabel} />
+		</div>
+	{:else}
+		{#if truncated}
+			<div
+				class="border-default-200 bg-default-50 text-default-700 border-b px-4 py-2 text-sm"
+				data-testid={buildTestId('text-viewer', 'truncated', testId)}
+			>
+				Showing the first {Math.round(maxBytes / 1024)} KB of this file.
+			</div>
+		{/if}
+		<pre
+			class="text-default-900 flex-1 overflow-auto p-4 font-mono text-sm [overflow-wrap:anywhere] whitespace-pre-wrap"
+			data-testid={buildTestId('text-viewer', 'content', testId)}>{content}</pre>
+	{/if}
+</div>

package/dist/elements/text-viewer/TextViewer.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { TextViewerProps } from './text-viewer-types.js';
+declare const TextViewer: import("svelte").Component<TextViewerProps, {}, "">;
+type TextViewer = ReturnType<typeof TextViewer>;
+export default TextViewer;

package/dist/elements/text-viewer/text-viewer-types.d.ts

@@ -0,0 +1,10 @@
+import type { ClassValue } from 'tailwind-variants';
+export type TextViewerProps = {
+    url: string;
+    maxBytes?: number;
+    loadingLabel?: string;
+    errorTitle?: string;
+    errorActionLabel?: string;
+    class?: ClassValue;
+    testId?: string;
+};

package/dist/elements/text-viewer/text-viewer-types.js

@@ -0,0 +1 @@
+export {};

package/dist/elements/viewer-shared/UnsupportedPreview.svelte

@@ -0,0 +1,84 @@
+<script lang="ts">
+	import { cn } from '../../helper/cls.js';
+	import { buildTestId } from '../../helper/testid.js';
+	import Button from '../../button/Button.svelte';
+	import { Color, Size } from '../../variants.js';
+	import type { UnsupportedPreviewProps } from './unsupported-preview-types.js';
+
+	let {
+		url,
+		fileName,
+		title = 'Preview not available',
+		message,
+		actionLabel = 'Open in new tab',
+		variant = 'info',
+		class: className = '',
+		testId
+	}: UnsupportedPreviewProps = $props();
+</script>
+
+<div
+	class={cn('flex h-full w-full items-center justify-center p-6', className)}
+	data-testid={buildTestId('unsupported-preview', undefined, testId)}
+>
+	<div class="ring-default-200 max-w-md rounded-xl bg-white p-6 text-center shadow-sm ring-1">
+		<div
+			class={cn(
+				'mx-auto mb-3 flex size-10 items-center justify-center rounded-full',
+				variant === 'error' ? 'bg-danger-50 text-danger-600' : 'bg-default-100 text-default-600'
+			)}
+			aria-hidden="true"
+		>
+			{#if variant === 'error'}
+				<svg
+					xmlns="http://www.w3.org/2000/svg"
+					class="h-5 w-5"
+					viewBox="0 0 24 24"
+					fill="none"
+					stroke="currentColor"
+					stroke-width="2"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+				>
+					<circle cx="12" cy="12" r="10" />
+					<line x1="12" y1="8" x2="12" y2="12" />
+					<line x1="12" y1="16" x2="12.01" y2="16" />
+				</svg>
+			{:else}
+				<svg
+					xmlns="http://www.w3.org/2000/svg"
+					class="h-5 w-5"
+					viewBox="0 0 24 24"
+					fill="none"
+					stroke="currentColor"
+					stroke-width="2"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+				>
+					<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
+					<polyline points="14 2 14 8 20 8" />
+				</svg>
+			{/if}
+		</div>
+
+		<p class="text-default-900 mb-1 text-base font-semibold">{title}</p>
+		{#if fileName}
+			<p class="text-default-700 mb-1 text-sm break-all">{fileName}</p>
+		{/if}
+		{#if message}
+			<p class="text-default-600 mb-4 text-sm">{message}</p>
+		{/if}
+
+		{#if url}
+			<Button
+				color={Color.PRIMARY}
+				size={Size.SM}
+				href={url}
+				target="_blank"
+				rel="noopener noreferrer"
+			>
+				{actionLabel}
+			</Button>
+		{/if}
+	</div>
+</div>

package/dist/elements/viewer-shared/UnsupportedPreview.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { UnsupportedPreviewProps } from './unsupported-preview-types.js';
+declare const UnsupportedPreview: import("svelte").Component<UnsupportedPreviewProps, {}, "">;
+type UnsupportedPreview = ReturnType<typeof UnsupportedPreview>;
+export default UnsupportedPreview;

package/dist/elements/viewer-shared/ViewerToolbar.svelte

@@ -0,0 +1,128 @@
+<script lang="ts">
+	import { buildTestId } from '../../helper/testid.js';
+	import type { ViewerToolbarProps } from './viewer-toolbar-types.js';
+
+	let {
+		component = 'viewer',
+		scale,
+		minScale,
+		maxScale,
+		disabled = false,
+		leftLabel = '',
+		onzoomin: onZoomIn,
+		onzoomout: onZoomOut,
+		onfittowidth: onFitToWidth,
+		testId
+	}: ViewerToolbarProps = $props();
+
+	function handleZoomIn() {
+		onZoomIn?.();
+	}
+	function handleZoomOut() {
+		onZoomOut?.();
+	}
+	function handleFitToWidth() {
+		onFitToWidth?.();
+	}
+
+	const btnClass =
+		'text-default-700 hover:bg-default-100 focus-visible:ring-primary-400 rounded-md p-1.5 transition-colors focus-visible:ring-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-40';
+</script>
+
+<div
+	class="border-default-200 bg-default-50 flex items-center justify-between border-b px-4 py-2"
+	data-testid={buildTestId(component, 'toolbar', testId)}
+>
+	<div class="flex items-center gap-2">
+		<span class="text-default-700 text-sm" aria-live="polite">{leftLabel}</span>
+	</div>
+
+	<div class="flex items-center gap-1">
+		<button
+			type="button"
+			onclick={handleZoomOut}
+			disabled={disabled || scale <= minScale}
+			class={btnClass}
+			aria-label="Zoom out"
+			title="Zoom out"
+			data-testid={buildTestId(component, 'zoom-out', testId)}
+		>
+			<svg
+				xmlns="http://www.w3.org/2000/svg"
+				class="h-5 w-5"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				stroke-width="2"
+				stroke-linecap="round"
+				stroke-linejoin="round"
+				aria-hidden="true"
+			>
+				<circle cx="11" cy="11" r="8" />
+				<line x1="21" y1="21" x2="16.65" y2="16.65" />
+				<line x1="8" y1="11" x2="14" y2="11" />
+			</svg>
+		</button>
+
+		<span
+			class="text-default-700 min-w-[3.5rem] text-center text-sm tabular-nums"
+			aria-live="polite"
+			data-testid={buildTestId(component, 'scale', testId)}
+		>
+			{Math.round(scale * 100)}%
+		</span>
+
+		<button
+			type="button"
+			onclick={handleZoomIn}
+			disabled={disabled || scale >= maxScale}
+			class={btnClass}
+			aria-label="Zoom in"
+			title="Zoom in"
+			data-testid={buildTestId(component, 'zoom-in', testId)}
+		>
+			<svg
+				xmlns="http://www.w3.org/2000/svg"
+				class="h-5 w-5"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				stroke-width="2"
+				stroke-linecap="round"
+				stroke-linejoin="round"
+				aria-hidden="true"
+			>
+				<circle cx="11" cy="11" r="8" />
+				<line x1="11" y1="8" x2="11" y2="14" />
+				<line x1="8" y1="11" x2="14" y2="11" />
+			</svg>
+		</button>
+
+		<button
+			type="button"
+			onclick={handleFitToWidth}
+			{disabled}
+			class={btnClass}
+			aria-label="Fit to width"
+			title="Fit to width"
+			data-testid={buildTestId(component, 'fit-to-width', testId)}
+		>
+			<svg
+				xmlns="http://www.w3.org/2000/svg"
+				class="h-5 w-5"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				stroke-width="2"
+				stroke-linecap="round"
+				stroke-linejoin="round"
+				aria-hidden="true"
+			>
+				<polyline points="15 3 21 3 21 9" />
+				<polyline points="9 21 3 21 3 15" />
+				<line x1="21" y1="3" x2="14" y2="10" />
+				<line x1="3" y1="21" x2="10" y2="14" />
+			</svg>
+		</button>
+	</div>
+</div>

package/dist/elements/viewer-shared/ViewerToolbar.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { ViewerToolbarProps } from './viewer-toolbar-types.js';
+declare const ViewerToolbar: import("svelte").Component<ViewerToolbarProps, {}, "">;
+type ViewerToolbar = ReturnType<typeof ViewerToolbar>;
+export default ViewerToolbar;

package/dist/elements/viewer-shared/unsupported-preview-types.d.ts

@@ -0,0 +1,17 @@
+import type { ClassValue } from 'tailwind-variants';
+export type UnsupportedPreviewProps = {
+    /** When set, an "open/download" link is shown (scheme-guarded by Button). */
+    url?: string;
+    /** File name shown above the message (rendered as text). */
+    fileName?: string;
+    /** Card heading. @default 'Preview not available' */
+    title?: string;
+    /** Supporting line under the heading. */
+    message?: string;
+    /** Label of the open/download link. @default 'Open in new tab' */
+    actionLabel?: string;
+    /** Visual treatment. @default 'info' */
+    variant?: 'info' | 'error';
+    class?: ClassValue;
+    testId?: string;
+};

package/dist/elements/viewer-shared/unsupported-preview-types.js

@@ -0,0 +1 @@
+export {};

package/dist/elements/viewer-shared/viewer-toolbar-types.d.ts

@@ -0,0 +1,14 @@
+export type ViewerToolbarProps = {
+    /** testid namespace, e.g. 'image-viewer'. @default 'viewer' */
+    component?: string;
+    scale: number;
+    minScale: number;
+    maxScale: number;
+    disabled?: boolean;
+    /** Optional left-aligned label (e.g. a page or dimension hint). */
+    leftLabel?: string;
+    onzoomin?: () => void;
+    onzoomout?: () => void;
+    onfittowidth?: () => void;
+    testId?: string;
+};

package/dist/elements/viewer-shared/viewer-toolbar-types.js

@@ -0,0 +1 @@
+export {};

package/dist/funcs/clerk-requests.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pure builders for Clerk user-API requests, extracted from
+ * `user-management.remote.ts` so the request shape is unit-testable — a
+ * `*.remote.ts` module cannot be imported in vitest (SvelteKit's plugin rejects
+ * any non-remote export).
+ *
+ * They also document the rule that caused minted API keys to silently never
+ * persist: Clerk deprecated sending `private_metadata` in the body of
+ * `PATCH /users/{id}` (it now returns 422 `form_param_deprecated`). User
+ * metadata must be written through the dedicated `PATCH /users/{id}/metadata`
+ * endpoint, which merges into the existing metadata.
+ */
+export interface ClerkRequest {
+    endpoint: string;
+    init: {
+        method: string;
+        body: string;
+    };
+}
+/**
+ * Build a request that persists `privateMetadata` on a Clerk user via the
+ * dedicated metadata endpoint. Clerk merges the provided keys into the user's
+ * existing private metadata.
+ */
+export declare function clerkMetadataPatch(userId: string, privateMetadata: Record<string, unknown>): ClerkRequest;
+/**
+ * Build the body for a profile update (`PATCH /users/{id}`). Metadata is
+ * intentionally excluded — it must go through {@link clerkMetadataPatch}.
+ */
+export declare function clerkProfilePatchBody(userData: {
+    first_name?: string;
+    last_name?: string;
+    username?: string;
+}): Record<string, string>;

package/dist/funcs/clerk-requests.js

@@ -0,0 +1,38 @@
+/**
+ * Pure builders for Clerk user-API requests, extracted from
+ * `user-management.remote.ts` so the request shape is unit-testable — a
+ * `*.remote.ts` module cannot be imported in vitest (SvelteKit's plugin rejects
+ * any non-remote export).
+ *
+ * They also document the rule that caused minted API keys to silently never
+ * persist: Clerk deprecated sending `private_metadata` in the body of
+ * `PATCH /users/{id}` (it now returns 422 `form_param_deprecated`). User
+ * metadata must be written through the dedicated `PATCH /users/{id}/metadata`
+ * endpoint, which merges into the existing metadata.
+ */
+/**
+ * Build a request that persists `privateMetadata` on a Clerk user via the
+ * dedicated metadata endpoint. Clerk merges the provided keys into the user's
+ * existing private metadata.
+ */
+export function clerkMetadataPatch(userId, privateMetadata) {
+    return {
+        endpoint: `/users/${userId}/metadata`,
+        init: { method: 'PATCH', body: JSON.stringify({ private_metadata: privateMetadata }) }
+    };
+}
+/**
+ * Build the body for a profile update (`PATCH /users/{id}`). Metadata is
+ * intentionally excluded — it must go through {@link clerkMetadataPatch}.
+ */
+export function clerkProfilePatchBody(userData) {
+    const body = {};
+    if (userData.first_name !== undefined)
+        body.first_name = userData.first_name;
+    if (userData.last_name !== undefined)
+        body.last_name = userData.last_name;
+    if (userData.username !== undefined && userData.username !== '') {
+        body.username = userData.username;
+    }
+    return body;
+}

package/dist/funcs/user-management.remote.js

@@ -2,6 +2,7 @@ import { command } from '$app/server';
 import { getRequestEvent } from '$app/server';
 import { env } from '$env/dynamic/private';
 import { building } from '$app/environment';
+import { clerkMetadataPatch, clerkProfilePatchBody } from './clerk-requests.js';
 const CLIENT_ID = env.CLIENT_ID;
 const ORGANIZATION_ID = env.ALLOWED_ORG_ID;
 if (!CLIENT_ID && !building) {
@@ -248,6 +249,16 @@ async function createUserPermissions(email, permissions, clientId = CLIENT_ID) {
     log.trace('createUserPermissions', 'Result:', result);
     return result;
 }
+/**
+ * Persist private metadata on a Clerk user via the dedicated metadata endpoint.
+ * Clerk deprecated `private_metadata` in the body of `PATCH /users/{id}` (it
+ * now returns 422 form_param_deprecated), which silently dropped minted API
+ * keys. Routes through `PATCH /users/{id}/metadata` (which merges) instead.
+ */
+async function writeClerkMetadata(userId, privateMetadata) {
+    const { endpoint, init } = clerkMetadataPatch(userId, privateMetadata);
+    return makeClerkRequest(endpoint, init);
+}
 export const getUsers = command('unchecked', async (options) => {
     log.trace('getUsers', 'Called with options:', options);
     try {
@@ -347,14 +358,9 @@ export const createUser = command('unchecked', async (userData) => {
                 const apiKey = adminKeyResult?.data?.key;
                 log.trace('createUser', 'Admin key created, has key:', !!apiKey);
                 if (adminKeyResult && apiKey) {
-                    const updatedUser = await makeClerkRequest(`/users/${result.id}`, {
-                        method: 'PATCH',
-                        body: JSON.stringify({
-                            private_metadata: {
-                                ...result.private_metadata,
-                                mako_api_key: apiKey
-                            }
-                        })
+                    const updatedUser = await writeClerkMetadata(result.id, {
+                        ...result.private_metadata,
+                        mako_api_key: apiKey
                     });
                     // Ensure updatedUser is serializable
                     result = JSON.parse(JSON.stringify(updatedUser));
@@ -385,22 +391,19 @@ export const updateUser = command('unchecked', async (options) => {
     const { userId, userData } = options;
     log.trace('updateUser', 'Called for userId:', userId, 'fields:', Object.keys(userData));
     try {
-        const updateData = {};
-        if (userData.first_name !== undefined)
-            updateData.first_name = userData.first_name;
-        if (userData.last_name !== undefined)
-            updateData.last_name = userData.last_name;
-        if (userData.username !== undefined && userData.username !== '') {
-            updateData.username = userData.username;
-        }
+        // Profile fields and metadata live behind different Clerk endpoints —
+        // `private_metadata` is no longer accepted on PATCH /users/{id}.
+        const profileBody = clerkProfilePatchBody(userData);
+        log.trace('updateUser', 'Profile payload:', profileBody);
+        let result = Object.keys(profileBody).length > 0
+            ? await makeClerkRequest(`/users/${userId}`, {
+                method: 'PATCH',
+                body: JSON.stringify(profileBody)
+            })
+            : await makeClerkRequest(`/users/${userId}`);
         if (userData.private_metadata !== undefined) {
-            updateData.private_metadata = userData.private_metadata;
+            result = await writeClerkMetadata(userId, userData.private_metadata);
         }
-        log.trace('updateUser', 'Update payload:', updateData);
-        let result = await makeClerkRequest(`/users/${userId}`, {
-            method: 'PATCH',
-            body: JSON.stringify(updateData)
-        });
         // Ensure result is serializable
         result = JSON.parse(JSON.stringify(result));
         if (userData.permissions !== undefined) {
@@ -572,14 +575,9 @@ export const updateUserPermissions = command('unchecked', async (options) => {
             const newKeyResult = await createUserPermissions(email, permissions);
             const newApiKey = newKeyResult?.data?.key;
             if (newApiKey) {
-                await makeClerkRequest(`/users/${userId}`, {
-                    method: 'PATCH',
-                    body: JSON.stringify({
-                        private_metadata: {
-                            ...(user.private_metadata || {}),
-                            mako_api_key: newApiKey
-                        }
-                    })
+                await writeClerkMetadata(userId, {
+                    ...(user.private_metadata || {}),
+                    mako_api_key: newApiKey
                 });
                 log.trace('updateUserPermissions', 'New key stored in Clerk metadata');
             }
@@ -742,14 +740,9 @@ export const generateApiKey = command('unchecked', async (options) => {
                 currentUser = await makeClerkRequest(`/users/${options.userId}`);
             }
             if (currentUser) {
-                await makeClerkRequest(`/users/${options.userId}`, {
-                    method: 'PATCH',
-                    body: JSON.stringify({
-                        private_metadata: {
-                            ...(currentUser.private_metadata || {}),
-                            mako_api_key: newApiKey
-                        }
-                    })
+                await writeClerkMetadata(options.userId, {
+                    ...(currentUser.private_metadata || {}),
+                    mako_api_key: newApiKey
                 });
                 log.trace('generateApiKey', 'Clerk metadata updated with new key');
             }
@@ -874,11 +867,9 @@ export const approveUser = command('unchecked', async (input) => {
         if (!apiKey) {
             throw new Error('Failed to mint API key during approval');
         }
-        await makeClerkRequest(`/users/${input.userId}`, {
-            method: 'PATCH',
-            body: JSON.stringify({
-                private_metadata: { ...(user.private_metadata || {}), mako_api_key: apiKey }
-            })
+        await writeClerkMetadata(input.userId, {
+            ...(user.private_metadata || {}),
+            mako_api_key: apiKey
         });
         log.trace('approveUser', 'Approved and key issued');
         return JSON.parse(JSON.stringify({ apiKey }));

package/dist/helper/is-safe-http-url.d.ts

@@ -0,0 +1,33 @@
+/**
+ * URL safety helpers for the file-preview viewers. See spec §4 / threat
+ * register T0.1, T1.3, T1.4. `isSafeHttpUrl` is a strict allowlist; do not
+ * convert it to a denylist.
+ */
+/** True for loopback / link-local / private / metadata / encoded-IP hosts. */
+export declare function isBlockedHost(hostname: string): boolean;
+export type SafeUrlOptions = {
+    /** Base for resolving relative URLs. Defaults to document.baseURI in a browser. */
+    base?: string;
+    /** Allow same-origin blob: URLs. */
+    allowBlob?: boolean;
+    /** Require the resolved origin to be the base origin (or in allowedOrigins). */
+    sameOrigin?: boolean;
+    /** Extra origins permitted when sameOrigin is set. */
+    allowedOrigins?: string[];
+    /**
+     * Waive private/loopback/metadata host blocking, but ONLY for the base
+     * (same-origin) origin or an entry in `allowedOrigins`. This is not a blanket
+     * SSRF bypass: cross-origin private hosts stay blocked even when set. Intended
+     * for same-origin dev fetches (e.g. a localhost PDF served by the app itself).
+     */
+    allowPrivateHosts?: boolean;
+};
+/** Strict allowlist: http/https (+ same-origin blob when allowBlob). */
+export declare function isSafeHttpUrl(url: string, opts?: SafeUrlOptions): boolean;
+/** Strip query string + hash for safe logging (signed-URL tokens live there). */
+export declare function redactUrl(url: string, base?: string): string;
+/**
+ * Link-href guard for navigation (`<a href>`). Broader than isSafeHttpUrl:
+ * allows http/https/mailto/tel/relative/hash, blocks only executable schemes.
+ */
+export declare function isSafeLinkHref(href: string, base?: string): boolean;