was-teaching-server 0.9.1

package/src/plugin.ts

@@ -0,0 +1,288 @@
+/**
+ * The WAS protocol surface as a registerable Fastify plugin (`fastifyWas`):
+ * the storage/config decorations, CORS, multipart and content-type parsers,
+ * and the route groups (the four WAS groups plus the WebKMS `/kms` facet) --
+ * everything from routes.ts down, including the auth/digest hook chains and
+ * the error handler those groups install.
+ *
+ * The community `createApp()` (server.ts) registers this plugin with defaults;
+ * a hardened downstream composition registers the same plugin (with its own
+ * backend and policy plugins around it) and inherits the identical wire
+ * behavior. Wrapped with `fastify-plugin`, so the decorations and parsers land
+ * on the root instance -- while each route group still creates its own
+ * encapsulated context for its hooks.
+ */
+import type { FastifyInstance } from 'fastify'
+import fp from 'fastify-plugin'
+import cors from '@fastify/cors'
+import Multipart from '@fastify/multipart'
+
+import {
+  initCollectionRoutes,
+  initKmsRoutes,
+  initResourceRoutes,
+  initSpaceRoutes,
+  initSpacesRepositoryRoutes
+} from './routes.js'
+import { assertValidServerUrl } from './config.default.js'
+import { defaultBackend } from './storage.js'
+import { onboardingTokenAuthorizer } from './provisioning.js'
+import type {
+  StorageBackend,
+  BackendProviderRegistry,
+  KmsRecordKekRegistry,
+  AuthorizeProvisioning
+} from './types.js'
+
+export interface FastifyWasOptions {
+  /**
+   * This server's base URL; used to build and match ZCap invocationTarget URLs
+   * (host and port must match exactly). When provided, it must be an absolute
+   * `http:`/`https:` URL with no path, query, or fragment (validated at
+   * registration -- sub-path deployment is not supported).
+   */
+  serverUrl?: string
+  /**
+   * Persistence backend to use; defaults to a filesystem backend rooted at the
+   * project `data/` directory. Tests inject their own (e.g. a
+   * FileSystemBackend over a temp dir).
+   */
+  backend?: StorageBackend
+  /**
+   * Per-Space storage limit in bytes (spec "Quotas"); applied only to the
+   * default backend (an injected `backend` carries its own `capacityBytes`).
+   * `undefined` means unlimited; `Infinity` (an explicit `unlimited`) is
+   * normalized by the backend to the same no-limit behavior.
+   */
+  storageLimitPerSpace?: number
+  /**
+   * Per-upload size cap in bytes (spec "Quotas", `maxUploadBytes`); applied
+   * only to the default backend (an injected `backend` carries its own).
+   * `undefined` applies the backend's default-on cap
+   * ({@link DEFAULT_MAX_UPLOAD_BYTES}); `Infinity` (an explicit `unlimited`)
+   * disables the cap.
+   */
+  maxUploadBytes?: number
+  /**
+   * Max Spaces a single controller may create (spec "Quotas", a default-on
+   * count quota); applied only to the default backend (an injected `backend`
+   * carries its own). `undefined` applies the backend's default
+   * ({@link DEFAULT_MAX_SPACES_PER_CONTROLLER}); `Infinity` (an explicit
+   * `unlimited`) disables the cap.
+   */
+  maxSpacesPerController?: number
+  /**
+   * Max Collections a single Space may hold (spec "Quotas", a default-on count
+   * quota); applied only to the default backend (an injected `backend` carries
+   * its own). `undefined` applies the backend's default
+   * ({@link DEFAULT_MAX_COLLECTIONS_PER_SPACE}); `Infinity` (an explicit
+   * `unlimited`) disables the cap.
+   */
+  maxCollectionsPerSpace?: number
+  /**
+   * Max live Resources a single Space may hold across all its Collections (spec
+   * "Quotas", a default-on count quota); applied only to the default backend
+   * (an injected `backend` carries its own). `undefined` applies the backend's
+   * default ({@link DEFAULT_MAX_RESOURCES_PER_SPACE}); `Infinity` (an explicit
+   * `unlimited`) disables the cap.
+   */
+  maxResourcesPerSpace?: number
+  /**
+   * The provider-adapter registry the resolver uses to build a Collection's
+   * selected external backend; defaults to an empty map (no external backend
+   * is operable).
+   */
+  providers?: BackendProviderRegistry
+  /**
+   * The registration allowlist of backend `provider` names; `undefined` means
+   * permissive.
+   */
+  enabledBackendProviders?: string[]
+  /**
+   * The at-rest WebKMS key-record encryption registry (config `KMS_RECORD_KEK` /
+   * `KMS_RECORD_KEKS` / `KMS_RECORD_CURRENT_KEK`); `undefined` (or
+   * `currentKekId: null`) disables encryption -- key records are written
+   * plaintext (the teaching default).
+   */
+  kmsRecordKek?: KmsRecordKekRegistry
+  /**
+   * Custom provisioning gate for `POST /spaces/` and `POST /kms/keystores`;
+   * receives `{ request }` and returns `'verify'` (normal zcap path), `'grant'`
+   * (authorized by the callback -- skip zcap verification), or `'deny'` (403).
+   * `undefined` means allow (the teaching default). Mutually exclusive with
+   * `onboardingToken`.
+   */
+  authorizeProvisioning?: AuthorizeProvisioning
+  /**
+   * Shared-secret gate for `POST /spaces/` and `POST /kms/keystores` (config
+   * `WAS_ONBOARDING_TOKEN`); when set, those two endpoints require an
+   * `Authorization: Bearer <token>` header, which then substitutes for zcap
+   * verification on that request. `undefined` means disabled (the teaching
+   * default). Mutually exclusive with `authorizeProvisioning`.
+   */
+  onboardingToken?: string
+}
+
+/**
+ * Decorates the instance with the WAS storage/config surface, registers the
+ * protocol-level plugins and content-type parsers, and mounts the route groups.
+ * @param fastify {import('fastify').FastifyInstance}
+ * @param options {FastifyWasOptions}
+ * @returns {Promise<void>}
+ */
+async function wasPlugin(
+  fastify: FastifyInstance,
+  options: FastifyWasOptions
+): Promise<void> {
+  const {
+    serverUrl,
+    backend,
+    storageLimitPerSpace,
+    maxUploadBytes,
+    maxSpacesPerController,
+    maxCollectionsPerSpace,
+    maxResourcesPerSpace,
+    providers,
+    enabledBackendProviders,
+    kmsRecordKek,
+    authorizeProvisioning,
+    onboardingToken
+  } = options
+
+  // Fail fast on a malformed base URL: a serverUrl carrying a path, query, or
+  // fragment silently breaks every ZCap invocationTarget match and Location
+  // header (URL-joins drop the base path), so it is rejected at registration.
+  if (serverUrl !== undefined) {
+    assertValidServerUrl(serverUrl)
+  }
+
+  // The two provisioning gates are alternative ways to configure the same seam.
+  if (authorizeProvisioning && onboardingToken) {
+    throw new Error(
+      'authorizeProvisioning and onboardingToken are mutually exclusive.'
+    )
+  }
+
+  fastify.decorate('serverUrl', serverUrl as string)
+  // Route the backend's diagnostics through the Fastify pino logger (the backend
+  // defaults to a silent logger until wired here).
+  const storage =
+    backend ??
+    defaultBackend({
+      capacityBytes: storageLimitPerSpace,
+      maxUploadBytes,
+      maxSpacesPerController,
+      maxCollectionsPerSpace,
+      maxResourcesPerSpace
+    })
+  storage.logger = fastify.log
+  fastify.decorate('storage', storage)
+
+  // Backend lifecycle: run the optional startup hook (e.g. Postgres connect +
+  // migrations) during registration, before the server starts listening, and
+  // wire the optional shutdown hook (pool drain) to Fastify's close.
+  if (storage.init) {
+    await storage.init()
+  }
+  if (storage.close) {
+    fastify.addHook('onClose', async () => {
+      await storage.close!()
+    })
+  }
+
+  // The provider-adapter registry the resolver (lib/backendRegistry.ts) consults
+  // to build a Collection's selected external backend. Injected (rather than a
+  // module-global mutable registry) so parallel test suites stay isolated -- the
+  // same rationale as the injected `storage`. Empty in production this stage.
+  fastify.decorate('backendProviders', providers ?? new Map())
+  // The optional registration allowlist (config `WAS_ENABLED_BACKENDS`);
+  // `undefined` = permissive (any provider may be registered).
+  fastify.decorate('enabledBackendProviders', enabledBackendProviders)
+  // The at-rest key-record encryption registry (config `KMS_RECORD_KEK`);
+  // `undefined` = disabled (records written plaintext). Read at the KMS
+  // orchestration seam (KeyRequest), never inside a backend.
+  fastify.decorate('kmsRecordKek', kmsRecordKek)
+  // The provisioning gate for `POST /spaces/` and `POST /kms/keystores`: a
+  // custom callback, or the stock onboarding-token check when a token is set,
+  // or `undefined` = allow (the teaching default). Read by the `provisioningGate`
+  // onRequest hook installed by those two route groups.
+  fastify.decorate(
+    'authorizeProvisioning',
+    authorizeProvisioning ??
+      (onboardingToken ? onboardingTokenAuthorizer(onboardingToken) : undefined)
+  )
+
+  // Disable CORS
+  fastify.register(cors, {
+    origin: '*',
+    methods: ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']
+  })
+
+  // Multipart file uploading. The cap is `files: 2`, not `1`: a write MUST carry
+  // exactly one file part, and `resolveResourceInput` enforces that by iterating
+  // the parts and rejecting a second one with `invalid-request-body` (400). With
+  // a `files: 1` limit busboy would instead silently drop the second part and
+  // raise its own `FST_FILES_LIMIT` (413), so the second part must be allowed
+  // through to the iterator to be caught and rejected with the correct error.
+  //
+  // `fileSize` bounds the in-memory buffer of the single permitted part to the
+  // backend's per-upload cap (`throwFileSizeLimit` makes `toBuffer()` throw at
+  // the boundary, which the request layer maps to `payload-too-large` (413)) --
+  // so an oversize multipart upload is rejected before it is fully buffered.
+  // The cap is default-on (the backend applies `DEFAULT_MAX_UPLOAD_BYTES` when
+  // none is configured), so `storage.maxUploadBytes` is `undefined` here only
+  // when the operator explicitly opted out (`MAX_UPLOAD_BYTES=unlimited`); the
+  // conditional spread then leaves multipart uncapped. Large binaries should
+  // use the streaming raw-body path, not multipart.
+  fastify.register(Multipart, {
+    throwFileSizeLimit: true,
+    limits: {
+      files: 2,
+      ...(storage.maxUploadBytes !== undefined && {
+        fileSize: storage.maxUploadBytes
+      })
+    }
+  })
+
+  // Parse `application/<suffix>+json` bodies (e.g. `application/jose+json` for
+  // EDV-over-WAS encrypted documents, `application/ld+json`, etc.) as JSON, the
+  // same as plain `application/json`. Fastify's built-in JSON parser only
+  // matches `application/json` exactly, so structured-suffix JSON media types
+  // would otherwise be rejected with a 415. The regex deliberately requires a
+  // non-`+` suffix before `+json`, so it never shadows the built-in parser for
+  // plain `application/json`. Registered on the root instance so every route
+  // group inherits it; `isJson()` already treats `+json` as JSON downstream
+  // (digest capture, resource-input resolution).
+  fastify.addContentTypeParser(
+    /^application\/[^+]+\+json/,
+    { parseAs: 'string' },
+    fastify.getDefaultJsonParser('error', 'error')
+  )
+
+  // Catch-all parser for arbitrary binary representations. The spec ("Content
+  // Types and Representations") lets a Resource be any media type, so a raw
+  // (non-multipart) blob PUT/POST -- `application/octet-stream`,
+  // `application/jsonl`, images, etc. -- must reach the handler as a byte
+  // stream. Fastify only ships parsers for `application/json` and `text/plain`
+  // and would otherwise reject every other media type with a 415 before the
+  // route runs. This bare pass-through leaves `request.body` as the raw stream,
+  // which `resolveResourceInput` normalizes to a `kind: 'binary'` input that the
+  // backend streams straight to storage. More specific parsers still win over
+  // this fallback: the built-in JSON/text parsers, the `+json` regex above,
+  // `@fastify/multipart`'s `multipart/*`, and the `application/x-tar` import
+  // parser are all matched ahead of it.
+  fastify.addContentTypeParser('*', function (_request, payload, done) {
+    done(null, payload)
+  })
+
+  fastify.register(initSpacesRepositoryRoutes)
+  fastify.register(initSpaceRoutes)
+  fastify.register(initCollectionRoutes)
+  fastify.register(initResourceRoutes)
+  fastify.register(initKmsRoutes)
+}
+
+export const fastifyWas = fp(wasPlugin, {
+  fastify: '5.x',
+  name: 'fastify-was'
+})

package/src/policy.ts

@@ -0,0 +1,176 @@
+/**
+ * Access-control policy evaluation: resolves the effective policy for a target
+ * (most-specific level wins) and decides whether a policy grants an action.
+ * Policies are the fallback authorization path -- consulted when a capability
+ * invocation is absent or does not grant access (see authorize.ts). v1
+ * recognizes only `{ "type": "PublicCanRead" }`; any other `type` grants nothing
+ * (fail-closed). Also builds the RFC9264 linkset that advertises a Space's or
+ * Collection's policy resource for discovery.
+ */
+import type { FastifyBaseLogger } from 'fastify'
+import type { PolicyDocument, StorageBackend } from './types.js'
+import {
+  POLICY_LINK_RELATION,
+  BACKEND_LINK_RELATION,
+  QUOTA_LINK_RELATION,
+  BACKENDS_AVAILABLE_LINK_RELATION,
+  QUOTAS_LINK_RELATION
+} from './config.default.js'
+import {
+  collectionPath,
+  spacePath,
+  policyPath,
+  backendPath,
+  quotaPath,
+  backendsPath,
+  quotasPath
+} from './lib/paths.js'
+
+/** The kind of access a request needs; derived from the HTTP method. */
+export type AccessAction = 'read' | 'write'
+
+/**
+ * Resolves the policy that governs a target, honoring the spec's
+ * most-specific-wins inheritance: a Resource policy overrides a Collection
+ * policy, which overrides a Space policy. The first level that has a policy
+ * document is the effective policy; if none do, resolves undefined.
+ *
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @param [options.resourceId] {string}
+ * @returns {Promise<PolicyDocument | undefined>}
+ */
+export async function resolveEffectivePolicy({
+  storage,
+  spaceId,
+  collectionId,
+  resourceId
+}: {
+  storage: StorageBackend
+  spaceId: string
+  collectionId?: string
+  resourceId?: string
+}): Promise<PolicyDocument | undefined> {
+  if (collectionId !== undefined && resourceId !== undefined) {
+    const resourcePolicy = await storage.getPolicy({
+      spaceId,
+      collectionId,
+      resourceId
+    })
+    if (resourcePolicy) {
+      return resourcePolicy
+    }
+  }
+  if (collectionId !== undefined) {
+    const collectionPolicy = await storage.getPolicy({ spaceId, collectionId })
+    if (collectionPolicy) {
+      return collectionPolicy
+    }
+  }
+  return await storage.getPolicy({ spaceId })
+}
+
+/**
+ * Decides whether a policy document grants the requested action. Dispatches on
+ * the policy `type`; an absent policy or an unrecognized `type` grants nothing
+ * (fail-closed).
+ *
+ * @param options {object}
+ * @param [options.policy] {PolicyDocument}   the effective policy, if any
+ * @param options.action {AccessAction}
+ * @param [options.logger] {FastifyBaseLogger}   logger for the fail-closed warn
+ *   on an unrecognized policy type
+ * @returns {boolean}
+ */
+export function policyGrants({
+  policy,
+  action,
+  logger
+}: {
+  policy?: PolicyDocument
+  action: AccessAction
+  logger?: FastifyBaseLogger
+}): boolean {
+  if (!policy) {
+    return false
+  }
+  switch (policy.type) {
+    case 'PublicCanRead':
+      return action === 'read'
+    default:
+      // Unknown policy type: grant nothing, fall through to zcap-only decision.
+      // Warn so a misconfigured / unsupported policy is diagnosable (the
+      // fail-closed behavior itself is correct; this is purely a signal).
+      logger?.warn(
+        { policyType: policy.type },
+        'Unrecognized access-control policy type; granting nothing (fail-closed).'
+      )
+      return false
+  }
+}
+
+/**
+ * Builds the RFC9264 linkset for a Space or Collection, advertising its
+ * auxiliary resources for discovery. Collection vs Space is selected by whether
+ * `collectionId` is present.
+ *
+ * Relations:
+ * - `policy` (`POLICY_LINK_RELATION`) -- the access-control policy resource,
+ *   advertised only when a policy document is set at that exact level.
+ * - On a Collection (`collectionId` present): `backend` (`BACKEND_LINK_RELATION`)
+ *   and `quota` (`QUOTA_LINK_RELATION`), advertised unconditionally (every
+ *   Collection has a selected backend and a quota report endpoint).
+ * - On a Space (`collectionId` absent): `backends-available`
+ *   (`BACKENDS_AVAILABLE_LINK_RELATION`) and `quotas` (`QUOTAS_LINK_RELATION`),
+ *   advertised unconditionally (both endpoints always exist).
+ *
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @returns {Promise<object>} a `{ linkset: [...] }` object
+ */
+export async function buildLinkset({
+  storage,
+  spaceId,
+  collectionId
+}: {
+  storage: StorageBackend
+  spaceId: string
+  collectionId?: string
+}): Promise<{ linkset: Array<Record<string, unknown>> }> {
+  const anchor =
+    collectionId !== undefined
+      ? collectionPath({ spaceId, collectionId })
+      : spacePath({ spaceId })
+  const policyHref = policyPath({ spaceId, collectionId })
+  const policy =
+    collectionId !== undefined
+      ? await storage.getPolicy({ spaceId, collectionId })
+      : await storage.getPolicy({ spaceId })
+
+  const entry: Record<string, unknown> = { anchor }
+  if (policy) {
+    entry[POLICY_LINK_RELATION] = [
+      { href: policyHref, type: 'application/json' }
+    ]
+  }
+  if (collectionId !== undefined) {
+    entry[BACKEND_LINK_RELATION] = [
+      { href: backendPath({ spaceId, collectionId }), type: 'application/json' }
+    ]
+    entry[QUOTA_LINK_RELATION] = [
+      { href: quotaPath({ spaceId, collectionId }), type: 'application/json' }
+    ]
+  } else {
+    entry[BACKENDS_AVAILABLE_LINK_RELATION] = [
+      { href: backendsPath({ spaceId }), type: 'application/json' }
+    ]
+    entry[QUOTAS_LINK_RELATION] = [
+      { href: quotasPath({ spaceId }), type: 'application/json' }
+    ]
+  }
+  return { linkset: [entry] }
+}

package/src/provisioning.ts

@@ -0,0 +1,98 @@
+/**
+ * Provisioning gate for the two open provisioning endpoints (`POST /spaces/`
+ * and `POST /kms/keystores`). By default provisioning is allowed -- anyone may
+ * create a Space or keystore by proving control of the controller DID named in
+ * the request body (the teaching-server behavior). A deployment that wants to
+ * gate provisioning supplies either an `onboardingToken` (a shared secret,
+ * checked here by the stock `onboardingTokenAuthorizer`) or a custom
+ * `authorizeProvisioning` callback; both flow through the same seam.
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify'
+import { createHash, timingSafeEqual } from 'node:crypto'
+import type { AuthorizeProvisioning, ProvisioningDecision } from './types.js'
+import {
+  InvalidOnboardingTokenError,
+  MissingOnboardingTokenError,
+  ProvisioningNotAuthorizedError
+} from './errors.js'
+
+/**
+ * The exact route URLs the provisioning gate acts on. `/spaces` (no trailing
+ * slash) is included so a token-authorized request reaches the canonical-slash
+ * 308 redirect instead of failing the auth-header check first.
+ */
+const PROVISIONING_ROUTES = new Set(['/spaces', '/spaces/', '/kms/keystores'])
+
+/**
+ * onRequest hook: the provisioning gate. Runs first in the hook chain of the
+ * SpacesRepository and `/kms` route groups. For a `POST` to one of the two
+ * provisioning endpoints it consults the configured `authorizeProvisioning`
+ * callback: `verify` proceeds to normal zcap verification, `grant` marks the
+ * request as provisioning-authorized (skipping zcap verification downstream),
+ * and `deny` refuses with a 403. Every other request (and every deployment with
+ * no callback configured) passes straight through, so the default zcap path is
+ * unchanged.
+ * @param request {import('fastify').FastifyRequest}
+ * @param reply {import('fastify').FastifyReply}
+ * @returns {Promise<void>}
+ */
+export async function provisioningGate(
+  request: FastifyRequest,
+  _reply: FastifyReply
+): Promise<void> {
+  // Only the two provisioning POST endpoints are gated; everything else passes.
+  if (
+    request.method !== 'POST' ||
+    !PROVISIONING_ROUTES.has(request.routeOptions.url ?? '')
+  ) {
+    return
+  }
+  const authorize = request.server.authorizeProvisioning
+  // No policy configured: default allow -- the zcap path is unchanged.
+  if (!authorize) {
+    return
+  }
+  const decision = await authorize({ request })
+  if (decision === 'grant') {
+    request.provisioningAuthorized = true
+    return
+  }
+  if (decision === 'deny') {
+    throw new ProvisioningNotAuthorizedError()
+  }
+  // 'verify': fall through to the normal zcap capability-invocation path.
+}
+
+/**
+ * Builds the stock onboarding-token provisioning authorizer: a shared-secret
+ * gate that requires an `Authorization: Bearer <token>` header matching the
+ * configured token. A request signed with a zcap `Authorization: Signature ...`
+ * also lands here -- with a token configured, provisioning requires the token,
+ * full stop. Throws `MissingOnboardingTokenError` (401) when no Bearer token is
+ * present and `InvalidOnboardingTokenError` (403) when it does not match; a
+ * match returns `grant`.
+ * @param onboardingToken {string}   the configured shared-secret token
+ * @returns {AuthorizeProvisioning}
+ */
+export function onboardingTokenAuthorizer(
+  onboardingToken: string
+): AuthorizeProvisioning {
+  return async function authorizeWithOnboardingToken({
+    request
+  }): Promise<ProvisioningDecision> {
+    const header = request.headers.authorization
+    const match = header?.match(/^Bearer\s+(.+)$/i)
+    if (!match) {
+      throw new MissingOnboardingTokenError()
+    }
+    const presented = match[1] as string
+    // Timing-safe comparison over fixed-length SHA-256 digests, so mismatched
+    // token lengths do not leak through `timingSafeEqual`'s length check.
+    const presentedDigest = createHash('sha256').update(presented).digest()
+    const expectedDigest = createHash('sha256').update(onboardingToken).digest()
+    if (!timingSafeEqual(presentedDigest, expectedDigest)) {
+      throw new InvalidOnboardingTokenError()
+    }
+    return 'grant'
+  }
+}