@ctcstack/ctcdocs-core 0.14.0 → 0.16.0

package/src/access-classes.ts

@@ -0,0 +1,384 @@
+/**
+ * Which readers each folder and document has, grouped into access classes
+ * (ADR-039).
+ *
+ * A document's readers are the groups every rule on its folder chain names:
+ * the set intersection of those rules, where `"*"` names every member and
+ * leaves the set as it is. A chain with no rule at all is closed to everyone
+ * but the admin groups. Documents with the same readers share a class, and a
+ * class is what the build files, search bundles and, later, the Worker work
+ * with.
+ *
+ * The model is a pure function of the configuration and the corpus, so the
+ * same input always yields the same classes and the same identifiers.
+ */
+import { createHash } from 'node:crypto';
+
+import {
+  EVERY_MEMBER,
+  type AccessConfiguration,
+  type AccessRule,
+} from './access-configuration.js';
+import type { CorpusStructure } from './corpus-structure.js';
+
+/** Every signed-in member may read it. */
+export const MEMBERS_CLASS = 'members';
+/** Only the admin groups may read it: closed, or with no reader left. */
+export const ADMINS_CLASS = 'admins';
+
+/** `"*"`, or the sorted group addresses that may read; empty means none. */
+export type Readers = typeof EVERY_MEMBER | readonly string[];
+
+export interface AccessClass {
+  readonly id: string;
+  readonly readers: Readers;
+}
+
+export interface AccessModel {
+  /** Whether the project has an `access` section at all. */
+  readonly enabled: boolean;
+  readonly admins: readonly string[];
+  /** Every class in use, by identifier. */
+  readonly classes: Readonly<Record<string, AccessClass>>;
+  /** Class of every folder in the corpus, by Drive ID. */
+  readonly folders: Readonly<Record<string, string>>;
+  /** Class of every document in the corpus, by Drive ID. */
+  readonly documents: Readonly<Record<string, string>>;
+}
+
+/** What the rules on a folder's chain amount to. */
+export type ChainReaders =
+  | { readonly kind: 'no-rule' }
+  | { readonly kind: 'broken' }
+  | { readonly kind: 'readers'; readonly readers: Readers };
+
+const CLASS_ID_DOMAIN = 'ctcdocs-access-class/v1\n';
+const CLASS_ID_LENGTH = 8;
+
+/** The groups both reader sets admit; `"*"` admits every group. */
+export function intersectReaders(left: Readers, right: Readers): Readers {
+  return intersect(left, right);
+}
+
+/** Whether `current` admits a group that `previous` did not. */
+export function widensReaders(current: Readers, previous: Readers): boolean {
+  if (previous === EVERY_MEMBER) {
+    return false;
+  }
+  if (current === EVERY_MEMBER) {
+    return true;
+  }
+  return current.some((group) => !previous.includes(group));
+}
+
+function intersect(left: Readers, right: Readers): Readers {
+  if (left === EVERY_MEMBER) {
+    return right;
+  }
+  if (right === EVERY_MEMBER) {
+    return left;
+  }
+  const keep = new Set(right);
+  return left.filter((group) => keep.has(group));
+}
+
+function readersOf(rule: AccessRule): Readers {
+  return rule.readers.includes(EVERY_MEMBER) ? EVERY_MEMBER : rule.readers;
+}
+
+/**
+ * The rules on a folder's chain, from the folder up to the root. A chain that
+ * loops or names a parent the corpus does not have is `broken`, and decides
+ * nothing: a folder whose place is unknown is closed.
+ */
+export function chainReaders(
+  folderId: string | null,
+  rules: ReadonlyMap<string, AccessRule>,
+  corpus: CorpusStructure,
+): ChainReaders {
+  let readers: Readers | undefined;
+  const seen = new Set<string>();
+  let current = folderId ?? corpus.rootFolderId;
+  while (current !== null) {
+    if (seen.has(current)) {
+      return { kind: 'broken' };
+    }
+    seen.add(current);
+    const rule = rules.get(current);
+    if (rule) {
+      readers =
+        readers === undefined
+          ? readersOf(rule)
+          : intersect(readers, readersOf(rule));
+    }
+    const folder = corpus.folders.get(current);
+    if (!folder) {
+      if (current === corpus.rootFolderId) {
+        break;
+      }
+      return { kind: 'broken' };
+    }
+    current = folder.parentId;
+  }
+  return readers === undefined
+    ? { kind: 'no-rule' }
+    : { kind: 'readers', readers };
+}
+
+/**
+ * The folders on a folder's chain, from the folder up to the root, as far as
+ * the corpus knows them. Two documents in the same place have the same chain;
+ * a move in Drive changes it, and a change to the rules does not.
+ */
+export function folderChain(
+  folderId: string | null,
+  corpus: CorpusStructure,
+): string[] {
+  const chain: string[] = [];
+  let current = folderId ?? corpus.rootFolderId;
+  while (current !== null && !chain.includes(current)) {
+    chain.push(current);
+    current = corpus.folders.get(current)?.parentId ?? null;
+  }
+  return chain;
+}
+
+/**
+ * The access rules on a chain as one comparable value: adding, removing or
+ * changing the readers of any of them changes it, and a label does not.
+ */
+export function chainRules(
+  chain: readonly string[],
+  rules: ReadonlyMap<string, AccessRule>,
+): string {
+  const named = chain.flatMap((folder) => {
+    const rule = rules.get(folder);
+    return rule ? [`${folder}=${[...rule.readers].sort().join(',')}`] : [];
+  });
+  return createHash('sha256')
+    .update(`ctcdocs-chain-rules/v1\n${named.join('\n')}`)
+    .digest('hex')
+    .slice(0, 16);
+}
+
+/** The readers a document was last published with, and from where. */
+export interface PublishedReaders {
+  readonly readers: Readers;
+  /** Its folder chain when it was published there. */
+  readonly chain: readonly string[];
+  /**
+   * Set while a move that would widen its readers waits: the chain it moved
+   * to, and the rules on that chain when it arrived.
+   */
+  readonly held?: { readonly chain: readonly string[]; readonly rules: string };
+}
+
+function sameChain(left: readonly string[], right: readonly string[]): boolean {
+  return (
+    left.length === right.length &&
+    left.every((folder, index) => folder === right[index])
+  );
+}
+
+/**
+ * The readers a document is published with this time (ADR-039).
+ *
+ * A change to the rules is reviewed where the configuration is, so it takes
+ * effect at once, wider or narrower. A move in Drive is not reviewed: one that
+ * would give the document readers it did not have keeps the readers both
+ * places allow, until a rule on the new chain is added or changed. A move that
+ * narrows, or a move back, takes effect at once.
+ */
+export function nextPublishedReaders(
+  current: {
+    readonly readers: Readers;
+    readonly chain: readonly string[];
+    readonly rules: string;
+  },
+  previous: Partial<PublishedReaders> | undefined,
+): { readonly published: PublishedReaders; readonly held: boolean } {
+  const settled = {
+    published: { readers: current.readers, chain: current.chain },
+    held: false,
+  };
+  if (previous?.readers === undefined || previous.chain === undefined) {
+    return settled;
+  }
+  if (
+    sameChain(current.chain, previous.chain) ||
+    !widensReaders(current.readers, previous.readers)
+  ) {
+    return settled;
+  }
+  const waiting =
+    previous.held !== undefined && sameChain(previous.held.chain, current.chain)
+      ? previous.held
+      : undefined;
+  if (waiting && waiting.rules !== current.rules) {
+    return settled;
+  }
+  return {
+    published: {
+      readers: intersect(current.readers, previous.readers),
+      chain: previous.chain,
+      held: waiting ?? { chain: current.chain, rules: current.rules },
+    },
+    held: true,
+  };
+}
+
+function readerKey(readers: readonly string[]): string {
+  return readers.join('\n');
+}
+
+function fullDigest(readers: readonly string[]): string {
+  return createHash('sha256')
+    .update(CLASS_ID_DOMAIN + readerKey(readers))
+    .digest('hex');
+}
+
+/**
+ * Short, stable identifiers for reader sets. Each is the start of a digest of
+ * the set; when two sets share a start, both are lengthened until they
+ * differ, so every other identifier is unaffected.
+ */
+export function classIdentifiers(
+  readerSets: readonly (readonly string[])[],
+): Map<string, string> {
+  const digests = new Map<string, string>();
+  for (const readers of readerSets) {
+    digests.set(readerKey(readers), fullDigest(readers));
+  }
+  const ids = new Map<string, string>();
+  const keys = [...digests.keys()];
+  for (const key of keys) {
+    const digest = digests.get(key) as string;
+    let length = CLASS_ID_LENGTH;
+    for (const other of keys) {
+      if (other === key) {
+        continue;
+      }
+      const otherDigest = digests.get(other) as string;
+      while (
+        length < digest.length &&
+        digest.slice(0, length) === otherDigest.slice(0, length)
+      ) {
+        length += 1;
+      }
+    }
+    ids.set(key, digest.slice(0, length));
+  }
+  return ids;
+}
+
+function sortedRecord<T>(entries: Iterable<[string, T]>): Record<string, T> {
+  return Object.fromEntries(
+    [...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+  );
+}
+
+/**
+ * Classes for every folder and document. Without an `access` section the whole
+ * corpus is the members class, as it was before access rules existed.
+ */
+export function computeAccessModel(
+  access: AccessConfiguration | undefined,
+  corpus: CorpusStructure,
+): AccessModel {
+  const membersOnly: AccessClass = { id: MEMBERS_CLASS, readers: EVERY_MEMBER };
+  if (!access) {
+    return {
+      enabled: false,
+      admins: [],
+      classes: { [MEMBERS_CLASS]: membersOnly },
+      folders: sortedRecord(
+        [...corpus.folders.keys()].map((id) => [id, MEMBERS_CLASS]),
+      ),
+      documents: sortedRecord(
+        [...corpus.documents.keys()].map((id) => [id, MEMBERS_CLASS]),
+      ),
+    };
+  }
+
+  const rules = new Map(access.rules.map((rule) => [rule.folder, rule]));
+  const folderReaders = new Map<string, Readers>();
+  const readersFor = (folderId: string | null): Readers => {
+    const key = folderId ?? corpus.rootFolderId ?? '';
+    const cached = folderReaders.get(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const chain = chainReaders(folderId, rules, corpus);
+    const readers = chain.kind === 'readers' ? chain.readers : [];
+    folderReaders.set(key, readers);
+    return readers;
+  };
+
+  const folderSets = new Map<string, Readers>();
+  for (const id of corpus.folders.keys()) {
+    folderSets.set(id, readersFor(id));
+  }
+  const documentSets = new Map<string, Readers>();
+  for (const document of corpus.documents.values()) {
+    const readers = readersFor(document.parentId);
+    documentSets.set(
+      document.id,
+      document.publishedReaders === undefined
+        ? readers
+        : intersect(readers, document.publishedReaders),
+    );
+  }
+
+  const groupSets = [...folderSets.values(), ...documentSets.values()].filter(
+    (readers): readers is readonly string[] =>
+      readers !== EVERY_MEMBER && readers.length > 0,
+  );
+  const ids = classIdentifiers(groupSets);
+  const classes = new Map<string, AccessClass>([[MEMBERS_CLASS, membersOnly]]);
+  const classOf = (readers: Readers): string => {
+    if (readers === EVERY_MEMBER) {
+      return MEMBERS_CLASS;
+    }
+    if (readers.length === 0) {
+      classes.set(ADMINS_CLASS, { id: ADMINS_CLASS, readers: [] });
+      return ADMINS_CLASS;
+    }
+    const id = ids.get(readerKey(readers)) as string;
+    classes.set(id, { id, readers });
+    return id;
+  };
+
+  return {
+    enabled: true,
+    admins: access.admins,
+    folders: sortedRecord(
+      [...folderSets].map(([id, readers]) => [id, classOf(readers)]),
+    ),
+    documents: sortedRecord(
+      [...documentSets].map(([id, readers]) => [id, classOf(readers)]),
+    ),
+    classes: sortedRecord(classes),
+  };
+}
+
+/**
+ * A document's class. A document the model does not know — written after the
+ * manifest was read — is closed when rules exist and open when they do not.
+ */
+export function documentClass(
+  model: AccessModel,
+  documentId: string | undefined,
+): string {
+  const known =
+    documentId === undefined ? undefined : model.documents[documentId];
+  return known ?? (model.enabled ? ADMINS_CLASS : MEMBERS_CLASS);
+}
+
+/** A folder's class, closed when unknown under rules, as for documents. */
+export function folderClass(
+  model: AccessModel,
+  folderId: string | undefined,
+): string {
+  const known = folderId === undefined ? undefined : model.folders[folderId];
+  return known ?? (model.enabled ? ADMINS_CLASS : MEMBERS_CLASS);
+}

package/src/access-configuration.ts

@@ -0,0 +1,139 @@
+/**
+ * Who may read which folder (ADR-039).
+ *
+ * A project names its admin groups and, per Drive folder, the Google groups
+ * that may read it. The folder is named by its Drive ID, so a rename moves
+ * nothing, and the rule carries the folder's name as a label a reviewer can
+ * read; the label is checked against the corpus and reported when it drifts,
+ * never failing a sync.
+ *
+ * Group addresses are compared case-insensitively by Google, so they are
+ * lowercased here once and compared exactly everywhere else.
+ */
+
+/** A reader value meaning every signed-in member of the organization. */
+export const EVERY_MEMBER = '*';
+
+export interface AccessRule {
+  /** The Drive folder the rule covers, with everything below it. */
+  readonly folder: string;
+  /** The folder's name as the rule's author knew it, for review. */
+  readonly label: string;
+  /**
+   * Group addresses, sorted, or `["*"]` for every member. A folder's readers
+   * are the groups every rule on its chain names (ADR-039).
+   */
+  readonly readers: readonly string[];
+}
+
+export interface AccessConfiguration {
+  /** Groups that read every folder, including folders without a rule. */
+  readonly admins: readonly string[];
+  readonly rules: readonly AccessRule[];
+}
+
+type Fail = (path: string, expectation: string) => never;
+
+const GROUP_ADDRESS =
+  /^[a-z0-9](?:[a-z0-9._%+-]*[a-z0-9])?@[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/u;
+
+/** The characters Google uses in file and folder IDs. */
+const FOLDER_ID = /^[A-Za-z0-9_-]{1,128}$/u;
+
+function object(
+  value: unknown,
+  path: string,
+  fail: Fail,
+): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    fail(path, 'must be an object');
+  }
+  return value as Record<string, unknown>;
+}
+
+/**
+ * A misspelled key would otherwise be ignored and leave a folder governed by a
+ * rule its author did not write, so an unknown key is an error.
+ */
+function knownKeys(
+  source: Record<string, unknown>,
+  allowed: readonly string[],
+  path: string,
+  fail: Fail,
+): void {
+  for (const key of Object.keys(source)) {
+    if (!allowed.includes(key)) {
+      fail(`${path}.${key}`, 'is not a known setting');
+    }
+  }
+}
+
+function groupAddress(value: unknown, path: string, fail: Fail): string {
+  const address = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (!GROUP_ADDRESS.test(address)) {
+    fail(path, 'must be a group address such as "team@example.com"');
+  }
+  return address;
+}
+
+function groupList(
+  value: unknown,
+  path: string,
+  fail: Fail,
+  allowEveryMember: boolean,
+): readonly string[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    fail(path, 'must be a non-empty array of group addresses');
+  }
+  if (allowEveryMember && value.includes(EVERY_MEMBER)) {
+    if (value.length !== 1) {
+      fail(path, `must be ["${EVERY_MEMBER}"] alone, or group addresses`);
+    }
+    return Object.freeze([EVERY_MEMBER]);
+  }
+  const groups = value.map((entry, index) =>
+    groupAddress(entry, `${path}[${index}]`, fail),
+  );
+  if (new Set(groups).size !== groups.length) {
+    fail(path, 'must not repeat a group');
+  }
+  return Object.freeze([...groups].sort());
+}
+
+export function parseAccessConfiguration(
+  value: unknown,
+  fail: Fail,
+): AccessConfiguration {
+  const source = object(value, 'access', fail);
+  knownKeys(source, ['admins', 'rules'], 'access', fail);
+  const admins = groupList(source.admins, 'access.admins', fail, false);
+
+  if (!Array.isArray(source.rules)) {
+    fail('access.rules', 'must be an array');
+  }
+  const folders = new Set<string>();
+  const rules = source.rules.map((raw: unknown, index: number) => {
+    const path = `access.rules[${index}]`;
+    const rule = object(raw, path, fail);
+    knownKeys(rule, ['folder', 'label', 'readers'], path, fail);
+    const folder = typeof rule.folder === 'string' ? rule.folder : '';
+    if (!FOLDER_ID.test(folder)) {
+      fail(`${path}.folder`, 'must be a Drive folder ID');
+    }
+    if (folders.has(folder)) {
+      fail(`${path}.folder`, 'must not have a second rule');
+    }
+    folders.add(folder);
+    const label = typeof rule.label === 'string' ? rule.label.trim() : '';
+    if (label.length === 0) {
+      fail(`${path}.label`, "must be the folder's name");
+    }
+    return Object.freeze({
+      folder,
+      label,
+      readers: groupList(rule.readers, `${path}.readers`, fail, true),
+    });
+  });
+
+  return Object.freeze({ admins, rules: Object.freeze(rules) });
+}

package/src/access-findings.ts

@@ -0,0 +1,183 @@
+/**
+ * What a reviewer should know about the access rules (ADR-039).
+ *
+ * None of these stops a sync: the content health page and the sync job summary
+ * list them. A closed folder is the safe outcome of a missing rule, and a label
+ * that drifted is a note for the next pull request, not an outage.
+ */
+import {
+  EVERY_MEMBER,
+  type AccessConfiguration,
+} from './access-configuration.js';
+import { chainReaders } from './access-classes.js';
+import type { CorpusFolder, CorpusStructure } from './corpus-structure.js';
+
+interface FolderPlace {
+  /** The Drive ID the finding is about. */
+  readonly folder: string;
+  /** The folder's name as the site shows it. */
+  readonly name: string;
+  /** Names of the folders above it, from the top; empty at the top. */
+  readonly trail: readonly string[];
+}
+
+export type AccessFinding =
+  | (FolderPlace & {
+      /** Documents in it, and in its folders without a rule, closed to all but admins. */
+      readonly code: 'folder-without-rule';
+      readonly documents: number;
+    })
+  | (FolderPlace & {
+      /** The rule's label no longer matches the folder's name. */
+      readonly code: 'rule-label-outdated';
+      readonly label: string;
+    })
+  | {
+      /** The rule names a folder the corpus does not have. */
+      readonly code: 'rule-folder-missing';
+      readonly folder: string;
+      readonly label: string;
+    }
+  | (FolderPlace & {
+      /** Groups the rule names that a rule above does not, which admit no one. */
+      readonly code: 'rule-group-not-admitted-above';
+      readonly label: string;
+      readonly groups: readonly string[];
+    });
+
+const ORDER: Record<AccessFinding['code'], number> = {
+  'folder-without-rule': 0,
+  'rule-group-not-admitted-above': 1,
+  'rule-folder-missing': 2,
+  'rule-label-outdated': 3,
+};
+
+function comparable(value: string): string {
+  return value.normalize('NFC').trim();
+}
+
+/** Names from the top folder down to `folder`'s parent, root excluded. */
+function trailOf(folder: CorpusFolder, corpus: CorpusStructure): string[] {
+  const names: string[] = [];
+  const seen = new Set<string>([folder.id]);
+  let parent = folder.parentId;
+  while (parent !== null && !seen.has(parent)) {
+    seen.add(parent);
+    const above = corpus.folders.get(parent);
+    if (!above || above.parentId === null) {
+      break;
+    }
+    names.unshift(above.label);
+    parent = above.parentId;
+  }
+  return names;
+}
+
+function placeOf(folder: CorpusFolder, corpus: CorpusStructure): FolderPlace {
+  return {
+    folder: folder.id,
+    name: folder.label,
+    trail: folder.parentId === null ? [] : trailOf(folder, corpus),
+  };
+}
+
+/**
+ * The folder a closed document is reported under: the top-level folder that
+ * holds it, or the root for a document directly in it. Every folder below a
+ * folder without a rule is without a rule too, unless it has its own, so the
+ * top is the one place a rule would fix them all.
+ */
+function reportedFolder(
+  folderId: string | null,
+  corpus: CorpusStructure,
+): string | null {
+  let current = folderId ?? corpus.rootFolderId;
+  const seen = new Set<string>();
+  while (current !== null && !seen.has(current)) {
+    seen.add(current);
+    const folder = corpus.folders.get(current);
+    if (!folder || folder.parentId === null) {
+      return current;
+    }
+    if (folder.parentId === corpus.rootFolderId) {
+      return current;
+    }
+    current = folder.parentId;
+  }
+  return current;
+}
+
+export function accessFindings(
+  access: AccessConfiguration,
+  corpus: CorpusStructure,
+): AccessFinding[] {
+  const rules = new Map(access.rules.map((rule) => [rule.folder, rule]));
+  const findings: AccessFinding[] = [];
+
+  const closed = new Map<string, number>();
+  for (const document of corpus.documents.values()) {
+    if (chainReaders(document.parentId, rules, corpus).kind === 'readers') {
+      continue;
+    }
+    const folder = reportedFolder(document.parentId, corpus);
+    if (folder !== null) {
+      closed.set(folder, (closed.get(folder) ?? 0) + 1);
+    }
+  }
+  for (const [id, documents] of closed) {
+    const folder = corpus.folders.get(id);
+    findings.push({
+      code: 'folder-without-rule',
+      documents,
+      ...(folder
+        ? placeOf(folder, corpus)
+        : { folder: id, name: id, trail: [] }),
+    });
+  }
+
+  for (const rule of access.rules) {
+    const folder = corpus.folders.get(rule.folder);
+    if (!folder) {
+      findings.push({
+        code: 'rule-folder-missing',
+        folder: rule.folder,
+        label: rule.label,
+      });
+      continue;
+    }
+    const label = comparable(rule.label);
+    if (
+      label !== comparable(folder.name) &&
+      label !== comparable(folder.label)
+    ) {
+      findings.push({
+        code: 'rule-label-outdated',
+        label: rule.label,
+        ...placeOf(folder, corpus),
+      });
+    }
+    if (rule.readers.includes(EVERY_MEMBER) || folder.parentId === null) {
+      continue;
+    }
+    const above = chainReaders(folder.parentId, rules, corpus);
+    if (above.kind !== 'readers' || above.readers === EVERY_MEMBER) {
+      continue;
+    }
+    const admitted = new Set(above.readers);
+    const groups = rule.readers.filter((group) => !admitted.has(group));
+    if (groups.length > 0) {
+      findings.push({
+        code: 'rule-group-not-admitted-above',
+        label: rule.label,
+        groups,
+        ...placeOf(folder, corpus),
+      });
+    }
+  }
+
+  return findings.sort(
+    (left, right) =>
+      ORDER[left.code] - ORDER[right.code] ||
+      (left.folder < right.folder ? -1 : left.folder > right.folder ? 1 : 0),
+  );
+}