emdash 0.0.0-a → 0.0.1

package/src/api/openapi/index.ts

@@ -0,0 +1 @@
+export { generateOpenApiDocument } from "./document.js";

package/src/api/parse.ts

@@ -0,0 +1,139 @@
+/**
+ * Request body and query parameter parsing with Zod validation.
+ *
+ * All API routes should use these utilities instead of `request.json() as T`
+ * or raw `url.searchParams.get()` with manual coercion.
+ */
+
+import { z } from "zod";
+
+import { apiError } from "./error.js";
+
+/** Maximum allowed JSON request body size (10 MB). */
+const MAX_BODY_SIZE = 10 * 1024 * 1024;
+
+/**
+ * Result of parsing: either the validated data or an error Response.
+ * Routes should check `if (result instanceof Response) return result;`
+ */
+export type ParseResult<T> = T | Response;
+
+/**
+ * Parse and validate a JSON request body against a Zod schema.
+ *
+ * Returns the validated data on success, or a 400 Response on failure.
+ * Replaces all `(await request.json()) as T` casts.
+ */
+export async function parseBody<T extends z.ZodType>(
+	request: Request,
+	schema: T,
+): Promise<ParseResult<z.infer<T>>> {
+	// Best-effort size check via Content-Length (can be absent with chunked encoding)
+	const contentLength = request.headers.get("Content-Length");
+	if (contentLength && parseInt(contentLength, 10) > MAX_BODY_SIZE) {
+		return apiError("PAYLOAD_TOO_LARGE", "Request body too large", 413);
+	}
+
+	let raw: unknown;
+	try {
+		raw = await request.json();
+	} catch {
+		return apiError("INVALID_JSON", "Request body must be valid JSON", 400);
+	}
+
+	return validate(schema, raw);
+}
+
+/**
+ * Parse and validate an optional JSON request body.
+ *
+ * Returns `defaultValue` if the body is empty, or the validated data if present.
+ * For endpoints where the body is optional (e.g., preview-url, confirm).
+ */
+export async function parseOptionalBody<T extends z.ZodType>(
+	request: Request,
+	schema: T,
+	defaultValue: z.infer<T>,
+): Promise<ParseResult<z.infer<T>>> {
+	// Best-effort size check via Content-Length (can be absent with chunked encoding)
+	const contentLength = request.headers.get("Content-Length");
+	if (contentLength && parseInt(contentLength, 10) > MAX_BODY_SIZE) {
+		return apiError("PAYLOAD_TOO_LARGE", "Request body too large", 413);
+	}
+
+	let text: string;
+	try {
+		text = await request.text();
+	} catch {
+		return defaultValue;
+	}
+
+	if (!text.trim()) {
+		return defaultValue;
+	}
+
+	let raw: unknown;
+	try {
+		raw = JSON.parse(text);
+	} catch {
+		return apiError("INVALID_JSON", "Request body must be valid JSON", 400);
+	}
+
+	return validate(schema, raw);
+}
+
+/**
+ * Parse and validate URL search params against a Zod schema.
+ *
+ * Converts searchParams to a plain object before validation.
+ * Zod coercion handles string -> number/boolean conversion.
+ * Replaces manual `url.searchParams.get()` + `parseInt()` patterns.
+ */
+export function parseQuery<T extends z.ZodType>(url: URL, schema: T): ParseResult<z.infer<T>> {
+	const raw: Record<string, string> = {};
+	for (const [key, value] of url.searchParams) {
+		raw[key] = value;
+	}
+	return validate(schema, raw);
+}
+
+/**
+ * Validate raw data against a schema. Returns data or error Response.
+ */
+function validate<T extends z.ZodType>(schema: T, data: unknown): ParseResult<z.infer<T>> {
+	const result = schema.safeParse(data);
+
+	if (result.success) {
+		return result.data as z.infer<T>;
+	}
+
+	// Format Zod errors into a readable structure
+	const issues = result.error.issues.map((issue: z.ZodIssue) => ({
+		path: issue.path.join("."),
+		message: issue.message,
+	}));
+
+	return Response.json(
+		{
+			error: {
+				code: "VALIDATION_ERROR",
+				message: "Invalid request data",
+				details: { issues },
+			},
+		},
+		{
+			status: 400,
+			headers: {
+				"Cache-Control": "private, no-store",
+			},
+		},
+	);
+}
+
+/**
+ * Type guard to check if a ParseResult is an error Response.
+ * Usage: `if (isParseError(result)) return result;`
+ */
+export function isParseError<T>(result: ParseResult<T>): result is Response {
+	return result instanceof Response;
+}

package/src/api/redirect.ts

@@ -0,0 +1,14 @@
+/**
+ * Validate that a redirect URL is a safe local path.
+ *
+ * Rejects:
+ * - Protocol-relative URLs (`//evil.com`)
+ * - Backslash bypass (`/\evil.com` — browsers normalize `\` to `/` in Location headers)
+ * - Absolute URLs (`https://evil.com`)
+ * - Empty / nullish values
+ */
+export function isSafeRedirect(url: string | null | undefined): url is string {
+	return (
+		typeof url === "string" && url.startsWith("/") && !url.startsWith("//") && !url.includes("\\")
+	);
+}

package/src/api/rev.ts

@@ -0,0 +1,67 @@
+/**
+ * Opaque _rev token generation and validation.
+ *
+ * Format: base64("version:updated_at")
+ * Stateless — server decodes and checks both components.
+ *
+ * Rules:
+ * - No _rev sent → blind write (backwards-compatible)
+ * - _rev matches → write proceeds, new _rev returned
+ * - _rev mismatch → 409 Conflict
+ */
+
+import type { ContentItem } from "../database/repositories/types.js";
+import { encodeBase64, decodeBase64 } from "../utils/base64.js";
+
+/**
+ * Generate a _rev token from a content item's version and updatedAt.
+ */
+export function encodeRev(item: ContentItem): string {
+	return encodeBase64(`${item.version}:${item.updatedAt}`);
+}
+
+/**
+ * Decode a _rev token into its components.
+ * Returns null if the token is malformed.
+ */
+export function decodeRev(rev: string): { version: number; updatedAt: string } | null {
+	try {
+		const decoded = decodeBase64(rev);
+		const colonIdx = decoded.indexOf(":");
+		if (colonIdx === -1) return null;
+
+		const version = parseInt(decoded.slice(0, colonIdx), 10);
+		const updatedAt = decoded.slice(colonIdx + 1);
+
+		if (isNaN(version) || !updatedAt) return null;
+		return { version, updatedAt };
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Validate a _rev token against a content item.
+ * Returns null if valid (or if no _rev provided), or an error message if invalid.
+ */
+export function validateRev(
+	rev: string | undefined,
+	item: ContentItem,
+): { valid: true } | { valid: false; message: string } {
+	// No _rev = blind write (backwards-compatible)
+	if (!rev) return { valid: true };
+
+	const decoded = decodeRev(rev);
+	if (!decoded) {
+		return { valid: false, message: "Malformed _rev token" };
+	}
+
+	if (decoded.version !== item.version || decoded.updatedAt !== item.updatedAt) {
+		return {
+			valid: false,
+			message: "Content has been modified since last read (version conflict)",
+		};
+	}
+
+	return { valid: true };
+}

package/src/api/schemas/auth.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+
+import { roleLevel } from "./common.js";
+
+// ---------------------------------------------------------------------------
+// WebAuthn credential schemas (matching @emdash-cms/auth/passkey types)
+// ---------------------------------------------------------------------------
+
+const authenticatorTransport = z.enum(["usb", "nfc", "ble", "internal", "hybrid"]);
+
+/** RegistrationResponse — sent by the browser after navigator.credentials.create() */
+const registrationCredential = z.object({
+	id: z.string(),
+	rawId: z.string(),
+	type: z.literal("public-key"),
+	response: z.object({
+		clientDataJSON: z.string(),
+		attestationObject: z.string(),
+		transports: z.array(authenticatorTransport).optional(),
+	}),
+	authenticatorAttachment: z.enum(["platform", "cross-platform"]).optional(),
+});
+
+/** AuthenticationResponse — sent by the browser after navigator.credentials.get() */
+const authenticationCredential = z.object({
+	id: z.string(),
+	rawId: z.string(),
+	type: z.literal("public-key"),
+	response: z.object({
+		clientDataJSON: z.string(),
+		authenticatorData: z.string(),
+		signature: z.string(),
+		userHandle: z.string().optional(),
+	}),
+	authenticatorAttachment: z.enum(["platform", "cross-platform"]).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Auth: Input schemas
+// ---------------------------------------------------------------------------
+
+export const signupRequestBody = z
+	.object({
+		email: z.string().email(),
+	})
+	.meta({ id: "SignupRequestBody" });
+
+export const signupCompleteBody = z
+	.object({
+		token: z.string().min(1),
+		credential: registrationCredential,
+		name: z.string().optional(),
+	})
+	.meta({ id: "SignupCompleteBody" });
+
+export const inviteCreateBody = z
+	.object({
+		email: z.string().email(),
+		role: roleLevel.optional(),
+	})
+	.meta({ id: "InviteCreateBody" });
+
+export const inviteCompleteBody = z
+	.object({
+		token: z.string().min(1),
+		credential: registrationCredential,
+		name: z.string().optional(),
+	})
+	.meta({ id: "InviteCompleteBody" });
+
+export const magicLinkSendBody = z
+	.object({
+		email: z.string().email(),
+	})
+	.meta({ id: "MagicLinkSendBody" });
+
+export const passkeyOptionsBody = z
+	.object({
+		email: z.string().email().optional(),
+	})
+	.meta({ id: "PasskeyOptionsBody" });
+
+export const passkeyVerifyBody = z
+	.object({
+		credential: authenticationCredential,
+	})
+	.meta({ id: "PasskeyVerifyBody" });
+
+export const passkeyRegisterOptionsBody = z
+	.object({
+		name: z.string().optional(),
+	})
+	.meta({ id: "PasskeyRegisterOptionsBody" });
+
+export const passkeyRegisterVerifyBody = z
+	.object({
+		credential: registrationCredential,
+		name: z.string().optional(),
+	})
+	.meta({ id: "PasskeyRegisterVerifyBody" });
+
+export const passkeyRenameBody = z
+	.object({
+		name: z.string().min(1),
+	})
+	.meta({ id: "PasskeyRenameBody" });
+
+export const authMeActionBody = z
+	.object({
+		action: z.string().min(1),
+	})
+	.meta({ id: "AuthMeActionBody" });

package/src/api/schemas/bylines.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+
+import { cursorPaginationQuery, httpUrl } from "./common.js";
+
+/** Slug pattern: lowercase letters, digits, and hyphens; must start with a letter */
+const bylineSlugPattern = /^[a-z][a-z0-9-]*$/;
+
+export const bylineSummarySchema = z
+	.object({
+		id: z.string(),
+		slug: z.string(),
+		displayName: z.string(),
+		bio: z.string().nullable(),
+		avatarMediaId: z.string().nullable(),
+		websiteUrl: z.string().nullable(),
+		userId: z.string().nullable(),
+		isGuest: z.boolean(),
+		createdAt: z.string(),
+		updatedAt: z.string(),
+	})
+	.meta({ id: "BylineSummary" });
+
+export const bylineCreditSchema = z
+	.object({
+		byline: bylineSummarySchema,
+		sortOrder: z.number().int(),
+		roleLabel: z.string().nullable(),
+		source: z.enum(["explicit", "inferred"]).optional().meta({
+			description: "Whether this credit was explicitly assigned or inferred from authorId",
+		}),
+	})
+	.meta({ id: "BylineCredit" });
+
+export const contentBylineInputSchema = z
+	.object({
+		bylineId: z.string().min(1),
+		roleLabel: z.string().nullish(),
+	})
+	.meta({ id: "ContentBylineInput" });
+
+export const bylinesListQuery = cursorPaginationQuery
+	.extend({
+		search: z.string().optional(),
+		isGuest: z.coerce.boolean().optional(),
+		userId: z.string().optional(),
+	})
+	.meta({ id: "BylinesListQuery" });
+
+export const bylineCreateBody = z
+	.object({
+		slug: z
+			.string()
+			.min(1)
+			.regex(bylineSlugPattern, "Slug must contain only lowercase letters, digits, and hyphens"),
+		displayName: z.string().min(1),
+		bio: z.string().nullish(),
+		avatarMediaId: z.string().nullish(),
+		websiteUrl: httpUrl.nullish(),
+		userId: z.string().nullish(),
+		isGuest: z.boolean().optional(),
+	})
+	.meta({ id: "BylineCreateBody" });
+
+export const bylineUpdateBody = z
+	.object({
+		slug: z
+			.string()
+			.min(1)
+			.regex(bylineSlugPattern, "Slug must contain only lowercase letters, digits, and hyphens")
+			.optional(),
+		displayName: z.string().min(1).optional(),
+		bio: z.string().nullish(),
+		avatarMediaId: z.string().nullish(),
+		websiteUrl: httpUrl.nullish(),
+		userId: z.string().nullish(),
+		isGuest: z.boolean().optional(),
+	})
+	.meta({ id: "BylineUpdateBody" });
+
+export const bylineListResponseSchema = z
+	.object({
+		items: z.array(bylineSummarySchema),
+		nextCursor: z.string().optional(),
+	})
+	.meta({ id: "BylineListResponse" });

package/src/api/schemas/comments.ts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Comments: Input schemas
+// ---------------------------------------------------------------------------
+
+export const createCommentBody = z
+	.object({
+		authorName: z.string().min(1).max(100),
+		authorEmail: z.string().email(),
+		body: z.string().min(1).max(5000),
+		parentId: z.string().optional(),
+		/** Honeypot field — hidden in the form, filled only by bots */
+		website_url: z.string().optional(),
+	})
+	.meta({ id: "CreateCommentBody" });
+
+export const commentStatusBody = z
+	.object({
+		status: z.enum(["approved", "pending", "spam", "trash"]),
+	})
+	.meta({ id: "CommentStatusBody" });
+
+export const commentBulkBody = z
+	.object({
+		ids: z.array(z.string().min(1)).min(1).max(100),
+		action: z.enum(["approve", "spam", "trash", "delete"]),
+	})
+	.meta({ id: "CommentBulkBody" });
+
+export const commentListQuery = z
+	.object({
+		status: z.enum(["pending", "approved", "spam", "trash"]).optional(),
+		collection: z.string().optional(),
+		search: z.string().optional(),
+		limit: z.coerce.number().int().min(1).max(100).optional(),
+		cursor: z.string().optional(),
+	})
+	.meta({ id: "CommentListQuery" });
+
+// ---------------------------------------------------------------------------
+// Comments: Response schemas
+// ---------------------------------------------------------------------------
+
+const commentStatusValues = z.enum(["pending", "approved", "spam", "trash"]);
+
+/**
+ * Public-facing comment (no email/IP).
+ *
+ * `replies` is recursive in practice (each reply can have replies), but we
+ * model it as a single level here to avoid circular type inference issues
+ * with tsgo. OpenAPI consumers should treat replies as the same shape.
+ */
+export const publicCommentSchema: z.ZodObject<{
+	id: z.ZodString;
+	authorName: z.ZodString;
+	isRegisteredUser: z.ZodBoolean;
+	body: z.ZodString;
+	parentId: z.ZodNullable<z.ZodString>;
+	createdAt: z.ZodString;
+	replies: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+}> = z
+	.object({
+		id: z.string(),
+		authorName: z.string(),
+		isRegisteredUser: z.boolean(),
+		body: z.string(),
+		parentId: z.string().nullable(),
+		createdAt: z.string(),
+		replies: z.array(z.any()).optional(),
+	})
+	.meta({ id: "PublicComment" });
+
+/** Admin comment with full details */
+export const commentSchema = z
+	.object({
+		id: z.string(),
+		collection: z.string(),
+		contentId: z.string(),
+		authorName: z.string(),
+		authorEmail: z.string(),
+		body: z.string(),
+		status: commentStatusValues,
+		parentId: z.string().nullable(),
+		ipHash: z.string().nullable(),
+		createdAt: z.string(),
+		updatedAt: z.string(),
+	})
+	.meta({ id: "Comment" });
+
+export const publicCommentListResponseSchema = z
+	.object({
+		items: z.array(publicCommentSchema),
+		nextCursor: z.string().optional(),
+		total: z.number().int(),
+	})
+	.meta({ id: "PublicCommentListResponse" });
+
+export const adminCommentListResponseSchema = z
+	.object({
+		items: z.array(commentSchema),
+		nextCursor: z.string().optional(),
+	})
+	.meta({ id: "AdminCommentListResponse" });
+
+export const commentCountsResponseSchema = z
+	.object({
+		pending: z.number().int(),
+		approved: z.number().int(),
+		spam: z.number().int(),
+		trash: z.number().int(),
+	})
+	.meta({ id: "CommentCountsResponse" });
+
+export const commentBulkResponseSchema = z
+	.object({ affected: z.number().int() })
+	.meta({ id: "CommentBulkResponse" });

package/src/api/schemas/common.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Role level
+// ---------------------------------------------------------------------------
+
+/** Valid role level values */
+export const VALID_ROLE_LEVELS = new Set([10, 20, 30, 40, 50]);
+
+/** Role level — coerces string/number to valid RoleLevel (10|20|30|40|50) */
+export const roleLevel = z.coerce
+	.number()
+	.int()
+	.refine((n): n is 10 | 20 | 30 | 40 | 50 => VALID_ROLE_LEVELS.has(n), {
+		message: "Invalid role level. Must be 10, 20, 30, 40, or 50",
+	});
+
+// ---------------------------------------------------------------------------
+// Pagination
+// ---------------------------------------------------------------------------
+
+/** Pagination query params — cursor-based */
+export const cursorPaginationQuery = z
+	.object({
+		cursor: z.string().optional().meta({ description: "Opaque cursor for pagination" }),
+		limit: z.coerce.number().int().min(1).max(100).optional().default(50).meta({
+			description: "Maximum number of items to return (1-100, default 50)",
+		}),
+	})
+	.meta({ id: "CursorPaginationQuery" });
+
+/** Pagination query params — offset-based */
+export const offsetPaginationQuery = z
+	.object({
+		limit: z.coerce.number().int().min(1).max(100).optional().default(50),
+		offset: z.coerce.number().int().min(0).optional().default(0),
+	})
+	.meta({ id: "OffsetPaginationQuery" });
+
+// ---------------------------------------------------------------------------
+// Shared primitives
+// ---------------------------------------------------------------------------
+
+/** Slug pattern: lowercase letters, digits, underscores; starts with letter */
+export const slugPattern = /^[a-z][a-z0-9_]*$/;
+
+/** Matches http(s) scheme at start of URL */
+const HTTP_SCHEME_RE = /^https?:\/\//i;
+
+/** Validates that a URL string uses http or https scheme. Rejects javascript:/data: URI XSS vectors. */
+export const httpUrl = z
+	.string()
+	.url()
+	.refine((url) => HTTP_SCHEME_RE.test(url), "URL must use http or https");
+
+/** BCP 47 locale code — language with optional script/region subtags (e.g. en, en-US, pt-BR, es-419, zh-Hant) */
+export const localeCode = z
+	.string()
+	.regex(/^[a-z]{2,3}(-[a-z0-9]{2,8})*$/i, "Invalid locale code")
+	.transform((v) => v.toLowerCase());
+
+// ---------------------------------------------------------------------------
+// OpenAPI: Shared response schemas
+// ---------------------------------------------------------------------------
+
+/** Standard API error response */
+export const apiErrorSchema = z
+	.object({
+		error: z.object({
+			code: z.string().meta({ description: "Machine-readable error code", example: "NOT_FOUND" }),
+			message: z.string().meta({ description: "Human-readable error message" }),
+		}),
+	})
+	.meta({ id: "ApiError" });
+
+/** Wrap a data schema in the standard success envelope: { data: T } */
+export function successEnvelope<T extends z.ZodType>(dataSchema: T) {
+	return z.object({ data: dataSchema });
+}
+
+/** Standard delete response */
+export const deleteResponseSchema = z.object({ deleted: z.literal(true) }).meta({
+	id: "DeleteResponse",
+});
+
+/** Standard count response */
+export const countResponseSchema = z
+	.object({ count: z.number().int().min(0) })
+	.meta({ id: "CountResponse" });