emdash 1.2.0 → 1.3.0

package/dist/transport-DxiXnbXk.d.mts

@@ -0,0 +1,42 @@
+//#region src/client/transport.d.ts
+/**
+ * Transport layer for the EmDash client.
+ *
+ * Implements a composable interceptor pipeline that modifies requests
+ * and responses. The client calls `transport.fetch(request)` — everything
+ * else (auth, CSRF, retry) is handled by interceptors.
+ */
+/**
+ * An interceptor can modify the request, call next(), inspect
+ * the response, and optionally retry.
+ */
+type Interceptor = (request: Request, next: (request: Request) => Promise<Response>) => Promise<Response>;
+interface TransportOptions {
+  interceptors?: Interceptor[];
+}
+/**
+ * Creates a fetch function that runs requests through an interceptor pipeline.
+ */
+declare function createTransport(options?: TransportOptions): {
+  fetch: (request: Request) => Promise<Response>;
+};
+/**
+ * Adds X-EmDash-Request: 1 and Origin headers to mutation requests
+ * (POST, PUT, DELETE). The custom header satisfies EmDash's CSRF check;
+ * the Origin header satisfies Astro's built-in origin verification which
+ * rejects server-side POST requests that lack a matching Origin.
+ */
+declare function csrfInterceptor(): Interceptor;
+/**
+ * Adds Authorization: Bearer header from a static token.
+ */
+declare function tokenInterceptor(token: string): Interceptor;
+/**
+ * Dev bypass interceptor. Calls the dev-bypass endpoint on first request
+ * to establish a session, then forwards the session cookie on subsequent
+ * requests.
+ */
+declare function devBypassInterceptor(baseUrl: string): Interceptor;
+//#endregion
+export { tokenInterceptor as a, devBypassInterceptor as i, createTransport as n, csrfInterceptor as r, Interceptor as t };
+//# sourceMappingURL=transport-DxiXnbXk.d.mts.map

package/dist/transport-DxiXnbXk.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-DxiXnbXk.d.mts","names":[],"sources":["../src/client/transport.ts"],"mappings":";;AAeA;;;;;;;;;;KAAY,WAAA,IACX,OAAA,EAAS,OAAA,EACT,IAAA,GAAO,OAAA,EAAS,OAAA,KAAY,OAAA,CAAQ,QAAA,MAChC,OAAA,CAAQ,QAAA;AAAA,UAEI,gBAAA;EAChB,YAAA,GAAe,WAAA;AAAA;;;;iBAUA,eAAA,CAAgB,OAAA,GAAS,gBAAA;EACxC,KAAA,GAAQ,OAAA,EAAS,OAAA,KAAY,OAAA,CAAQ,QAAA;AAAA;;;AAZtC;;;;iBAqCgB,eAAA,CAAA,GAAmB,WAAA;AA1BnC;;;AAAA,iBA8CgB,gBAAA,CAAiB,KAAA,WAAgB,WAAA;;;;;;iBAajC,oBAAA,CAAqB,OAAA,WAAkB,WAAA"}

package/dist/trusted-proxy-BU3Nx9g1.mjs

@@ -0,0 +1,51 @@
+//#region src/auth/trusted-proxy.ts
+/**
+* RFC 7230 token — valid characters for an HTTP header name. Invalid names
+* passed to `Headers.get()` throw a TypeError at runtime, which would
+* otherwise surface as a 500 from every auth route.
+*/
+const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9a-z]+$/;
+/**
+* Normalise a list of header names the way both the config path and any
+* caller passing a pre-resolved list should do: trim, lowercase, drop
+* empty, drop anything that isn't a valid RFC 7230 token. Invalid names
+* would crash `Headers.get()` at runtime.
+*/
+function normalizeTrustedHeaders(names) {
+	return names.map((h) => h.trim().toLowerCase()).filter((h) => h.length > 0 && HEADER_NAME_PATTERN.test(h));
+}
+function isValidHeaderName(name) {
+	return HEADER_NAME_PATTERN.test(name);
+}
+/** Cache for the env-derived value. `null` means "not yet parsed". */
+let _envCache = null;
+function getEnvTrustedHeaders() {
+	if (_envCache !== null) return _envCache;
+	let raw;
+	try {
+		const importMetaEnv = import.meta.env;
+		raw = (typeof process !== "undefined" ? process.env?.EMDASH_TRUSTED_PROXY_HEADERS : void 0) || importMetaEnv?.EMDASH_TRUSTED_PROXY_HEADERS;
+	} catch {
+		raw = void 0;
+	}
+	if (!raw) {
+		_envCache = [];
+		return _envCache;
+	}
+	_envCache = raw.split(",").map((s) => s.trim().toLowerCase()).filter((s) => s.length > 0 && isValidHeaderName(s));
+	return _envCache;
+}
+/**
+* Return the lowercased list of headers to trust for client-IP resolution.
+*
+* When `config?.trustedProxyHeaders` is explicitly set (even to `[]`), it
+* wins. Otherwise fall through to the env var, then to `[]`.
+*/
+function getTrustedProxyHeaders(config) {
+	if (config && config.trustedProxyHeaders !== void 0) return config.trustedProxyHeaders.map((h) => h.trim().toLowerCase()).filter((h) => h.length > 0 && isValidHeaderName(h));
+	return getEnvTrustedHeaders();
+}
+
+//#endregion
+export { normalizeTrustedHeaders as n, getTrustedProxyHeaders as t };
+//# sourceMappingURL=trusted-proxy-BU3Nx9g1.mjs.map

package/dist/trusted-proxy-BU3Nx9g1.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"trusted-proxy-BU3Nx9g1.mjs","names":[],"sources":["../src/auth/trusted-proxy.ts"],"sourcesContent":["/**\n * Resolve the list of client-IP headers the operator trusts.\n *\n * Resolution order:\n *   1. `config.trustedProxyHeaders` — explicit opt-in via astro.config.mjs.\n *      An empty array is respected (means \"trust nothing, ignore env\").\n *   2. `EMDASH_TRUSTED_PROXY_HEADERS` env var — comma-separated header names.\n *   3. `[]` — default, no trusted headers.\n *\n * Operators must only set this when they control the reverse proxy.\n * Untrusted clients can set any header they like; trusting headers from\n * an open network defeats rate limiting.\n *\n * Header names are returned lowercased because HTTP header lookups are\n * case-insensitive.\n */\n\nimport type { EmDashConfig } from \"../astro/integration/runtime.js\";\n\n/**\n * RFC 7230 token — valid characters for an HTTP header name. Invalid names\n * passed to `Headers.get()` throw a TypeError at runtime, which would\n * otherwise surface as a 500 from every auth route.\n */\nconst HEADER_NAME_PATTERN = /^[!#$%&'*+\\-.^_`|~0-9a-z]+$/;\n\n/**\n * Normalise a list of header names the way both the config path and any\n * caller passing a pre-resolved list should do: trim, lowercase, drop\n * empty, drop anything that isn't a valid RFC 7230 token. Invalid names\n * would crash `Headers.get()` at runtime.\n */\nexport function normalizeTrustedHeaders(names: readonly string[]): string[] {\n\treturn names\n\t\t.map((h) => h.trim().toLowerCase())\n\t\t.filter((h) => h.length > 0 && HEADER_NAME_PATTERN.test(h));\n}\n\nfunction isValidHeaderName(name: string): boolean {\n\treturn HEADER_NAME_PATTERN.test(name);\n}\n\n/** Cache for the env-derived value. `null` means \"not yet parsed\". */\nlet _envCache: string[] | null = null;\n\n/** Test-only: clear the env cache so a fresh value is read on next call. */\nexport function _resetTrustedProxyHeadersCache(): void {\n\t_envCache = null;\n}\n\nfunction getEnvTrustedHeaders(): string[] {\n\tif (_envCache !== null) return _envCache;\n\tlet raw: string | undefined;\n\ttry {\n\t\t// Prefer process.env so SSR/container deployments can override this\n\t\t// value at runtime (Vite/Astro inline import.meta.env at build time,\n\t\t// which locks the value into the bundle). Fall back to import.meta.env\n\t\t// for bundler-managed environments where process.env isn't populated.\n\t\t// eslint-disable-next-line typescript/no-unsafe-type-assertion -- import.meta.env shape varies by bundler\n\t\tconst importMetaEnv = (import.meta as unknown as { env?: Record<string, string | undefined> })\n\t\t\t.env;\n\t\traw =\n\t\t\t(typeof process !== \"undefined\" ? process.env?.EMDASH_TRUSTED_PROXY_HEADERS : undefined) ||\n\t\t\timportMetaEnv?.EMDASH_TRUSTED_PROXY_HEADERS;\n\t} catch {\n\t\traw = undefined;\n\t}\n\tif (!raw) {\n\t\t_envCache = [];\n\t\treturn _envCache;\n\t}\n\t_envCache = raw\n\t\t.split(\",\")\n\t\t.map((s) => s.trim().toLowerCase())\n\t\t.filter((s) => s.length > 0 && isValidHeaderName(s));\n\treturn _envCache;\n}\n\n/**\n * Return the lowercased list of headers to trust for client-IP resolution.\n *\n * When `config?.trustedProxyHeaders` is explicitly set (even to `[]`), it\n * wins. Otherwise fall through to the env var, then to `[]`.\n */\nexport function getTrustedProxyHeaders(config: EmDashConfig | null | undefined): string[] {\n\tif (config && config.trustedProxyHeaders !== undefined) {\n\t\treturn config.trustedProxyHeaders\n\t\t\t.map((h) => h.trim().toLowerCase())\n\t\t\t.filter((h) => h.length > 0 && isValidHeaderName(h));\n\t}\n\treturn getEnvTrustedHeaders();\n}\n"],"mappings":";;;;;;AAwBA,MAAM,sBAAsB;;;;;;;AAQ5B,SAAgB,wBAAwB,OAAoC;AAC3E,QAAO,MACL,KAAK,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,CAClC,QAAQ,MAAM,EAAE,SAAS,KAAK,oBAAoB,KAAK,EAAE,CAAC;;AAG7D,SAAS,kBAAkB,MAAuB;AACjD,QAAO,oBAAoB,KAAK,KAAK;;;AAItC,IAAI,YAA6B;AAOjC,SAAS,uBAAiC;AACzC,KAAI,cAAc,KAAM,QAAO;CAC/B,IAAI;AACJ,KAAI;EAMH,MAAM,gBAAiB,OAAO,KAC5B;AACF,SACE,OAAO,YAAY,cAAc,QAAQ,KAAK,+BAA+B,WAC9E,eAAe;SACT;AACP,QAAM;;AAEP,KAAI,CAAC,KAAK;AACT,cAAY,EAAE;AACd,SAAO;;AAER,aAAY,IACV,MAAM,IAAI,CACV,KAAK,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,CAClC,QAAQ,MAAM,EAAE,SAAS,KAAK,kBAAkB,EAAE,CAAC;AACrD,QAAO;;;;;;;;AASR,SAAgB,uBAAuB,QAAmD;AACzF,KAAI,UAAU,OAAO,wBAAwB,OAC5C,QAAO,OAAO,oBACZ,KAAK,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,CAClC,QAAQ,MAAM,EAAE,SAAS,KAAK,kBAAkB,EAAE,CAAC;AAEtD,QAAO,sBAAsB"}

package/dist/turnstile-CJwvsOqw.mjs

@@ -0,0 +1,58 @@
+//#region src/comments/turnstile.ts
+/**
+* Server-side Turnstile verification for public comment submissions.
+*
+* The comment form widget (`CommentForm.astro`) submits a `turnstileToken`;
+* this verifies it against Cloudflare's siteverify API. Enforcement is
+* opt-in: it only runs when the operator configures the Turnstile secret
+* key (`EMDASH_TURNSTILE_SECRET_KEY` or `TURNSTILE_SECRET_KEY`), so
+* existing non-Turnstile sites are unaffected.
+*
+* Mirrors `verifyTurnstile` in `@emdash-cms/plugin-forms` (not imported —
+* core doesn't depend on plugin packages).
+*/
+const SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+/**
+* Resolve the configured Turnstile secret key, or `""` when Turnstile
+* enforcement is not configured.
+*
+* Reads `process.env` only: Vite replaces `import.meta.env` at build time,
+* which would bake a build-machine secret into the bundle and hide a secret
+* set on the deployment platform.
+*/
+function getTurnstileSecretKey() {
+	const env = typeof process !== "undefined" && process.env ? process.env : {};
+	return env.EMDASH_TURNSTILE_SECRET_KEY || env.TURNSTILE_SECRET_KEY || "";
+}
+/**
+* Verify a Turnstile response token via siteverify.
+*
+* Fails closed: a missing token, a failed verification, and a siteverify
+* transport error all return `false` — when the operator has configured a
+* secret, an unverifiable submission must not be persisted.
+*/
+async function verifyTurnstileToken(token, secretKey, remoteIp) {
+	if (!token) return false;
+	const body = {
+		secret: secretKey,
+		response: token
+	};
+	if (remoteIp) body.remoteip = remoteIp;
+	try {
+		const data = await (await fetch(SITEVERIFY_URL, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(1e4)
+		})).json();
+		if (!data.success) console.warn("[comments] Turnstile verification failed:", data["error-codes"] ?? []);
+		return data.success === true;
+	} catch (error) {
+		console.error("[comments] Turnstile siteverify request failed:", error instanceof Error ? error.message : error);
+		return false;
+	}
+}
+
+//#endregion
+export { getTurnstileSecretKey, verifyTurnstileToken };
+//# sourceMappingURL=turnstile-CJwvsOqw.mjs.map

package/dist/turnstile-CJwvsOqw.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnstile-CJwvsOqw.mjs","names":[],"sources":["../src/comments/turnstile.ts"],"sourcesContent":["/**\n * Server-side Turnstile verification for public comment submissions.\n *\n * The comment form widget (`CommentForm.astro`) submits a `turnstileToken`;\n * this verifies it against Cloudflare's siteverify API. Enforcement is\n * opt-in: it only runs when the operator configures the Turnstile secret\n * key (`EMDASH_TURNSTILE_SECRET_KEY` or `TURNSTILE_SECRET_KEY`), so\n * existing non-Turnstile sites are unaffected.\n *\n * Mirrors `verifyTurnstile` in `@emdash-cms/plugin-forms` (not imported —\n * core doesn't depend on plugin packages).\n */\n\nconst SITEVERIFY_URL = \"https://challenges.cloudflare.com/turnstile/v0/siteverify\";\n\n/**\n * Resolve the configured Turnstile secret key, or `\"\"` when Turnstile\n * enforcement is not configured.\n *\n * Reads `process.env` only: Vite replaces `import.meta.env` at build time,\n * which would bake a build-machine secret into the bundle and hide a secret\n * set on the deployment platform.\n */\nexport function getTurnstileSecretKey(): string {\n\tconst env = typeof process !== \"undefined\" && process.env ? process.env : {};\n\treturn env.EMDASH_TURNSTILE_SECRET_KEY || env.TURNSTILE_SECRET_KEY || \"\";\n}\n\n/**\n * Verify a Turnstile response token via siteverify.\n *\n * Fails closed: a missing token, a failed verification, and a siteverify\n * transport error all return `false` — when the operator has configured a\n * secret, an unverifiable submission must not be persisted.\n */\nexport async function verifyTurnstileToken(\n\ttoken: string | undefined,\n\tsecretKey: string,\n\tremoteIp?: string | null,\n): Promise<boolean> {\n\tif (!token) return false;\n\n\tconst body: Record<string, string> = { secret: secretKey, response: token };\n\tif (remoteIp) {\n\t\tbody.remoteip = remoteIp;\n\t}\n\n\ttry {\n\t\tconst res = await fetch(SITEVERIFY_URL, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: { \"Content-Type\": \"application/json\" },\n\t\t\tbody: JSON.stringify(body),\n\t\t\t// Fail closed *quickly* if siteverify is slow — without a timeout\n\t\t\t// the comment POST would hang until the runtime kills it\n\t\t\tsignal: AbortSignal.timeout(10_000),\n\t\t});\n\t\tconst data: { success?: boolean; \"error-codes\"?: string[] } = await res.json();\n\t\tif (!data.success) {\n\t\t\tconsole.warn(\"[comments] Turnstile verification failed:\", data[\"error-codes\"] ?? []);\n\t\t}\n\t\treturn data.success === true;\n\t} catch (error) {\n\t\tconsole.error(\n\t\t\t\"[comments] Turnstile siteverify request failed:\",\n\t\t\terror instanceof Error ? error.message : error,\n\t\t);\n\t\treturn false;\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,MAAM,iBAAiB;;;;;;;;;AAUvB,SAAgB,wBAAgC;CAC/C,MAAM,MAAM,OAAO,YAAY,eAAe,QAAQ,MAAM,QAAQ,MAAM,EAAE;AAC5E,QAAO,IAAI,+BAA+B,IAAI,wBAAwB;;;;;;;;;AAUvE,eAAsB,qBACrB,OACA,WACA,UACmB;AACnB,KAAI,CAAC,MAAO,QAAO;CAEnB,MAAM,OAA+B;EAAE,QAAQ;EAAW,UAAU;EAAO;AAC3E,KAAI,SACH,MAAK,WAAW;AAGjB,KAAI;EASH,MAAM,OAAwD,OARlD,MAAM,MAAM,gBAAgB;GACvC,QAAQ;GACR,SAAS,EAAE,gBAAgB,oBAAoB;GAC/C,MAAM,KAAK,UAAU,KAAK;GAG1B,QAAQ,YAAY,QAAQ,IAAO;GACnC,CAAC,EACsE,MAAM;AAC9E,MAAI,CAAC,KAAK,QACT,SAAQ,KAAK,6CAA6C,KAAK,kBAAkB,EAAE,CAAC;AAErF,SAAO,KAAK,YAAY;UAChB,OAAO;AACf,UAAQ,MACP,mDACA,iBAAiB,QAAQ,MAAM,UAAU,MACzC;AACD,SAAO"}

package/dist/types-BA3ey2QH.d.mts

@@ -0,0 +1,87 @@
+//#region src/settings/types.d.ts
+/**
+ * Site Settings Types
+ *
+ * Global configuration for the site (title, logo, social links, etc.)
+ */
+/**
+ * Media reference for logo/favicon/seo.defaultOgImage.
+ *
+ * Stored shape is just `{ mediaId, alt? }`. The remaining fields are
+ * populated by `resolveMediaReference` on read so templates can emit
+ * correct head tags without a second round-trip to the media table.
+ *
+ * The Zod schemas at the REST/MCP boundary are split:
+ *  - `mediaReferenceInput` (used by `settingsUpdateBody`) defines only
+ *    `mediaId` and `alt`. Default strip-mode parsing discards any
+ *    resolved fields a client posts back, so they never reach storage.
+ *  - `mediaReferenceResponse` (used by `siteSettingsSchema`) includes
+ *    the resolved fields so generated OpenAPI clients see them.
+ *
+ * If you ever switch `mediaReferenceInput` to `passthrough`, you must
+ * also strip the resolved fields explicitly in `setSiteSettings`, or
+ * stored options will accumulate stale `url` / `contentType` / `width`
+ * / `height` snapshots.
+ */
+interface MediaReference {
+  mediaId: string;
+  alt?: string;
+  /** Resolved URL. Populated by `resolveMediaReference`; absent on raw stored values. */
+  url?: string;
+  /** Stored MIME type (e.g. `image/svg+xml`). Populated alongside `url`. */
+  contentType?: string;
+  /** Pixel width if known. Populated alongside `url`. */
+  width?: number;
+  /** Pixel height if known. Populated alongside `url`. */
+  height?: number;
+}
+/** Site-level SEO settings */
+interface SeoSettings {
+  /** Separator between page title and site title (e.g., " | ", " — ") */
+  titleSeparator?: string;
+  /** Default OG image when content has no seo_image */
+  defaultOgImage?: MediaReference;
+  /** Custom robots.txt content. If unset, a default is generated. */
+  robotsTxt?: string;
+  /** Add rules to robots.txt that ask AI crawlers not to use the site for training. */
+  disallowAiTraining?: boolean;
+  /** Google Search Console verification meta tag content */
+  googleVerification?: string;
+  /** Bing Webmaster Tools verification meta tag content */
+  bingVerification?: string;
+}
+/** Site settings schema */
+interface SiteSettings {
+  title: string;
+  tagline?: string;
+  logo?: MediaReference;
+  favicon?: MediaReference;
+  url?: string;
+  postsPerPage: number;
+  dateFormat: string;
+  timezone: string;
+  social?: {
+    twitter?: string;
+    github?: string;
+    facebook?: string;
+    instagram?: string;
+    linkedin?: string;
+    youtube?: string;
+  };
+  seo?: SeoSettings;
+}
+/** Partial SEO update. `null` removes the configured default image. */
+interface SeoSettingsUpdate extends Omit<SeoSettings, "defaultOgImage"> {
+  defaultOgImage?: MediaReference | null;
+}
+/** Site-settings write shape. `null` removes media references; omitted fields are unchanged. */
+interface SiteSettingsUpdate extends Omit<Partial<SiteSettings>, "logo" | "favicon" | "seo"> {
+  logo?: MediaReference | null;
+  favicon?: MediaReference | null;
+  seo?: SeoSettingsUpdate;
+}
+/** Keys that are valid site settings */
+type SiteSettingKey = keyof SiteSettings;
+//#endregion
+export { SiteSettings as a, SiteSettingKey as i, SeoSettings as n, SiteSettingsUpdate as o, SeoSettingsUpdate as r, MediaReference as t };
+//# sourceMappingURL=types-BA3ey2QH.d.mts.map

package/dist/types-BA3ey2QH.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-BA3ey2QH.d.mts","names":[],"sources":["../src/settings/types.ts"],"mappings":";;AAyBA;;;;;;;;;;;;AAcA;;;;;;;;;;;UAdiB,cAAA;EAChB,OAAA;EACA,GAAA;EA4B4B;EA1B5B,GAAA;EA8BO;EA5BP,WAAA;EAkDM;EAhDN,KAAA;EAgDiB;EA9CjB,MAAA;AAAA;;UAIgB,WAAA;EAqBhB;EAnBA,cAAA;EAsBA;EApBA,cAAA,GAAiB,cAAA;EAwBjB;EAtBA,SAAA;EA0BA;EAxBA,kBAAA;EA0BC;EAxBD,kBAAA;EA0BC;EAxBD,gBAAA;AAAA;;UAIgB,YAAA;EAEhB,KAAA;EACA,OAAA;EACA,IAAA,GAAO,cAAA;EACP,OAAA,GAAU,cAAA;EAGV,GAAA;EAGA,YAAA;EACA,UAAA;EACA,QAAA;EAGA,MAAA;IACC,OAAA;IACA,MAAA;IACA,QAAA;IACA,SAAA;IACA,QAAA;IACA,OAAA;EAAA;EAID,GAAA,GAAM,WAAA;AAAA;;UAIU,iBAAA,SAA0B,IAAA,CAAK,WAAA;EAC/C,cAAA,GAAiB,cAAA;AAAA;;UAID,kBAAA,SAA2B,IAAA,CAC3C,OAAA,CAAQ,YAAA;EAGR,IAAA,GAAO,cAAA;EACP,OAAA,GAAU,cAAA;EACV,GAAA,GAAM,iBAAA;AAAA;;KAIK,cAAA,SAAuB,YAAA"}

package/dist/types-Bwpzb5o6.d.mts

@@ -0,0 +1,227 @@
+//#region src/storage/types.d.ts
+/**
+ * Storage Layer Types
+ *
+ * Defines the interface for S3-compatible storage backends.
+ * Works with R2, AWS S3, Minio, and other S3-compatible services.
+ */
+/**
+ * Storage configuration for S3-compatible backends
+ */
+interface S3StorageConfig {
+  /** S3 endpoint URL (e.g., "https://xxx.r2.cloudflarestorage.com") */
+  endpoint: string;
+  /** Bucket name */
+  bucket: string;
+  /**
+   * AWS access key ID.
+   * May be resolved from the `S3_ACCESS_KEY_ID` env var at runtime on Node.
+   * Must be provided together with `secretAccessKey`, or both omitted.
+   */
+  accessKeyId?: string;
+  /**
+   * AWS secret access key.
+   * May be resolved from the `S3_SECRET_ACCESS_KEY` env var at runtime on Node.
+   * Must be provided together with `accessKeyId`, or both omitted.
+   */
+  secretAccessKey?: string;
+  /** Optional region (defaults to "auto") */
+  region?: string;
+  /** Optional public URL prefix for generated URLs (e.g., CDN URL) */
+  publicUrl?: string;
+}
+/**
+ * Local filesystem storage for development
+ */
+interface LocalStorageConfig {
+  /** Directory path for storing files */
+  directory: string;
+  /** Base URL for serving files */
+  baseUrl: string;
+}
+/**
+ * Storage adapter descriptor (serializable config)
+ */
+interface StorageDescriptor {
+  /** Module path exporting createStorage function */
+  entrypoint: string;
+  /** Serializable config passed to createStorage at runtime */
+  config: Record<string, unknown>;
+}
+/**
+ * Factory function signature for storage adapters
+ *
+ * Each adapter accesses its own bindings directly:
+ * - R2: imports from cloudflare:workers
+ * - S3: uses credentials from config
+ * - Local: uses filesystem path from config
+ */
+type CreateStorageFn = (config: Record<string, unknown>) => Storage;
+/**
+ * Upload result
+ */
+interface UploadResult {
+  /** Storage key (path within bucket) */
+  key: string;
+  /** Public URL to access the file */
+  url: string;
+  /** File size in bytes */
+  size: number;
+}
+/**
+ * A single byte range of a file, as requested by an HTTP `Range` header
+ */
+type ByteRange = /** `length` bytes from `offset`, or every byte from `offset` when `length` is omitted */{
+  offset: number;
+  length?: number;
+} /** The last `suffix` bytes */ | {
+  suffix: number;
+};
+/**
+ * Options for downloading a file
+ */
+interface DownloadOptions {
+  /**
+   * Download only this part of the file. Adapters that can't serve it,
+   * including when it starts past the end of the file, return the whole file.
+   */
+  range?: ByteRange;
+}
+/**
+ * Download result
+ */
+interface DownloadResult {
+  /** File content as readable stream */
+  body: ReadableStream<Uint8Array>;
+  /** MIME type */
+  contentType: string;
+  /** Size of the whole file in bytes, even when `body` holds only part of it */
+  size: number;
+  /**
+   * The part of the file `body` holds, when the adapter served
+   * `DownloadOptions.range`. Absent when `body` is the whole file.
+   */
+  range?: {
+    offset: number;
+    length: number;
+  };
+  /** Last modification time of the stored object, when the backend can provide it. */
+  lastModified?: Date;
+}
+/**
+ * Signed URL for direct upload
+ */
+interface SignedUploadUrl {
+  /** Signed URL for PUT request */
+  url: string;
+  /** HTTP method (always PUT) */
+  method: "PUT";
+  /** Headers to include in the upload request */
+  headers: Record<string, string>;
+  /** URL expiration time (ISO string) */
+  expiresAt: string;
+}
+/**
+ * Options for generating signed upload URL
+ */
+interface SignedUploadOptions {
+  /** Storage key (path within bucket) */
+  key: string;
+  /** MIME type of the file */
+  contentType: string;
+  /** File size in bytes (for content-length validation) */
+  size?: number;
+  /** URL expiration in seconds (default: 3600) */
+  expiresIn?: number;
+}
+/**
+ * File listing result
+ */
+interface ListResult {
+  /** List of files */
+  files: FileInfo[];
+  /** Cursor for next page (if more results) */
+  nextCursor?: string;
+}
+/**
+ * File info from listing
+ */
+interface FileInfo {
+  /** Storage key */
+  key: string;
+  /** File size in bytes */
+  size: number;
+  /** Last modified date */
+  lastModified: Date;
+  /** ETag (content hash) */
+  etag?: string;
+}
+/**
+ * Options for listing files
+ */
+interface ListOptions {
+  /** Filter by key prefix */
+  prefix?: string;
+  /** Maximum results per page */
+  limit?: number;
+  /** Cursor from previous list call */
+  cursor?: string;
+}
+/**
+ * Storage interface
+ *
+ * All storage backends must implement this interface.
+ */
+interface Storage {
+  /**
+   * Upload a file to storage
+   */
+  upload(options: {
+    key: string;
+    body: Buffer | Uint8Array | ReadableStream<Uint8Array>;
+    contentType: string; /** Optional HTTP cache policy stored with publicly served objects. */
+    cacheControl?: string;
+  }): Promise<UploadResult>;
+  /**
+   * Download a file from storage, or part of it with `options.range`
+   */
+  download(key: string, options?: DownloadOptions): Promise<DownloadResult>;
+  /**
+   * Delete a file from storage
+   * Idempotent - does not throw if file doesn't exist
+   */
+  delete(key: string): Promise<void>;
+  /**
+   * Check if a file exists
+   */
+  exists(key: string): Promise<boolean>;
+  /**
+   * List files in storage
+   */
+  list(options?: ListOptions): Promise<ListResult>;
+  /**
+   * Generate a signed URL for direct upload
+   * Client uploads directly to storage, bypassing the server
+   */
+  getSignedUploadUrl(options: SignedUploadOptions): Promise<SignedUploadUrl>;
+  /**
+   * Get public URL for a file
+   */
+  getPublicUrl(key: string): string;
+  /**
+   * Get the origin the browser connects to for direct client uploads.
+   * Used by the admin CSP when the storage descriptor has no static endpoint.
+   */
+  getClientUploadOrigin?(): string;
+}
+/**
+ * Storage error with additional context
+ */
+declare class EmDashStorageError extends Error {
+  code: string;
+  cause?: unknown | undefined;
+  constructor(message: string, code: string, cause?: unknown | undefined);
+}
+//#endregion
+export { EmDashStorageError as a, ListResult as c, SignedUploadOptions as d, SignedUploadUrl as f, UploadResult as h, DownloadResult as i, LocalStorageConfig as l, StorageDescriptor as m, CreateStorageFn as n, FileInfo as o, Storage as p, DownloadOptions as r, ListOptions as s, ByteRange as t, S3StorageConfig as u };
+//# sourceMappingURL=types-Bwpzb5o6.d.mts.map

package/dist/types-Bwpzb5o6.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-Bwpzb5o6.d.mts","names":[],"sources":["../src/storage/types.ts"],"mappings":";;AAUA;;;;;;;;UAAiB,eAAA;EAoBhB;EAlBA,QAAA;EAkBS;EAhBT,MAAA;EAsBkC;;;;AAUnC;EA1BC,WAAA;;;;;;EAMA,eAAA;EAwBc;EAtBd,MAAA;EAiC0B;EA/B1B,SAAA;AAAA;;;;UAMgB,kBAAA;EAyByD;EAvBzE,SAAA;EA4B4B;EA1B5B,OAAA;AAAA;;;;UAMgB,iBAAA;EA0BZ;EAxBJ,UAAA;EA8BoB;EA5BpB,MAAA,EAAQ,MAAA;AAAA;;;;;;AAqCT;;;KA1BY,eAAA,IAAmB,MAAA,EAAQ,MAAA,sBAA4B,OAAA;;AAqCnE;;UAhCiB,YAAA;EAkCK;EAhCrB,GAAA;EA2Ce;EAzCf,GAAA;EAyCmB;EAvCnB,IAAA;AAAA;;;;KAMW,SAAA;EAEP,MAAA;EAAgB,MAAA;AAAA;EAEhB,MAAA;AAAA;;;;UAKY,eAAA;EAoCP;;;;EA/BT,KAAA,GAAQ,SAAA;AAAA;;;;UAMQ,cAAA;EAuChB;EArCA,IAAA,EAAM,cAAA,CAAe,UAAA;EAuCZ;EArCT,WAAA;EA2CgB;EAzChB,IAAA;;;;;EAKA,KAAA;IAAU,MAAA;IAAgB,MAAA;EAAA;EA8CF;EA5CxB,YAAA,GAAe,IAAA;AAAA;;;;UAMC,eAAA;EA8ChB;EA5CA,GAAA;EA4CI;EA1CJ,MAAA;EAgD2B;EA9C3B,OAAA,EAAS,MAAA;EA8CkB;EA5C3B,SAAA;AAAA;;;;UAMgB,mBAAA;EAoDO;EAlDvB,GAAA;EAwDO;EAtDP,WAAA;EAsD4C;EApD5C,IAAA;EAwDY;EAtDZ,SAAA;AAAA;;;;UAMgB,UAAA;EAqED;EAnEf,KAAA,EAAO,QAAA;EAmEsB;EAjE7B,UAAA;AAAA;;;;UAMgB,QAAA;EAiCf;EA/BD,GAAA;EAgCO;EA9BP,IAAA;EA8B6B;EA5B7B,YAAA,EAAc,IAAA;EA6Bb;EA3BD,IAAA;AAAA;;;;UAMgB,WAAA;EA6BgB;EA3BhC,MAAA;EA2BkD;EAzBlD,KAAA;EA+BA;EA7BA,MAAA;AAAA;;;;;;UAQgB,OAAA;EA+Ba;;;EA3B7B,MAAA,CAAO,OAAA;IACN,GAAA;IACA,IAAA,EAAM,MAAA,GAAS,UAAA,GAAa,cAAA,CAAe,UAAA;IAC3C,WAAA,UAmCD;IAjCC,YAAA;EAAA,IACG,OAAA,CAAQ,YAAA;EAsCS;;AAMtB;EAvCC,QAAA,CAAS,GAAA,UAAa,OAAA,GAAU,eAAA,GAAkB,OAAA,CAAQ,cAAA;;;;;EAM1D,MAAA,CAAO,GAAA,WAAc,OAAA;;;;EAKrB,MAAA,CAAO,GAAA,WAAc,OAAA;EAgCW;;;EA3BhC,IAAA,CAAK,OAAA,GAAU,WAAA,GAAc,OAAA,CAAQ,UAAA;;;;;EAMrC,kBAAA,CAAmB,OAAA,EAAS,mBAAA,GAAsB,OAAA,CAAQ,eAAA;;;;EAK1D,YAAA,CAAa,GAAA;;;;;EAMb,qBAAA;AAAA;;;;cAMY,kBAAA,SAA2B,KAAA;EAG/B,IAAA;EACS,KAAA;cAFhB,OAAA,UACO,IAAA,UACS,KAAA;AAAA"}