@dwk/remotestorage 0.1.0-beta.0

package/src/config.ts

@@ -0,0 +1,197 @@
+/**
+ * Configuration, the declared Cloudflare `Env` fragment, and config resolution
+ * for `@dwk/remotestorage`.
+ *
+ * Per the composition contract the package never reads the global environment
+ * directly: all tunables (base URL, token issuer/JWKS, accepted audience,
+ * offload threshold, GC window, path mapping) are passed into
+ * {@link createRemoteStorage} / {@link createRemoteStorageGc}, so a vault can be
+ * instantiated multiple times and unit-tested in isolation. The Cloudflare
+ * bindings — the per-account 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 { RemoteStorageAuth } from "./auth";
+import type { RemoteStorageObject } from "./storage";
+
+/** Cloudflare bindings required by the handler and the per-account Durable Object. */
+export interface RemoteStorageEnv {
+  /** Durable Object namespace for the per-account class ({@link RemoteStorageObject}). */
+  readonly STORAGE: DurableObjectNamespace<RemoteStorageObject>;
+  /** R2 bucket holding document bodies (MAY be shared with `@dwk/solid-pod`). */
+  readonly BLOBS: R2Bucket;
+  /**
+   * Shared D1 database tracking orphaned blob keys for the out-of-band GC cron.
+   * Optional: when bound, the DO forwards its transactional orphan outbox here
+   * after writes so {@link createRemoteStorageGc} 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 RemoteStorageGcEnv {
+  /** R2 bucket holding document bodies. */
+  readonly BLOBS: R2Bucket;
+  /** Shared D1 database tracking orphaned blob keys (see `@dwk/store`). */
+  readonly GC_DB: D1Database;
+}
+
+/** The account and account-relative storage path parsed from a request URL. */
+export interface ParsedPath {
+  /** Stable account identifier; keys the per-account Durable Object. */
+  readonly account: string;
+  /** Account-relative storage path, percent-encoded, always starting with `/`. */
+  readonly path: string;
+}
+
+/** Configuration passed to {@link createRemoteStorage}. */
+export interface RemoteStorageConfig {
+  /**
+   * The storage server's base URL, e.g. `https://storage.example`. Used for
+   * discovery metadata and as a default token audience. No trailing slash.
+   */
+  readonly baseUrl: string;
+
+  /**
+   * Accepted access-token issuer (`iss`). When set, a token whose `iss` differs
+   * is rejected. Ignored when a custom {@link authenticate} hook is supplied.
+   */
+  readonly issuer?: string;
+
+  /**
+   * Accepted token audience(s) (`aud`). When set, a token is accepted only when
+   * its `aud` intersects this set; when unset the audience check is skipped
+   * (plain OAuth bearer tokens often omit `aud`).
+   */
+  readonly audience?: string | readonly string[];
+
+  /** Static JWK verification keys for the issuer (hermetic alternative to {@link jwksUri}). */
+  readonly jwks?: readonly JsonWebKey[];
+
+  /** 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 cell. Defaults to the ~2 MB DO-cell ceiling in `@dwk/store`.
+   */
+  readonly maxInlineBytes?: number;
+
+  /**
+   * GC safety window (ms) advertised to the cron handler; an orphaned R2 object
+   * is reclaimed only 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 bearer-token verification entirely. When provided, the handler
+   * calls this instead of the built-in JWKS verifier — useful for tests and for
+   * token formats the default verifier does not cover (e.g. opaque tokens
+   * resolved via RFC 7662 introspection). Returning `null` means "no/invalid
+   * credentials"; the request then proceeds unauthenticated (only `/public/`
+   * document reads succeed).
+   */
+  readonly authenticate?: (
+    request: Request,
+  ) => Promise<RemoteStorageAuth | null> | RemoteStorageAuth | null;
+
+  /**
+   * Map a request `pathname` to an {@link ParsedPath}. Defaults to treating the
+   * first path segment as the account and the remainder (with leading slash) as
+   * the account-relative storage path: `/alice/documents/x` → account `alice`,
+   * path `/documents/x`; `/alice` or `/alice/` → account `alice`, path `/`.
+   * Return `null` to 404 a request that names no account.
+   */
+  readonly parsePath?: (pathname: string) => ParsedPath | null;
+
+  /** Logger for auth/authz events; defaults to a no-op (see `@dwk/log`). */
+  readonly logger?: Logger;
+  /** Metrics sink for the same events; defaults to a no-op. */
+  readonly metrics?: Metrics;
+}
+
+/** Fully-resolved configuration with defaults applied. */
+export interface ResolvedConfig {
+  readonly baseUrl: string;
+  readonly issuer?: string;
+  readonly audience: readonly string[];
+  readonly jwks?: readonly JsonWebKey[];
+  readonly jwksUri?: string;
+  readonly maxInlineBytes?: number;
+  readonly gcSafetyWindowMs: number;
+  readonly now: () => number;
+  readonly fetch: typeof fetch;
+  readonly authenticate?: RemoteStorageConfig["authenticate"];
+  readonly parsePath: (pathname: string) => ParsedPath | null;
+  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 header the trusted front door uses to hand config to the DO. */
+export const INTERNAL_HEADERS = {
+  /** JSON-encoded subset of config the DO needs (offload threshold). */
+  config: "x-remotestorage-config",
+} as const;
+
+/** Strip the trailing slash from a base URL so joins are unambiguous. */
+function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+
+/**
+ * Default {@link RemoteStorageConfig.parsePath}: first segment is the account,
+ * the rest (with leading slash) is the storage path. Returns `null` when the
+ * path names no account (e.g. `/`).
+ */
+export function defaultParsePath(pathname: string): ParsedPath | null {
+  const match = /^\/([^/]+)(\/.*)?$/.exec(pathname);
+  if (!match) return null;
+  const account = decodeURIComponent(match[1] as string);
+  // Keep the storage path percent-encoded: decoding `%2F` would conflate it
+  // with a real separator and corrupt store keys.
+  const path = match[2] ?? "/";
+  return { account, path };
+}
+
+/** Apply defaults and derived values to raw {@link RemoteStorageConfig}. */
+export function resolveConfig(config: RemoteStorageConfig): ResolvedConfig {
+  if (!config.baseUrl) {
+    throw new Error("@dwk/remotestorage: `baseUrl` is required");
+  }
+  const baseUrl = normalizeBaseUrl(config.baseUrl);
+  const audience =
+    config.audience === undefined
+      ? []
+      : typeof config.audience === "string"
+        ? [config.audience]
+        : [...config.audience];
+
+  return {
+    baseUrl,
+    issuer: config.issuer,
+    audience,
+    jwks: config.jwks,
+    jwksUri: config.jwksUri,
+    maxInlineBytes: config.maxInlineBytes,
+    gcSafetyWindowMs: config.gcSafetyWindowMs ?? DEFAULT_GC_SAFETY_WINDOW_MS,
+    now: config.now ?? (() => Date.now()),
+    fetch: config.fetch ?? fetch,
+    authenticate: config.authenticate,
+    parsePath: config.parsePath ?? defaultParsePath,
+    logger: config.logger ?? noopLogger,
+    metrics: config.metrics ?? noopMetrics,
+  };
+}

package/src/cors.ts

@@ -0,0 +1,68 @@
+/**
+ * Permissive CORS for browser apps on other origins (draft §6). remoteStorage
+ * is built for "no-backend" web apps that run on an origin different from the
+ * storage server, so every response — including errors and the preflight — must
+ * carry CORS headers or the browser hides the result from the app.
+ *
+ * Pure and runtime-free: it maps a request `Origin` to the header set. Bearer
+ * tokens travel in the `Authorization` header (not cookies), so credentialed
+ * CORS is unnecessary and `*` is a safe default; when a concrete `Origin` is
+ * present it is echoed (with `Vary: Origin`) so caches stay correct.
+ */
+
+/** Methods the storage API exposes, advertised on the preflight. */
+export const ALLOWED_METHODS = "GET, HEAD, PUT, DELETE, OPTIONS";
+
+/** Request headers a browser app may send (preflight `Access-Control-Allow-Headers`). */
+const ALLOWED_HEADERS =
+  "Authorization, Content-Type, Content-Length, If-Match, If-None-Match, Origin, X-Requested-With";
+
+/** Response headers a browser app may read (`Access-Control-Expose-Headers`). */
+const EXPOSED_HEADERS = "ETag, Content-Type, Content-Length, Location";
+
+/** How long (seconds) a browser may cache the preflight result. */
+const MAX_AGE = "86400";
+
+/** Build the CORS header set for a request with the given `Origin` (may be null). */
+export function corsHeaders(
+  requestOrigin: string | null,
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    "access-control-allow-origin": requestOrigin ?? "*",
+    "access-control-expose-headers": EXPOSED_HEADERS,
+    vary: "Origin",
+  };
+  return headers;
+}
+
+/** The preflight (`OPTIONS`) response, answered at the edge without a store hit. */
+export function preflightResponse(requestOrigin: string | null): Response {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      ...corsHeaders(requestOrigin),
+      "access-control-allow-methods": ALLOWED_METHODS,
+      "access-control-allow-headers": ALLOWED_HEADERS,
+      "access-control-max-age": MAX_AGE,
+    },
+  });
+}
+
+/**
+ * Return `response` with the CORS headers merged in. The body and status are
+ * preserved; existing headers win only for names CORS does not own.
+ */
+export function withCors(
+  response: Response,
+  requestOrigin: string | null,
+): Response {
+  const headers = new Headers(response.headers);
+  for (const [name, value] of Object.entries(corsHeaders(requestOrigin))) {
+    headers.set(name, value);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}

package/src/discovery.ts

@@ -0,0 +1,48 @@
+/**
+ * remoteStorage discovery (draft §10): the WebFinger link advertising a user's
+ * storage root and the OAuth endpoint a connecting app uses.
+ *
+ * A no-backend app is given only a user address (`user@host`); it discovers the
+ * storage root by querying WebFinger for that account and reading the
+ * remoteStorage link. This module builds that link as a plain
+ * [`@dwk/webfinger`](../webfinger) `Link` so a deployment can drop it into its
+ * existing WebFinger resource record rather than standing up a second endpoint.
+ * Pure data — no Workers runtime.
+ */
+
+import type { Link } from "@dwk/webfinger";
+
+/** The remoteStorage WebFinger link relation (draft §10). */
+export const REMOTESTORAGE_REL =
+  "http://tools.ietf.org/id/draft-dejong-remotestorage";
+
+/** The remoteStorage draft version advertised in the link properties. */
+export const REMOTESTORAGE_VERSION = "draft-dejong-remotestorage-22";
+
+/** Inputs for {@link remoteStorageLink}. */
+export interface RemoteStorageLinkConfig {
+  /** The user's storage root URL (the `href` apps GET/PUT/DELETE under). */
+  readonly storageRoot: string;
+  /** The OAuth authorization endpoint (RFC 6749 §4.2 implicit grant). */
+  readonly authEndpoint: string;
+}
+
+/**
+ * Build the WebFinger remoteStorage `Link` for one account. The `properties`
+ * carry the spec version, the OAuth authorization URL, and the capability flags
+ * remoteStorage clients read (`Bearer` auth, `Content-Range` support); a `null`
+ * property value means "advertised as absent", per RFC 7033.
+ */
+export function remoteStorageLink(config: RemoteStorageLinkConfig): Link {
+  return {
+    rel: REMOTESTORAGE_REL,
+    href: config.storageRoot,
+    properties: {
+      "http://remotestorage.io/spec/version": REMOTESTORAGE_VERSION,
+      "http://tools.ietf.org/html/rfc6749#section-4.2": config.authEndpoint,
+      "http://tools.ietf.org/html/rfc6750#section-2.3": "false",
+      "http://tools.ietf.org/html/rfc7233": "GET",
+      "http://remotestorage.io/spec/web-authoring": null,
+    },
+  };
+}

package/src/encoding.ts

@@ -0,0 +1,22 @@
+/**
+ * base64url + UTF-8 helpers for the OAuth bearer-token decode path.
+ *
+ * Dependency-free and runtime-agnostic (`atob` / `btoa` / Web `TextDecoder`
+ * only) so the surrounding modules unit-test without a Workers runtime.
+ */
+
+/** 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,50 @@
+/**
+ * The R2 garbage-collection cron handler.
+ *
+ * Each account'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 (identical in shape to
+ * `@dwk/solid-pod`'s GC, and able to share one `BLOBS`/`GC_DB` pair with it).
+ */
+
+import { collectGarbage, ensureGcSchema } from "@dwk/store";
+
+import {
+  resolveConfig,
+  type RemoteStorageConfig,
+  type RemoteStorageGcEnv,
+} from "./config";
+
+/** A `scheduled`-compatible cron handler for R2 blob garbage collection. */
+export type RemoteStorageGcHandler = (
+  event: ScheduledController,
+  env: RemoteStorageGcEnv,
+  ctx: ExecutionContext,
+) => Promise<void>;
+
+/**
+ * Create the cron handler that reclaims orphaned R2 blobs. Bind it to a
+ * `scheduled` trigger alongside the storage 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 createRemoteStorageGc(
+  config: RemoteStorageConfig,
+): RemoteStorageGcHandler {
+  const resolved = resolveConfig(config);
+
+  return async (_event, env, _ctx) => {
+    if (!env.BLOBS) {
+      throw new Error("@dwk/remotestorage: GC requires the `BLOBS` R2 binding");
+    }
+    if (!env.GC_DB) {
+      throw new Error("@dwk/remotestorage: 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,225 @@
+/**
+ * The stateless remoteStorage front door.
+ *
+ * It answers CORS preflights at the edge, authenticates the OAuth bearer token
+ * (`auth.ts`), and enforces the per-module read/write **scope** model
+ * (`scope.ts`) — including the public-`/public/`-document exception — before
+ * forwarding an already-authorized request to the per-account Durable Object,
+ * which owns all storage consistency. One Durable Object per account (keyed by
+ * the parsed account id); the handler is mountable under any path prefix because
+ * it routes purely on the request URL via {@link RemoteStorageConfig.parsePath}.
+ */
+
+import { hostFromUrl, type LogFields } from "@dwk/log";
+
+import { authenticate, type AuthResult } from "./auth";
+import {
+  INTERNAL_HEADERS,
+  resolveConfig,
+  type RemoteStorageConfig,
+  type RemoteStorageEnv,
+  type ResolvedConfig,
+} from "./config";
+import { ALLOWED_METHODS, preflightResponse, withCors } from "./cors";
+import { RemoteStorageLogEvent } from "./log";
+import { authorizeScopes, isPublicDocument } from "./scope";
+
+/** A `fetch`-compatible Worker handler. */
+export type RemoteStorageHandler = (
+  request: Request,
+  env: RemoteStorageEnv,
+  ctx: ExecutionContext,
+) => Promise<Response>;
+
+/** Client headers safe to forward verbatim to the Durable Object. */
+const FORWARDED_HEADERS = [
+  "content-type",
+  "content-length",
+  "if-match",
+  "if-none-match",
+] as const;
+
+/** Methods the storage API serves; anything else is `405`. */
+const METHODS = new Set(["GET", "HEAD", "PUT", "DELETE"]);
+
+/** Fail loudly if a required Cloudflare binding is missing (no silent degradation). */
+function assertBindings(env: RemoteStorageEnv): void {
+  if (!env.STORAGE) {
+    throw new Error(
+      "@dwk/remotestorage: missing required Durable Object binding `STORAGE`",
+    );
+  }
+  if (!env.BLOBS) {
+    throw new Error("@dwk/remotestorage: missing required R2 binding `BLOBS`");
+  }
+}
+
+/** Build the internal DO request: clean account-relative URL + config header. */
+function internalRequest(
+  request: Request,
+  storagePath: string,
+  config: ResolvedConfig,
+): Request {
+  const headers = new Headers();
+  for (const name of FORWARDED_HEADERS) {
+    const value = request.headers.get(name);
+    if (value !== null) headers.set(name, value);
+  }
+  headers.set(
+    INTERNAL_HEADERS.config,
+    JSON.stringify(
+      config.maxInlineBytes !== undefined
+        ? { maxInlineBytes: config.maxInlineBytes }
+        : {},
+    ),
+  );
+
+  const url = new URL(request.url);
+  url.pathname = storagePath;
+  url.search = "";
+
+  const method = request.method.toUpperCase();
+  const hasBody = method !== "GET" && method !== "HEAD";
+  return new Request(url.toString(), {
+    method: request.method,
+    headers,
+    ...(hasBody ? { body: request.body } : {}),
+  });
+}
+
+/** Emit a structured event on both the logger and the metrics seam. */
+function emit(
+  config: ResolvedConfig,
+  level: "info" | "warn",
+  event: string,
+  fields?: LogFields,
+): void {
+  config.logger[level](event, fields);
+  config.metrics.count(event, fields);
+}
+
+/** A `401` with the Bearer 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": `Bearer realm="remotestorage", error="invalid_token", error_description="${reason}"`,
+    },
+  });
+}
+
+/** A `403` for an authenticated request whose scopes do not cover the target. */
+function forbidden(): Response {
+  return new Response("Forbidden", {
+    status: 403,
+    headers: { "content-type": "text/plain; charset=utf-8" },
+  });
+}
+
+/**
+ * Decide whether a request is authorized, given the auth result, the storage
+ * path, and whether the method writes. Returns `null` to allow, or the Response
+ * to return. The `/public/` document read is allowed even unauthenticated; every
+ * other access needs a scope covering the path's module (or `*`).
+ */
+function authorize(
+  config: ResolvedConfig,
+  result: AuthResult,
+  path: string,
+  needWrite: boolean,
+  method: string,
+): Response | null {
+  const publicRead = !needWrite && isPublicDocument(path);
+
+  if (result.kind === "anonymous") {
+    if (publicRead) return null;
+    emit(config, "warn", RemoteStorageLogEvent.AccessDenied, {
+      method,
+      status: 401,
+    });
+    return unauthorized("missing_token");
+  }
+
+  // Authenticated: a public-document read always succeeds; otherwise the token
+  // must carry a scope for the path's module at the required mode. (A `rejected`
+  // result never reaches here — the caller returns before authorizing.)
+  if (result.kind === "rejected") return unauthorized(result.reason);
+  if (publicRead || authorizeScopes(result.auth.scopes, path, needWrite)) {
+    return null;
+  }
+  emit(config, "warn", RemoteStorageLogEvent.AccessDenied, {
+    method,
+    status: 403,
+  });
+  return forbidden();
+}
+
+/**
+ * Create the stateless remoteStorage front-door handler. CORS and auth are
+ * enforced here; storage flows through the per-account
+ * {@link RemoteStorageObject} so it remains the single consistency authority.
+ */
+export function createRemoteStorage(
+  config: RemoteStorageConfig,
+): RemoteStorageHandler {
+  const resolved = resolveConfig(config);
+
+  return async (request, env, _ctx) => {
+    assertBindings(env);
+    const requestOrigin = request.headers.get("origin");
+    const method = request.method.toUpperCase();
+
+    // Preflight is answered at the edge — no auth, no store hit.
+    if (method === "OPTIONS") return preflightResponse(requestOrigin);
+
+    const respond = (response: Response): Response =>
+      withCors(response, requestOrigin);
+
+    if (!METHODS.has(method)) {
+      return respond(
+        new Response("Method Not Allowed", {
+          status: 405,
+          headers: {
+            "content-type": "text/plain; charset=utf-8",
+            allow: ALLOWED_METHODS,
+          },
+        }),
+      );
+    }
+
+    const parsed = resolved.parsePath(new URL(request.url).pathname);
+    if (!parsed) {
+      return respond(
+        new Response("Not Found", {
+          status: 404,
+          headers: { "content-type": "text/plain; charset=utf-8" },
+        }),
+      );
+    }
+
+    const result = await authenticate(request, resolved);
+    if (result.kind === "rejected") {
+      emit(resolved, "warn", RemoteStorageLogEvent.AuthRejected, {
+        reason: result.reason,
+      });
+      return respond(unauthorized(result.reason));
+    }
+    if (result.kind === "authenticated") {
+      emit(resolved, "info", RemoteStorageLogEvent.AuthAccepted, {
+        ...(result.auth.subject
+          ? { subjectHost: hostFromUrl(result.auth.subject) }
+          : {}),
+      });
+    }
+
+    const needWrite = method === "PUT" || method === "DELETE";
+    const denied = authorize(resolved, result, parsed.path, needWrite, method);
+    if (denied) return respond(denied);
+
+    const forwarded = internalRequest(request, parsed.path, resolved);
+    const id = env.STORAGE.idFromName(parsed.account);
+    const response = await env.STORAGE.get(id).fetch(forwarded);
+    return respond(response);
+  };
+}