@emdash-cms/plugin-atproto 0.0.1

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@emdash-cms/plugin-atproto",
+  "version": "0.0.1",
+  "description": "AT Protocol / standard.site syndication plugin for EmDash CMS",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./sandbox": "./src/sandbox-entry.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "emdash",
+    "cms",
+    "plugin",
+    "atproto",
+    "bluesky",
+    "standard-site",
+    "syndication",
+    "fediverse"
+  ],
+  "author": "Matt Kane",
+  "license": "MIT",
+  "peerDependencies": {
+    "emdash": "0.0.1"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsgo --noEmit"
+  }
+}

package/src/atproto.ts

@@ -0,0 +1,408 @@
+/**
+ * AT Protocol client helpers
+ *
+ * Handles session management, record CRUD, and handle resolution.
+ * All HTTP goes through ctx.http.fetch() for sandbox compatibility.
+ */
+
+import type { PluginContext } from "emdash";
+
+// ── Types ───────────────────────────────────────────────────────
+
+export interface AtSession {
+	accessJwt: string;
+	refreshJwt: string;
+	did: string;
+	handle: string;
+}
+
+export interface AtRecord {
+	uri: string;
+	cid: string;
+}
+
+export interface BlobRef {
+	$type: "blob";
+	ref: { $link: string };
+	mimeType: string;
+	size: number;
+}
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+/** Get the HTTP client from plugin context, or throw a helpful error. */
+export function requireHttp(ctx: PluginContext) {
+	if (!ctx.http) {
+		throw new Error("AT Protocol plugin requires the network:fetch capability");
+	}
+	return ctx.http;
+}
+
+/** Validate that a PDS response contains expected string fields. */
+function requireString(data: Record<string, unknown>, field: string, context: string): string {
+	const value = data[field];
+	if (typeof value !== "string") {
+		throw new Error(`${context}: missing or invalid '${field}' in response`);
+	}
+	return value;
+}
+
+// ── Session management ──────────────────────────────────────────
+
+/**
+ * Create a new session with the PDS using an app password.
+ */
+export async function createSession(
+	ctx: PluginContext,
+	pdsHost: string,
+	identifier: string,
+	password: string,
+): Promise<AtSession> {
+	const http = requireHttp(ctx);
+	const res = await http.fetch(`https://${pdsHost}/xrpc/com.atproto.server.createSession`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ identifier, password }),
+	});
+
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new Error(`createSession failed (${res.status}): ${body}`);
+	}
+
+	const data = (await res.json()) as Record<string, unknown>;
+	return {
+		accessJwt: requireString(data, "accessJwt", "createSession"),
+		refreshJwt: requireString(data, "refreshJwt", "createSession"),
+		did: requireString(data, "did", "createSession"),
+		handle: requireString(data, "handle", "createSession"),
+	};
+}
+
+/**
+ * Refresh an existing session using the refresh token.
+ */
+export async function refreshSession(
+	ctx: PluginContext,
+	pdsHost: string,
+	refreshJwt: string,
+): Promise<AtSession> {
+	const http = requireHttp(ctx);
+	const res = await http.fetch(`https://${pdsHost}/xrpc/com.atproto.server.refreshSession`, {
+		method: "POST",
+		headers: { Authorization: `Bearer ${refreshJwt}` },
+	});
+
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new Error(`refreshSession failed (${res.status}): ${body}`);
+	}
+
+	const data = (await res.json()) as Record<string, unknown>;
+	return {
+		accessJwt: requireString(data, "accessJwt", "refreshSession"),
+		refreshJwt: requireString(data, "refreshJwt", "refreshSession"),
+		did: requireString(data, "did", "refreshSession"),
+		handle: requireString(data, "handle", "refreshSession"),
+	};
+}
+
+/**
+ * In-flight refresh promise for deduplication.
+ * Prevents concurrent publishes from racing on token refresh,
+ * which would corrupt tokens since PDS invalidates refresh tokens after use.
+ */
+let refreshInFlight: Promise<AtSession> | null = null;
+
+/**
+ * Get a valid access token, refreshing if needed.
+ * Uses promise deduplication to prevent concurrent refresh races.
+ */
+export async function ensureSession(ctx: PluginContext): Promise<{
+	accessJwt: string;
+	did: string;
+	pdsHost: string;
+}> {
+	const pdsHost = (await ctx.kv.get<string>("settings:pdsHost")) || "bsky.social";
+	const handle = await ctx.kv.get<string>("settings:handle");
+	const appPassword = await ctx.kv.get<string>("settings:appPassword");
+
+	if (!handle || !appPassword) {
+		throw new Error("AT Protocol credentials not configured");
+	}
+
+	// Try existing tokens first
+	const existingAccess = await ctx.kv.get<string>("state:accessJwt");
+	const existingRefresh = await ctx.kv.get<string>("state:refreshJwt");
+	const existingDid = await ctx.kv.get<string>("state:did");
+
+	if (existingAccess && existingDid) {
+		return { accessJwt: existingAccess, did: existingDid, pdsHost };
+	}
+
+	// Try refresh if we have a refresh token (deduplicated)
+	if (existingRefresh) {
+		if (!refreshInFlight) {
+			refreshInFlight = refreshSession(ctx, pdsHost, existingRefresh)
+				.then(async (session) => {
+					await persistSession(ctx, session);
+					return session;
+				})
+				.finally(() => {
+					refreshInFlight = null;
+				});
+		}
+		try {
+			const session = await refreshInFlight;
+			return { accessJwt: session.accessJwt, did: session.did, pdsHost };
+		} catch {
+			// Refresh failed, fall through to full login
+		}
+	}
+
+	// Full login
+	const session = await createSession(ctx, pdsHost, handle, appPassword);
+	await persistSession(ctx, session);
+	return { accessJwt: session.accessJwt, did: session.did, pdsHost };
+}
+
+async function persistSession(ctx: PluginContext, session: AtSession): Promise<void> {
+	await ctx.kv.set("state:accessJwt", session.accessJwt);
+	await ctx.kv.set("state:refreshJwt", session.refreshJwt);
+	await ctx.kv.set("state:did", session.did);
+}
+
+// ── Record CRUD ─────────────────────────────────────────────────
+
+/**
+ * Create a record on the PDS. Returns the AT-URI and CID.
+ * Retries once on 401 (expired token) by refreshing the session.
+ */
+export async function createRecord(
+	ctx: PluginContext,
+	pdsHost: string,
+	accessJwt: string,
+	did: string,
+	collection: string,
+	record: unknown,
+): Promise<AtRecord> {
+	const http = requireHttp(ctx);
+	let res = await http.fetch(`https://${pdsHost}/xrpc/com.atproto.repo.createRecord`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${accessJwt}`,
+			"Content-Type": "application/json",
+		},
+		body: JSON.stringify({ repo: did, collection, record }),
+	});
+
+	// Retry once on 401 with refreshed token
+	if (res.status === 401) {
+		const refreshed = await ensureSessionFresh(ctx, pdsHost);
+		if (refreshed) {
+			res = await http.fetch(`https://${pdsHost}/xrpc/com.atproto.repo.createRecord`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${refreshed.accessJwt}`,
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({ repo: refreshed.did, collection, record }),
+			});
+		}
+	}
+
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new Error(`createRecord failed (${res.status}): ${body}`);
+	}
+
+	const data = (await res.json()) as Record<string, unknown>;
+	return {
+		uri: requireString(data, "uri", "createRecord"),
+		cid: requireString(data, "cid", "createRecord"),
+	};
+}
+
+/**
+ * Update (upsert) a record on the PDS.
+ * Retries once on 401 (expired token).
+ */
+export async function putRecord(
+	ctx: PluginContext,
+	pdsHost: string,
+	accessJwt: string,
+	did: string,
+	collection: string,
+	rkey: string,
+	record: unknown,
+): Promise<AtRecord> {
+	const http = requireHttp(ctx);
+	let res = await http.fetch(`https://${pdsHost}/xrpc/com.atproto.repo.putRecord`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${accessJwt}`,
+			"Content-Type": "application/json",
+		},
+		body: JSON.stringify({ repo: did, collection, rkey, record }),
+	});
+
+	if (res.status === 401) {
+		const refreshed = await ensureSessionFresh(ctx, pdsHost);
+		if (refreshed) {
+			res = await http.fetch(`https://${pdsHost}/xrpc/com.atproto.repo.putRecord`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${refreshed.accessJwt}`,
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({ repo: refreshed.did, collection, rkey, record }),
+			});
+		}
+	}
+
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new Error(`putRecord failed (${res.status}): ${body}`);
+	}
+
+	const data = (await res.json()) as Record<string, unknown>;
+	return {
+		uri: requireString(data, "uri", "putRecord"),
+		cid: requireString(data, "cid", "putRecord"),
+	};
+}
+
+/**
+ * Delete a record from the PDS.
+ * Retries once on 401 (expired token).
+ */
+export async function deleteRecord(
+	ctx: PluginContext,
+	pdsHost: string,
+	accessJwt: string,
+	did: string,
+	collection: string,
+	rkey: string,
+): Promise<void> {
+	const http = requireHttp(ctx);
+	let res = await http.fetch(`https://${pdsHost}/xrpc/com.atproto.repo.deleteRecord`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${accessJwt}`,
+			"Content-Type": "application/json",
+		},
+		body: JSON.stringify({ repo: did, collection, rkey }),
+	});
+
+	if (res.status === 401) {
+		const refreshed = await ensureSessionFresh(ctx, pdsHost);
+		if (refreshed) {
+			res = await http.fetch(`https://${pdsHost}/xrpc/com.atproto.repo.deleteRecord`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${refreshed.accessJwt}`,
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({ repo: refreshed.did, collection, rkey }),
+			});
+		}
+	}
+
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new Error(`deleteRecord failed (${res.status}): ${body}`);
+	}
+}
+
+/**
+ * Force a session refresh (for 401 retry). Clears the stale access token
+ * and delegates to ensureSession, which handles refresh deduplication.
+ * Returns null if refresh fails.
+ */
+async function ensureSessionFresh(
+	ctx: PluginContext,
+	_pdsHost: string,
+): Promise<{ accessJwt: string; did: string } | null> {
+	// Clear stale access token so ensureSession will attempt a refresh
+	await ctx.kv.set("state:accessJwt", "");
+
+	try {
+		const result = await ensureSession(ctx);
+		return { accessJwt: result.accessJwt, did: result.did };
+	} catch {
+		return null;
+	}
+}
+
+// ── Handle resolution ───────────────────────────────────────────
+
+/**
+ * Resolve an AT Protocol handle to a DID.
+ * Uses the public API -- no auth required.
+ */
+export async function resolveHandle(ctx: PluginContext, handle: string): Promise<string> {
+	const http = requireHttp(ctx);
+	const res = await http.fetch(
+		`https://public.api.bsky.app/xrpc/com.atproto.identity.resolveHandle?handle=${encodeURIComponent(handle)}`,
+	);
+
+	if (!res.ok) {
+		throw new Error(`resolveHandle failed for ${handle} (${res.status})`);
+	}
+
+	const data = (await res.json()) as Record<string, unknown>;
+	return requireString(data, "did", "resolveHandle");
+}
+
+// ── Blob upload ─────────────────────────────────────────────────
+
+/**
+ * Upload a blob (image) to the PDS. Returns a blob reference for embedding.
+ */
+export async function uploadBlob(
+	ctx: PluginContext,
+	pdsHost: string,
+	accessJwt: string,
+	imageBytes: ArrayBuffer,
+	mimeType: string,
+): Promise<BlobRef> {
+	const http = requireHttp(ctx);
+	const res = await http.fetch(`https://${pdsHost}/xrpc/com.atproto.repo.uploadBlob`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${accessJwt}`,
+			"Content-Type": mimeType,
+		},
+		body: imageBytes,
+	});
+
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new Error(`uploadBlob failed (${res.status}): ${body}`);
+	}
+
+	const data = (await res.json()) as Record<string, unknown>;
+	if (!data.blob || typeof data.blob !== "object") {
+		throw new Error("uploadBlob: missing 'blob' in response");
+	}
+	const blob = data.blob as Record<string, unknown>;
+	if (!blob.ref || typeof blob.ref !== "object") {
+		throw new Error("uploadBlob: malformed blob reference in response");
+	}
+	return data.blob as BlobRef;
+}
+
+// ── Utilities ───────────────────────────────────────────────────
+
+/**
+ * Extract the rkey from an AT-URI.
+ * at://did:plc:xxx/collection/rkey -> rkey
+ */
+export function rkeyFromUri(uri: string): string {
+	const parts = uri.split("/");
+	const rkey = parts.at(-1);
+	if (!rkey) {
+		throw new Error(`Invalid AT-URI: ${uri}`);
+	}
+	return rkey;
+}

package/src/bluesky.ts

@@ -0,0 +1,185 @@
+/**
+ * Bluesky cross-posting helpers
+ *
+ * Builds app.bsky.feed.post records with link cards and rich text facets.
+ */
+
+import type { BlobRef } from "./atproto.js";
+
+// ── Pre-compiled regexes ────────────────────────────────────────
+
+const TEMPLATE_TITLE_RE = /\{title\}/g;
+const TEMPLATE_URL_RE = /\{url\}/g;
+const TEMPLATE_EXCERPT_RE = /\{excerpt\}/g;
+const TRAILING_PUNCTUATION_RE = /[.,;:!?'"]+$/;
+// Global regexes for facet detection -- reset lastIndex before each use
+const URL_REGEX = /https?:\/\/[^\s)>\]]+/g;
+const HASHTAG_REGEX = /(?<=\s|^)#([a-zA-Z0-9_]+)/g;
+
+// ── Types ───────────────────────────────────────────────────────
+
+export interface BskyPost {
+	$type: "app.bsky.feed.post";
+	text: string;
+	createdAt: string;
+	langs?: string[];
+	facets?: BskyFacet[];
+	embed?: BskyEmbed;
+}
+
+export interface BskyFacet {
+	index: { byteStart: number; byteEnd: number };
+	features: Array<
+		| { $type: "app.bsky.richtext.facet#link"; uri: string }
+		| { $type: "app.bsky.richtext.facet#tag"; tag: string }
+	>;
+}
+
+export type BskyEmbed = {
+	$type: "app.bsky.embed.external";
+	external: {
+		uri: string;
+		title: string;
+		description: string;
+		thumb?: BlobRef;
+	};
+};
+
+// ── Post builder ────────────────────────────────────────────────
+
+/**
+ * Build a Bluesky post record for cross-posting published content.
+ */
+export function buildBskyPost(opts: {
+	template: string;
+	content: Record<string, unknown>;
+	siteUrl: string;
+	thumbBlob?: BlobRef;
+	langs?: string[];
+}): BskyPost {
+	const { template, content, siteUrl, thumbBlob, langs } = opts;
+
+	const title = (content.title as string) || "Untitled";
+	const slug = content.slug as string;
+	const excerpt = (content.excerpt || content.description || "") as string;
+	const url = slug ? `${stripTrailingSlash(siteUrl)}/${slug}` : siteUrl;
+
+	// Apply template -- substitute before truncation so we can detect
+	// if the URL survives intact after truncation
+	const fullText = template
+		.replace(TEMPLATE_TITLE_RE, title)
+		.replace(TEMPLATE_URL_RE, url)
+		.replace(TEMPLATE_EXCERPT_RE, excerpt);
+
+	// Truncate to 300 graphemes (Bluesky limit)
+	const text = truncateGraphemes(fullText, 300);
+	const wasTruncated = text !== fullText;
+
+	const post: BskyPost = {
+		$type: "app.bsky.feed.post",
+		text,
+		createdAt: new Date().toISOString(),
+	};
+
+	if (langs && langs.length > 0) {
+		post.langs = langs.slice(0, 3); // Max 3 per spec
+	}
+
+	// Auto-detect URLs in text and build facets.
+	// If text was truncated, skip facets -- truncation may have cut
+	// a URL mid-string, producing a broken link facet.
+	if (!wasTruncated) {
+		const facets = buildFacets(text);
+		if (facets.length > 0) {
+			post.facets = facets;
+		}
+	}
+
+	// Link card embed
+	post.embed = {
+		$type: "app.bsky.embed.external",
+		external: {
+			uri: url,
+			title,
+			description: truncateGraphemes(excerpt, 300),
+			...(thumbBlob ? { thumb: thumbBlob } : {}),
+		},
+	};
+
+	return post;
+}
+
+// ── Rich text facets ────────────────────────────────────────────
+
+/**
+ * Build rich text facets for URLs and hashtags in text.
+ *
+ * CRITICAL: Facet byte offsets use UTF-8 bytes, not JavaScript string indices.
+ */
+export function buildFacets(text: string): BskyFacet[] {
+	const encoder = new TextEncoder();
+	const facets: BskyFacet[] = [];
+
+	// Detect URLs
+	let match: RegExpExecArray | null;
+	URL_REGEX.lastIndex = 0;
+	while ((match = URL_REGEX.exec(text)) !== null) {
+		// Strip trailing punctuation that was captured by the greedy regex
+		const cleanUrl = match[0].replace(TRAILING_PUNCTUATION_RE, "");
+		const beforeBytes = encoder.encode(text.slice(0, match.index));
+		const matchBytes = encoder.encode(cleanUrl);
+		facets.push({
+			index: {
+				byteStart: beforeBytes.length,
+				byteEnd: beforeBytes.length + matchBytes.length,
+			},
+			features: [{ $type: "app.bsky.richtext.facet#link", uri: cleanUrl }],
+		});
+	}
+
+	// Detect hashtags
+	HASHTAG_REGEX.lastIndex = 0;
+	while ((match = HASHTAG_REGEX.exec(text)) !== null) {
+		const tag = match[1];
+		if (!tag) continue;
+
+		// Include the # in the byte range
+		const beforeBytes = encoder.encode(text.slice(0, match.index));
+		const matchBytes = encoder.encode(match[0]);
+		facets.push({
+			index: {
+				byteStart: beforeBytes.length,
+				byteEnd: beforeBytes.length + matchBytes.length,
+			},
+			features: [{ $type: "app.bsky.richtext.facet#tag", tag }],
+		});
+	}
+
+	return facets;
+}
+
+// ── Utilities ───────────────────────────────────────────────────
+
+/**
+ * Truncate a string to a maximum number of graphemes.
+ * Uses Intl.Segmenter for correct Unicode handling.
+ */
+function truncateGraphemes(text: string, maxGraphemes: number): string {
+	// Intl.Segmenter handles multi-codepoint graphemes (emoji, combining chars)
+	const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
+	const segments = [...segmenter.segment(text)];
+
+	if (segments.length <= maxGraphemes) return text;
+
+	// Truncate and add ellipsis
+	return (
+		segments
+			.slice(0, maxGraphemes - 1)
+			.map((s) => s.segment)
+			.join("") + "\u2026"
+	);
+}
+
+function stripTrailingSlash(url: string): string {
+	return url.endsWith("/") ? url.slice(0, -1) : url;
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * AT Protocol / standard.site Plugin for EmDash CMS
+ *
+ * Syndicates published content to the AT Protocol network using the
+ * standard.site lexicons, with optional cross-posting to Bluesky.
+ *
+ * Features:
+ * - Creates site.standard.publication record (one per site)
+ * - Creates site.standard.document records on publish
+ * - Optional Bluesky cross-post with link card
+ * - Automatic <link rel="site.standard.document"> injection via page:metadata
+ * - Sync status tracking in plugin storage
+ *
+ * Designed for sandboxed execution:
+ * - All HTTP via ctx.http.fetch()
+ * - Block Kit admin UI (no React components)
+ * - Capabilities: read:content, network:fetch:any
+ */
+
+import type { PluginDescriptor } from "emdash";
+
+// ── Descriptor ──────────────────────────────────────────────────
+
+/**
+ * Create the AT Protocol plugin descriptor.
+ * Import this in your astro.config.mjs / live.config.ts.
+ */
+export function atprotoPlugin(): PluginDescriptor {
+	return {
+		id: "atproto",
+		version: "0.1.0",
+		format: "standard",
+		entrypoint: "@emdash-cms/plugin-atproto/sandbox",
+		capabilities: ["read:content", "network:fetch:any"],
+		storage: {
+			publications: { indexes: ["contentId", "platform", "publishedAt"] },
+		},
+		// Block Kit admin pages (no adminEntry needed -- sandboxed)
+		adminPages: [{ path: "/status", label: "AT Protocol", icon: "globe" }],
+		adminWidgets: [{ id: "sync-status", title: "AT Protocol", size: "third" }],
+	};
+}