headroom-cms 0.1.1

package/src/image.ts

@@ -0,0 +1,62 @@
+/**
+ * Image Infrastructure
+ *
+ * Sharp-based image transformation Lambda with HMAC-signed URLs.
+ * Supports dev mode (Node.js source) and package mode (pre-bundled handler).
+ */
+
+import path from "path";
+import type { StorageResources } from "./storage.js";
+
+export interface ImageArgs {
+  contentBucket: StorageResources["contentBucket"];
+  pkgRoot: string;
+  dev?: {
+    /** SST handler string, e.g. "packages/image-lambda/index.handler" */
+    handler: string;
+  };
+}
+
+export function createImage(name: string, args: ImageArgs) {
+  const imageSigningSecret = new sst.Secret(`${name}ImageSigningSecret`);
+
+  let imageLambda: sst.aws.Function;
+  if (args.dev) {
+    imageLambda = new sst.aws.Function(`${name}ImageLambda`, {
+      handler: args.dev.handler,
+      runtime: "nodejs22.x",
+      architecture: "arm64",
+      timeout: "30 seconds",
+      memory: "1536 MB",
+      url: {
+        authorization: "iam",
+      },
+      environment: {
+        CONTENT_BUCKET: args.contentBucket.name,
+        IMAGE_SIGNING_SECRET: imageSigningSecret.value,
+      },
+      link: [args.contentBucket, imageSigningSecret],
+    });
+  } else {
+    imageLambda = new sst.aws.Function(`${name}ImageLambda`, {
+      bundle: path.join(args.pkgRoot, "lambda/image-lambda"),
+      handler: "index.handler",
+      runtime: "nodejs22.x",
+      architecture: "arm64",
+      timeout: "30 seconds",
+      memory: "1536 MB",
+      url: {
+        authorization: "iam",
+      },
+      environment: {
+        CONTENT_BUCKET: args.contentBucket.name,
+        IMAGE_SIGNING_SECRET: imageSigningSecret.value,
+      },
+      link: [args.contentBucket, imageSigningSecret],
+    });
+  }
+
+  return { imageSigningSecret, imageLambda };
+}
+
+export type ImageResources = ReturnType<typeof createImage>;

package/src/index.ts

@@ -0,0 +1,216 @@
+/**
+ * Headroom CMS — SST Component
+ *
+ * A single HeadroomCMS class that provisions the full CMS infrastructure:
+ * DynamoDB tables, S3, Cognito, Lambda functions, CloudFront, and Admin UI.
+ */
+
+import fs from "fs";
+import path from "path";
+import { createStorage } from "./storage.js";
+import { createAuth } from "./auth.js";
+import { createWebhooks } from "./webhooks.js";
+import { createImage } from "./image.js";
+import { createApi } from "./api.js";
+import { createCdn } from "./cdn.js";
+import { createAdminSite } from "./admin-site.js";
+
+/**
+ * Resolve the headroom-cms package root directory.
+ *
+ * We can't rely on import.meta.url because SST's esbuild bundler inlines
+ * all config code into a single .mjs file under .sst/platform/, which makes
+ * import.meta.url point to the bundled output instead of the original source.
+ *
+ * Instead, walk up from process.cwd() looking for node_modules/headroom-cms.
+ */
+function resolvePkgRoot(): string {
+  let dir = process.cwd();
+  while (true) {
+    const candidate = path.join(dir, "node_modules", "headroom-cms");
+    if (fs.existsSync(candidate)) {
+      return fs.realpathSync(candidate);
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    "Could not find headroom-cms package in node_modules. " +
+    "Ensure it is installed as a dependency.",
+  );
+}
+
+// Re-export resource types for consumers
+export type { StorageResources } from "./storage.js";
+export type { AuthResources } from "./auth.js";
+export type { WebhookResources } from "./webhooks.js";
+export type { ImageResources } from "./image.js";
+export type { ApiResources } from "./api.js";
+export type { CdnResources } from "./cdn.js";
+export type { AdminSiteResources } from "./admin-site.js";
+
+export interface HeadroomCMSArgs {
+  /**
+   * Email address for sending admin invitations and password resets.
+   * Must be verified in SES (Headroom creates the SES identity automatically,
+   * but you must click the verification link sent to this address).
+   */
+  senderEmail: string;
+
+  /**
+   * Custom domain for the CDN (API endpoint).
+   * If not provided, uses the default CloudFront domain.
+   */
+  domain?: {
+    name: string;
+    /** ACM certificate ARN (must be in us-east-1 for CloudFront) */
+    certificateArn: string;
+  };
+
+  /**
+   * Custom domain for the admin UI.
+   * If not provided, uses the default CloudFront domain.
+   */
+  adminDomain?: {
+    name: string;
+    /** ACM certificate ARN (must be in us-east-1 for CloudFront) */
+    certificateArn: string;
+  };
+
+  /**
+   * CloudFront price class.
+   * @default "PriceClass_100" (US, Canada, Europe)
+   */
+  priceClass?: "PriceClass_100" | "PriceClass_200" | "PriceClass_All";
+
+  /**
+   * API cache TTL in seconds.
+   * @default 3600 (1 hour)
+   */
+  apiCacheTtl?: number;
+
+  /**
+   * Cognito password policy overrides.
+   */
+  passwordPolicy?: {
+    minimumLength?: number;
+    requireLowercase?: boolean;
+    requireUppercase?: boolean;
+    requireNumbers?: boolean;
+    requireSymbols?: boolean;
+  };
+
+  /**
+   * Development overrides. Used when developing Headroom itself.
+   * When set, Lambda functions are compiled from source (requires Go + Node.js).
+   */
+  dev?: {
+    /** Go source path for API Lambda, e.g. "packages/api" */
+    apiHandler: string;
+    /** Go source path for webhook worker, e.g. "packages/webhook-worker" */
+    webhookWorkerHandler: string;
+    /** SST handler for custom message function, e.g. "packages/functions/custom-message.handler" */
+    customMessageHandler: string;
+    /** SST handler for image Lambda, e.g. "packages/image-lambda/index.handler" */
+    imageLambdaHandler: string;
+    /** Path to admin UI source, e.g. "packages/admin" */
+    adminPath: string;
+  };
+}
+
+export class HeadroomCMS {
+  public readonly apiUrl: $util.Output<string>;
+  public readonly cdnUrl: $util.Output<string>;
+  public readonly adminUrl: $util.Output<string>;
+  public readonly userPoolId: $util.Output<string>;
+  public readonly userPoolClientId: $util.Output<string>;
+
+  public readonly outputs: Record<string, $util.Output<string>>;
+
+  constructor(name: string, args: HeadroomCMSArgs) {
+    // Only need pkgRoot for package mode (pre-built artifacts)
+    const pkgRoot = args.dev ? "" : resolvePkgRoot();
+
+    // 1. Storage (DynamoDB tables, S3 bucket, KVS)
+    const storage = createStorage(name);
+
+    // 2. Auth (Cognito, SES, custom message Lambda)
+    const auth = createAuth(name, {
+      senderEmail: args.senderEmail,
+      passwordPolicy: args.passwordPolicy,
+      pkgRoot,
+      dev: args.dev
+        ? { handler: args.dev.customMessageHandler }
+        : undefined,
+    });
+
+    // 3. Webhooks (DynamoDB tables, SQS queues, worker Lambda)
+    const webhooks = createWebhooks(name, {
+      sites: storage.sites,
+      pkgRoot,
+      dev: args.dev
+        ? { handler: args.dev.webhookWorkerHandler }
+        : undefined,
+    });
+
+    // 4. Image Lambda (Sharp transform with HMAC-signed URLs)
+    const image = createImage(name, {
+      contentBucket: storage.contentBucket,
+      pkgRoot,
+      dev: args.dev
+        ? { handler: args.dev.imageLambdaHandler }
+        : undefined,
+    });
+
+    // 5. API Lambda (Go handler with access to all resources)
+    const api = createApi(name, {
+      storage,
+      auth,
+      webhooks,
+      image,
+      pkgRoot,
+      dev: args.dev
+        ? { handler: args.dev.apiHandler }
+        : undefined,
+    });
+
+    // 6. CDN (CloudFront distribution + edge functions)
+    const cdn = createCdn(name, {
+      api,
+      image,
+      contentBucket: storage.contentBucket,
+      kvs: storage.kvs,
+      priceClass: args.priceClass,
+      apiCacheTtl: args.apiCacheTtl,
+      domain: args.domain,
+    });
+
+    // 7. Admin UI (static site)
+    const admin = createAdminSite(name, {
+      api,
+      cdn,
+      auth,
+      pkgRoot,
+      dev: args.dev
+        ? { adminPath: args.dev.adminPath }
+        : undefined,
+      domain: args.adminDomain,
+    });
+
+    // Expose outputs
+    this.apiUrl = api.api.url;
+    this.cdnUrl = cdn.url;
+    this.adminUrl = admin.url;
+    this.userPoolId = auth.userPool.id;
+    this.userPoolClientId = auth.userPoolClient.id;
+
+    this.outputs = {
+      api: api.api.url,
+      cdn: cdn.url,
+      admin: admin.url,
+      userPoolId: auth.userPool.id,
+      userPoolClientId: auth.userPoolClient.id,
+    };
+  }
+}

package/src/sst-env.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Minimal ambient type declarations for SST v3 and Pulumi globals.
+ *
+ * In the dev repo, SST provides these as runtime globals via .sst/platform/.
+ * This file declares just enough type information for tsc compilation.
+ * At runtime, SST provides the full implementations.
+ */
+
+// ---------------------------------------------------------------------------
+// Pulumi Output type (minimal)
+// ---------------------------------------------------------------------------
+interface PulumiOutput<T> {
+  apply<U>(fn: (value: T) => U | PulumiOutput<U> | Promise<U>): PulumiOutput<U>;
+}
+
+// ---------------------------------------------------------------------------
+// SST namespace
+// ---------------------------------------------------------------------------
+declare namespace sst {
+  class Secret {
+    constructor(name: string, ...args: any[]);
+    value: PulumiOutput<string>;
+  }
+
+  namespace aws {
+    class Dynamo {
+      constructor(name: string, args: any, opts?: any);
+      name: PulumiOutput<string>;
+      arn: PulumiOutput<string>;
+    }
+
+    class Bucket {
+      constructor(name: string, args?: any, opts?: any);
+      name: PulumiOutput<string>;
+      arn: PulumiOutput<string>;
+    }
+
+    class Function {
+      constructor(name: string, args: any, opts?: any);
+      url: PulumiOutput<string>;
+      name: PulumiOutput<string>;
+      arn: PulumiOutput<string>;
+    }
+
+    class CognitoUserPool {
+      constructor(name: string, args?: any, opts?: any);
+      id: PulumiOutput<string>;
+      arn: PulumiOutput<string>;
+      addClient(name: string, args?: any): CognitoUserPoolClient;
+    }
+
+    class CognitoUserPoolClient {
+      id: PulumiOutput<string>;
+    }
+
+    class Queue {
+      constructor(name: string, args?: any, opts?: any);
+      url: PulumiOutput<string>;
+      arn: PulumiOutput<string>;
+      subscribe(handler: any, opts?: any): void;
+    }
+
+    class StaticSite {
+      constructor(name: string, args?: any, opts?: any);
+      url: PulumiOutput<string>;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// AWS (Pulumi) namespace
+// ---------------------------------------------------------------------------
+declare namespace aws {
+  function getRegionOutput(): { name: PulumiOutput<string> };
+
+  namespace cloudfront {
+    class KeyValueStore {
+      constructor(name: string, args?: any, opts?: any);
+      arn: PulumiOutput<string>;
+      id: PulumiOutput<string>;
+    }
+
+    class Function {
+      constructor(name: string, args?: any, opts?: any);
+      arn: PulumiOutput<string>;
+    }
+
+    class CachePolicy {
+      constructor(name: string, args?: any, opts?: any);
+      id: PulumiOutput<string>;
+    }
+
+    class OriginRequestPolicy {
+      constructor(name: string, args?: any, opts?: any);
+      id: PulumiOutput<string>;
+    }
+
+    class OriginAccessControl {
+      constructor(name: string, args?: any, opts?: any);
+      id: PulumiOutput<string>;
+    }
+
+    class Distribution {
+      constructor(name: string, args?: any, opts?: any);
+      arn: PulumiOutput<string>;
+      domainName: PulumiOutput<string>;
+    }
+  }
+
+  namespace ses {
+    class EmailIdentity {
+      constructor(name: string, args?: any, opts?: any);
+      arn: PulumiOutput<string>;
+    }
+  }
+
+  namespace lambda {
+    class Permission {
+      constructor(name: string, args?: any, opts?: any);
+    }
+
+    class EventSourceMapping {
+      constructor(name: string, args?: any, opts?: any);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SST globals
+// ---------------------------------------------------------------------------
+declare const $app: {
+  readonly name: string;
+  readonly stage: string;
+};
+
+declare const $interpolate: (
+  strings: TemplateStringsArray,
+  ...values: any[]
+) => PulumiOutput<string>;
+
+declare namespace $util {
+  type Output<T> = PulumiOutput<T>;
+}

package/src/storage.ts

@@ -0,0 +1,138 @@
+/**
+ * Storage Infrastructure
+ *
+ * 9 DynamoDB tables + S3 bucket + CloudFront KeyValueStore.
+ * All resources are prefixed with the component name.
+ */
+
+export function createStorage(name: string) {
+  const sites = new sst.aws.Dynamo(`${name}Sites`, {
+    fields: {
+      pk: "string",
+      sk: "string",
+    },
+    primaryIndex: { hashKey: "pk", rangeKey: "sk" },
+  });
+
+  const content = new sst.aws.Dynamo(`${name}Content`, {
+    fields: {
+      pk: "string",
+      sk: "string",
+      gsiPk: "string",
+      gsiSk: "string",
+      lastDraftAtSk: "string",
+      collectionGsiPk: "string",
+      titleSk: "string",
+    },
+    primaryIndex: { hashKey: "pk", rangeKey: "sk" },
+    globalIndexes: {
+      byPublishedDate: { hashKey: "gsiPk", rangeKey: "gsiSk" },
+      byLastDraftAt: { hashKey: "pk", rangeKey: "lastDraftAtSk" },
+      byCollectionTitle: { hashKey: "collectionGsiPk", rangeKey: "titleSk" },
+    },
+  });
+
+  const draftContent = new sst.aws.Dynamo(`${name}DraftContent`, {
+    fields: {
+      pk: "string",
+      sk: "string",
+    },
+    primaryIndex: { hashKey: "pk", rangeKey: "sk" },
+  });
+
+  const blocks = new sst.aws.Dynamo(`${name}Blocks`, {
+    fields: {
+      pk: "string",
+    },
+    primaryIndex: { hashKey: "pk" },
+  });
+
+  const media = new sst.aws.Dynamo(`${name}Media`, {
+    fields: {
+      pk: "string",
+      sk: "string",
+      uploadedAt: "number",
+      folderGsiPk: "string",
+    },
+    primaryIndex: { hashKey: "pk", rangeKey: "sk" },
+    globalIndexes: {
+      byDate: { hashKey: "pk", rangeKey: "uploadedAt" },
+      byFolder: { hashKey: "folderGsiPk", rangeKey: "uploadedAt" },
+    },
+  });
+
+  const collections = new sst.aws.Dynamo(`${name}Collections`, {
+    fields: {
+      pk: "string",
+      sk: "string",
+    },
+    primaryIndex: { hashKey: "pk", rangeKey: "sk" },
+  });
+
+  const blockTypes = new sst.aws.Dynamo(`${name}BlockTypes`, {
+    fields: {
+      pk: "string",
+      sk: "string",
+    },
+    primaryIndex: { hashKey: "pk", rangeKey: "sk" },
+  });
+
+  const adminAudit = new sst.aws.Dynamo(`${name}AdminAudit`, {
+    fields: {
+      pk: "string",
+      sk: "string",
+    },
+    primaryIndex: { hashKey: "pk", rangeKey: "sk" },
+  });
+
+  const relationships = new sst.aws.Dynamo(`${name}Relationships`, {
+    fields: {
+      pk: "string",
+      sk: "string",
+      targetPk: "string",
+      targetSk: "string",
+    },
+    primaryIndex: { hashKey: "pk", rangeKey: "sk" },
+    globalIndexes: {
+      byTarget: { hashKey: "targetPk", rangeKey: "targetSk" },
+    },
+  });
+
+  const contentBucket = new sst.aws.Bucket(`${name}ContentBucket`, {
+    versioning: true,
+    access: "cloudfront",
+    transform: {
+      bucket: (args: any) => {
+        args.lifecycleRules = [
+          {
+            id: "cleanup-pending-uploads",
+            enabled: true,
+            expirations: [{ days: 1 }],
+            tags: { status: "pending" },
+          },
+        ];
+      },
+    },
+  });
+
+  const kvs = new aws.cloudfront.KeyValueStore(`${name}KVS`, {
+    name: $interpolate`${$app.name}-${$app.stage}-kvs`,
+    comment: "Headroom CMS edge data: API keys and site versions",
+  });
+
+  return {
+    sites,
+    content,
+    draftContent,
+    blocks,
+    media,
+    collections,
+    blockTypes,
+    adminAudit,
+    relationships,
+    contentBucket,
+    kvs,
+  };
+}
+
+export type StorageResources = ReturnType<typeof createStorage>;

package/src/webhooks.ts

@@ -0,0 +1,114 @@
+/**
+ * Webhook Infrastructure
+ *
+ * 2 DynamoDB tables + 2 SQS queues + webhook worker Lambda.
+ * Supports dev mode (Go source) and package mode (pre-compiled binary).
+ */
+
+import path from "path";
+import type { StorageResources } from "./storage.js";
+
+export interface WebhookArgs {
+  sites: StorageResources["sites"];
+  pkgRoot: string;
+  dev?: {
+    /** Go source path, e.g. "packages/webhook-worker" */
+    handler: string;
+  };
+}
+
+export function createWebhooks(name: string, args: WebhookArgs) {
+  const webhooks = new sst.aws.Dynamo(`${name}Webhooks`, {
+    fields: {
+      pk: "string",
+      sk: "string",
+    },
+    primaryIndex: { hashKey: "pk", rangeKey: "sk" },
+  });
+
+  const webhookDeliveries = new sst.aws.Dynamo(`${name}WebhookDeliveries`, {
+    fields: {
+      pk: "string",
+      sk: "string",
+    },
+    primaryIndex: { hashKey: "pk", rangeKey: "sk" },
+    ttl: "ttl",
+  });
+
+  const webhookDeliveryDLQ = new sst.aws.Queue(`${name}WebhookDeliveryDLQ`, {
+    transform: {
+      queue: (queueArgs: any) => {
+        queueArgs.messageRetentionSeconds = 14 * 24 * 60 * 60; // 14 days
+      },
+    },
+  });
+
+  const webhookDeliveryQueue = new sst.aws.Queue(
+    `${name}WebhookDeliveryQueue`,
+    {
+      dlq: {
+        queue: webhookDeliveryDLQ.arn,
+        retry: 5,
+      },
+      transform: {
+        queue: (queueArgs: any) => {
+          queueArgs.visibilityTimeoutSeconds = 60;
+          queueArgs.messageRetentionSeconds = 4 * 24 * 60 * 60; // 4 days
+        },
+      },
+    },
+  );
+
+  // Webhook worker Lambda: processes SQS messages and delivers webhooks.
+  // Note: We use a manual Function + EventSourceMapping instead of
+  // queue.subscribe() to avoid a duplicate LambdaEncryptionKey issue
+  // caused by SST's dynamic import creating a separate Function class instance.
+  const workerConfig = args.dev
+    ? {
+        handler: args.dev.handler,
+        runtime: "go" as const,
+      }
+    : {
+        bundle: path.join(args.pkgRoot, "lambda/webhook-worker"),
+        handler: "bootstrap",
+        runtime: "provided.al2023" as const,
+        architecture: "arm64" as const,
+      };
+
+  const webhookWorker = new sst.aws.Function(`${name}WebhookWorker`, {
+    ...workerConfig,
+    memory: "256 MB",
+    timeout: "30 seconds",
+    environment: {
+      WEBHOOK_DELIVERIES_TABLE: webhookDeliveries.name,
+      WEBHOOKS_TABLE: webhooks.name,
+      SITES_TABLE: args.sites.name,
+    },
+    link: [webhookDeliveries, webhooks, args.sites],
+    permissions: [
+      {
+        actions: [
+          "sqs:ReceiveMessage",
+          "sqs:DeleteMessage",
+          "sqs:GetQueueAttributes",
+        ],
+        resources: [webhookDeliveryQueue.arn],
+      },
+    ],
+  });
+
+  new aws.lambda.EventSourceMapping(`${name}WebhookWorkerEventSource`, {
+    eventSourceArn: webhookDeliveryQueue.arn,
+    functionName: webhookWorker.name,
+    batchSize: 1,
+  });
+
+  return {
+    webhooks,
+    webhookDeliveries,
+    webhookDeliveryQueue,
+    webhookDeliveryDLQ,
+  };
+}
+
+export type WebhookResources = ReturnType<typeof createWebhooks>;