@ctcstack/ctcdocs-core 0.14.0 → 0.16.0

package/dist/corpus-structure.d.ts

@@ -0,0 +1,39 @@
+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 declare class CorpusStructureError extends Error {
+    readonly name = "CorpusStructureError";
+}
+export declare const EMPTY_CORPUS: CorpusStructure;
+/** Reads the folder chain out of a parsed sync manifest. */
+export declare function parseCorpusStructure(manifest: unknown): CorpusStructure;
+/**
+ * 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 declare function readCorpusStructure(projectRoot: string): CorpusStructure;

package/dist/corpus-structure.js

@@ -0,0 +1,96 @@
+/**
+ * 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 class CorpusStructureError extends Error {
+    name = 'CorpusStructureError';
+}
+export const EMPTY_CORPUS = Object.freeze({
+    rootFolderId: null,
+    folders: new Map(),
+    documents: new Map(),
+});
+function invalid(path) {
+    throw new CorpusStructureError(`${PROJECT_LAYOUT.manifestFile}: ${path} is not what the sync writes.`);
+}
+function entries(value, path) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        invalid(path);
+    }
+    return Object.entries(value);
+}
+function field(source, key, path, nullable = false) {
+    const value = source[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) {
+    if (typeof manifest !== 'object' || manifest === null) {
+        invalid('the manifest');
+    }
+    const source = manifest;
+    const folders = new Map();
+    for (const [id, raw] of entries(source.folders, 'folders')) {
+        const path = `folders.${id}`;
+        const slug = raw.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();
+    for (const [id, raw] of entries(source.documents, 'documents')) {
+        const path = `documents.${id}`;
+        const published = raw.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 }
+                : {}),
+        });
+    }
+    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) {
+    let text;
+    try {
+        text = readFileSync(resolve(projectRoot, PROJECT_LAYOUT.manifestFile), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return EMPTY_CORPUS;
+        }
+        throw error;
+    }
+    return parseCorpusStructure(JSON.parse(text));
+}

package/dist/index.d.ts

@@ -1,6 +1,14 @@
-export { GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, permanentLinkPath, PROJECT_LAYOUT, RESERVED_SLUGS, SHORT_ID_PATTERN, } from './project-layout.js';
+export { ACCESS_CLASSES_ROUTE, GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, PLATFORM_WORKERS, permanentLinkPath, PROJECT_LAYOUT, RESERVED_SLUGS, SHORT_ID_PATTERN, } from './project-layout.js';
 export { assertGeneratedPathAllowed, isGeneratedPathAllowed, normalizeRepositoryPath, } from './generated-paths.js';
 export { generatedMarkdownHeader, 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, SiteConfigurationError, } from './site-configuration.js';
-export type { AddressPolicy, BrandConfiguration, DeploymentConfiguration, DeploymentEnvironmentConfiguration, DeploymentEnvironmentConfigurations, DeploymentVisibility, HomeConfiguration, NavigationConfiguration, SiteConfiguration, SyncConfigurationDefaults, } from './site-configuration.js';
+export type { AddressPolicy, BrandConfiguration, DeploymentConfiguration, DeploymentEnvironmentConfiguration, DeploymentEnvironmentConfigurations, DeploymentVisibility, HomeConfiguration, NavigationConfiguration, SignInConfiguration, SiteConfiguration, SyncConfigurationDefaults, } from './site-configuration.js';

package/dist/index.js

@@ -1,5 +1,9 @@
-export { GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, permanentLinkPath, PROJECT_LAYOUT, RESERVED_SLUGS, SHORT_ID_PATTERN, } from './project-layout.js';
+export { ACCESS_CLASSES_ROUTE, GENERATED_DIRECTORY_ALLOWLIST, GENERATED_FILE_ALLOWLIST, PLATFORM_ROUTE_HREFS, PLATFORM_ROUTES, PLATFORM_WORKERS, permanentLinkPath, PROJECT_LAYOUT, RESERVED_SLUGS, SHORT_ID_PATTERN, } from './project-layout.js';
 export { assertGeneratedPathAllowed, isGeneratedPathAllowed, normalizeRepositoryPath, } from './generated-paths.js';
 export { generatedMarkdownHeader, generatedSourceHeader, } from './ownership-markers.js';
 export { findProjectRoot, ProjectRootError } from './project-root.js';
+export { EVERY_MEMBER, parseAccessConfiguration, } from './access-configuration.js';
+export { CorpusStructureError, EMPTY_CORPUS, parseCorpusStructure, readCorpusStructure, } from './corpus-structure.js';
+export { ADMINS_CLASS, chainReaders, chainRules, classIdentifiers, computeAccessModel, documentClass, folderChain, folderClass, intersectReaders, MEMBERS_CLASS, nextPublishedReaders, widensReaders, } from './access-classes.js';
+export { accessFindings } from './access-findings.js';
 export { loadSiteConfiguration, parseSiteConfiguration, SiteConfigurationError, } from './site-configuration.js';

package/dist/project-layout.d.ts

@@ -15,6 +15,11 @@ export declare const PROJECT_LAYOUT: {
     readonly configurationFile: "site.config.json";
     /** Deployment target. Wrangler reads it itself, so it cannot be generated. */
     readonly wranglerConfigurationFile: "wrangler.jsonc";
+    /**
+     * The scheduled Worker that keeps the directory snapshot of a private
+     * deployment (ADR-040), deployed beside the site's own Worker.
+     */
+    readonly directoryWranglerConfigurationFile: "wrangler.directory.jsonc";
     /** Secret-scanning configuration, whose exemptions `validate` checks. */
     readonly gitleaksConfigurationFile: ".gitleaks.toml";
     /** Served verbatim by the Worker. */
@@ -32,6 +37,11 @@ export declare const PROJECT_LAYOUT: {
     readonly syncReportFile: "data/latest-sync-report.json";
     /** What each document's opening says about its title (ADR-023). */
     readonly 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.
+     */
+    readonly accessMapFile: ".ctcdocs/access-map.json";
 };
 /**
  * Addresses the platform serves itself.
@@ -59,6 +69,23 @@ export declare const PLATFORM_ROUTES: {
      */
     readonly contentHealth: "content-health";
 };
+/**
+ * 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 declare const PLATFORM_WORKERS: {
+    readonly gate: "node_modules/@ctcstack/ctcdocs/worker/index.ts";
+    readonly directory: "node_modules/@ctcstack/ctcdocs/worker/directory/index.ts";
+    readonly accessMapAlias: "ctcdocs-access-map";
+    readonly stateBinding: "KB_STATE";
+    readonly directorySchedule: "*/10 * * * *";
+};
+/**
+ * Where the Worker tells a signed-in reader which search bundles, beyond the
+ * members bundle, they may open (ADR-039). Answered `{ "bundles": [...] }`.
+ */
+export declare const ACCESS_CLASSES_ROUTE = "/_kb/classes";
 /** Each platform route as the href a link uses. */
 export declare const PLATFORM_ROUTE_HREFS: {
     readonly fullIndex: "/documents/";

package/dist/project-layout.js

@@ -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',
 };
 /**
  * Addresses the platform serves itself.
@@ -59,12 +69,38 @@ export const PLATFORM_ROUTES = {
      */
     contentHealth: 'content-health',
 };
+/**
+ * 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 * * * *',
+};
+/**
+ * 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}/`,
 };
-export const RESERVED_SLUGS = 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'];
+export const RESERVED_SLUGS = Object.freeze([
+    ...Object.values(PLATFORM_ROUTES),
+    ...SERVED_ADDRESSES,
+]);
 /**
  * A short ID: lowercase hexadecimal, six characters unless six collided with
  * another item's, in which case it is longer. It is recorded once per item and

package/dist/site-configuration.d.ts

@@ -1,3 +1,4 @@
+import { type AccessConfiguration } from './access-configuration.js';
 export interface BrandConfiguration {
     /** The organization or product the documentation belongs to. */
     readonly name: string;
@@ -125,7 +126,23 @@ export interface NavigationConfiguration {
     readonly addresses: AddressPolicy;
 }
 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;

package/dist/site-configuration.js

@@ -13,6 +13,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { parseAccessConfiguration, } from './access-configuration.js';
 import { PROJECT_LAYOUT } from './project-layout.js';
 export class SiteConfigurationError extends Error {
     name = 'SiteConfigurationError';
@@ -227,12 +228,52 @@ export function parseSiteConfiguration(input) {
     }
     const navigationSource = record(root.navigation, 'navigation');
     const homeSource = record(root.home, 'home');
+    const deployment = {
+        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;
+    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;
+    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, index) => {
+            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, 'corpusIndex', 'home.corpusIndex', true),
             lede: text(homeSource, 'lede', 'home.lede'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctcstack/ctcdocs-core",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Configuration schema, project layout, and generated-path allowlist shared by the CTCDocs platform packages.",
   "keywords": [
     "ctcdocs",