@takosjp/yurucommu-core 4.1.3 → 4.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-core",
-  "version": "4.1.3",
+  "version": "4.1.5",
   "license": "AGPL-3.0-only",
   "type": "module",
   "workspaces": [

package/packages/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-api",
-  "version": "4.1.3",
+  "version": "4.1.5",
   "description": "Typed client SDK and public API contract for yurucommu-server clients.",
   "license": "AGPL-3.0-only",
   "type": "module",

package/src/backend/lib/conditional-request.ts

@@ -0,0 +1,87 @@
+/**
+ * `If-None-Match` evaluation (RFC 9110 §8.8.3, §13.1.2).
+ *
+ * Two rules from the RFC are easy to get wrong and are both pinned here.
+ *
+ * The FIELD IS A LIST, and a comma is not a separator it can be split on.
+ * `etagc` admits every VCHAR except DQUOTE, so `","` is a legal opaque-tag and
+ * `header.split(",")` would tear one in half. The scan below reads a tag at a
+ * time — an optional `W/`, an opening DQUOTE, then everything up to the next
+ * DQUOTE, which is unambiguous precisely because the tag body cannot contain
+ * one.
+ *
+ * The COMPARISON IS WEAK. §13.1.2 evaluates `If-None-Match` with the weak
+ * comparison function, so the weakness marker is ignored on both sides and only
+ * the quoted opaque-tags are compared, character for character. (The strong
+ * function is for `If-Match` and `If-Range`, where a weak validator may not be
+ * used to reassemble a representation.)
+ *
+ * A field value the grammar does not admit yields no tags at all and therefore
+ * no match: §13.1 says to ignore a condition that cannot be evaluated, which
+ * for a cache validator means serving the full representation.
+ */
+
+/**
+ * Would the client's cached copy still be valid — i.e. should the caller answer
+ * `304 Not Modified` instead of the representation?
+ *
+ * `httpEtag` must be the SAME value the response emits in `ETag`: the quoted,
+ * header-safe spelling. A bare backend etag never matches anything a client
+ * echoes back, which is the whole reason this takes the header form.
+ *
+ * Call this only once the requested representation is known to exist and the
+ * requester is known to be allowed to read it. `*` matches whenever there is a
+ * current representation, and answering 304 to someone who may not read the
+ * object would leak its existence.
+ */
+export function ifNoneMatchIsFresh(
+  header: string | undefined | null,
+  httpEtag: string | undefined,
+): boolean {
+  if (!header || !httpEtag) return false;
+  const field = header.trim();
+  // `If-None-Match = "*" / 1#entity-tag`: the wildcard is the WHOLE field, not
+  // a member of the list, and it matches because a representation exists.
+  if (field === "*") return true;
+  const target = opaqueTagOf(httpEtag);
+  if (target === null) return false;
+  return entityTags(field).includes(target);
+}
+
+/** One entity-tag reduced to its quoted opaque-tag, or `null` if malformed. */
+function opaqueTagOf(tag: string): string | null {
+  const bare = tag.startsWith("W/") ? tag.slice(2) : tag;
+  if (bare.length < 2 || !bare.startsWith('"') || !bare.endsWith('"')) {
+    return null;
+  }
+  return bare;
+}
+
+/** Every entity-tag in a list field value, or none at all if it is malformed. */
+function entityTags(field: string): string[] {
+  const tags: string[] = [];
+  let index = 0;
+  while (index < field.length) {
+    const char = field[index];
+    if (char === "," || char === " " || char === "\t") {
+      index += 1;
+      continue;
+    }
+    // The weakness marker is consumed and discarded: the weak comparison
+    // function does not distinguish `W/"x"` from `"x"`.
+    if (field.startsWith("W/", index)) index += 2;
+    if (field[index] !== '"') return [];
+    const end = field.indexOf('"', index + 1);
+    if (end === -1) return [];
+    tags.push(field.slice(index, end + 1));
+    index = end + 1;
+    while (index < field.length) {
+      const next = field[index];
+      if (next !== " " && next !== "\t") break;
+      index += 1;
+    }
+    // Nothing but a comma may follow an entity-tag.
+    if (index < field.length && field[index] !== ",") return [];
+  }
+  return tags;
+}

package/src/backend/middleware/cache.ts

@@ -15,6 +15,7 @@
 import type { Context, MiddlewareHandler, Next } from "hono";
 import type { Env, Variables } from "../types.ts";
 import { logger } from "../lib/logger.ts";
+import { ifNoneMatchIsFresh } from "../lib/conditional-request.ts";
 import { bytesToHex } from "../lib/hex.ts";
 
 const log = logger.child({ component: "middleware.cache" });
@@ -224,8 +225,11 @@ function isConditionalHit(
   etag: string | null,
   lastModified: string | null,
 ): boolean {
-  const ifNoneMatch = c.req.header("If-None-Match");
-  if (ifNoneMatch && etag && ifNoneMatch === etag) {
+  // One `If-None-Match` reading for the whole backend. String equality was not
+  // one: the field is a LIST, `W/"x"` is a match for `"x"` under §13.1.2's weak
+  // comparison, and `*` matches any existing representation. `generateETag`
+  // already emits the quoted form these are compared against.
+  if (ifNoneMatchIsFresh(c.req.header("If-None-Match"), etag ?? undefined)) {
     return true;
   }
 

package/src/backend/public.ts

@@ -108,8 +108,17 @@ export {
 } from "./runtime/edge-queue.ts";
 export {
   EdgeObjectStorage,
+  EdgeObjectsBucket,
   EdgeObjectsShapeError,
+  type EdgeObjectHttpMetadata,
+  type EdgeObjectRange,
+  type EdgeObjectsGetOptions,
+  type EdgeObjectsListOptions,
+  type EdgeR2Object,
+  type EdgeR2ObjectBody,
+  type EdgeR2Objects,
   wrapEdgeObjects,
+  wrapEdgeObjectsAsBucket,
 } from "./runtime/edge-objects.ts";
 export type {
   IKeyValueStore,

package/src/backend/routes/apps.ts

@@ -282,7 +282,10 @@ appsServeRoutes.get("/:clientId/:appName/*", async (c) => {
       filePath.includes("/assets/")
         ? "public, max-age=31536000, immutable"
         : "public, max-age=3600",
-      object.etag,
+      // The quoted entity-tag, never the port's verbatim `etag`: that one is a
+      // bare hex digest on the portable lane and is not a valid `ETag` field
+      // value (RFC 9110 §8.8.3).
+      object.httpEtag,
     );
     return new Response(object.body, { headers });
   }
@@ -295,7 +298,7 @@ appsServeRoutes.get("/:clientId/:appName/*", async (c) => {
       const headers = createHostedHeaders(
         "text/html; charset=utf-8",
         "no-cache",
-        indexObject.etag,
+        indexObject.httpEtag,
       );
       return new Response(indexObject.body, { headers });
     }

package/src/backend/routes/media.ts

@@ -11,6 +11,7 @@ import {
 } from "../../db/index.ts";
 import { generateId } from "../federation-helpers.ts";
 import { canViewerReadObject } from "../lib/community-visibility.ts";
+import { ifNoneMatchIsFresh } from "../lib/conditional-request.ts";
 import { canViewerReadObjectFull } from "../lib/post-visibility.ts";
 import { stripImageMetadata } from "../lib/strip-image-metadata.ts";
 import { logger } from "../lib/logger.ts";
@@ -588,18 +589,44 @@ async function serveMediaByR2Key(c: MediaContext, r2Key: string) {
     const maxAge = contentType.startsWith("video/")
       ? CACHE_MAX_AGE_VIDEO
       : CACHE_MAX_AGE_IMAGE;
-    const etag = object.etag;
+    const cacheControl = `${cacheScope}, max-age=${maxAge}`;
+    // The HEADER form, not `object.etag`. An `ETag` field value is an
+    // entity-tag and an entity-tag's opaque-tag is always quoted (RFC 9110
+    // §8.8.3); the port's `etag` is the backend's verbatim spelling, which on
+    // the portable lane is a BARE hex digest. Serving that produced a field no
+    // cache could match and no client could echo back — media was effectively
+    // uncacheable on self-host. `httpEtag` is the quoted form on every lane.
+    const etag = object.httpEtag;
+
+    // §13.1.2 evaluates `If-None-Match` with the WEAK comparison function, so
+    // `W/"x"` from the client matches the `"x"` we sent; only the opaque-tags
+    // are compared. The validator on both sides of that comparison is the one
+    // we emitted, which is why it reads `httpEtag` and not `etag`. Reached only
+    // after the authorization gate above: `*` matches any representation that
+    // exists, so answering 304 earlier would disclose that a private object is
+    // there.
+    if (etag && ifNoneMatchIsFresh(c.req.header("If-None-Match"), etag)) {
+      // The port has no `head`, so the bytes were already fetched; a 304 must
+      // not carry them (§15.4.5), and dropping the stream unread would leak it.
+      await object.body?.cancel().catch(() => undefined);
+      // §15.4.5 also asks a 304 to carry the header fields a 200 would have
+      // sent that guide cache behaviour — here, the validator and the policy.
+      return c.body(null, 304, {
+        "Cache-Control": cacheControl,
+        ETag: etag,
+      });
+    }
 
     if (!object.body) {
       return c.body(null, 200, {
         "Content-Type": contentType,
-        "Cache-Control": `${cacheScope}, max-age=${maxAge}`,
+        "Cache-Control": cacheControl,
         ...(etag ? { ETag: etag } : {}),
       });
     }
     return c.body(object.body, 200, {
       "Content-Type": contentType,
-      "Cache-Control": `${cacheScope}, max-age=${maxAge}`,
+      "Cache-Control": cacheControl,
       ...(etag ? { ETag: etag } : {}),
     });
   } catch (error) {

package/src/backend/runtime/cloudflare.ts

@@ -56,7 +56,14 @@ class CloudflareStorage implements ObjectStore {
       key,
       body: obj.body as unknown as ReadableStream,
       contentType: obj.httpMetadata?.contentType,
+      // R2 spells the same validator twice: `etag` bare, `httpEtag` quoted.
+      // This adapter has always handed the quoted one over as the port's
+      // opaque `etag`, and that stays — narrowing a published field to R2's
+      // bare spelling would silently change what every existing reader sees.
+      // `httpEtag` names the header-safe form explicitly, which on this lane is
+      // the same string.
       etag: obj.httpEtag,
+      httpEtag: obj.httpEtag,
       byteLength: obj.size,
     };
   }

package/src/backend/runtime/edge-objects.ts

@@ -1,14 +1,62 @@
 /**
- * `edge.objects@1.0.0` → {@link ObjectStore}.
+ * `edge.objects@1.0.0` → an R2-shaped bucket, and → {@link ObjectStore}.
  *
- * The facade is deliberately narrower than R2, and the narrow spots are the
- * interesting ones:
+ * ## What the Host hands over, and what R2 hands over
+ *
+ * Takoserver's facade is method-for-method a bucket (`head`, `get`, `put`,
+ * `delete`, `list`, plus the four multipart calls), which is the whole point of
+ * the Interface: an app written against R2 is supposed to port over unchanged.
+ * The RESULT objects were not: the facade's `get()` answers with a plain record
+ * of `{etag, size, contentType?, body, partial, range?}`, while a native
+ * `R2ObjectBody` also carries `text()`, `json()`, `arrayBuffer()`, `bytes()`,
+ * `blob()`, `key`, `httpEtag`, `uploaded`, `httpMetadata` and
+ * `writeHttpMetadata()`. So the facade WAS distinguishable from R2 — by exactly
+ * the members an app is most likely to reach for. `await (await env.MEDIA.get(k)).text()`, which is
+ * legal R2, threw `o.text is not a function` on the portable lane.
+ *
+ * The wire contract is Takoserver's (ADR 0005) and does not move. This module
+ * closes the gap on THIS side: {@link EdgeObjectsBucket} wraps the binding and
+ * returns objects that carry R2's members, so R2-shaped app code compiles and
+ * runs against either host.
+ *
+ * ## The parity rule
+ *
+ * PROVIDED, with R2's names and R2's semantics: `key`, `size`, `etag`,
+ * `httpEtag`, `httpMetadata`, `customMetadata`, `range`, `writeHttpMetadata()`,
+ * and on a body answer `body`, `bodyUsed`, `arrayBuffer()`, `bytes()`, `text()`,
+ * `json()`, `blob()`. The five body helpers and `bodyUsed` are a real
+ * `Response`'s, so a second read REJECTS with a `TypeError` exactly as R2's do
+ * rather than replaying a cached value, and reading `body` directly also marks
+ * the object used. `blob()` answers with the bytes and no `type`; the stored
+ * content type is read from `httpMetadata` / `writeHttpMetadata()`, which is
+ * where R2 keeps it too.
+ *
+ * BEST EFFORT: `uploaded`. The Host's `head` and `list` carry
+ * `uploadedAtMillis`, so it is a `Date` there. Its `get` and `put` do NOT —
+ * both Takoserver wrapper backends build their answer without it on purpose —
+ * so it is `undefined` there rather than invented. It is `Date | undefined`
+ * everywhere so one type describes all four.
+ *
+ * NOT PROVIDED, because the wire carries nothing to derive them from:
+ * `version`, `checksums`, `storageClass`. `customMetadata` is present and
+ * always `undefined`: ADR 0005 gives `edge.objects` no custom metadata at all,
+ * so "absent" is the true answer rather than a missing member.
+ *
+ * `etag` is the Host's etag VERBATIM and is opaque: the self-host wrapper sends
+ * a bare hex digest (R2's unquoted `etag` spelling) and the managed wrapper
+ * forwards R2's quoted `httpEtag`. This facade does not rewrite it: it is the
+ * Host's own identity for those bytes, and R2 does not rewrite its `etag`
+ * either. `httpEtag` is derived — the same value, quoted when it was not
+ * already — and THAT is the one a response emits, because a bare digest is not
+ * an entity-tag (RFC 9110 §8.8.3) and no cache can match one. The
+ * provider-neutral {@link ObjectStore} answer carries both for the same reason.
+ *
+ * ## The narrow spots of the facade itself, which parity does not widen
  *
  *  - NO CUSTOM METADATA. Only `contentType` survives a round trip, which is
  *    also all the provider-neutral {@link ObjectStorePutOptions} carries.
- *  - FIXED ARITIES. The Host counts `arguments.length`, so `get` and `put` are
- *    always called with their full argument list even when the options are
- *    absent.
+ *  - FIXED ARITIES. The Host counts `arguments.length`, so every call passes
+ *    its full argument list even when the options slot is absent.
  *  - A STREAMING `put` NEEDS `contentLength`. ADR 0005 is explicit that a Host
  *    enforces the declared count while streaming and never buffers a body to
  *    discover its size. Every body shape but a bare `ReadableStream` already
@@ -16,10 +64,12 @@
  *    `ArrayBuffer`, a string — so the length is declared and the bytes stream
  *    through. A stream that arrives without a knowable length is buffered
  *    HERE, in the Worker, which is the honest cost of not knowing the size.
- *  - `delete` TAKES ONE KEY. The port's array form becomes a sequence of calls,
- *    which is not atomic — the same as R2's, which also has no transaction.
- *  - NO ENUMERATION OR HEAD. The port does not carry them, so neither does the
- *    adapter, even though the Host projects both.
+ *  - `delete` TAKES ONE KEY. The bucket's array form becomes a sequence of
+ *    calls, which is not atomic — the same as R2's, which also has no
+ *    transaction.
+ *  - AN UNRANGED `get` MUST NOT BE PARTIAL. A truncated body served as a whole
+ *    object is a silent corruption, so the bytes are dropped and the call
+ *    throws.
  *
  * AVAILABILITY: BOTH wrapper backends project `edge.objects`. The managed
  * Cloudflare backend does it over provider-private R2
@@ -37,8 +87,12 @@ import type {
   ObjectStoreObject,
   ObjectStorePutOptions,
 } from "./types.ts";
-import type { EdgeObjectsBinding } from "./edge-facades.ts";
-import { readStream } from "./shared.ts";
+import type {
+  EdgeObjectBody,
+  EdgeObjectMetadata,
+  EdgeObjectsBinding,
+} from "./edge-facades.ts";
+import { httpEtagOf, readStream } from "./shared.ts";
 
 /** A request or response the facade cannot express. */
 export class EdgeObjectsShapeError extends TypeError {
@@ -48,6 +102,198 @@ export class EdgeObjectsShapeError extends TypeError {
   }
 }
 
+/**
+ * R2's `R2HTTPMetadata`, restricted to the one field `edge.objects` carries.
+ *
+ * The other five R2 fields (`contentLanguage`, `contentDisposition`,
+ * `contentEncoding`, `cacheControl`, `cacheExpiry`) are absent on every answer
+ * because the Interface never accepted them on `put`.
+ */
+export interface EdgeObjectHttpMetadata {
+  readonly contentType?: string;
+}
+
+/** A byte range the Host actually served, in R2's `R2Range` spelling. */
+export interface EdgeObjectRange {
+  readonly offset: number;
+  readonly length: number;
+}
+
+/**
+ * R2's `R2Object` over `edge.objects@1.0.0`: what `head`, `put` and a `list`
+ * entry answer with.
+ */
+export interface EdgeR2Object {
+  readonly key: string;
+  readonly size: number;
+  /** The Host's etag verbatim. Opaque; quoting differs by backend. */
+  readonly etag: string;
+  /** The same etag in R2's header-safe quoted spelling. */
+  readonly httpEtag: string;
+  /** A `Date` on `head` and `list`; `undefined` on `get` and `put`. */
+  readonly uploaded: Date | undefined;
+  readonly httpMetadata: EdgeObjectHttpMetadata;
+  /** Always `undefined`: `edge.objects` has no custom metadata (ADR 0005). */
+  readonly customMetadata: undefined;
+  /** Present only on a ranged `get`. */
+  readonly range?: EdgeObjectRange;
+  /** Writes the metadata this object carries onto response headers. */
+  writeHttpMetadata(headers: Headers): void;
+}
+
+/** R2's `R2ObjectBody`: an {@link EdgeR2Object} whose bytes came with it. */
+export interface EdgeR2ObjectBody extends EdgeR2Object {
+  readonly body: ReadableStream<Uint8Array>;
+  readonly bodyUsed: boolean;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  bytes(): Promise<Uint8Array>;
+  text(): Promise<string>;
+  json<T = unknown>(): Promise<T>;
+  blob(): Promise<Blob>;
+}
+
+/** R2's `R2Objects`: one page of {@link EdgeObjectsBucket.list}. */
+export interface EdgeR2Objects {
+  readonly objects: readonly EdgeR2Object[];
+  readonly truncated: boolean;
+  readonly cursor?: string;
+  /** R2's name for the common prefixes a `delimiter` collapsed. */
+  readonly delimitedPrefixes: readonly string[];
+}
+
+export interface EdgeObjectsGetOptions {
+  readonly range?: { readonly offset: number; readonly length?: number };
+}
+
+export interface EdgeObjectsListOptions {
+  readonly prefix?: string;
+  readonly delimiter?: string;
+  readonly cursor?: string;
+  readonly limit?: number;
+}
+
+function writeContentType(
+  contentType: string | undefined,
+  headers: Headers,
+): void {
+  // R2 writes only the fields its `httpMetadata` actually holds, so an object
+  // stored without a content type leaves the caller's headers alone.
+  if (contentType !== undefined) headers.set("content-type", contentType);
+}
+
+/**
+ * R2's `R2Object`. Metadata only: `head`, `put` and every `list` entry.
+ */
+class EdgeR2ObjectMetadata implements EdgeR2Object {
+  readonly key: string;
+  readonly size: number;
+  readonly etag: string;
+  readonly httpEtag: string;
+  readonly uploaded: Date | undefined;
+  readonly httpMetadata: EdgeObjectHttpMetadata;
+  readonly customMetadata: undefined = undefined;
+  readonly range?: EdgeObjectRange;
+
+  constructor(
+    key: string,
+    metadata: {
+      readonly etag: string;
+      readonly size: number;
+      readonly contentType?: string;
+      readonly uploadedAtMillis?: number;
+    },
+    range?: EdgeObjectRange,
+  ) {
+    this.key = key;
+    this.size = metadata.size;
+    this.etag = metadata.etag;
+    this.httpEtag = httpEtagOf(metadata.etag);
+    this.uploaded =
+      metadata.uploadedAtMillis === undefined
+        ? undefined
+        : new Date(metadata.uploadedAtMillis);
+    this.httpMetadata =
+      metadata.contentType === undefined
+        ? {}
+        : { contentType: metadata.contentType };
+    if (range !== undefined) this.range = range;
+  }
+
+  writeHttpMetadata(headers: Headers): void {
+    writeContentType(this.httpMetadata.contentType, headers);
+  }
+}
+
+/**
+ * R2's `R2ObjectBody`.
+ *
+ * The bytes are held in a `Response`, which is where the body semantics come
+ * from rather than being re-implemented: `bodyUsed` flips the moment the stream
+ * is disturbed — including by a caller that read `body` itself — and a second
+ * `text()` / `json()` / `arrayBuffer()` / `blob()` REJECTS with a `TypeError`
+ * instead of replaying the first read. That is R2's own behaviour (workerd's
+ * `R2ObjectBody` refuses a disturbed body the same way the `Body` mixin does),
+ * so a caller cannot tell the two apart by consuming twice.
+ */
+class EdgeR2ObjectWithBody
+  extends EdgeR2ObjectMetadata
+  implements EdgeR2ObjectBody
+{
+  readonly #response: Response;
+
+  constructor(
+    key: string,
+    metadata: {
+      readonly etag: string;
+      readonly size: number;
+      readonly contentType?: string;
+      readonly uploadedAtMillis?: number;
+    },
+    body: ReadableStream<Uint8Array>,
+    range?: EdgeObjectRange,
+  ) {
+    super(key, metadata, range);
+    // Bytes only, with no content type attached: a `Response` normalises the
+    // header it is given (appending `;charset=utf-8` to a text type, for one),
+    // and that normalisation would show up on `blob().type` as a value the Host
+    // never stored. The stored content type is read where R2 puts it —
+    // `httpMetadata` and `writeHttpMetadata()`.
+    this.#response = new Response(body as unknown as BodyInit);
+  }
+
+  get body(): ReadableStream<Uint8Array> {
+    // A `Response` built from a stream always has one.
+    return this.#response.body as ReadableStream<Uint8Array>;
+  }
+
+  get bodyUsed(): boolean {
+    return this.#response.bodyUsed;
+  }
+
+  arrayBuffer(): Promise<ArrayBuffer> {
+    return this.#response.arrayBuffer();
+  }
+
+  async bytes(): Promise<Uint8Array> {
+    // Built on `arrayBuffer()` rather than `Response.bytes()`, which this repo
+    // cannot name while type-checking against the DOM lib. It is the same read,
+    // so the once-only semantics are the same: a second call rejects.
+    return new Uint8Array(await this.#response.arrayBuffer());
+  }
+
+  text(): Promise<string> {
+    return this.#response.text();
+  }
+
+  json<T = unknown>(): Promise<T> {
+    return this.#response.json() as Promise<T>;
+  }
+
+  blob(): Promise<Blob> {
+    return this.#response.blob();
+  }
+}
+
 /**
  * The byte length of a body the Host can be told up front, or `undefined` for
  * a bare stream whose size only the producer knows.
@@ -61,14 +307,57 @@ function knownBodyLength(value: ObjectStoreBody): number | undefined {
   return undefined;
 }
 
-export class EdgeObjectStorage implements ObjectStore {
-  constructor(private readonly bucket: EdgeObjectsBinding) {}
+/**
+ * `edge.objects@1.0.0` as a bucket whose answers are R2's.
+ *
+ * The calls are the facade's (its option names, its ceilings, its error
+ * vocabulary); the results are R2-shaped, so app code written against
+ * `R2Bucket` reads them unchanged. See the parity rule at the top of this file
+ * for what is provided, what is best effort, and what the wire cannot supply.
+ */
+export class EdgeObjectsBucket {
+  constructor(private readonly binding: EdgeObjectsBinding) {}
+
+  async head(key: string): Promise<EdgeR2Object | null> {
+    const found: EdgeObjectMetadata | null = await this.binding.head(key);
+    if (!found) return null;
+    return new EdgeR2ObjectMetadata(key, found);
+  }
+
+  async get(
+    key: string,
+    options?: EdgeObjectsGetOptions,
+  ): Promise<EdgeR2ObjectBody | null> {
+    const range = options?.range;
+    // Fixed arity: the Host counts `arguments.length`, so the options slot is
+    // always passed, even when it is empty.
+    const found: EdgeObjectBody | null = await this.binding.get(
+      key,
+      range === undefined ? undefined : { range },
+    );
+    if (!found) return null;
+    if (found.partial && range === undefined) {
+      // No range was asked for, so a partial body would be a truncated object
+      // served as if it were whole. Refuse rather than hand the caller bytes
+      // that do not add up to the object.
+      await found.body.cancel().catch(() => undefined);
+      throw new EdgeObjectsShapeError(
+        "edge.objects: the Host returned a partial body for an unranged get",
+      );
+    }
+    return new EdgeR2ObjectWithBody(
+      key,
+      found,
+      found.body as ReadableStream<Uint8Array>,
+      found.range,
+    );
+  }
 
   async put(
     key: string,
     value: ObjectStoreBody,
     options?: ObjectStorePutOptions,
-  ): Promise<void> {
+  ): Promise<EdgeR2Object> {
     const contentType = options?.contentType;
     let contentLength = knownBodyLength(value);
     // The facade's body slot has no `Blob`. A Blob's stream carries the same
@@ -84,41 +373,90 @@ export class EdgeObjectStorage implements ObjectStore {
       body = buffered;
       contentLength = buffered.byteLength;
     }
-    await this.bucket.put(key, body, {
+    const stored = await this.binding.put(key, body, {
       contentLength,
       ...(contentType === undefined ? {} : { contentType }),
     });
+    // The Host's `put` answers with `{etag, size}` and nothing else, so the
+    // returned object's `uploaded` is absent — see the parity rule above.
+    return new EdgeR2ObjectMetadata(key, {
+      etag: stored.etag,
+      size: stored.size,
+      ...(contentType === undefined ? {} : { contentType }),
+    });
+  }
+
+  async delete(key: string | readonly string[]): Promise<void> {
+    const keys = typeof key === "string" ? [key] : [...new Set(key)];
+    for (const one of keys) await this.binding.delete(one);
+  }
+
+  async list(options?: EdgeObjectsListOptions): Promise<EdgeR2Objects> {
+    const page = await this.binding.list(options);
+    return {
+      objects: page.objects.map(
+        (entry) => new EdgeR2ObjectMetadata(entry.key, entry),
+      ),
+      truncated: page.truncated,
+      ...(page.cursor === undefined ? {} : { cursor: page.cursor }),
+      // R2 calls the common prefixes a delimiter collapsed `delimitedPrefixes`.
+      delimitedPrefixes: page.prefixes,
+    };
+  }
+}
+
+/**
+ * The provider-neutral {@link ObjectStore} over the same bucket.
+ *
+ * This is the port the core's own routes speak, and it stays deliberately
+ * narrower than R2 — flat metadata, no enumeration, no separate head — so app
+ * code does not grow a dependency on a vendor object shape. Code that WANTS R2
+ * takes {@link EdgeObjectsBucket} instead; both run the same adapter, so the
+ * media path proves it.
+ */
+export class EdgeObjectStorage implements ObjectStore {
+  readonly #bucket: EdgeObjectsBucket;
+
+  constructor(bucket: EdgeObjectsBinding) {
+    this.#bucket = new EdgeObjectsBucket(bucket);
+  }
+
+  async put(
+    key: string,
+    value: ObjectStoreBody,
+    options?: ObjectStorePutOptions,
+  ): Promise<void> {
+    await this.#bucket.put(key, value, options);
   }
 
   async get(key: string): Promise<ObjectStoreObject | null> {
-    const found = await this.bucket.get(key, undefined);
+    const found = await this.#bucket.get(key);
     if (!found) return null;
-    if (found.partial) {
-      // No range was asked for, so a partial body would be a truncated object
-      // served as if it were whole. Refuse rather than hand the caller bytes
-      // that do not add up to the object.
-      await found.body.cancel().catch(() => undefined);
-      throw new EdgeObjectsShapeError(
-        "edge.objects: the Host returned a partial body for an unranged get",
-      );
-    }
     return {
-      key,
-      body: found.body as ReadableStream<Uint8Array>,
-      ...(found.contentType === undefined
+      key: found.key,
+      body: found.body,
+      ...(found.httpMetadata.contentType === undefined
         ? {}
-        : { contentType: found.contentType }),
+        : { contentType: found.httpMetadata.contentType }),
       etag: found.etag,
+      httpEtag: found.httpEtag,
       byteLength: found.size,
     };
   }
 
   async delete(key: string | readonly string[]): Promise<void> {
-    const keys = typeof key === "string" ? [key] : [...new Set(key)];
-    for (const one of keys) await this.bucket.delete(one);
+    await this.#bucket.delete(key);
   }
 }
 
+/** Wrap an `edge.objects@1.0.0` binding as an R2-shaped bucket. */
+export function wrapEdgeObjectsAsBucket(
+  bucket: EdgeObjectsBinding,
+): EdgeObjectsBucket {
+  return new EdgeObjectsBucket(bucket);
+}
+
+/** Wrap an `edge.objects@1.0.0` binding as the provider-neutral port. */
 export function wrapEdgeObjects(bucket: EdgeObjectsBinding): ObjectStore {
   return new EdgeObjectStorage(bucket);
 }

package/src/backend/runtime/managed-runtime.ts

@@ -13,6 +13,7 @@ import {
   type ManagedRuntimeConnectionMaterialization,
 } from "@takosjp/takosumi-contract/managed-runtime-connections";
 
+import { httpEtagOf } from "./shared.ts";
 import type {
   IKeyValueStore,
   ObjectStore,
@@ -401,6 +402,16 @@ class ManagedRuntimeStorageObject implements ObjectStoreObject {
     return this.response.headers.get("etag") ?? undefined;
   }
 
+  /**
+   * The gateway forwards R2's quoted `httpEtag`, so this is normally the same
+   * string as `etag`. It is derived rather than assumed: the port's contract is
+   * that `httpEtag` is always an entity-tag a header may carry.
+   */
+  get httpEtag(): string | undefined {
+    const etag = this.etag;
+    return etag === undefined ? undefined : httpEtagOf(etag);
+  }
+
   get byteLength(): number | undefined {
     return parseContentLength(this.response.headers.get("content-length"));
   }

package/src/backend/runtime/s3-fetch.ts

@@ -1,3 +1,4 @@
+import { httpEtagOf } from "./shared.ts";
 import type {
   ObjectStore,
   ObjectStoreBody,
@@ -135,7 +136,10 @@ class S3FetchObjectStore implements ObjectStore {
           ? null
           : boundedBody(response.body, this.maxObjectBytes, "get"),
       ...(contentType === undefined ? {} : { contentType }),
-      ...(etag === undefined ? {} : { etag }),
+      // S3 answers with a quoted entity-tag, so the derivation is a no-op here
+      // — but the port promises `httpEtag` on every backend, and deriving it
+      // is what makes that true without trusting one server's spelling.
+      ...(etag === undefined ? {} : { etag, httpEtag: httpEtagOf(etag) }),
       ...(byteLength === undefined ? {} : { byteLength }),
     };
   }

package/src/backend/runtime/shared.ts

@@ -39,6 +39,28 @@ export function nowSeconds(): number {
   return Date.now() / 1000;
 }
 
+/**
+ * One backend etag in the spelling an `ETag` header may actually carry.
+ *
+ * RFC 9110 §8.8.3 defines an entity-tag as an optional `W/` marker followed by
+ * a QUOTED opaque-tag, so a bare digest is not a valid field value and no cache
+ * can match one. Backends do not agree on the spelling they hand over: R2 keeps
+ * `etag` bare and `httpEtag` quoted, the `edge.objects` self-host wrapper sends
+ * the raw hex digest, and S3 and the managed gateway forward an already-quoted
+ * one. Every object seam therefore carries the derived, header-safe form beside
+ * the verbatim one, and it is the derived form that reaches a response.
+ *
+ * A value that is already an entity-tag — quoted, weak or strong — is returned
+ * unchanged; anything else is quoted.
+ */
+export function httpEtagOf(etag: string): string {
+  const bare = etag.startsWith("W/") ? etag.slice(2) : etag;
+  if (bare.length >= 2 && bare.startsWith('"') && bare.endsWith('"')) {
+    return etag;
+  }
+  return `"${etag}"`;
+}
+
 export function hasNulByte(value: string): boolean {
   return value.includes("\0");
 }

package/src/backend/runtime/types.ts

@@ -81,7 +81,19 @@ export interface ObjectStoreObject {
   key: string;
   body: ReadableStream<Uint8Array> | null;
   contentType?: string;
+  /**
+   * The backend's etag VERBATIM, and opaque. Backends disagree on the spelling:
+   * some hand over a bare digest, others an already-quoted tag. So this is a
+   * value to compare and to store, never one to put in a header.
+   */
   etag?: string;
+  /**
+   * The same etag as an entity-tag: quoted, and safe to emit (RFC 9110 §8.8.3).
+   * Present exactly when `etag` is. This is the value a response carries in
+   * `ETag` and the value a client echoes back in `If-None-Match`, so a
+   * conditional request is evaluated against this one, not against `etag`.
+   */
+  httpEtag?: string;
   byteLength?: number;
 }