@dwk/remotestorage 0.1.0-beta.0

package/src/index.ts

@@ -0,0 +1,84 @@
+/**
+ * `@dwk/remotestorage` — an Unhosted-style remoteStorage personal data vault.
+ *
+ * A per-user document vault that "no-backend" web apps read and write over a
+ * plain HTTP `GET`/`PUT`/`DELETE` API, scoped by OAuth 2.0 bearer tokens
+ * (draft-dejong-remotestorage). It is a *competing* personal-data protocol to
+ * Solid — simpler, document-oriented, no RDF — filed for completeness, **not**
+ * as a recommendation alongside `@dwk/solid-pod`.
+ *
+ * Its value here is that it rides on the **same backing store** the Pod uses:
+ * `@dwk/store` is a generic `key → { rdf | blob }` pointer map, so remoteStorage
+ * documents are just its blob tier, and the only library addition this package
+ * required is the generic `list(prefix)` projection (which `@dwk/solid-pod`
+ * could use for LDP container enumeration too). This package ships a thin
+ * per-account Durable Object that reuses `@dwk/store`; the divergent auth model
+ * (plain OAuth bearer + per-module `:r`/`:rw` scopes + a public `/public/` tree,
+ * not DPoP/WAC) and folder semantics live entirely here.
+ *
+ * @see spec/packages/remotestorage.md
+ * @packageDocumentation
+ */
+
+export { createRemoteStorage, type RemoteStorageHandler } from "./handler";
+export { createRemoteStorageGc, type RemoteStorageGcHandler } from "./gc";
+export { RemoteStorageObject } from "./storage";
+
+export {
+  resolveConfig,
+  defaultParsePath,
+  type RemoteStorageConfig,
+  type RemoteStorageEnv,
+  type RemoteStorageGcEnv,
+  type ResolvedConfig,
+  type ParsedPath,
+} from "./config";
+
+export {
+  authenticate,
+  bearerToken,
+  type RemoteStorageAuth,
+  type AuthResult,
+  type AuthFailureReason,
+} from "./auth";
+
+export {
+  parseScopes,
+  authorizeScopes,
+  moduleForPath,
+  isFolderPath,
+  isPublicDocument,
+  ROOT_MODULE,
+  type RemoteStorageScope,
+  type ScopeMode,
+} from "./scope";
+
+export {
+  buildFolderModel,
+  renderFolderDescription,
+  hashSignature,
+  FOLDER_DESCRIPTION_TYPE,
+  FOLDER_DESCRIPTION_CONTEXT,
+  type FolderModel,
+  type FolderDocument,
+  type FolderSubfolder,
+  type FolderDescription,
+  type FolderItem,
+} from "./folder";
+
+export {
+  corsHeaders,
+  preflightResponse,
+  withCors,
+  ALLOWED_METHODS,
+} from "./cors";
+
+export {
+  remoteStorageLink,
+  REMOTESTORAGE_REL,
+  REMOTESTORAGE_VERSION,
+  type RemoteStorageLinkConfig,
+} from "./discovery";
+
+export { RemoteStorageLogEvent } from "./log";
+export type { Logger, Metrics } from "@dwk/log";

package/src/jwt.ts

@@ -0,0 +1,155 @@
+/**
+ * Minimal JWT decode and JWKS-based signature verification for the built-in
+ * bearer-token verifier.
+ *
+ * remoteStorage uses **plain OAuth 2.0 bearer tokens** (no DPoP); a deployment
+ * that issues self-contained JWT access tokens can have this package verify them
+ * directly against the issuer's public JWKS. The module decodes the compact JWS,
+ * selects the key by `kid`/`kty`, and verifies with Web Crypto; claim policy
+ * (issuer/audience/expiry/`scope`) lives in `auth.ts`.
+ *
+ * Only asymmetric algorithms are accepted. `HS*` and `none` are refused: an
+ * access token must be signed by the issuer's private key, never a symmetric
+ * secret a resource server could not safely hold.
+ */
+
+import { base64urlToBytes, base64urlToText } from "./encoding";
+
+/** Asymmetric JOSE algorithms accepted for issuer-signed access tokens. */
+export type JwtAlgorithm = "ES256" | "ES384" | "RS256" | "PS256";
+
+interface AlgSpec {
+  kty: "EC" | "RSA";
+  crv?: string;
+  importParams: { name: string; namedCurve?: string; hash?: string };
+  verifyParams: { name: string; hash?: string; saltLength?: number };
+}
+
+// We avoid the DOM lib's algorithm-parameter type names (not declared by
+// @cloudflare/workers-types); these objects are accepted structurally by
+// crypto.subtle.importKey / verify, mirroring `@dwk/dpop` and `@dwk/solid-pod`.
+const ALGS: Record<JwtAlgorithm, AlgSpec> = {
+  ES256: {
+    kty: "EC",
+    crv: "P-256",
+    importParams: { name: "ECDSA", namedCurve: "P-256" },
+    verifyParams: { name: "ECDSA", hash: "SHA-256" },
+  },
+  ES384: {
+    kty: "EC",
+    crv: "P-384",
+    importParams: { name: "ECDSA", namedCurve: "P-384" },
+    verifyParams: { name: "ECDSA", hash: "SHA-384" },
+  },
+  RS256: {
+    kty: "RSA",
+    importParams: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    verifyParams: { name: "RSASSA-PKCS1-v1_5" },
+  },
+  PS256: {
+    kty: "RSA",
+    importParams: { name: "RSA-PSS", hash: "SHA-256" },
+    verifyParams: { name: "RSA-PSS", saltLength: 32 },
+  },
+};
+
+/** A decoded JWT: its header, claims, and the raw segments for verification. */
+export interface DecodedJwt {
+  readonly header: Record<string, unknown>;
+  readonly payload: Record<string, unknown>;
+  readonly signingInput: string;
+  readonly signature: Uint8Array;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Decode a compact JWS into its header, payload, and signature. Returns `null`
+ * for anything that is not three base64url segments with JSON header/payload.
+ */
+export function decodeJwt(token: string): DecodedJwt | null {
+  if (typeof token !== "string") return null;
+  const segments = token.split(".");
+  if (segments.length !== 3) return null;
+  const [headerSeg, payloadSeg, signatureSeg] = segments as [
+    string,
+    string,
+    string,
+  ];
+  try {
+    const header = JSON.parse(base64urlToText(headerSeg)) as unknown;
+    const payload = JSON.parse(base64urlToText(payloadSeg)) as unknown;
+    if (!isObject(header) || !isObject(payload)) return null;
+    return {
+      header,
+      payload,
+      signingInput: `${headerSeg}.${payloadSeg}`,
+      signature: base64urlToBytes(signatureSeg),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Whether a JWK could verify a signature under the given algorithm. */
+function keyMatchesAlg(jwk: JsonWebKey, spec: AlgSpec): boolean {
+  if (jwk.kty !== spec.kty) return false;
+  if (spec.crv !== undefined && jwk.crv !== spec.crv) return false;
+  return true;
+}
+
+/**
+ * Verify `decoded`'s signature against a JWKS. Selects the verification key by
+ * `kid` when the header carries one, otherwise tries every key compatible with
+ * the header `alg`. Returns `true` on the first key that verifies.
+ */
+export async function verifyJwtSignature(
+  decoded: DecodedJwt,
+  jwks: readonly JsonWebKey[],
+): Promise<boolean> {
+  const alg = decoded.header.alg;
+  const spec = typeof alg === "string" ? ALGS[alg as JwtAlgorithm] : undefined;
+  if (!spec) return false;
+
+  const kid = decoded.header.kid;
+  const compatible = jwks.filter((jwk) => keyMatchesAlg(jwk, spec));
+
+  // When the token names a `kid`, pin verification to the key(s) carrying it; a
+  // `kid` matching no JWKS key is rejected rather than verified against
+  // unrelated keys (which would silently weaken `kid` pinning). Only when the
+  // header omits `kid` do we try every alg-compatible key.
+  let candidates = compatible;
+  if (typeof kid === "string") {
+    candidates = compatible.filter(
+      (jwk) => (jwk as { kid?: unknown }).kid === kid,
+    );
+    if (candidates.length === 0) return false;
+  }
+
+  // The signing input is the same for every candidate key; encode it once.
+  const signingInput = new TextEncoder().encode(decoded.signingInput);
+  for (const jwk of candidates) {
+    try {
+      const key = await crypto.subtle.importKey(
+        "jwk",
+        jwk,
+        spec.importParams,
+        false,
+        ["verify"],
+      );
+      const ok = await crypto.subtle.verify(
+        spec.verifyParams,
+        key,
+        decoded.signature,
+        signingInput,
+      );
+      if (ok) return true;
+    } catch {
+      // A key that fails to import (wrong shape) simply does not match; try the
+      // next candidate rather than aborting the whole verification.
+    }
+  }
+  return false;
+}

package/src/log.ts

@@ -0,0 +1,31 @@
+/**
+ * `@dwk/remotestorage` — structured observability event taxonomy.
+ *
+ * The vault authenticates OAuth bearer tokens and enforces per-module scopes at
+ * the edge; an auth/authz decision that is silently swallowed is an operational
+ * blind spot. Logging and metrics are opt-in via an injected {@link Logger} and
+ * {@link Metrics} (see `@dwk/log`) wired **once at the composition boundary**
+ * (the stateless front door). They **share this one vocabulary**: the same
+ * dotted event name is passed to the logger and the metrics sink so a log line
+ * and its counter line up.
+ *
+ * Fields follow the redaction policy: only machine-readable reason codes, HTTP
+ * method/status, and a sanitized subject host — never tokens, scopes verbatim,
+ * resource paths, or bodies. See `spec/observability.md`.
+ *
+ * @packageDocumentation
+ */
+
+/** Stable event names emitted by `@dwk/remotestorage`. */
+export const RemoteStorageLogEvent = {
+  /** A presented bearer token failed verification. Field: `reason`. */
+  AuthRejected: "remotestorage.auth.rejected",
+  /** A request authenticated successfully at the edge. Field: `subjectHost`. */
+  AuthAccepted: "remotestorage.auth.accepted",
+  /** A request lacked the scope (or auth) for the target. Fields: `method`, `status` (401/403). */
+  AccessDenied: "remotestorage.scope.denied",
+} as const;
+
+/** Union of the event-name string literals in {@link RemoteStorageLogEvent}. */
+export type RemoteStorageLogEvent =
+  (typeof RemoteStorageLogEvent)[keyof typeof RemoteStorageLogEvent];

package/src/scope.ts

@@ -0,0 +1,99 @@
+/**
+ * The remoteStorage authorization model as pure, runtime-free logic: OAuth
+ * **scope** parsing, the module a storage path belongs to, and the read/write
+ * access decision. No Workers runtime, no store, no token verification — so it
+ * unit-tests in isolation and the front door and any future co-tenant share one
+ * audited rule set.
+ *
+ * remoteStorage scopes are space-delimited `<module>:<mode>` entries (draft
+ * §10): `mode` is `r` (read-only) or `rw` (read-write), and the module is a
+ * top-level folder name, or `*` for the whole vault. A module scope `m` grants
+ * access to both the private tree `/<m>/…` and the public tree `/public/<m>/…`.
+ */
+
+/** A granted access mode: read-only or read-write. */
+export type ScopeMode = "r" | "rw";
+
+/** A single parsed remoteStorage OAuth scope. */
+export interface RemoteStorageScope {
+  /** Top-level module (folder) name, or {@link ROOT_MODULE} for the whole vault. */
+  readonly module: string;
+  /** Whether the scope grants writes (`rw`) or reads only (`r`). */
+  readonly mode: ScopeMode;
+}
+
+/** The wildcard module name granting access to the entire vault. */
+export const ROOT_MODULE = "*";
+
+/**
+ * Parse a space-delimited OAuth `scope` string into remoteStorage scopes.
+ * Malformed entries (no `:`, empty module, or a mode other than `r`/`rw`) are
+ * dropped rather than failing the whole token, so an unrelated scope a client
+ * also requested cannot deny access to a valid one.
+ */
+export function parseScopes(
+  raw: string | undefined | null,
+): RemoteStorageScope[] {
+  if (!raw) return [];
+  const scopes: RemoteStorageScope[] = [];
+  for (const entry of raw.split(/\s+/)) {
+    if (entry === "") continue;
+    const colon = entry.lastIndexOf(":");
+    if (colon <= 0) continue;
+    const module = entry.slice(0, colon);
+    const mode = entry.slice(colon + 1);
+    if (mode !== "r" && mode !== "rw") continue;
+    scopes.push({ module, mode });
+  }
+  return scopes;
+}
+
+/** Whether a request path targets a folder (the trailing-slash convention). */
+export function isFolderPath(path: string): boolean {
+  return path.endsWith("/");
+}
+
+/**
+ * Whether a path is a **publicly readable document**: it lives under `/public/`
+ * and is not itself a folder. Folder listings are never public, even under
+ * `/public/` (draft §10), so a trailing-slash path returns `false`.
+ */
+export function isPublicDocument(path: string): boolean {
+  return path.startsWith("/public/") && !isFolderPath(path);
+}
+
+/**
+ * The top-level module a storage path belongs to, for scope matching. The
+ * leading `/public/` segment is transparent — `/public/photos/x` and
+ * `/photos/x` share the module `photos` — and the vault root (`/`, or
+ * `/public/`) maps to the empty module, which only the {@link ROOT_MODULE}
+ * (`*`) scope can reach.
+ */
+export function moduleForPath(path: string): string {
+  let rel = path.replace(/^\/+/, "");
+  if (rel === "public" || rel.startsWith("public/")) {
+    rel = rel.slice("public".length).replace(/^\/+/, "");
+  }
+  const slash = rel.indexOf("/");
+  return slash === -1 ? rel : rel.slice(0, slash);
+}
+
+/**
+ * Decide whether the granted `scopes` permit the requested access to `path`.
+ * `needWrite` selects read-vs-write: a write requires an `rw` scope, a read is
+ * satisfied by either. A scope matches when its module equals the path's module
+ * or is the `*` wildcard. The empty-module root (`/`) is reachable only via `*`.
+ */
+export function authorizeScopes(
+  scopes: readonly RemoteStorageScope[],
+  path: string,
+  needWrite: boolean,
+): boolean {
+  const module = moduleForPath(path);
+  for (const scope of scopes) {
+    if (scope.module !== ROOT_MODULE && scope.module !== module) continue;
+    if (needWrite && scope.mode !== "rw") continue;
+    return true;
+  }
+  return false;
+}