@dwk/solid-pod 0.1.0-beta.0

package/src/config.ts

@@ -0,0 +1,254 @@
+/**
+ * Configuration, the declared Cloudflare `Env` fragment, and config resolution
+ * for `@dwk/solid-pod`.
+ *
+ * Per the composition contract, the package never reads the global environment
+ * directly: all tunables (base URL, token issuer/JWKS, accepted audience,
+ * offload threshold, replay/GC windows) are passed into {@link createSolidPod}
+ * and {@link createSolidPodGc}, so a pod can be instantiated multiple times and
+ * unit-tested in isolation. The Cloudflare bindings — the per-pod Durable
+ * Object namespace and the R2 blob bucket — are the only runtime coupling, and
+ * a missing one fails loudly at startup.
+ */
+
+import { noopLogger, noopMetrics, type Logger, type Metrics } from "@dwk/log";
+
+import type { SolidPodObject } from "./pod";
+
+/** Cloudflare bindings required by the Solid Pod handler and Durable Object. */
+export interface SolidPodEnv {
+  /** Durable Object namespace for the per-pod class ({@link SolidPodObject}). */
+  readonly POD: DurableObjectNamespace<SolidPodObject>;
+  /** R2 bucket holding blob bodies. */
+  readonly BLOBS: R2Bucket;
+  /**
+   * Shared D1 database tracking orphaned blob keys for the out-of-band GC cron.
+   * Optional: when bound, the DO opportunistically forwards its transactional
+   * orphan outbox here after writes so {@link createSolidPodGc} can reclaim them
+   * without ever waking a Durable Object.
+   */
+  readonly GC_DB?: D1Database;
+}
+
+/** Cloudflare bindings required by the out-of-band R2 garbage-collection cron. */
+export interface SolidPodGcEnv {
+  /** R2 bucket holding blob bodies. */
+  readonly BLOBS: R2Bucket;
+  /** Shared D1 database tracking orphaned blob keys (see `@dwk/store`). */
+  readonly GC_DB: D1Database;
+}
+
+/**
+ * A verification key set used to validate issuer-signed access tokens. Supply
+ * either static {@link SolidPodConfig.jwks} (hermetic, no network) or a
+ * {@link SolidPodConfig.jwksUri} the handler fetches and caches.
+ */
+export type Jwks = readonly JsonWebKey[];
+
+/** Configuration passed to {@link createSolidPod}. */
+export interface SolidPodConfig {
+  /**
+   * The pod's identity root / base URL, e.g. `https://pod.example`. Used as the
+   * origin for absolute resource IRIs in WAC and content negotiation, and as
+   * the default token audience. No trailing slash.
+   */
+  readonly baseUrl: string;
+
+  /**
+   * The pod owner's WebID(s). An owner is always granted full access
+   * (`Read`/`Write`/`Append`/`Control`) regardless of ACLs, which bootstraps
+   * ACL management — without it, no one could create the first `.acl`.
+   */
+  readonly owner?: string | readonly string[];
+
+  /**
+   * Accepted access-token issuer (`iss`). When set, a token whose `iss` differs
+   * is rejected. Required unless a custom {@link SolidPodConfig.authenticate}
+   * hook is supplied.
+   */
+  readonly issuer?: string;
+
+  /**
+   * Accepted token audience(s) (`aud`). A token is accepted when its `aud`
+   * intersects this set. Defaults to `["solid", baseUrl]`.
+   */
+  readonly audience?: string | readonly string[];
+
+  /**
+   * Required access-token header `typ`. Solid-OIDC / RFC 9068 access tokens
+   * carry `typ: at+jwt`; enforcing it stops an ID token or other issuer-signed
+   * JWT sharing the same `iss`/`aud`/`webid` from being replayed as an access
+   * token (token-type confusion). Compared case-insensitively, tolerating the
+   * `application/at+jwt` media-type form. Set to `null` to skip the check for
+   * issuers that omit `typ`. Defaults to `"at+jwt"`.
+   */
+  readonly accessTokenType?: string | null;
+
+  /** Static JWK verification keys for the issuer (hermetic alternative to {@link jwksUri}). */
+  readonly jwks?: Jwks;
+
+  /** Issuer JWKS endpoint; fetched and cached when {@link jwks} is not given. */
+  readonly jwksUri?: string;
+
+  /**
+   * Bodies larger than this (bytes) are offloaded to R2 as opaque blobs instead
+   * of the DO SQLite quad store. Defaults to the ~2 MB DO-cell ceiling.
+   */
+  readonly maxInlineBytes?: number;
+
+  /**
+   * The documented read-replay tradeoff: reads MAY reuse a DPoP proof within
+   * this many seconds (edge-cached window) rather than enforcing strict
+   * single-use `jti`. Writes are always strict. Defaults to `0` (strict reads).
+   */
+  readonly readReplayWindowSeconds?: number;
+
+  /**
+   * Allow **unauthenticated** writes (`PUT`/`POST`/`PATCH`/`DELETE`) when WAC
+   * grants the public agent class (`acl:agentClass foaf:Agent`) the needed
+   * mode. Such requests carry no DPoP proof, so they get **no `jti` replay /
+   * anti-abuse protection** — the "DPoP everywhere" guarantee does not hold for
+   * them. Defaults to `false`: a tokenless write is refused `401` even where a
+   * public-write ACL would otherwise permit it. Set `true` to opt into
+   * public write as an explicit, documented tradeoff.
+   */
+  readonly allowAnonymousWrites?: boolean;
+
+  /**
+   * GC safety window (ms) advertised to the cron handler; an orphaned R2 object
+   * is only reclaimed once it is older than this. MUST be ≥ the maximum write
+   * duration. Defaults to five minutes.
+   */
+  readonly gcSafetyWindowMs?: number;
+
+  /** Injectable clock (epoch ms) for deterministic tests. Defaults to `Date.now`. */
+  readonly now?: () => number;
+
+  /** `fetch` implementation used to resolve {@link jwksUri}; defaults to global `fetch`. */
+  readonly fetch?: typeof fetch;
+
+  /**
+   * Override the edge authentication step entirely. When provided, the handler
+   * calls this instead of the built-in JWKS + DPoP validation — useful for
+   * tests and for issuers the default verifier does not cover. Returning
+   * `null` means "no/invalid credentials" and the request proceeds
+   * unauthenticated (WAC then decides public access).
+   */
+  readonly authenticate?: (
+    request: Request,
+  ) => Promise<AuthContext | null> | AuthContext | null;
+
+  /**
+   * Logger for auth/authz events; defaults to a no-op. Wired once here at the
+   * composition boundary (see `@dwk/log`) to surface edge-authentication
+   * rejections and the Durable Object's WAC denials, anonymous-write refusals,
+   * and DPoP replay rejections instead of swallowing them.
+   */
+  readonly logger?: Logger;
+  /**
+   * Metrics sink for the same events; defaults to a no-op. Wire an adapter (e.g.
+   * `analyticsEngineMetrics` from `@dwk/log`) to chart what the logger names —
+   * auth rejections by reason, WAC denials/min, replay rejections.
+   */
+  readonly metrics?: Metrics;
+}
+
+/** The authenticated facts the front door hands to the Durable Object. */
+export interface AuthContext {
+  /** The authenticated agent's WebID. */
+  readonly webid: string;
+  /** The verified DPoP proof's `jti`, for write replay enforcement in the DO. */
+  readonly jti: string;
+  /** The DPoP key thumbprint the token is bound to (`cnf.jkt`). */
+  readonly jkt: string;
+}
+
+/** Fully-resolved configuration with defaults applied. */
+export interface ResolvedConfig {
+  readonly baseUrl: string;
+  readonly origin: string;
+  readonly owners: readonly string[];
+  readonly issuer?: string;
+  readonly audience: readonly string[];
+  readonly accessTokenType: string | null;
+  readonly jwks?: Jwks;
+  readonly jwksUri?: string;
+  readonly maxInlineBytes?: number;
+  readonly readReplayWindowSeconds: number;
+  readonly allowAnonymousWrites: boolean;
+  readonly gcSafetyWindowMs: number;
+  readonly now: () => number;
+  readonly fetch: typeof fetch;
+  readonly authenticate?: SolidPodConfig["authenticate"];
+  readonly logger: Logger;
+  readonly metrics: Metrics;
+}
+
+/** Default GC safety window: five minutes, comfortably above any write. */
+const DEFAULT_GC_SAFETY_WINDOW_MS = 5 * 60 * 1000;
+
+/** Internal headers the trusted front door uses to hand auth facts to the DO. */
+export const INTERNAL_HEADERS = {
+  /** Authenticated agent WebID (absent ⇒ unauthenticated request). */
+  webid: "x-solid-webid",
+  /** Verified DPoP `jti` (present on authenticated writes for replay control). */
+  jti: "x-solid-jti",
+  /** Verified DPoP key thumbprint (`cnf.jkt`). */
+  jkt: "x-solid-jkt",
+  /** JSON-encoded subset of config the DO needs (offload threshold, etc.). */
+  config: "x-solid-config",
+  /**
+   * DO→front-door: a machine-readable authorization outcome (see `PodOutcome`)
+   * the composition boundary logs via the injected seams, then strips before the
+   * response reaches the client.
+   */
+  outcome: "x-solid-outcome",
+} as const;
+
+/** Strip the trailing slash from a base URL so path joins are unambiguous. */
+function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+
+/** Apply defaults and derived values to raw {@link SolidPodConfig}. */
+export function resolveConfig(config: SolidPodConfig): ResolvedConfig {
+  if (!config.baseUrl) {
+    throw new Error("@dwk/solid-pod: `baseUrl` is required");
+  }
+  const baseUrl = normalizeBaseUrl(config.baseUrl);
+  const origin = new URL(baseUrl).origin;
+  const audience =
+    config.audience === undefined
+      ? ["solid", baseUrl]
+      : typeof config.audience === "string"
+        ? [config.audience]
+        : [...config.audience];
+
+  const owners =
+    config.owner === undefined
+      ? []
+      : typeof config.owner === "string"
+        ? [config.owner]
+        : [...config.owner];
+
+  return {
+    baseUrl,
+    origin,
+    owners,
+    issuer: config.issuer,
+    audience,
+    accessTokenType:
+      config.accessTokenType === undefined ? "at+jwt" : config.accessTokenType,
+    jwks: config.jwks,
+    jwksUri: config.jwksUri,
+    maxInlineBytes: config.maxInlineBytes,
+    readReplayWindowSeconds: config.readReplayWindowSeconds ?? 0,
+    allowAnonymousWrites: config.allowAnonymousWrites ?? false,
+    gcSafetyWindowMs: config.gcSafetyWindowMs ?? DEFAULT_GC_SAFETY_WINDOW_MS,
+    now: config.now ?? (() => Date.now()),
+    fetch: config.fetch ?? fetch,
+    authenticate: config.authenticate,
+    logger: config.logger ?? noopLogger,
+    metrics: config.metrics ?? noopMetrics,
+  };
+}

package/src/encoding.ts

@@ -0,0 +1,32 @@
+/**
+ * base64url + UTF-8 helpers for the edge auth path (JWT/JWKS, DPoP hashing).
+ *
+ * Dependency-free and runtime-agnostic (Web Crypto / `atob` / `btoa` only) so
+ * the surrounding modules unit-test without a Workers runtime.
+ */
+
+/** Encode bytes as unpadded base64url (RFC 4648 §5). */
+export function bytesToBase64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+/** Decode unpadded (or padded) base64url to bytes. */
+export function base64urlToBytes(segment: string): Uint8Array {
+  const b64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+  const padded =
+    b64.length % 4 === 0 ? b64 : b64 + "=".repeat(4 - (b64.length % 4));
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** Decode unpadded base64url to a UTF-8 string. */
+export function base64urlToText(segment: string): string {
+  return new TextDecoder().decode(base64urlToBytes(segment));
+}

package/src/gc.ts

@@ -0,0 +1,47 @@
+/**
+ * The R2 garbage-collection cron handler.
+ *
+ * Each pod's Durable Object forwards its orphaned blob keys (copy-on-write
+ * displacements and deletes) into a shared D1 table as it writes. This handler
+ * — wired to a Cloudflare cron trigger — reclaims those R2 objects once they
+ * are older than a safety window ≥ the maximum write duration, touching only D1
+ * and R2 and never waking a Durable Object. The reclamation logic lives in
+ * `@dwk/store`; this is the thin endpoint wiring.
+ */
+
+import { collectGarbage, ensureGcSchema } from "@dwk/store";
+
+import {
+  resolveConfig,
+  type SolidPodConfig,
+  type SolidPodGcEnv,
+} from "./config";
+
+/** A `scheduled`-compatible cron handler for R2 blob garbage collection. */
+export type SolidPodGcHandler = (
+  event: ScheduledController,
+  env: SolidPodGcEnv,
+  ctx: ExecutionContext,
+) => Promise<void>;
+
+/**
+ * Create the cron handler that reclaims orphaned R2 blobs. Bind it to a
+ * `scheduled` trigger alongside the pod Worker; it shares the same `BLOBS`
+ * bucket and the `GC_DB` D1 database the DO forwards orphans into.
+ *
+ * Fails loudly when the required `BLOBS` / `GC_DB` bindings are missing.
+ */
+export function createSolidPodGc(config: SolidPodConfig): SolidPodGcHandler {
+  const resolved = resolveConfig(config);
+
+  return async (_event, env, _ctx) => {
+    if (!env.BLOBS) {
+      throw new Error("@dwk/solid-pod: GC requires the `BLOBS` R2 binding");
+    }
+    if (!env.GC_DB) {
+      throw new Error("@dwk/solid-pod: GC requires the `GC_DB` D1 binding");
+    }
+    await ensureGcSchema(env.GC_DB);
+    await collectGarbage(env, { safetyWindowMs: resolved.gcSafetyWindowMs });
+  };
+}

package/src/handler.ts

@@ -0,0 +1,199 @@
+/**
+ * The stateless Solid Pod front door.
+ *
+ * It authenticates DPoP-bound bearer tokens at the edge (`auth.ts`), then hands
+ * the request — augmented with the verified agent facts via internal headers —
+ * to the per-pod Durable Object, which owns all consistency, authorization, and
+ * notification logic. v1 runs a single Durable Object per `baseUrl` (no
+ * sharding). The handler is mountable under any path prefix because it routes
+ * purely on the request URL.
+ */
+
+import { hostFromUrl, type LogFields } from "@dwk/log";
+
+import {
+  INTERNAL_HEADERS,
+  resolveConfig,
+  type ResolvedConfig,
+  type SolidPodConfig,
+  type SolidPodEnv,
+} from "./config";
+import { authenticate } from "./auth";
+import { PodOutcome, SolidPodLogEvent } from "./log";
+
+/** A `fetch`-compatible Worker handler. */
+export type SolidPodHandler = (
+  request: Request,
+  env: SolidPodEnv,
+  ctx: ExecutionContext,
+) => Promise<Response>;
+
+/** Client headers that are safe to forward verbatim to the Durable Object. */
+const FORWARDED_HEADERS = [
+  "accept",
+  "content-type",
+  "content-length",
+  "if-match",
+  "if-none-match",
+  "slug",
+  "link",
+  "origin",
+  "upgrade",
+  "sec-websocket-key",
+  "sec-websocket-version",
+  "sec-websocket-protocol",
+  "sec-websocket-extensions",
+] as const;
+
+/** Fail loudly if a required Cloudflare binding is missing (no silent degradation). */
+function assertBindings(env: SolidPodEnv): void {
+  if (!env.POD) {
+    throw new Error(
+      "@dwk/solid-pod: missing required Durable Object binding `POD`",
+    );
+  }
+  if (!env.BLOBS) {
+    throw new Error("@dwk/solid-pod: missing required R2 binding `BLOBS`");
+  }
+}
+
+/** Build the internal DO request, stripping any client-supplied auth headers. */
+function internalRequest(
+  request: Request,
+  config: ResolvedConfig,
+  auth: { webid: string; jti: string; jkt: string } | null,
+): Request {
+  const headers = new Headers();
+  for (const name of FORWARDED_HEADERS) {
+    const value = request.headers.get(name);
+    if (value !== null) headers.set(name, value);
+  }
+  // The DO trusts these headers, so they are always set by us — never passed
+  // through from the client.
+  if (auth) {
+    headers.set(INTERNAL_HEADERS.webid, auth.webid);
+    headers.set(INTERNAL_HEADERS.jti, auth.jti);
+    headers.set(INTERNAL_HEADERS.jkt, auth.jkt);
+  }
+  headers.set(
+    INTERNAL_HEADERS.config,
+    JSON.stringify({
+      owners: config.owners,
+      allowAnonymousWrites: config.allowAnonymousWrites,
+      ...(config.maxInlineBytes !== undefined
+        ? { maxInlineBytes: config.maxInlineBytes }
+        : {}),
+    }),
+  );
+
+  const method = request.method.toUpperCase();
+  const hasBody = method !== "GET" && method !== "HEAD";
+  return new Request(request.url, {
+    method: request.method,
+    headers,
+    ...(hasBody ? { body: request.body } : {}),
+  });
+}
+
+/** A `401` with the DPoP challenge and a machine-readable failure reason. */
+function unauthorized(reason: string): Response {
+  return new Response("Unauthorized", {
+    status: 401,
+    headers: {
+      "content-type": "text/plain; charset=utf-8",
+      "www-authenticate": `DPoP realm="solid", error="invalid_token", error_description="${reason}"`,
+    },
+  });
+}
+
+/**
+ * Emit a structured event on both the logger and the metrics seam, which share
+ * one event vocabulary (see `@dwk/log`): `warn` for handled-but-notable
+ * rejections, `info` for normal outcomes. Honors the redaction policy — callers
+ * pass only reason codes, HTTP method/status, and sanitized hosts.
+ */
+function emit(
+  config: ResolvedConfig,
+  level: "info" | "warn",
+  event: string,
+  fields?: LogFields,
+): void {
+  config.logger[level](event, fields);
+  config.metrics.count(event, fields);
+}
+
+/**
+ * Translate the Durable Object's internal authorization-outcome header into the
+ * matching {@link SolidPodLogEvent} on the injected seams, then strip the header
+ * before the response reaches the client. The DO cannot hold the injected
+ * logger/metrics (they do not cross the isolate boundary), so it signals its WAC
+ * denial / anonymous-write refusal / replay rejection here, at the composition
+ * boundary, where the seams are wired. Responses without the header (including
+ * WebSocket upgrades) pass through untouched.
+ */
+function logPodOutcome(
+  config: ResolvedConfig,
+  request: Request,
+  response: Response,
+): Response {
+  const outcome = response.headers.get(INTERNAL_HEADERS.outcome);
+  if (!outcome) return response;
+
+  const method = request.method;
+  switch (outcome) {
+    case PodOutcome.WacDenied:
+      emit(config, "warn", SolidPodLogEvent.AccessDenied, {
+        method,
+        status: response.status,
+      });
+      break;
+    case PodOutcome.AnonymousWriteRefused:
+      emit(config, "warn", SolidPodLogEvent.AnonymousWriteRefused, { method });
+      break;
+    case PodOutcome.Replay:
+      emit(config, "warn", SolidPodLogEvent.ReplayRejected, { method });
+      break;
+  }
+
+  const headers = new Headers(response.headers);
+  headers.delete(INTERNAL_HEADERS.outcome);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+/**
+ * Create the stateless Solid Pod front-door handler. Writes funnel through the
+ * per-pod {@link SolidPodObject}; reads and notifications likewise route through
+ * it so the DO remains the single consistency authority.
+ */
+export function createSolidPod(config: SolidPodConfig): SolidPodHandler {
+  const resolved = resolveConfig(config);
+
+  return async (request, env, _ctx) => {
+    assertBindings(env);
+
+    const result = await authenticate(request, resolved);
+    if (result.kind === "rejected") {
+      emit(resolved, "warn", SolidPodLogEvent.AuthRejected, {
+        reason: result.reason,
+      });
+      return unauthorized(result.reason);
+    }
+
+    const auth = result.kind === "authenticated" ? result.context : null;
+    if (auth) {
+      emit(resolved, "info", SolidPodLogEvent.AuthAccepted, {
+        agentHost: hostFromUrl(auth.webid),
+      });
+    }
+    const forwarded = internalRequest(request, resolved, auth);
+
+    // One Durable Object per pod, keyed by the identity root (no sharding).
+    const id = env.POD.idFromName(resolved.baseUrl);
+    const response = await env.POD.get(id).fetch(forwarded);
+    return logPodOutcome(resolved, request, response);
+  };
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * `@dwk/solid-pod` — edge-native Solid Pod.
+ *
+ * A stateless Worker front door over a per-pod Durable Object that is the
+ * consistency, authz, and notification authority, with R2 for blob bodies. This
+ * is the only `@dwk` package that ships a Durable Object.
+ *
+ * The package is **not** protocol-agnostic: it is the Solid Protocol endpoint,
+ * composing the reusable libs `@dwk/dpop` (edge DPoP validation), `@dwk/rdf`
+ * (Turtle/JSON-LD content negotiation), `@dwk/wac` (access control), and
+ * `@dwk/store` (DO-SQLite quads + R2 copy-on-write blobs). v1 is a **Resource
+ * Server only** (no OIDC OP) and runs **one Durable Object per pod** (no
+ * sharding).
+ *
+ * @see spec/packages/solid-pod.md
+ * @packageDocumentation
+ */
+
+export { createSolidPod, type SolidPodHandler } from "./handler";
+export { createSolidPodGc, type SolidPodGcHandler } from "./gc";
+export { SolidPodObject } from "./pod";
+
+export {
+  type SolidPodConfig,
+  type SolidPodEnv,
+  type SolidPodGcEnv,
+  type AuthContext,
+  type Jwks,
+} from "./config";
+
+export { SolidPodLogEvent } from "./log";
+export type { Logger, Metrics } from "@dwk/log";