@ctcstack/ctcdocs-core 0.15.0 → 0.16.0

package/src/corpus-structure.ts

@@ -0,0 +1,143 @@
+/**
+ * The shape of the synchronized corpus: which folder holds what.
+ *
+ * Access is decided by a document's chain of Drive folders (ADR-039), and that
+ * chain is in the sync manifest. The sync package owns the manifest's full
+ * schema; this reads only the fields the chain needs, so that the build and
+ * the configuration checks can use it without depending on the sync.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { PROJECT_LAYOUT } from './project-layout.js';
+
+export interface CorpusFolder {
+  readonly id: string;
+  /** `null` for the Drive root the sync reads. */
+  readonly parentId: string | null;
+  /** The name in Drive, as typed. */
+  readonly name: string;
+  /** The name the site shows, without an order number. */
+  readonly label: string;
+  /** The folder's address, when it has one; the root has none. */
+  readonly slug: string | undefined;
+}
+
+export interface CorpusDocument {
+  readonly id: string;
+  readonly parentId: string | null;
+  readonly slug: string;
+  /**
+   * The readers the document was last published with (ADR-039). Its class
+   * never reaches beyond them: a move that would widen them waits for a rule
+   * on its new chain to be confirmed.
+   */
+  readonly publishedReaders?: '*' | readonly string[];
+}
+
+export interface CorpusStructure {
+  readonly rootFolderId: string | null;
+  readonly folders: ReadonlyMap<string, CorpusFolder>;
+  readonly documents: ReadonlyMap<string, CorpusDocument>;
+}
+
+export class CorpusStructureError extends Error {
+  override readonly name = 'CorpusStructureError';
+}
+
+export const EMPTY_CORPUS: CorpusStructure = Object.freeze({
+  rootFolderId: null,
+  folders: new Map(),
+  documents: new Map(),
+});
+
+function invalid(path: string): never {
+  throw new CorpusStructureError(
+    `${PROJECT_LAYOUT.manifestFile}: ${path} is not what the sync writes.`,
+  );
+}
+
+function entries(value: unknown, path: string): [string, unknown][] {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    invalid(path);
+  }
+  return Object.entries(value as Record<string, unknown>);
+}
+
+function field(
+  source: unknown,
+  key: string,
+  path: string,
+  nullable = false,
+): string | null {
+  const value = (source as Record<string, unknown>)[key];
+  if (nullable && value === null) {
+    return null;
+  }
+  if (typeof value !== 'string' || value.length === 0) {
+    invalid(`${path}.${key}`);
+  }
+  return value;
+}
+
+/** Reads the folder chain out of a parsed sync manifest. */
+export function parseCorpusStructure(manifest: unknown): CorpusStructure {
+  if (typeof manifest !== 'object' || manifest === null) {
+    invalid('the manifest');
+  }
+  const source = manifest as Record<string, unknown>;
+  const folders = new Map<string, CorpusFolder>();
+  for (const [id, raw] of entries(source.folders, 'folders')) {
+    const path = `folders.${id}`;
+    const slug = (raw as Record<string, unknown>).stableSlug;
+    folders.set(id, {
+      id,
+      parentId: field(raw, 'googleParentId', path, true),
+      name: field(raw, 'googleName', path) ?? '',
+      label: field(raw, 'displayLabel', path) ?? '',
+      slug: typeof slug === 'string' && slug.length > 0 ? slug : undefined,
+    });
+  }
+  const documents = new Map<string, CorpusDocument>();
+  for (const [id, raw] of entries(source.documents, 'documents')) {
+    const path = `documents.${id}`;
+    const published = (raw as Record<string, unknown>).publishedReaders;
+    documents.set(id, {
+      id,
+      parentId: field(raw, 'googleParentId', path, true),
+      slug: field(raw, 'stableSlug', path) ?? '',
+      ...(published === '*' ||
+      (Array.isArray(published) &&
+        published.every((group) => typeof group === 'string'))
+        ? { publishedReaders: published as '*' | readonly string[] }
+        : {}),
+    });
+  }
+  const root = source.rootFolderId;
+  return {
+    rootFolderId: typeof root === 'string' && root.length > 0 ? root : null,
+    folders,
+    documents,
+  };
+}
+
+/**
+ * The corpus of a project, or an empty one before its first sync. A manifest
+ * that exists but cannot be read is an error: guessing an empty corpus there
+ * would decide access without the folders it is about.
+ */
+export function readCorpusStructure(projectRoot: string): CorpusStructure {
+  let text: string;
+  try {
+    text = readFileSync(
+      resolve(projectRoot, PROJECT_LAYOUT.manifestFile),
+      'utf8',
+    );
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return EMPTY_CORPUS;
+    }
+    throw error;
+  }
+  return parseCorpusStructure(JSON.parse(text));
+}

package/src/index.ts

@@ -1,8 +1,10 @@
 export {
+  ACCESS_CLASSES_ROUTE,
   GENERATED_DIRECTORY_ALLOWLIST,
   GENERATED_FILE_ALLOWLIST,
   PLATFORM_ROUTE_HREFS,
   PLATFORM_ROUTES,
+  PLATFORM_WORKERS,
   permanentLinkPath,
   PROJECT_LAYOUT,
   RESERVED_SLUGS,
@@ -18,6 +20,48 @@ export {
   generatedSourceHeader,
 } from './ownership-markers.js';
 export { findProjectRoot, ProjectRootError } from './project-root.js';
+export {
+  EVERY_MEMBER,
+  parseAccessConfiguration,
+} from './access-configuration.js';
+export type {
+  AccessConfiguration,
+  AccessRule,
+} from './access-configuration.js';
+export {
+  CorpusStructureError,
+  EMPTY_CORPUS,
+  parseCorpusStructure,
+  readCorpusStructure,
+} from './corpus-structure.js';
+export type {
+  CorpusDocument,
+  CorpusFolder,
+  CorpusStructure,
+} from './corpus-structure.js';
+export {
+  ADMINS_CLASS,
+  chainReaders,
+  chainRules,
+  classIdentifiers,
+  computeAccessModel,
+  documentClass,
+  folderChain,
+  folderClass,
+  intersectReaders,
+  MEMBERS_CLASS,
+  nextPublishedReaders,
+  widensReaders,
+} from './access-classes.js';
+export type {
+  AccessClass,
+  AccessModel,
+  ChainReaders,
+  PublishedReaders,
+  Readers,
+} from './access-classes.js';
+export { accessFindings } from './access-findings.js';
+export type { AccessFinding } from './access-findings.js';
 export {
   loadSiteConfiguration,
   parseSiteConfiguration,
@@ -32,6 +76,7 @@ export type {
   DeploymentVisibility,
   HomeConfiguration,
   NavigationConfiguration,
+  SignInConfiguration,
   SiteConfiguration,
   SyncConfigurationDefaults,
 } from './site-configuration.js';

package/src/project-layout.ts

@@ -15,6 +15,11 @@ export const PROJECT_LAYOUT = {
   configurationFile: 'site.config.json',
   /** Deployment target. Wrangler reads it itself, so it cannot be generated. */
   wranglerConfigurationFile: 'wrangler.jsonc',
+  /**
+   * The scheduled Worker that keeps the directory snapshot of a private
+   * deployment (ADR-040), deployed beside the site's own Worker.
+   */
+  directoryWranglerConfigurationFile: 'wrangler.directory.jsonc',
   /** Secret-scanning configuration, whose exemptions `validate` checks. */
   gitleaksConfigurationFile: '.gitleaks.toml',
   /** Served verbatim by the Worker. */
@@ -32,6 +37,11 @@ export const PROJECT_LAYOUT = {
   syncReportFile: 'data/latest-sync-report.json',
   /** What each document's opening says about its title (ADR-023). */
   titleReportFile: 'data/title-report.json',
+  /**
+   * Which access class every built file belongs to (ADR-039). Written by the
+   * build outside `dist`, so it is never published, and read by the Worker.
+   */
+  accessMapFile: '.ctcdocs/access-map.json',
 } as const;
 
 /**
@@ -61,15 +71,42 @@ export const PLATFORM_ROUTES = {
   contentHealth: 'content-health',
 } as const;
 
+/**
+ * The platform's Workers, as a project's Wrangler configuration names them
+ * (ADR-038, ADR-040), and the alias under which they import the build's
+ * access map.
+ */
+export const PLATFORM_WORKERS = {
+  gate: 'node_modules/@ctcstack/ctcdocs/worker/index.ts',
+  directory: 'node_modules/@ctcstack/ctcdocs/worker/directory/index.ts',
+  accessMapAlias: 'ctcdocs-access-map',
+  stateBinding: 'KB_STATE',
+  directorySchedule: '*/10 * * * *',
+} as const;
+
+/**
+ * Where the Worker tells a signed-in reader which search bundles, beyond the
+ * members bundle, they may open (ADR-039). Answered `{ "bundles": [...] }`.
+ */
+export const ACCESS_CLASSES_ROUTE = '/_kb/classes';
+
 /** Each platform route as the href a link uses. */
 export const PLATFORM_ROUTE_HREFS = {
   fullIndex: `/${PLATFORM_ROUTES.fullIndex}/`,
   contentHealth: `/${PLATFORM_ROUTES.contentHealth}/`,
 } as const;
 
-export const RESERVED_SLUGS: readonly string[] = Object.freeze(
-  Object.values(PLATFORM_ROUTES),
-);
+/**
+ * Top-level addresses the platform serves beside the corpus: the Worker's
+ * sign-in routes (ADR-038), the search bundles, `/pagefind/` and
+ * `/pagefind-<class>/` (ADR-039), and the original files under `/assets/`.
+ */
+const SERVED_ADDRESSES = ['auth', 'pagefind', 'assets'] as const;
+
+export const RESERVED_SLUGS: readonly string[] = Object.freeze([
+  ...Object.values(PLATFORM_ROUTES),
+  ...SERVED_ADDRESSES,
+]);
 
 /**
  * A short ID: lowercase hexadecimal, six characters unless six collided with

package/src/site-configuration.ts

@@ -14,6 +14,10 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
+import {
+  parseAccessConfiguration,
+  type AccessConfiguration,
+} from './access-configuration.js';
 import { PROJECT_LAYOUT } from './project-layout.js';
 
 export interface BrandConfiguration {
@@ -152,7 +156,24 @@ export interface NavigationConfiguration {
 
 export type AddressPolicy = 'stable' | 'follow-names';
 
+/**
+ * How a private deployment signs readers in (ADR-038): with Google, admitting
+ * only accounts whose `hd` is one of these Workspace domains. An organization
+ * with secondary domains lists each, since `hd` names the domain of a
+ * reader's own primary address.
+ */
+export interface SignInConfiguration {
+  readonly workspaceDomains: readonly string[];
+}
+
 export interface SiteConfiguration {
+  /** Required to serve a private environment through the platform's Worker. */
+  readonly signIn?: SignInConfiguration;
+  /**
+   * Who may read which folder (ADR-039). Absent, every document is open to
+   * every reader the deployment admits, as before access rules existed.
+   */
+  readonly access?: AccessConfiguration;
   readonly brand: BrandConfiguration;
   readonly deployment: DeploymentConfiguration;
   readonly home: HomeConfiguration;
@@ -460,13 +481,68 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
 
   const navigationSource = record(root.navigation, 'navigation');
   const homeSource = record(root.home, 'home');
+  const deployment: DeploymentConfiguration = {
+    environments: environments(deploymentSource),
+    workerName,
+  };
+
+  /*
+   * Rules close folders to some readers, which a public environment cannot
+   * do: everyone may read it. Accepting rules there would promise a boundary
+   * that does not exist.
+   */
+  let access: AccessConfiguration | undefined;
+  if (root.access !== undefined) {
+    const publicEnvironment = Object.entries(deployment.environments).find(
+      ([, environment]) => environment.visibility === 'public',
+    );
+    if (publicEnvironment) {
+      fail(
+        'access',
+        `must not be set while the ${publicEnvironment[0]} environment is public`,
+      );
+    }
+    access = parseAccessConfiguration(root.access, fail);
+  }
+
+  let signIn: SignInConfiguration | undefined;
+  if (root.signIn !== undefined) {
+    const source = record(root.signIn, 'signIn');
+    for (const key of Object.keys(source)) {
+      if (key !== 'workspaceDomains') {
+        fail(`signIn.${key}`, 'is not a known setting');
+      }
+    }
+    const domains = source.workspaceDomains;
+    if (!Array.isArray(domains) || domains.length === 0) {
+      fail('signIn.workspaceDomains', 'must be a non-empty array of domains');
+    }
+    const parsed = domains.map((domain: unknown, index: number) => {
+      const value =
+        typeof domain === 'string' ? domain.trim().toLowerCase() : '';
+      if (
+        !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/u.test(
+          value,
+        )
+      ) {
+        fail(
+          `signIn.workspaceDomains[${index}]`,
+          'must be a domain such as "example.com"',
+        );
+      }
+      return value;
+    });
+    if (new Set(parsed).size !== parsed.length) {
+      fail('signIn.workspaceDomains', 'must not repeat a domain');
+    }
+    signIn = { workspaceDomains: Object.freeze(parsed) };
+  }
 
   return {
+    ...(signIn ? { signIn } : {}),
+    ...(access ? { access } : {}),
     brand,
-    deployment: {
-      environments: environments(deploymentSource),
-      workerName,
-    },
+    deployment,
     home: {
       corpusIndex: optionalFlag(
         homeSource,