@xexr/blog-platform 1.0.7 → 1.0.8

package/dist/lib/cors.ts

@@ -0,0 +1,243 @@
+/**
+ * CORS configuration for blog platform API endpoints
+ * 
+ * This provides centralized CORS handling with security best practices
+ * for cross-origin requests from Bloggy core applications.
+ */
+
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
+import { getAPISecurityHeaders, type SecurityConfig } from "./security-headers";
+
+/**
+ * CORS configuration interface
+ */
+export interface CorsConfig {
+  /** Allowed origins (default: allow configured domains only) */
+  allowedOrigins?: string[];
+
+  /** Allow all origins with wildcard (default: false for security) */
+  allowWildcard?: boolean;
+
+  /** Allow credentials to be sent (default: false) */
+  allowCredentials?: boolean;
+
+  /** Cache preflight requests for this many seconds (default: 86400 = 24 hours) */
+  maxAge?: number;
+
+  /** Security headers configuration */
+  securityConfig?: SecurityConfig;
+}
+
+/**
+ * Default CORS configuration for blog platform
+ */
+const DEFAULT_CORS_CONFIG: Required<CorsConfig> = {
+  allowedOrigins: [
+    "http://localhost:3000",    // Development Bloggy core
+    "https://localhost:3000",   // Development Bloggy core (HTTPS)
+    "http://127.0.0.1:3000",    // Alternative localhost
+    "https://127.0.0.1:3000",   // Alternative localhost (HTTPS)
+  ],
+  allowWildcard: false,         // Security: don't allow all origins by default
+  allowCredentials: false,      // Security: don't allow credentials by default
+  maxAge: 86400,               // Cache preflight for 24 hours
+  securityConfig: {},           // Default security configuration
+};
+
+/**
+ * Get CORS configuration from environment or defaults
+ */
+function getCorsConfig(): Required<CorsConfig> {
+  const envOrigins = process.env.BLOG_PLATFORM_ALLOWED_ORIGINS;
+  const allowWildcard = process.env.BLOG_PLATFORM_ALLOW_WILDCARD === "true";
+  const allowCredentials = process.env.BLOG_PLATFORM_ALLOW_CREDENTIALS === "true";
+  
+  return {
+    ...DEFAULT_CORS_CONFIG,
+    allowedOrigins: envOrigins ? envOrigins.split(",").map(origin => origin.trim()) : DEFAULT_CORS_CONFIG.allowedOrigins,
+    allowWildcard,
+    allowCredentials,
+  };
+}
+
+/**
+ * Check if an origin is allowed based on CORS configuration
+ */
+function isOriginAllowed(origin: string | null, config: Required<CorsConfig>): boolean {
+  if (!origin) {
+    return false;
+  }
+  
+  // If wildcard is enabled, allow all origins
+  if (config.allowWildcard) {
+    return true;
+  }
+  
+  // Check against allowed origins list
+  return config.allowedOrigins.includes(origin);
+}
+
+/**
+ * Get CORS headers for a given request and configuration
+ */
+function getCorsHeaders(request: NextRequest, config: Required<CorsConfig>): Record<string, string> {
+  const origin = request.headers.get("origin");
+  const headers: Record<string, string> = {};
+  
+  // Set allowed origin
+  if (config.allowWildcard) {
+    headers["Access-Control-Allow-Origin"] = "*";
+  } else if (origin && isOriginAllowed(origin, config)) {
+    headers["Access-Control-Allow-Origin"] = origin;
+  }
+  
+  // Set credentials if allowed (only when not using wildcard)
+  if (config.allowCredentials && !config.allowWildcard) {
+    headers["Access-Control-Allow-Credentials"] = "true";
+  }
+  
+  // Always include Vary header when not using wildcard
+  if (!config.allowWildcard) {
+    headers.Vary = "Origin";
+  }
+  
+  return headers;
+}
+
+/**
+ * Get preflight CORS headers for OPTIONS requests
+ */
+function getPreflightHeaders(
+  request: NextRequest, 
+  config: Required<CorsConfig>,
+  allowedMethods: string[],
+  allowedHeaders: string[]
+): Record<string, string> {
+  const corsHeaders = getCorsHeaders(request, config);
+  
+  return {
+    ...corsHeaders,
+    "Access-Control-Allow-Methods": allowedMethods.join(", "),
+    "Access-Control-Allow-Headers": allowedHeaders.join(", "),
+    "Access-Control-Max-Age": config.maxAge.toString(),
+  };
+}
+
+/**
+ * Standard allowed headers for blog platform API endpoints
+ */
+export const STANDARD_ALLOWED_HEADERS = [
+  "Content-Type",
+  "X-Bloggy-Version", 
+  "X-Idempotency-Key",
+  "Authorization",
+  "X-Requested-With",
+];
+
+/**
+ * Create CORS-enabled response for API endpoints
+ */
+export function createCorsResponse<T>(
+  request: NextRequest,
+  data: T,
+  options: {
+    status?: number;
+    headers?: Record<string, string>;
+    corsConfig?: CorsConfig;
+  } = {}
+): NextResponse<T> {
+  const { status = 200, headers = {}, corsConfig = {} } = options;
+  const config = { ...getCorsConfig(), ...corsConfig };
+
+  const corsHeaders = getCorsHeaders(request, config);
+  const securityHeaders = getAPISecurityHeaders(request, config.securityConfig);
+
+  const responseHeaders = {
+    "Content-Type": "application/json",
+    ...corsHeaders,
+    ...securityHeaders,
+    ...headers,
+  };
+
+  return NextResponse.json(data, {
+    status,
+    headers: responseHeaders,
+  });
+}
+
+/**
+ * Handle CORS preflight OPTIONS requests
+ */
+export function handleCorsOptions(
+  request: NextRequest,
+  allowedMethods: string[],
+  options: {
+    allowedHeaders?: string[];
+    corsConfig?: CorsConfig;
+  } = {}
+): NextResponse {
+  const { allowedHeaders = STANDARD_ALLOWED_HEADERS, corsConfig = {} } = options;
+  const config = { ...getCorsConfig(), ...corsConfig };
+
+  const origin = request.headers.get("origin");
+
+  // Check if origin is allowed
+  if (origin && !config.allowWildcard && !isOriginAllowed(origin, config)) {
+    const securityHeaders = getAPISecurityHeaders(request, config.securityConfig);
+    return new NextResponse(null, {
+      status: 403,
+      headers: {
+        "Content-Type": "text/plain",
+        ...securityHeaders,
+      },
+    });
+  }
+
+  const preflightHeaders = getPreflightHeaders(
+    request,
+    config,
+    [...allowedMethods, "OPTIONS"],
+    allowedHeaders
+  );
+
+  const securityHeaders = getAPISecurityHeaders(request, config.securityConfig);
+
+  return new NextResponse(null, {
+    status: 200,
+    headers: {
+      ...preflightHeaders,
+      ...securityHeaders,
+    },
+  });
+}
+
+/**
+ * Middleware to add CORS headers to any response
+ */
+export function addCorsHeaders(
+  request: NextRequest,
+  response: NextResponse,
+  corsConfig: CorsConfig = {}
+): NextResponse {
+  const config = { ...getCorsConfig(), ...corsConfig };
+  const corsHeaders = getCorsHeaders(request, config);
+  const securityHeaders = getAPISecurityHeaders(request, config.securityConfig);
+
+  // Add CORS and security headers to existing response
+  Object.entries({ ...corsHeaders, ...securityHeaders }).forEach(([key, value]) => {
+    response.headers.set(key, value);
+  });
+
+  return response;
+}
+
+/**
+ * Check if request origin is allowed (utility for manual CORS checking)
+ */
+export function checkOriginAllowed(request: NextRequest, corsConfig: CorsConfig = {}): boolean {
+  const config = { ...getCorsConfig(), ...corsConfig };
+  const origin = request.headers.get("origin");
+  
+  return isOriginAllowed(origin, config);
+}

package/dist/lib/database.ts

@@ -0,0 +1,277 @@
+/**
+ * Database interface for blog platform storage
+ *
+ * This provides a simple interface for storing published articles
+ * without coupling to any specific database implementation.
+ * Customers can implement this interface with their preferred database.
+ */
+
+import type { PublishedArticle, PublishResult } from "@/types/contracts";
+
+export interface BlogPlatformStorage {
+  /**
+   * Store a published article
+   */
+  saveArticle(
+    article: PublishedArticle,
+    idempotencyKey: string,
+  ): Promise<PublishResult>;
+
+  /**
+   * Get an article by slug
+   */
+  getArticle(slug: string): Promise<PublishedArticle | null>;
+
+  /**
+   * List all published articles
+   */
+  listArticles(options?: {
+    limit?: number;
+    offset?: number;
+    sortBy?: "publishedAt" | "updatedAt";
+    order?: "asc" | "desc";
+  }): Promise<{
+    articles: PublishedArticle[];
+    total: number;
+  }>;
+
+  /**
+   * Remove an article by slug
+   */
+  removeArticle(slug: string, idempotencyKey: string): Promise<PublishResult>;
+
+  /**
+   * Check if an operation was already performed (idempotency)
+   */
+  checkIdempotency(idempotencyKey: string): Promise<PublishResult | null>;
+
+  /**
+   * Store the result of an operation for idempotency
+   */
+  storeOperationResult(
+    idempotencyKey: string,
+    result: PublishResult,
+  ): Promise<void>;
+}
+
+/**
+ * Default in-memory storage implementation for development/testing
+ * IMPORTANT: This is not suitable for production use!
+ */
+export class InMemoryStorage implements BlogPlatformStorage {
+  private articles = new Map<string, PublishedArticle>();
+  private operations = new Map<string, PublishResult>();
+
+  async saveArticle(
+    article: PublishedArticle,
+    idempotencyKey: string,
+  ): Promise<PublishResult> {
+    // Check for existing idempotency key
+    const existingResult = await this.checkIdempotency(idempotencyKey);
+
+    // CRITICAL FIX: Allow republish after unpublish
+    // If we found a cached operation result AND it was successful,
+    // check if the article still exists. If it was removed (unpublished),
+    // proceed with the save to allow republishing.
+    if (existingResult) {
+      if (existingResult.success) {
+        // Check if article still exists by finding it in the articles map
+        const articleStillExists = Array.from(this.articles.values()).some(
+          (a) => a.id === article.id,
+        );
+
+        // If article was removed, allow republish by not returning cached result
+        if (!articleStillExists) {
+          // Article was unpublished - proceed with save
+        } else {
+          // Article still exists - this is a true duplicate
+          return existingResult;
+        }
+      } else {
+        // Failed operations are always returned as-is
+        return existingResult;
+      }
+    }
+
+    // Validate slug uniqueness
+    if (this.articles.has(article.slug)) {
+      const result: PublishResult = {
+        success: false,
+        error: {
+          code: "PUB003",
+          message: "This URL is already in use. Please choose another.",
+        },
+        idempotencyKey,
+      };
+      await this.storeOperationResult(idempotencyKey, result);
+      return result;
+    }
+
+    // Store the article
+    this.articles.set(article.slug, article);
+
+    const result: PublishResult = {
+      success: true,
+      url: `/${article.slug}`,
+      platformPostId: article.id,
+      publishedAt: article.publishedAt,
+      idempotencyKey,
+    };
+
+    await this.storeOperationResult(idempotencyKey, result);
+    return result;
+  }
+
+  async getArticle(slug: string): Promise<PublishedArticle | null> {
+    return this.articles.get(slug) ?? null;
+  }
+
+  async listArticles(
+    options: {
+      limit?: number;
+      offset?: number;
+      sortBy?: "publishedAt" | "updatedAt";
+      order?: "asc" | "desc";
+    } = {},
+  ): Promise<{ articles: PublishedArticle[]; total: number }> {
+    const {
+      limit = 10,
+      offset = 0,
+      sortBy = "publishedAt",
+      order = "desc",
+    } = options;
+
+    const allArticles = Array.from(this.articles.values());
+
+    // Sort articles
+    allArticles.sort((a, b) => {
+      const aValue = new Date(a[sortBy]).getTime();
+      const bValue = new Date(b[sortBy]).getTime();
+      return order === "desc" ? bValue - aValue : aValue - bValue;
+    });
+
+    // Apply pagination
+    const articles = allArticles.slice(offset, offset + limit);
+
+    return {
+      articles,
+      total: allArticles.length,
+    };
+  }
+
+  async removeArticle(
+    slug: string,
+    idempotencyKey: string,
+  ): Promise<PublishResult> {
+    // Check for existing idempotency key
+    const existingResult = await this.checkIdempotency(idempotencyKey);
+
+    // CRITICAL FIX: Allow re-unpublish after republish
+    // If we found a cached operation result AND it was successful,
+    // check if the article NOW exists. If it was republished,
+    // proceed with the removal to allow re-unpublishing.
+    if (existingResult) {
+      if (existingResult.success) {
+        // Check if article exists NOW (might have been republished)
+        const articleExists = this.articles.has(slug);
+
+        // If article EXISTS, it was republished - allow re-unpublish
+        if (articleExists) {
+          // Article was republished - proceed with removal
+        } else {
+          // Article still removed - this is a true duplicate
+          return existingResult;
+        }
+      } else {
+        // Failed operations are always returned as-is
+        return existingResult;
+      }
+    }
+
+    // Check if article exists
+    if (!this.articles.has(slug)) {
+      const result: PublishResult = {
+        success: false,
+        error: {
+          code: "PUB007",
+          message: "Article not found",
+        },
+        idempotencyKey,
+      };
+      await this.storeOperationResult(idempotencyKey, result);
+      return result;
+    }
+
+    // Remove the article
+    this.articles.delete(slug);
+
+    const result: PublishResult = {
+      success: true,
+      idempotencyKey,
+    };
+
+    await this.storeOperationResult(idempotencyKey, result);
+    return result;
+  }
+
+  async checkIdempotency(
+    idempotencyKey: string,
+  ): Promise<PublishResult | null> {
+    return this.operations.get(idempotencyKey) ?? null;
+  }
+
+  async storeOperationResult(
+    idempotencyKey: string,
+    result: PublishResult,
+  ): Promise<void> {
+    this.operations.set(idempotencyKey, result);
+  }
+}
+
+type GlobalWithStorage = typeof globalThis & {
+  __BLOG_PLATFORM_STORAGE__?: BlogPlatformStorage;
+  __BLOG_PLATFORM_STORAGE_WARNED__?: boolean;
+};
+
+function warnAboutEphemeralStorage(): void {
+  const globalRef = globalThis as GlobalWithStorage;
+  if (globalRef.__BLOG_PLATFORM_STORAGE_WARNED__) {
+    return;
+  }
+
+  globalRef.__BLOG_PLATFORM_STORAGE_WARNED__ = true;
+
+  const message =
+    "Blog platform: No storage provider configured. Falling back to in-memory storage (data is not persisted).";
+  if (process.env.NODE_ENV === "production") {
+    console.error(
+      `${message} Call initBlogPlatform({ storage: /* your persistent adapter */ }) to avoid data loss.`,
+    );
+  } else {
+    console.warn(message);
+  }
+}
+
+function getGlobalStorage(): BlogPlatformStorage {
+  const globalRef = globalThis as GlobalWithStorage;
+  if (!globalRef.__BLOG_PLATFORM_STORAGE__) {
+    warnAboutEphemeralStorage();
+    globalRef.__BLOG_PLATFORM_STORAGE__ = new InMemoryStorage();
+  }
+  const storage = globalRef.__BLOG_PLATFORM_STORAGE__;
+  if (!storage) {
+    // This should be unreachable because we set it above,
+    // but the guard satisfies strict type checking without assertions.
+    throw new Error("Blog platform storage not initialized");
+  }
+  return storage;
+}
+
+export function getStorage(): BlogPlatformStorage {
+  return getGlobalStorage();
+}
+
+export function setStorage(storage: BlogPlatformStorage): void {
+  const globalRef = globalThis as GlobalWithStorage;
+  globalRef.__BLOG_PLATFORM_STORAGE__ = storage;
+}

package/dist/lib/init.ts

@@ -0,0 +1,186 @@
+/**
+ * Initialization utilities for the blog platform package
+ *
+ * This module provides convenient setup functions for customers
+ * to configure authentication, storage, and other platform features.
+ */
+
+import {
+  setAuthConfig,
+  type AuthConfig,
+  NoAuth,
+  EnvAuth,
+} from "./auth";
+import { setStorage, type BlogPlatformStorage } from "./database";
+import {
+  autoConfigureRateLimit,
+  configureRateLimit,
+  type RateLimitConfig,
+} from "./ratelimit";
+
+declare global {
+  // Using `var` here intentionally to declare a global on Node's globalThis
+  // across module boundaries. This is not a directive; remove stale disable.
+  var __BLOG_PLATFORM_INITIALISED__: boolean | undefined;
+}
+
+/**
+ * Configuration options for blog platform initialization
+ */
+export interface BlogPlatformConfig {
+  /** Authentication configuration (REQUIRED) */
+  auth: AuthConfig;
+
+  /** Custom storage implementation */
+  storage?: BlogPlatformStorage;
+
+  /** Custom rate limiting configuration */
+  rateLimit?: RateLimitConfig;
+
+  /** Whether to automatically configure rate limiting from environment */
+  autoRateLimit?: boolean;
+}
+
+/**
+ * Initialize the blog platform with custom configuration
+ *
+ * This should be called once during your app startup, typically in:
+ * - Next.js: middleware.ts or layout.tsx
+ * - Express: app startup
+ * - Other frameworks: main entry point
+ *
+ * @param config - Configuration options (auth is REQUIRED)
+ *
+ * @example
+ * ```typescript
+ * // Environment-based API key authentication
+ * initBlogPlatform({
+ *   auth: new EnvAuth(), // Reads from BLOG_PLATFORM_API_KEYS
+ * });
+ *
+ * // Custom environment variable
+ * initBlogPlatform({
+ *   auth: new EnvAuth("MY_BLOG_API_KEYS"),
+ * });
+ *
+ * // Custom authentication provider
+ * initBlogPlatform({
+ *   auth: new CustomAuthProvider(),
+ *   storage: new PostgresStorage(connectionString),
+ *   rateLimit: {
+ *     redisUrl: "https://...",
+ *     redisToken: "...",
+ *     requestsPerMinute: 10
+ *   }
+ * });
+ *
+ * // Disable rate limiting for testing
+ * initBlogPlatform({
+ *   auth: new NoAuth(), // Development only!
+ *   autoRateLimit: false
+ * });
+ * ```
+ */
+export function initBlogPlatform(config: BlogPlatformConfig): void {
+  const {
+    auth,
+    storage,
+    rateLimit,
+    autoRateLimit = true,
+  } = config;
+
+  // Validate required configuration
+  if (!auth) {
+    throw new Error(
+      "Blog platform initialization failed: 'auth' is required.\n" +
+      "Example: initBlogPlatform({ auth: new EnvAuth() })\n" +
+      "See https://github.com/xexr/blog-platform#authentication for more details."
+    );
+  }
+
+  // Set up authentication (REQUIRED)
+  console.log("Blog platform: Setting up authentication");
+  setAuthConfig(auth);
+
+  // Set up rate limiting
+  if (rateLimit) {
+    console.log("Blog platform: Using custom rate limiting configuration");
+    configureRateLimit(rateLimit);
+  } else if (autoRateLimit) {
+    console.log(
+      "Blog platform: Auto-configuring rate limiting from environment",
+    );
+    autoConfigureRateLimit();
+  } else {
+    console.log("Blog platform: Rate limiting disabled");
+  }
+
+  // Set up storage
+  if (storage) {
+    console.log("Blog platform: Using custom storage provider");
+    setStorage(storage);
+  } else {
+    console.log(
+      "Blog platform: Using default in-memory storage (not suitable for production)",
+    );
+  }
+
+  console.log("Blog platform initialized successfully");
+  globalThis.__BLOG_PLATFORM_INITIALISED__ = true;
+}
+
+/**
+ * Initialize the blog platform only once per process.
+ * Safe to call from multiple modules (e.g., layout + API routes).
+ *
+ * @param config - Configuration options (auth is REQUIRED)
+ */
+export function initBlogPlatformOnce(config: BlogPlatformConfig): void {
+  if (globalThis.__BLOG_PLATFORM_INITIALISED__) {
+    console.log("Blog platform: Already initialized, skipping");
+    return;
+  }
+  console.log("Blog platform: Initializing blog platform once");
+  initBlogPlatform(config);
+}
+
+/**
+ * Quick setup for development/testing
+ * WARNING: Disables authentication - never use in production!
+ * Uses NoAuth (accepts all requests), in-memory storage, and disables rate limiting
+ */
+export function initBlogPlatformDev(): void {
+  initBlogPlatform({
+    auth: new NoAuth(),
+    autoRateLimit: false
+  });
+  console.log(
+    "Blog platform: Development mode enabled (no auth, in-memory storage, no rate limiting)",
+  );
+}
+
+/**
+ * Production setup with environment-based API keys and rate limiting
+ * Requires BLOG_PLATFORM_API_KEYS (or custom env var), UPSTASH_REDIS_REST_URL,
+ * and UPSTASH_REDIS_REST_TOKEN environment variables
+ *
+ * @param apiKeysEnvVar - Optional custom environment variable name for API keys (default: BLOG_PLATFORM_API_KEYS)
+ */
+export function initBlogPlatformProd(apiKeysEnvVar?: string): void {
+  const envVar = apiKeysEnvVar ?? "BLOG_PLATFORM_API_KEYS";
+
+  if (!process.env[envVar]) {
+    throw new Error(
+      `Missing required environment variable: ${envVar}. ` +
+        "Set this to a comma-separated list of API keys for blog platform authentication.",
+    );
+  }
+
+  initBlogPlatform({
+    auth: new EnvAuth(envVar),
+    autoRateLimit: true,
+  });
+  console.log(
+    "Blog platform: Production mode enabled (environment-based auth, rate limiting)",
+  );
+}