was-teaching-server 0.9.1

package/src/requests/SpacesRepositoryRequest.ts

@@ -0,0 +1,194 @@
+/**
+ * Request handler for SpacesRepository operations:
+ * - POST /spaces/ (Create Space)
+ * - GET /spaces/ (List Spaces).
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify'
+import { v4 as uuidv4 } from 'uuid'
+import { isRootInvocation, verifyZcap } from '../zcap.js'
+import { invalidateSpaceDescription } from './spaceContext.js'
+import { verifyBodyControllerConsent } from './controllerConsent.js'
+import { invokerDid } from '../auth-header-hooks.js'
+import { assertValidId } from '../lib/validateId.js'
+import { spacePath, spacesPath } from '../lib/paths.js'
+import { assertValidController } from '../lib/validateDid.js'
+import {
+  SpaceControllerMismatchError,
+  InvalidRequestBodyError,
+  IdConflictError
+} from '../errors.js'
+import type { IDID, SpaceSummary, SpaceListing } from '../types.js'
+
+export class SpacesRepositoryRequest {
+  /**
+   * GET /spaces/
+   * Request handler for "List Spaces" (spec "List Spaces Operation"): returns
+   * `{ url, totalItems, items }` with only the Spaces the caller is authorized
+   * to see. An anonymous or unauthorized request is NOT an error -- it gets the
+   * empty-items 200, the spec's explicit exception to 404 masking -- so nothing
+   * is revealed about which Spaces exist.
+   *
+   * Authorization is per Space controller: the root capability for `/spaces/`
+   * is synthesized with the candidate Space's controller (see `verifyZcap`), so
+   * one verification decides visibility for every Space sharing that
+   * controller. A bare-root invocation can only verify where the signer *is*
+   * the controller, so those candidates are filtered before any signature
+   * work; a delegated invocation reveals the Spaces of whichever controller
+   * roots its capability chain.
+   *
+   * @param request {import('fastify').FastifyRequest}
+   * @param reply {import('fastify').FastifyReply}
+   * @returns {Promise<FastifyReply>}
+   */
+  static async get(
+    request: FastifyRequest,
+    reply: FastifyReply
+  ): Promise<FastifyReply> {
+    const { url, method, headers } = request
+    const { serverUrl, storage } = request.server
+
+    const items: SpaceSummary[] = []
+    const listing: SpaceListing = { url: spacesPath(), totalItems: 0, items }
+
+    // No (complete) authorization presented: authorized to see no Spaces,
+    // which is the empty 200, not an error.
+    if (!request.zcap?.invocation) {
+      return reply.send(listing)
+    }
+
+    const { keyId, invocation } = request.zcap
+    const [zcapSigningDid] = keyId.split('#')
+    const rootInvocation = isRootInvocation({ invocation })
+    const allowedTarget = new URL(spacesPath(), serverUrl).toString()
+
+    // Visibility is identical across Spaces sharing a controller (the
+    // verification depends only on the controller), so verify once per
+    // distinct controller. A failed verification just excludes that
+    // controller's Spaces -- never an error response.
+    const verifiedByController = new Map<IDID, boolean>()
+    for (const space of await storage.listSpaces()) {
+      const { controller } = space
+      if (rootInvocation && controller !== zcapSigningDid) {
+        continue // a bare-root invocation cannot verify for another controller
+      }
+      let authorized = verifiedByController.get(controller)
+      if (authorized === undefined) {
+        try {
+          const result = await verifyZcap({
+            url,
+            allowedTarget,
+            allowedAction: 'GET',
+            method,
+            headers,
+            serverUrl,
+            spaceController: controller
+          })
+          authorized = result.verified === true
+        } catch (err) {
+          request.log.debug(
+            { err },
+            'List Spaces: invocation did not verify for a candidate controller'
+          )
+          authorized = false
+        }
+        verifiedByController.set(controller, authorized)
+      }
+      if (authorized) {
+        const item: SpaceSummary = {
+          id: space.id,
+          url: spacePath({ spaceId: space.id })
+        }
+        if (space.name !== undefined) {
+          item.name = space.name
+        }
+        items.push(item)
+      }
+    }
+
+    listing.totalItems = items.length
+    return reply.send(listing)
+  }
+
+  /**
+   * POST /spaces/
+   * Request handler for "Create Space" request
+   * Before this, `parseAuthHeaders()` hook executed, resulting in:
+   * request.zcap: {
+   *   keyId, headers, signature, created, expires, invocation, digest
+   * }
+   *
+   * @param request {import('fastify').FastifyRequest}
+   * @param reply {import('fastify').FastifyReply}
+   * @returns {Promise<FastifyReply>}
+   */
+  static async post(
+    request: FastifyRequest<{
+      Body: { id?: string; name?: string; controller: IDID }
+    }>,
+    reply: FastifyReply
+  ): Promise<FastifyReply> {
+    const { body } = request
+    const { serverUrl, storage } = request.server
+
+    // The Space Description body must carry a controller DID. The `name`
+    // property is optional (see spec: Space Description object).
+    if (!body?.controller) {
+      throw new InvalidRequestBodyError({
+        requestName: 'Create Space',
+        detail: 'Space Description body requires a "controller" property.',
+        pointer: '#/controller'
+      })
+    }
+    // Reject a malformed / non-`did:key` controller before it is stored.
+    assertValidController(body.controller, { requestName: 'Create Space' })
+    // Reject a path-traversal / non-URL-safe client-supplied space id.
+    if (body.id !== undefined) {
+      assertValidId(body.id, { kind: 'space', requestName: 'Create Space' })
+      // POST must never replace an existing Space: the signature below is
+      // verified against the *body's* controller, so without this check any
+      // caller could overwrite a Space (controller included) by POSTing its
+      // id. Spec: `id-conflict` (409); create-or-replace by id is PUT's job.
+      if (await storage.getSpaceDescription({ spaceId: body.id })) {
+        throw new IdConflictError({ kind: 'Space' })
+      }
+    }
+
+    const spaceId = body.id || uuidv4()
+    const spaceDescription = { ...body, id: spaceId, type: ['Space'] }
+
+    // The invocation must be *authorized by* the body's controller (spec:
+    // Create Space): signed directly by it, or via a delegation chain rooted
+    // in it (see `verifyBodyControllerConsent`). Skipped when the provisioning
+    // policy already vouched for the request (e.g. a valid onboarding token).
+    if (!request.provisioningAuthorized) {
+      await verifyBodyControllerConsent({
+        request,
+        controller: body.controller,
+        allowedTarget: new URL(spacesPath(), serverUrl).toString(),
+        allowedAction: 'POST',
+        MismatchError: SpaceControllerMismatchError,
+        requestName: 'Create Space'
+      })
+    }
+
+    // zCap checks out, continue. A token-provisioned create carries no
+    // invocation, so it records no `createdBy`.
+    const createdBy = invokerDid(request)
+    await storage.writeSpace({ spaceId, spaceDescription, createdBy })
+    // Bust any cached (e.g. negatively cached) description for this id so the
+    // next read sees the freshly created Space.
+    invalidateSpaceDescription({ storage, spaceId })
+
+    const createdSpaceUrl = new URL(
+      spacesPath({ spaceId }),
+      serverUrl
+    ).toString()
+    reply.header('Location', createdSpaceUrl)
+    // Echo what was persisted, `createdBy` included, so the create response and
+    // a subsequent Get Space agree. An id already in use was rejected as a 409
+    // above, so this write created the Space and its creator is this invoker.
+    return reply
+      .status(201)
+      .send({ ...spaceDescription, ...(createdBy && { createdBy }) })
+  }
+}

package/src/requests/collectionContext.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared handler prelude: fetch a Collection Description or 404 (paralleling
+ * spaceContext.ts / keystoreContext.ts). Nearly every Collection- and
+ * Resource-level handler repeats the same shape after authorization -- load
+ * the Collection Description for context, throw `CollectionNotFoundError`
+ * when absent -- so it lives here.
+ */
+import { CollectionNotFoundError } from '../errors.js'
+import type { CollectionDescription, StorageBackend } from '../types.js'
+
+/**
+ * Fetches a Collection Description or throws CollectionNotFoundError (404)
+ * when absent.
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.requestName {string}   human-readable request name, used in
+ *   error titles
+ * @returns {Promise<CollectionDescription & { descriptionVersion?: number }>}
+ */
+export async function getCollectionOrThrow({
+  storage,
+  spaceId,
+  collectionId,
+  requestName
+}: {
+  storage: StorageBackend
+  spaceId: string
+  collectionId: string
+  requestName: string
+}): Promise<CollectionDescription & { descriptionVersion?: number }> {
+  const collectionDescription = await storage.getCollectionDescription({
+    spaceId,
+    collectionId
+  })
+  if (!collectionDescription) {
+    throw new CollectionNotFoundError({ requestName })
+  }
+  return collectionDescription
+}

package/src/requests/controllerConsent.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared handler prelude for the create-by-consent bootstrap (paralleling
+ * spaceContext.ts / keystoreContext.ts): the operations that create a
+ * top-level resource owned by a DID named in the request *body* (Create
+ * Space, the create form of Update Space, Create Keystore) have no stored
+ * controller to verify against yet, so the invocation must be *authorized by*
+ * the body's controller -- signed directly by it, or via a delegation chain
+ * rooted in it. Verifying against the signer instead would let anyone install
+ * an unrelated, non-consenting DID as controller.
+ */
+import type { FastifyRequest } from 'fastify'
+import { handleZcapVerify, isRootInvocation } from '../zcap.js'
+import type { ProblemError } from '../errors.js'
+import type { IDID } from '../types.js'
+
+/**
+ * Verifies that the invocation is authorized by `controller` (the DID named
+ * in the request body). For the bare-root invocation form the signer *is* the
+ * invoker, so a mismatch is rejected up front, before any signature work. The
+ * delegated form instead carries a capability chain, judged by the
+ * verification (which synthesizes the root capability with `controller` as
+ * its controller): a delegated invocation that fails to verify is a chain not
+ * rooted in the body's controller, wrapped in `MismatchError` (spec
+ * `controller-mismatch`, 400). Root-form verification failures keep their
+ * generic errors -- the signer already matched the controller.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies url, method, headers,
+ *   logger, `request.zcap`, and `request.server` for serverUrl
+ * @param options.controller {IDID}   the controller DID named in the request
+ *   body, which must authorize the invocation
+ * @param options.allowedTarget {string}   the capability's expected
+ *   invocationTarget (full URL, including host and port)
+ * @param options.allowedAction {string}   expected action, e.g. an HTTP verb
+ * @param options.MismatchError {new (options) => ProblemError}   the
+ *   operation's `controller-mismatch` error class (constructed with
+ *   `{ zcapSigningDid, controller, cause? }`)
+ * @param [options.requestName] {string}   human-readable request name, used
+ *   in error titles
+ * @param [options.maxChainLength] {number}   max delegation chain length,
+ *   root included (see `verifyZcap`)
+ * @param [options.maxDelegationTtl] {number}   max delegated-zcap TTL in
+ *   milliseconds (see `verifyZcap`)
+ * @returns {Promise<void>}
+ */
+export async function verifyBodyControllerConsent({
+  request,
+  controller,
+  allowedTarget,
+  allowedAction,
+  MismatchError,
+  requestName,
+  maxChainLength,
+  maxDelegationTtl
+}: {
+  request: FastifyRequest
+  controller: IDID
+  allowedTarget: string
+  allowedAction: string
+  MismatchError: new (options: {
+    zcapSigningDid: string
+    controller: string
+    cause?: Error
+  }) => ProblemError
+  requestName?: string
+  maxChainLength?: number
+  maxDelegationTtl?: number
+}): Promise<void> {
+  const { url, method, headers } = request
+  const { serverUrl } = request.server
+  // The strict `requireAuthHeaders` hook guarantees auth headers were present
+  // and `parseAuthHeaders` set `request.zcap` before any calling handler.
+  const { keyId, invocation } = request.zcap!
+  const [zcapSigningDid] = keyId.split('#')
+  const rootInvocation = isRootInvocation({ invocation })
+  if (rootInvocation && zcapSigningDid !== controller) {
+    throw new MismatchError({ zcapSigningDid: zcapSigningDid!, controller })
+  }
+
+  try {
+    await handleZcapVerify({
+      url,
+      allowedTarget,
+      allowedAction,
+      method,
+      headers,
+      serverUrl,
+      spaceController: controller,
+      requestName,
+      logger: request.log,
+      // Consent verifies a chain rooted in the BODY's controller for a
+      // resource that does not exist yet, so there is no keystore or Space
+      // scope a revocation could have been stored under.
+      revocation: 'no-revocation-scope',
+      maxChainLength,
+      maxDelegationTtl
+    })
+  } catch (err) {
+    if (!rootInvocation) {
+      throw new MismatchError({
+        zcapSigningDid: zcapSigningDid!,
+        controller,
+        cause: err as Error
+      })
+    }
+    throw err
+  }
+}

package/src/requests/keystoreContext.ts

@@ -0,0 +1,124 @@
+/**
+ * Shared WebKMS keystore context helper (the `/kms` facet): the keystore
+ * analogue of `fetchSpaceAndVerify`
+ * (spaceContext.ts), used by the keystore-lifecycle, key-operation, and
+ * revocation request handlers.
+ */
+import type { FastifyRequest } from 'fastify'
+import { handleZcapVerify } from '../zcap.js'
+import { isUrlSafeSegment } from '../lib/validateId.js'
+import { kmsKeystoresPath } from '../lib/paths.js'
+import {
+  KMS_MAX_CHAIN_LENGTH,
+  KMS_MAX_DELEGATION_TTL
+} from '../config.default.js'
+import { KeystoreNotFoundError } from '../errors.js'
+import type { KeystoreConfig } from '../types.js'
+
+/**
+ * Loads a keystore config by its URL param, masking an unknown (or
+ * non-URL-safe) id as the 404 `KeystoreNotFoundError` -- the WAS
+ * existence-masking convention. The verification-free half of
+ * `fetchKeystoreAndVerify`, for handlers that need the config before they can
+ * build their expected values (the revocation route).
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies `request.server.storage`
+ * @param options.keystoreId {string}   the keystore's local id (URL param)
+ * @param options.requestName {string}   request name used in error titles
+ * @returns {Promise<KeystoreConfig>}   the stored config
+ */
+export async function fetchKeystore({
+  request,
+  keystoreId,
+  requestName
+}: {
+  request: FastifyRequest
+  keystoreId: string
+  requestName: string
+}): Promise<KeystoreConfig> {
+  // A non-URL-safe id cannot name a stored keystore (ids are server-generated
+  // base58 values) and must not reach the filesystem layer: same 404 masking.
+  if (!isUrlSafeSegment(keystoreId)) {
+    throw new KeystoreNotFoundError({ requestName })
+  }
+  const config = await request.server.storage.getKeystore({ keystoreId })
+  if (!config) {
+    throw new KeystoreNotFoundError({ requestName })
+  }
+  return config
+}
+
+/**
+ * Loads the keystore config (404 `KeystoreNotFoundError` when absent -- the
+ * WAS existence-masking convention) and verifies the capability invocation
+ * against the *stored* config's controller, with the keystore URL as the root
+ * invocation target. `allowedAction` is the webkms action (`read` / `write` /
+ * an operation name), not the HTTP verb. The verification carries the unified
+ * `/kms` delegation policy (`KMS_MAX_CHAIN_LENGTH`, `KMS_MAX_DELEGATION_TTL`;
+ * the zcap library itself already requires `expires` on every delegated
+ * capability) and the keystore's revocation-store chain inspector, so a
+ * revoked delegation fails on every keystore-rooted route.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies url, method, headers,
+ *   logger, and `request.server` for serverUrl + storage
+ * @param options.keystoreId {string}   the keystore's local id (URL param)
+ * @param options.allowedAction {string}   expected zcap action
+ * @param options.requestName {string}   request name used in error titles
+ * @param [options.allowTargetAttenuation] {boolean}   accept a request URL
+ *   under the keystore URL (the key routes: every key operation roots in the
+ *   keystore's capability, with the key URL as an attenuated target -- see
+ *   `verifyZcap`)
+ * @param [options.allowTargetQuery] {boolean}   tolerate query parameters on
+ *   the request URL that are absent from the capability target (the List Keys
+ *   route's `?limit` / `?cursor` pagination parameters select a page within an
+ *   already-authorized target; the same treatment as List Keystores)
+ * @returns {Promise<{ config: KeystoreConfig, dereferencedChainLength: number }>}
+ *   the stored config and the verified invocation's chain length, root
+ *   included (a root invocation is 1) -- the input to the per-key
+ *   `maxCapabilityChainLength` gate at operation time
+ */
+export async function fetchKeystoreAndVerify({
+  request,
+  keystoreId,
+  allowedAction,
+  requestName,
+  allowTargetAttenuation = false,
+  allowTargetQuery = false
+}: {
+  request: FastifyRequest
+  keystoreId: string
+  allowedAction: string
+  requestName: string
+  allowTargetAttenuation?: boolean
+  allowTargetQuery?: boolean
+}): Promise<{ config: KeystoreConfig; dereferencedChainLength: number }> {
+  const { serverUrl, storage } = request.server
+  const config = await fetchKeystore({ request, keystoreId, requestName })
+  const { url, method, headers } = request
+  const allowedTarget = new URL(
+    kmsKeystoresPath({ keystoreId }),
+    serverUrl
+  ).toString()
+  const zcapVerifyResult = await handleZcapVerify({
+    url,
+    allowedTarget,
+    allowedAction,
+    method,
+    headers,
+    serverUrl,
+    spaceController: config.controller,
+    requestName,
+    logger: request.log,
+    allowTargetAttenuation,
+    allowTargetQuery,
+    revocation: { storage, scope: { keystoreId } },
+    maxChainLength: KMS_MAX_CHAIN_LENGTH,
+    maxDelegationTtl: KMS_MAX_DELEGATION_TTL
+  })
+  return {
+    config,
+    dereferencedChainLength: zcapVerifyResult.dereferencedChain?.length ?? 1
+  }
+}

package/src/requests/resourceInput.ts

@@ -0,0 +1,118 @@
+/**
+ * Request-layer adapter: resolves a Fastify request into a transport-neutral
+ * `ResourceInput` value object, so that storage backends never depend on
+ * Fastify. JSON bodies pass through as parsed values; raw blob bodies and
+ * multipart uploads are normalized to a readable byte stream.
+ */
+import type { FastifyRequest } from 'fastify'
+import { Readable } from 'node:stream'
+import { isJson } from '../lib/isJson.js'
+import {
+  MissingContentTypeError,
+  InvalidRequestBodyError,
+  PayloadTooLargeError
+} from '../errors.js'
+import type { ResourceInput, StorageBackend } from '../types.js'
+
+/**
+ * @param request {import('fastify').FastifyRequest}
+ * @param [dataBackend] {StorageBackend}   the resolved data-plane backend the
+ *   write targets (the Collection's selected backend); its `maxUploadBytes` and
+ *   `describe().id` size and label the `payload-too-large` (413) for a multipart
+ *   upload. Defaults to the server `storage` backend, read lazily only on the
+ *   multipart path so non-multipart callers need not supply it.
+ * @returns {Promise<ResourceInput>}
+ */
+export async function resolveResourceInput(
+  request: FastifyRequest,
+  dataBackend?: StorageBackend
+): Promise<ResourceInput> {
+  const contentType = request.headers['content-type']
+  if (!contentType) {
+    throw new MissingContentTypeError({ requestName: 'Write Resource' })
+  }
+
+  if (isJson({ contentType })) {
+    return { kind: 'json', contentType, data: request.body }
+  }
+  if (contentType.startsWith('multipart')) {
+    // Spec ("Content Types and Representations"): a multipart write MUST carry
+    // exactly one file part -- reject zero file parts, or more than one, as
+    // `invalid-request-body` (400). Iterate every part rather than calling
+    // `request.file()` (which silently takes the first file part and ignores any
+    // extras). `toBuffer()` drains each file part's stream, which both lets the
+    // iterator advance to detect a second (disallowed) part and yields the exact
+    // byte length to pre-flight the upload cap. Buffering the part in memory is
+    // acceptable for this multipart convenience path (the HTML form workflow) --
+    // large binaries should use the streaming raw-body path. The buffer is
+    // bounded by the backend's `maxUploadBytes` (the multipart `fileSize` limit
+    // set in `plugin.ts`): `toBuffer()` throws `FST_REQ_FILE_TOO_LARGE` at the
+    // boundary, mapped here to `payload-too-large` (413).
+    const backend = dataBackend ?? request.server.storage
+    let file: { mimetype: string; bytes: Buffer } | undefined
+    for await (const part of request.parts()) {
+      if (part.type !== 'file') {
+        continue
+      }
+      if (file) {
+        throw new InvalidRequestBodyError({
+          requestName: 'Write Resource',
+          detail: 'multipart request must carry exactly one file part.'
+        })
+      }
+      try {
+        file = { mimetype: part.mimetype, bytes: await part.toBuffer() }
+      } catch (err) {
+        if ((err as { code?: string }).code === 'FST_REQ_FILE_TOO_LARGE') {
+          throw new PayloadTooLargeError({
+            maxUploadBytes: backend.maxUploadBytes!,
+            backendId: backend.describe().id
+          })
+        }
+        throw err
+      }
+    }
+    if (!file) {
+      throw new InvalidRequestBodyError({
+        requestName: 'Write Resource',
+        detail: 'multipart request is missing a file part.'
+      })
+    }
+    return {
+      kind: 'binary',
+      contentType: file.mimetype,
+      stream: Readable.from(file.bytes),
+      declaredBytes: file.bytes.length
+    }
+  }
+  // A `text/plain` body arrives already parsed as a **string** (Fastify's
+  // built-in text parser, which the `*` catch-all does not shadow); other
+  // `text/*` and binary media types arrive as a raw stream. Wrap a string (or
+  // Buffer) as a byte stream so it is written verbatim -- piping a string into
+  // the backend's `stream.pipeline` would iterate it by UTF-16 code unit (one
+  // write per character, splitting astral-plane characters into lone
+  // surrogates), corrupting the stored bytes.
+  const body = request.body
+  if (typeof body === 'string' || Buffer.isBuffer(body)) {
+    const bytes = Buffer.from(body as string | Buffer)
+    return {
+      kind: 'binary',
+      contentType,
+      stream: Readable.from(bytes),
+      declaredBytes: bytes.length
+    }
+  }
+  // A raw (non-multipart) blob body carries its size in `Content-Length` when
+  // present; expose it as `declaredBytes` so the backend can pre-flight the
+  // quota check before streaming. Ignore an absent or malformed value.
+  const contentLength = Number(request.headers['content-length'])
+  return {
+    kind: 'binary',
+    contentType,
+    stream: body as Readable,
+    declaredBytes:
+      Number.isInteger(contentLength) && contentLength >= 0
+        ? contentLength
+        : undefined
+  }
+}