was-teaching-server 0.9.1

package/src/lib/preconditions.ts

@@ -0,0 +1,145 @@
+/**
+ * Backend-agnostic conditional-write precondition evaluation (the
+ * `conditional-writes` feature). Both storage backends evaluate `If-Match` /
+ * `If-None-Match` against a Resource's current state through these two
+ * helpers, so the 412 semantics cannot drift between them. Callers MUST invoke
+ * them atomically with the write that follows (under the filesystem backend's
+ * per-Resource lock, or inside the Postgres backend's row-locking
+ * transaction).
+ */
+import { PreconditionFailedError } from '../errors.js'
+import { formatEtag } from './etag.js'
+
+/**
+ * Evaluates a content-write (or delete) precondition against a Resource's
+ * current state. Throws `PreconditionFailedError` (412) when it is not met.
+ * `ifNoneMatch` (`If-None-Match: *`, create-if-absent) takes precedence over
+ * `ifMatch` when both are present (RFC9110): the write proceeds only if the
+ * Resource is absent. `ifMatch` (update-if-unchanged) requires the Resource to
+ * exist with a current ETag equal to the supplied validator.
+ * @param options {object}
+ * @param options.resourceId {string}   for the error detail
+ * @param options.exists {boolean}   whether the Resource currently exists (a
+ *   tombstone counts as "does not exist")
+ * @param options.currentVersion {number}   the Resource's current content
+ *   `version` (0 for a legacy Resource without one)
+ * @param [options.ifMatch] {string}   a quoted ETag (`If-Match`)
+ * @param [options.ifNoneMatch] {boolean}   `If-None-Match: *` (create-if-absent)
+ * @returns {void}
+ */
+export function assertWritePrecondition({
+  resourceId,
+  exists,
+  currentVersion,
+  ifMatch,
+  ifNoneMatch
+}: {
+  resourceId: string
+  exists: boolean
+  currentVersion: number
+  ifMatch?: string
+  ifNoneMatch?: boolean
+}): void {
+  if (ifNoneMatch) {
+    if (exists) {
+      throw new PreconditionFailedError({
+        detail: `Resource '${resourceId}' already exists (If-None-Match: *).`
+      })
+    }
+    return
+  }
+
+  if (ifMatch === undefined) {
+    return
+  }
+
+  // `If-Match` (update-if-unchanged): the Resource must exist and its current
+  // ETag must equal the supplied validator.
+  if (!exists) {
+    throw new PreconditionFailedError({
+      detail: `Resource '${resourceId}' does not exist; If-Match cannot be satisfied.`
+    })
+  }
+  const currentEtag = formatEtag(currentVersion)
+  if (currentEtag !== ifMatch) {
+    throw new PreconditionFailedError({
+      detail: `Resource '${resourceId}' ETag ${currentEtag} does not match If-Match ${ifMatch}.`
+    })
+  }
+}
+
+/**
+ * Evaluates a Collection Description write precondition against the Collection's
+ * current description `version` (the `key-epochs` / conditional-Collection-write
+ * feature). Throws `PreconditionFailedError` (412) when the supplied `If-Match`
+ * validator does not equal the current description ETag. Only `If-Match`
+ * (update-if-unchanged) is supported for Collections; a create through an
+ * unconditional PUT is unaffected. MUST be called atomically with the write
+ * (under the filesystem backend's per-Collection lock, or inside the Postgres
+ * backend's row-locking transaction).
+ * @param options {object}
+ * @param options.collectionId {string}   for the error detail
+ * @param options.currentVersion {number}   the Collection's current description
+ *   `version` (0 for a legacy Collection without one, or before its first write)
+ * @param [options.ifMatch] {string}   a quoted ETag (`If-Match`)
+ * @returns {void}
+ */
+export function assertCollectionWritePrecondition({
+  collectionId,
+  currentVersion,
+  ifMatch
+}: {
+  collectionId: string
+  currentVersion: number
+  ifMatch?: string
+}): void {
+  if (ifMatch === undefined) {
+    return
+  }
+  const currentEtag = formatEtag(currentVersion)
+  if (currentEtag !== ifMatch) {
+    throw new PreconditionFailedError({
+      detail: `Collection '${collectionId}' ETag ${currentEtag} does not match If-Match ${ifMatch}.`
+    })
+  }
+}
+
+/**
+ * Evaluates a metadata-write (`/meta`) precondition against a Resource's
+ * current `metaVersion`. Throws `PreconditionFailedError` (412) when it is not
+ * met. `If-None-Match: *` means "only if no metadata has been written yet"
+ * (`metaVersion` unset); `If-Match` pins the current `metaVersion` ETag.
+ * @param options {object}
+ * @param options.resourceId {string}   for the error detail
+ * @param [options.metaVersion] {number}   the current `metaVersion`
+ *   (`undefined` until the first metadata write)
+ * @param [options.ifMatch] {string}   a quoted ETag (`If-Match`)
+ * @param [options.ifNoneMatch] {boolean}   `If-None-Match: *`
+ * @returns {void}
+ */
+export function assertMetaWritePrecondition({
+  resourceId,
+  metaVersion,
+  ifMatch,
+  ifNoneMatch
+}: {
+  resourceId: string
+  metaVersion?: number
+  ifMatch?: string
+  ifNoneMatch?: boolean
+}): void {
+  if (ifNoneMatch) {
+    if (metaVersion !== undefined) {
+      throw new PreconditionFailedError({
+        detail: `Resource '${resourceId}' metadata already exists (If-None-Match: *).`
+      })
+    }
+  } else if (ifMatch !== undefined) {
+    const currentEtag = formatEtag(metaVersion ?? 0)
+    if (currentEtag !== ifMatch) {
+      throw new PreconditionFailedError({
+        detail: `Resource '${resourceId}' metadata ETag ${currentEtag} does not match If-Match ${ifMatch}.`
+      })
+    }
+  }
+}

package/src/lib/resourceFileName.ts

@@ -0,0 +1,69 @@
+/**
+ * On-disk resource-filename codec: the single shared home for encoding a
+ * Resource's representation file name (`r.<resourceId>.<encodedContentType>.<ext>`)
+ * and decoding it back. Kept low-level (no imports from `src/backends/` or
+ * `importTar.ts`) so both the filesystem backend and the tar importer can depend
+ * on it without an import cycle.
+ */
+import * as mime from 'mime-types'
+
+/**
+ * Percent-encodes a filename segment so it carries no literal `.`, the
+ * structural delimiter of `r.<resourceId>.<encodedContentType>.<ext>`.
+ * `encodeURIComponent` leaves `.` unescaped, so escape it explicitly to `%2E`;
+ * `decodeURIComponent` reverses both. This keeps resource ids and content-types
+ * that legitimately contain dots (e.g. `index.html`, `application/vnd.api+json`)
+ * unambiguously parseable -- without it, a dotted id mis-splits and is read back
+ * under the wrong id and content-type. For dot-free segments (the common case)
+ * the result is byte-identical to the previous `encodeURIComponent`-only scheme.
+ * @param segment {string}
+ * @returns {string}
+ */
+export function encodeFilenameSegment(segment: string): string {
+  return encodeURIComponent(segment).replace(/\./g, '%2E')
+}
+
+/**
+ * Builds the on-disk filename for a resource representation:
+ * `r.<resourceId>.<encodedContentType>.<ext>`. Both the `resourceId` and
+ * content-type segments are dot-escaped (see {@link encodeFilenameSegment}) so
+ * the three `.` separators are the only literal dots.
+ * @param options {object}
+ * @param options.resourceId {string}
+ * @param options.contentType {string}
+ * @returns {string}
+ */
+export function fileNameFor({
+  resourceId,
+  contentType
+}: {
+  resourceId: string
+  contentType: string
+}): string {
+  const encodedId = encodeFilenameSegment(resourceId)
+  const encodedType = encodeFilenameSegment(contentType)
+  const extension = mime.extension(contentType) || 'blob'
+  return `r.${encodedId}.${encodedType}.${extension}`
+}
+
+/**
+ * Parses an on-disk resource filename (`r.<resourceId>.<encodedContentType>.<ext>`)
+ * back into its components, reversing the dot-escaping {@link fileNameFor}
+ * applies. Returns the exact stored content-type (decoded from the filename
+ * segment, more reliable than `mime.lookup` on the extension), falling back to
+ * the spec default `application/octet-stream` if unparseable.
+ * @param fileName {string}   the basename of the resource file
+ * @returns {{ resourceId: string, contentType: string }}
+ */
+export function parseResourceFileName(fileName: string): {
+  resourceId: string
+  contentType: string
+} {
+  const [, encodedId, encodedType] = fileName.split('.')
+  return {
+    resourceId: encodedId ? decodeURIComponent(encodedId) : '',
+    contentType: encodedType
+      ? decodeURIComponent(encodedType)
+      : 'application/octet-stream'
+  }
+}

package/src/lib/revocations.ts

@@ -0,0 +1,116 @@
+/**
+ * The zcap revocation chain-inspection hook. Wired into every keystore-rooted
+ * and Space-rooted
+ * verification as the zcap library's `inspectCapabilityChain` extension
+ * point, it fails a verification whose dereferenced chain contains any
+ * capability with a stored revocation. Both route families share this hook;
+ * they differ only in the scope the storage lookup is keyed on (a keystore or
+ * a Space). Also home to the revocation-record file-name codec shared by the
+ * filesystem store and both backends' Space exports.
+ */
+import { createHash } from 'node:crypto'
+import type {
+  CapabilityChainDetails,
+  InspectCapabilityChain
+} from '@interop/zcap'
+import type {
+  CapabilitySummary,
+  RevocationScope,
+  StorageBackend
+} from '../types.js'
+
+/**
+ * The file name a revocation record is stored (and archived) under:
+ * the `(delegator, capabilityId)` unique key folded into a SHA-256 digest,
+ * plus `.json`. Both parts are arbitrary-length URIs, so hashing (rather than
+ * encoding) keeps the name fixed-width and filesystem-safe. Shared by the
+ * filesystem store and both backends' `exportSpace`, so the same record
+ * always lands under the same name.
+ * @param options {object}
+ * @param options.delegator {string}   the revoked capability's delegator
+ * @param options.capabilityId {string}   the revoked capability's id
+ * @returns {string}
+ */
+export function revocationFileName({
+  delegator,
+  capabilityId
+}: {
+  delegator: string
+  capabilityId: string
+}): string {
+  const digest = createHash('sha256')
+    .update(`${delegator}\n${capabilityId}`)
+    .digest('hex')
+  return `${digest}.json`
+}
+
+/**
+ * Extracts the `(capabilityId, delegator)` lookup pairs from a verified,
+ * dereferenced capability chain. The root capability is skipped -- root zcaps
+ * cannot be revoked -- and so is any link whose verify result carries no
+ * delegator (nothing to key a revocation record on).
+ *
+ * @param options {object}
+ * @param options.capabilityChain {object[]}   the dereferenced chain (root to
+ *   tail)
+ * @param options.capabilityChainMeta {object[]}   the per-capability verify
+ *   results (the root's entry has a `null` `verifyResult`)
+ * @returns {CapabilitySummary[]}
+ */
+export function capabilitySummaries({
+  capabilityChain,
+  capabilityChainMeta
+}: CapabilityChainDetails): CapabilitySummary[] {
+  const summaries: CapabilitySummary[] = []
+  for (const [index, capability] of capabilityChain.entries()) {
+    // skip the root zcap; it cannot be revoked
+    if (index === 0) {
+      continue
+    }
+    const verifyResult = capabilityChainMeta[index]?.verifyResult as {
+      results?: Array<{ purposeResult?: { delegator?: { id?: string } } }>
+    } | null
+    const delegator = verifyResult?.results?.[0]?.purposeResult?.delegator?.id
+    if (delegator) {
+      summaries.push({ capabilityId: capability.id, delegator })
+    }
+  }
+  return summaries
+}
+
+/**
+ * Builds the `inspectCapabilityChain` hook for one scope: valid when no
+ * delegated capability in the chain has a stored revocation under that
+ * keystore or Space (a chain of just the root has nothing to check, so a bare
+ * root invocation never reaches the store).
+ *
+ * @param options {object}
+ * @param options.storage {StorageBackend}   supplies the revocation store
+ * @param options.scope {RevocationScope}   the keystore or Space the lookup is
+ *   keyed on
+ * @returns {InspectCapabilityChain}
+ */
+export function revocationChainInspector({
+  storage,
+  scope
+}: {
+  storage: StorageBackend
+  scope: RevocationScope
+}): InspectCapabilityChain {
+  return async details => {
+    const capabilities = capabilitySummaries(details)
+    if (capabilities.length === 0) {
+      return { valid: true }
+    }
+    const revoked = await storage.isRevoked({ scope, capabilities })
+    if (revoked) {
+      return {
+        valid: false,
+        error: new Error(
+          'One or more capabilities in the chain have been revoked.'
+        )
+      }
+    }
+    return { valid: true }
+  }
+}

package/src/lib/validateDid.ts

@@ -0,0 +1,41 @@
+/**
+ * Validation for the `controller` DID supplied in Space Description request
+ * bodies. The server's only DID method is `did:key` with Ed25519 keys, whose
+ * multibase encoding always begins `z6Mk` (the `0xed01` Ed25519-pub multicodec
+ * prefix) followed by base58btc characters. This asserts that shape at the
+ * request layer so a malformed or non-`did:key` controller is rejected on the
+ * way in, rather than being stored and only failing later at
+ * capability-verification time.
+ */
+import { InvalidControllerError } from '../errors.js'
+import type { IDID } from '../types.js'
+
+// An Ed25519 `did:key` is `did:key:` + `z6Mk` + a base58btc payload. The
+// base58btc (Bitcoin) alphabet omits `0`, `O`, `I`, and `l`.
+const DID_KEY_ED25519_PATTERN = /^did:key:z6Mk[1-9A-HJ-NP-Za-km-z]+$/
+
+/**
+ * Returns true when `value` is a syntactically valid Ed25519 `did:key` DID.
+ * @param value {unknown}
+ * @returns {boolean}
+ */
+export function isValidController(value: unknown): value is IDID {
+  return typeof value === 'string' && DID_KEY_ED25519_PATTERN.test(value)
+}
+
+/**
+ * Asserts that `controller` is a valid Ed25519 `did:key`, throwing
+ * InvalidControllerError (400) otherwise.
+ * @param controller {unknown}   the `controller` value from the request body
+ * @param options {object}
+ * @param [options.requestName] {string}   request name used in the error title
+ * @returns {void}
+ */
+export function assertValidController(
+  controller: unknown,
+  { requestName }: { requestName?: string } = {}
+): void {
+  if (!isValidController(controller)) {
+    throw new InvalidControllerError({ requestName })
+  }
+}

package/src/lib/validateId.ts

@@ -0,0 +1,148 @@
+/**
+ * Id sanitization for path-traversal defense. `spaceId` / `collectionId` /
+ * `resourceId` values arrive from URL params, request bodies, and tar-entry
+ * names, then flow into filesystem paths (and glob patterns). This validator
+ * rejects anything that is not a single, URL-safe path segment -- empty, `.`,
+ * `..`, a value containing `/` or `\`, or any character outside the RFC 3986
+ * "unreserved" set -- so a malicious id can never escape its parent directory.
+ * It also rejects Collection / Resource ids that collide with the spec's
+ * Reserved Path Segment Registry (`reserved-id`, 409).
+ */
+import {
+  InvalidSpaceIdError,
+  InvalidCollectionIdError,
+  InvalidResourceIdError,
+  ReservedIdError
+} from '../errors.js'
+
+/** Which kind of id is being validated (selects the thrown error class). */
+export type IdKind = 'space' | 'collection' | 'resource'
+
+/**
+ * URL-safe id charset: the RFC 3986 "unreserved" characters
+ * (ALPHA / DIGIT / `-` / `.` / `_` / `~`). This excludes path separators
+ * (`/`, `\`) and every glob metacharacter, so a validated id is safe to use
+ * both as a single path segment and inside a glob pattern.
+ */
+const ID_PATTERN = /^[A-Za-z0-9._~-]+$/
+
+/**
+ * Whether `id` is a single, URL-safe path segment: non-empty, not `.` / `..`,
+ * free of path separators, and made only of the RFC 3986 "unreserved" charset
+ * ({@link ID_PATTERN}). The shared safety predicate behind `assertValidId` (and
+ * `assertValidBackendId` in `lib/backends.ts`); does **not** check the reserved
+ * path-segment registry, which is id-kind specific.
+ * @param id {string}
+ * @returns {boolean}
+ */
+export function isUrlSafeSegment(id: string): boolean {
+  return (
+    typeof id === 'string' &&
+    id.length > 0 &&
+    id !== '.' &&
+    id !== '..' &&
+    !id.includes('/') &&
+    !id.includes('\\') &&
+    ID_PATTERN.test(id)
+  )
+}
+
+/**
+ * Reserved path segments from the spec's Reserved Path Segment Registry (plus
+ * the server's own non-spec `import` endpoint). A client-chosen Collection or
+ * Resource id matching one of these would shadow the reserved route at that
+ * position (e.g. a Collection named `export` would shadow
+ * `/space/{id}/export`), so the spec requires rejecting it with 409
+ * `reserved-id`. Space ids have no reserved siblings (`/space/{id}` has no
+ * static neighbors), so no set exists for the `space` kind.
+ *
+ * Exported as the server's authoritative per-kind sets so a client can mirror
+ * them rather than hand-maintaining a copy (client #13). NOTE the one known
+ * divergence from the pure spec registry: `import` is this server's non-spec
+ * tar-import endpoint, so a client mirroring the *spec* registry should omit
+ * it. Kept byte-identical to `@interop/storage-core`'s exported registry
+ * (locked by a drift-guard test); the local definition keeps the id-safety
+ * logic self-contained.
+ */
+export const RESERVED_COLLECTION_IDS = new Set([
+  'backends',
+  'collections',
+  'export',
+  'import', // non-spec: this server's tar-import endpoint
+  'linkset',
+  'policy',
+  'query',
+  'quotas'
+])
+export const RESERVED_RESOURCE_IDS = new Set([
+  'backend',
+  'linkset',
+  'policy',
+  'query',
+  'quota'
+])
+
+/**
+ * Asserts that an id is a single, URL-safe path segment that does not collide
+ * with a reserved path segment -- throwing the typed 400 `invalid-id` error
+ * matching `kind` for an unsafe id, or the 409 `reserved-id` error for a
+ * reserved-segment collision.
+ * @param id {string}   the id parsed from a URL param, body, or tar entry
+ * @param options {object}
+ * @param options.kind {IdKind}   which id is being validated
+ * @param [options.requestName] {string}   request name used in the error title
+ * @returns {void}
+ */
+export function assertValidId(
+  id: string,
+  { kind, requestName }: { kind: IdKind; requestName?: string }
+): void {
+  if (!isUrlSafeSegment(id)) {
+    switch (kind) {
+      case 'collection':
+        throw new InvalidCollectionIdError({ requestName })
+      case 'resource':
+        throw new InvalidResourceIdError({ requestName })
+      default:
+        throw new InvalidSpaceIdError({ requestName })
+    }
+  }
+
+  // Collections and Resources may not take a reserved path-segment name.
+  const reserved =
+    kind === 'collection'
+      ? RESERVED_COLLECTION_IDS
+      : kind === 'resource'
+        ? RESERVED_RESOURCE_IDS
+        : undefined
+  if (reserved?.has(id)) {
+    throw new ReservedIdError({ kind, id })
+  }
+}
+
+/**
+ * Convenience wrapper that validates whichever of `spaceId` / `collectionId` /
+ * `resourceId` are present on a request's params object. Call at the top of a
+ * handler, before any storage access.
+ * @param ids {object}
+ * @param [ids.spaceId] {string}
+ * @param [ids.collectionId] {string}
+ * @param [ids.resourceId] {string}
+ * @param options {object}
+ * @param [options.requestName] {string}   request name used in the error title
+ * @returns {void}
+ */
+export function assertValidIds(
+  ids: { spaceId?: string; collectionId?: string; resourceId?: string },
+  { requestName }: { requestName?: string } = {}
+): void {
+  if (ids.spaceId !== undefined) {
+    assertValidId(ids.spaceId, { kind: 'space', requestName })
+  }
+  if (ids.collectionId !== undefined) {
+    assertValidId(ids.collectionId, { kind: 'collection', requestName })
+  }
+  if (ids.resourceId !== undefined) {
+    assertValidId(ids.resourceId, { kind: 'resource', requestName })
+  }
+}