@panorama-industries/effect-vercel-blob 0.0.0 → 0.2.0

package/src/internal/presign.ts

@@ -0,0 +1,477 @@
+import { DateTime, Effect, Option, Redacted, Result, Schema } from "effect";
+import { Base64Url } from "effect/encoding";
+
+import type { BlobAccess, DelegationOperation, StoreId } from "../contracts/blob-domain.ts";
+import type { PresignOptions, SigningToken } from "../contracts/blob-signed-urls.ts";
+
+import { PresignedUrlPayload } from "../contracts/blob-domain.ts";
+import { BlobPresignFailed } from "../contracts/blob-errors.ts";
+import { storeIdFromDelegationToken } from "./store-id.ts";
+import { blobUrl, isUrl } from "./urls.ts";
+
+/*
+ * Presigned URLs, ported from the SDK's `signed-token.ts` (`presign`, `presignUrl`,
+ * `canonicalString`) and `presign-query-params.ts`. The canonical string and query entries must
+ * stay aligned with the Blob API and proxy that verify them.
+ */
+
+/** Signed expiry of one URL, when earlier than the delegation's. */
+export const presignQueryValidUntil = "vercel-blob-valid-until";
+/** Largest upload a presigned `put` accepts. */
+export const presignQueryMaximumSize = "vercel-blob-maximum-size-in-bytes";
+/** Media types a presigned `put` accepts, sorted and comma-separated. */
+export const presignQueryAllowedContentTypes = "vercel-blob-allowed-content-types";
+/** `true`/`false`. */
+export const presignQueryAddRandomSuffix = "vercel-blob-add-random-suffix";
+/** `true`/`false`. */
+export const presignQueryAllowOverwrite = "vercel-blob-allow-overwrite";
+/** Seconds. */
+export const presignQueryCacheControlMaxAge = "vercel-blob-cache-control-max-age";
+/** ETag a presigned `put` or `delete` requires. */
+export const presignQueryIfMatch = "vercel-blob-if-match";
+/** Where the store sends `blob.upload-completed`. */
+export const presignQueryCallbackUrl = "vercel-blob-callback-url";
+/** `tokenPayload` of the upload-completed callback. */
+export const presignQueryCallbackTokenPayload = "vercel-blob-callback-token-payload";
+
+/** Every signed constraint, in UTF-8 order, as the SDK's `PRESIGN_CANONICAL_QUERY_KEYS`. */
+export const presignCanonicalQueryKeys = [
+  presignQueryAddRandomSuffix,
+  presignQueryAllowOverwrite,
+  presignQueryAllowedContentTypes,
+  presignQueryCacheControlMaxAge,
+  presignQueryCallbackTokenPayload,
+  presignQueryCallbackUrl,
+  presignQueryIfMatch,
+  presignQueryMaximumSize,
+  presignQueryValidUntil,
+] as const;
+
+/** Longest `onUploadCompleted.callbackUrl` a presigned URL may carry. */
+export const maximumPresignCallbackUrlLength = 4096;
+
+/** Longest `onUploadCompleted.tokenPayload` a presigned URL may carry. */
+export const maximumPresignCallbackTokenPayloadLength = 8192;
+
+/** Largest `cacheControlMaxAge` a presigned URL may carry: one year, in seconds. */
+export const maximumPresignCacheControlMaxAge = 365 * 24 * 60 * 60;
+
+const maximumIfMatchLength = 256;
+
+// oxlint-disable-next-line no-control-regex -- control characters are what it rejects
+const ifMatchControlCharacters = /[\x00-\x1f\x7f]/;
+
+const label = "presignUrl";
+
+/** One signed query parameter. */
+export type PresignQueryEntry = readonly [key: string, value: string];
+
+/** What a delegation token's payload constrains, as the SDK reads it for presigning. */
+export const DelegationScope = Schema.Struct({
+  pathname: Schema.optionalKey(Schema.String),
+  operations: Schema.optionalKey(Schema.Array(Schema.String)),
+  /** Epoch milliseconds. */
+  validUntil: Schema.optionalKey(Schema.Number),
+  maximumSizeInBytes: Schema.optionalKey(Schema.Number),
+  allowedContentTypes: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+
+/** What a delegation token's payload constrains. */
+export type DelegationScope = typeof DelegationScope.Type;
+
+const decodeScope = Schema.decodeUnknownOption(Schema.fromJsonString(DelegationScope));
+
+/**
+ * Read the scope of a delegation token: the base64url JSON before its first `.`. Standard base64
+ * characters and padding are accepted, as the SDK's decoder accepts them.
+ *
+ * @returns None when the token has no `.` or the segment is not base64url JSON of an object.
+ */
+export const delegationScope = (delegationToken: string): Option.Option<DelegationScope> => {
+  const dot = delegationToken.indexOf(".");
+  if (dot < 0) {
+    return Option.none();
+  }
+  const segment = delegationToken
+    .slice(0, dot)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return Result.getSuccess(Base64Url.decodeString(segment)).pipe(Option.flatMap(decodeScope));
+};
+
+const utf8 = new TextEncoder();
+
+/** Bytewise UTF-8 order, as the SDK's `compareUtf8` (Go string order). */
+const compareUtf8 = (a: string, b: string): number => {
+  const left = utf8.encode(a);
+  const right = utf8.encode(b);
+  const length = Math.min(left.length, right.length);
+  for (let i = 0; i < length; i++) {
+    const difference = left[i]! - right[i]!;
+    if (difference !== 0) {
+      return difference;
+    }
+  }
+  return left.length - right.length;
+};
+
+/**
+ * The string a presigned URL's signature covers, as the SDK's `canonicalString`: `operation=…`,
+ * `pathname=…` and every non-empty signed entry as `key=value`, sorted bytewise and joined by `\n`.
+ */
+export const canonicalString = (
+  pathname: string,
+  entries: ReadonlyArray<PresignQueryEntry>,
+  operation: DelegationOperation,
+): string => {
+  const lines = [`operation=${operation}`, `pathname=${pathname}`];
+  for (const key of presignCanonicalQueryKeys) {
+    const value = entries.find(([entry]) => entry === key)?.[1];
+    if (value) {
+      lines.push(`${key}=${value}`);
+    }
+  }
+  return lines.sort(compareUtf8).join("\n");
+};
+
+/** HMAC-SHA256 of `data` keyed by `secret` (both UTF-8), as unpadded base64url. */
+export const hmacSha256Base64Url = Effect.fnUntraced(function* (secret: string, data: string) {
+  const key = yield* Effect.promise(() =>
+    globalThis.crypto.subtle.importKey(
+      "raw",
+      utf8.encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"],
+    ),
+  );
+  const signature = yield* Effect.promise(() =>
+    globalThis.crypto.subtle.sign("HMAC", key, utf8.encode(data)),
+  );
+  return Base64Url.encode(new Uint8Array(signature));
+});
+
+const failed = (message: string) => Effect.fail(new BlobPresignFailed({ message }));
+
+/** Signed constraints of one presigned URL, in epoch milliseconds and seconds as on the wire. */
+export interface PresignUrlConstraints {
+  readonly validUntil?: number | undefined;
+  readonly allowedContentTypes?: ReadonlyArray<string> | undefined;
+  readonly maximumSizeInBytes?: number | undefined;
+  readonly addRandomSuffix?: boolean | undefined;
+  readonly allowOverwrite?: boolean | undefined;
+  readonly cacheControlMaxAge?: number | undefined;
+  readonly ifMatch?: string | undefined;
+  readonly onUploadCompleted?:
+    | { readonly callbackUrl: string; readonly tokenPayload?: string | null | undefined }
+    | undefined;
+}
+
+/** What the delegation allows, as the SDK's `DelegationScopeForPresign`. */
+export interface PresignDelegation {
+  /** Epoch milliseconds; none when the delegation states no expiry. */
+  readonly validUntil: number | undefined;
+  readonly maximumSizeInBytes?: number | undefined;
+  readonly allowedContentTypes?: ReadonlyArray<string> | undefined;
+}
+
+const contentTypeAllowed = (contentType: string, allowed: ReadonlyArray<string>): boolean => {
+  const [type] = contentType.split("/");
+  return allowed.includes(contentType) || (type ? allowed.includes(`${type}/*`) : false);
+};
+
+/**
+ * The URL's expiry, as the SDK's `resolvePresignUrlValidUntilMs`: the requested one capped to the
+ * delegation's, which must be after `now`. A delegation without an expiry and no requested one
+ * yields `NaN`, as in the SDK, which then signs no expiry.
+ */
+const resolveValidUntil = (
+  delegationValidUntil: number | undefined,
+  requested: number | undefined,
+  now: number,
+) => {
+  let until = Math.trunc(requested ?? delegationValidUntil ?? Number.NaN);
+  if (delegationValidUntil !== undefined && Number.isFinite(delegationValidUntil)) {
+    until = Math.min(until, Math.trunc(delegationValidUntil));
+  }
+  if (until <= now) {
+    return failed(
+      `${label}: resolved URL expiry is not after the current time; issue a new delegation token or pass a later validUntil.`,
+    );
+  }
+  return Effect.succeed(until);
+};
+
+const validateUploadConstraints = Effect.fnUntraced(function* (
+  options: PresignUrlConstraints,
+  delegation: PresignDelegation,
+) {
+  const allowed = delegation.allowedContentTypes;
+  if (options.allowedContentTypes?.length && allowed?.length) {
+    for (const contentType of options.allowedContentTypes) {
+      if (!contentTypeAllowed(contentType, allowed)) {
+        return yield* failed(
+          `${label}: allowedContentTypes entry "${contentType}" is not permitted by the delegation token.`,
+        );
+      }
+    }
+  }
+  if (
+    options.maximumSizeInBytes !== undefined &&
+    delegation.maximumSizeInBytes !== undefined &&
+    options.maximumSizeInBytes > delegation.maximumSizeInBytes
+  ) {
+    return yield* failed(
+      `${label}: maximumSizeInBytes must be ≤ delegation (${String(delegation.maximumSizeInBytes)}).`,
+    );
+  }
+  const maxAge = options.cacheControlMaxAge;
+  if (
+    maxAge !== undefined &&
+    (!Number.isInteger(maxAge) || maxAge < 0 || maxAge > maximumPresignCacheControlMaxAge)
+  ) {
+    return yield* failed(
+      `${label}: cacheControlMaxAge must be an integer between 0 and ${maximumPresignCacheControlMaxAge}.`,
+    );
+  }
+  const ifMatch = options.ifMatch;
+  if (ifMatch !== undefined) {
+    if (ifMatch.length === 0) {
+      return yield* failed(`${label}: ifMatch must be a non-empty string.`);
+    }
+    if (ifMatch.length > maximumIfMatchLength) {
+      return yield* failed(`${label}: ifMatch is too long.`);
+    }
+    if (ifMatchControlCharacters.test(ifMatch)) {
+      return yield* failed(`${label}: ifMatch contains disallowed control characters.`);
+    }
+  }
+  const callback = options.onUploadCompleted;
+  if (callback !== undefined) {
+    if (callback.callbackUrl.length === 0) {
+      return yield* failed(`${label}: onUploadCompleted.callbackUrl must be a non-empty string.`);
+    }
+    if (callback.callbackUrl.length > maximumPresignCallbackUrlLength) {
+      return yield* failed(`${label}: onUploadCompleted.callbackUrl is too long.`);
+    }
+    if (!URL.canParse(callback.callbackUrl)) {
+      return yield* failed(`${label}: onUploadCompleted.callbackUrl must be a valid URL.`);
+    }
+    if (
+      callback.tokenPayload !== undefined &&
+      callback.tokenPayload !== null &&
+      callback.tokenPayload.length > maximumPresignCallbackTokenPayloadLength
+    ) {
+      return yield* failed(`${label}: onUploadCompleted.tokenPayload is too long.`);
+    }
+  }
+});
+
+const sortedCsv = (types: ReadonlyArray<string>): string =>
+  [...types].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).join(",");
+
+/**
+ * The signed query entries of one presigned URL, as the SDK's `buildPresignCanonicalQueryEntries`,
+ * in the same order. `vercel-blob-valid-until` is left out when it equals the delegation's expiry;
+ * `get` and `head` sign only the expiry, `delete` also `ifMatch`, and `put` every constraint after
+ * checking that each one only narrows the delegation's.
+ */
+export const presignCanonicalQueryEntries = Effect.fnUntraced(function* (args: {
+  readonly operation: DelegationOperation;
+  readonly delegation: PresignDelegation;
+  readonly urlOptions: PresignUrlConstraints;
+  readonly now: number;
+}) {
+  const { operation, delegation, urlOptions, now } = args;
+  const until = yield* resolveValidUntil(delegation.validUntil, urlOptions.validUntil, now);
+  const entries: Array<PresignQueryEntry> = [];
+  if (until < Math.trunc(delegation.validUntil ?? Number.NaN)) {
+    entries.push([presignQueryValidUntil, String(until)]);
+  }
+
+  if (operation === "delete") {
+    if (urlOptions.ifMatch !== undefined) {
+      entries.push([presignQueryIfMatch, urlOptions.ifMatch]);
+    }
+    return entries;
+  }
+  if (operation !== "put") {
+    return entries;
+  }
+
+  yield* validateUploadConstraints(urlOptions, delegation);
+
+  if (urlOptions.allowedContentTypes !== undefined) {
+    const csv = sortedCsv(urlOptions.allowedContentTypes);
+    if (csv.length > 16_384) {
+      return yield* failed(`${label}: allowedContentTypes query value is too long.`);
+    }
+    entries.push([presignQueryAllowedContentTypes, csv]);
+  }
+  if (urlOptions.maximumSizeInBytes !== undefined) {
+    entries.push([presignQueryMaximumSize, String(Math.trunc(urlOptions.maximumSizeInBytes))]);
+  }
+  if (urlOptions.addRandomSuffix !== undefined) {
+    entries.push([presignQueryAddRandomSuffix, urlOptions.addRandomSuffix ? "true" : "false"]);
+  }
+  if (urlOptions.allowOverwrite !== undefined) {
+    entries.push([presignQueryAllowOverwrite, urlOptions.allowOverwrite ? "true" : "false"]);
+  }
+  if (urlOptions.cacheControlMaxAge !== undefined) {
+    entries.push([
+      presignQueryCacheControlMaxAge,
+      String(Math.trunc(urlOptions.cacheControlMaxAge)),
+    ]);
+  }
+  if (urlOptions.ifMatch !== undefined) {
+    entries.push([presignQueryIfMatch, urlOptions.ifMatch]);
+  }
+  if (urlOptions.onUploadCompleted !== undefined) {
+    const { callbackUrl, tokenPayload } = urlOptions.onUploadCompleted;
+    entries.push([presignQueryCallbackUrl, callbackUrl]);
+    if (tokenPayload !== undefined && tokenPayload !== null && tokenPayload !== "") {
+      entries.push([presignQueryCallbackTokenPayload, tokenPayload]);
+    }
+  }
+  return entries;
+});
+
+const epochMillis = (value: DateTime.Utc | undefined): number | undefined =>
+  value === undefined ? undefined : DateTime.toEpochMillis(value);
+
+/** The signed constraints of {@link PresignOptions}, in wire units. */
+const urlConstraints = (options: PresignOptions): PresignUrlConstraints => {
+  const validUntil = epochMillis(options.validUntil);
+  switch (options.operation) {
+    case "get":
+    case "head":
+      return { validUntil };
+    case "delete":
+      return { validUntil, ifMatch: options.ifMatch };
+    case "put":
+      return {
+        validUntil,
+        allowedContentTypes: options.allowedContentTypes,
+        maximumSizeInBytes: options.maximumSizeInBytes,
+        addRandomSuffix: options.addRandomSuffix,
+        allowOverwrite: options.allowOverwrite,
+        cacheControlMaxAge: options.cacheControlMaxAge,
+        ifMatch: options.ifMatch,
+        onUploadCompleted: options.onUploadCompleted,
+      };
+  }
+};
+
+const operationNotDelegated: Record<DelegationOperation, string> = {
+  get: 'The delegation token is not valid for `GET` requests. Include `"get"` in `operations` when calling `issueSignedToken`.',
+  head: 'The delegation token is not valid for `HEAD` requests. Include `"head"` in `operations` when calling `issueSignedToken`.',
+  put: 'The delegation token is not valid for presigned write requests. Include `"put"` in `operations` when calling `issueSignedToken`.',
+  delete:
+    'The delegation token is not valid for presigned delete requests. Include `"delete"` in `operations` when calling `issueSignedToken`.',
+};
+
+/**
+ * Sign one request with a signed token, as the SDK's `presign`: check the delegation's pathname,
+ * expiry and operations, build the signed query entries, and HMAC their canonical string with the
+ * client signing token.
+ *
+ * @param now - Current time in epoch milliseconds.
+ * @returns The payload, or `BlobPresignFailed` with the SDK's message.
+ */
+export const presignPayload = Effect.fnUntraced(function* (
+  token: SigningToken,
+  options: PresignOptions,
+  now: number,
+) {
+  const clientSigningToken = Redacted.value(token.clientSigningToken);
+  if (!clientSigningToken || !token.delegationToken) {
+    return yield* failed(
+      "`clientSigningToken` and `delegationToken` from `issueSignedToken` are required.",
+    );
+  }
+  const scope = delegationScope(token.delegationToken);
+  if (Option.isNone(scope)) {
+    return yield* failed("Invalid or unreadable `delegationToken` payload.");
+  }
+  const { pathname, validUntil, operations, maximumSizeInBytes, allowedContentTypes } = scope.value;
+  if (pathname && pathname !== "*" && options.pathname !== pathname) {
+    return yield* failed(
+      `Blob path does not match the signed token scope; expected \`${pathname}\`, got \`${options.pathname}\`.`,
+    );
+  }
+  if (validUntil !== undefined && Number.isFinite(validUntil) && now > validUntil) {
+    return yield* failed("The signed delegation has expired; issue a new token first.");
+  }
+  if (!operations?.includes(options.operation)) {
+    return yield* failed(operationNotDelegated[options.operation]);
+  }
+
+  const entries = yield* presignCanonicalQueryEntries({
+    operation: options.operation,
+    delegation: { validUntil, maximumSizeInBytes, allowedContentTypes },
+    urlOptions: urlConstraints(options),
+    now,
+  });
+  const signature = yield* hmacSha256Base64Url(
+    clientSigningToken,
+    canonicalString(options.pathname, entries, options.operation),
+  );
+  return new PresignedUrlPayload({
+    delegationToken: token.delegationToken,
+    signature,
+    params: Object.fromEntries(entries),
+  });
+});
+
+/** `url` with the payload's params, `vercel-blob-delegation` and `vercel-blob-signature` set. */
+export const withPresignedParams = (url: URL, payload: PresignedUrlPayload): URL => {
+  const result = new URL(url);
+  for (const [key, value] of Object.entries(payload.params)) {
+    result.searchParams.set(key, value);
+  }
+  result.searchParams.set("vercel-blob-delegation", payload.delegationToken);
+  result.searchParams.set("vercel-blob-signature", payload.signature);
+  return result;
+};
+
+/**
+ * The presigned URL of a `get` or `head`, as the SDK's `buildPresignedGetUrl`: a blob URL is used
+ * as is, a pathname is resolved under the delegation's store (`blobBaseUrl`); `cache=0` (unsigned)
+ * is added for a private `get` with `useCache: false`.
+ *
+ * @returns None when the delegation token carries no valid store id, which the SDK requires even
+ *   for a blob URL.
+ */
+export const presignedBlobUrl = (args: {
+  readonly pathnameOrUrl: string;
+  readonly payload: PresignedUrlPayload;
+  readonly access: BlobAccess;
+  readonly useCache: boolean | undefined;
+  readonly blobBaseUrl: (storeId: StoreId, access: BlobAccess) => URL;
+}): Option.Option<URL> =>
+  Option.map(storeIdFromDelegationToken(args.payload.delegationToken), (storeId) => {
+    const url = isUrl(args.pathnameOrUrl)
+      ? new URL(args.pathnameOrUrl)
+      : blobUrl(args.blobBaseUrl(storeId, args.access), args.pathnameOrUrl);
+    if (args.useCache === false && args.access === "private") {
+      url.searchParams.set("cache", "0");
+    }
+    return withPresignedParams(url, args.payload);
+  });
+
+/**
+ * The presigned URL of a `put` or `delete`, as the SDK's `buildPresignedPutUrl`: the Blob API's
+ * `/?pathname=…` (trailing slashes of `apiUrl` removed) plus the payload's params.
+ */
+export const presignedApiUrl = (
+  apiUrl: URL,
+  pathname: string,
+  payload: PresignedUrlPayload,
+): URL => {
+  const base = apiUrl.href.replace(/\/+$/, "");
+  return withPresignedParams(
+    new URL(`${base}/?${new URLSearchParams({ pathname }).toString()}`),
+    payload,
+  );
+};

package/src/internal/store-id.ts

@@ -0,0 +1,69 @@
+import { Option, Result, Schema } from "effect";
+import { Base64Url } from "effect/encoding";
+
+import { StoreId } from "../contracts/blob-domain.ts";
+
+const decodeStoreId = Schema.decodeUnknownOption(StoreId);
+
+/**
+ * Strip the optional `store_` prefix from a store id. `BLOB_STORE_ID` (as written by
+ * `vercel env pull`) and the `storeId` option accept `store_<id>` or `<id>`; the API wants the bare
+ * id, case preserved.
+ */
+export const normalizeStoreId = (storeId: string): string =>
+  storeId.startsWith("store_") ? storeId.slice("store_".length) : storeId;
+
+/**
+ * Validate a store id given in either form (`store_<id>` or `<id>`).
+ *
+ * @returns The bare id, or none when it is empty or contains whitespace or `_`.
+ */
+export const parseStoreId = (storeId: string): Option.Option<StoreId> =>
+  decodeStoreId(normalizeStoreId(storeId));
+
+/**
+ * The store id embedded in a read-write token (`vercel_blob_rw_<storeId>_<secret>`): the fourth
+ * `_`-separated segment, as the SDK's `parseStoreIdFromReadWriteToken`.
+ *
+ * @returns None when the token has no valid fourth segment.
+ */
+export const storeIdFromReadWriteToken = (token: string): Option.Option<StoreId> =>
+  Option.flatMap(Option.fromUndefinedOr(token.split("_")[3]), decodeStoreId);
+
+/**
+ * The store id embedded in a client token (`vercel_blob_client_<storeId>_<payload>`). The SDK reads
+ * it with the same fourth-segment rule as read-write tokens.
+ */
+export const storeIdFromClientToken: (token: string) => Option.Option<StoreId> =
+  storeIdFromReadWriteToken;
+
+const DelegationPayload = Schema.fromJsonString(Schema.Struct({ storeId: Schema.NonEmptyString }));
+
+const decodeDelegationPayload = Schema.decodeUnknownOption(DelegationPayload);
+
+/**
+ * Read the store id from a delegation token, the public half of a signed token that every presigned
+ * URL carries in `vercel-blob-delegation`. The token's payload is the base64url JSON before the first
+ * `.`; its `storeId` field is returned without the `store_` prefix.
+ *
+ * Works in browsers, so a client can address the right store from a presigned payload alone.
+ *
+ * @returns None when the token has no `.`, its payload is not base64url JSON, or it has no
+ *   non-empty `storeId` string that is a valid store id.
+ */
+export const storeIdFromDelegationToken = (delegationToken: string): Option.Option<StoreId> => {
+  const dot = delegationToken.indexOf(".");
+  if (dot < 0) {
+    return Option.none();
+  }
+  // The SDK's decoder also accepts standard base64 characters; normalize them to base64url.
+  const segment = delegationToken
+    .slice(0, dot)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return Result.getSuccess(Base64Url.decodeString(segment)).pipe(
+    Option.flatMap(decodeDelegationPayload),
+    Option.flatMap((payload) => parseStoreId(payload.storeId)),
+  );
+};

package/src/internal/urls.ts

@@ -0,0 +1,42 @@
+import type { BlobAccess, StoreId } from "../contracts/blob-domain.ts";
+
+/** The production Blob API, used unless `VERCEL_BLOB_API_URL` or an option overrides it. */
+export const defaultApiUrl = "https://vercel.com/api/blob";
+
+/** Where a store serves its blobs: `https://<storeId>.<access>.blob.vercel-storage.com/`. */
+export const defaultBlobBaseUrl = (storeId: StoreId, access: BlobAccess): URL =>
+  new URL(`https://${storeId}.${access}.blob.vercel-storage.com/`);
+
+/**
+ * The URL of the blob at `pathname` under a store's base URL (`BlobConfig.blobBaseUrl`), as the
+ * SDK's `constructBlobUrl`: the pathname is appended as is, so URL syntax in it (`?`, `#`) keeps its
+ * URL meaning exactly as with the SDK.
+ */
+export const blobUrl = (baseUrl: URL, pathname: string): URL => {
+  const base = baseUrl.href.endsWith("/") ? baseUrl.href : `${baseUrl.href}/`;
+  return new URL(`${base}${pathname}`);
+};
+
+/** True for strings the SDK treats as URLs rather than pathnames (`http://` or `https://`). */
+export const isUrl = (urlOrPathname: string): boolean =>
+  urlOrPathname.startsWith("http://") || urlOrPathname.startsWith("https://");
+
+/**
+ * Whether `get` may send credentials to `url`: hosts under `.blob.vercel-storage.com`, and, when
+ * the API URL is overridden (an emulator or a test server), that API URL's origin.
+ *
+ * @param apiUrl - The configured API URL; the production default allows no extra origin.
+ */
+export const isAllowedBlobUrl = (url: URL, apiUrl: URL): boolean =>
+  url.hostname.endsWith(".blob.vercel-storage.com") ||
+  (apiUrl.href !== new URL(defaultApiUrl).href && apiUrl.origin === url.origin);
+
+/**
+ * The URL that makes browsers download a blob instead of displaying it: the blob URL with
+ * `download=1` in its query.
+ */
+export const downloadUrl = (url: URL | string): URL => {
+  const result = new URL(url);
+  result.searchParams.set("download", "1");
+  return result;
+};

package/src/internal/wire.ts

@@ -0,0 +1,80 @@
+import { Schema, SchemaGetter } from "effect";
+
+import {
+  BlobMetadata,
+  CreateFolderResult,
+  ListPage,
+  PutBlobResult,
+} from "../contracts/blob-domain.ts";
+
+/*
+ * JSON bodies of Blob API responses, decoded into the contract classes. Unknown fields are ignored
+ * so newer API versions keep decoding. Pass these as `response` to `BlobRequester.call`.
+ */
+
+/** `PUT /`, `PUT ?pathname&fromUrl` (copy), rename, put-image and multipart `complete`. */
+export const PutBlobResponse = Schema.Struct({
+  url: Schema.URLFromString,
+  downloadUrl: Schema.URLFromString,
+  pathname: Schema.String,
+  contentType: Schema.String,
+  contentDisposition: Schema.String,
+  etag: Schema.String,
+}).pipe(Schema.decodeTo(PutBlobResult));
+
+/** `PUT /?pathname=<folder>/`: only `url` and `pathname` are kept, as the SDK does. */
+export const CreateFolderResponse = Schema.Struct({
+  url: Schema.URLFromString,
+  pathname: Schema.String,
+}).pipe(Schema.decodeTo(CreateFolderResult));
+
+/** `GET ?url=…` (head). `uploadedAt` is an ISO 8601 string. */
+export const HeadBlobResponse = Schema.Struct({
+  url: Schema.URLFromString,
+  downloadUrl: Schema.URLFromString,
+  pathname: Schema.String,
+  size: Schema.Int,
+  uploadedAt: Schema.DateTimeUtcFromString,
+  contentType: Schema.String,
+  contentDisposition: Schema.String,
+  cacheControl: Schema.String,
+  etag: Schema.String,
+}).pipe(Schema.decodeTo(BlobMetadata));
+
+const ListedBlobWire = Schema.Struct({
+  url: Schema.URLFromString,
+  downloadUrl: Schema.URLFromString,
+  pathname: Schema.String,
+  size: Schema.Int,
+  uploadedAt: Schema.DateTimeUtcFromString,
+  etag: Schema.String,
+});
+
+const ListWire = Schema.Struct({
+  blobs: Schema.Array(ListedBlobWire),
+  folders: Schema.optionalKey(Schema.Array(Schema.String)),
+  cursor: Schema.OptionFromOptionalNullOr(Schema.String),
+  hasMore: Schema.Boolean,
+});
+
+/**
+ * `GET ?limit&prefix&cursor&mode` (list). `folders` is only sent for `mode=folded`; it decodes to
+ * an empty array otherwise.
+ */
+export const ListResponse = ListWire.pipe(
+  Schema.decodeTo(ListPage, {
+    decode: SchemaGetter.transform(({ folders, ...page }) => ({ ...page, folders: folders ?? [] })),
+    encode: SchemaGetter.transform((page) => page),
+  }),
+);
+
+/** `POST /mpu` with `x-mpu-action: create`. */
+export const CreateMultipartUploadResponse = Schema.Struct({
+  uploadId: Schema.String,
+  key: Schema.String,
+});
+
+/** `POST /mpu` with `x-mpu-action: upload`. */
+export const UploadPartResponse = Schema.Struct({
+  etag: Schema.String,
+});