emdash 0.0.0-a → 0.0.1

package/src/utils/hash.ts

@@ -0,0 +1,36 @@
+/**
+ * SHA-256 hash of a string, truncated to 16 hex chars (64 bits).
+ * For cache invalidation / ETags — not for security.
+ */
+export async function hashString(content: string): Promise<string> {
+	const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(content));
+	return Array.from(new Uint8Array(buf).slice(0, 8), (b) => b.toString(16).padStart(2, "0")).join(
+		"",
+	);
+}
+
+/**
+ * Compute content hash using Web Crypto API
+ *
+ * Uses SHA-1 which is the fastest option in SubtleCrypto.
+ * SHA-1 is cryptographically weak but fine for content deduplication
+ * where we only need to detect identical files, not resist attacks.
+ *
+ * Returns hex string prefixed with "sha1:" for future-proofing
+ */
+export async function computeContentHash(content: Uint8Array | ArrayBuffer): Promise<string> {
+	// SubtleCrypto.digest() requires BufferSource (ArrayBuffer | ArrayBufferView<ArrayBuffer>).
+	// Uint8Array.buffer is ArrayBufferLike which may include SharedArrayBuffer in the type system,
+	// so we ensure we have a plain ArrayBuffer.
+	let buf: ArrayBuffer;
+	if (content instanceof ArrayBuffer) {
+		buf = content;
+	} else {
+		buf = new ArrayBuffer(content.byteLength);
+		new Uint8Array(buf).set(content);
+	}
+	const hashBuffer = await crypto.subtle.digest("SHA-1", buf);
+	const hashArray = new Uint8Array(hashBuffer);
+	const hashHex = Array.from(hashArray, (b) => b.toString(16).padStart(2, "0")).join("");
+	return `sha1:${hashHex}`;
+}

package/src/utils/sanitize.ts

@@ -0,0 +1,20 @@
+import sanitizeHtml from "sanitize-html";
+
+/**
+ * Sanitize HTML content to prevent XSS attacks.
+ *
+ * Allows standard formatting tags, images, iframes (from specific providers),
+ * and basic attributes.
+ */
+export function sanitizeContent(html: string): string {
+	return sanitizeHtml(html, {
+		allowedTags: [...sanitizeHtml.defaults.allowedTags, "img", "span", "iframe"],
+		allowedAttributes: {
+			...sanitizeHtml.defaults.allowedAttributes,
+			"*": ["class", "id", "data-*"],
+			iframe: ["src", "width", "height", "frameborder", "allow", "allowfullscreen"],
+			img: ["src", "srcset", "alt", "title", "width", "height", "loading"],
+		},
+		allowedIframeHostnames: ["www.youtube.com", "player.vimeo.com"],
+	});
+}

package/src/utils/slugify.ts

@@ -0,0 +1,29 @@
+// Regex patterns for slug normalization
+const DIACRITICS_PATTERN = /[\u0300-\u036f]/g;
+const WHITESPACE_UNDERSCORE_PATTERN = /[\s_]+/g;
+const NON_ALPHANUMERIC_HYPHEN_PATTERN = /[^a-z0-9-]/g;
+const MULTIPLE_HYPHENS_PATTERN = /-+/g;
+const LEADING_TRAILING_HYPHEN_PATTERN = /^-|-$/g;
+const TRAILING_HYPHEN_PATTERN = /-$/;
+
+/**
+ * Convert a string to a URL-friendly slug.
+ *
+ * Handles unicode by normalizing to NFD and stripping diacritics,
+ * so "café" becomes "cafe", "naïve" becomes "naive", etc.
+ */
+export function slugify(text: string, maxLength: number = 80): string {
+	return (
+		text
+			.toLowerCase()
+			.normalize("NFD")
+			.replace(DIACRITICS_PATTERN, "")
+			.replace(WHITESPACE_UNDERSCORE_PATTERN, "-")
+			.replace(NON_ALPHANUMERIC_HYPHEN_PATTERN, "")
+			.replace(MULTIPLE_HYPHENS_PATTERN, "-")
+			.replace(LEADING_TRAILING_HYPHEN_PATTERN, "")
+			.slice(0, maxLength)
+			// Clean trailing hyphen from truncation
+			.replace(TRAILING_HYPHEN_PATTERN, "")
+	);
+}

package/src/utils/url.ts

@@ -0,0 +1,48 @@
+/**
+ * URL scheme validation utilities
+ *
+ * Prevents XSS via dangerous URL schemes (javascript:, data:, vbscript:, etc.)
+ * by allowlisting known-safe schemes before rendering into href attributes.
+ */
+
+/**
+ * Matches URLs that are safe to render in href attributes.
+ *
+ * Allowed:
+ * - http:// and https://
+ * - mailto: and tel:
+ * - Relative paths (starting with /)
+ * - Fragment links (starting with #)
+ * - Protocol-relative URLs are NOT allowed (starting with //) as they can
+ *   redirect to attacker-controlled hosts.
+ */
+const SAFE_URL_SCHEME_RE = /^(https?:|mailto:|tel:|\/(?!\/)|#)/i;
+
+/**
+ * Returns the URL unchanged if it uses a safe scheme, otherwise returns "#".
+ *
+ * Use this at the render layer as the primary defense against XSS via
+ * dangerous URL schemes like `javascript:`, `data:`, or `vbscript:`.
+ *
+ * @example
+ * ```ts
+ * sanitizeHref("https://example.com")        // "https://example.com"
+ * sanitizeHref("/about")                      // "/about"
+ * sanitizeHref("#section")                    // "#section"
+ * sanitizeHref("mailto:a@b.com")              // "mailto:a@b.com"
+ * sanitizeHref("javascript:alert(1)")         // "#"
+ * sanitizeHref("data:text/html,<script>")     // "#"
+ * sanitizeHref("")                            // "#"
+ * ```
+ */
+export function sanitizeHref(url: string | undefined | null): string {
+	if (!url) return "#";
+	return SAFE_URL_SCHEME_RE.test(url) ? url : "#";
+}
+
+/**
+ * Returns true if the URL uses a safe scheme for rendering in href attributes.
+ */
+export function isSafeHref(url: string): boolean {
+	return SAFE_URL_SCHEME_RE.test(url);
+}

package/src/virtual-modules.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Type declarations for EmDash virtual modules
+ *
+ * These modules are generated at build time by the Astro integration.
+ * They provide static imports for configured adapters (database, storage, auth).
+ */
+
+declare module "virtual:emdash/config" {
+	import type { I18nConfig } from "./i18n/config.js";
+	import type { DatabaseDescriptor, StorageDescriptor, AuthDescriptor } from "./index.js";
+
+	interface VirtualConfig {
+		database?: DatabaseDescriptor;
+		storage?: StorageDescriptor;
+		auth?: AuthDescriptor;
+		i18n?: I18nConfig | null;
+	}
+
+	const config: VirtualConfig;
+	export default config;
+}
+
+declare module "virtual:emdash/dialect" {
+	import type { Dialect } from "kysely";
+
+	import type { DatabaseDialectType } from "./db/adapters.js";
+
+	// Can be undefined if no database configured, or the actual function
+	export const createDialect: ((config: unknown) => Dialect) | undefined;
+	export const dialectType: DatabaseDialectType | undefined;
+
+	// D1 read replica session helpers (no-ops for non-D1 adapters).
+	// Types use `unknown` because the core package doesn't depend on
+	// @cloudflare/workers-types — the actual D1Database types are resolved
+	// at bundle time in the cloudflare adapter.
+	export const isSessionEnabled: (config: unknown) => boolean;
+	export const getD1Binding: (config: unknown) => unknown;
+	export const getDefaultConstraint: (config: unknown) => string;
+	export const getBookmarkCookieName: (config: unknown) => string;
+	export const createSessionDialect: ((database: unknown) => Dialect) | undefined;
+}
+
+declare module "virtual:emdash/storage" {
+	import type { Storage } from "./storage/types.js";
+
+	// Can be undefined if no storage configured, or the actual function
+	export const createStorage: ((config: Record<string, unknown>) => Storage) | undefined;
+}
+
+declare module "virtual:emdash/auth" {
+	import type { AuthResult } from "./auth/types.js";
+
+	// Can be undefined if no external auth configured, or the actual function
+	export const authenticate:
+		| ((request: Request, config: unknown) => Promise<AuthResult>)
+		| undefined;
+}
+
+declare module "virtual:emdash/storage" {
+	import type { Storage } from "./storage/types.js";
+
+	export const createStorage: ((config: Record<string, unknown>) => Storage) | null;
+}
+
+declare module "virtual:emdash/auth" {
+	import type { AuthResult } from "./auth/types.js";
+
+	export const authenticate: ((request: Request, config: unknown) => Promise<AuthResult>) | null;
+}
+
+declare module "virtual:emdash/plugins" {
+	import type { ResolvedPlugin } from "./plugins/types.js";
+
+	export const plugins: ResolvedPlugin[];
+}
+
+declare module "virtual:emdash/sandbox-runner" {
+	import type { SandboxRunner, SandboxRunnerFactory, SandboxOptions } from "./plugins/types.js";
+
+	export const createSandboxRunner: SandboxRunnerFactory | null;
+	export const CloudflareSandboxRunner: (new (options: SandboxOptions) => SandboxRunner) | null;
+}
+
+declare module "virtual:emdash/sandboxed-plugins" {
+	import type { PluginDescriptor } from "./astro/integration/runtime.js";
+
+	export const sandboxedPlugins: PluginDescriptor[];
+}
+
+declare module "virtual:emdash/block-components" {
+	export const pluginBlockComponents: Record<string, unknown>;
+}
+
+declare module "virtual:emdash/admin-registry" {
+	/**
+	 * Plugin admin module registry.
+	 * Each entry is the namespace import of the plugin's admin entry module.
+	 * Convention for exports:
+	 *   - pages: Record<pageId, ComponentType>
+	 *   - widgets: Record<widgetId, ComponentType>
+	 *   - fields: Record<widgetName, ComponentType> (field widget renderers)
+	 */
+	export const pluginAdmins: Record<
+		string,
+		{
+			pages?: Record<string, unknown>;
+			widgets?: Record<string, unknown>;
+			fields?: Record<string, unknown>;
+		}
+	>;
+}

package/src/visual-editing/editable.ts

@@ -0,0 +1,108 @@
+/**
+ * Visual editing annotation system
+ *
+ * Creates Proxy objects that emit data-emdash-ref attributes when spread onto elements.
+ */
+
+export interface CMSAnnotation {
+	collection: string;
+	id: string;
+	field?: string;
+	/** Entry status — only present on entry-level annotations (not field-level) */
+	status?: string;
+	/** Whether the entry has unpublished draft changes */
+	hasDraft?: boolean;
+}
+
+/** The shape returned when spreading an edit annotation onto an element */
+export interface FieldAnnotation {
+	"data-emdash-ref": string;
+}
+
+export interface EditableOptions {
+	/** Entry status: "draft", "published", "scheduled" */
+	status?: string;
+	/** true when draftRevisionId exists and differs from liveRevisionId */
+	hasDraft?: boolean;
+}
+
+/**
+ * Create an editable proxy for an entry.
+ *
+ * Usage:
+ * - `{...entry.edit}` - entry-level annotation (includes status/hasDraft)
+ * - `{...entry.edit.title}` - field-level annotation
+ * - `{...entry.edit['nested.field']}` - nested field (bracket notation)
+ */
+export function createEditable(
+	collection: string,
+	id: string,
+	options?: EditableOptions,
+): EditProxy {
+	const base: CMSAnnotation = {
+		collection,
+		id,
+		...(options?.status && { status: options.status }),
+		...(options?.hasDraft && { hasDraft: true }),
+	};
+
+	return new Proxy({} as EditProxy, {
+		get(_, prop) {
+			if (prop === "toJSON") return () => ({ "data-emdash-ref": JSON.stringify(base) });
+			if (typeof prop === "symbol") return undefined;
+
+			// data-emdash-ref access returns the entry-level string
+			if (prop === "data-emdash-ref") return JSON.stringify(base);
+
+			// Field-level: return a FieldAnnotation for the specific field
+			return {
+				"data-emdash-ref": JSON.stringify({ ...base, field: String(prop) }),
+			} satisfies FieldAnnotation;
+		},
+		ownKeys() {
+			return ["data-emdash-ref"];
+		},
+		getOwnPropertyDescriptor(_, prop) {
+			if (prop === "data-emdash-ref") {
+				return {
+					configurable: true,
+					enumerable: true,
+					value: JSON.stringify(base),
+				};
+			}
+			return undefined;
+		},
+	});
+}
+
+/**
+ * Create a noop proxy for production mode.
+ * Spreading this produces no attributes.
+ */
+export function createNoop(): EditProxy {
+	return new Proxy({} as EditProxy, {
+		get(_, prop) {
+			if (typeof prop === "symbol") return undefined;
+			// All property access returns undefined in noop mode
+			return undefined;
+		},
+		ownKeys() {
+			return [];
+		},
+		getOwnPropertyDescriptor() {
+			return undefined;
+		},
+	});
+}
+
+/**
+ * Visual editing proxy type.
+ *
+ * Spread directly onto elements for entry-level annotations: `{...entry.edit}`
+ * Access a field for field-level annotations: `{...entry.edit.title}`
+ *
+ * In production, spreading produces no attributes (noop).
+ */
+export type EditProxy = {
+	readonly [field: string]: Partial<FieldAnnotation>;
+};