stack-site-builder 1.12.0 → 1.14.0

package/src/lib/private.ts

@@ -0,0 +1,129 @@
+/**
+ * Build-side half of private (login-gated) content. Runs only during
+ * `astro build` / `astro dev` (Node): derives the site content key, wraps it
+ * per user, and encrypts rendered HTML. The browser half (login + decrypt)
+ * lives in ./private-client.ts; the whole design is documented in
+ * docs/private-content-design.md.
+ *
+ * Env contract (see .env.sample in a consuming site):
+ *   AAS_PRIVATE_USERS         "id:password,id2:password2" (plaintext passwords)
+ *   AAS_PRIVATE_MASTER_SECRET stable secret K derives from; rotate = global logout
+ *   AAS_PRIVATE_SESSION_DAYS  client session lifetime in days (0 = never; default 30)
+ */
+import { createCipheriv, createHash, hkdfSync, pbkdf2Sync, randomBytes } from 'node:crypto';
+
+/** Must match private-client.ts. */
+export const KDF_ITERATIONS = 600_000;
+const HKDF_INFO = 'aas-private-v1';
+const MIN_PASSWORD_LENGTH = 10;
+
+export interface PrivateUserRecord {
+  /** SHA-256(buildSalt + lowercase(id)), hex — the deployed site never carries raw ids. */
+  h: string;
+  /** PBKDF2 salt, base64. */
+  s: string;
+  /** AES-GCM IV for the wrapped key, base64. */
+  iv: string;
+  /** wrappedK = AES-256-GCM(KEK, K) with auth tag appended, base64. */
+  w: string;
+}
+
+const b64 = (b: Buffer | Uint8Array) => Buffer.from(b).toString('base64');
+
+interface PrivateConfig {
+  key: Buffer; // K — the site content key
+  users: PrivateUserRecord[];
+  buildSalt: string; // base64; used by the client to hash the entered id
+  sessionDays: number;
+}
+
+let cached: PrivateConfig | null = null;
+
+/**
+ * Parse env + derive keys, once per build. Throws (failing the build loudly)
+ * when private entries exist but the env contract isn't met — a misconfigured
+ * build must not ship silently locked-forever pages.
+ */
+function getConfig(): PrivateConfig {
+  if (cached) return cached;
+
+  const secret = process.env.AAS_PRIVATE_MASTER_SECRET?.trim();
+  const usersRaw = process.env.AAS_PRIVATE_USERS?.trim();
+  if (!secret || !usersRaw) {
+    throw new Error(
+      '[private] this site has `private: true` entries, but AAS_PRIVATE_MASTER_SECRET ' +
+        'and/or AAS_PRIVATE_USERS is not set. Set both in .env (locally) or as CI ' +
+        'secrets — see docs/private-content-design.md.',
+    );
+  }
+
+  // K derives from the master secret (not random): ordinary redeploys keep
+  // logged-in devices working; rotating the secret is the global-logout switch.
+  const key = Buffer.from(hkdfSync('sha256', secret, 'aas-private', HKDF_INFO, 32));
+
+  const buildSaltBytes = randomBytes(16);
+  const users: PrivateUserRecord[] = [];
+  const seen = new Set<string>();
+  for (const pair of usersRaw.split(',')) {
+    const idx = pair.indexOf(':');
+    if (idx < 1) throw new Error(`[private] AAS_PRIVATE_USERS entry is not "id:password": "${pair.trim()}"`);
+    const id = pair.slice(0, idx).trim().toLowerCase();
+    const password = pair.slice(idx + 1).trim();
+    if (seen.has(id)) throw new Error(`[private] duplicate user id "${id}" in AAS_PRIVATE_USERS`);
+    seen.add(id);
+    if (password.length < MIN_PASSWORD_LENGTH)
+      throw new Error(
+        `[private] password for user "${id}" is shorter than ${MIN_PASSWORD_LENGTH} chars — ` +
+          'wrapped keys can be brute-forced offline, use a long passphrase',
+      );
+    const salt = randomBytes(16);
+    const kek = pbkdf2Sync(password, salt, KDF_ITERATIONS, 32, 'sha256');
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', kek, iv);
+    const wrapped = Buffer.concat([cipher.update(key), cipher.final(), cipher.getAuthTag()]);
+    users.push({
+      h: createHash('sha256').update(Buffer.concat([buildSaltBytes, Buffer.from(id)])).digest('hex'),
+      s: b64(salt),
+      iv: b64(iv),
+      w: b64(wrapped),
+    });
+  }
+
+  const daysRaw = process.env.AAS_PRIVATE_SESSION_DAYS?.trim();
+  const sessionDays = daysRaw === undefined || daysRaw === '' ? 30 : Number(daysRaw);
+  if (!Number.isFinite(sessionDays) || sessionDays < 0)
+    throw new Error(`[private] AAS_PRIVATE_SESSION_DAYS must be a number ≥ 0 (got "${daysRaw}")`);
+
+  console.warn(
+    '[private] this build contains private entries — remember: the SOURCE repo must be ' +
+      'private (the .mdx files are plaintext); only the built output is encrypted.',
+  );
+
+  cached = { key, users, buildSalt: b64(buildSaltBytes), sessionDays };
+  return cached;
+}
+
+/** Everything PrivateGate embeds for the client (records are ~120 bytes/user). */
+export function privateClientData(): { users: PrivateUserRecord[]; salt: string; days: number } {
+  const { users, buildSalt, sessionDays } = getConfig();
+  return { users, salt: buildSalt, days: sessionDays };
+}
+
+/** AES-256-GCM encrypt rendered HTML with the site content key. */
+export function encryptHtml(html: string): { iv: string; ct: string } {
+  const { key } = getConfig();
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const ct = Buffer.concat([cipher.update(html, 'utf8'), cipher.final(), cipher.getAuthTag()]);
+  return { iv: b64(iv), ct: b64(ct) };
+}
+
+/**
+ * Pathname registry for the sitemap filter: PrivateGate records every private
+ * page it renders; index.mjs (a separate module graph — hence globalThis) reads
+ * it in the sitemap `filter`, which @astrojs/sitemap runs after the pages built.
+ */
+export function registerPrivatePath(pathname: string): void {
+  const g = globalThis as { __aasPrivatePaths?: Set<string> };
+  (g.__aasPrivatePaths ??= new Set()).add(pathname.replace(/\/?$/, '/'));
+}

package/src/lib/reinit.ts

@@ -0,0 +1,12 @@
+/**
+ * Run a DOM-wiring routine now AND again whenever private content is decrypted
+ * and injected (the injected HTML wasn't there when page scripts first ran).
+ * Component scripts whose targets can sit inside a private gate wrap their init
+ * in this. `fn` must be idempotent or guard against double-wiring itself.
+ */
+export const PRIVATE_DECRYPTED_EVENT = 'aas:private-decrypted';
+
+export function initOnReady(fn: () => void): void {
+  fn();
+  document.addEventListener(PRIVATE_DECRYPTED_EVENT, () => fn());
+}

package/src/lib/sections.ts

@@ -0,0 +1,34 @@
+import { site } from '@aas-data/site';
+
+/**
+ * Optional content sections a site can turn off. The core catalog (home, stack
+ * detail, categories, tags, vendors) is always on; these are opt-out. Disabling
+ * one removes both its routes and its header-nav item (routes are skipped in the
+ * integration, the nav link in BaseLayout).
+ *
+ * `pages` is the standalone-pages collection (About/소개, contact, …); turning it
+ * off drops every page and its nav item at once — finer control is per-page via
+ * the `nav` / `draft` frontmatter, or by not authoring the page.
+ *
+ * A site sets overrides in `src/data/site.ts` (`sections`), which astro.config
+ * also forwards to the theme integration for route filtering. Omitted = enabled.
+ */
+export type SectionKey = 'concepts' | 'articles' | 'samples' | 'slides' | 'glossary' | 'pages';
+
+const DEFAULTS: Record<SectionKey, boolean> = {
+  concepts: true,
+  articles: true,
+  samples: true,
+  slides: true,
+  glossary: true,
+  pages: true,
+};
+
+/** Whether each optional section is enabled, after applying the site's overrides. */
+export const sections: Record<SectionKey, boolean> = {
+  ...DEFAULTS,
+  ...((site as { sections?: Partial<Record<SectionKey, boolean>> }).sections ?? {}),
+};
+
+/** True unless the site explicitly turned `key` off. */
+export const sectionEnabled = (key: SectionKey): boolean => sections[key];

package/src/pages/[...lang]/[page].astro

@@ -3,6 +3,7 @@ import { site } from '@aas-data/site';
 import type { GetStaticPaths } from 'astro';
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import PageDetail from '../../components/PageDetail.astro';
+import PrivateGate from '../../components/PrivateGate.astro';
 import { getPages, pageSlugOf } from '../../lib/pages';
 import { allLocales, langParam } from '../../lib/locales';
 
@@ -18,13 +19,17 @@ export const getStaticPaths = (async () => {
 
 const { lang, entry } = Astro.props;
 const slug = pageSlugOf(entry);
+const priv = entry.data.private;
 ---
 
 <BaseLayout
   title={`${entry.data.title} — ${site.name}`}
-  description={entry.data.description}
+  description={priv ? entry.data.teaser : entry.data.description}
   lang={lang}
   path={`${slug}/`}
+  noindex={priv}
 >
-  <PageDetail entry={entry} lang={lang} />
+  <PrivateGate enabled={priv} lang={lang} title={entry.data.title} teaser={entry.data.teaser}>
+    <PageDetail entry={entry} lang={lang} />
+  </PrivateGate>
 </BaseLayout>

package/src/pages/[...lang]/article/[...id].astro

@@ -3,6 +3,7 @@ import { site } from '@aas-data/site';
 import type { GetStaticPaths } from 'astro';
 import BaseLayout from '../../../layouts/BaseLayout.astro';
 import ArticleDetail from '../../../components/ArticleDetail.astro';
+import PrivateGate from '../../../components/PrivateGate.astro';
 import { getArticles, articleSlugOf } from '../../../lib/articles';
 import { allLocales, langParam } from '../../../lib/locales';
 
@@ -18,13 +19,17 @@ export const getStaticPaths = (async () => {
 
 const { lang, entry } = Astro.props;
 const slug = articleSlugOf(entry);
+const priv = entry.data.private;
 ---
 
 <BaseLayout
   title={`${entry.data.title} — ${site.name}`}
-  description={entry.data.description}
+  description={priv ? entry.data.teaser : entry.data.description}
   lang={lang}
   path={`article/${slug}/`}
+  noindex={priv}
 >
-  <ArticleDetail entry={entry} lang={lang} />
+  <PrivateGate enabled={priv} lang={lang} title={entry.data.title} teaser={entry.data.teaser}>
+    <ArticleDetail entry={entry} lang={lang} />
+  </PrivateGate>
 </BaseLayout>

package/src/pages/[...lang]/concept/[...id].astro

@@ -3,6 +3,7 @@ import { site } from '@aas-data/site';
 import type { GetStaticPaths } from 'astro';
 import BaseLayout from '../../../layouts/BaseLayout.astro';
 import ConceptDetail from '../../../components/ConceptDetail.astro';
+import PrivateGate from '../../../components/PrivateGate.astro';
 import { getConcepts, conceptSlugOf } from '../../../lib/concepts';
 import { allLocales, langParam } from '../../../lib/locales';
 
@@ -18,13 +19,17 @@ export const getStaticPaths = (async () => {
 
 const { lang, entry } = Astro.props;
 const slug = conceptSlugOf(entry);
+const priv = entry.data.private;
 ---
 
 <BaseLayout
   title={`${entry.data.title} — ${site.name}`}
-  description={entry.data.description}
+  description={priv ? entry.data.teaser : entry.data.description}
   lang={lang}
   path={`concept/${slug}/`}
+  noindex={priv}
 >
-  <ConceptDetail entry={entry} lang={lang} />
+  <PrivateGate enabled={priv} lang={lang} title={entry.data.title} teaser={entry.data.teaser}>
+    <ConceptDetail entry={entry} lang={lang} />
+  </PrivateGate>
 </BaseLayout>

package/src/pages/[...lang]/stack/[...id].astro

@@ -4,6 +4,7 @@ import type { GetStaticPaths } from 'astro';
 import { getRelativeLocaleUrl } from 'astro:i18n';
 import BaseLayout from '../../../layouts/BaseLayout.astro';
 import StackDetail from '../../../components/StackDetail.astro';
+import PrivateGate from '../../../components/PrivateGate.astro';
 import { getStacks, getStackAliases, slugOf, type StackEntry } from '../../../lib/stacks';
 import { allLocales, langParam } from '../../../lib/locales';
 
@@ -28,6 +29,7 @@ const { lang, entry, redirectTo } = Astro.props as {
   redirectTo: string | null;
 };
 const target = redirectTo ? getRelativeLocaleUrl(lang, `stack/${redirectTo}/`) : null;
+const priv = entry?.data.private ?? false;
 ---
 
 {
@@ -48,11 +50,14 @@ const target = redirectTo ? getRelativeLocaleUrl(lang, `stack/${redirectTo}/`) :
   ) : (
     <BaseLayout
       title={`${entry!.data.name} — ${site.name}`}
-      description={entry!.data.description}
+      description={priv ? entry!.data.teaser : entry!.data.description}
       lang={lang}
       path={`stack/${slugOf(entry!)}/`}
+      noindex={priv}
     >
-      <StackDetail entry={entry!} lang={lang} />
+      <PrivateGate enabled={priv} lang={lang} title={entry!.data.name} teaser={entry!.data.teaser}>
+        <StackDetail entry={entry!} lang={lang} />
+      </PrivateGate>
     </BaseLayout>
   )
 }