@tinacms/astro 0.0.1 → 0.2.0

package/src/__tests__/sanitize.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+import { sanitizeHref, sanitizeImageSrc } from '../sanitize';
+
+describe('sanitizeHref', () => {
+  it('blocks javascript: scheme', () => {
+    expect(sanitizeHref('javascript:alert(1)')).toBe('#');
+    expect(sanitizeHref('JavaScript:alert(1)')).toBe('#');
+    expect(sanitizeHref('  javascript:alert(1)  ')).toBe('#');
+  });
+
+  it('blocks data: and vbscript: schemes', () => {
+    expect(sanitizeHref('data:text/html,<script>alert(1)</script>')).toBe('#');
+    expect(sanitizeHref('vbscript:msgbox(1)')).toBe('#');
+  });
+
+  it('blocks protocol-relative URLs', () => {
+    expect(sanitizeHref('//evil.com/path')).toBe('#');
+  });
+
+  it('allows http(s) URLs', () => {
+    expect(sanitizeHref('https://tina.io')).toBe('https://tina.io');
+    expect(sanitizeHref('http://tina.io/x')).toBe('http://tina.io/x');
+  });
+
+  it('allows mailto:', () => {
+    expect(sanitizeHref('mailto:hi@tina.io')).toBe('mailto:hi@tina.io');
+  });
+
+  it('allows relative, root-relative, and fragment paths', () => {
+    expect(sanitizeHref('/about')).toBe('/about');
+    expect(sanitizeHref('./relative')).toBe('./relative');
+    expect(sanitizeHref('../up')).toBe('../up');
+    expect(sanitizeHref('#section')).toBe('#section');
+  });
+
+  it('returns fallback for non-strings, empty, or invalid', () => {
+    expect(sanitizeHref(null)).toBe('#');
+    expect(sanitizeHref(undefined)).toBe('#');
+    expect(sanitizeHref('')).toBe('#');
+    expect(sanitizeHref('   ')).toBe('#');
+    expect(sanitizeHref(42)).toBe('#');
+    expect(sanitizeHref('not a url')).toBe('#');
+  });
+
+  it('honours a custom fallback', () => {
+    expect(sanitizeHref('javascript:alert(1)', '/safe')).toBe('/safe');
+  });
+});
+
+describe('sanitizeImageSrc', () => {
+  it('allows http(s) URLs', () => {
+    expect(sanitizeImageSrc('https://cdn.tina.io/x.png')).toBe(
+      'https://cdn.tina.io/x.png'
+    );
+  });
+
+  it('allows relative paths', () => {
+    expect(sanitizeImageSrc('/uploads/x.png')).toBe('/uploads/x.png');
+    expect(sanitizeImageSrc('./local.png')).toBe('./local.png');
+    expect(sanitizeImageSrc('../up.png')).toBe('../up.png');
+  });
+
+  it('blocks protocol-relative and dangerous schemes', () => {
+    expect(sanitizeImageSrc('//evil.com/x.png')).toBe('');
+    expect(sanitizeImageSrc('javascript:alert(1)')).toBe('');
+    expect(sanitizeImageSrc('data:image/png;base64,xxx')).toBe('');
+  });
+
+  it('returns empty for non-strings, empty, or invalid', () => {
+    expect(sanitizeImageSrc(null)).toBe('');
+    expect(sanitizeImageSrc(undefined)).toBe('');
+    expect(sanitizeImageSrc('')).toBe('');
+    expect(sanitizeImageSrc(42)).toBe('');
+  });
+});

package/src/bridge-route.ts

@@ -0,0 +1,33 @@
+/**
+ * Astro endpoint injected by the `tina()` integration. Serves the bridge
+ * as a single self-contained ESM bundle at `/_tina/bridge.js`. Loaded by
+ * the inline `<script type="module">` the middleware splices into edit-
+ * mode pages — production visitors never reach this URL.
+ *
+ * `@tinacms/bridge`'s build already emits a fully bundled `dist/index.js`
+ * (no relative imports remain), so we stream it back as-is and let the
+ * browser cache it immutably.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import type { APIRoute } from 'astro';
+
+const require = createRequire(import.meta.url);
+let cached: string | undefined;
+
+function loadBridge(): string {
+  if (cached !== undefined) return cached;
+  const bridgePath = require.resolve('@tinacms/bridge');
+  cached = readFileSync(bridgePath, 'utf-8');
+  return cached;
+}
+
+export const prerender = false;
+
+export const GET: APIRoute = () =>
+  new Response(loadBridge(), {
+    headers: {
+      'Content-Type': 'application/javascript; charset=utf-8',
+      'Cache-Control': 'public, max-age=31536000, immutable',
+    },
+  });

package/src/bridge.ts

@@ -0,0 +1,7 @@
+/**
+ * Re-exports of `@tinacms/bridge` so Astro projects can pull the bridge from
+ * `@tinacms/astro/bridge` instead of installing it separately. The bridge
+ * package stays publishable on its own for non-Astro frontends (Hugo, plain
+ * HTML, Eleventy).
+ */
+export * from '@tinacms/bridge';

package/src/data.ts

@@ -0,0 +1,97 @@
+/**
+ * `requestWithMetadata()` is the only Astro-specific call site needed
+ * around the standard `client.queries.<name>(...)` pattern. In production
+ * it stamps the result with the metadata `tinaField()` reads to build
+ * click-to-focus markers and the `id` the bridge uses to address forms;
+ * inside the editor iframe it additionally swaps `data` for the unsaved
+ * overlay the bridge has POSTed for that form.
+ *
+ * The current `Astro.request` is read from AsyncLocalStorage scoped by
+ * the middleware the `tina()` integration injects, so the call site stays
+ * a single argument:
+ *
+ * ```ts
+ * import client from '../../tina/__generated__/client';
+ * import { requestWithMetadata } from '@tinacms/astro';
+ *
+ * const post = await requestWithMetadata(
+ *   client.queries.post({ relativePath: `${slug}.md` }),
+ * );
+ * ```
+ *
+ * Outside a request scope (static builds, integration not installed) the
+ * wrapper falls through to a metadata-stamped pass-through — production
+ * output stays correct, just without the live overlay swap that only
+ * matters during admin editing.
+ */
+import { addMetadata, hashFromQuery } from '@tinacms/bridge/metadata';
+import { readOverlay } from '@tinacms/bridge/preview';
+import { recordForm } from './internal/forms-store';
+import { requestStore } from './internal/request-context';
+
+export interface QueryResult<TData> {
+  data: TData;
+  query: string;
+  variables: Record<string, unknown>;
+  id: string;
+}
+
+/** Shape every `client.queries.<name>` returns. Inferring from this lets
+ *  `requestWithMetadata()` stay framework-agnostic — it doesn't need to
+ *  know about `PostQuery`, `PageQuery`, etc. */
+type ClientResult<TData> =
+  | {
+      data: TData;
+      query: string;
+      variables: Record<string, unknown>;
+    }
+  | null
+  | undefined;
+
+export async function requestWithMetadata<TData>(
+  source: ClientResult<TData> | Promise<ClientResult<TData>>
+): Promise<QueryResult<TData>> {
+  let result: ClientResult<TData> = null;
+  try {
+    result = (await source) ?? null;
+  } catch (error) {
+    // Disk-fetch failures are normal in edit mode (a doc the editor is
+    // creating doesn't exist yet) and should never crash the page render
+    // — the bridge will populate via overlay. In production, the warning
+    // surfaces real misconfigurations.
+    console.warn('[@tinacms/astro] client query failed', error);
+  }
+
+  const query = result?.query ?? '';
+  const variables = result?.variables ?? {};
+  const id = hashFromQuery(JSON.stringify({ query, variables }));
+  const data = (result?.data ?? {}) as TData;
+
+  const request = requestStore.getStore();
+  let resolvedData: TData = data;
+  if (request) {
+    const overlay = await readOverlay<TData>(request, id);
+    if (overlay !== undefined) {
+      resolvedData = overlay;
+    }
+  }
+
+  const enriched = {
+    data: addMetadata(id, resolvedData) as TData,
+    query,
+    variables,
+    id,
+  };
+
+  // Append to the per-request forms list so the integration's middleware
+  // can splice the bridge wiring into edit-mode pages without the caller
+  // touching their layout. No-ops outside a request scope (static builds).
+  recordForm({
+    id,
+    query,
+    variables,
+    data: enriched.data as unknown as object,
+  });
+
+  return enriched;
+}

package/src/experimental.ts

@@ -0,0 +1,14 @@
+/**
+ * Experimental surface area. Anything here may change in a minor or
+ * patch release — opt in only when the underlying tradeoff is worth
+ * it for your project.
+ *
+ * `experimental_createIslandRoute` builds on Astro's
+ * `experimental_AstroContainer`, which Astro itself flags as unstable;
+ * this re-export inherits the same caveat.
+ */
+export {
+  experimental_createIslandRoute,
+  type IslandConfig,
+  type IslandRegistry,
+} from './island-route';

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Runtime entry for the package's `.` subpath. Astro consumers resolve
+ * through the `astro` export condition straight to `src/TinaMarkdown.astro`
+ * — they get the real component as the default export plus the named
+ * helpers re-exported from the .astro frontmatter.
+ *
+ * This file is the fallback for any tool that *doesn't* understand the
+ * `astro` condition (TypeScript types, plain Node ESM resolution). It
+ * exposes the named runtime helpers and a placeholder default that
+ * throws with a clear redirect if someone reaches it.
+ */
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+import type { CustomComponentsMap, TinaRichTextContent } from './types';
+
+export { requestWithMetadata, type QueryResult } from './data';
+export { tinaField } from './tina-field';
+export type {
+  AstroComponent,
+  CustomComponentsMap,
+  MdxElement,
+  TextElement,
+  TinaRichTextContent,
+  TinaRichTextNode,
+  TinaRichTextRoot,
+} from './types';
+
+/**
+ * Typed shape of `<TinaMarkdown content={...} components={...} />` for tools
+ * that resolve through the `types` / `default` export condition rather than
+ * the `astro` condition. The actual component is `src/TinaMarkdown.astro`;
+ * this placeholder throws if invoked because the only legitimate caller is
+ * Astro's component pipeline, which reaches the .astro file directly.
+ *
+ * The intersection of `AstroComponentFactory` (Astro's component-validity
+ * check) and a typed prop signature (TinaMarkdown's actual API) gives the
+ * Astro language server enough shape to both recognise this as a renderable
+ * component AND offer prop completions / type errors at the call site.
+ */
+type TinaMarkdownComponent = AstroComponentFactory & {
+  (props: {
+    content: TinaRichTextContent;
+    components?: CustomComponentsMap;
+  }): unknown;
+};
+
+const TinaMarkdownPlaceholder = (() => {
+  throw new Error(
+    "[@tinacms/astro] TinaMarkdown must be loaded through Astro's pipeline. " +
+      'Add `tina()` from `@tinacms/astro/integration` to your astro.config integrations, ' +
+      'or import directly from `@tinacms/astro/TinaMarkdown.astro`.'
+  );
+}) as unknown as TinaMarkdownComponent;
+
+export default TinaMarkdownPlaceholder;

package/src/integration.ts

@@ -0,0 +1,49 @@
+/**
+ * Tina Astro integration. Wires the middleware that exposes
+ * `Astro.locals.tinaEdit` so pages and components can branch on edit
+ * context without writing `src/middleware.ts` themselves.
+ *
+ * Usage:
+ *
+ * ```ts
+ * // astro.config.mjs
+ * import { defineConfig } from 'astro/config';
+ * import tina from '@tinacms/astro/integration';
+ *
+ * export default defineConfig({
+ *   integrations: [tina()],
+ * });
+ * ```
+ */
+import type { AstroIntegration } from 'astro';
+
+export interface TinaIntegrationOptions {
+  /** Override the middleware ordering relative to other integrations.
+   *  Defaults to `'pre'` so `Astro.locals.tinaEdit` is populated before
+   *  user middleware sees the request. */
+  middlewareOrder?: 'pre' | 'post';
+}
+
+export default function tina(
+  options: TinaIntegrationOptions = {}
+): AstroIntegration {
+  const { middlewareOrder = 'pre' } = options;
+  return {
+    name: '@tinacms/astro',
+    hooks: {
+      'astro:config:setup': ({ addMiddleware, injectRoute }) => {
+        addMiddleware({
+          entrypoint: '@tinacms/astro/middleware',
+          order: middlewareOrder,
+        });
+        // The middleware splices a `<script type="module" src="/_tina/bridge.js">`
+        // into edit-mode pages. This route serves the bundled bridge.
+        // Production pages never reference it (the script tag isn't injected).
+        injectRoute({
+          pattern: '/_tina/bridge.js',
+          entrypoint: '@tinacms/astro/bridge-route',
+        });
+      },
+    },
+  };
+}

package/src/internal/escape.ts

@@ -0,0 +1,15 @@
+/**
+ * HTML attribute escape for double-quoted attributes. `&` is escaped first
+ * so the subsequent replacements don't double-encode existing entities.
+ * Adequate for the shapes we emit server-side — `data-tina-form` payloads
+ * and `data-tina-island` marker paths — neither of which is parsed as
+ * HTML downstream.
+ */
+export function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}

package/src/internal/forms-store.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-request collector for `tina()` results. Each call pushes its
+ * `{id, query, variables, data}` payload here so the integration's
+ * middleware can read the full list at response time and splice the
+ * bridge wiring into edit-mode pages — the user never writes a `forms`
+ * prop or imports a wiring component.
+ *
+ * Initialised by the middleware the `tina()` integration injects.
+ *
+ * The store is keyed by a `Symbol.for(...)` slot on `globalThis` so all
+ * bundle copies of this module (esbuild inlines it into each entry that
+ * imports it) share the same instance — without that, the middleware
+ * would `.run()` one ALS while `tina()` reads from a different one.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export interface CollectedForm {
+  id: string;
+  query: string;
+  variables: object;
+  data: object;
+}
+
+const STORE_KEY = Symbol.for('@tinacms/astro/forms-store');
+
+type Slot = { [STORE_KEY]?: AsyncLocalStorage<CollectedForm[]> };
+const slot = globalThis as unknown as Slot;
+
+export const formsStore: AsyncLocalStorage<CollectedForm[]> = (slot[
+  STORE_KEY
+] ??= new AsyncLocalStorage<CollectedForm[]>());
+
+export function recordForm(form: CollectedForm): void {
+  const list = formsStore.getStore();
+  if (!list) return;
+  // Same id can appear multiple times (e.g., layout + page both fetch the
+  // global). De-dup on id so the bridge doesn't see two open events for
+  // the same form.
+  if (list.some((existing) => existing.id === form.id)) return;
+  list.push(form);
+}

package/src/internal/request-context.ts

@@ -0,0 +1,23 @@
+/**
+ * Request-scoped storage so `tina()` can read the current request without
+ * the caller threading `Astro.request` through every loader. The
+ * middleware injected by the `tina()` integration runs every request
+ * through `requestStore.run(...)`.
+ *
+ * Falls through to `undefined` outside a request scope (static builds,
+ * integration not installed) — `tina()` treats that as "no overlay,
+ * no edit mode," so static contexts still produce correct output.
+ *
+ * Stashed on `globalThis` via `Symbol.for(...)` so all bundle copies of
+ * this module share one ALS instance — esbuild inlines it into every
+ * entry that imports it, and per-entry copies wouldn't share state.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const STORE_KEY = Symbol.for('@tinacms/astro/request-context');
+
+type Slot = { [STORE_KEY]?: AsyncLocalStorage<Request> };
+const slot = globalThis as unknown as Slot;
+
+export const requestStore: AsyncLocalStorage<Request> = (slot[STORE_KEY] ??=
+  new AsyncLocalStorage<Request>());

package/src/is-edit-mode.ts

@@ -0,0 +1,68 @@
+/**
+ * Server-side check: is this request being rendered inside the TinaCMS
+ * admin iframe?
+ *
+ * Resolves true when any of the following hold:
+ *   1. `?tina-edit=1` — explicit signal added by the admin's router for
+ *      deep-link previews.
+ *   2. `Sec-Fetch-Dest: iframe` AND a same-origin Referer under
+ *      `/admin/` — covers the first request after the admin sets
+ *      `iframe.src` to a preview URL.
+ *   3. `Sec-Fetch-Dest: iframe` AND a `__tina_edit=1` cookie — covers
+ *      in-iframe link clicks, where the Referer is the previous preview
+ *      page rather than `/admin/`. The middleware sets the cookie on
+ *      every edit-mode response so the session sticks for the iframe's
+ *      lifetime.
+ *
+ * Direct browser visits set `Sec-Fetch-Dest: document` for top-level
+ * navigations, so a stale cookie left behind in someone's browser can
+ * never trip edit mode outside an iframe — production HTML is byte-
+ * identical to a Tina-free Astro app for end users.
+ */
+export const EDIT_COOKIE = '__tina_edit';
+
+/**
+ * Set-Cookie header value the middleware writes on every edit-mode
+ * response. Refreshing on each response keeps long editing sessions
+ * sticky and short Max-Age limits the blast radius if a cookie lingers.
+ * The `Sec-Fetch-Dest: iframe` gate in `isEditMode` blocks the cookie
+ * from triggering edit mode on top-level visits.
+ */
+export const EDIT_COOKIE_HEADER = `${EDIT_COOKIE}=1; Path=/; SameSite=Strict; Max-Age=3600`;
+
+export function isEditMode(request: Request): boolean {
+  const url = new URL(request.url);
+  if (url.searchParams.get('tina-edit') === '1') return true;
+
+  const dest = request.headers.get('Sec-Fetch-Dest');
+  if (dest !== 'iframe') return false;
+
+  const referer = request.headers.get('Referer');
+  if (referer) {
+    try {
+      const refererUrl = new URL(referer);
+      if (
+        refererUrl.origin === url.origin &&
+        refererUrl.pathname.startsWith('/admin/')
+      ) {
+        return true;
+      }
+    } catch {
+      // Malformed Referer — fall through to cookie check.
+    }
+  }
+
+  return readCookie(request, EDIT_COOKIE) === '1';
+}
+
+export function readCookie(request: Request, name: string): string | null {
+  const header = request.headers.get('Cookie');
+  if (!header) return null;
+  for (const pair of header.split(';')) {
+    const eq = pair.indexOf('=');
+    if (eq === -1) continue;
+    const key = pair.slice(0, eq).trim();
+    if (key === name) return pair.slice(eq + 1).trim();
+  }
+  return null;
+}

package/src/island-route.ts

@@ -0,0 +1,110 @@
+/**
+ * Factory for the dynamic `/tina-island/[name]` endpoint the bridge calls
+ * to refetch a region with the editor's overlay applied. Each entry in
+ * `islands` describes one editable region: how to load its data, which
+ * Astro component to render, and the wrapper element the page-side
+ * `<div data-tina-island>` is expected to swap.
+ *
+ * @experimental
+ *
+ * Built on Astro's `experimental_AstroContainer`, which is itself
+ * experimental — Astro may break the underlying API in any minor or patch
+ * release. The shape of `createIslandRoute` is similarly experimental and
+ * will graduate once the container API stabilises.
+ *
+ * Usage:
+ *
+ * ```ts
+ * // src/pages/tina-island/[name].ts
+ * import { experimental_createIslandRoute } from '@tinacms/astro/experimental';
+ * import { islands } from '../../lib/islands';
+ *
+ * export const prerender = false;
+ * export const ALL = experimental_createIslandRoute(islands);
+ * ```
+ */
+import type { APIRoute } from 'astro';
+import { experimental_AstroContainer as AstroContainer } from 'astro/container';
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+import { PREVIEW_CONTENT_TYPE } from '@tinacms/bridge/preview';
+import { escapeAttr } from './internal/escape';
+
+export interface IslandWrapper {
+  tag: string;
+  className?: string;
+}
+
+export interface IslandConfig {
+  /** Resolve the data the component needs. May ignore the search params. */
+  fetch: (request: Request, params: URLSearchParams) => Promise<unknown>;
+  /** Astro component to render with the fetched data. */
+  component: AstroComponentFactory;
+  /** Outer element the bridge swaps into — must match the page-side wrapper. */
+  wrapper: IslandWrapper;
+  /** Map fetched data + URL params to the component's props. */
+  propsFromData: (
+    data: unknown,
+    params: URLSearchParams
+  ) => Record<string, unknown>;
+}
+
+export type IslandRegistry = Record<string, IslandConfig>;
+
+export function experimental_createIslandRoute(
+  islands: IslandRegistry
+): APIRoute {
+  return async ({ params, request, url }) => {
+    const rejection = rejectIfUnsafe(request);
+    if (rejection) return rejection;
+
+    const island = islands[params.name ?? ''];
+    if (!island) {
+      return new Response(`Unknown island "${params.name}"`, { status: 404 });
+    }
+
+    try {
+      const data = await island.fetch(request, url.searchParams);
+      const container = await AstroContainer.create();
+      const html = await container.renderToString(island.component, {
+        props: island.propsFromData(data, url.searchParams),
+      });
+      return new Response(wrapIsland(html, island.wrapper, url), {
+        headers: {
+          'Content-Type': 'text/html; charset=utf-8',
+          'Cache-Control': 'no-store',
+        },
+      });
+    } catch {
+      return new Response('Island render failed', { status: 500 });
+    }
+  };
+}
+
+/**
+ * Layered defense for an endpoint whose response is shaped by the request
+ * body. The bridge always issues a same-origin POST with the Tina-preview
+ * content-type; production traffic never matches all three signals so it
+ * can never reach the renderer.
+ */
+function rejectIfUnsafe(request: Request): Response | null {
+  if (request.method !== 'POST') {
+    return new Response('Method Not Allowed', { status: 405 });
+  }
+  const contentType = request.headers.get('content-type') ?? '';
+  if (!contentType.includes(PREVIEW_CONTENT_TYPE)) {
+    return new Response('Not Found', { status: 404 });
+  }
+  const fetchSite = request.headers.get('sec-fetch-site');
+  if (fetchSite === 'cross-site' || fetchSite === 'cross-origin') {
+    return new Response('Forbidden', { status: 403 });
+  }
+  return null;
+}
+
+function wrapIsland(html: string, wrapper: IslandWrapper, url: URL): string {
+  const cls = wrapper.className
+    ? ` class="${escapeAttr(wrapper.className)}"`
+    : '';
+  const marker = escapeAttr(`${url.pathname}${url.search}`);
+  return `<${wrapper.tag}${cls} data-tina-island="${marker}">${html}</${wrapper.tag}>`;
+}