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

package/src/internal/callback.ts

@@ -0,0 +1,200 @@
+import type { VercelSystemEnv } from "@panorama-industries/effect-vercel-core";
+
+import { Effect, Option, Result } from "effect";
+import { Base64, Hex } from "effect/encoding";
+
+/*
+ * Upload-completed callbacks, as the SDK's `client.ts` handles them: where the store sends them
+ * (`getCallbackUrl`) and how their `x-vercel-signature` is verified.
+ */
+
+/** Header that carries the signature of an upload-completed callback. */
+export const callbackSignatureHeader = "x-vercel-signature";
+
+/** The SDK's warning when an upload route has `onUploadCompleted` but no callback URL. */
+export const callbackUrlUndeterminedWarning =
+  "onUploadCompleted provided but no callbackUrl could be determined. Please provide a callbackUrl in onBeforeGenerateToken or set the VERCEL_BLOB_CALLBACK_URL environment variable.";
+
+/** The SDK's warning when an upload route returns a callback URL but has no `onUploadCompleted`. */
+export const callbackUrlUnhandledWarning =
+  "callbackUrl was provided but onUploadCompleted is not defined. The callback will not be handled.";
+
+/**
+ * Path and query of a request URL, absolute or relative, as the SDK's `getPathFromRequestUrl`.
+ *
+ * @returns None when the URL cannot be parsed.
+ */
+export const requestPath = (url: string): Option.Option<string> => {
+  const base = "https://dummy.com";
+  if (!URL.canParse(url, base)) {
+    return Option.none();
+  }
+  const parsed = new URL(url, base);
+  return Option.some(parsed.pathname + parsed.search);
+};
+
+/**
+ * Where the store should send the upload-completed callback of this route when the route gave no
+ * URL, as the SDK's `getCallbackUrl`, in order: `callbackBaseUrl` (`VERCEL_BLOB_CALLBACK_URL`) plus
+ * the request's path and query; on Vercel, the branch URL, else the deployment URL, of a preview, or
+ * the production URL of production. Logs the SDK's warning when the request URL cannot be parsed or
+ * the code runs neither with a callback base URL nor on Vercel.
+ *
+ * @param requestUrl - The request's original URL, absolute or a path.
+ */
+export const deriveCallbackUrl = Effect.fnUntraced(function* (args: {
+  readonly requestUrl: string;
+  readonly callbackBaseUrl: Option.Option<string>;
+  readonly env: VercelSystemEnv["Service"];
+}) {
+  const path = requestPath(args.requestUrl);
+  if (Option.isNone(path)) {
+    yield* Effect.logWarning(callbackUrlUndeterminedWarning);
+    return Option.none<string>();
+  }
+  if (Option.isSome(args.callbackBaseUrl)) {
+    return Option.some(`${args.callbackBaseUrl.value}${path.value}`);
+  }
+  const { env } = args;
+  if (!env.isVercel) {
+    yield* Effect.logWarning(callbackUrlUndeterminedWarning);
+    return Option.none<string>();
+  }
+  const onHost = (host: string) => `https://${host}${path.value}`;
+  if (Option.contains(env.target, "preview")) {
+    const previewHost = Option.orElse(env.branchUrl, () => env.url);
+    if (Option.isSome(previewHost)) {
+      return Option.some(onHost(previewHost.value));
+    }
+  }
+  if (Option.contains(env.target, "production")) {
+    return Option.map(env.projectProductionUrl, onHost);
+  }
+  return Option.none<string>();
+});
+
+/**
+ * The callback URL to sign into an upload, as `handleUpload` and `handleUploadPresigned` choose it:
+ * the route's URL, else (with `onUploadCompleted`) the derived one. Without `onUploadCompleted`, a
+ * route URL is kept and the SDK's warning logged, since nothing will handle the callback.
+ *
+ * @param derive - {@link deriveCallbackUrl} for this request; run only when needed.
+ */
+export const resolveCallbackUrl = Effect.fnUntraced(function* <E, R>(args: {
+  readonly provided: string | undefined;
+  readonly handlesCallback: boolean;
+  readonly derive: Effect.Effect<Option.Option<string>, E, R>;
+}) {
+  let callbackUrl = Option.filter(Option.fromUndefinedOr(args.provided), (url) => url !== "");
+  if (args.handlesCallback && Option.isNone(callbackUrl)) {
+    callbackUrl = yield* args.derive;
+  }
+  if (!args.handlesCallback && Option.isSome(callbackUrl)) {
+    yield* Effect.logWarning(callbackUrlUnhandledWarning);
+  }
+  return callbackUrl;
+});
+
+/**
+ * The text a callback signature covers: the body re-serialized as `JSON.stringify(JSON.parse(body))`,
+ * as the SDK signs the parsed body.
+ *
+ * @returns None when the body is not JSON.
+ */
+export const parseCallbackBody = (
+  body: string,
+): Option.Option<{ readonly json: unknown; readonly normalized: string }> => {
+  try {
+    const json: unknown = JSON.parse(body);
+    return Option.some({ json, normalized: JSON.stringify(json) });
+  } catch {
+    return Option.none();
+  }
+};
+
+const utf8 = new TextEncoder();
+
+/**
+ * Whether `signatureHex` is the HMAC-SHA256 (hex) of `body` keyed by the store's read-write token,
+ * as `handleUpload` verifies `x-vercel-signature`. Compared in constant time by Web Crypto `verify`;
+ * a signature that is not hex never verifies.
+ */
+export const verifyHmacCallbackSignature = Effect.fnUntraced(function* (
+  readWriteToken: string,
+  signatureHex: string,
+  body: string,
+) {
+  const signature = Result.getSuccess(Hex.decode(signatureHex));
+  if (Option.isNone(signature)) {
+    return false;
+  }
+  const key = yield* Effect.promise(() =>
+    globalThis.crypto.subtle.importKey(
+      "raw",
+      utf8.encode(readWriteToken),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["verify"],
+    ),
+  );
+  return yield* Effect.promise(() =>
+    globalThis.crypto.subtle.verify(
+      "HMAC",
+      key,
+      Uint8Array.from(signature.value),
+      utf8.encode(body),
+    ),
+  );
+});
+
+/**
+ * DER bytes of a PEM `-----BEGIN PUBLIC KEY-----` (SPKI) block, as the SDK's
+ * `publicKeyDerFromPem`.
+ *
+ * @returns None when there is no such block or its content is not base64.
+ */
+export const publicKeyDerFromPem = (pem: string): Option.Option<Uint8Array> => {
+  const match = /-----BEGIN PUBLIC KEY-----([^-]*)-----END PUBLIC KEY-----/s.exec(pem.trim());
+  const base64 = match?.[1]?.replace(/\s+/g, "");
+  if (!base64) {
+    return Option.none();
+  }
+  return Result.getSuccess(Base64.decode(base64));
+};
+
+const ed25519SignatureHex = /^[0-9a-fA-F]{128}$/;
+
+/**
+ * Whether `signatureHex` is an Ed25519 signature of `body` by the key in `publicKeyPem` (SPKI PEM,
+ * `BLOB_WEBHOOK_PUBLIC_KEY`), as `handleUploadPresigned` verifies `x-vercel-signature`. The
+ * signature must be 128 hex characters; a key that cannot be imported never verifies.
+ */
+export const verifyEd25519CallbackSignature = Effect.fnUntraced(function* (
+  publicKeyPem: string,
+  signatureHex: string,
+  body: string,
+) {
+  if (!ed25519SignatureHex.test(signatureHex)) {
+    return false;
+  }
+  const der = publicKeyDerFromPem(publicKeyPem);
+  const signature = Result.getSuccess(Hex.decode(signatureHex));
+  if (Option.isNone(der) || Option.isNone(signature)) {
+    return false;
+  }
+  return yield* Effect.tryPromise(async () => {
+    const key = await globalThis.crypto.subtle.importKey(
+      "spki",
+      Uint8Array.from(der.value),
+      { name: "Ed25519" },
+      false,
+      ["verify"],
+    );
+    return globalThis.crypto.subtle.verify(
+      "Ed25519",
+      key,
+      Uint8Array.from(signature.value),
+      utf8.encode(body),
+    );
+  }).pipe(Effect.orElseSucceed(() => false));
+});

package/src/internal/client-token.ts

@@ -0,0 +1,132 @@
+import { Effect, Option, Result, Schema } from "effect";
+import { Base64, Hex } from "effect/encoding";
+
+import type { StoreId } from "../contracts/blob-domain.ts";
+
+import { ClientToken } from "../contracts/blob-domain.ts";
+
+/*
+ * Client tokens, as the SDK's `generateClientTokenFromReadWriteToken` builds them:
+ * `vercel_blob_client_<storeId>_<base64("<hex HMAC-SHA256(payload)>.<payload>")>`, where `payload` is
+ * the base64 of the token's JSON and the HMAC is keyed by the store's read-write token. The JSON is
+ * serialized exactly as the SDK does (key order and all), so tokens are byte-identical.
+ */
+
+/** Prefix of every client token. */
+export const clientTokenPrefix = "vercel_blob_client_";
+
+/** How long a client token generated without `validUntil` stays valid, as the SDK: 30 seconds. */
+export const defaultClientTokenLifetimeMillis = 30_000;
+
+/**
+ * Fields of a client token's JSON, already in wire form (`validUntil` in epoch milliseconds), in
+ * the order they are serialized. `undefined` values are omitted, as `JSON.stringify` omits them.
+ */
+export type ClientTokenFields = Readonly<Record<string, unknown>>;
+
+/**
+ * The JSON a client token encodes, as the SDK serializes it: the fields in their order, with
+ * `allowOverwrite: true` appended when `ifMatch` is set and `allowOverwrite` is not, and
+ * `validUntil` defaulted to `defaultValidUntil` (kept in place when the fields have it).
+ *
+ * Callers reject `ifMatch` with `allowOverwrite: false` first; see {@link contradictsIfMatch}.
+ */
+export const clientTokenPayloadJson = (
+  fields: ClientTokenFields,
+  defaultValidUntil: number,
+): string => {
+  const args: Record<string, unknown> = { ...fields };
+  if (Boolean(args["ifMatch"]) && args["allowOverwrite"] === undefined) {
+    args["allowOverwrite"] = true;
+  }
+  return JSON.stringify({ ...args, validUntil: args["validUntil"] ?? defaultValidUntil });
+};
+
+/** The SDK's message for an `ifMatch` with `allowOverwrite: false`, which it refuses to sign. */
+export const ifMatchContradictionMessage =
+  "ifMatch and allowOverwrite: false are contradictory. ifMatch is used for conditional overwrites, which requires allowOverwrite to be true.";
+
+/** Whether the fields set `ifMatch` together with `allowOverwrite: false`, which the SDK rejects. */
+export const contradictsIfMatch = (fields: ClientTokenFields): boolean =>
+  Boolean(fields["ifMatch"]) && fields["allowOverwrite"] === false;
+
+const textEncoder = new TextEncoder();
+
+/** HMAC-SHA256 of `data` keyed by `secret` (both UTF-8), as lowercase hex. */
+export const hmacSha256Hex = Effect.fnUntraced(function* (secret: string, data: string) {
+  const key = yield* Effect.promise(() =>
+    globalThis.crypto.subtle.importKey(
+      "raw",
+      textEncoder.encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"],
+    ),
+  );
+  const signature = yield* Effect.promise(() =>
+    globalThis.crypto.subtle.sign("HMAC", key, textEncoder.encode(data)),
+  );
+  return Hex.encode(new Uint8Array(signature));
+});
+
+/**
+ * Sign a client token's JSON with the store's read-write token.
+ *
+ * @param payloadJson - The token's JSON, from {@link clientTokenPayloadJson}.
+ * @returns `vercel_blob_client_<storeId>_<base64("<hex HMAC>.<base64 payloadJson>")>`.
+ */
+export const signClientToken = Effect.fnUntraced(function* (
+  readWriteToken: string,
+  storeId: StoreId,
+  payloadJson: string,
+) {
+  const payload = Base64.encode(payloadJson);
+  const signature = yield* hmacSha256Hex(readWriteToken, payload);
+  return ClientToken.make(
+    `${clientTokenPrefix}${storeId}_${Base64.encode(`${signature}.${payload}`)}`,
+  );
+});
+
+/** `onUploadCompleted` as a client token carries it. */
+export const ClientTokenCallback = Schema.Struct({
+  callbackUrl: Schema.String,
+  tokenPayload: Schema.optionalKey(Schema.NullOr(Schema.String)),
+});
+
+/** The JSON a client token encodes, as the SDK's `DecodedClientTokenPayload`. */
+export const ClientTokenPayload = Schema.Struct({
+  pathname: Schema.String,
+  /** Expiry in epoch milliseconds. */
+  validUntil: Schema.Number,
+  onUploadCompleted: Schema.optionalKey(ClientTokenCallback),
+  maximumSizeInBytes: Schema.optionalKey(Schema.Number),
+  allowedContentTypes: Schema.optionalKey(Schema.Array(Schema.String)),
+  addRandomSuffix: Schema.optionalKey(Schema.Boolean),
+  allowOverwrite: Schema.optionalKey(Schema.Boolean),
+  cacheControlMaxAge: Schema.optionalKey(Schema.Number),
+  ifMatch: Schema.optionalKey(Schema.String),
+  /** Set by upload routes, which copy the route's `tokenPayload` into the token as the SDK does. */
+  tokenPayload: Schema.optionalKey(Schema.NullOr(Schema.String)),
+});
+
+/** The JSON a client token encodes. */
+export type ClientTokenPayload = typeof ClientTokenPayload.Type;
+
+const decodePayload = Schema.decodeUnknownOption(Schema.fromJsonString(ClientTokenPayload));
+
+const decodeBase64String = (input: string): Option.Option<string> =>
+  Result.getSuccess(Base64.decodeString(input));
+
+/**
+ * Read the JSON a client token encodes without verifying its signature, as the SDK's
+ * `getPayloadFromClientToken`: the fifth `_`-separated segment is base64 of `<hmac>.<base64 JSON>`.
+ * Works in browsers.
+ *
+ * @returns None when the token does not have that shape or its JSON is not a client token payload.
+ */
+export const getPayloadFromClientToken = (clientToken: string): Option.Option<ClientTokenPayload> =>
+  decodeBase64String(clientToken.split("_")[4] ?? "").pipe(
+    Option.flatMap((secured) => Option.fromUndefinedOr(secured.split(".")[1])),
+    Option.flatMap(decodeBase64String),
+    Option.flatMap(decodePayload),
+  );

package/src/internal/env.ts

@@ -0,0 +1,128 @@
+import { Config, ConfigProvider, Effect, Option, Schema } from "effect";
+
+import { defaultApiUrl } from "./urls.ts";
+
+const defaultApiVersion = "13";
+
+const defaultRetries = 10;
+
+/** A `ConfigError` with a message explaining what to fix. */
+export const configError = (message: string) =>
+  new Config.ConfigError(new ConfigProvider.SourceError({ message }));
+
+/**
+ * A variable as the SDK's `readEnv` reads it: trimmed, and absent when blank. In browsers these
+ * are usually `NEXT_PUBLIC_*` values inlined by the bundler, or absent.
+ */
+export const env = (name: string) =>
+  Config.option(Config.String(name)).pipe(
+    Config.map((value) =>
+      Option.filter(
+        Option.map(value, (value) => value.trim()),
+        (value) => value !== "",
+      ),
+    ),
+  );
+
+/** The first of several variables that is set, such as a name and its `NEXT_PUBLIC_` twin. */
+export const firstEnv = (...names: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    for (const name of names) {
+      const value = yield* env(name);
+      if (Option.isSome(value)) return value;
+    }
+    return Option.none<string>();
+  });
+
+const decodeUrl = Schema.decodeUnknownOption(Schema.URLFromString);
+
+const decodeRetries = Schema.decodeUnknownOption(
+  Schema.NumberFromString.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0)),
+);
+
+/** Values that replace what {@link requestEnv} reads from the environment. */
+export interface RequestEnvOptions {
+  readonly apiUrl?: URL | string | undefined;
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+  readonly retries?: number | undefined;
+}
+
+/** How every Blob API request is addressed and retried, shared by the server and browser clients. */
+export interface RequestEnv {
+  readonly apiUrl: URL;
+  readonly apiVersion: string;
+  readonly retries: number;
+  readonly sendContentLength: boolean;
+  readonly headers: Readonly<Record<string, string>>;
+}
+
+/**
+ * Reads the request settings the SDK's `requestApi` reads on every call: `VERCEL_BLOB_API_URL`,
+ * `VERCEL_BLOB_API_VERSION_OVERRIDE`, `VERCEL_BLOB_PROXY_THROUGH_ALTERNATIVE_API` (each also with a
+ * `NEXT_PUBLIC_` prefix), `VERCEL_BLOB_RETRIES` and `VERCEL_BLOB_USE_X_CONTENT_LENGTH`.
+ *
+ * Fails with a `ConfigError` when the API URL is not absolute or the retry count is not a
+ * non-negative integer.
+ */
+export const requestEnv = Effect.fnUntraced(function* (
+  options: RequestEnvOptions,
+): Effect.fn.Return<RequestEnv, Config.ConfigError> {
+  const apiUrlInput =
+    options.apiUrl ??
+    Option.getOrElse(
+      yield* firstEnv("VERCEL_BLOB_API_URL", "NEXT_PUBLIC_VERCEL_BLOB_API_URL"),
+      () => defaultApiUrl,
+    );
+  const apiUrl = yield* Option.match(decodeUrl(String(apiUrlInput)), {
+    onNone: () =>
+      Effect.fail(
+        configError(`Invalid Blob API URL "${String(apiUrlInput)}": expected an absolute URL.`),
+      ),
+    onSome: Effect.succeed,
+  });
+
+  const apiVersion = Option.getOrElse(
+    yield* firstEnv(
+      "VERCEL_BLOB_API_VERSION_OVERRIDE",
+      "NEXT_PUBLIC_VERCEL_BLOB_API_VERSION_OVERRIDE",
+    ),
+    () => defaultApiVersion,
+  );
+
+  const retries =
+    options.retries ??
+    (yield* Option.match(yield* env("VERCEL_BLOB_RETRIES"), {
+      onNone: () => Effect.succeed(defaultRetries),
+      onSome: (value) =>
+        Option.match(decodeRetries(value), {
+          onNone: () =>
+            Effect.fail(
+              configError(
+                `Invalid VERCEL_BLOB_RETRIES "${value}": expected a non-negative integer.`,
+              ),
+            ),
+          onSome: Effect.succeed,
+        }),
+    }));
+  if (!Number.isInteger(retries) || retries < 0) {
+    return yield* Effect.fail(
+      configError(`Invalid retries ${retries}: expected a non-negative integer.`),
+    );
+  }
+
+  const sendContentLength = Option.contains(yield* env("VERCEL_BLOB_USE_X_CONTENT_LENGTH"), "1");
+
+  const proxyThroughAlternativeApi = yield* firstEnv(
+    "VERCEL_BLOB_PROXY_THROUGH_ALTERNATIVE_API",
+    "NEXT_PUBLIC_VERCEL_BLOB_PROXY_THROUGH_ALTERNATIVE_API",
+  );
+  const headers = {
+    ...Option.match(proxyThroughAlternativeApi, {
+      onNone: () => ({}),
+      onSome: (value) => ({ "x-proxy-through-alternative-api": value }),
+    }),
+    ...options.headers,
+  };
+
+  return { apiUrl, apiVersion, retries, sendContentLength, headers };
+});