@moloodev/editor-store 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@moloodev/editor-store",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./write": "./src/write.ts",
+    "./blob": "./src/blob.ts",
+    "./private": "./src/private.ts",
+    "./upload": "./src/upload.ts"
+  },
+  "dependencies": {
+    "@vercel/blob": "^2.8.0",
+    "zod": "^4.5.4",
+    "@moloodev/platform": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2",
+    "@moloodev/typescript-config": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test 'src/**/*.test.ts'"
+  }
 }

package/src/blob.ts

@@ -0,0 +1,19 @@
+import { put } from "@vercel/blob";
+import type { ObjectWriter } from "./pointer";
+
+// Explicit token so writes never use the platform media store.
+export function blobWriter(token: string): ObjectWriter {
+  if (token.length === 0) throw new Error("public store token is empty");
+  return {
+    async write(pathname, body, meta) {
+      await put(pathname, Buffer.from(body), {
+        access: "public",
+        token,
+        addRandomSuffix: false,
+        allowOverwrite: true,
+        contentType: meta.contentType,
+        cacheControlMaxAge: meta.maxAge,
+      });
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export {
+  ARTIFACT_MAX_AGE,
+  cacheControl,
+  encodePointer,
+  isDnsId,
+  parsePointer,
+  pointerFor,
+  pointerPath,
+  SCRIPT_TYPE,
+  scriptPath,
+  type ObjectReader,
+  type ObjectWriter,
+  type WriteMeta,
+} from "./pointer";
+export { publicReader } from "./read";

package/src/pointer.ts

@@ -0,0 +1,105 @@
+import { parseNetwork } from "@moloodev/platform/network";
+import { z } from "zod";
+
+const DNS_ID = /^[0-9a-z]{24}$/;
+const SCRIPT_PATH = /^revisions\/[0-9a-z]{24}\/[0-9a-z]{24}\/editor\.js$/;
+const POINTER_BYTES_MAX = 4096;
+
+export const ARTIFACT_MAX_AGE = 31_536_000;
+export const POINTER_MAX_AGE = 60;
+export const SCRIPT_TYPE = "text/javascript; charset=utf-8";
+export const POINTER_TYPE = "application/json; charset=utf-8";
+
+const idSchema = z.string().regex(DNS_ID);
+const pointerSchema = z.strictObject({
+  revisionId: idSchema,
+  network: z.array(z.string()),
+  paths: z.strictObject({
+    script: z.string().regex(SCRIPT_PATH),
+  }),
+});
+
+export type Pointer = z.infer<typeof pointerSchema>;
+
+type ObjectBody = {
+  readonly body: Uint8Array;
+  readonly contentType: string;
+};
+
+export type ObjectReader = {
+  read(pathname: string): Promise<ObjectBody | null>;
+};
+
+export type WriteMeta = {
+  readonly contentType: string;
+  readonly maxAge: number;
+  readonly immutable: boolean;
+};
+
+export type ObjectWriter = {
+  write(pathname: string, body: Uint8Array, meta: WriteMeta): Promise<void>;
+};
+
+export function isDnsId(value: string): boolean {
+  return DNS_ID.test(value);
+}
+
+export function isRevisionScript(pathname: string): boolean {
+  return SCRIPT_PATH.test(pathname);
+}
+
+export function cacheControl(meta: Pick<WriteMeta, "maxAge" | "immutable">): string {
+  const base = `public, max-age=${String(meta.maxAge)}`;
+  return meta.immutable ? `${base}, immutable` : base;
+}
+
+export function scriptPath(editorId: string, revisionId: string): string {
+  if (!isDnsId(editorId) || !isDnsId(revisionId)) throw new Error("invalid id");
+  return `revisions/${editorId}/${revisionId}/editor.js`;
+}
+
+export function pointerFor(
+  editorId: string,
+  revisionId: string,
+  network: readonly string[],
+): Pointer {
+  return {
+    revisionId,
+    network: [...network],
+    paths: { script: scriptPath(editorId, revisionId) },
+  };
+}
+
+export function pointerPath(editorId: string): string {
+  if (!isDnsId(editorId)) throw new Error("invalid id");
+  return `pointers/${editorId}.json`;
+}
+
+export function encodePointer(pointer: Pointer): Uint8Array {
+  return new TextEncoder().encode(JSON.stringify(pointer));
+}
+
+export function parsePointer(editorId: string, bytes: Uint8Array): Pointer | undefined {
+  if (!isDnsId(editorId) || bytes.byteLength > POINTER_BYTES_MAX) return undefined;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    return undefined;
+  }
+  const parsed = pointerSchema.safeParse(raw);
+  if (!parsed.success) return undefined;
+  let network: string[];
+  try {
+    network = parseNetwork(parsed.data.network);
+  } catch {
+    return undefined;
+  }
+  const expected = scriptPath(editorId, parsed.data.revisionId);
+  if (parsed.data.paths.script !== expected) return undefined;
+  return {
+    revisionId: parsed.data.revisionId,
+    network,
+    paths: { script: expected },
+  };
+}

package/src/private.ts

@@ -0,0 +1,102 @@
+import { BlobNotFoundError, del, get, put } from "@vercel/blob";
+import { isRevisionScript, type ObjectReader, type ObjectWriter } from "./pointer";
+
+type PrivatePut = (
+  pathname: string,
+  body: Buffer,
+  options: {
+    access: "private";
+    token: string;
+    addRandomSuffix: false;
+    allowOverwrite: true;
+    contentType: string;
+    cacheControlMaxAge: number;
+  },
+) => Promise<unknown>;
+
+// Separate token and access so a submission cannot land in the public store.
+export function privateWriter(token: string, putBlob?: PrivatePut): ObjectWriter {
+  if (token.length === 0) throw new Error("private store token is empty");
+  const writeBlob: PrivatePut =
+    putBlob ??
+    ((pathname, body, options) => put(pathname, body, options));
+  return {
+    async write(pathname, body, meta) {
+      await writeBlob(pathname, Buffer.from(body), {
+        access: "private",
+        token,
+        addRandomSuffix: false,
+        allowOverwrite: true,
+        contentType: meta.contentType,
+        cacheControlMaxAge: meta.maxAge,
+      });
+    },
+  };
+}
+
+type PrivateGetResult = {
+  statusCode: number;
+  stream: ReadableStream<Uint8Array> | null;
+  blob: { contentType: string | null };
+} | null;
+
+type PrivateGet = (
+  pathname: string,
+  options: { access: "private"; token: string; useCache: false },
+) => Promise<PrivateGetResult>;
+
+async function defaultGet(
+  pathname: string,
+  options: { access: "private"; token: string; useCache: false },
+): Promise<PrivateGetResult> {
+  return get(pathname, options);
+}
+
+export function privateReader(token: string, getBlob: PrivateGet = defaultGet): ObjectReader {
+  if (token.length === 0) throw new Error("private store token is empty");
+  return {
+    async read(pathname) {
+      if (!isRevisionScript(pathname)) return null;
+      let result: PrivateGetResult;
+      try {
+        result = await getBlob(pathname, {
+          access: "private",
+          token,
+          useCache: false,
+        });
+      } catch {
+        // The blob client puts the store URL on the error. Callers see a fixed message.
+        throw new Error("private store read failed");
+      }
+      if (!result || result.statusCode !== 200 || result.stream === null) return null;
+      return {
+        body: new Uint8Array(await new Response(result.stream).arrayBuffer()),
+        contentType: result.blob.contentType ?? "application/octet-stream",
+      };
+    },
+  };
+}
+
+export type PrivateDeleter = {
+  delete(pathname: string): Promise<void>;
+};
+
+type PrivateDel = (pathname: string, options: { token: string }) => Promise<void>;
+
+// Private token only. A purge must not be able to remove a public pointer.
+export function privateDeleter(token: string, delBlob?: PrivateDel): PrivateDeleter {
+  if (token.length === 0) throw new Error("private store token is empty");
+  const remove: PrivateDel = delBlob ?? ((pathname, options) => del(pathname, options));
+  return {
+    async delete(pathname) {
+      if (!isRevisionScript(pathname)) throw new Error("private store path refused");
+      try {
+        await remove(pathname, { token });
+      } catch (err) {
+        if (err instanceof BlobNotFoundError) return;
+        // The blob client puts the store URL on the error. Callers see a fixed message.
+        throw new Error("private store delete failed");
+      }
+    },
+  };
+}

package/src/read.ts

@@ -0,0 +1,54 @@
+import type { ObjectReader } from "./pointer";
+
+const OBJECT_PATH = /^pointers\/[0-9a-z]{24}\.json$|^revisions\/[0-9a-z]{24}\/[0-9a-z]{24}\/editor\.js$/;
+
+export function publicReader(baseUrl: string, fetchImpl: typeof fetch = fetch): ObjectReader {
+  const base = parseBase(baseUrl);
+  return {
+    async read(pathname) {
+      const url = objectUrl(base, pathname);
+      if (url === null) return null;
+      const response = await fetchImpl(url);
+      if (response.status === 404) {
+        await response.body?.cancel();
+        return null;
+      }
+      if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error("public store read failed");
+      }
+      return {
+        body: new Uint8Array(await response.arrayBuffer()),
+        contentType: response.headers.get("content-type") ?? "application/octet-stream",
+      };
+    },
+  };
+}
+
+function parseBase(baseUrl: string): URL {
+  let url: URL;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new Error("public store base url is invalid");
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.username !== "" ||
+    url.password !== "" ||
+    url.search !== "" ||
+    url.hash !== "" ||
+    (url.pathname !== "/" && url.pathname !== "")
+  ) {
+    throw new Error("public store base url is invalid");
+  }
+  url.pathname = "/";
+  return url;
+}
+
+function objectUrl(base: URL, pathname: string): URL | null {
+  if (!OBJECT_PATH.test(pathname)) return null;
+  const url = new URL(pathname, base);
+  if (url.origin !== base.origin || url.pathname !== `/${pathname}`) return null;
+  return url;
+}

package/src/upload.ts

@@ -0,0 +1,196 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { BlobNotFoundError, del, get } from "@vercel/blob";
+import {
+  generateClientTokenFromReadWriteToken,
+  getPayloadFromClientToken,
+  put,
+} from "@vercel/blob/client";
+import { isDnsId, type ObjectReader } from "./pointer";
+
+const UPLOAD_PATH = /^uploads\/[0-9a-z]{24}\/editor\.js$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+export const SCRIPT_UPLOAD_TYPE = "text/javascript";
+export const SCRIPT_UPLOAD_TTL_MS = 10 * 60 * 1000;
+
+type PrivateGetResult = {
+  statusCode: number;
+  stream: ReadableStream<Uint8Array> | null;
+  blob: { contentType: string | null };
+} | null;
+
+type PrivateGet = (
+  pathname: string,
+  options: { access: "private"; token: string; useCache: false },
+) => Promise<PrivateGetResult>;
+
+type PrivateDel = (pathname: string, options: { token: string }) => Promise<void>;
+
+type ClientPut = (
+  pathname: string,
+  body: Buffer,
+  options: {
+    access: "private";
+    token: string;
+    contentType: typeof SCRIPT_UPLOAD_TYPE;
+  },
+) => Promise<unknown>;
+
+type ScriptUploadFailure = "path" | "missing" | "size" | "digest" | "encoding";
+
+type LoadedScript =
+  | { ok: true; script: string }
+  | { ok: false; reason: ScriptUploadFailure };
+
+type ScriptUploadToken = {
+  pathname: string;
+  maximumBytes: number | undefined;
+  contentTypes: string[] | undefined;
+  addRandomSuffix: boolean | undefined;
+  allowOverwrite: boolean | undefined;
+  validUntil: number;
+};
+
+// Shared private intake. Builtin publish and an external submission both
+// check the bytes at this pathname before they write a revision.
+export function uploadPath(id: string): string {
+  if (!isDnsId(id)) throw new Error("invalid id");
+  return `uploads/${id}/editor.js`;
+}
+
+export function isUploadPath(pathname: string): boolean {
+  return UPLOAD_PATH.test(pathname);
+}
+
+export async function issueScriptUpload(input: {
+  storeToken: string;
+  pathname: string;
+  maximumBytes: number;
+  now?: number;
+}): Promise<string> {
+  if (input.storeToken.length === 0) throw new Error("private store token is empty");
+  if (!isUploadPath(input.pathname)) throw new Error("upload path refused");
+  const now = input.now ?? Date.now();
+  return generateClientTokenFromReadWriteToken({
+    token: input.storeToken,
+    pathname: input.pathname,
+    maximumSizeInBytes: input.maximumBytes,
+    allowedContentTypes: [SCRIPT_UPLOAD_TYPE],
+    addRandomSuffix: false,
+    allowOverwrite: false,
+    validUntil: now + SCRIPT_UPLOAD_TTL_MS,
+  });
+}
+
+export function readScriptUploadToken(clientToken: string): ScriptUploadToken {
+  const payload = getPayloadFromClientToken(clientToken);
+  const contentTypes = payload.allowedContentTypes;
+  return {
+    pathname: payload.pathname,
+    maximumBytes: payload.maximumSizeInBytes,
+    contentTypes: contentTypes === undefined ? undefined : [...contentTypes],
+    addRandomSuffix: payload.addRandomSuffix,
+    allowOverwrite: payload.allowOverwrite,
+    validUntil: payload.validUntil,
+  };
+}
+
+export async function putScriptUpload(
+  clientToken: string,
+  pathname: string,
+  body: Uint8Array,
+  putBlob?: ClientPut,
+): Promise<void> {
+  if (!clientToken.startsWith("vercel_blob_client_")) throw new Error("upload token refused");
+  if (!isUploadPath(pathname)) throw new Error("upload path refused");
+  const write = putBlob ?? defaultPut;
+  await write(pathname, Buffer.from(body), {
+    access: "private",
+    token: clientToken,
+    contentType: SCRIPT_UPLOAD_TYPE,
+  });
+}
+
+export function uploadReader(token: string, getBlob: PrivateGet = defaultGet): ObjectReader {
+  if (token.length === 0) throw new Error("private store token is empty");
+  return {
+    async read(pathname) {
+      if (!isUploadPath(pathname)) return null;
+      let result: PrivateGetResult;
+      try {
+        result = await getBlob(pathname, {
+          access: "private",
+          token,
+          useCache: false,
+        });
+      } catch {
+        throw new Error("private store read failed");
+      }
+      if (!result || result.statusCode !== 200 || result.stream === null) return null;
+      return {
+        body: new Uint8Array(await new Response(result.stream).arrayBuffer()),
+        contentType: result.blob.contentType ?? "application/octet-stream",
+      };
+    },
+  };
+}
+
+export async function loadScriptUpload(input: {
+  reader: ObjectReader;
+  pathname: string;
+  sha256: string;
+  maximumBytes: number;
+}): Promise<LoadedScript> {
+  if (!isUploadPath(input.pathname)) return { ok: false, reason: "path" };
+  if (!SHA256_HEX.test(input.sha256)) return { ok: false, reason: "digest" };
+  const object = await input.reader.read(input.pathname);
+  if (!object) return { ok: false, reason: "missing" };
+  if (object.body.byteLength === 0 || object.body.byteLength > input.maximumBytes) {
+    return { ok: false, reason: "size" };
+  }
+  const actual = createHash("sha256").update(object.body).digest();
+  const expected = Buffer.from(input.sha256, "hex");
+  if (actual.byteLength !== expected.byteLength || !timingSafeEqual(actual, expected)) {
+    return { ok: false, reason: "digest" };
+  }
+  try {
+    return { ok: true, script: new TextDecoder("utf-8", { fatal: true }).decode(object.body) };
+  } catch {
+    return { ok: false, reason: "encoding" };
+  }
+}
+
+export async function deleteScriptUpload(
+  token: string,
+  pathname: string,
+  delBlob?: PrivateDel,
+): Promise<void> {
+  if (token.length === 0) throw new Error("private store token is empty");
+  if (!isUploadPath(pathname)) throw new Error("upload path refused");
+  const remove: PrivateDel = delBlob ?? ((path, options) => del(path, options));
+  try {
+    await remove(pathname, { token });
+  } catch (err) {
+    if (err instanceof BlobNotFoundError) return;
+    throw new Error("private store delete failed");
+  }
+}
+
+function defaultPut(
+  pathname: string,
+  body: Buffer,
+  options: {
+    access: "private";
+    token: string;
+    contentType: typeof SCRIPT_UPLOAD_TYPE;
+  },
+): Promise<unknown> {
+  return put(pathname, body, options);
+}
+
+async function defaultGet(
+  pathname: string,
+  options: { access: "private"; token: string; useCache: false },
+): Promise<PrivateGetResult> {
+  return get(pathname, options);
+}

package/src/write.ts

@@ -0,0 +1,43 @@
+import { parseNetwork } from "@moloodev/platform/network";
+import {
+  ARTIFACT_MAX_AGE,
+  encodePointer,
+  POINTER_MAX_AGE,
+  POINTER_TYPE,
+  pointerFor,
+  pointerPath,
+  SCRIPT_TYPE,
+  type ObjectWriter,
+  type Pointer,
+} from "./pointer";
+
+export async function putRevision(
+  writer: ObjectWriter,
+  input: {
+    readonly editorId: string;
+    readonly revisionId: string;
+    readonly script: Uint8Array;
+    readonly network: readonly string[];
+  },
+): Promise<Pointer> {
+  const pointer = pointerFor(
+    input.editorId,
+    input.revisionId,
+    parseNetwork(input.network),
+  );
+  // Copy first. The pointer is written only after that write resolves, so a
+  // failed or partial copy cannot leave the pointer aimed at a short script.
+  // A later retry overwrites both and converges.
+  const script = new Uint8Array(input.script);
+  await writer.write(pointer.paths.script, script, {
+    contentType: SCRIPT_TYPE,
+    maxAge: ARTIFACT_MAX_AGE,
+    immutable: true,
+  });
+  await writer.write(pointerPath(input.editorId), encodePointer(pointer), {
+    contentType: POINTER_TYPE,
+    maxAge: POINTER_MAX_AGE,
+    immutable: false,
+  });
+  return pointer;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.