@spacefast/common 0.0.21 → 0.0.24

package/dist/contracts/runtime-services.js

@@ -0,0 +1,437 @@
+/**
+ * Platform services that tenant code reaches through the runtime rather than
+ * through a credential of its own: Gravatar, spam checking, and mail.
+ *
+ * Three properties hold for all three, and they are the reason this file
+ * exists instead of three unrelated ones:
+ *
+ * - **The credential is never in tenant reach.** An Akismet key or a Gravatar
+ *   token in a bundle is a published secret, and a wp.cloud `SMTP_PASS` in a
+ *   capsule is worse. Every call below is brokered: the runtime attaches
+ *   authority outside the code that asked for the call.
+ * - **The interface is the contract, not the accessor.** Zero hands these to a
+ *   handler as `ctx.gravatar` / `ctx.spam` / `ctx.email`; Functions binds them
+ *   as `env.GRAVATAR` / `env.SPAM` / `env.EMAIL`. Method names and semantic
+ *   fields stay shared. Zero's `check` narrows the input because its HTTP host
+ *   can add request metadata; a detached Functions call supplies that metadata
+ *   explicitly.
+ * - **The client is the same source on both tiers.** See
+ *   `RUNTIME_SERVICE_CLIENT_SOURCE`: normalization, validation and the pure
+ *   avatar-URL construction are one implementation injected into both runtimes,
+ *   so the two tiers cannot drift into behaving differently.
+ *
+ * What differs between tiers is the transport under `call()`, and only that.
+ */
+/* -------------------------------------------------------------------------- */
+/* Gravatar                                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * What Gravatar serves when an address has no image. `404` is here so callers
+ * can detect absence by status instead of receiving a generated face they then
+ * have to recognise as a placeholder.
+ */
+export const GRAVATAR_DEFAULTS = [
+    "404",
+    "mp",
+    "identicon",
+    "monsterid",
+    "wavatar",
+    "retro",
+    "robohash",
+    "blank",
+];
+export const GRAVATAR_RATINGS = ["g", "pg", "r", "x"];
+/** Gravatar's own ceiling. Larger values are refused rather than clamped. */
+export const GRAVATAR_AVATAR_MAX_SIZE = 2048;
+/* -------------------------------------------------------------------------- */
+/* Spam                                                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * Akismet's recognised content types. The vendor is not in the name of
+ * anything an author touches — `ctx.spam` outlives whichever service answers
+ * it — but the vocabulary is Akismet's because the classifier is trained on
+ * it, and inventing synonyms would only lose signal.
+ */
+export const SPAM_CONTENT_TYPES = [
+    "comment",
+    "reply",
+    "forum-post",
+    "contact-form",
+    "signup",
+    "message",
+];
+/* -------------------------------------------------------------------------- */
+/* Upstreams                                                                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * The hosts a broker may reach on a tenant's behalf are deliberately NOT listed
+ * here. That table lives in `stattic-runtime-core`'s egress policy, where it is
+ * generated into both the runtime's PHP constants and the Rust broker, so one
+ * declaration is enforced at both places a connection is actually made. A copy
+ * in this file would be a third statement of the same fact that nothing checks.
+ *
+ * The `gravatar.com` in the avatar URL below is not that table: it is a public
+ * URL handed to a browser, not an egress target.
+ */
+/* -------------------------------------------------------------------------- */
+/* The shared client                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * The client both runtimes inject, as source.
+ *
+ * It is a string rather than a module because neither runtime can import from
+ * npm at the point it needs this: Zero compiles a capsule to QuickJS bytecode
+ * with a generated prelude, and the Functions host injects modules into a
+ * tenant isolate it does not build. Shipping one source to both is what makes
+ * "the same API" a fact about the code rather than a promise in a doc.
+ *
+ * It closes over nothing of ours. The host defines `call(service, operation,
+ * payload)` and everything else — normalization, the pure avatar URL, the
+ * shapes returned to tenant code — is here, identical on both tiers.
+ *
+ * The SHA-256 is hand-rolled for the same reason: QuickJS has no WebCrypto,
+ * and Cloudflare's `crypto.subtle` is async, which would force `avatarUrl` to
+ * return a promise on one tier and a string on the other. A synchronous
+ * implementation is the only way the signature can be identical.
+ */
+export const RUNTIME_SERVICE_CLIENT_SOURCE = String.raw `
+const SERVICE_DEFAULTS = ${JSON.stringify(GRAVATAR_DEFAULTS)};
+const SERVICE_RATINGS = ${JSON.stringify(GRAVATAR_RATINGS)};
+const SPAM_TYPES = ${JSON.stringify(SPAM_CONTENT_TYPES)};
+const GRAVATAR_MAX_SIZE = ${GRAVATAR_AVATAR_MAX_SIZE};
+
+class ServiceError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "SpacefastServiceError";
+    this.code = code;
+  }
+}
+
+function invalid(message) {
+  return new ServiceError("service_payload_invalid", message);
+}
+
+// UTF-8 by hand: TextEncoder is not guaranteed in QuickJS, and the digest below
+// must agree byte for byte with the one the other tier computes.
+function utf8Bytes(value) {
+  const bytes = [];
+  for (let index = 0; index < value.length; index++) {
+    let point = value.charCodeAt(index);
+    if (point >= 0xd800 && point <= 0xdbff && index + 1 < value.length) {
+      const low = value.charCodeAt(index + 1);
+      if (low >= 0xdc00 && low <= 0xdfff) {
+        point = ((point - 0xd800) << 10) + (low - 0xdc00) + 0x10000;
+        index++;
+      }
+    }
+    if (point < 0x80) {
+      bytes.push(point);
+    } else if (point < 0x800) {
+      bytes.push(0xc0 | (point >> 6), 0x80 | (point & 0x3f));
+    } else if (point < 0x10000) {
+      bytes.push(0xe0 | (point >> 12), 0x80 | ((point >> 6) & 0x3f), 0x80 | (point & 0x3f));
+    } else {
+      bytes.push(
+        0xf0 | (point >> 18),
+        0x80 | ((point >> 12) & 0x3f),
+        0x80 | ((point >> 6) & 0x3f),
+        0x80 | (point & 0x3f),
+      );
+    }
+  }
+  return bytes;
+}
+
+const SHA256_K = [
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+
+function sha256Hex(value) {
+  const bytes = utf8Bytes(value);
+  const bitLength = bytes.length * 8;
+  bytes.push(0x80);
+  while (bytes.length % 64 !== 56) bytes.push(0);
+  // Length is 64-bit big-endian; inputs here are addresses, so the high word is
+  // always zero and is written as such rather than computed.
+  bytes.push(0, 0, 0, 0);
+  bytes.push((bitLength >>> 24) & 0xff, (bitLength >>> 16) & 0xff, (bitLength >>> 8) & 0xff, bitLength & 0xff);
+
+  const hash = [
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ];
+  const words = new Array(64);
+
+  for (let offset = 0; offset < bytes.length; offset += 64) {
+    for (let index = 0; index < 16; index++) {
+      const at = offset + index * 4;
+      words[index] =
+        ((bytes[at] << 24) | (bytes[at + 1] << 16) | (bytes[at + 2] << 8) | bytes[at + 3]) >>> 0;
+    }
+    for (let index = 16; index < 64; index++) {
+      const a = words[index - 15];
+      const b = words[index - 2];
+      const s0 = ((a >>> 7) | (a << 25)) ^ ((a >>> 18) | (a << 14)) ^ (a >>> 3);
+      const s1 = ((b >>> 17) | (b << 15)) ^ ((b >>> 19) | (b << 13)) ^ (b >>> 10);
+      words[index] = (words[index - 16] + s0 + words[index - 7] + s1) >>> 0;
+    }
+
+    let [a, b, c, d, e, f, g, h] = hash;
+    for (let index = 0; index < 64; index++) {
+      const s1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+      const ch = (e & f) ^ (~e & g);
+      const temp1 = (h + s1 + ch + SHA256_K[index] + words[index]) >>> 0;
+      const s0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const temp2 = (s0 + maj) >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = (d + temp1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (temp1 + temp2) >>> 0;
+    }
+    hash[0] = (hash[0] + a) >>> 0;
+    hash[1] = (hash[1] + b) >>> 0;
+    hash[2] = (hash[2] + c) >>> 0;
+    hash[3] = (hash[3] + d) >>> 0;
+    hash[4] = (hash[4] + e) >>> 0;
+    hash[5] = (hash[5] + f) >>> 0;
+    hash[6] = (hash[6] + g) >>> 0;
+    hash[7] = (hash[7] + h) >>> 0;
+  }
+
+  let hex = "";
+  for (const word of hash) {
+    hex += ("00000000" + (word >>> 0).toString(16)).slice(-8);
+  }
+  return hex;
+}
+
+// Gravatar's own identifier rule. Trim and lower-case only: it deliberately
+// does not strip dots or plus-tags, because two addresses that differ there are
+// two accounts as far as Gravatar is concerned.
+function gravatarHash(email) {
+  if (typeof email !== "string" || email.trim() === "") {
+    throw invalid("An email address is required.");
+  }
+  return sha256Hex(email.trim().toLowerCase());
+}
+
+function makeGravatar(call) {
+  return Object.freeze({
+    avatarUrl(email, options) {
+      const hash = gravatarHash(email);
+      const settings = options && typeof options === "object" ? options : {};
+      const query = [];
+      if (settings.size !== undefined) {
+        const size = Number(settings.size);
+        if (!Number.isInteger(size) || size < 1 || size > GRAVATAR_MAX_SIZE) {
+          throw invalid("Avatar size must be an integer between 1 and " + GRAVATAR_MAX_SIZE + ".");
+        }
+        query.push("s=" + size);
+      }
+      if (settings.default !== undefined) {
+        if (!SERVICE_DEFAULTS.includes(settings.default)) {
+          throw invalid("Avatar default must be one of: " + SERVICE_DEFAULTS.join(", ") + ".");
+        }
+        query.push("d=" + encodeURIComponent(settings.default));
+      }
+      if (settings.rating !== undefined) {
+        if (!SERVICE_RATINGS.includes(settings.rating)) {
+          throw invalid("Avatar rating must be one of: " + SERVICE_RATINGS.join(", ") + ".");
+        }
+        query.push("r=" + settings.rating);
+      }
+      if (settings.forceDefault === true) {
+        query.push("f=y");
+      }
+      return (
+        "https://gravatar.com/avatar/" + hash + (query.length > 0 ? "?" + query.join("&") : "")
+      );
+    },
+    async profile(email) {
+      return call("gravatar", "profile", { hash: gravatarHash(email) });
+    },
+  });
+}
+
+function spamPayload(submission) {
+  if (!submission || typeof submission !== "object") {
+    throw invalid("A submission object is required.");
+  }
+  if (typeof submission.content !== "string" || submission.content === "") {
+    throw invalid("Submission content is required.");
+  }
+  if (typeof submission.userIp !== "string" || submission.userIp.trim() === "") {
+    throw invalid("Submission userIp is required: a verdict without it is unreliable.");
+  }
+  if (submission.type !== undefined && !SPAM_TYPES.includes(submission.type)) {
+    throw invalid("Submission type must be one of: " + SPAM_TYPES.join(", ") + ".");
+  }
+  if (submission.authorRole !== undefined && submission.authorRole !== "administrator") {
+    throw invalid('Submission authorRole may only be "administrator".');
+  }
+  const payload = {
+    content: submission.content,
+    userIp: submission.userIp.trim(),
+    type: submission.type || "comment",
+  };
+  for (const field of [
+    "userAgent",
+    "referrer",
+    "permalink",
+    "authorName",
+    "authorEmail",
+    "authorUrl",
+    "authorRole",
+    "createdAt",
+  ]) {
+    if (typeof submission[field] === "string" && submission[field] !== "") {
+      payload[field] = submission[field];
+    }
+  }
+  if (Array.isArray(submission.languages) && submission.languages.length > 0) {
+    payload.languages = submission.languages.filter((entry) => typeof entry === "string");
+  }
+  return payload;
+}
+
+function requestSpamPayload(submission, requestContext) {
+  const userIp =
+    requestContext && typeof requestContext.userIp === "string"
+      ? requestContext.userIp.trim()
+      : "";
+  if (userIp === "") {
+    throw new ServiceError(
+      "service_context_unavailable",
+      "The runtime did not receive a trusted visitor IP for this spam check.",
+    );
+  }
+  // Rebuild the network fields from host-owned context even when untyped
+  // JavaScript smuggles same-named properties into the author submission.
+  const payload = spamPayload({
+    ...submission,
+    userIp,
+    userAgent: undefined,
+    referrer: undefined,
+    permalink: undefined,
+  });
+  for (const field of ["userAgent", "referrer", "permalink"]) {
+    if (typeof requestContext[field] === "string" && requestContext[field] !== "") {
+      payload[field] = requestContext[field];
+    }
+  }
+  return payload;
+}
+
+function makeSpam(call, requestContext) {
+  return Object.freeze({
+    async check(submission) {
+      const payload =
+        requestContext === undefined
+          ? spamPayload(submission)
+          : requestSpamPayload(submission, requestContext);
+      const result = await call("spam", "check", payload);
+      return Object.freeze({ spam: result.spam === true, discard: result.discard === true });
+    },
+    async reportSpam(submission) {
+      await call("spam", "report_spam", spamPayload(submission));
+    },
+    async reportHam(submission) {
+      await call("spam", "report_ham", spamPayload(submission));
+    },
+  });
+}
+
+function emailAddress(value, field) {
+  if (typeof value === "string") {
+    if (value.trim() === "") throw invalid(field + " must not be empty.");
+    return { email: value.trim() };
+  }
+  if (value && typeof value === "object" && typeof value.email === "string" && value.email.trim() !== "") {
+    const address = { email: value.email.trim() };
+    if (typeof value.name === "string" && value.name !== "") address.name = value.name;
+    return address;
+  }
+  throw invalid(field + " must be an address or an { email, name } object.");
+}
+
+function emailAddressList(value, field) {
+  const entries = Array.isArray(value) ? value : [value];
+  if (entries.length === 0) throw invalid(field + " must name at least one recipient.");
+  return entries.map((entry) => emailAddress(entry, field));
+}
+
+function emailPayload(message) {
+  if (!message || typeof message !== "object") {
+    throw invalid("A message object is required.");
+  }
+  if (typeof message.subject !== "string" || message.subject === "") {
+    throw invalid("Message subject is required.");
+  }
+  const hasText = typeof message.text === "string" && message.text !== "";
+  const hasHtml = typeof message.html === "string" && message.html !== "";
+  if (!hasText && !hasHtml) {
+    throw invalid("Message must carry text, html, or both.");
+  }
+  const payload = {
+    from: emailAddress(message.from, "from"),
+    to: emailAddressList(message.to, "to"),
+    subject: message.subject,
+  };
+  if (hasText) payload.text = message.text;
+  if (hasHtml) payload.html = message.html;
+  if (message.cc !== undefined) payload.cc = emailAddressList(message.cc, "cc");
+  if (message.bcc !== undefined) payload.bcc = emailAddressList(message.bcc, "bcc");
+  if (message.replyTo !== undefined) payload.replyTo = emailAddress(message.replyTo, "replyTo");
+  if (message.headers !== undefined) {
+    if (!message.headers || typeof message.headers !== "object") {
+      throw invalid("Message headers must be an object.");
+    }
+    const headers = {};
+    for (const name of Object.keys(message.headers)) {
+      const value = message.headers[name];
+      if (typeof value !== "string") throw invalid("Header " + name + " must be a string.");
+      // Refused here rather than at the broker so the author sees the field
+      // name they wrote. The broker refuses again — this is convenience, not
+      // the boundary.
+      if (/[^\x21-\x39\x3b-\x7e]/.test(name)) {
+        throw invalid("Header " + name + " is not a valid header name.");
+      }
+      if (/[\r\n\x00]/.test(value)) {
+        throw invalid("Header " + name + " must not contain line breaks or NUL.");
+      }
+      headers[name] = value;
+    }
+    payload.headers = headers;
+  }
+  return payload;
+}
+
+function makeEmail(call) {
+  return Object.freeze({
+    async send(message) {
+      const result = await call("email", "send", emailPayload(message));
+      return Object.freeze({ messageId: result.messageId });
+    },
+  });
+}
+
+function makeRuntimeServices(call, requestContext) {
+  return {
+    gravatar: makeGravatar(call),
+    spam: makeSpam(call, requestContext),
+    email: makeEmail(call),
+  };
+}
+`;

package/dist/contracts/runtime-storage.d.ts

@@ -1,79 +1,70 @@
 import { z } from "zod";
-export declare const runtimeStorageVisibilitySchema: z.ZodEnum<{
-    public: "public";
-    private: "private";
-}>;
-export type RuntimeStorageVisibility = z.infer<typeof runtimeStorageVisibilitySchema>;
+/** Objects are addressed by a bare 128-bit random id — there is no key and no visibility. */
 export declare const runtimeStorageObjectIdSchema: z.ZodString;
-export declare const runtimeStorageObjectKeySchema: z.ZodString;
+/** The runtime-scoped, revocable read key that makes a `/__stattic/u/<id>` URL readable. */
+export declare const runtimeStorageReadKeySchema: z.ZodString;
+export type UploadedObject = {
+    id: string;
+    contentType: string;
+    size: number;
+    url: string;
+};
+export type StorageClient = {
+    upload(file: Blob): Promise<UploadedObject>;
+    get(id: string): Promise<Response | null>;
+    delete(id: string): Promise<void>;
+};
 export declare const runtimeStorageListQuerySchema: z.ZodObject<{
     cursor: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
-    visibility: z.ZodOptional<z.ZodEnum<{
-        public: "public";
-        private: "private";
-    }>>;
 }, z.core.$strict>;
 export declare const runtimeStorageObjectSchema: z.ZodObject<{
-    key: z.ZodString;
-    visibility: z.ZodEnum<{
-        public: "public";
-        private: "private";
-    }>;
+    id: z.ZodString;
     contentType: z.ZodString;
     createdAt: z.ZodString;
     size: z.ZodNumber;
     uploaderId: z.ZodString;
     sha256: z.ZodString;
+    url: z.ZodString;
 }, z.core.$strict>;
 export type RuntimeStorageObject = z.infer<typeof runtimeStorageObjectSchema>;
 export declare const runtimeStorageListResponseSchema: z.ZodObject<{
     objects: z.ZodArray<z.ZodObject<{
-        key: z.ZodString;
-        visibility: z.ZodEnum<{
-            public: "public";
-            private: "private";
-        }>;
+        id: z.ZodString;
         contentType: z.ZodString;
         createdAt: z.ZodString;
         size: z.ZodNumber;
         uploaderId: z.ZodString;
         sha256: z.ZodString;
+        url: z.ZodString;
     }, z.core.$strict>>;
     cursor: z.ZodNullable<z.ZodString>;
     hasMore: z.ZodBoolean;
-    usedBytes: z.ZodNumber;
-    quotaBytes: z.ZodNumber;
 }, z.core.$strict>;
 export type RuntimeStorageListResponse = z.infer<typeof runtimeStorageListResponseSchema>;
 export declare const runtimeStorageListPublicResponseSchema: z.ZodObject<{
     data: z.ZodObject<{
         objects: z.ZodArray<z.ZodObject<{
-            key: z.ZodString;
-            visibility: z.ZodEnum<{
-                public: "public";
-                private: "private";
-            }>;
+            id: z.ZodString;
             contentType: z.ZodString;
             createdAt: z.ZodString;
             size: z.ZodNumber;
             uploaderId: z.ZodString;
             sha256: z.ZodString;
+            url: z.ZodString;
         }, z.core.$strict>>;
         cursor: z.ZodNullable<z.ZodString>;
         hasMore: z.ZodBoolean;
-        usedBytes: z.ZodNumber;
-        quotaBytes: z.ZodNumber;
     }, z.core.$strict>;
 }, z.core.$strip>;
 export declare const runtimeStorageDeleteResponseSchema: z.ZodObject<{
-    key: z.ZodString;
+    id: z.ZodString;
     deleted: z.ZodBoolean;
 }, z.core.$strict>;
 export type RuntimeStorageDeleteResponse = z.infer<typeof runtimeStorageDeleteResponseSchema>;
 export declare const runtimeStorageDeletePublicResponseSchema: z.ZodObject<{
     data: z.ZodObject<{
-        key: z.ZodString;
+        id: z.ZodString;
         deleted: z.ZodBoolean;
     }, z.core.$strict>;
     operation: z.ZodNullable<z.ZodObject<{
@@ -99,8 +90,8 @@ export declare const runtimeStorageDeletePublicResponseSchema: z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -118,3 +109,25 @@ export declare const runtimeStorageDeletePublicResponseSchema: z.ZodObject<{
         finishedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+export declare const runtimeStorageReadKeyResponseSchema: z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$strict>;
+export type RuntimeStorageReadKeyResponse = z.infer<typeof runtimeStorageReadKeyResponseSchema>;
+export declare const runtimeStorageReadKeyRotateResponseSchema: z.ZodObject<{
+    key: z.ZodString;
+    rotatedAt: z.ZodString;
+    purge: z.ZodObject<{
+        status: z.ZodEnum<{
+            failed: "failed";
+            pending: "pending";
+            ok: "ok";
+        }>;
+        mode: z.ZodEnum<{
+            domain: "domain";
+            none: "none";
+            urls: "urls";
+        }>;
+        urls: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type RuntimeStorageReadKeyRotateResponse = z.infer<typeof runtimeStorageReadKeyRotateResponseSchema>;

package/dist/contracts/runtime-storage.js

@@ -1,24 +1,27 @@
 import { z } from "zod";
 import { dataEnvelope, mutationEnvelope } from "./common.js";
-export const runtimeStorageVisibilitySchema = z.enum(["public", "private"]);
+/** Objects are addressed by a bare 128-bit random id — there is no key and no visibility. */
 export const runtimeStorageObjectIdSchema = z.string().regex(/^[a-f0-9]{32}$/);
-export const runtimeStorageObjectKeySchema = z.string().regex(/^(public|private)\/[a-f0-9]{32}$/);
+/** The runtime-scoped, revocable read key that makes a `/__stattic/u/<id>` URL readable. */
+export const runtimeStorageReadKeySchema = z.string().regex(/^[a-f0-9]{32}$/);
 export const runtimeStorageListQuerySchema = z
     .object({
     cursor: z.string().min(1).max(2_048).optional(),
     limit: z.coerce.number().int().min(1).max(100).default(50),
-    visibility: runtimeStorageVisibilitySchema.optional(),
 })
     .strict();
 export const runtimeStorageObjectSchema = z
     .object({
-    key: runtimeStorageObjectKeySchema,
-    visibility: runtimeStorageVisibilitySchema,
+    id: runtimeStorageObjectIdSchema,
     contentType: z.string().min(1).max(255),
     createdAt: z.string().datetime(),
     size: z.number().int().nonnegative(),
     uploaderId: z.string().min(1).max(255),
     sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    // Path-relative and composed from the read key that was current at response
+    // time: `/__stattic/u/<id>?k=<key>`. The caller absolutizes it against
+    // whichever of the space's hostnames it is presenting.
+    url: z.string().min(1),
 })
     .strict();
 export const runtimeStorageListResponseSchema = z
@@ -26,15 +29,34 @@ export const runtimeStorageListResponseSchema = z
     objects: z.array(runtimeStorageObjectSchema),
     cursor: z.string().nullable(),
     hasMore: z.boolean(),
-    usedBytes: z.number().int().nonnegative(),
-    quotaBytes: z.number().int().positive(),
 })
     .strict();
 export const runtimeStorageListPublicResponseSchema = dataEnvelope(runtimeStorageListResponseSchema);
 export const runtimeStorageDeleteResponseSchema = z
     .object({
-    key: runtimeStorageObjectKeySchema,
+    id: runtimeStorageObjectIdSchema,
     deleted: z.boolean(),
 })
     .strict();
 export const runtimeStorageDeletePublicResponseSchema = mutationEnvelope(runtimeStorageDeleteResponseSchema);
+export const runtimeStorageReadKeyResponseSchema = z
+    .object({ key: runtimeStorageReadKeySchema })
+    .strict();
+// Rotation is the emergency lever: every URL minted under the old key answers
+// 404 afterwards, so the runtime purges every hostname on the box and reports
+// how that purge landed.
+export const runtimeStorageReadKeyRotateResponseSchema = z
+    .object({
+    key: runtimeStorageReadKeySchema,
+    rotatedAt: z.string().datetime({ offset: true }),
+    // `none` is the receipt for a runtime that serves no hostname yet, so there
+    // was nothing to purge.
+    purge: z
+        .object({
+        status: z.enum(["ok", "failed", "pending"]),
+        mode: z.enum(["urls", "domain", "none"]),
+        urls: z.number().int().nonnegative().optional(),
+    })
+        .strict(),
+})
+    .strict();