@roottale/cms-core 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @roottale/cms-core
+
+## 0.2.0
+
+### Minor Changes
+
+- d1b5d35: cms-\* public renderer 패키지 npm public publish — Phase 1 dogfood.
+
+  ADR-0029 §0 amend (publish-only dormant) 는 design system 5 패키지 (tokens, ui-css, ui-react, ui-astro, ui-admin) 에 한정. cms-\* 는 별도 정책 — 실행 로직 + 5-20 외부 customer site 직접 의존 + schema 호환 + 보안 경계. Codex consult verdict (session `019e6703…`) 정합.
+
+  변경:
+  - 4 패키지 `private: true` 해제 + `publishConfig.access: "public"`
+  - `@roottale/cms-renderer-next` 에서 `@roottale/tokens/tokens.css` import 제거 — 모든 `--rt-*` 변수에 static fallback 으로 self-contained. tokens dormant 와 무관하게 동작.
+  - `RootTaleLeadForm` RSC 추가 — 외부 사이트 진단 폼 (`vertical`/`redirectUrl` props, medical 국외이전 동의 자동).
+  - README + repository / homepage / keywords 메타 정비
+  - `peerDependencies.react: ^19` 명시 (cms-renderer-next)
+  - `cms-renderer-astro` 도 동등 surface 유지를 위해 동시 publish
+
+  후속:
+  - ADR 신규 — cms-\* publish 정책 (별 PR)
+  - Astro 측 LeadForm 컴포넌트 (현재 `@roottale/ui-astro` 위치, `cms-renderer-astro` 로 이동 검토)

package/README.md

@@ -0,0 +1,24 @@
+# @roottale/cms-core
+
+RootTale CMS core — Block JSON schema (Gutenberg/Tiptap-compatible), serialize, validate.
+
+Transitive dependency of [`@roottale/cms-renderer-next`](https://www.npmjs.com/package/@roottale/cms-renderer-next) and [`@roottale/cms-renderer-astro`](https://www.npmjs.com/package/@roottale/cms-renderer-astro). You usually don't install this directly — the renderer pulls it in. Install standalone if you need the types/schema in your own pipeline (custom validators, content migrations, codegen).
+
+See ADR-0034 §3 §5 for the schema decision context.
+
+## Install
+
+```bash
+npm install @roottale/cms-core
+```
+
+## Exports
+
+- Block JSON Zod schemas
+- `serializeBlocks` / `parseBlocks`
+- Block id stable hash helpers
+- TypeScript types
+
+## License
+
+Proprietary (UNLICENSED). Issued under the RootTale customer contract.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@roottale/cms-core",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "RootTale CMS core — Block JSON schema (Gutenberg-compatible), serialize, validate. ADR-0034 §3 §5. Transitive dependency of @roottale/cms-renderer-next / @roottale/cms-renderer-astro.",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "uuidv7": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "roottale",
+    "cms",
+    "block-json",
+    "schema",
+    "tiptap",
+    "gutenberg"
+  ],
+  "license": "UNLICENSED",
+  "homepage": "https://github.com/RootTale/roottale-platform/tree/main/packages/cms-core",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RootTale/roottale-platform.git",
+    "directory": "packages/cms-core"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}

package/src/__tests__/preview-token.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import { issuePreviewToken, verifyPreviewToken } from "../preview-token";
+
+describe("preview-token (HMAC + expiry)", () => {
+  const secret = "test-secret-do-not-use-in-prod";
+
+  it("issue → verify round-trips postId + expiry", () => {
+    const expiresAt = new Date(Date.now() + 60_000);
+    const token = issuePreviewToken(secret, {
+      postId: "post-abc",
+      expiresAt,
+    });
+    const payload = verifyPreviewToken(secret, token);
+    expect(payload?.postId).toBe("post-abc");
+    expect(payload?.expiresAt.getTime()).toBe(expiresAt.getTime());
+  });
+
+  it("rejects wrong secret", () => {
+    const token = issuePreviewToken(secret, {
+      postId: "post-abc",
+      expiresAt: new Date(Date.now() + 60_000),
+    });
+    expect(verifyPreviewToken("other-secret", token)).toBeNull();
+  });
+
+  it("rejects expired token", () => {
+    const token = issuePreviewToken(secret, {
+      postId: "post-abc",
+      expiresAt: new Date(Date.now() - 1),
+    });
+    expect(verifyPreviewToken(secret, token)).toBeNull();
+  });
+
+  it("rejects tampered postId", () => {
+    const token = issuePreviewToken(secret, {
+      postId: "post-abc",
+      expiresAt: new Date(Date.now() + 60_000),
+    });
+    const parts = token.split(".");
+    // swap postId
+    parts[0] = "post-evil";
+    const tampered = parts.join(".");
+    expect(verifyPreviewToken(secret, tampered)).toBeNull();
+  });
+
+  it("rejects malformed token (wrong segment count)", () => {
+    expect(verifyPreviewToken(secret, "only.two")).toBeNull();
+    expect(verifyPreviewToken(secret, "a.b.c.d.e")).toBeNull();
+  });
+
+  it("two issues with same payload differ (nonce randomness)", () => {
+    const expiresAt = new Date(Date.now() + 60_000);
+    const t1 = issuePreviewToken(secret, { postId: "p", expiresAt });
+    const t2 = issuePreviewToken(secret, { postId: "p", expiresAt });
+    expect(t1).not.toBe(t2);
+  });
+});

package/src/block-definition.ts

@@ -0,0 +1,57 @@
+// ADR-0034 §5 — BlockDefinition (렌더러 어댑터)
+// codex v2 verdict #3 + #11: Astro = 유일 public renderer (Phase 0~4).
+// `nextRender` 시그니처 의도적 제거 — Phase 5 에 Next public 활성 시 별도 ADR.
+
+import type { ZodSchema } from "zod";
+
+import type { Block } from "./block";
+
+/**
+ * Astro island spec — `client:visible` / `client:idle` / `client:load` 등.
+ * frontend 의 native interactivity. WP Interactivity API 카피 안 함.
+ */
+export interface AstroIslandSpec {
+  /** Astro `client:*` directive */
+  hydration?: "visible" | "idle" | "load" | "media" | "only";
+  /** client-side module path (relative to package) */
+  module?: string;
+}
+
+/**
+ * BlockDefinition<A> — block 의 schema + Astro render 어댑터.
+ * Phase 5 에 Next public renderer 활성 시 별도 ADR-amend 의 add 의무.
+ */
+export interface BlockDefinition<A = Record<string, unknown>> {
+  /** `core/<x>` or `roottale/<x>` */
+  name: string;
+  /** display metadata for admin editor */
+  meta: {
+    title: string;
+    description?: string;
+    category?: "text" | "media" | "design" | "widgets" | "theme" | "embed";
+    icon?: string;
+  };
+  /** attributes validation */
+  schema: ZodSchema<A>;
+  /** WP `supports` 등 flags */
+  supports?: {
+    align?: boolean;
+    color?: boolean;
+    spacing?: boolean;
+    typography?: boolean;
+    customClassName?: boolean;
+  };
+  /** parent block name 강제 (e.g. `core/column` 은 `core/columns` 아래만) */
+  parent?: readonly string[];
+  /** ancestor block name 강제 */
+  ancestor?: readonly string[];
+  /** Astro server render — 본 함수는 packages/cms-renderer-astro 에서 호출 */
+  astroRender: (block: Block & { attributes: A }) => unknown;
+  /** Astro client island (optional) */
+  clientHydration?: { astro?: AstroIslandSpec };
+}
+
+/**
+ * Block registry — Phase 1 에서 register/lookup helper 추가 (현재는 type-only).
+ */
+export type BlockRegistry = ReadonlyMap<string, BlockDefinition>;

package/src/block.ts

@@ -0,0 +1,85 @@
+// ADR-0034 §5 — Block JSON 스펙 (WP 호환)
+// Gutenberg block shape + 우리 확장:
+//   - `_id` (uuidv7 stable across revisions, ADR §2 P5)
+//   - `rawHtml` (WP delimiter innerHTML 보존, codex v2 verdict #7)
+//   - `metadata.reusableRef` (Phase 2 = flat expand)
+
+import { z } from "zod";
+
+/** WP-compatible name pattern: `core/<x>` | `roottale/<x>` */
+export const BLOCK_NAME_PATTERN = /^(core|roottale)\/[a-z0-9-]+$/;
+
+const blockMetadataSchema = z
+  .object({
+    bindings: z
+      .record(
+        z.object({
+          source: z.string(),
+          args: z.record(z.unknown()).optional(),
+        }),
+      )
+      .optional(),
+    name: z.string().optional(),
+    reusableRef: z.string().optional(),
+  })
+  .strict()
+  .optional();
+
+/**
+ * Block schema (recursive — innerBlocks).
+ * `_id` 는 internal-only (export 시 strip, ADR §5).
+ */
+export const blockSchema: z.ZodType<Block> = z.lazy(() =>
+  z
+    .object({
+      _id: z.string().uuid(),
+      name: z.string().regex(BLOCK_NAME_PATTERN),
+      attributes: z.record(z.unknown()),
+      innerBlocks: z.array(blockSchema),
+      rawHtml: z.string().optional(),
+      metadata: blockMetadataSchema,
+    })
+    .strict(),
+);
+
+export interface Block {
+  /** uuidv7. Internal-only — never exported as WP delimiter attribute. */
+  _id: string;
+  /** `core/<x>` or `roottale/<x>` */
+  name: string;
+  attributes: Record<string, unknown>;
+  innerBlocks: Block[];
+  /** WP delimiter innerHTML (preserved for round-trip — codex v2 verdict #7). */
+  rawHtml?: string;
+  metadata?: {
+    bindings?: Record<string, { source: string; args?: Record<string, unknown> }>;
+    name?: string;
+    reusableRef?: string;
+  };
+}
+
+export function isValidBlock(value: unknown): value is Block {
+  return blockSchema.safeParse(value).success;
+}
+
+export function parseBlock(value: unknown): Block {
+  return blockSchema.parse(value);
+}
+
+/**
+ * Phase 1 core block names (10) — ADR-0034 §5.
+ * Phase 2+ 에 `core/embed`, `core/gallery`, `core/cover` 등 추가.
+ */
+export const PHASE_1_CORE_BLOCKS = [
+  "core/paragraph",
+  "core/heading",
+  "core/image",
+  "core/list",
+  "core/quote",
+  "core/code",
+  "core/columns",
+  "core/group",
+  "core/separator",
+  "core/spacer",
+] as const;
+export type Phase1CoreBlockName = (typeof PHASE_1_CORE_BLOCKS)[number];

package/src/delimiter.ts

@@ -0,0 +1,59 @@
+// ADR-0034 §5 + §6 — WP delimiter parse/serialize
+//
+// WP 의 block serialization 은 HTML 주석 형태:
+//   <!-- wp:paragraph {"attr":1} -->
+//   <p>본문</p>
+//   <!-- /wp:paragraph -->
+//
+// Round-trip 룰 (codex v2 verdict #7 + v3 verdict #4):
+//   - `_id` 는 export 시 strip (WP-side import 가 unknown attribute 로 인식해 깨짐 차단)
+//   - `rawHtml` ↔ innerHTML
+//   - 우리가 schema 정의 안 한 block = Tiptap opaque atom node (편집 불가, 보존)
+
+import type { Block } from "./block";
+
+/**
+ * Block → WP delimiter 형식 직렬화 (export).
+ * `_id` 와 `metadata.reusableRef` 는 strip — WP 호환.
+ */
+export function serializeBlock(block: Block): string {
+  const exportable = sanitizeAttributesForExport(block);
+  const attrsJson = serializeAttributes(exportable.attributes);
+  const innerHtml = block.rawHtml ?? "";
+  const innerSerialized = (block.innerBlocks ?? [])
+    .map((b) => serializeBlock(b))
+    .join("\n");
+
+  // self-closing 형태 (innerHTML + innerBlocks 모두 없으면)
+  if (!innerHtml && innerSerialized.length === 0) {
+    return attrsJson
+      ? `<!-- wp:${normalizeName(block.name)} ${attrsJson} /-->`
+      : `<!-- wp:${normalizeName(block.name)} /-->`;
+  }
+
+  const open = attrsJson
+    ? `<!-- wp:${normalizeName(block.name)} ${attrsJson} -->`
+    : `<!-- wp:${normalizeName(block.name)} -->`;
+  const close = `<!-- /wp:${normalizeName(block.name)} -->`;
+
+  const body = [innerHtml, innerSerialized].filter(Boolean).join("\n");
+  return `${open}\n${body}\n${close}`;
+}
+
+/** WP-side 에서 `core/` 는 보통 namespace 생략 (e.g. `<!-- wp:paragraph -->`) */
+function normalizeName(name: string): string {
+  return name.startsWith("core/") ? name.slice("core/".length) : name;
+}
+
+function serializeAttributes(attrs: Record<string, unknown>): string {
+  const keys = Object.keys(attrs);
+  if (keys.length === 0) return "";
+  return JSON.stringify(attrs);
+}
+
+function sanitizeAttributesForExport(block: Block): {
+  attributes: Record<string, unknown>;
+} {
+  // `_id` 와 `metadata.reusableRef` 제거. attributes 안의 임의 키는 그대로 export.
+  return { attributes: { ...block.attributes } };
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// @roottale/cms-core — ADR-0034 §3 §5 (Phase 1 Block JSON foundation)
+export * from "./block";
+export * from "./block-definition";
+export * from "./delimiter";
+export * from "./preview-token";
+export * from "./sanitize";
+export * from "./stable-id";

package/src/preview-token.ts

@@ -0,0 +1,60 @@
+// ADR-0034 §7.1.1 test #10 — Draft preview token sign/verify.
+//
+// HMAC-SHA256 signed token + DB row (post_preview_tokens_v2) lookup.
+// Atomic consume = consumedAt update at verify time.
+//
+// Token format: `<postId>.<expiresAt-ms>.<hmac-base64url>`
+
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+export interface PreviewTokenPayload {
+  postId: string;
+  expiresAt: Date;
+}
+
+const DELIMITER = ".";
+
+function base64url(buf: Buffer): string {
+  return buf.toString("base64url");
+}
+
+function fromBase64url(s: string): Buffer {
+  return Buffer.from(s, "base64url");
+}
+
+function sign(secret: string, message: string): string {
+  return base64url(createHmac("sha256", secret).update(message).digest());
+}
+
+/** 새 preview token 생성. DB insert 책임은 caller. */
+export function issuePreviewToken(
+  secret: string,
+  payload: PreviewTokenPayload,
+): string {
+  const exp = payload.expiresAt.getTime();
+  const nonce = base64url(randomBytes(12));
+  const message = `${payload.postId}${DELIMITER}${exp}${DELIMITER}${nonce}`;
+  const sig = sign(secret, message);
+  return `${message}${DELIMITER}${sig}`;
+}
+
+/** Token 검증 (서명 + 만료). DB row consumed_at update 는 caller (atomic). */
+export function verifyPreviewToken(
+  secret: string,
+  token: string,
+): PreviewTokenPayload | null {
+  const parts = token.split(DELIMITER);
+  if (parts.length !== 4) return null;
+  const [postId, expRaw, nonce, sig] = parts as [string, string, string, string];
+  const exp = Number(expRaw);
+  if (!Number.isFinite(exp)) return null;
+  if (Date.now() > exp) return null;
+
+  const expectedSig = sign(secret, `${postId}${DELIMITER}${exp}${DELIMITER}${nonce}`);
+  const a = fromBase64url(sig);
+  const b = fromBase64url(expectedSig);
+  if (a.length !== b.length) return null;
+  if (!timingSafeEqual(a, b)) return null;
+
+  return { postId, expiresAt: new Date(exp) };
+}

package/src/sanitize.ts

@@ -0,0 +1,39 @@
+// ADR-0034 §7.1.1 test #7 — XSS sanitize helper (minimal allow-list).
+//
+// Phase 1 = strict CSP (`script-src 'self'`) 가 1차 방어. 본 helper 는 2차
+// 방어로 Tiptap output 의 inline `<script>` / `on*` attribute / `javascript:`
+// URL 을 strip. Phase 2 에 본격 sanitize (sanitize-html 또는 DOMPurify).
+
+const SCRIPT_TAG_RE = /<script\b[^>]*>[\s\S]*?<\/script\s*>/gi;
+const ON_EVENT_ATTR_RE = /\s+on[a-z]+\s*=\s*"(?:[^"\\]|\\.)*"/gi;
+const ON_EVENT_ATTR_RE_SINGLE = /\s+on[a-z]+\s*=\s*'(?:[^'\\]|\\.)*'/gi;
+const JS_URL_RE = /\s+(href|src)\s*=\s*(['"])\s*javascript:[^'"]*\2/gi;
+const DATA_URL_RE = /\s+(href|src)\s*=\s*(['"])\s*data:(?!image\/)[^'"]*\2/gi;
+
+/**
+ * 미니멀 XSS sanitize — Tiptap HTML output 또는 rawHtml 의 안전 정리.
+ * Phase 1 acceptance: `<script>alert(1)</script>` 인라인이 inert 가 되어야 함.
+ */
+export function sanitizeHtml(html: string): string {
+  return html
+    .replace(SCRIPT_TAG_RE, "")
+    .replace(ON_EVENT_ATTR_RE, "")
+    .replace(ON_EVENT_ATTR_RE_SINGLE, "")
+    .replace(JS_URL_RE, " $1=\"#\"")
+    .replace(DATA_URL_RE, " $1=\"#\"");
+}
+
+/**
+ * 표준 CSP 헤더 값 (Phase 1 acceptance test #7 정합).
+ * Astro middleware / Next.js header config 에서 사용.
+ */
+export const PHASE_1_CSP =
+  "default-src 'self'; " +
+  "script-src 'self'; " +
+  "style-src 'self' 'unsafe-inline'; " +
+  "img-src 'self' data: https://imagedelivery.net https://*.r2.cloudflarestorage.com; " +
+  "font-src 'self' data:; " +
+  "connect-src 'self'; " +
+  "frame-ancestors 'none'; " +
+  "base-uri 'self'; " +
+  "form-action 'self'";

package/src/stable-id.ts

@@ -0,0 +1,30 @@
+// ADR-0034 §2 P5 — Stable block id (uuidv7 inject)
+//
+// Tiptap 의 BlockId extension 이 본 helper 를 사용해 새 block 에 uuidv7 inject.
+// 기존 block 의 `_id` 는 보존 (revision 간 정합).
+
+import { uuidv7 } from "uuidv7";
+
+import type { Block } from "./block";
+
+/**
+ * Block 에 stable id 주입.
+ * 이미 `_id` 있는 block 은 그대로, 없으면 uuidv7 생성. recursive (innerBlocks).
+ */
+export function ensureStableIds(block: Omit<Block, "_id"> & { _id?: string }): Block {
+  return {
+    ...block,
+    _id: block._id ?? uuidv7(),
+    innerBlocks: (block.innerBlocks ?? []).map((inner) =>
+      ensureStableIds(inner as Omit<Block, "_id"> & { _id?: string }),
+    ),
+  };
+}
+
+/**
+ * 한 번에 block tree 전체에 stable id 주입.
+ * import 또는 새 post 생성 시 entrypoint.
+ */
+export function injectStableIdsTree(blocks: readonly (Omit<Block, "_id"> & { _id?: string })[]): Block[] {
+  return blocks.map((b) => ensureStableIds(b));
+}