was-teaching-server 0.9.1

package/src/lib/importTar.ts

@@ -0,0 +1,381 @@
+import * as tar from 'tar-stream'
+import YAML from 'yaml'
+import type { Readable } from 'node:stream'
+import { assertValidId } from './validateId.js'
+import { parseResourceFileName } from './resourceFileName.js'
+import { InvalidImportError } from '../errors.js'
+import type {
+  CollectionDescription,
+  PolicyDocument,
+  RevocationRecord
+} from '../types.js'
+
+/** Suffix shared by the description / policy / metadata dot-files. */
+const JSON_SUFFIX = '.json'
+/** Prefix of a policy dot-file (`.policy.<id>.json`). */
+const POLICY_PREFIX = '.policy.'
+/** Prefix of a resource metadata sidecar (`.meta.<id>.json`). */
+const META_PREFIX = '.meta.'
+
+/**
+ * If `fileName` is a dot-file with the given prefix and `.json` suffix, returns
+ * the `<id>` between them; otherwise undefined. Uses slice (not split) so ids
+ * containing dots (URL-safe `.` is allowed) round-trip correctly.
+ * @param fileName {string}
+ * @param prefix {string}
+ * @returns {string | undefined}
+ */
+function dotFileId(fileName: string, prefix: string): string | undefined {
+  if (!fileName.startsWith(prefix) || !fileName.endsWith(JSON_SUFFIX)) {
+    return undefined
+  }
+  const id = fileName.slice(prefix.length, -JSON_SUFFIX.length)
+  return id.length > 0 ? id : undefined
+}
+
+/**
+ * If `fileName` is a policy dot-file (`.policy.<id>.json`), returns the `<id>`
+ * it is keyed by; otherwise undefined.
+ * @param fileName {string}
+ * @returns {string | undefined}
+ */
+function policyFileId(fileName: string): string | undefined {
+  return dotFileId(fileName, POLICY_PREFIX)
+}
+
+/**
+ * If `fileName` is a metadata sidecar (`.meta.<resourceId>.json`), returns the
+ * `<resourceId>` it is keyed by; otherwise undefined.
+ * @param fileName {string}
+ * @returns {string | undefined}
+ */
+export function metaSidecarFileId(fileName: string): string | undefined {
+  return dotFileId(fileName, META_PREFIX)
+}
+
+/** One extracted archive entry, keyed by its archive path. */
+export interface TarEntry {
+  type: 'file' | 'directory'
+  body?: Buffer
+}
+
+/** One resource staged for import by {@link buildImportPlan}. */
+export interface ImportPlanResource {
+  fileName: string
+  resourceId: string
+  body: Buffer
+}
+
+/** One collection (plus its resources and policies) staged for import. */
+export interface ImportPlanCollection {
+  collectionId: string
+  collectionDescription: CollectionDescription
+  /** Collection-level access-control policy, if the archive carries one. */
+  collectionPolicy?: PolicyDocument
+  resources: ImportPlanResource[]
+  /** Resource-level policies, keyed by resourceId. */
+  resourcePolicies: Map<string, PolicyDocument>
+  /** Resource metadata sidecars (raw `.meta.<id>.json` bytes), keyed by resourceId. */
+  resourceMetadata: Map<string, Buffer>
+}
+
+/** The merge plan produced by {@link buildImportPlan}. */
+export interface ImportPlan {
+  /** Space-level access-control policy, if the archive carries one. */
+  spacePolicy?: PolicyDocument
+  collections: ImportPlanCollection[]
+  /**
+   * Space-scoped zcap revocation records the archive carries (top-level
+   * `revocations/` entries), restored under the destination Space's scope.
+   */
+  revocations: RevocationRecord[]
+}
+
+/**
+ * @param options {object}
+ * @param options.tarStream {Readable}
+ * @returns {Promise<Map<string, TarEntry>>}
+ */
+export async function extractTarEntries(
+  tarStream: Readable
+): Promise<Map<string, TarEntry>> {
+  const entries = new Map<string, TarEntry>()
+
+  await new Promise<void>((resolve, reject) => {
+    const extract = tar.extract()
+
+    extract.on('entry', (header, stream, next) => {
+      if (header.type === 'directory') {
+        entries.set(header.name, { type: 'directory' })
+        stream.resume()
+        next()
+        return
+      }
+
+      const chunks: Buffer[] = []
+      stream.on('data', chunk => chunks.push(Buffer.from(chunk)))
+      stream.on('end', () => {
+        entries.set(header.name, {
+          type: 'file',
+          body: Buffer.concat(chunks)
+        })
+        next()
+      })
+      stream.on('error', reject)
+    })
+
+    extract.on('finish', resolve)
+    extract.on('error', reject)
+    tarStream.on('error', reject)
+    tarStream.pipe(extract)
+  })
+
+  return entries
+}
+
+/**
+ * Validates that the archive carries a well-formed UBC v0.1 `manifest.yml`
+ * describing a WAS space export. Throws on any problem.
+ * @param entries {Map<string, TarEntry>}
+ * @returns {void}
+ */
+export function validateManifest(entries: Map<string, TarEntry>): void {
+  const manifestEntry = entries.get('manifest.yml')
+  if (!manifestEntry?.body) {
+    throw new InvalidImportError({
+      message: 'Archive is missing manifest.yml.'
+    })
+  }
+
+  let manifest
+  try {
+    manifest = YAML.parse(manifestEntry.body.toString('utf8'))
+  } catch (err) {
+    throw new InvalidImportError({
+      message: 'Archive manifest.yml is not valid YAML.',
+      cause: err as Error
+    })
+  }
+
+  if (manifest['ubc-version'] !== '0.1') {
+    throw new InvalidImportError({
+      message: 'Unsupported archive manifest version.'
+    })
+  }
+
+  if (!manifest.contents?.space) {
+    throw new InvalidImportError({
+      message: 'Archive manifest does not describe a WAS space export.'
+    })
+  }
+}
+
+/**
+ * Build a merge plan from a WAS space export tarball.
+ *
+ * Expected archive layout (UBC v0.1, produced by exportSpace):
+ * - manifest.yml
+ * - revocations/<digest>.json (Space-scoped zcap revocations; optional)
+ * - space/
+ * - space/<sourceSpaceId>/
+ * - space/<sourceSpaceId>/.space.<sourceSpaceId>.json (space metadata; ignored on import)
+ * - space/<sourceSpaceId>/.policy.<sourceSpaceId>.json (space-level policy)
+ * - space/<sourceSpaceId>/<collectionId>/
+ * - space/<sourceSpaceId>/<collectionId>/.collection.<collectionId>.json
+ * - space/<sourceSpaceId>/<collectionId>/.policy.<collectionId>.json (collection policy)
+ * - space/<sourceSpaceId>/<collectionId>/.policy.<resourceId>.json (resource policy)
+ * - space/<sourceSpaceId>/<collectionId>/r.<resourceId>.<encodedContentType>.<ext>
+ *
+ * The source space id in the path may differ from the import target; collection
+ * metadata, r.* resource files, and `.policy.*` policy files are merged into the
+ * destination.
+ *
+ * @param entries {Map<string, TarEntry>}
+ * @returns {ImportPlan}
+ */
+export function buildImportPlan(entries: Map<string, TarEntry>): ImportPlan {
+  validateManifest(entries)
+
+  let sourceSpaceId: string | undefined
+  for (const name of entries.keys()) {
+    const match = name.match(/^space\/([^/]+)\//)
+    if (match) {
+      sourceSpaceId = match[1]
+      break
+    }
+  }
+  if (!sourceSpaceId) {
+    throw new InvalidImportError({
+      message: 'Archive does not contain space data.'
+    })
+  }
+
+  const prefix = `space/${sourceSpaceId}/`
+
+  // Space-level policy (`.policy.<sourceSpaceId>.json` at the space root).
+  const spacePolicyEntry = entries.get(`${prefix}.policy.${sourceSpaceId}.json`)
+  const spacePolicy: PolicyDocument | undefined = spacePolicyEntry?.body
+    ? JSON.parse(spacePolicyEntry.body.toString('utf8'))
+    : undefined
+  const collectionIds = new Set<string>()
+  for (const name of entries.keys()) {
+    if (!name.startsWith(prefix)) {
+      continue
+    }
+    const match = name.slice(prefix.length).match(/^([^/]+)\//)
+    if (match?.[1]) {
+      // Reject a path-traversal / non-URL-safe id parsed from the archive
+      // before it is used to build a destination path.
+      assertValidId(match[1], {
+        kind: 'collection',
+        requestName: 'Import Space'
+      })
+      collectionIds.add(match[1])
+    }
+  }
+
+  const collections = [...collectionIds].sort().map(collectionId => {
+    const collectionMetaKey = `${prefix}${collectionId}/.collection.${collectionId}.json`
+    const metaEntry = entries.get(collectionMetaKey)
+    const collectionDescription: CollectionDescription = metaEntry?.body
+      ? JSON.parse(metaEntry.body.toString('utf8'))
+      : { id: collectionId, type: ['Collection'], name: collectionId }
+
+    const collectionPrefix = `${prefix}${collectionId}/`
+    const resources: ImportPlanResource[] = []
+    let collectionPolicy: PolicyDocument | undefined
+    const resourcePolicies = new Map<string, PolicyDocument>()
+    const resourceMetadata = new Map<string, Buffer>()
+    for (const [entryName, entry] of entries) {
+      if (
+        !entryName.startsWith(collectionPrefix) ||
+        entry.type !== 'file' ||
+        !entry.body
+      ) {
+        continue
+      }
+
+      const fileName = entryName.slice(collectionPrefix.length)
+      if (fileName.includes('/')) {
+        continue
+      }
+
+      // Policy dot-files: `.policy.<collectionId>.json` is the Collection policy;
+      // `.policy.<resourceId>.json` is a Resource policy keyed by resource id.
+      const policyId = policyFileId(fileName)
+      if (policyId !== undefined) {
+        const policy: PolicyDocument = JSON.parse(entry.body.toString('utf8'))
+        if (policyId === collectionId) {
+          collectionPolicy = policy
+        } else {
+          // Reject a path-traversal / non-URL-safe id parsed from the archive.
+          assertValidId(policyId, {
+            kind: 'resource',
+            requestName: 'Import Space'
+          })
+          resourcePolicies.set(policyId, policy)
+        }
+        continue
+      }
+
+      // Metadata sidecar (`.meta.<resourceId>.json`): carried as raw bytes,
+      // keyed by resourceId. Written alongside a newly-created resource
+      // (preserving its timestamps and user-writable `custom`), or -- for a
+      // tombstone, whose content file is gone -- on its own as an orphan sidecar
+      // (see `importSpace`).
+      const metaId = metaSidecarFileId(fileName)
+      if (metaId !== undefined) {
+        assertValidId(metaId, { kind: 'resource', requestName: 'Import Space' })
+        resourceMetadata.set(metaId, entry.body)
+        continue
+      }
+
+      if (!fileName.startsWith('r.')) {
+        continue
+      }
+
+      const parts = fileName.split('.')
+      if (parts.length < 4 || !parts[1]) {
+        continue
+      }
+
+      // Decode the dot-escaped id segment (see `fileNameFor`) so a dotted id
+      // (e.g. `index.html`) round-trips. The `fileName` is preserved verbatim
+      // (the bytes are written under their stored name); only the parsed
+      // `resourceId` -- used for dedup, sidecar, and policy keying -- is decoded.
+      const { resourceId } = parseResourceFileName(fileName)
+
+      // Reject a path-traversal / non-URL-safe resource id parsed from the
+      // archive before its bytes are written to a destination path.
+      assertValidId(resourceId, {
+        kind: 'resource',
+        requestName: 'Import Space'
+      })
+
+      resources.push({
+        fileName,
+        resourceId,
+        body: entry.body
+      })
+    }
+
+    return {
+      collectionId,
+      collectionDescription,
+      collectionPolicy,
+      resources,
+      resourcePolicies,
+      resourceMetadata
+    }
+  })
+
+  return { spacePolicy, collections, revocations: revocationRecords(entries) }
+}
+
+/** Prefix of the archive's Space-scoped revocation entries. */
+const REVOCATIONS_PREFIX = 'revocations/'
+
+/**
+ * Parses the archive's Space-scoped zcap revocation records (top-level
+ * `revocations/<digest>.json` entries; see `revocationFileName`). Archives
+ * from servers that predate revocation export carry none, which yields an
+ * empty list. A record that is not JSON or lacks the `(capability.id,
+ * meta.delegator)` unique key rejects the import -- the store's file names
+ * and uniqueness gate are derived from those fields.
+ * @param entries {Map<string, TarEntry>}
+ * @returns {RevocationRecord[]}
+ */
+function revocationRecords(entries: Map<string, TarEntry>): RevocationRecord[] {
+  const records: RevocationRecord[] = []
+  for (const [entryName, entry] of entries) {
+    if (
+      !entryName.startsWith(REVOCATIONS_PREFIX) ||
+      entry.type !== 'file' ||
+      !entry.body ||
+      entryName.slice(REVOCATIONS_PREFIX.length).includes('/')
+    ) {
+      continue
+    }
+    let record: RevocationRecord
+    try {
+      record = JSON.parse(entry.body.toString('utf8'))
+    } catch (err) {
+      throw new InvalidImportError({
+        message: `Archive revocation record "${entryName}" is not valid JSON.`,
+        cause: err as Error
+      })
+    }
+    if (
+      typeof record?.capability?.id !== 'string' ||
+      record.capability.id.length === 0 ||
+      typeof record?.meta?.delegator !== 'string' ||
+      record.meta.delegator.length === 0
+    ) {
+      throw new InvalidImportError({
+        message: `Archive revocation record "${entryName}" is malformed.`
+      })
+    }
+    records.push(record)
+  }
+  return records
+}

package/src/lib/isJson.ts

@@ -0,0 +1,18 @@
+/**
+ * Helper: true if a content-type denotes JSON -- `application/json` or any
+ * `application/<prefix>+json` structured-suffix variant (e.g.
+ * `application/ld+json`, `application/vnd.api+json`), each optionally followed
+ * by parameters (`; charset=utf-8`). The `json` token is anchored to the end of
+ * the media type so non-JSON types that merely begin with `json` --
+ * `application/jsonl`, `application/json-seq`, `application/json5` -- are NOT
+ * treated as JSON and instead take the binary blob path.
+ * @param options {object}
+ * @param options.contentType {string}
+ * @returns {boolean}
+ */
+export function isJson({ contentType }: { contentType?: string }): boolean {
+  return (
+    typeof contentType === 'string' &&
+    /^application\/(?:[^+\s;]+\+)?json\s*(?:;.*)?$/i.test(contentType)
+  )
+}

package/src/lib/keyEpoch.ts

@@ -0,0 +1,89 @@
+/**
+ * Helpers for the client-declared key-epoch stamp on encrypted-Collection
+ * Resources (the `key-epochs` feature). A writer declares which epoch key
+ * encrypted a Resource's content so a reader can pick the right key BEFORE
+ * attempting decryption; the value is advisory metadata the server stores
+ * opaquely and never computes or verifies (a write may race a rotation).
+ *
+ * On a **content** write the epoch is declared via the `WAS-Key-Epoch` request
+ * header -- one mechanism that works uniformly for JSON, raw-stream binary, and
+ * multipart writes. It is deliberately NOT signature-covered (like `If-Match`):
+ * it is advisory client-declared metadata, not part of the capability
+ * invocation. A content write stores the header's value when present and CLEARS
+ * the stamp when absent -- the new ciphertext's epoch is unknown, and a stale
+ * stamp is worse than none (a reader falls back to `currentEpoch` and can try
+ * other epochs). A `PUT .../meta` may also declare `epoch` as a top-level member
+ * of the body (a sibling of `custom`), where omitting it PRESERVES the stored
+ * value -- see the `putMeta` handler.
+ *
+ * The only validation is that a present value is a non-empty string (400
+ * otherwise); the server never checks it against the Collection marker's epochs.
+ */
+import { InvalidRequestBodyError } from '../errors.js'
+
+/** The request header carrying the client-declared key-epoch on a content write. */
+export const KEY_EPOCH_HEADER = 'was-key-epoch'
+
+/**
+ * Parses the OPTIONAL `WAS-Key-Epoch` request header into the epoch stamp for a
+ * content write. Resolves `{ epoch: string }` for a non-empty single-valued
+ * header, `{ epoch: undefined }` when absent (the content write clears any
+ * stored stamp), and throws `invalid-request-body` (400) for an empty or
+ * array-valued header.
+ * @param options {object}
+ * @param options.headers {object}   the Fastify request headers
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {{ epoch?: string }}
+ */
+export function parseKeyEpochHeader({
+  headers,
+  requestName
+}: {
+  headers: Record<string, string | string[] | undefined>
+  requestName?: string
+}): { epoch?: string } {
+  const value = headers[KEY_EPOCH_HEADER]
+  if (value === undefined) {
+    return {}
+  }
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new InvalidRequestBodyError({
+      requestName,
+      detail: 'The "WAS-Key-Epoch" header must be a non-empty string.'
+    })
+  }
+  return { epoch: value }
+}
+
+/**
+ * Validates and extracts the OPTIONAL top-level `epoch` member of an Update
+ * Resource Metadata (`PUT .../meta`) body. Unlike a content write, a metadata
+ * write PRESERVES the stored epoch when the member is omitted (the stamp
+ * describes the content write, not the metadata write); a present value must be
+ * a non-empty string (400 otherwise). Returns `{ epoch: string }` when supplied,
+ * or `{}` when the member is absent (preserve).
+ * @param options {object}
+ * @param options.body {object}   the parsed request body (already known to be an object)
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {{ epoch?: string }}
+ */
+export function parseMetaEpoch({
+  body,
+  requestName
+}: {
+  body: Record<string, unknown>
+  requestName?: string
+}): { epoch?: string } {
+  if (!Object.hasOwn(body, 'epoch')) {
+    return {}
+  }
+  const value = body.epoch
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new InvalidRequestBodyError({
+      requestName,
+      detail: 'The "epoch" property must be a non-empty string.',
+      pointer: '/epoch'
+    })
+  }
+  return { epoch: value }
+}

package/src/lib/keyedMutex.ts

@@ -0,0 +1,45 @@
+/**
+ * A keyed in-process mutex that serializes async functions per key, ported from
+ * the `@interop/edv-server` storage layer. The conditional-write path uses it to
+ * make a Resource's read-check-write atomic: two concurrent writers of the same
+ * Resource cannot both observe the same prior version and both succeed.
+ *
+ * This is a single-instance lock only. It does NOT coordinate writes across
+ * multiple server processes or a horizontally-scaled deployment -- that is out
+ * of scope for the reference server (see the spec's Conditional Requests note).
+ */
+
+/**
+ * Serializes async functions per key. `run` chains the given function onto the
+ * tail of the key's promise queue, so all functions for the same key execute
+ * strictly one at a time, in call order. Distinct keys run concurrently.
+ */
+export class KeyedMutex {
+  private readonly queues = new Map<string, Promise<unknown>>()
+
+  /**
+   * Runs `fn` once all previously-queued functions for `key` have settled,
+   * resolving (or rejecting) with `fn`'s result. The key's queue entry is
+   * cleaned up once it drains so the map does not grow without bound.
+   * @param key {string}   the serialization key (e.g. a per-Resource path)
+   * @param fn {() => Promise<T>}   the critical section to run under the lock
+   * @returns {Promise<T>}
+   */
+  async run<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    const previous = this.queues.get(key) ?? Promise.resolve()
+    const run = previous.then(fn, fn)
+    // Keep the chain alive even if `fn` rejects, so a failed critical section
+    // does not wedge the key's queue; track this swallowed-rejection tail so the
+    // queue entry can be reclaimed once it drains (unless a later call replaced
+    // it).
+    const tail = run.catch(() => {})
+    this.queues.set(key, tail)
+    try {
+      return await run
+    } finally {
+      if (this.queues.get(key) === tail) {
+        this.queues.delete(key)
+      }
+    }
+  }
+}