@dytsou/shorten-url 2.4.4 → 2.4.5

package/src/lib/flag-routes.js

@@ -0,0 +1,155 @@
+import { hasPassedAccess } from "./access.js";
+import { createFlagManagement } from "./flag-management.js";
+import { FLAGSHIP_CONTEXT_ATTRIBUTES } from "./feature-toggle.js";
+import { flagEvaluationFields, log } from "./observability.js";
+
+const TARGETING_KEY_COOKIE = "shorten-url-targeting-key";
+const TARGETING_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+const REQUEST_CONTEXT_ATTRIBUTES = FLAGSHIP_CONTEXT_ATTRIBUTES.filter(
+  (attribute) => !["country", "utmSource", "utmMedium", "utmCampaign"].includes(attribute)
+);
+const CAMPAIGN_PARAMETERS = [
+  ["utm_source", "utmSource"],
+  ["utm_medium", "utmMedium"],
+  ["utm_campaign", "utmCampaign"],
+];
+
+function normalizePrefix(prefix) {
+  return `/${String(prefix || "").replace(/^\/|\/$/g, "")}`;
+}
+
+function originFromPageUrl(pageUrl) {
+  try {
+    return new URL(pageUrl).origin;
+  } catch {
+    return null;
+  }
+}
+
+function isPathWithin(path, prefix) {
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+
+function managementRoute(path, apiPrefix) {
+  const suffix = path === apiPrefix ? "" : path.slice(`${apiPrefix}/`.length);
+  const routes = {
+    csrf: "csrf",
+    flags: "flags",
+    flag: "flag",
+    "flag/shorten-routing": "flag:shorten-routing",
+    "flag/shorten-routing/publish": "publish:shorten-routing",
+  };
+  return routes[suffix] || "unknown";
+}
+
+function targetingKeyFromRequest(request) {
+  const cookie = request.headers.get("Cookie") || "";
+  for (const entry of cookie.split(";")) {
+    const separator = entry.indexOf("=");
+    if (separator < 0 || entry.slice(0, separator).trim() !== TARGETING_KEY_COOKIE) continue;
+    const value = entry.slice(separator + 1).trim();
+    return TARGETING_KEY_PATTERN.test(value) ? value : null;
+  }
+  return null;
+}
+
+function boundedContextValue(value, maxLength = 128) {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized && normalized.length <= maxLength ? normalized : null;
+}
+
+function contextFromRequest(request) {
+  const context = {};
+  const geo = request.cf;
+  for (const attribute of REQUEST_CONTEXT_ATTRIBUTES) {
+    const value = boundedContextValue(geo?.[attribute], attribute === "timezone" ? 64 : 128);
+    if (value) context[attribute] = value;
+  }
+
+  const language = boundedContextValue(
+    request.headers.get("Accept-Language")?.split(",", 1)[0]?.split(";", 1)[0]?.toLowerCase(),
+    35
+  );
+  if (language) context.language = language;
+
+  const url = new URL(request.url);
+  for (const [parameter, attribute] of CAMPAIGN_PARAMETERS) {
+    const value = boundedContextValue(url.searchParams.get(parameter));
+    if (value) context[attribute] = value;
+  }
+  return context;
+}
+
+function setTargetingKeyCookie(response, targetingKey) {
+  const headers = new Headers(response.headers);
+  headers.append(
+    "Set-Cookie",
+    `${TARGETING_KEY_COOKIE}=${targetingKey}; Path=/; Max-Age=31536000; HttpOnly; Secure; SameSite=Lax`
+  );
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+export function createFlagRoutes({
+  prefix,
+  shorteningPath,
+  pageUrl,
+  shortener,
+  env,
+  adapter,
+  verifyToken,
+  allowedOrigins = [],
+  createTargetingKey = () => globalThis.crypto.randomUUID(),
+}) {
+  const settingsPrefix = normalizePrefix(prefix);
+  const pageOrigin = originFromPageUrl(pageUrl);
+  const trustedOrigins = [
+    ...new Set(
+      [pageOrigin, ...(Array.isArray(allowedOrigins) ? allowedOrigins : [])].filter(Boolean)
+    ),
+  ];
+  const management = createFlagManagement({
+    adapter,
+    responses: shortener,
+    env,
+    verifyToken,
+    allowedOrigins: trustedOrigins,
+  });
+  const apiPrefix = `${settingsPrefix}/api`;
+
+  function handleSettings(request, path) {
+    if (!isPathWithin(path, settingsPrefix)) return null;
+    if (!isPathWithin(path, apiPrefix)) {
+      return shortener.jsonResponse({ status: 404, message: "Settings route not found" }, 404);
+    }
+    return management.handle(request, managementRoute(path, apiPrefix));
+  }
+
+  async function evaluateShortening(request, path, fallbackResponse) {
+    if (request.method !== "GET" || !hasPassedAccess(request, env)) return null;
+    if (path !== shorteningPath) return null;
+    const country = request.cf?.country;
+    const existingTargetingKey = targetingKeyFromRequest(request);
+    const targetingKey = existingTargetingKey || createTargetingKey();
+    const context = contextFromRequest(request);
+    const decision = await adapter.evaluate(country, {
+      targetingKey,
+      ...(Object.keys(context).length ? { context } : {}),
+    });
+    log("info", "flagship.evaluation", flagEvaluationFields(decision));
+    let response = null;
+    if (decision.outcome === "matched") {
+      response = Response.redirect(decision.destination, 302);
+    } else if (typeof fallbackResponse === "function") {
+      response = await fallbackResponse();
+    }
+    if (!response || existingTargetingKey) return response;
+    return setTargetingKeyCookie(response, targetingKey);
+  }
+
+  return { handleSettings, evaluateShortening };
+}

package/src/lib/flagship.js

@@ -0,0 +1,269 @@
+import { log } from "./observability.js";
+import {
+  SHORTENING_FLAG_KEY,
+  FLAGSHIP_CONTEXT_ATTRIBUTES,
+  fromProviderFlag,
+  normalizeCountry,
+  toProviderFlag,
+  validateFlagDefinition,
+} from "./feature-toggle.js";
+import { isSafeDestination } from "./safety.js";
+
+export class FlagshipUnavailableError extends Error {
+  constructor(message = "Flagship is not configured") {
+    super(message);
+    this.name = "FlagshipUnavailableError";
+  }
+}
+
+export class FlagshipManagementError extends Error {
+  constructor(message, status = 502) {
+    super(message);
+    this.name = "FlagshipManagementError";
+    this.status = status;
+  }
+}
+
+/**
+ * Typed boundary for the first-party Cloudflare Flagship binding.
+ *
+ * @typedef {object} FlagshipBinding
+ * @property {(key: string, fallback: object, context?: Record<string, string>) => Promise<object>} getObjectDetails
+ *
+ * @typedef {object} FlagshipEnvironment
+ * @property {FlagshipBinding} [FLAGS] Official Cloudflare Flagship evaluation binding.
+ * @property {string} [CLOUDFLARE_ACCOUNT_ID] Account identifier for management calls.
+ * @property {string} [FLAGSHIP_APP_ID] Flagship app identifier for management calls.
+ * @property {string} [FLAGSHIP_API_TOKEN] Secret token for management calls.
+ * @property {string} [FLAGSHIP_CSRF_SECRET] Secret used for settings CSRF tokens.
+ */
+
+function getBinding(env) {
+  const binding = env?.FLAGS;
+  return binding && typeof binding.getObjectDetails === "function" ? binding : null;
+}
+
+const SUPPORTED_PROVIDER_REASONS = new Set(["TARGETING_MATCH", "SPLIT", "DEFAULT", "DISABLED"]);
+const DEFAULT_PROVIDER_REASONS = new Set(["DEFAULT", "DISABLED"]);
+
+function failedProviderDecision(country, fallbackReason, durationMs) {
+  return { outcome: "failed", country, fallbackReason, durationMs };
+}
+
+function unmatchedProviderDecision(country, fallbackReason, durationMs) {
+  return { outcome: "unmatched", country, fallbackReason, durationMs };
+}
+
+function hasValidProviderDestination(details) {
+  const destination = details.value?.url;
+  return Boolean(
+    destination && isSafeDestination(destination) && typeof details.variant === "string"
+  );
+}
+
+function matchedProviderDecision(details, country, durationMs) {
+  return {
+    outcome: "matched",
+    country,
+    variant: details.variant,
+    destination: details.value.url,
+    flagKey: details.flagKey || SHORTENING_FLAG_KEY,
+    ...(details.version ? { version: details.version } : {}),
+    durationMs,
+  };
+}
+
+function defaultFallbackReason(reason, country) {
+  if (reason === "DISABLED") return "disabled_default_missing";
+  if (country) return "no_match";
+  return "missing_country";
+}
+
+function runtimeDecision(details, country, durationMs) {
+  const normalizedCountry = normalizeCountry(country);
+  if (!details || typeof details !== "object") {
+    return failedProviderDecision(normalizedCountry, "malformed_provider_response", durationMs);
+  }
+  if (details.errorCode) {
+    return failedProviderDecision(normalizedCountry, "provider_error", durationMs);
+  }
+  const reason = details.reason;
+  if (!SUPPORTED_PROVIDER_REASONS.has(reason)) {
+    return failedProviderDecision(normalizedCountry, "malformed_provider_response", durationMs);
+  }
+  if (DEFAULT_PROVIDER_REASONS.has(reason)) {
+    if (hasValidProviderDestination(details)) {
+      return matchedProviderDecision(details, normalizedCountry, durationMs);
+    }
+    return unmatchedProviderDecision(
+      normalizedCountry,
+      defaultFallbackReason(reason, normalizedCountry),
+      durationMs
+    );
+  }
+  if (!hasValidProviderDestination(details)) {
+    return unmatchedProviderDecision(normalizedCountry, "invalid_provider_value", durationMs);
+  }
+  return matchedProviderDecision(details, normalizedCountry, durationMs);
+}
+
+function providerBase(env) {
+  const accountId = env?.CLOUDFLARE_ACCOUNT_ID;
+  const appId = env?.FLAGSHIP_APP_ID;
+  const token = env?.FLAGSHIP_API_TOKEN;
+  if (!accountId || !appId || !token) throw new FlagshipUnavailableError();
+  return {
+    token,
+    url:
+      env.FLAGSHIP_API_BASE_URL ||
+      `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/flagship/apps/${encodeURIComponent(appId)}/flags`,
+  };
+}
+
+export function createFlagshipAdapter(
+  env,
+  { fetchImpl = globalThis.fetch, now = () => Date.now(), evaluationTimeoutMs = 200 } = {}
+) {
+  async function evaluate(
+    country,
+    { targetingKey, context: requestContext, flagKey = SHORTENING_FLAG_KEY } = {}
+  ) {
+    const started = now();
+    const binding = getBinding(env);
+    const normalizedCountry = normalizeCountry(country);
+    if (!binding) {
+      return runtimeDecision(null, country, now() - started);
+    }
+    let timeoutId;
+    try {
+      const providedContext = {};
+      for (const attribute of FLAGSHIP_CONTEXT_ATTRIBUTES) {
+        if (attribute === "country") continue;
+        const value = requestContext?.[attribute];
+        if (typeof value === "string" && value.trim()) {
+          providedContext[attribute] = value.trim();
+        }
+      }
+      const context = {
+        ...(normalizedCountry ? { country: normalizedCountry } : {}),
+        ...providedContext,
+        ...(typeof targetingKey === "string" && targetingKey ? { targetingKey } : {}),
+      };
+      const details = await Promise.race([
+        binding.getObjectDetails(
+          flagKey,
+          { url: null },
+          Object.keys(context).length ? context : undefined
+        ),
+        new Promise(
+          (_, reject) =>
+            (timeoutId = setTimeout(
+              () => reject(new Error("Flagship evaluation timed out")),
+              evaluationTimeoutMs
+            ))
+        ),
+      ]);
+      return runtimeDecision(details, country, now() - started);
+    } catch (error) {
+      const fallbackReason = error?.message?.includes("timed out") ? "timeout" : "provider_error";
+      log("warn", "flagship.evaluate_failed", { fallback_reason: fallbackReason });
+      return {
+        outcome: "failed",
+        country: normalizedCountry,
+        fallbackReason,
+        durationMs: now() - started,
+      };
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  async function managementRequest(path = "", options = {}) {
+    const { token, url } = providerBase(env);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 2000);
+    let response;
+    try {
+      response = await fetchImpl(`${url}${path}`, {
+        ...options,
+        signal: controller.signal,
+        headers: {
+          accept: "application/json",
+          "content-type": "application/json",
+          authorization: `Bearer ${token}`,
+          ...options.headers,
+        },
+      });
+    } catch {
+      throw new FlagshipManagementError("Flagship management request failed", 502);
+    } finally {
+      clearTimeout(timeout);
+    }
+    let body = null;
+    try {
+      body = await response.json();
+    } catch {
+      // Treat a non-JSON provider response as an unavailable provider.
+    }
+    if (!response.ok || !body?.success) {
+      throw new FlagshipManagementError(
+        "Flagship management request failed",
+        response.status || 502
+      );
+    }
+    return body.result;
+  }
+
+  async function listFlags() {
+    return managementRequest();
+  }
+
+  async function getFlag(key = SHORTENING_FLAG_KEY) {
+    return managementRequest(`/${encodeURIComponent(key)}`);
+  }
+
+  async function saveFlag(definition, { key = definition?.key, expectedUpdatedAt } = {}) {
+    const validated = validateFlagDefinition(definition);
+    if (!validated.ok) {
+      throw new FlagshipManagementError(validated.errors.join("; "), 400);
+    }
+    if (expectedUpdatedAt !== undefined) {
+      const current = await getFlag(key);
+      if (current?.updated_at !== expectedUpdatedAt) {
+        throw new FlagshipManagementError("Flag definition changed; reload before saving", 409);
+      }
+    }
+    const providerFlag = toProviderFlag(validated.value);
+    return managementRequest(`/${encodeURIComponent(key)}`, {
+      method: "PUT",
+      body: JSON.stringify(providerFlag),
+    });
+  }
+
+  async function createFlag(definition) {
+    const validated = validateFlagDefinition(definition);
+    if (!validated.ok) throw new FlagshipManagementError(validated.errors.join("; "), 400);
+    return managementRequest("", {
+      method: "POST",
+      body: JSON.stringify(toProviderFlag(validated.value)),
+    });
+  }
+
+  async function publishFlag(definition, expectedUpdatedAt) {
+    const validated = validateFlagDefinition({ ...definition, enabled: true });
+    if (!validated.ok) throw new FlagshipManagementError(validated.errors.join("; "), 400);
+    return saveFlag(validated.value, { expectedUpdatedAt });
+  }
+
+  return {
+    evaluate,
+    listFlags,
+    getFlag,
+    saveFlag,
+    createFlag,
+    publishFlag,
+    normalizeProviderFlag: fromProviderFlag,
+  };
+}
+
+export { runtimeDecision };

package/src/lib/observability.js

@@ -1,5 +1,11 @@
 import { tracing } from "cloudflare:workers";
 
+const FLAG_OUTCOMES = new Set(["matched", "unmatched", "unpublished", "failed"]);
+
+function boundedString(value, maxLength) {
+  return typeof value === "string" && value ? value.slice(0, maxLength) : null;
+}
+
 /** Structured JSON log for Workers Logs indexing. */
 export function log(level, event, fields = {}) {
   console.log({ level, event, ts: new Date().toISOString(), ...fields });
@@ -37,6 +43,34 @@ export function requestFields(request) {
   };
 }
 
+/** Return only bounded, non-sensitive fields for a Flagship decision log. */
+export function flagEvaluationFields(decision) {
+  const key = boundedString(decision?.flagKey, 64) || "shorten-routing";
+  const outcome = FLAG_OUTCOMES.has(decision?.outcome) ? decision.outcome : "failed";
+  const variant = boundedString(decision?.variant, 64);
+  const country =
+    typeof decision?.country === "string" && /^[A-Za-z]{2}$/.test(decision.country)
+      ? decision.country.toUpperCase()
+      : null;
+  const version = boundedString(decision?.version, 128);
+  const fallbackReason = boundedString(decision?.fallbackReason, 128);
+
+  return {
+    flagship: {
+      key,
+      outcome,
+      ...(variant ? { variant } : {}),
+      ...(country ? { country } : {}),
+      ...(version ? { version } : {}),
+      ...(fallbackReason ? { fallback_reason: fallbackReason } : {}),
+    },
+    duration_ms:
+      typeof decision?.durationMs === "number" && Number.isFinite(decision.durationMs)
+        ? Math.max(0, Math.round(decision.durationMs))
+        : null,
+  };
+}
+
 function setRequestSpanAttributes(span, request) {
   if (!span.isTraced) return;
   const url = new URL(request.url);

package/src/lib/responses.js

@@ -1,14 +1,39 @@
 import { wantsJson } from "./validate.js";
 
+function withHostedPageBase(html, url) {
+  if (!/<head\b/i.test(html) || /<base\b/i.test(html)) return html;
+  let baseUrl;
+  try {
+    baseUrl = new URL(".", url).href;
+  } catch {
+    return html;
+  }
+  const escapedBaseUrl = baseUrl.replaceAll("&", "&amp;").replaceAll('"', "&quot;");
+  return html.replace(/<head\b[^>]*>/i, (head) => `${head}<base href="${escapedBaseUrl}">`);
+}
+
 async function fetchHostedPage(url, status = 200) {
+  if (!url) {
+    return new Response("Page is not configured", {
+      status,
+      headers: { "content-type": "text/plain;charset=UTF-8" },
+    });
+  }
   const upstream = await fetch(url, { redirect: "follow" });
-  return new Response(await upstream.text(), {
+  const html = withHostedPageBase(await upstream.text(), url);
+  return new Response(html, {
     status,
     headers: { "content-type": "text/html;charset=UTF-8" },
   });
 }
 
 async function fetchInterstitial(url, destination) {
+  if (!url) {
+    return new Response("Redirect interstitial is not configured", {
+      status: 503,
+      headers: { "content-type": "text/plain;charset=UTF-8" },
+    });
+  }
   const upstream = await fetch(url);
   const html = (await upstream.text()).replace(/{Replace}/gm, destination);
   return new Response(html, { headers: { "content-type": "text/html;charset=UTF-8" } });
@@ -17,9 +42,20 @@ async function fetchInterstitial(url, destination) {
 export function createResponses({ worker, endpoints }) {
   function corsHeaders() {
     if (worker.cors !== "on") return {};
+    let allowedOrigin = endpoints.frontendOrigin || "";
+    if (!allowedOrigin && endpoints.shortenPage) {
+      try {
+        allowedOrigin = new URL(endpoints.shortenPage).origin;
+      } catch {
+        allowedOrigin = "";
+      }
+    }
+    allowedOrigin ||= "*";
     return {
-      "Access-Control-Allow-Origin": "*",
-      "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
+      "Access-Control-Allow-Origin": allowedOrigin,
+      "Access-Control-Allow-Methods": "POST, GET, PUT, OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type, X-CSRF-Token",
+      ...(allowedOrigin === "*" ? {} : { "Access-Control-Allow-Credentials": "true" }),
     };
   }
 

package/src/lib/runtime-config.js

@@ -0,0 +1,90 @@
+const DEFAULT_FRONTEND = {
+  url: "",
+  pagesBase: "",
+  workerOrigin: "",
+  displayDomain: null,
+  theme: "",
+};
+
+const DEFAULT_WORKER = {
+  no_ref: "off",
+  cors: "on",
+  unique_link: true,
+  custom_link: true,
+  safe_browsing_api_key: "",
+  max_custom_slug_length: 50,
+  min_random_key_length: 6,
+  random_chars: "ABCDEFGHJKMNPQRSTWXYZabcdefhijkmnprstwxyz2345678",
+  reserved_slugs: [
+    "api",
+    "admin",
+    "www",
+    "mail",
+    "ftp",
+    "localhost",
+    "password",
+    "help",
+    "support",
+    "contact",
+    "about",
+    "settings",
+  ],
+};
+
+const DEFAULT_CONFIG = {
+  frontend: DEFAULT_FRONTEND,
+  worker: DEFAULT_WORKER,
+  storage: { binding_name: "LINKS" },
+  flagship: { binding_name: "FLAGS", app_id: "" },
+};
+
+function isObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value);
+}
+
+function cloneConfig(value) {
+  if (Array.isArray(value)) return [...value];
+  if (isObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, cloneConfig(entry)])
+    );
+  }
+  return value;
+}
+
+function mergeConfig(base, override) {
+  const result = cloneConfig(base);
+  if (!isObject(override)) return result;
+
+  for (const [key, value] of Object.entries(override)) {
+    result[key] = isObject(value) ? mergeConfig(result[key] || {}, value) : value;
+  }
+  return result;
+}
+
+function envValue(env, name, fallback) {
+  return typeof env?.[name] === "string" && env[name] ? env[name] : fallback;
+}
+
+/**
+ * Build the non-secret Worker configuration from defaults and runtime values.
+ * Provider credentials intentionally stay in `env` and are never copied here.
+ */
+export function createRuntimeConfig(env = {}, overrides = {}) {
+  const config = mergeConfig(DEFAULT_CONFIG, overrides);
+
+  config.frontend.url = envValue(env, "FRONTEND_URL", config.frontend.url);
+  config.frontend.pagesBase = envValue(
+    env,
+    "FRONTEND_PAGES_BASE",
+    config.frontend.pagesBase || config.frontend.url
+  );
+  config.frontend.workerOrigin = envValue(env, "WORKER_ORIGIN", config.frontend.workerOrigin);
+  config.worker.cors = envValue(env, "WORKER_CORS", config.worker.cors);
+  config.worker.no_ref = envValue(env, "WORKER_NO_REF", config.worker.no_ref);
+  config.flagship.app_id = envValue(env, "FLAGSHIP_APP_ID", config.flagship.app_id);
+
+  return config;
+}
+
+export const defaultConfig = DEFAULT_CONFIG;

package/src/lib/safety.js

@@ -1,5 +1,20 @@
 import { traceSpan } from "./observability.js";
 
+export function isSafeDestination(url) {
+  if (typeof url !== "string") return false;
+  try {
+    const parsed = new URL(url);
+    return (
+      (parsed.protocol === "https:" || parsed.protocol === "http:") &&
+      !parsed.username &&
+      !parsed.password &&
+      !parsed.hash
+    );
+  } catch {
+    return false;
+  }
+}
+
 export async function isUrlSafe(url, worker, endpoints) {
   return traceSpan("safe_browsing.check", async () => {
     const body = JSON.stringify({

package/src/lib/shortener.js

@@ -5,7 +5,7 @@ import { createResponses } from "./responses.js";
 import { isUrlSafe } from "./safety.js";
 import { isValidCustomSlug, isValidUrl } from "./validate.js";
 
-export function createShortener({ worker, endpoints, kv }) {
+export function createShortener({ worker, endpoints, kv, env }) {
   const responses = createResponses({ worker, endpoints });
   const kvStore = createKvStore({ worker, kv });
   const reservedSlugSet = new Set(worker.reserved_slugs.map((s) => s.toLowerCase()));
@@ -55,7 +55,7 @@ export function createShortener({ worker, endpoints, kv }) {
         return jsonResponse({ status: 404, message: "Invalid API path" }, 404);
       }
 
-      if (requireAccess && !hasPassedAccess(request)) {
+      if (requireAccess && !hasPassedAccess(request, env)) {
         log("warn", "shorten.access_denied", { api: { path: apiPath } });
         return errorResponse("You must use WARP to shorten the URL", 403, request);
       }