pyric-admin 0.1.0-alpha.21 → 0.1.0-alpha.24

package/src/storage/index.ts

@@ -7,10 +7,10 @@
  *
  *   - **Remote sandbox path** — a handle branded by `@pyric/cli`'
  *     `connectRemoteSandbox()`/`remoteSandbox()` relays every data
- *     operation over the bridge to the browser-hosted SharedWorker's
- *     object store (admin lens pinned — rules bypass). Single bucket;
- *     8 MiB per-op byte cap; `getSignedUrl` stays the local stub. See
- *     the remote arm section below.
+ *     operation to the sandbox's host (admin lens pinned — rules bypass).
+ *     Bytes move over the host's HTTP byte route when it has one, and as
+ *     frames when it does not (a browser tab's SharedWorker). Single bucket;
+ *     `getSignedUrl` stays the local stub. See the remote arm section below.
  *
  *   - **Sandbox path** — returns an in-process {@link Storage} backed
  *     by an in-memory `Map<bucketName, Map<path, FileEntry>>`. State
@@ -23,23 +23,37 @@
  *       - `storage.bucket(name?)` → {@link Bucket}-shaped handle
  *       - `bucket.file(path)` → {@link File}-shaped handle
  *       - `file.save(data, options?)` — `Buffer | string | Uint8Array`
- *       - `file.download(options?)` → `[Buffer]`
+ *       - `file.download(options?)` → `[Buffer]`, whole or `start..end`
+ *       - `file.createReadStream(options?)`, whole or `start..end`
+ *       - `file.createWriteStream(options?)`
+ *       - `file.getMetadata()` / `file.setMetadata(metadata)`: settable fields
+ *         and custom metadata; a custom key set to `null` is removed
+ *       - `getDownloadURL(file)`: mints a token into
+ *         `firebaseStorageDownloadTokens` when the file has none. The Node
+ *         host returns its HTTP URL; elsewhere the URL is a `data:` URI
  *       - `file.delete()` — idempotent
  *       - `file.exists()` → `[boolean]`
  *       - `file.getSignedUrl(options)` → `['pyric-sandbox-storage://…']`
  *
  *     **Deferred in the sandbox backend** (throws `"not implemented in
- *     pyric-admin/storage sandbox backend"`): streaming uploads
- *     (`createWriteStream`), resumable uploads, signed cookies, IAM
- *     policies, lifecycle rules, ACLs, copy/move, notifications.
+ *     pyric-admin/storage sandbox backend"`): resumable uploads, signed
+ *     cookies, IAM policies, lifecycle rules, ACLs, copy/move,
+ *     notifications.
  */
 
+import { createWriteStream as createFileWriteStream, openAsBlob, type WriteStream } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable, Writable } from 'node:stream';
 import {
   isRemoteSandbox,
   type RemoteSandbox,
   type RemoteSandboxChannel,
   type Sandbox,
 } from 'pyric/sandbox';
+import { fetchFromByteRoute, uploadOverByteRoute } from 'pyric/storage/internal';
 
 import {
   ADMIN_APP_TARGET,
@@ -83,9 +97,9 @@ export interface Bucket {
  * / getSignedUrl, etc.) so common consumer code retains the familiar shape.
  *
  * The sandbox backend implements the methods documented here. Any
- * other `File` method from `@google-cloud/storage` (`createWriteStream`,
- * `createReadStream`, `copy`, `move`, `setMetadata` beyond the basic
- * `save` options, etc.) throws on the sandbox path — see module header.
+ * other `File` method from `@google-cloud/storage` (`copy`, `move`,
+ * `setMetadata` beyond the basic `save` options, etc.) is not implemented
+ * on the sandbox path — see module header.
  */
 export interface File {
   /** Name (path) of the file within its bucket. */
@@ -101,11 +115,30 @@ export interface File {
    */
   save(data: Buffer | string | Uint8Array, options?: SaveOptions): Promise<void>;
   /**
-   * Read the file's bytes. Returns a `[Buffer]` tuple to mirror
-   * `@google-cloud/storage`'s `File.download` (which returns
-   * `[Buffer, ...]`). Throws if the file does not exist.
+   * Read the file's bytes, or the inclusive range `start..end` of them.
+   * Returns a `[Buffer]` tuple to mirror `@google-cloud/storage`'s
+   * `File.download` (which returns `[Buffer, ...]`). Throws if the file
+   * does not exist.
    */
   download(options?: DownloadOptions): Promise<[Buffer]>;
+  /**
+   * A readable stream of the file's bytes, or of the inclusive range
+   * `start..end`. A missing file surfaces as the stream's error.
+   */
+  createReadStream(options?: CreateReadStreamOptions): Readable;
+  /**
+   * A writable stream whose bytes replace the file's content once the
+   * stream finishes, as {@link File.save} does.
+   */
+  createWriteStream(options?: CreateWriteStreamOptions): Writable;
+  /** The file's metadata, as a `[metadata]` tuple. Throws if the file does not exist. */
+  getMetadata(): Promise<[FileMetadata]>;
+  /**
+   * Change the file's metadata: the named settable fields, and the custom
+   * keys under `metadata`, where `null` removes a key and the others stay.
+   * Removing `firebaseStorageDownloadTokens` revokes the file's download URL.
+   */
+  setMetadata(metadata: FileMetadataUpdate): Promise<[FileMetadata]>;
   /**
    * Remove the file from its bucket. Idempotent — deleting a missing
    * file is a no-op (matches `@google-cloud/storage`'s
@@ -148,10 +181,58 @@ export interface SaveOptions {
 
 /** Options bag for {@link File.download}. Subset of `@google-cloud/storage`'s `DownloadOptions`. */
 export interface DownloadOptions {
+  /** First byte to read, inclusive. */
+  start?: number;
+  /** Last byte to read, inclusive. */
+  end?: number;
   /** The sandbox accepts but ignores `validation`. */
   validation?: 'md5' | 'crc32c' | boolean;
 }
 
+/** Options bag for {@link File.createReadStream}. Subset of `@google-cloud/storage`'s `CreateReadStreamOptions`. */
+export type CreateReadStreamOptions = DownloadOptions;
+
+/** Options bag for {@link File.createWriteStream}. Subset of `@google-cloud/storage`'s `CreateWriteStreamOptions`. */
+export interface CreateWriteStreamOptions {
+  /** Stored alongside the file, as {@link SaveOptions.metadata} is. */
+  metadata?: Record<string, unknown>;
+  /** Content type stored on the file. */
+  contentType?: string;
+}
+
+/** The custom metadata key holding a file's download tokens, comma-separated. */
+const DOWNLOAD_TOKENS_KEY = 'firebaseStorageDownloadTokens';
+
+/** Settable fields the sandbox keeps, besides custom metadata. */
+const SETTABLE_FIELDS = ['contentType', 'cacheControl', 'contentDisposition', 'contentEncoding', 'contentLanguage'] as const;
+type SettableField = (typeof SETTABLE_FIELDS)[number];
+
+/** A file's metadata. Subset of `@google-cloud/storage`'s `FileMetadata`. */
+export interface FileMetadata {
+  name: string;
+  bucket: string;
+  generation: string;
+  metageneration: string;
+  /** Size in bytes, as a decimal string. */
+  size: string;
+  timeCreated: string;
+  updated: string;
+  contentType?: string;
+  cacheControl?: string;
+  contentDisposition?: string;
+  contentEncoding?: string;
+  contentLanguage?: string;
+  md5Hash?: string;
+  /** Custom metadata, including `firebaseStorageDownloadTokens` once the file has a download URL. Absent when there is none. */
+  metadata?: Record<string, string>;
+}
+
+/** What {@link File.setMetadata} takes. Subset of `@google-cloud/storage`'s `FileMetadata`. */
+export type FileMetadataUpdate = Partial<Pick<FileMetadata, SettableField>> & {
+  /** Custom keys to set; `null` removes a key. Values are stored as strings. */
+  metadata?: Record<string, string | number | boolean | null>;
+};
+
 /** Options bag for {@link File.getSignedUrl}. Mirrors `@google-cloud/storage`'s shape. */
 export interface GetSignedUrlOptions {
   /** `'read' | 'write' | 'delete' | 'resumable'`. Sandbox stamps it into the URL only as a hint. */
@@ -204,13 +285,28 @@ export function getStorage(app?: StorageApp): Storage {
   );
 }
 
+/** Each arm's own download URL. */
+const DOWNLOAD_URL = Symbol('pyric-admin/storage download URL');
+
+interface DownloadUrlSource {
+  [DOWNLOAD_URL](): Promise<string>;
+}
+
 /**
- * Link-compatible mirror of `firebase-admin/storage`'s `getDownloadURL(file)`.
- * Returns a deterministic sandbox storage stub URL from `file.getSignedUrl()`.
+ * Mirror of `firebase-admin/storage`'s `getDownloadURL(file)`. A file without
+ * a download token gets one in `firebaseStorageDownloadTokens`, as production
+ * mints it. On the Node host the URL is its HTTP byte route URL, which serves
+ * ranges and stops working when the token is removed. In process and on a
+ * SharedWorker host there is no HTTP origin, so the URL is a `data:` URI that
+ * carries the bytes.
  */
 export async function getDownloadURL(file: File): Promise<string> {
-  const [url] = await file.getSignedUrl({ action: 'read', expires: '2099-01-01' });
-  return url;
+  const source = file as File & Partial<DownloadUrlSource>;
+  const served = typeof source[DOWNLOAD_URL] === 'function';
+  if (!served) {
+    throw new Error('pyric-admin/storage: getDownloadURL expects a File from getStorage().bucket().file().');
+  }
+  return source[DOWNLOAD_URL]!();
 }
 
 // ─── Sandbox path ───────────────────────────────────────────────────────
@@ -222,11 +318,23 @@ export async function getDownloadURL(file: File): Promise<string> {
  */
 const DEFAULT_SANDBOX_BUCKET = 'pyric-default';
 
-/** A single file's bytes + opaque metadata in the in-memory store. */
+/** A single file's bytes and metadata in the in-memory store. */
 interface FileEntry {
   data: Uint8Array;
-  metadata: Record<string, unknown>;
-  contentType?: string;
+  settable: Partial<Record<SettableField, string>>;
+  custom: Record<string, string>;
+  generation: string;
+  metageneration: number;
+  timeCreated: string;
+  updated: string;
+}
+
+let generationSequence = 0;
+
+/** A generation in the form `@google-cloud/storage` reports: microseconds since the epoch. */
+function nextGeneration(): string {
+  generationSequence = (generationSequence + 1) % 1000;
+  return `${Date.now()}${String(generationSequence).padStart(3, '0')}`;
 }
 
 /** Per-sandbox state: bucket name → (file path → entry). */
@@ -323,16 +431,79 @@ class SandboxFile implements File {
       );
     }
     const bytes = toBytes(data);
-    const metadata = options.metadata ?? {};
-    const entry: FileEntry = {
+    const saved = patchOf(options.metadata ?? {}, { strict: false });
+    const contentType = options.contentType ?? saved.settable.contentType;
+    const now = new Date().toISOString();
+    const custom: Record<string, string> = {};
+    for (const [key, value] of Object.entries(saved.customMetadata)) if (value !== null) custom[key] = value;
+    const hasTokens = typeof saved.downloadTokens === 'string';
+    if (hasTokens) custom[DOWNLOAD_TOKENS_KEY] = saved.downloadTokens!;
+    this.files.set(this.name, {
       data: bytes,
-      metadata,
-      ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),
+      settable: { ...saved.settable, ...(contentType !== undefined ? { contentType } : {}) },
+      custom,
+      generation: nextGeneration(),
+      metageneration: 1,
+      timeCreated: now,
+      updated: now,
+    });
+  }
+
+  async getMetadata(): Promise<[FileMetadata]> {
+    return [this.metadataOf(this.entry())];
+  }
+
+  async setMetadata(metadata: FileMetadataUpdate): Promise<[FileMetadata]> {
+    const entry = this.entry();
+    const patch = patchOf(metadata, { strict: true });
+    Object.assign(entry.settable, patch.settable);
+    for (const [key, value] of Object.entries(patch.customMetadata)) {
+      if (value === null) delete entry.custom[key];
+      else entry.custom[key] = value;
+    }
+    if (patch.downloadTokens === null) delete entry.custom[DOWNLOAD_TOKENS_KEY];
+    else if (patch.downloadTokens !== undefined) entry.custom[DOWNLOAD_TOKENS_KEY] = patch.downloadTokens;
+    this.touch(entry);
+    return [this.metadataOf(entry)];
+  }
+
+  async [DOWNLOAD_URL](): Promise<string> {
+    const entry = this.entry();
+    const tokenless = !entry.custom[DOWNLOAD_TOKENS_KEY];
+    if (tokenless) {
+      entry.custom[DOWNLOAD_TOKENS_KEY] = randomUUID();
+      this.touch(entry);
+    }
+    return dataUri(entry.data, entry.settable.contentType);
+  }
+
+  private entry(): FileEntry {
+    const entry = this.files.get(this.name);
+    if (!entry) throw new Error(`No such object: ${this.bucket.name}/${this.name}`);
+    return entry;
+  }
+
+  private touch(entry: FileEntry): void {
+    entry.metageneration += 1;
+    entry.updated = new Date().toISOString();
+  }
+
+  private metadataOf(entry: FileEntry): FileMetadata {
+    const hasCustom = Object.keys(entry.custom).length > 0;
+    return {
+      name: this.name,
+      bucket: this.bucket.name,
+      generation: entry.generation,
+      metageneration: String(entry.metageneration),
+      size: String(entry.data.byteLength),
+      timeCreated: entry.timeCreated,
+      updated: entry.updated,
+      ...entry.settable,
+      ...(hasCustom ? { metadata: { ...entry.custom } } : {}),
     };
-    this.files.set(this.name, entry);
   }
 
-  async download(_options: DownloadOptions = {}): Promise<[Buffer]> {
+  async download(options: DownloadOptions = {}): Promise<[Buffer]> {
     const entry = this.files.get(this.name);
     if (!entry) {
       // Mirror the gcs/firebase-admin error message shape so consumer
@@ -341,7 +512,19 @@ class SandboxFile implements File {
         `No such object: ${this.bucket.name}/${this.name}`,
       );
     }
-    return [Buffer.from(entry.data)];
+    return [Buffer.from(byteRange(entry.data, options))];
+  }
+
+  createReadStream(options: CreateReadStreamOptions = {}): Readable {
+    const read = async function* (file: SandboxFile): AsyncGenerator<Uint8Array> {
+      const [bytes] = await file.download(options);
+      yield bytes;
+    };
+    return Readable.from(read(this), { objectMode: false });
+  }
+
+  createWriteStream(options: CreateWriteStreamOptions = {}): Writable {
+    return spooledWriteStream(async spooled => this.save(await readFile(spooled), options));
   }
 
   async delete(): Promise<void> {
@@ -356,28 +539,13 @@ class SandboxFile implements File {
     return [stubSignedUrl(this.bucket.name, this.name, options)];
   }
 
-  // ─── Deferred surface (declared so TS callers see a clear error) ────
-
-  /** @deprecated Streaming writes are deferred — see module header. */
-  createWriteStream(): never {
-    throw new Error(
-      'not implemented in pyric-admin/storage sandbox backend: createWriteStream',
-    );
-  }
-
-  /** @deprecated Streaming reads are deferred — see module header. */
-  createReadStream(): never {
-    throw new Error(
-      'not implemented in pyric-admin/storage sandbox backend: createReadStream',
-    );
-  }
 }
 
 // ─── Remote sandbox arm (remote sandbox, slice 2) ───────────────────────
 //
-// The app's `Sandbox` is a Node-side handle onto the browser-hosted
-// SharedWorker sandbox. Every data operation relays over the handle's
-// worker channel with `actAs: { mode: 'admin' }` pinned — firebase-admin's
+// The app's `Sandbox` is a Node-side handle onto a hosted sandbox or a
+// browser tab's SharedWorker sandbox. Every data operation relays over the
+// handle's worker channel with `actAs: { mode: 'admin' }` pinned — firebase-admin's
 // rules-bypass semantics against the ONE object store the app + Studio +
 // agents share (the host resolves the lens to `pyric/storage/internal`'s
 // admin plane). There is deliberately NO local state here: a `WeakMap`
@@ -390,21 +558,24 @@ class SandboxFile implements File {
 //     ("the data store is shared" — bucket names only round-trip in
 //     metadata), so `bucket('non-default')` throws instead of silently
 //     merging buckets. The default bucket name matches the local arm.
-//   - byte payloads are capped at 8 MiB per op (whole-object buffering
-//     over four relay hops; streaming stays unsupported on both sandbox arms).
+//   - a host with an HTTP byte route takes and serves bytes there; a
+//     SharedWorker host has none and takes frames, in 4 MiB parts past that.
 // `getSignedUrl` does NOT relay: it stays the byte-identical local stub.
 
 /** firebase-admin's rules-bypass lens, pinned on every relayed operation. */
 const STORAGE_REMOTE_ADMIN_LENS = { mode: 'admin' } as const;
 
 /**
- * Raw per-op byte cap for relayed storage payloads. MUST mirror
- * `@pyric/cli`' `MAX_STORAGE_OP_BYTES` (serve/worker/protocol.ts) — the
+ * Raw per-part byte cap for storage payloads sent as frames. MUST mirror
+ * `@pyric/cli`' `MAX_STORAGE_PART_BYTES` (serve/worker/protocol.ts) — the
  * worker host enforces the same cap on its end. Inlined (like the RTDB
  * push-id generator) because `pyric-admin` deliberately does not depend on
  * `@pyric/cli`.
  */
-const MAX_REMOTE_STORAGE_OP_BYTES = 8 * 1024 * 1024;
+const MAX_STORAGE_PART_BYTES = 4 * 1024 * 1024;
+
+/** Maximum whole-object size supported by the sandbox backend (512 MiB). Matches MAX_STORAGE_OBJECT_BYTES. */
+const MAX_STORAGE_OBJECT_BYTES = 512 * 1024 * 1024;
 
 /** One remote `Storage` per remote handle (handles only — never data). */
 const remoteStorageBySandbox = new WeakMap<Sandbox, Storage>();
@@ -471,38 +642,184 @@ class RemoteFile implements File {
         'not implemented in pyric-admin/storage remote sandbox backend: resumable uploads',
       );
     }
-    const bytes = toBytes(data);
-    if (bytes.byteLength > MAX_REMOTE_STORAGE_OP_BYTES) {
-      throw payloadTooLarge(bytes.byteLength, `save() payload for '${this.name}'`);
+    const rawLength = typeof data === 'string' ? Buffer.byteLength(data, 'utf8') : data.byteLength;
+    if (rawLength > MAX_STORAGE_OBJECT_BYTES) {
+      throw quotaExceeded(rawLength, `save() payload for '${this.name}'`);
     }
-    await this.channel.op({
-      method: 'storage.putBytes',
-      path: this.name,
-      dataB64: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64'),
+    await this.upload(new Blob([toBytes(data) as Uint8Array<ArrayBuffer>]), options);
+  }
+
+  async download(options: DownloadOptions = {}): Promise<[Buffer]> {
+    const parts: Uint8Array[] = [];
+    for await (const part of this.read(options)) parts.push(part);
+    return [Buffer.concat(parts)];
+  }
+
+  createReadStream(options: CreateReadStreamOptions = {}): Readable {
+    return Readable.from(this.read(options), { objectMode: false });
+  }
+
+  createWriteStream(options: CreateWriteStreamOptions = {}): Writable {
+    return spooledWriteStream(async spooled => {
+      const data = await openAsBlob(spooled);
+      if (data.size > MAX_STORAGE_OBJECT_BYTES) {
+        throw quotaExceeded(data.size, `createWriteStream() payload for '${this.name}'`);
+      }
+      await this.upload(data, options);
+    });
+  }
+
+  /** Store `data` over the host's byte route, or as one frame when the host has none. */
+  private async upload(data: Blob, options: CreateWriteStreamOptions): Promise<void> {
+    const request = {
       ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),
       ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
+    };
+    const route = await this.channel.byteRoute?.();
+    const routed = route !== undefined;
+    if (routed) {
+      await uploadOverByteRoute(this.channel, route, { path: this.name, data, ...request, actAs: STORAGE_REMOTE_ADMIN_LENS });
+      return;
+    }
+    const bytes = new Uint8Array(await data.arrayBuffer());
+    if (bytes.byteLength <= MAX_STORAGE_PART_BYTES) {
+      await this.channel.op({
+        method: 'storage.putBytes',
+        path: this.name,
+        dataB64: base64Of(bytes),
+        ...request,
+        actAs: STORAGE_REMOTE_ADMIN_LENS,
+      });
+      return;
+    }
+    // A SharedWorker host takes a larger object in parts (ADR 0015).
+    const { uploadId } = (await this.channel.op({
+      method: 'storage.beginUpload',
+      path: this.name,
+      size: bytes.byteLength,
+      ...request,
       actAs: STORAGE_REMOTE_ADMIN_LENS,
-    });
+    })) as { uploadId: string };
+    try {
+      for (let offset = 0, index = 0; offset < bytes.byteLength; offset += MAX_STORAGE_PART_BYTES, index++) {
+        await this.channel.op({
+          method: 'storage.putPart',
+          uploadId,
+          partIndex: index,
+          dataB64: base64Of(bytes.subarray(offset, offset + MAX_STORAGE_PART_BYTES)),
+          actAs: STORAGE_REMOTE_ADMIN_LENS,
+        });
+      }
+      await this.channel.op({ method: 'storage.finishUpload', uploadId, actAs: STORAGE_REMOTE_ADMIN_LENS });
+    } catch (err) {
+      try {
+        await this.channel.op({ method: 'storage.abortUpload', uploadId, actAs: STORAGE_REMOTE_ADMIN_LENS });
+      } catch {
+        // secondary abort best effort
+      }
+      throw err;
+    }
   }
 
-  async download(_options: DownloadOptions = {}): Promise<[Buffer]> {
-    let wire: RemoteGetBytesResult;
+  /** The object's bytes, or the inclusive range `start..end`, as they arrive. */
+  private async *read(options: DownloadOptions): AsyncGenerator<Uint8Array> {
+    const metadata = await this.missingAsNoSuchObject(this.channel.op({
+      method: 'storage.getMetadata',
+      path: this.name,
+      actAs: STORAGE_REMOTE_ADMIN_LENS,
+    })) as { bucket: string; size: number; generation: string };
+    const route = await this.channel.byteRoute?.();
+    const routed = route !== undefined;
+    if (!routed) {
+      yield* this.readFrames(metadata, options);
+      return;
+    }
+    const response = await this.missingAsNoSuchObject(fetchFromByteRoute(route, {
+      bucket: metadata.bucket,
+      path: this.name,
+      start: options.start,
+      end: options.end,
+    }));
+    const body = response.body;
+    if (body === null) return;
+    const reader = body.getReader();
     try {
-      wire = (await this.channel.op({
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        yield value;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  /** Read from a SharedWorker host, which sends bytes as frames: whole, or in ranged parts (ADR 0015). */
+  private async *readFrames(metadata: { size: number; generation: string }, options: DownloadOptions): AsyncGenerator<Uint8Array> {
+    if (metadata.size <= MAX_STORAGE_PART_BYTES) {
+      const wire = await this.missingAsNoSuchObject(this.channel.op({
         method: 'storage.getBytes',
         path: this.name,
         actAs: STORAGE_REMOTE_ADMIN_LENS,
       })) as RemoteGetBytesResult;
+      yield byteRange(Buffer.from(wire.dataB64, 'base64'), options);
+      return;
+    }
+    const last = Math.min(metadata.size, options.end === undefined ? metadata.size : options.end + 1);
+    for (let offset = options.start ?? 0; offset < last; offset += MAX_STORAGE_PART_BYTES) {
+      const wire = await this.missingAsNoSuchObject(this.channel.op({
+        method: 'storage.getBytes',
+        path: this.name,
+        offset,
+        length: Math.min(MAX_STORAGE_PART_BYTES, last - offset),
+        expectedGeneration: metadata.generation,
+        actAs: STORAGE_REMOTE_ADMIN_LENS,
+      })) as RemoteGetBytesResult;
+      yield Buffer.from(wire.dataB64, 'base64');
+    }
+  }
+
+  async getMetadata(): Promise<[FileMetadata]> {
+    const full = await this.missingAsNoSuchObject(this.channel.op({
+      method: 'storage.getMetadata',
+      path: this.name,
+      actAs: STORAGE_REMOTE_ADMIN_LENS,
+    })) as HostMetadata;
+    return [fileMetadataOf(full)];
+  }
+
+  async setMetadata(metadata: FileMetadataUpdate): Promise<[FileMetadata]> {
+    const full = await this.missingAsNoSuchObject(this.channel.op({
+      method: 'storage.setMetadata',
+      path: this.name,
+      patch: patchOf(metadata, { strict: true }),
+      actAs: STORAGE_REMOTE_ADMIN_LENS,
+    })) as HostMetadata;
+    return [fileMetadataOf(full)];
+  }
+
+  /** The host mints the token; the Node host serves the URL, a SharedWorker host has nowhere to. */
+  async [DOWNLOAD_URL](): Promise<string> {
+    const { path } = await this.missingAsNoSuchObject(this.channel.op({
+      method: 'storage.getDownloadURL',
+      path: this.name,
+      actAs: STORAGE_REMOTE_ADMIN_LENS,
+    })) as { path: string };
+    const route = await this.channel.byteRoute?.();
+    const routed = route !== undefined;
+    if (routed) return new URL(path, route.baseUrl).href;
+    const [[metadata], [bytes]] = await Promise.all([this.getMetadata(), this.download()]);
+    return dataUri(bytes, metadata.contentType);
+  }
+
+  /** Mirror the gcs/firebase-admin (and local arm) `No such object` message for a missing file. */
+  private async missingAsNoSuchObject<T>(pending: Promise<T>): Promise<T> {
+    try {
+      return await pending;
     } catch (err) {
-      if (isObjectNotFound(err)) {
-        // Mirror the gcs/firebase-admin (and local arm) message shape so
-        // consumer catch-blocks that string-match `No such object` work
-        // identically across arms.
-        throw new Error(`No such object: ${this.bucket.name}/${this.name}`);
-      }
+      if (isObjectNotFound(err)) throw new Error(`No such object: ${this.bucket.name}/${this.name}`);
       throw err;
     }
-    return [Buffer.from(wire.dataB64, 'base64')];
   }
 
   async delete(): Promise<void> {
@@ -540,22 +857,49 @@ class RemoteFile implements File {
   async getSignedUrl(options: GetSignedUrlOptions): Promise<[string]> {
     return [stubSignedUrl(this.bucket.name, this.name, options)];
   }
+}
 
-  // ─── Deferred surface (remediating throws, remote-flavored) ─────────
-
-  createWriteStream(): never {
-    throw new Error(
-      'not implemented in pyric-admin/storage remote sandbox backend: createWriteStream — ' +
-        'streams cannot span the bridge relay; use file.save(buffer) (≤ 8 MiB) instead.',
-    );
-  }
+/** Object metadata as a host reports it (`pyric/storage`'s `FullMetadata`, with its download tokens). */
+interface HostMetadata {
+  bucket: string;
+  fullPath: string;
+  generation: string;
+  metageneration: string;
+  size: number;
+  timeCreated: string;
+  updated: string;
+  md5Hash?: string;
+  contentType?: string;
+  cacheControl?: string;
+  contentDisposition?: string;
+  contentEncoding?: string;
+  contentLanguage?: string;
+  customMetadata?: Record<string, string>;
+  downloadTokens?: string;
+}
 
-  createReadStream(): never {
-    throw new Error(
-      'not implemented in pyric-admin/storage remote sandbox backend: createReadStream — ' +
-        'streams cannot span the bridge relay; use file.download() (≤ 8 MiB) instead.',
-    );
+/** A host's metadata in `@google-cloud/storage`'s shape: the download tokens become the custom key production uses. */
+function fileMetadataOf(host: HostMetadata): FileMetadata {
+  const custom = { ...(host.customMetadata ?? {}) };
+  if (host.downloadTokens) custom[DOWNLOAD_TOKENS_KEY] = host.downloadTokens;
+  const settable: Partial<Record<SettableField, string>> = {};
+  for (const field of SETTABLE_FIELDS) {
+    const value = host[field];
+    if (value !== undefined) settable[field] = value;
   }
+  const hasCustom = Object.keys(custom).length > 0;
+  return {
+    name: host.fullPath,
+    bucket: host.bucket,
+    generation: host.generation,
+    metageneration: host.metageneration,
+    size: String(host.size),
+    timeCreated: host.timeCreated,
+    updated: host.updated,
+    ...settable,
+    ...(host.md5Hash !== undefined ? { md5Hash: host.md5Hash } : {}),
+    ...(hasCustom ? { metadata: custom } : {}),
+  };
 }
 
 /** Is this relayed error the worker's `storage/object-not-found`? */
@@ -563,21 +907,108 @@ function isObjectNotFound(err: unknown): boolean {
   return (err as { code?: unknown })?.code === 'storage/object-not-found';
 }
 
-/** Over-cap rejection (code `payload-too-large`) — mirrors the worker host's
- *  message shape and names the streaming gap. */
-function payloadTooLarge(sizeBytes: number, what: string): Error & { code: string } {
+/** Over-cap rejection (code `storage/quota-exceeded`) — mirrors the worker host's message shape. */
+function quotaExceeded(sizeBytes: number, what: string): Error & { code: string } {
   const err = new Error(
     `pyric-admin/storage: ${what} is ${sizeBytes} bytes — over the ` +
-      `${MAX_REMOTE_STORAGE_OP_BYTES / (1024 * 1024)} MiB remote storage op cap. ` +
-      'Streaming/resumable transfers are not supported on the sandbox backend; ' +
-      'split the object or keep it under the cap.',
+      `${MAX_STORAGE_OBJECT_BYTES / (1024 * 1024)} MiB maximum storage object cap (MAX_STORAGE_OBJECT_BYTES).`,
   ) as Error & { code: string };
-  err.code = 'payload-too-large';
+  err.code = 'storage/quota-exceeded';
   return err;
 }
 
 // ─── Helpers ────────────────────────────────────────────────────────────
 
+/** A metadata change in the form hosts take: settable fields, custom keys, and the download tokens apart. */
+interface MetadataPatch {
+  settable: Partial<Record<SettableField, string>>;
+  customMetadata: Record<string, string | null>;
+  downloadTokens?: string | null;
+}
+
+/**
+ * Split `@google-cloud/storage`-shaped metadata into a {@link MetadataPatch}.
+ * `setMetadata` is strict and refuses fields the sandbox does not keep;
+ * `save` has always stored what it was given and ignores them.
+ */
+function patchOf(metadata: FileMetadataUpdate | Record<string, unknown>, { strict }: { strict: boolean }): MetadataPatch {
+  const source = metadata as Record<string, unknown>;
+  const unsupported = Object.keys(source).filter(key => key !== 'metadata' && !(SETTABLE_FIELDS as readonly string[]).includes(key));
+  const refused = strict && unsupported.length > 0;
+  if (refused) {
+    throw new Error(
+      `not implemented in pyric-admin/storage sandbox backend: setMetadata of ${unsupported.join(', ')}. ` +
+        `The sandbox keeps ${SETTABLE_FIELDS.join(', ')}, and custom metadata under \`metadata\`.`,
+    );
+  }
+  const patch: MetadataPatch = { settable: {}, customMetadata: {} };
+  for (const field of SETTABLE_FIELDS) {
+    const value = source[field];
+    if (typeof value === 'string') patch.settable[field] = value;
+  }
+  const custom = source.metadata;
+  const hasCustom = custom !== null && typeof custom === 'object';
+  if (!hasCustom) return patch;
+  for (const [key, value] of Object.entries(custom as Record<string, unknown>)) {
+    if (value === undefined) continue;
+    const next = value === null ? null : String(value);
+    if (key === DOWNLOAD_TOKENS_KEY) patch.downloadTokens = next;
+    else patch.customMetadata[key] = next;
+  }
+  return patch;
+}
+
+/** A `data:` URI carrying `bytes`, the download URL where no host serves them over HTTP. */
+function dataUri(bytes: Uint8Array, contentType: string | undefined): string {
+  return `data:${contentType ?? 'application/octet-stream'};base64,${base64Of(bytes)}`;
+}
+
+/** `bytes` as base64, for a frame. */
+function base64Of(bytes: Uint8Array): string {
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64');
+}
+
+/** The inclusive range `start..end` of `bytes`, as `@google-cloud/storage` reads it. */
+function byteRange(bytes: Uint8Array, options: DownloadOptions): Uint8Array {
+  const end = options.end === undefined ? undefined : options.end + 1;
+  return bytes.subarray(options.start ?? 0, end);
+}
+
+/**
+ * A writable stream that spools its bytes to a temporary file and, once it
+ * finishes, hands that file to `commit`. The file is removed either way.
+ */
+function spooledWriteStream(commit: (spooled: string) => Promise<void>): Writable {
+  let directory: string | undefined;
+  let sink: WriteStream | undefined;
+  return new Writable({
+    construct(callback) {
+      mkdtemp(join(tmpdir(), 'pyric-admin-upload-')).then(created => {
+        directory = created;
+        sink = createFileWriteStream(join(created, 'object'));
+        callback();
+      }, callback);
+    },
+    write(chunk: Buffer, _encoding, callback) {
+      sink!.write(chunk, callback);
+    },
+    final(callback) {
+      sink!.end(() => {
+        commit(join(directory!, 'object')).then(() => callback(), callback);
+      });
+    },
+    destroy(error, callback) {
+      sink?.destroy();
+      const created = directory;
+      if (created === undefined) {
+        callback(error);
+        return;
+      }
+      rm(created, { recursive: true, force: true }).finally(() => callback(error));
+    },
+  });
+}
+
 /**
  * The deterministic sandbox signed-URL stub, shared by the local and remote
  * arms so their output is byte-identical (the URL is never served — it's a