@dwk/remotestorage 0.1.0-beta.0

package/dist/storage.js

@@ -0,0 +1,313 @@
+/**
+ * The per-account Durable Object: the single-threaded consistency authority for
+ * one remoteStorage vault.
+ *
+ * The stateless front door (`handler.ts`) authenticates the bearer token and
+ * enforces per-module scopes at the edge, then forwards already-authorized
+ * requests here, where Cloudflare guarantees one thread per account. Everything
+ * that must be strongly consistent — document GET/PUT/DELETE, conditional
+ * (`If-Match`/`If-None-Match`) writes, document↔folder conflict detection, the
+ * virtual folder listing and its aggregate ETag, and R2 copy-on-write through
+ * `@dwk/store` — happens here. This object reuses `@dwk/store` exactly as
+ * `@dwk/solid-pod` does (same library, same storage primitives); the only Solid
+ * facility it leans on beyond the blob tier is the generic `list(prefix)`
+ * projection. Consumers bind this class as a Durable Object namespace.
+ */
+import { DurableObject } from "cloudflare:workers";
+import { createStore, d1OrphanSink, forwardOrphans, PreconditionFailedError, } from "@dwk/store";
+import { INTERNAL_HEADERS } from "./config";
+import { buildFolderModel, FOLDER_DESCRIPTION_TYPE, hashSignature, renderFolderDescription, } from "./folder";
+import { isFolderPath } from "./scope";
+function text(status, body, headers = {}) {
+    return new Response(body, {
+        status,
+        headers: { "content-type": "text/plain; charset=utf-8", ...headers },
+    });
+}
+export class RemoteStorageObject extends DurableObject {
+    #store = null;
+    /** Lazily build the store with the front-door's offload threshold. */
+    #getStore(config) {
+        if (this.#store === null) {
+            this.#store = createStore(this.ctx, this.env, {
+                ...(config.maxInlineBytes !== undefined
+                    ? { maxInlineBytes: config.maxInlineBytes }
+                    : {}),
+            });
+        }
+        return this.#store;
+    }
+    async fetch(request) {
+        const config = (() => {
+            const raw = request.headers.get(INTERNAL_HEADERS.config);
+            if (!raw)
+                return {};
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return {};
+            }
+        })();
+        const store = this.#getStore(config);
+        const url = new URL(request.url);
+        // Keep the path percent-encoded: decoding `%2F` would conflate it with a
+        // real separator and corrupt store keys.
+        const path = url.pathname;
+        const method = request.method.toUpperCase();
+        try {
+            switch (method) {
+                case "HEAD":
+                case "GET":
+                    return isFolderPath(path)
+                        ? await this.#readFolder(store, path, request, method === "HEAD")
+                        : await this.#readDocument(store, path, request, method === "HEAD");
+                case "PUT":
+                    return await this.#putDocument(store, path, request);
+                case "DELETE":
+                    return await this.#deleteDocument(store, path, request);
+                default:
+                    return text(405, "Method Not Allowed", { allow: ALLOW });
+            }
+        }
+        catch (error) {
+            if (error instanceof PreconditionFailedError) {
+                return text(412, "Precondition Failed");
+            }
+            if (error instanceof LengthRequiredError) {
+                return text(411, "Length Required");
+            }
+            throw error;
+        }
+    }
+    // -- document read ---------------------------------------------------------
+    async #readDocument(store, path, request, headOnly) {
+        const meta = store.head(path);
+        if (!meta)
+            return text(404, "Not Found");
+        const ifNoneMatch = request.headers.get("if-none-match");
+        if (ifNoneMatch && ifNoneMatchSatisfied(ifNoneMatch, meta.etag)) {
+            return new Response(null, {
+                status: 304,
+                headers: { etag: meta.etag, "cache-control": "no-cache" },
+            });
+        }
+        const blob = await store.readBlob(path);
+        // A non-blob pointer at a document path should not arise (writes always go
+        // through the blob tier), but guard rather than stream a null body.
+        if (!blob)
+            return text(404, "Not Found");
+        const headers = documentHeaders(meta.etag, blob.contentType);
+        headers.set("content-length", String(blob.size));
+        if (headOnly) {
+            await blob.stream.cancel();
+            return new Response(null, { status: 200, headers });
+        }
+        return new Response(blob.stream, { status: 200, headers });
+    }
+    // -- folder read -----------------------------------------------------------
+    async #readFolder(store, path, request, headOnly) {
+        // A folder is virtual: its listing and ETag derive from descendants. An
+        // empty/absent folder still answers 200 with a stable ETag (over the empty
+        // signature), matching remoteStorage's "folders always exist" model.
+        const model = buildFolderModel(path, store.list(path));
+        const etag = await hashSignature(model.signature);
+        const ifNoneMatch = request.headers.get("if-none-match");
+        if (ifNoneMatch && ifNoneMatchSatisfied(ifNoneMatch, etag)) {
+            return new Response(null, {
+                status: 304,
+                headers: { etag, "cache-control": "no-cache" },
+            });
+        }
+        const headers = new Headers({
+            etag,
+            "content-type": FOLDER_DESCRIPTION_TYPE,
+            "cache-control": "no-cache",
+            allow: ALLOW,
+        });
+        if (headOnly)
+            return new Response(null, { status: 200, headers });
+        const body = JSON.stringify(await renderFolderDescription(model));
+        headers.set("content-length", String(new TextEncoder().encode(body).length));
+        return new Response(body, { status: 200, headers });
+    }
+    // -- document write --------------------------------------------------------
+    async #putDocument(store, path, request) {
+        if (isFolderPath(path)) {
+            // A folder path (trailing slash) is not a document; remoteStorage has no
+            // verb to create a folder directly (draft §6).
+            return text(400, "Cannot PUT a folder", { allow: ALLOW });
+        }
+        // Document↔folder name collisions are forbidden (draft §6): a path that
+        // already has descendants is a folder, and any ancestor that is a document
+        // would shadow this one.
+        const conflict = this.#conflict(store, path);
+        if (conflict)
+            return text(409, conflict, { allow: ALLOW });
+        const existed = store.head(path) !== null;
+        await this.#writeBody(store, path, request, {
+            ifMatch: ifMatchOf(request),
+            ifNoneMatch: ifNoneMatchOf(request),
+        });
+        await this.#drainOrphans(store);
+        const meta = store.head(path);
+        const headers = new Headers({ allow: ALLOW });
+        if (meta)
+            headers.set("etag", meta.etag);
+        return new Response(null, { status: existed ? 200 : 201, headers });
+    }
+    // -- document delete -------------------------------------------------------
+    async #deleteDocument(store, path, request) {
+        if (isFolderPath(path)) {
+            return text(400, "Cannot DELETE a folder", { allow: ALLOW });
+        }
+        const meta = store.head(path);
+        if (!meta)
+            return text(404, "Not Found");
+        const oldEtag = meta.etag;
+        store.delete(path, { ifMatch: ifMatchOf(request) });
+        await this.#drainOrphans(store);
+        // The emptied parent folders simply vanish — they are virtual. The deleted
+        // document's ETag is returned for clients that track it (draft §6).
+        return new Response(null, {
+            status: 200,
+            headers: { etag: oldEtag, allow: ALLOW },
+        });
+    }
+    // -- helpers ---------------------------------------------------------------
+    /**
+     * Detect a document↔folder name collision for a PUT to `path`. Returns a
+     * human-readable reason, or `null` when the write is unobstructed:
+     *  - `path` already has descendants ⇒ it is a folder, not a document;
+     *  - an ancestor segment is itself a stored document ⇒ it would shadow `path`.
+     */
+    #conflict(store, path) {
+        if (store.list(`${path}/`).length > 0) {
+            return "A folder already exists at this path";
+        }
+        let slash = path.indexOf("/", 1);
+        while (slash !== -1) {
+            const ancestor = path.slice(0, slash);
+            if (ancestor.length > 0 && store.head(ancestor) !== null) {
+                return "A document already exists at an ancestor path";
+            }
+            slash = path.indexOf("/", slash + 1);
+        }
+        return null;
+    }
+    /**
+     * Forward any blob keys the store outboxed (copy-on-write displacements and
+     * deletes) into the shared D1 GC table, so the out-of-band cron can reclaim
+     * them without waking this DO. No-op when `GC_DB` is not bound.
+     */
+    async #drainOrphans(store) {
+        if (!this.env.GC_DB)
+            return;
+        await forwardOrphans(store, d1OrphanSink(this.env.GC_DB));
+    }
+    /**
+     * Write a request body as a document blob without ever buffering an oversized
+     * body in the DO. A body known (by `Content-Length`) to exceed the offload
+     * ceiling is streamed straight to R2; a small or undeclared body is probed up
+     * to the ceiling (trusting nothing) and written from memory, while a probe
+     * that overflows an undeclared length is rejected `411` rather than buffered.
+     */
+    async #writeBody(store, path, request, preconditions) {
+        const contentType = request.headers.get("content-type")?.split(";")[0]?.trim() ||
+            "application/octet-stream";
+        const declared = parseContentLength(request.headers.get("content-length"));
+        if (declared !== null && declared > store.maxInlineBytes) {
+            await store.putBlob(path, request.body ?? new Blob([]), {
+                contentType,
+                ...preconditions,
+            });
+            return;
+        }
+        const peeked = await readUpToLimit(request.body, store.maxInlineBytes);
+        if (peeked.kind === "overflow")
+            throw new LengthRequiredError();
+        await store.putBlob(path, peeked.bytes, { contentType, ...preconditions });
+    }
+}
+// ---------------------------------------------------------------------------
+// Module-level helpers
+// ---------------------------------------------------------------------------
+const ALLOW = "GET, HEAD, PUT, DELETE, OPTIONS";
+/** Headers common to document responses. */
+function documentHeaders(etag, contentType) {
+    return new Headers({
+        etag,
+        "content-type": contentType || "application/octet-stream",
+        "cache-control": "no-cache",
+        allow: ALLOW,
+    });
+}
+/**
+ * Whether a stored `etag` satisfies an `If-None-Match` header (RFC 7232 §3.2).
+ * `*` matches any current representation; otherwise the comma-separated entity
+ * tags are compared with the weak comparison function (the `W/` prefix ignored).
+ */
+function ifNoneMatchSatisfied(header, etag) {
+    if (header.trim() === "*")
+        return true;
+    const opaque = (tag) => tag.trim().replace(/^W\//, "");
+    const target = opaque(etag);
+    return header.split(",").some((tag) => {
+        const candidate = opaque(tag);
+        return candidate.length > 0 && candidate === target;
+    });
+}
+function ifMatchOf(request) {
+    return request.headers.get("if-match") ?? undefined;
+}
+function ifNoneMatchOf(request) {
+    return request.headers.get("if-none-match") ?? undefined;
+}
+/** Concatenate read chunks into one `Uint8Array` of `total` bytes. */
+function concatChunks(chunks, total) {
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+/**
+ * Parse a `Content-Length` header into a non-negative integer, or `null` when
+ * absent or malformed (treated as "length unknown").
+ */
+function parseContentLength(header) {
+    if (header === null || !/^\d+$/.test(header))
+        return null;
+    const value = Number(header);
+    return Number.isSafeInteger(value) ? value : null;
+}
+/**
+ * Read at most `limit` bytes from `body` to classify an undeclared-length body
+ * without buffering an oversized one. Returns the buffered bytes when the body
+ * ends within `limit`; signals `overflow` (cancelling the body) the moment it
+ * exceeds `limit`. A body of exactly `limit` bytes still fits.
+ */
+async function readUpToLimit(body, limit) {
+    if (!body)
+        return { kind: "buffered", bytes: new Uint8Array(0) };
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            return { kind: "buffered", bytes: concatChunks(chunks, total) };
+        chunks.push(value);
+        total += value.byteLength;
+        if (total > limit) {
+            await reader.cancel();
+            return { kind: "overflow" };
+        }
+    }
+}
+/** Thrown by `#writeBody` when an unsized body is too large to buffer or stream (→ 411). */
+class LengthRequiredError extends Error {
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@dwk/remotestorage",
+  "version": "0.1.0-beta.0",
+  "description": "remoteStorage (draft-dejong-remotestorage) personal data vault: OAuth-bearer GET/PUT/DELETE documents and folder listings over @dwk/store. Ships the per-account Durable Object.",
+  "keywords": [
+    "remotestorage",
+    "personal-data",
+    "data-vault",
+    "oauth2",
+    "cloudflare-workers",
+    "durable-objects"
+  ],
+  "type": "module",
+  "license": "ISC",
+  "author": "David W. Keith <me@dwk.io>",
+  "homepage": "https://github.com/davidwkeith/workers/tree/main/packages/remotestorage#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwkeith/workers.git",
+    "directory": "packages/remotestorage"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test-harness.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dwk/log": "0.1.0-beta.0",
+    "@dwk/store": "0.1.0-beta.0",
+    "@dwk/webfinger": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,146 @@
+/**
+ * Edge authentication for the vault: resolve an OAuth 2.0 bearer token into the
+ * scopes it grants, before any request reaches the per-account Durable Object.
+ *
+ * remoteStorage uses **plain bearer tokens** (no DPoP). A request with no
+ * `Authorization` header is `anonymous` — only `/public/` document reads will
+ * then succeed. A request that *presents* a token must verify fully or it is
+ * `rejected`: the built-in verifier checks the issuer JWKS signature and the
+ * `iss` / `aud` / `exp` / `nbf` claims, then reads the OAuth `scope` claim. A
+ * deployer-supplied {@link RemoteStorageConfig.authenticate} hook fully replaces
+ * the built-in path (e.g. to introspect opaque tokens via RFC 7662).
+ */
+
+import type { ResolvedConfig } from "./config";
+import { decodeJwt, verifyJwtSignature } from "./jwt";
+import { parseScopes, type RemoteStorageScope } from "./scope";
+
+/** The verified facts a token yields: its scopes and (optionally) its subject. */
+export interface RemoteStorageAuth {
+  /** The remoteStorage scopes the token grants. */
+  readonly scopes: readonly RemoteStorageScope[];
+  /** The token subject (`sub`), used only for sanitized logging. */
+  readonly subject?: string;
+}
+
+/** A stable reason a token failed verification (for `WWW-Authenticate`). */
+export type AuthFailureReason =
+  | "no_jwks"
+  | "token_malformed"
+  | "signature_invalid"
+  | "issuer_mismatch"
+  | "audience_mismatch"
+  | "token_expired"
+  | "token_not_yet_valid";
+
+/** Outcome of {@link authenticate}: scopes, an explicit failure, or "no creds". */
+export type AuthResult =
+  | { readonly kind: "authenticated"; readonly auth: RemoteStorageAuth }
+  | { readonly kind: "anonymous" }
+  | { readonly kind: "rejected"; readonly reason: AuthFailureReason };
+
+/** In-memory JWKS cache shared across requests within an isolate. */
+interface CachedJwks {
+  keys: readonly JsonWebKey[];
+  fetchedAt: number;
+}
+const JWKS_TTL_MS = 5 * 60 * 1000;
+const jwksCache = new Map<string, CachedJwks>();
+
+/** Resolve the issuer verification keys: static config first, then cached fetch. */
+async function resolveJwks(
+  config: ResolvedConfig,
+): Promise<readonly JsonWebKey[] | null> {
+  if (config.jwks && config.jwks.length > 0) return config.jwks;
+  if (!config.jwksUri) return null;
+
+  const now = config.now();
+  const cached = jwksCache.get(config.jwksUri);
+  if (cached && now - cached.fetchedAt < JWKS_TTL_MS) return cached.keys;
+
+  try {
+    const response = await config.fetch(config.jwksUri);
+    if (!response.ok) return cached?.keys ?? null;
+    const body = (await response.json()) as { keys?: JsonWebKey[] } | null;
+    // Only cache a well-formed JWKS; a null/empty/garbled body (e.g. literal
+    // JSON `null`) is ignored rather than throwing — and caching it would poison
+    // verification for the whole TTL and discard the last good keys.
+    if (!body || !Array.isArray(body.keys)) return cached?.keys ?? null;
+    jwksCache.set(config.jwksUri, { keys: body.keys, fetchedAt: now });
+    return body.keys;
+  } catch {
+    return cached?.keys ?? null;
+  }
+}
+
+/** Extract the `Bearer <token>` value, if present. */
+export function bearerToken(request: Request): string | null {
+  const header = request.headers.get("authorization");
+  if (!header) return null;
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match ? (match[1] as string) : null;
+}
+
+/** Whether the token's `aud` claim intersects the accepted audience set. */
+function audienceMatches(aud: unknown, accepted: readonly string[]): boolean {
+  if (accepted.length === 0) return true; // audience check disabled
+  const values = Array.isArray(aud)
+    ? aud.filter((a): a is string => typeof a === "string")
+    : typeof aud === "string"
+      ? [aud]
+      : [];
+  return values.some((a) => accepted.includes(a));
+}
+
+/**
+ * Authenticate a request at the edge. Returns `anonymous` when no credentials
+ * are presented, `authenticated` with the granted scopes on success, and
+ * `rejected` with a stable reason on any failure of a *presented* token.
+ */
+export async function authenticate(
+  request: Request,
+  config: ResolvedConfig,
+): Promise<AuthResult> {
+  // A deployer-supplied hook fully replaces the built-in verifier.
+  if (config.authenticate) {
+    const auth = await config.authenticate(request);
+    return auth ? { kind: "authenticated", auth } : { kind: "anonymous" };
+  }
+
+  const token = bearerToken(request);
+  if (!token) return { kind: "anonymous" };
+
+  const decoded = decodeJwt(token);
+  if (!decoded) return { kind: "rejected", reason: "token_malformed" };
+
+  const jwks = await resolveJwks(config);
+  if (!jwks || jwks.length === 0)
+    return { kind: "rejected", reason: "no_jwks" };
+
+  if (!(await verifyJwtSignature(decoded, jwks))) {
+    return { kind: "rejected", reason: "signature_invalid" };
+  }
+
+  const { iss, aud, exp, nbf, sub, scope } = decoded.payload;
+  if (config.issuer !== undefined && iss !== config.issuer) {
+    return { kind: "rejected", reason: "issuer_mismatch" };
+  }
+  if (!audienceMatches(aud, config.audience)) {
+    return { kind: "rejected", reason: "audience_mismatch" };
+  }
+  const now = Math.floor(config.now() / 1000);
+  if (typeof exp !== "number" || now >= exp) {
+    return { kind: "rejected", reason: "token_expired" };
+  }
+  if (nbf !== undefined && (typeof nbf !== "number" || now < nbf)) {
+    return { kind: "rejected", reason: "token_not_yet_valid" };
+  }
+
+  return {
+    kind: "authenticated",
+    auth: {
+      scopes: parseScopes(typeof scope === "string" ? scope : undefined),
+      ...(typeof sub === "string" ? { subject: sub } : {}),
+    },
+  };
+}