@crombolo/transfer 0.10.0 → 0.12.1

package/src/load.ts

@@ -6,21 +6,35 @@
  * check reports on what it would do, and by then a malformed node file would be
  * a crash rather than a finding.
  */
+
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import {
   BUNDLE_FORMAT_VERSION,
   BUNDLE_SECTIONS,
+  type BundleAccess,
   type BundleKind,
   type BundleManifest,
   type BundleNode,
   type BundleProblem,
+  type BundleRedirect,
+  type BundleSchedule,
   type BundleSection,
   type BundleValue,
   type BundleVariant,
   type ContentSet,
 } from './model.ts'
-import { blobPath, bundleIntegrity, MANIFEST_FILE, nodePath, sectionOf } from './write.ts'
+import { type BundlePeople, openPeople, type PeopleBlock, parsePeopleBlock } from './people.ts'
+import { openBytes, parseSealParameters, unlock } from './seal.ts'
+import {
+  blobPath,
+  bundleIntegrity,
+  MANIFEST_FILE,
+  nodePath,
+  type SealedValues,
+  sectionOf,
+  valuesPath,
+} from './write.ts'
 
 export interface LoadedBundle {
   set: ContentSet | undefined
@@ -31,6 +45,10 @@ export interface LoadedBundle {
    * content-only bundle, which is every version 1 bundle.
    */
   files: Map<string, string>
+  /** The sealed people, when the bundle carries any: opened by `openBundle`. */
+  people?: { block: PeopleBlock; files: Map<string, Uint8Array> }
+  /** Each node's sealed values, by path, when the content is sealed. */
+  sealedValues?: Map<string, Uint8Array>
   /**
    * The media files the bundle carries, by store key, as paths on disk.
    *
@@ -139,6 +157,31 @@ export function parseNode(
     : []
   if (variants.length === 0) problems.push({ file, message: 'no variants: a node needs a name' })
 
+  const access = parseAccess(raw.access)
+  const schedule = Array.isArray(raw.schedule)
+    ? raw.schedule.flatMap((e): BundleSchedule[] =>
+        isRecord(e) &&
+        (e.action === 'publish' || e.action === 'unpublish') &&
+        typeof e.date === 'string' &&
+        !Number.isNaN(Date.parse(e.date))
+          ? [{ culture: nullableStr(e.culture) ?? null, action: e.action, date: e.date }]
+          : [],
+      )
+    : []
+  const redirects = Array.isArray(raw.redirects)
+    ? raw.redirects.flatMap((r): BundleRedirect[] =>
+        isRecord(r) && typeof r.path === 'string' && r.path.startsWith('/')
+          ? [
+              {
+                path: r.path,
+                root: nullableStr(r.root) ?? null,
+                culture: nullableStr(r.culture) ?? null,
+              },
+            ]
+          : [],
+      )
+    : []
+
   return {
     key,
     kind,
@@ -148,6 +191,25 @@ export function parseNode(
     template: nullableStr(raw.template) ?? null,
     variants,
     values,
+    ...(access ? { access } : {}),
+    ...(schedule.length > 0 ? { schedule } : {}),
+    ...(redirects.length > 0 ? { redirects } : {}),
+  }
+}
+
+const names = (v: unknown): string[] =>
+  Array.isArray(v) ? v.flatMap((n) => (typeof n === 'string' ? [n] : [])) : []
+
+function parseAccess(raw: unknown): BundleAccess | undefined {
+  if (!isRecord(raw)) return undefined
+  const loginNode = str(raw.loginNode)
+  const errorNode = str(raw.errorNode)
+  if (!loginNode || !errorNode) return undefined
+  return {
+    loginNode,
+    errorNode,
+    memberGroups: names(raw.memberGroups),
+    ...(Array.isArray(raw.memberUserNames) ? { memberUserNames: names(raw.memberUserNames) } : {}),
   }
 }
 
@@ -246,6 +308,11 @@ function parseManifest(text: string, problems: BundleProblem[]): BundleManifest
         )
       : [],
     ...(isRecord(raw.carries) ? { carries: parseCarries(raw.carries) } : {}),
+    ...(raw.people !== undefined && parsePeopleBlock(raw.people)
+      ? { people: parsePeopleBlock(raw.people) as PeopleBlock }
+      : {}),
+    ...(parseSealParameters(raw.seal) ? { seal: parseSealParameters(raw.seal) } : {}),
+    ...(raw.content === 'sealed' || raw.content === 'omitted' ? { content: raw.content } : {}),
   }
 }
 
@@ -329,6 +396,48 @@ export function loadBundle(dir: string): LoadedBundle {
     }
   }
 
+  // People are sealed bytes, opened only with the passphrase at install; here
+  // they are only read, and counted in the hash like everything else.
+  const people = new Map<string, Uint8Array>()
+  for (const path of manifest.people?.paths ?? []) {
+    const file = join(dir, path)
+    if (!existsSync(file)) {
+      problems.push({
+        file: path,
+        message: 'the manifest says this file is carried, and it is not',
+      })
+      continue
+    }
+    const bytes = new Uint8Array(readFileSync(file))
+    people.set(path, bytes)
+    read.push({ path, bytes })
+  }
+
+  if ((manifest.content === 'sealed' || manifest.people) && !manifest.seal)
+    problems.push({
+      file: MANIFEST_FILE,
+      message: 'the bundle says it is sealed but carries no seal to open it with',
+    })
+
+  // A sealed bundle carries one sealed file per node, read as bytes here and
+  // opened only with the passphrase.
+  const sealed = new Map<string, Uint8Array>()
+  if (manifest.content === 'sealed')
+    for (const name of nodeFiles) {
+      const path = valuesPath(name.slice(0, -'.json'.length))
+      const file = join(dir, path)
+      if (!existsSync(file)) {
+        problems.push({
+          file: path,
+          message: 'a sealed bundle carries the values of every node, and this one is missing',
+        })
+        continue
+      }
+      const bytes = new Uint8Array(readFileSync(file))
+      sealed.set(path, bytes)
+      read.push({ path, bytes })
+    }
+
   // Before shape: a truncated copy produces confusing field errors otherwise.
   const integrity = bundleIntegrity(read)
   if (manifest.integrity && manifest.integrity !== integrity)
@@ -356,5 +465,60 @@ export function loadBundle(dir: string): LoadedBundle {
     seen.add(node.key)
   }
 
-  return { set: { manifest, nodes }, problems, blobs, files }
+  const isSealed = manifest.content === 'sealed' || manifest.people !== undefined
+  return {
+    set: { manifest, nodes, ...(isSealed ? { sealed: true } : {}) },
+    problems,
+    blobs,
+    files,
+    ...(manifest.people ? { people: { block: manifest.people, files: people } } : {}),
+    ...(manifest.content === 'sealed' ? { sealedValues: sealed } : {}),
+  }
+}
+
+/** A bundle opened with its passphrase: values filled in, people read, media files openable. */
+export interface OpenedBundle {
+  set: ContentSet
+  people: BundlePeople | undefined
+  /** A carried media file's bytes as they were exported. */
+  openBlob: (key: string, bytes: Uint8Array) => Uint8Array
+}
+
+/**
+ * Opens what a bundle sealed. Throws `WrongPassphraseError` for the wrong
+ * passphrase and `SealedFileError` for a file altered or moved; a bundle with
+ * nothing sealed opens without one.
+ */
+export function openBundle(loaded: LoadedBundle, passphrase: string | undefined): OpenedBundle {
+  const set = loaded.set
+  if (!set) throw new Error('The bundle could not be read, so there is nothing to open.')
+  const params = set.manifest.seal
+  if (!set.sealed || !params) return { set, people: undefined, openBlob: (_key, bytes) => bytes }
+  const key = unlock(passphrase ?? '', params)
+  const nodes = set.nodes.map((node) => {
+    const path = valuesPath(node.key)
+    const bytes = loaded.sealedValues?.get(path)
+    if (!bytes) return node
+    const opened = JSON.parse(openBytes(key, path, bytes).toString('utf8')) as SealedValues
+    const at = (v: { property: string; culture: string | null; segment: string | null }) =>
+      `${v.property}|${v.culture ?? ''}|${v.segment ?? ''}`
+    const payload = new Map(opened.values.map((v) => [at(v), v.value]))
+    return {
+      ...node,
+      values: node.values.map((v) => ({ ...v, value: payload.get(at(v)) })),
+      ...(node.access && opened.memberUserNames
+        ? { access: { ...node.access, memberUserNames: opened.memberUserNames } }
+        : {}),
+    }
+  })
+  const people = loaded.people
+    ? openPeople(loaded.people.block, loaded.people.files, key)
+    : undefined
+  const sealedBlobs = set.manifest.content === 'sealed'
+  const { sealed: _sealed, ...rest } = set
+  return {
+    set: { ...rest, nodes, ...(people ? { people } : {}) },
+    people,
+    openBlob: (blob, bytes) => (sealedBlobs ? openBytes(key, blobPath(blob), bytes) : bytes),
+  }
 }

package/src/model.ts

@@ -8,8 +8,14 @@
  * across environments — with the alias as the readable fallback.
  */
 
+import type { BundlePeople, PeopleBlock } from './people.ts'
+import type { SealParameters } from './seal.ts'
+
 /** Bumped when a change to the shapes below stops an older reader understanding a bundle. */
-export const BUNDLE_FORMAT_VERSION = 2
+export const BUNDLE_FORMAT_VERSION = 3
+
+/** What a bundle with sections and nothing sealed writes: version 2 readers still read it. */
+export const SECTIONS_FORMAT_VERSION = 2
 
 /**
  * The version a bundle carrying only content is still written as.
@@ -61,6 +67,7 @@ export interface BundleValue {
   segment: string | null
   /** The editor that wrote it, so the destination can refuse a property whose editor changed. */
   editor: string
+  /** Undefined while the bundle's content is sealed. */
   value: unknown
   /** Node keys this value refers to, extracted at export so the importer need not re-parse. */
   references?: string[]
@@ -77,6 +84,34 @@ export interface BundleVariant {
   published: boolean
 }
 
+/**
+ * A protected page: who may see it, by member group name, and where a
+ * visitor is sent. The usernames are personal, so they travel with the values.
+ */
+export interface BundleAccess {
+  loginNode: string
+  errorNode: string
+  memberGroups: string[]
+  /** Absent while sealed, or when the bundle carries no content. */
+  memberUserNames?: string[]
+}
+
+/** A publish or unpublish waiting for its time. */
+export interface BundleSchedule {
+  culture: string | null
+  action: 'publish' | 'unpublish'
+  /** ISO 8601, UTC. */
+  date: string
+}
+
+/** A route the page used to answer on, which redirects to it. */
+export interface BundleRedirect {
+  path: string
+  /** The hostname root it was under, by key; null for none. */
+  root: string | null
+  culture: string | null
+}
+
 export interface BundleNode {
   key: string
   kind: BundleKind
@@ -88,6 +123,9 @@ export interface BundleNode {
   template: string | null
   variants: BundleVariant[]
   values: BundleValue[]
+  access?: BundleAccess
+  schedule?: BundleSchedule[]
+  redirects?: BundleRedirect[]
 }
 
 /** Something the bundle refers to but does not carry: it must already exist at the destination. */
@@ -176,8 +214,24 @@ export interface BundleManifest {
    * content-only bundle, which is what version 1 always was.
    */
   carries?: Partial<Record<BundleSection, string[]>>
+  /**
+   * Members and users, sealed (story 071): counts and how to derive the key,
+   * never who. Present only on a bundle exported with them — format 3, which an
+   * older reader refuses by name rather than half-reading.
+   */
+  people?: PeopleBlock
+  /** How values, media files and people are sealed: the salt and cost, never the key. */
+  seal?: SealParameters
+  /**
+   * `sealed`: values and media files are under `seal`. `omitted`: exported
+   * without them, so an import names and places pages and writes no value.
+   * Absent: in the open.
+   */
+  content?: BundleContentMode
 }
 
+export type BundleContentMode = 'sealed' | 'omitted'
+
 /**
  * A bundle read into memory: the manifest and its nodes. Named for
  * `SchemaSet` in `@crombolo/schema`, which plays the same part for structure.
@@ -185,6 +239,10 @@ export interface BundleManifest {
 export interface ContentSet {
   manifest: BundleManifest
   nodes: BundleNode[]
+  /** True while the values are still sealed: `openBundle` with the passphrase first. */
+  sealed?: boolean
+  /** The people, once opened. */
+  people?: BundlePeople
 }
 
 /** A problem with the bundle itself, as opposed to a finding about applying it. */

package/src/package.ts

@@ -7,6 +7,7 @@
  * hash and sections mean what they always did. The package is what gives it a
  * name, a version and a core it was written for.
  */
+import { PEOPLE_DIR } from './people.ts'
 import type { BundleFile } from './write.ts'
 
 /** The directory inside a package that holds the `bundle.json` payload. */
@@ -77,6 +78,12 @@ export function writeBundlePackage(
   info: BundlePackageInfo,
 ): BundleFile[] {
   if (!isPackageName(info.name)) throw new Error(`"${info.name}" is not a package name npm accepts`)
+  // Personal data never goes where `npm publish` can take it, sealed or not;
+  // and sealed content would be no use to anyone who installed it.
+  if (!info.private && payload.some((file) => file.path.startsWith(`${PEOPLE_DIR}/`)))
+    throw new Error('A bundle that carries members or users can only be a private package.')
+  if (!info.private && payload.some((file) => file.path.startsWith('values/')))
+    throw new Error('A bundle whose content is encrypted can only be a private package.')
   return [
     { path: 'package.json', text: `${JSON.stringify(bundlePackageJson(info), null, 2)}\n` },
     ...payload.map((file) => ({ ...file, path: `${PAYLOAD_DIR}/${file.path}` })),