@crombolo/transfer 0.11.0 → 0.13.1

package/src/people.ts

@@ -0,0 +1,167 @@
+/**
+ * A bundle's people (story 071): member groups, members, user groups and
+ * users, in the bundle's `people/` directory — always sealed (`seal.ts`). The
+ * manifest says how many of each, never who.
+ * docs/content-transfer.md, "People".
+ */
+import type { BundleValue } from './model.ts'
+import { openBytes, type Seal, sealBytes } from './seal.ts'
+
+export interface BundleMemberGroup {
+  key: string
+  name: string
+}
+
+export interface BundleMember {
+  key: string
+  name: string
+  memberTypeAlias: string
+  email: string
+  username: string
+  isApproved: boolean
+  isLockedOut: boolean
+  /** As the source stored it, with its algorithm marker; null for none. */
+  passwordHash: string | null
+  passwordConfig: string | null
+  groupKeys: string[]
+  values: BundleValue[]
+}
+
+export interface BundleUserGroup {
+  key: string
+  alias: string
+  name: string
+  icon: string | null
+  sections: string[]
+  /** Default permission verbs, e.g. `Umb.Document.Read`. */
+  permissions: string[]
+  hasAccessToAllLanguages: boolean
+  languages: string[]
+  documentStartNodeKey: string | null
+  mediaStartNodeKey: string | null
+}
+
+export interface BundleUser {
+  key: string
+  name: string
+  userName: string
+  email: string
+  languageIsoCode: string | null
+  disabled: boolean
+  passwordHash: string | null
+  passwordConfig: string | null
+  groupAliases: string[]
+}
+
+export interface BundlePeople {
+  memberGroups: BundleMemberGroup[]
+  members: BundleMember[]
+  userGroups: BundleUserGroup[]
+  users: BundleUser[]
+}
+
+export const EMPTY_PEOPLE: BundlePeople = {
+  memberGroups: [],
+  members: [],
+  userGroups: [],
+  users: [],
+}
+
+/** What the manifest says of a bundle's people: counts, never who. */
+export interface PeopleBlock {
+  counts: { memberGroups: number; members: number; userGroups: number; users: number }
+  /** Every sealed file, in path order. */
+  paths: string[]
+}
+
+export const PEOPLE_DIR = 'people'
+
+const MEMBER_GROUPS = `${PEOPLE_DIR}/member-groups.json`
+const USER_GROUPS = `${PEOPLE_DIR}/user-groups.json`
+const memberPath = (key: string) => `${PEOPLE_DIR}/members/${key}.json`
+const userPath = (key: string) => `${PEOPLE_DIR}/users/${key}.json`
+
+const json = (value: unknown) => Buffer.from(`${JSON.stringify(value, null, 2)}\n`)
+
+/** People sealed under the bundle's seal: the files, and the manifest's block. */
+export function sealPeople(
+  people: BundlePeople,
+  { key }: Seal,
+): { files: Array<{ path: string; bytes: Uint8Array }>; block: PeopleBlock } {
+  const plain: Array<{ path: string; bytes: Buffer }> = [
+    { path: MEMBER_GROUPS, bytes: json(people.memberGroups) },
+    { path: USER_GROUPS, bytes: json(people.userGroups) },
+    ...people.members.map((m) => ({ path: memberPath(m.key), bytes: json(m) })),
+    ...people.users.map((u) => ({ path: userPath(u.key), bytes: json(u) })),
+  ].sort((a, b) => a.path.localeCompare(b.path))
+  const files = plain.map((file) => ({
+    path: file.path,
+    bytes: sealBytes(key, file.path, file.bytes),
+  }))
+  return {
+    files,
+    block: {
+      counts: {
+        memberGroups: people.memberGroups.length,
+        members: people.members.length,
+        userGroups: people.userGroups.length,
+        users: people.users.length,
+      },
+      paths: files.map((f) => f.path),
+    },
+  }
+}
+
+/** A bundle's people, opened with its key; `SealedFileError` for a file altered or moved. */
+export function openPeople(
+  block: PeopleBlock,
+  files: ReadonlyMap<string, Uint8Array>,
+  key: Buffer,
+): BundlePeople {
+  const read = <T>(path: string): T => {
+    const sealed = files.get(path)
+    if (!sealed) throw new Error(`${path} is missing from the bundle's people.`)
+    return JSON.parse(openBytes(key, path, sealed).toString('utf8')) as T
+  }
+  const out: BundlePeople = {
+    memberGroups: block.paths.includes(MEMBER_GROUPS) ? read(MEMBER_GROUPS) : [],
+    userGroups: block.paths.includes(USER_GROUPS) ? read(USER_GROUPS) : [],
+    members: [],
+    users: [],
+  }
+  for (const path of block.paths) {
+    if (path.startsWith(`${PEOPLE_DIR}/members/`)) out.members.push(read<BundleMember>(path))
+    if (path.startsWith(`${PEOPLE_DIR}/users/`)) out.users.push(read<BundleUser>(path))
+  }
+  const counts = block.counts
+  if (
+    out.members.length !== counts.members ||
+    out.users.length !== counts.users ||
+    out.memberGroups.length !== counts.memberGroups ||
+    out.userGroups.length !== counts.userGroups
+  )
+    throw new Error("The bundle's people do not match the counts its manifest gives.")
+  return out
+}
+
+/** A manifest's people block read without trusting it: undefined when absent or malformed. Pure. */
+export function parsePeopleBlock(raw: unknown): PeopleBlock | undefined {
+  if (!raw || typeof raw !== 'object') return undefined
+  const block = raw as Record<string, unknown>
+  const counts = block.counts as Record<string, unknown> | undefined
+  if (!counts || !Array.isArray(block.paths)) return undefined
+  const paths = (block.paths as unknown[]).filter(
+    (p): p is string =>
+      typeof p === 'string' && p.startsWith(`${PEOPLE_DIR}/`) && !p.split('/').includes('..'),
+  )
+  const count = (name: string) => (Number.isInteger(counts[name]) ? (counts[name] as number) : 0)
+  return {
+    counts: {
+      memberGroups: count('memberGroups'),
+      members: count('members'),
+      userGroups: count('userGroups'),
+      users: count('users'),
+    },
+    paths: paths.sort(),
+  }
+}

package/src/resolutions.ts

@@ -7,11 +7,19 @@
  * again in production, each time against more content.
  *
  * It holds resolutions **by node key**, so a path that means something
- * different in the next environment cannot change what was decided.
+ * different in the next environment cannot change what was decided. Each node's
+ * answers are `"*"` for the whole node and `"<alias>"` or `"<alias>@<culture>"`
+ * for one property.
  */
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { isResolution, type Resolution } from './check.ts'
+import {
+  isResolution,
+  type NodeResolutions,
+  nodeResolutionProblems,
+  type Resolution,
+  WHOLE_NODE,
+} from './check.ts'
 
 export const RESOLUTIONS_FILE = 'resolutions.json'
 
@@ -21,7 +29,48 @@ export interface ResolutionsFile {
   /** Where the bundle was placed, when it was re-rooted. */
   under?: string | null
   all?: Resolution | null
-  byNode: Record<string, Resolution>
+  byNode: Record<string, NodeResolutions>
+}
+
+/**
+ * `--resolve` values into answers by node: `<key>=<choice>` answers the node,
+ * `<key>/<alias>[@<culture>]=<choice>` one property. Pure; problems are named.
+ */
+export function parseResolveFlags(pairs: readonly string[]): {
+  byNode: Record<string, NodeResolutions>
+  problems: string[]
+} {
+  const byNode: Record<string, Record<string, Resolution>> = {}
+  const problems: string[] = []
+  for (const pair of pairs) {
+    const eq = pair.lastIndexOf('=')
+    if (eq < 0) {
+      problems.push(`--resolve wants <key>=<choice> or <key>/<property>=<choice>, not "${pair}"`)
+      continue
+    }
+    const target = pair.slice(0, eq)
+    const choice = pair.slice(eq + 1)
+    const slash = target.indexOf('/')
+    const key = slash < 0 ? target : target.slice(0, slash)
+    const handle = slash < 0 ? WHOLE_NODE : target.slice(slash + 1)
+    const found = nodeResolutionProblems(key, { [handle]: choice })
+    if (found.length > 0 || !handle) {
+      problems.push(...(found.length > 0 ? found : [`--resolve "${pair}" names no property`]))
+      continue
+    }
+    byNode[key] = { ...(byNode[key] ?? {}), [handle]: choice as Resolution }
+  }
+  return { byNode, problems }
+}
+
+/** Answers laid over others, node by node and property by property. Pure. */
+export function mergeResolutions(
+  under: Readonly<Record<string, NodeResolutions>>,
+  over: Readonly<Record<string, NodeResolutions>>,
+): Record<string, NodeResolutions> {
+  const out: Record<string, NodeResolutions> = { ...under }
+  for (const [key, answers] of Object.entries(over)) out[key] = { ...(out[key] ?? {}), ...answers }
+  return out
 }
 
 export function writeResolutions(file: ResolutionsFile): string {
@@ -31,7 +80,12 @@ export function writeResolutions(file: ResolutionsFile): string {
       under: file.under ?? null,
       all: file.all ?? null,
       byNode: Object.fromEntries(
-        Object.entries(file.byNode).sort(([a], [b]) => a.localeCompare(b)),
+        Object.entries(file.byNode)
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([key, answers]) => [
+            key,
+            Object.fromEntries(Object.entries(answers).sort(([a], [b]) => a.localeCompare(b))),
+          ]),
       ),
     },
     null,
@@ -68,11 +122,19 @@ export function loadResolutions(dir: string, bundleId: string): LoadedResolution
   if (found && found !== bundleId)
     problems.push(`${RESOLUTIONS_FILE}: answers bundle ${found}, not ${bundleId} — ignoring it`)
 
-  const byNode: Record<string, Resolution> = {}
+  const byNode: Record<string, NodeResolutions> = {}
   const entries = typeof record.byNode === 'object' && record.byNode !== null ? record.byNode : {}
   for (const [key, value] of Object.entries(entries as Record<string, unknown>)) {
-    if (typeof value === 'string' && isResolution(value)) byNode[key] = value
-    else problems.push(`${RESOLUTIONS_FILE}: "${key}" has no usable resolution`)
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      problems.push(
+        `${RESOLUTIONS_FILE}: "${key}" must map "*" or a property to a resolution, as { "*": "take-bundle" }`,
+      )
+      continue
+    }
+    const found = nodeResolutionProblems(key, value as Record<string, unknown>)
+    if (found.length > 0)
+      problems.push(...found.map((message) => `${RESOLUTIONS_FILE}: ${message}`))
+    else byNode[key] = value as Record<string, Resolution>
   }
   const all = typeof record.all === 'string' && isResolution(record.all) ? record.all : null
 

package/src/revert.ts

@@ -27,6 +27,7 @@ import {
   type TransferRun,
   TransferRunRepository,
 } from '@crombolo/data'
+import { isPersonKind, removePerson } from './people-apply.ts'
 
 /** What to do about a node whose state has moved on since the import. */
 export type RevertResolution = 'discard' | 'skip'
@@ -74,7 +75,7 @@ export interface RevertPlan {
    * run created, and `unrecycle` brings back what a *reverted* run recycled —
    * which is what makes a revert revertible in its own right.
    */
-  action: 'restore' | 'recycle' | 'unrecycle' | 'skip' | 'gone'
+  action: 'restore' | 'recycle' | 'unrecycle' | 'skip' | 'gone' | 'remove'
   resolution: RevertResolution | undefined
 }
 
@@ -91,6 +92,8 @@ export interface RevertResult {
   check: RevertCheck
   restored: string[]
   recycled: string[]
+  /** Members, users and groups the run had created, now removed. */
+  removed: string[]
 }
 
 const link = (backOfficePath: string | undefined, key: string): string | null =>
@@ -154,6 +157,30 @@ export async function checkRevert(
 
   for (const change of changes) {
     if (change.action === 'skip') continue
+    // People have no history to roll back to: what the run created goes, and
+    // what it updated keeps the bundle's details.
+    if (isPersonKind(change.kind)) {
+      if (change.action === 'create')
+        plan.push({
+          key: change.nodeKey,
+          name: change.nodeKey,
+          action: 'remove',
+          resolution: undefined,
+        })
+      else
+        findings.push({
+          kind: 'auto',
+          code: 'person-kept',
+          subjectType: change.kind,
+          subjectKey: change.nodeKey,
+          subjectName: change.nodeKey,
+          propertyAlias: null,
+          culture: null,
+          message: `${change.kind} ${change.nodeKey} was updated by the run and keeps those details`,
+          link: null,
+        })
+      continue
+    }
     const resolution = resolutions[change.nodeKey] ?? options.resolveAll
     const node = await docs.nodes.byKey(change.nodeKey)
     const name = node?.text ?? change.nodeKey
@@ -261,7 +288,7 @@ export async function revertRun(
     db.transaction(async (tx) => {
       const check = await checkRevert(tx, runId, options)
       if (check.outstanding.length > 0)
-        return { runId: undefined, check, restored: [], recycled: [] }
+        return { runId: undefined, check, restored: [], recycled: [], removed: [] }
 
       const runs = new TransferRunRepository(tx)
       const original = (await runs.byId(runId)) as TransferRun
@@ -288,7 +315,19 @@ export async function revertRun(
       const skipped = new Set(
         check.plan.filter((p) => p.action === 'skip' || p.action === 'gone').map((p) => p.key),
       )
-      const todo = changes.filter((c) => c.action !== 'skip' && !skipped.has(c.nodeKey))
+      const todo = changes.filter(
+        (c) => c.action !== 'skip' && !skipped.has(c.nodeKey) && !isPersonKind(c.kind),
+      )
+      // Members before the groups they belong to.
+      const removed: string[] = []
+      const order = ['member', 'user', 'member-group', 'user-group']
+      for (const change of changes
+        .filter((c) => isPersonKind(c.kind) && c.action === 'create')
+        .sort((a, b) => order.indexOf(a.kind) - order.indexOf(b.kind)))
+        if (
+          await removePerson(tx, change.kind as Parameters<typeof removePerson>[1], change.nodeKey)
+        )
+          removed.push(change.nodeKey)
       const byKey = new Map<string, NodeRow>()
       for (const change of todo) {
         const node = await repo(change.kind).nodes.byKey(change.nodeKey)
@@ -372,7 +411,7 @@ export async function revertRun(
           eventId: markers?.head ?? null,
         })
       }
-      await runs.finish(newRunId, todo.length)
+      await runs.finish(newRunId, todo.length + removed.length)
       await runs.setStatus(runId, 'reverted')
 
       await appendCacheInstruction(tx, {
@@ -381,7 +420,7 @@ export async function revertRun(
         by: options.nodeId,
       })
 
-      return { runId: newRunId, check, restored, recycled }
+      return { runId: newRunId, check, restored, recycled, removed }
     }),
   )
 }

package/src/seal.ts

@@ -0,0 +1,129 @@
+/**
+ * Sealing what in a bundle can hold personal information (story 071):
+ * property values, media files, protected-page usernames and people. The key is stretched from a passphrase
+ * given at export and at install — never stored — with scrypt and a salt the
+ * bundle keeps; each file is AES-256-GCM with a nonce of its own and its path
+ * as additional data, so a file cannot be swapped for another's. A check value
+ * tells a wrong passphrase apart from a damaged file. docs/content-transfer.md,
+ * "People".
+ */
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto'
+
+/** What the manifest keeps to derive the key again: never the key itself. */
+export interface SealParameters {
+  kdf: 'scrypt'
+  /** scrypt's cost, block size and parallelism. */
+  n: number
+  r: number
+  p: number
+  /** Base64. */
+  salt: string
+  /** A known value sealed under the key, so a wrong passphrase is named as one. */
+  check: string
+}
+
+export const SEAL_MAGIC = Buffer.from('CRBSEAL1')
+const CHECK_PATH = 'people/.check'
+const CHECK_TEXT = 'crombolo people'
+
+export class WrongPassphraseError extends Error {
+  constructor() {
+    super('The passphrase does not open this bundle’s people.')
+  }
+}
+
+export class SealedFileError extends Error {}
+
+/** The key a passphrase gives under these parameters. */
+export function deriveKey(
+  passphrase: string,
+  params: Pick<SealParameters, 'n' | 'r' | 'p' | 'salt'>,
+): Buffer {
+  if (!passphrase) throw new WrongPassphraseError()
+  return scryptSync(passphrase.normalize('NFC'), Buffer.from(params.salt, 'base64'), 32, {
+    N: params.n,
+    r: params.r,
+    p: params.p,
+    maxmem: 256 * params.n * params.r + 1024 * 1024,
+  })
+}
+
+/** One file sealed: magic, nonce, ciphertext, tag. `nonce` is injectable for tests. */
+export function sealBytes(
+  key: Buffer,
+  path: string,
+  plain: Uint8Array,
+  nonce = randomBytes(12),
+): Buffer {
+  const cipher = createCipheriv('aes-256-gcm', key, nonce)
+  cipher.setAAD(Buffer.from(path))
+  const body = Buffer.concat([cipher.update(plain), cipher.final()])
+  return Buffer.concat([SEAL_MAGIC, nonce, body, cipher.getAuthTag()])
+}
+
+/** One file opened; throws when it was altered, moved or is not sealed. */
+export function openBytes(key: Buffer, path: string, sealed: Uint8Array): Buffer {
+  const bytes = Buffer.from(sealed)
+  if (bytes.length < SEAL_MAGIC.length + 12 + 16 || !bytes.subarray(0, 8).equals(SEAL_MAGIC))
+    throw new SealedFileError(`${path} is not a sealed file.`)
+  const nonce = bytes.subarray(8, 20)
+  const tag = bytes.subarray(bytes.length - 16)
+  const decipher = createDecipheriv('aes-256-gcm', key, nonce)
+  decipher.setAAD(Buffer.from(path))
+  decipher.setAuthTag(tag)
+  try {
+    return Buffer.concat([decipher.update(bytes.subarray(20, bytes.length - 16)), decipher.final()])
+  } catch {
+    throw new SealedFileError(`${path} was altered, or belongs to another file.`)
+  }
+}
+
+/** The parameters a bundle keeps, and the key they give. */
+export interface Seal {
+  params: SealParameters
+  key: Buffer
+}
+
+/** Fresh parameters and the key they give: what an export starts with. */
+export function newSeal(
+  passphrase: string,
+  cost: Pick<SealParameters, 'n' | 'r' | 'p'> = { n: 2 ** 17, r: 8, p: 1 },
+): Seal {
+  const salt = randomBytes(16).toString('base64')
+  const key = deriveKey(passphrase, { ...cost, salt })
+  const check = sealBytes(key, CHECK_PATH, Buffer.from(CHECK_TEXT)).toString('base64')
+  return { params: { kdf: 'scrypt', ...cost, salt, check }, key }
+}
+
+/** The key for a bundle's people, or a refusal naming a wrong passphrase. */
+export function unlock(passphrase: string, params: SealParameters): Buffer {
+  const key = deriveKey(passphrase, params)
+  try {
+    const opened = openBytes(key, CHECK_PATH, Buffer.from(params.check, 'base64'))
+    if (opened.toString() !== CHECK_TEXT) throw new WrongPassphraseError()
+  } catch {
+    throw new WrongPassphraseError()
+  }
+  return key
+}
+
+/** A manifest's seal read without trusting it: undefined when absent or malformed. Pure. */
+export function parseSealParameters(raw: unknown): SealParameters | undefined {
+  if (!raw || typeof raw !== 'object') return undefined
+  const seal = raw as Record<string, unknown>
+  if (
+    seal.kdf !== 'scrypt' ||
+    typeof seal.salt !== 'string' ||
+    typeof seal.check !== 'string' ||
+    ![seal.n, seal.r, seal.p].every((v) => Number.isInteger(v) && (v as number) > 0)
+  )
+    return undefined
+  return {
+    kdf: 'scrypt',
+    n: seal.n as number,
+    r: seal.r as number,
+    p: seal.p as number,
+    salt: seal.salt,
+    check: seal.check,
+  }
+}