@dwk/remotestorage 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 David W. Keith
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# `@dwk/remotestorage`
+
+> remoteStorage (draft-dejong-remotestorage) personal data vault. Endpoint
+> package + per-account Durable Object.
+
+Part of the [`@dwk` IndieWeb + Solid cohort](../../README.md). See the
+[package specification](../../spec/packages/remotestorage.md) for the full
+requirements.
+
+An [Unhosted](https://unhosted.org/)-style **remoteStorage** server: 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. It is a *competing*
+personal-data protocol to Solid — simpler, document-oriented, **no RDF** — and
+is filed here for completeness, **not** as a recommendation alongside
+[`@dwk/solid-pod`](../solid-pod).
+
+## Why it's here: one backing store, two protocols
+
+[`@dwk/store`](../store) is **not** Solid-specific — it is a generic
+`key → { rdf | blob }` pointer map over DO-SQLite + content-addressed,
+copy-on-write R2 bodies with TOCTOU-free conditional writes and an orphan-outbox
+GC. remoteStorage documents are simply its **blob tier**, so a remoteStorage
+vault and a Solid Pod can ride the same library, the same R2 bucket, and the same
+GC. The only library addition this package required is a single, **generic**
+projection on the `Store` interface:
+
+```ts
+store.list(prefix); // every resource pointer whose key starts with `prefix`
+```
+
+`list(prefix)` ascribes no meaning to `/` or to "folders" — the folder model and
+its aggregate ETags are derived in this package — so `@dwk/solid-pod` could use
+the same projection to enumerate LDP container membership. Everything that makes
+remoteStorage *remoteStorage* (the auth model and folder semantics) lives here.
+
+## Usage
+
+```ts
+import {
+  createRemoteStorage,
+  createRemoteStorageGc,
+  RemoteStorageObject,
+} from "@dwk/remotestorage";
+
+const storage = createRemoteStorage({
+  baseUrl: "https://storage.example",
+  // Built-in OAuth bearer (JWT) verification against the issuer's JWKS:
+  issuer: "https://auth.example",
+  jwksUri: "https://auth.example/jwks",
+  // …or pass `authenticate(request)` to resolve opaque tokens (e.g. RFC 7662
+  // introspection via @dwk/oauth) into `{ scopes }`.
+});
+
+// In your Worker, route the storage tree (default: `/<account>/<path…>`):
+//   PUT  /alice/documents/note.txt
+//   GET  /alice/documents/
+//   GET  /alice/public/photos/cat.jpg   (no token needed)
+export default { fetch: storage };
+export { RemoteStorageObject };
+
+// Bind a cron trigger to reclaim orphaned R2 bodies:
+export const scheduled = createRemoteStorageGc({ baseUrl: "https://storage.example" });
+```
+
+**Bindings** (declared `Env` fragment, fail-loud if missing): a Durable Object
+namespace `STORAGE` for the per-account class, an R2 bucket `BLOBS` (MAY be
+shared with `@dwk/solid-pod`), and an optional D1 `GC_DB` the DO forwards orphan
+keys into for the GC cron.
+
+### Documents
+
+- `PUT` a document → records its `Content-Type`, returns the new strong `ETag`
+  (`201` on create, `200` on overwrite). Honors `If-Match` and `If-None-Match: *`
+  (create-only), checked TOCTOU-free inside the store's write transaction (`412`
+  on failure). Oversized bodies stream straight to R2, never buffered in the DO.
+- `GET`/`HEAD` a document → body + `Content-Type` + `ETag`; `If-None-Match`
+  yields `304`.
+- `DELETE` a document → `200` with the deleted document's `ETag`; emptied parent
+  folders simply vanish (they are virtual).
+- A name that is already a folder (or whose ancestor is already a document) is a
+  collision → **409**. A `PUT`/`DELETE` on a folder path (trailing slash) → **400**.
+
+### Folders
+
+`GET <path>/` returns the `application/ld+json`
+[folder description](https://datatracker.ietf.org/doc/html/draft-dejong-remotestorage-22)
+(`http://remotestorage.io/spec/folder-description`): a map of immediate children
+(documents with their `ETag` + `Content-Type`, subfolders with an aggregate
+`ETag`) and a folder `ETag`. The folder ETag is a SHA-256 over a canonical
+signature of **every descendant**, so it changes whenever anything in the subtree
+does. An empty/absent folder still answers `200` with a stable ETag.
+
+### Authorization (scopes)
+
+Plain OAuth 2.0 **bearer** tokens (no DPoP). A token's `scope` claim is a
+space-delimited list of `<module>:r` / `<module>:rw` entries, where the module is
+a top-level folder name or `*` (the whole vault). A module scope covers both the
+private tree `/<module>/…` and the public tree `/public/<module>/…`.
+
+- **Reads** of `/public/` **documents** need no token (folders are never public).
+- Every other access needs a scope at the required mode; a write without `rw` →
+  **403**, a missing/invalid token on a private path → **401**.
+
+### CORS
+
+Permissive CORS on every response (draft §6) so browser apps on other origins
+work: `OPTIONS` preflights are answered at the edge, and `ETag`/`Content-Type`/
+`Content-Length` are exposed. Bearer tokens travel in `Authorization`, so no
+credentialed CORS is needed.
+
+### Discovery
+
+`remoteStorageLink({ storageRoot, authEndpoint })` builds the WebFinger link a
+connecting app reads to find a user's storage root and OAuth endpoint — drop it
+into a [`@dwk/webfinger`](../webfinger) resource record.
+
+## Design
+
+Stateless front door (CORS + token verification + scope enforcement) over a
+per-account Durable Object that is the single consistency authority (DO-SQLite +
+R2 via `@dwk/store`). Authoritative state lives only in strongly-consistent
+stores — **never KV**. The scope, folder, and CORS logic is pure and unit-tests
+without a Workers runtime.
+
+## Observability
+
+Auth/authz events flow through the injected `@dwk/log` `Logger`/`Metrics` seams
+(default no-op): `remotestorage.auth.accepted` / `.rejected` and
+`remotestorage.scope.denied`. Fields are redacted to reason codes, HTTP
+method/status, and a sanitized subject host — never tokens, scopes verbatim,
+paths, or bodies.

package/dist/auth.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 { 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;
+};
+/** Extract the `Bearer <token>` value, if present. */
+export declare function bearerToken(request: Request): string | null;
+/**
+ * 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 declare function authenticate(request: Request, config: ResolvedConfig): Promise<AuthResult>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE/D,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC/C,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,iBAAiB,GACjB,mBAAmB,GACnB,iBAAiB,GACjB,mBAAmB,GACnB,eAAe,GACf,qBAAqB,CAAC;AAE1B,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAoCtE,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAK3D;AAaD;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,UAAU,CAAC,CA2CrB"}

package/dist/auth.js

@@ -0,0 +1,108 @@
+/**
+ * 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 { decodeJwt, verifyJwtSignature } from "./jwt";
+import { parseScopes } from "./scope";
+const JWKS_TTL_MS = 5 * 60 * 1000;
+const jwksCache = new Map();
+/** Resolve the issuer verification keys: static config first, then cached fetch. */
+async function resolveJwks(config) {
+    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());
+        // 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) {
+    const header = request.headers.get("authorization");
+    if (!header)
+        return null;
+    const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+    return match ? match[1] : null;
+}
+/** Whether the token's `aud` claim intersects the accepted audience set. */
+function audienceMatches(aud, accepted) {
+    if (accepted.length === 0)
+        return true; // audience check disabled
+    const values = Array.isArray(aud)
+        ? aud.filter((a) => 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, config) {
+    // 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 } : {}),
+        },
+    };
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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 { 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;
+}
+/** Internal header the trusted front door uses to hand config to the DO. */
+export declare const INTERNAL_HEADERS: {
+    /** JSON-encoded subset of config the DO needs (offload threshold). */
+    readonly config: "x-remotestorage-config";
+};
+/**
+ * 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 declare function defaultParsePath(pathname: string): ParsedPath | null;
+/** Apply defaults and derived values to raw {@link RemoteStorageConfig}. */
+export declare function resolveConfig(config: RemoteStorageConfig): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

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

package/dist/config.js

@@ -0,0 +1,67 @@
+/**
+ * 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 } from "@dwk/log";
+/** 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",
+};
+/** Strip the trailing slash from a base URL so joins are unambiguous. */
+function normalizeBaseUrl(baseUrl) {
+    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) {
+    const match = /^\/([^/]+)(\/.*)?$/.exec(pathname);
+    if (!match)
+        return null;
+    const account = decodeURIComponent(match[1]);
+    // 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) {
+    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,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAA6B,MAAM,UAAU,CAAC;AA8H9E,2EAA2E;AAC3E,MAAM,2BAA2B,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAElD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,sEAAsE;IACtE,MAAM,EAAE,wBAAwB;CACxB,CAAC;AAEX,yEAAyE;AACzE,SAAS,gBAAgB,CAAC,OAAe;IACvC,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAW,CAAC,CAAC;IACvD,0EAA0E;IAC1E,gDAAgD;IAChD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;IAC7B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,aAAa,CAAC,MAA2B;IACvD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,QAAQ,GACZ,MAAM,CAAC,QAAQ,KAAK,SAAS;QAC3B,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;YACnC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;YACnB,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE7B,OAAO;QACL,OAAO;QACP,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,QAAQ;QACR,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,2BAA2B;QACxE,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACrC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,KAAK;QAC5B,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,gBAAgB;QAC/C,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,UAAU;QACnC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,WAAW;KACvC,CAAC;AACJ,CAAC"}

package/dist/cors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 declare const ALLOWED_METHODS = "GET, HEAD, PUT, DELETE, OPTIONS";
+/** Build the CORS header set for a request with the given `Origin` (may be null). */
+export declare function corsHeaders(requestOrigin: string | null): Record<string, string>;
+/** The preflight (`OPTIONS`) response, answered at the edge without a store hit. */
+export declare function preflightResponse(requestOrigin: string | null): Response;
+/**
+ * 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 declare function withCors(response: Response, requestOrigin: string | null): Response;
+//# sourceMappingURL=cors.d.ts.map

package/dist/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,oEAAoE;AACpE,eAAO,MAAM,eAAe,oCAAoC,CAAC;AAYjE,qFAAqF;AACrF,wBAAgB,WAAW,CACzB,aAAa,EAAE,MAAM,GAAG,IAAI,GAC3B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ,CAUxE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,MAAM,GAAG,IAAI,GAC3B,QAAQ,CAUV"}

package/dist/cors.js

@@ -0,0 +1,56 @@
+/**
+ * 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) {
+    const headers = {
+        "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) {
+    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, requestOrigin) {
+    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,
+    });
+}
+//# sourceMappingURL=cors.js.map

package/dist/cors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.js","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,oEAAoE;AACpE,MAAM,CAAC,MAAM,eAAe,GAAG,iCAAiC,CAAC;AAEjE,yFAAyF;AACzF,MAAM,eAAe,GACnB,gGAAgG,CAAC;AAEnG,iFAAiF;AACjF,MAAM,eAAe,GAAG,8CAA8C,CAAC;AAEvE,mEAAmE;AACnE,MAAM,OAAO,GAAG,OAAO,CAAC;AAExB,qFAAqF;AACrF,MAAM,UAAU,WAAW,CACzB,aAA4B;IAE5B,MAAM,OAAO,GAA2B;QACtC,6BAA6B,EAAE,aAAa,IAAI,GAAG;QACnD,+BAA+B,EAAE,eAAe;QAChD,IAAI,EAAE,QAAQ;KACf,CAAC;IACF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,iBAAiB,CAAC,aAA4B;IAC5D,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;QACxB,MAAM,EAAE,GAAG;QACX,OAAO,EAAE;YACP,GAAG,WAAW,CAAC,aAAa,CAAC;YAC7B,8BAA8B,EAAE,eAAe;YAC/C,8BAA8B,EAAE,eAAe;YAC/C,wBAAwB,EAAE,OAAO;SAClC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,QAAkB,EAClB,aAA4B;IAE5B,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC9C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;QACvE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE;QACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,OAAO;KACR,CAAC,CAAC;AACL,CAAC"}

package/dist/discovery.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 declare const REMOTESTORAGE_REL = "http://tools.ietf.org/id/draft-dejong-remotestorage";
+/** The remoteStorage draft version advertised in the link properties. */
+export declare 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 declare function remoteStorageLink(config: RemoteStorageLinkConfig): Link;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,wDACyB,CAAC;AAExD,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AAErE,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAYvE"}