@soloworks/smking-next 0.20.3 → 0.21.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @soloworks/smking-next
 
+## 0.21.1 — 2026-06-12
+
+**Webhook replay protection (security review M6).**
+
+The webhook receiver now rejects deliveries whose `deliveredAt` falls
+outside a ±5-minute window (401 `stale_delivery`; a missing field counts
+as stale — the SaaS has sent it since v0.11) and dedupes `deliveryId`
+re-sends inside that window (401 `duplicate_delivery`). Dedup is
+best-effort in-memory per serverless instance; the time window is the
+primary defense. The SaaS now stamps every delivery with a unique
+`deliveryId` — payloads from a SaaS predating the field skip dedup and
+keep working. Both fields sit inside the HMAC-signed JSON body, so an
+attacker can't forge or strip them. No customer action needed; `^0.21`
+picks this up automatically.
+
+**Mode B block types caught up with the SaaS catalog (types only — no
+runtime change).**
+
+The `Block` union had drifted to 3 of the SaaS's 10 block components; it
+now covers all of them — added `search`, `nav-recent-posts`,
+`nav-related-posts`, `nav-category-index`, `image`, `slideshow`, and
+`social-share` (plus the missing `NavSnapshotEntry.href` field). The types
+are no longer a hand-maintained mirror: the monorepo's `@smking/shared`
+package is the single source of truth and `src/cms-blocks.ts` is a
+generated vendored copy (`pnpm sync:block-types`, guarded by a vitest
+sync test). All block prop interfaces are also exported from the package
+root now (`Block`, `BlockComponent`, `SearchProps`, …). Mode A
+(`bodyHtml`) rendering is unaffected.
+
+## 0.21.0 — 2026-06-09
+
+**Per-site CMS theme — `<SmkingRuntime>` now mounts a `theme.css` stylesheet.**
+
+`SmkingRuntime` gains an optional `apiKey` prop (auto-resolved from
+`SMKING_API_KEY`); when set, it injects `<link rel="stylesheet"
+href="…/api/v1/public/theme.css?key=…">` right after `runtime.css` so the
+site's shadcn theme variables override the neutral defaults inside the
+`[data-smking="cms"]` container. No customer code change — the env var is
+already required; the link is omitted when no key is configured.
+
 ## 0.20.3 — 2026-06-08
 
 **CMS draft preview URL now carries a visible `?smking_preview=1` marker.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.20.3",
+  "version": "0.21.1",
   "description": "AI-native SEO (AEO) for Next.js — auto-inject JSON-LD, FAQ, AI summary, and SEO metadata so AI crawlers (ChatGPT, Perplexity, Google AI) can cite your pages.",
   "license": "MIT",
   "homepage": "https://github.com/sillyleo/smking/tree/main/packages/smking-next",

package/src/cms-blocks.ts

@@ -0,0 +1,219 @@
+// GENERATED FILE — do not edit by hand.
+// Vendored copy of packages/shared/src/types/cms-blocks.ts (the SDK ships
+// raw src/ to npm, so it can't import the private workspace package).
+// Regenerate with: pnpm sync:block-types
+
+/**
+ * CMS block primitives — substrate-pivot v2.
+ *
+ * Single source of truth for the Mode B (blocks JSON) contract shared by
+ * the SaaS dashboard (`apps/web/src/features/cms`) and the customer SDKs.
+ * The dashboard editor serializes Plate documents into this shape, the
+ * publish pipeline materializes nav snapshots into it, and
+ * `/api/v1/public/page` returns it verbatim.
+ *
+ * ⚠️ `@soloworks/smking-next` publishes raw `src/` to npm and cannot import
+ * this private workspace package — it ships a vendored copy at
+ * `packages/smking-next/src/cms-blocks.ts` instead. After editing this file
+ * run `pnpm sync:block-types` to regenerate it (drift fails the SDK's
+ * vitest guard).
+ *
+ * `article` is the serialize-time HTML container for runs of Plate built-in
+ * blocks — paragraphs / headings / lists are collapsed into one HTML body
+ * block via Plate's `serializeHtml`. New block primitives land here + in
+ * apps/web `block-schemas.ts`.
+ *
+ * `nav-taxonomy-list` uses a `source` discriminator — category mode is
+ * slug-prefix derived, tag mode targets `taxonomies.slug`.
+ */
+
+export interface HeroProps {
+  title: string;
+  subtitle?: string;
+  image?: { url: string; alt: string };
+  cta?: { label: string; href: string };
+  /** Header layout — omitted = the original centred hero; "start" = the
+   * Apple-newsroom-style left-aligned header; "cover" = title-only banner
+   * over a full-bleed background image (Apple services index). Visuals ship
+   * via bodyHtml; this mirrors the node attr for SDK Mode B (per-block)
+   * consumers. */
+  align?: "center" | "start" | "cover";
+}
+
+export interface ArticleProps {
+  /** Plate `serializeHtml` output — a contiguous run of built-in blocks
+   * (paragraphs / headings / lists) collapsed into one HTML body block. */
+  html: string;
+}
+
+export interface ModuleHeader {
+  heading?: string;
+  viewAll?: { label: string; href: string };
+}
+
+export type NavLayout = "grid" | "list" | "carousel" | "archive";
+
+/**
+ * Materialized snapshot entry written into nav-* block props at publish
+ * time (see apps/web `materialize-blocks.ts` for the resolver). The
+ * customer SDK echoes `snapshot` verbatim — it never round-trips back to
+ * smking for nav rendering, so if smking is down customer pages still
+ * render whatever was last published.
+ */
+export interface NavSnapshotEntry {
+  slug: string;
+  /**
+   * Absolute href = the customer's CMS mount prefix + slug (baked at publish
+   * from `sites.config.cmsBasePath`). Optional — falls back to `/${slug}`.
+   */
+  href?: string;
+  title: string | null;
+  excerpt: string | null;
+  featuredImageUrl: string | null;
+  /** ISO string. */
+  publishedAt: string | null;
+  contentType: "article" | "landing" | "listing" | null;
+}
+
+/**
+ * `search` block — a command-palette over the WHOLE site's published CMS
+ * pages. Unlike `nav-taxonomy-list` (which scopes to a category / tag),
+ * search bakes EVERY published `cms_page` into `snapshot` at publish time
+ * and the `<smking-search>` web component filters the rendered cards
+ * client-side. Reuses `NavSnapshotEntry` (the static render only reads
+ * `href` / `title` / `excerpt` — no thumbnail, command-palette text feel).
+ */
+export interface SearchProps {
+  /** Input placeholder. Defaults to "Search…" at render time. */
+  placeholder?: string;
+  /** Optional heading above the search input. */
+  heading?: string;
+  /** Publish-time materialized snapshot — every published page on the site. */
+  snapshot?: NavSnapshotEntry[];
+}
+
+export interface RecentPostsProps extends ModuleHeader {
+  /** Author-set number of latest posts to show (1..50). */
+  limit: number;
+  /** Publish-time materialized snapshot — whole-site newest-first. */
+  snapshot?: NavSnapshotEntry[];
+}
+
+export interface RelatedPostsProps extends ModuleHeader {
+  /** Author-set number of related posts to show (1..50). */
+  limit: number;
+  /** Publish-time materialized snapshot — same-tag, ranked by overlap. */
+  snapshot?: NavSnapshotEntry[];
+}
+
+/** One author-selected category in a nav-category-index block. */
+export interface CategoryIndexItem {
+  /** Slug prefix identifying the category (e.g. `blog/seo`). */
+  path: string;
+  /** Display name on the card (slug leaf by default; author-editable). */
+  label: string;
+}
+
+/**
+ * Materialized card for nav-category-index: the category's name, its archive
+ * link, and its latest post (null when the category has no published posts).
+ */
+export interface CategoryCardSnapshot {
+  label: string;
+  /** Archive href = mount prefix + category path (baked at publish). */
+  href: string;
+  latest: NavSnapshotEntry | null;
+}
+
+export interface CategoryIndexProps extends ModuleHeader {
+  items: CategoryIndexItem[];
+  /** Card layout — omitted/"cards" = category cards (archive links);
+   * "featured" = Apple-newsroom services-index tiles where each card IS the
+   * category's latest article. Visuals ship via bodyHtml; this mirrors the
+   * node attr for SDK Mode B (per-block) consumers. */
+  layout?: "cards" | "featured";
+  snapshot?: CategoryCardSnapshot[];
+}
+
+/**
+ * `image` block — a single figure (image + optional caption). `widthMode`
+ * controls the breakout (content = text column, wide = up to 1024px centred
+ * on the container). All fields optional so an unconfigured block is valid;
+ * the static render emits nothing until an image is uploaded.
+ */
+export interface ImageProps {
+  url?: string;
+  alt?: string;
+  caption?: string;
+  widthMode?: "content" | "wide";
+}
+
+/** One slide in a `slideshow` block. */
+export interface SlideshowSlideProps {
+  url: string;
+  alt?: string;
+  caption?: string;
+}
+
+/**
+ * `slideshow` block — an image carousel. `widthMode` controls the breakout
+ * (content / wide). `slides` optional so an unconfigured block is valid; the
+ * static render emits nothing (and the customer SDK upgrades it into a
+ * paginated carousel via the `<smking-slideshow>` web component).
+ */
+export interface SlideshowProps {
+  slides?: SlideshowSlideProps[];
+  widthMode?: "content" | "wide";
+  /** Fixed crop ratio for every slide (render default 16:9). */
+  aspectRatio?: "16:9" | "4:3";
+}
+
+/**
+ * `social-share` block — X / Facebook / LinkedIn share links + copy-link. The
+ * platforms are fixed; `shareUrl` is the optional no-JS fallback target (the
+ * `<smking-share>` web component overrides every link from window.location at
+ * runtime, so the live share always points at the real current page).
+ */
+export interface SocialShareProps {
+  shareUrl?: string;
+  /** Heading above the row. Omitted = "Share article" default at render
+   * time; empty string = bare icon row (Apple-newsroom header style). */
+  label?: string;
+}
+
+export interface NavTaxonomyListProps extends ModuleHeader {
+  /**
+   * Discriminator:
+   *  - `category-by-path` → `path` is a slug prefix (e.g. `/blog/seo`); SDK
+   *    queries pages whose slug starts with this prefix.
+   *  - `tag` → `path` is the taxonomy slug (flat tag namespace).
+   */
+  source: "category-by-path" | "tag";
+  path: string;
+  limit: number;
+  /** List EVERY published article under the category/tag instead of the
+   * latest `limit` (Apple archive page). The resolver still applies a 200
+   * safety cap. Omitted (not false) when off — back-compat shape. */
+  showAll?: boolean;
+  layout: NavLayout;
+  /** Publish-time materialized snapshot. */
+  snapshot?: NavSnapshotEntry[];
+}
+
+export type Block =
+  | { component: "hero"; id: string; props: HeroProps }
+  | { component: "article"; id: string; props: ArticleProps }
+  | {
+      component: "nav-taxonomy-list";
+      id: string;
+      props: NavTaxonomyListProps;
+    }
+  | { component: "search"; id: string; props: SearchProps }
+  | { component: "nav-recent-posts"; id: string; props: RecentPostsProps }
+  | { component: "nav-related-posts"; id: string; props: RelatedPostsProps }
+  | { component: "nav-category-index"; id: string; props: CategoryIndexProps }
+  | { component: "image"; id: string; props: ImageProps }
+  | { component: "slideshow"; id: string; props: SlideshowProps }
+  | { component: "social-share"; id: string; props: SocialShareProps };
+
+export type BlockComponent = Block["component"];

package/src/components/smking-runtime.tsx

@@ -15,8 +15,10 @@
  */
 export function SmkingRuntime({
   baseUrl,
+  apiKey,
 }: {
   baseUrl?: string;
+  apiKey?: string;
 }) {
   const url = (
     baseUrl ?? process.env.SMKING_BASE_URL ?? "https://smking.app"
@@ -24,6 +26,9 @@ export function SmkingRuntime({
   return (
     <>
       <link rel="stylesheet" href={`${url}/api/v1/public/runtime.css`} />
+      {apiKey && (
+        <link rel="stylesheet" href={`${url}/api/v1/public/theme.css?key=${apiKey}`} />
+      )}
       <script src={`${url}/api/v1/public/runtime.js`} async />
     </>
   );

package/src/index.ts

@@ -6,6 +6,12 @@ export { getCmsPage } from "./lib/cms-client";
 export type {
   AeoResponse,
   AeoStatus,
+  ArticleProps,
+  Block,
+  BlockComponent,
+  CategoryCardSnapshot,
+  CategoryIndexItem,
+  CategoryIndexProps,
   ChatLinks,
   CmsPage,
   CmsParams,
@@ -13,5 +19,17 @@ export type {
   CmsStatus,
   DiscoverParams,
   FaqItem,
+  HeroProps,
+  ImageProps,
+  ModuleHeader,
+  NavLayout,
+  NavSnapshotEntry,
+  NavTaxonomyListProps,
+  RecentPostsProps,
+  RelatedPostsProps,
+  SearchProps,
   SeoMeta,
+  SlideshowProps,
+  SlideshowSlideProps,
+  SocialShareProps,
 } from "./types";

package/src/lib/webhook-route.ts

@@ -7,6 +7,35 @@ interface WebhookPayload {
   paths?: string[];
   slugs?: string[];
   deliveredAt?: string;
+  deliveryId?: string;
+}
+
+// Replay protection (v0.21.1+). The deliveredAt window is the primary
+// defense — ±5min absorbs clock skew between SaaS and customer while
+// capping how long an intercepted delivery stays replayable. deliveryId
+// dedup is best-effort on top: serverless instances each hold their own
+// Map, so a replay landing on a different instance only has the window
+// to beat. SaaS payloads predating deliveryId pass dedup untouched.
+const REPLAY_WINDOW_MS = 5 * 60 * 1000;
+const SEEN_DELIVERIES_MAX = 1000;
+const seenDeliveries = new Map<string, number>(); // deliveryId → expiry (ms)
+
+function isDuplicateDelivery(
+  deliveryId: string | undefined,
+  now: number,
+): boolean {
+  for (const [id, expiry] of seenDeliveries) {
+    if (expiry <= now) seenDeliveries.delete(id);
+  }
+  if (typeof deliveryId !== "string" || deliveryId.length === 0) return false;
+  if (seenDeliveries.has(deliveryId)) return true;
+  if (seenDeliveries.size >= SEEN_DELIVERIES_MAX) {
+    // Map iterates in insertion order — evict the oldest entry.
+    const oldest = seenDeliveries.keys().next().value;
+    if (oldest !== undefined) seenDeliveries.delete(oldest);
+  }
+  seenDeliveries.set(deliveryId, now + REPLAY_WINDOW_MS);
+  return false;
 }
 
 /**
@@ -41,6 +70,13 @@ interface WebhookPayload {
  * Auth: HMAC-SHA256 only. Bearer dropped — single auth model means one
  * env var, one shim, fewer customer mis-config paths (the disambiguation
  * problem the v0.10 dual-handler shipped with).
+ *
+ * Replay protection (v0.21.1+): a signed delivery is only accepted while
+ * `deliveredAt` sits inside a ±5min window (401 `stale_delivery`
+ * otherwise — missing field counts as stale), and a `deliveryId` seen
+ * before within that window is rejected (401 `duplicate_delivery`).
+ * Payloads from a SaaS predating `deliveryId` skip dedup — the window
+ * remains the primary defense.
  */
 export async function POST(request: Request): Promise<Response> {
   const secret = process.env.SMKING_WEBHOOK_SECRET;
@@ -66,6 +102,23 @@ export async function POST(request: Request): Promise<Response> {
     return Response.json({ error: "invalid_payload" }, { status: 400 });
   }
 
+  // Replay protection — deliveredAt must sit inside a ±5min window
+  // (missing/unparseable counts as stale; SaaS has sent it since v0.11),
+  // then deliveryId dedup rejects re-sends of a delivery we already saw.
+  const now = Date.now();
+  const deliveredAtMs = payload.deliveredAt
+    ? Date.parse(payload.deliveredAt)
+    : Number.NaN;
+  if (
+    Number.isNaN(deliveredAtMs) ||
+    Math.abs(now - deliveredAtMs) > REPLAY_WINDOW_MS
+  ) {
+    return Response.json({ error: "stale_delivery" }, { status: 401 });
+  }
+  if (isDuplicateDelivery(payload.deliveryId, now)) {
+    return Response.json({ error: "duplicate_delivery" }, { status: 401 });
+  }
+
   const kind = payload.kind;
   if (typeof kind !== "string" || kind.length === 0) {
     // Forward-compat: SaaS may emit kinds we haven't taught the SDK

package/src/types.ts

@@ -64,58 +64,34 @@ export type CmsContentType = "article" | "landing" | "listing";
 // `<article class="prose">` around `<SmkingCms>` themselves.
 
 /**
- * v2 substrate block primitives. Mirrors `apps/web/src/features/cms/types.ts`
- * on the SaaS side (kept in sync manually — when the v1 block catalog
- * grows past 5 primitives, a shared workspace package replaces this
- * duplication per `docs/superpowers/specs/2026-05-15-cms-dashboard-editor-design.md`
- * section §11 + ai-cms-v2 §"擴充性").
+ * v2 substrate block primitives. Single source of truth lives in the
+ * monorepo's `packages/shared/src/types/cms-blocks.ts`; this package ships
+ * a vendored copy (`./cms-blocks`, regenerated via `pnpm sync:block-types`)
+ * because raw `src/` is published to npm and can't depend on the private
+ * workspace package. A vitest guard fails when the copy drifts.
  */
-export interface HeroProps {
-  title: string;
-  subtitle?: string;
-  image?: { url: string; alt: string };
-  cta?: { label: string; href: string };
-}
-export interface ArticleProps {
-  html: string;
-}
-export interface ModuleHeader {
-  heading?: string;
-  viewAll?: { label: string; href: string };
-}
-export type NavLayout = "grid" | "list" | "carousel";
-
-/**
- * Materialized snapshot entry — published pages on the smking SaaS
- * pre-resolve their nav-* block data at publish time and bake it into
- * `block.props.snapshot`. Customer SDK echoes this verbatim, never
- * round-trips back to smking for nav rendering. If smking is down,
- * customer pages still render whatever was last published.
- */
-export interface NavSnapshotEntry {
-  slug: string;
-  title: string | null;
-  excerpt: string | null;
-  featuredImageUrl: string | null;
-  /** ISO string. */
-  publishedAt: string | null;
-  contentType: "article" | "landing" | "listing" | null;
-}
-
-export interface NavTaxonomyListProps extends ModuleHeader {
-  /** category-by-path: slug prefix; tag: taxonomies.slug */
-  source: "category-by-path" | "tag";
-  path: string;
-  limit: number;
-  layout: NavLayout;
-  /** Publish-time materialized — never fetched live. */
-  snapshot?: NavSnapshotEntry[];
-}
-
-export type Block =
-  | { component: "hero"; id: string; props: HeroProps }
-  | { component: "article"; id: string; props: ArticleProps }
-  | { component: "nav-taxonomy-list"; id: string; props: NavTaxonomyListProps };
+import type { Block } from "./cms-blocks";
+
+export type {
+  ArticleProps,
+  Block,
+  BlockComponent,
+  CategoryCardSnapshot,
+  CategoryIndexItem,
+  CategoryIndexProps,
+  HeroProps,
+  ImageProps,
+  ModuleHeader,
+  NavLayout,
+  NavSnapshotEntry,
+  NavTaxonomyListProps,
+  RecentPostsProps,
+  RelatedPostsProps,
+  SearchProps,
+  SlideshowProps,
+  SlideshowSlideProps,
+  SocialShareProps,
+} from "./cms-blocks";
 
 /**
  * A single published CMS page returned by the smking public API