@sentroy-co/client-sdk 2.8.0 → 2.12.0

package/src/cli/env.ts

@@ -0,0 +1,402 @@
+/**
+ * `sentroy env <subcommand>` — vault sync from a local .env file.
+ *
+ * The token's (project, environment) scope is implicit; the CLI never
+ * asks for either since it can't change them.
+ */
+
+import * as fs from "fs"
+import * as path from "path"
+import * as readline from "readline"
+import {
+  parseDotenv,
+  serializeDotenv,
+  type DotenvEntry,
+} from "./dotenv"
+
+const DEFAULT_FILE = ".env"
+const DEFAULT_BASE_URL = "https://sentroy.com"
+
+interface SharedOpts {
+  token: string
+  baseUrl: string
+}
+
+interface RemoteVariable {
+  key: string
+  value: string
+  type: string
+  public: boolean
+}
+
+interface PushResponse {
+  project: string
+  environment: string
+  added: number
+  updated: number
+  unchanged: number
+  deleted: number
+  total: number
+}
+
+interface FetchResponse {
+  project: string
+  environment: string
+  variables: RemoteVariable[]
+}
+
+// ── ANSI helpers (no deps) ───────────────────────────────────────────────
+const supportsColor = process.stdout.isTTY && process.env.TERM !== "dumb"
+const c = {
+  bold: (s: string) => (supportsColor ? `\x1b[1m${s}\x1b[0m` : s),
+  dim: (s: string) => (supportsColor ? `\x1b[2m${s}\x1b[0m` : s),
+  red: (s: string) => (supportsColor ? `\x1b[31m${s}\x1b[0m` : s),
+  green: (s: string) => (supportsColor ? `\x1b[32m${s}\x1b[0m` : s),
+  yellow: (s: string) => (supportsColor ? `\x1b[33m${s}\x1b[0m` : s),
+  cyan: (s: string) => (supportsColor ? `\x1b[36m${s}\x1b[0m` : s),
+  magenta: (s: string) => (supportsColor ? `\x1b[35m${s}\x1b[0m` : s),
+}
+
+function fail(msg: string): never {
+  process.stderr.write(`${c.red("✗")} ${msg}\n`)
+  process.exit(1)
+}
+
+function info(msg: string): void {
+  process.stdout.write(`${c.cyan("→")} ${msg}\n`)
+}
+
+function ok(msg: string): void {
+  process.stdout.write(`${c.green("✓")} ${msg}\n`)
+}
+
+function warn(msg: string): void {
+  process.stdout.write(`${c.yellow("⚠")} ${msg}\n`)
+}
+
+function resolveSharedOpts(rest: Record<string, string | boolean>): SharedOpts {
+  const token =
+    (typeof rest.token === "string" ? rest.token : null) ??
+    process.env.SENTROY_ENV_API_KEY ??
+    null
+  if (!token) {
+    fail(
+      "no token. Pass --token=stk_env_... or set SENTROY_ENV_API_KEY in your environment.",
+    )
+  }
+  const baseUrl =
+    (typeof rest.url === "string" ? rest.url : null) ??
+    process.env.SENTROY_ENV_API_URL ??
+    DEFAULT_BASE_URL
+  return { token, baseUrl: baseUrl.replace(/\/+$/, "") }
+}
+
+async function http<T>(
+  shared: SharedOpts,
+  path: string,
+  init?: RequestInit,
+): Promise<T> {
+  const res = await fetch(`${shared.baseUrl}${path}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${shared.token}`,
+      ...(init?.body ? { "Content-Type": "application/json" } : {}),
+      ...(init?.headers ?? {}),
+    },
+  })
+  const text = await res.text()
+  let body: unknown
+  try {
+    body = text ? JSON.parse(text) : null
+  } catch {
+    body = text
+  }
+  if (!res.ok) {
+    const errMsg =
+      body && typeof body === "object" && "error" in body
+        ? String((body as { error: unknown }).error)
+        : `HTTP ${res.status}`
+    throw new Error(`${path}: ${errMsg}`)
+  }
+  return (body as { data?: T })?.data as T
+}
+
+function readFileOrFail(file: string): string {
+  if (!fs.existsSync(file)) {
+    fail(`file not found: ${file}`)
+  }
+  return fs.readFileSync(file, "utf8")
+}
+
+interface Diff {
+  added: DotenvEntry[]
+  updated: { entry: DotenvEntry; remote: RemoteVariable }[]
+  unchanged: { entry: DotenvEntry; remote: RemoteVariable }[]
+  deleted: RemoteVariable[]
+}
+
+function computeDiff(
+  local: DotenvEntry[],
+  remote: RemoteVariable[],
+): Diff {
+  const remoteByKey = new Map(remote.map((v) => [v.key, v]))
+  const added: DotenvEntry[] = []
+  const updated: Diff["updated"] = []
+  const unchanged: Diff["unchanged"] = []
+  for (const e of local) {
+    const r = remoteByKey.get(e.key)
+    if (!r) {
+      added.push(e)
+      continue
+    }
+    if (r.value !== e.value || r.public !== e.public) {
+      updated.push({ entry: e, remote: r })
+    } else {
+      unchanged.push({ entry: e, remote: r })
+    }
+  }
+  const localKeys = new Set(local.map((e) => e.key))
+  const deleted = remote.filter((v) => !localKeys.has(v.key))
+  return { added, updated, unchanged, deleted }
+}
+
+function printDiff(diff: Diff, deleteMissing: boolean): void {
+  for (const e of diff.added) {
+    process.stdout.write(`  ${c.green("+")} ${e.key}\n`)
+  }
+  for (const u of diff.updated) {
+    process.stdout.write(`  ${c.yellow("~")} ${u.entry.key}\n`)
+  }
+  if (deleteMissing) {
+    for (const d of diff.deleted) {
+      process.stdout.write(`  ${c.red("-")} ${d.key}\n`)
+    }
+  } else if (diff.deleted.length > 0) {
+    process.stdout.write(
+      `  ${c.dim(`(${diff.deleted.length} key(s) only in vault, kept — pass --delete-missing to remove)`)}\n`,
+    )
+  }
+}
+
+async function confirm(question: string): Promise<boolean> {
+  if (!process.stdin.isTTY) return false
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  })
+  const answer = await new Promise<string>((resolve) => {
+    rl.question(`${question} [y/N] `, (ans) => {
+      rl.close()
+      resolve(ans.trim().toLowerCase())
+    })
+  })
+  return answer === "y" || answer === "yes"
+}
+
+// ── push ─────────────────────────────────────────────────────────────────
+
+export async function cmdPush(args: string[]): Promise<void> {
+  const { positional, flags } = parseFlags(args)
+  const file = positional[0] ?? DEFAULT_FILE
+  const dryRun = !!flags["dry-run"]
+  const deleteMissing = !!flags["delete-missing"]
+  const shared = resolveSharedOpts(flags)
+
+  const text = readFileOrFail(path.resolve(process.cwd(), file))
+  const parsed = parseDotenv(text)
+  if (parsed.errors.length > 0) {
+    process.stderr.write(`${c.red("✗")} parse errors in ${file}:\n`)
+    for (const err of parsed.errors) {
+      process.stderr.write(`    line ${err.line}: ${err.message}\n`)
+    }
+    process.exit(1)
+  }
+
+  info(`fetching current vault snapshot…`)
+  const remote = await http<FetchResponse>(shared, "/api/env-vault/fetch")
+  const diff = computeDiff(parsed.entries, remote.variables)
+
+  process.stdout.write(
+    `\n${c.bold(remote.project)} ${c.dim("/")} ${c.magenta(remote.environment)} ${c.dim(
+      `(${file} → ${shared.baseUrl})`,
+    )}\n`,
+  )
+  printDiff(diff, deleteMissing)
+  process.stdout.write(
+    `\n  ${c.dim("summary:")} ${diff.added.length} new · ${diff.updated.length} updated · ${diff.unchanged.length} unchanged${
+      deleteMissing ? ` · ${diff.deleted.length} to delete` : ""
+    }\n\n`,
+  )
+
+  if (
+    diff.added.length === 0 &&
+    diff.updated.length === 0 &&
+    (!deleteMissing || diff.deleted.length === 0)
+  ) {
+    ok("nothing to push.")
+    return
+  }
+
+  if (dryRun) {
+    info("dry run — no changes pushed.")
+    return
+  }
+
+  if (deleteMissing && diff.deleted.length > 0) {
+    if (flags.yes) {
+      info(`--yes provided, skipping confirmation for ${diff.deleted.length} delete(s).`)
+    } else if (!process.stdin.isTTY) {
+      fail(
+        `refusing to delete ${diff.deleted.length} key(s) without --yes in a non-interactive shell.`,
+      )
+    } else {
+      const proceed = await confirm(
+        `${c.yellow("⚠")} this will delete ${diff.deleted.length} key(s) from the vault. continue?`,
+      )
+      if (!proceed) {
+        warn("aborted.")
+        return
+      }
+    }
+  }
+
+  const result = await http<PushResponse>(shared, "/api/env-vault/push", {
+    method: "POST",
+    body: JSON.stringify({
+      entries: parsed.entries.map((e) => ({
+        key: e.key,
+        value: e.value,
+        public: e.public,
+        description: e.description,
+      })),
+      deleteMissing,
+    }),
+  })
+  ok(
+    `${result.added} added · ${result.updated} updated · ${result.unchanged} unchanged · ${result.deleted} deleted`,
+  )
+}
+
+// ── pull ─────────────────────────────────────────────────────────────────
+
+export async function cmdPull(args: string[]): Promise<void> {
+  const { positional, flags } = parseFlags(args)
+  const file = positional[0] ?? DEFAULT_FILE
+  const force = !!flags.force
+  const shared = resolveSharedOpts(flags)
+
+  const target = path.resolve(process.cwd(), file)
+  if (fs.existsSync(target) && !force) {
+    fail(`${file} already exists. Pass --force to overwrite.`)
+  }
+
+  info(`fetching from ${shared.baseUrl}…`)
+  const remote = await http<FetchResponse>(shared, "/api/env-vault/fetch")
+  const entries: DotenvEntry[] = remote.variables.map((v) => ({
+    key: v.key,
+    value: v.value,
+    public: v.public,
+    description: null,
+  }))
+  const text = serializeDotenv(entries)
+  fs.writeFileSync(target, text, "utf8")
+  ok(
+    `wrote ${entries.length} variable(s) to ${file} (${remote.project}/${remote.environment})`,
+  )
+}
+
+// ── list ─────────────────────────────────────────────────────────────────
+
+export async function cmdList(args: string[]): Promise<void> {
+  const { flags } = parseFlags(args)
+  const showValues = !!flags.values
+  const publicOnly = !!flags["public-only"]
+  const shared = resolveSharedOpts(flags)
+
+  const endpoint = publicOnly ? "/api/env-vault/public" : "/api/env-vault/fetch"
+  const remote = await http<FetchResponse>(shared, endpoint)
+  process.stdout.write(
+    `${c.bold(remote.project)} ${c.dim("/")} ${c.magenta(remote.environment)} ${c.dim(`(${remote.variables.length} variable(s))`)}\n`,
+  )
+  for (const v of remote.variables) {
+    const tag = v.public ? c.dim(" [public]") : ""
+    if (showValues) {
+      process.stdout.write(`  ${c.cyan(v.key)}=${v.value}${tag}\n`)
+    } else {
+      process.stdout.write(`  ${c.cyan(v.key)}${tag}\n`)
+    }
+  }
+}
+
+// ── diff ─────────────────────────────────────────────────────────────────
+
+export async function cmdDiff(args: string[]): Promise<void> {
+  const { positional, flags } = parseFlags(args)
+  const file = positional[0] ?? DEFAULT_FILE
+  const deleteMissing = !!flags["delete-missing"]
+  const shared = resolveSharedOpts(flags)
+
+  const text = readFileOrFail(path.resolve(process.cwd(), file))
+  const parsed = parseDotenv(text)
+  if (parsed.errors.length > 0) {
+    process.stderr.write(`${c.red("✗")} parse errors in ${file}:\n`)
+    for (const err of parsed.errors) {
+      process.stderr.write(`    line ${err.line}: ${err.message}\n`)
+    }
+    process.exit(1)
+  }
+  const remote = await http<FetchResponse>(shared, "/api/env-vault/fetch")
+  const diff = computeDiff(parsed.entries, remote.variables)
+
+  process.stdout.write(
+    `${c.bold(remote.project)} ${c.dim("/")} ${c.magenta(remote.environment)} ${c.dim(`(${file} vs vault)`)}\n`,
+  )
+  printDiff(diff, deleteMissing)
+  process.stdout.write(
+    `\n  ${c.dim("summary:")} ${diff.added.length} new · ${diff.updated.length} updated · ${diff.unchanged.length} unchanged · ${diff.deleted.length} only in vault\n`,
+  )
+}
+
+// ── flag parser ──────────────────────────────────────────────────────────
+
+interface ParsedArgs {
+  positional: string[]
+  flags: Record<string, string | boolean>
+}
+
+/**
+ * Flags that take a value as a separate token (`--flag value`). All other
+ * `--flag` tokens are booleans. The `--flag=value` form always works
+ * regardless of this list. Keeping this explicit avoids the classic argv
+ * bug where `--dry-run /path/to/file` swallows the positional.
+ */
+const VALUE_FLAGS = new Set(["token", "url"])
+
+function parseFlags(args: string[]): ParsedArgs {
+  const positional: string[] = []
+  const flags: Record<string, string | boolean> = {}
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (!a.startsWith("--")) {
+      positional.push(a)
+      continue
+    }
+    const body = a.slice(2)
+    const eq = body.indexOf("=")
+    if (eq >= 0) {
+      flags[body.slice(0, eq)] = body.slice(eq + 1)
+      continue
+    }
+    if (VALUE_FLAGS.has(body)) {
+      const next = args[i + 1]
+      if (next === undefined || next.startsWith("--")) {
+        fail(`flag --${body} requires a value (use --${body}=value or --${body} value)`)
+      }
+      flags[body] = next
+      i++
+    } else {
+      flags[body] = true
+    }
+  }
+  return { positional, flags }
+}

package/src/cli/index.ts

@@ -0,0 +1,122 @@
+/**
+ * `sentroy` — CLI entry point.
+ *
+ * Subcommand router with no third-party deps. Today only `env` exists;
+ * future subcommands (`mail`, `media`, etc.) hook in here.
+ */
+
+import { cmdPush, cmdPull, cmdList, cmdDiff } from "./env"
+
+const VERSION = "__VERSION__" // replaced at runtime via package.json read
+
+interface SubCommand {
+  description: string
+  handler: (args: string[]) => Promise<void> | void
+}
+
+const ENV_SUBCOMMANDS: Record<string, SubCommand> = {
+  push: {
+    description: "Push a local .env file to the vault (full sync if --delete-missing)",
+    handler: cmdPush,
+  },
+  pull: {
+    description: "Fetch the vault scope and write to a local .env file",
+    handler: cmdPull,
+  },
+  list: {
+    description: "Print every key in the vault scope (--values to include values, --public-only)",
+    handler: cmdList,
+  },
+  diff: {
+    description: "Show what would change if you pushed the local .env file",
+    handler: cmdDiff,
+  },
+}
+
+function readPackageVersion(): string {
+  if (VERSION !== "__VERSION__") return VERSION
+  // Walk up from this file: dist/cli/index.js → dist/cli → dist → package.
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { version } = require("../../package.json") as { version: string }
+    return version
+  } catch {
+    return "unknown"
+  }
+}
+
+function showHelp(): void {
+  const v = readPackageVersion()
+  process.stdout.write(
+    `\nsentroy ${v} — Sentroy CLI\n\n` +
+      `USAGE\n` +
+      `  sentroy <command> [args] [flags]\n\n` +
+      `COMMANDS\n` +
+      `  env push  [<file>]     ${ENV_SUBCOMMANDS.push.description}\n` +
+      `  env pull  [<file>]     ${ENV_SUBCOMMANDS.pull.description}\n` +
+      `  env list               ${ENV_SUBCOMMANDS.list.description}\n` +
+      `  env diff  [<file>]     ${ENV_SUBCOMMANDS.diff.description}\n\n` +
+      `GLOBAL FLAGS\n` +
+      `  --token=stk_env_...    Vault token (default: $SENTROY_ENV_API_KEY)\n` +
+      `  --url=https://...      Sentroy core URL (default: $SENTROY_ENV_API_URL or https://sentroy.com)\n\n` +
+      `ENV PUSH FLAGS\n` +
+      `  --delete-missing       Remove vault keys not present in the local file (full sync)\n` +
+      `  --dry-run              Print the diff but do not write\n` +
+      `  --yes                  Skip the delete-confirmation prompt (CI-friendly)\n\n` +
+      `ENV PULL FLAGS\n` +
+      `  --force                Overwrite the file if it already exists\n\n` +
+      `ENV LIST FLAGS\n` +
+      `  --values               Include values (default: keys only)\n` +
+      `  --public-only          Only variables marked public\n\n` +
+      `EXAMPLES\n` +
+      `  sentroy env push .env.production --delete-missing\n` +
+      `  sentroy env pull .env --force\n` +
+      `  sentroy env diff .env.production --delete-missing\n` +
+      `  sentroy env list --values --public-only\n\n` +
+      `Token scope (project + environment) is implicit — generate one in the\n` +
+      `Sentroy vault dashboard.\n\n`,
+  )
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2)
+  if (
+    argv.length === 0 ||
+    argv[0] === "-h" ||
+    argv[0] === "--help" ||
+    argv[0] === "help"
+  ) {
+    showHelp()
+    return
+  }
+  if (argv[0] === "-v" || argv[0] === "--version") {
+    process.stdout.write(`${readPackageVersion()}\n`)
+    return
+  }
+
+  const cmd = argv[0]
+  if (cmd === "env") {
+    const sub = argv[1]
+    const handler = sub ? ENV_SUBCOMMANDS[sub] : undefined
+    if (!handler) {
+      process.stderr.write(
+        `unknown env subcommand: ${sub ?? "<missing>"}\n` +
+          `available: ${Object.keys(ENV_SUBCOMMANDS).join(", ")}\n`,
+      )
+      process.exit(1)
+    }
+    await handler.handler(argv.slice(2))
+    return
+  }
+
+  process.stderr.write(
+    `unknown command: ${cmd}\nrun \`sentroy --help\` for usage.\n`,
+  )
+  process.exit(1)
+}
+
+main().catch((err: unknown) => {
+  const msg = err instanceof Error ? err.message : String(err)
+  process.stderr.write(`\n\x1b[31m✗\x1b[0m ${msg}\n`)
+  process.exit(1)
+})

package/src/vault/index.ts

@@ -179,6 +179,38 @@ export async function getEnvOrThrow(key: string): Promise<string> {
   return v
 }
 
+/**
+ * Migration helper — vault'tan oku, yoksa `process.env` fallback.
+ *
+ * Sentroy app'lerini kademeli olarak `process.env` → vault'a çevirirken
+ * "her ikisi de çalışsın" senaryosu için. Vault doldurulmamış / token
+ * eksik / fetch fail dönerse sessizce `process.env[key]`'e döner — eski
+ * deploy ile yeni kod bir arada çalışabilir.
+ *
+ * **Migration tamamlandıktan sonra** çağrı sitelerini `getEnv()` ya da
+ * `getEnvOrThrow()`'a çevir; fallback'i bırakmak silently process.env
+ * sızıntısı riskini taşır (kullanıcı vault'tan key'i sildi sansa bile
+ * eski process.env değeri etkili olur).
+ *
+ * Bootstrap path için (`SENTROY_ENV_API_KEY` set değil) doğrudan
+ * `process.env`'e döner — vault fetch denemez. Bu önemli: Sentroy app'i
+ * vault'sız boot edilebilir.
+ */
+export async function getEnvWithFallback(
+  key: string,
+): Promise<string | undefined> {
+  // Token yoksa bypass — vault fetch denemeyelim, log spam etmeyelim.
+  const apiKey = resolvedApiKey ?? readEnv("SENTROY_ENV_API_KEY")
+  if (!apiKey) return readEnv(key)
+  try {
+    const v = await getEnv(key)
+    if (v !== undefined) return v
+  } catch {
+    // Fetch fail / network down / 401 → sessizce fallback
+  }
+  return readEnv(key)
+}
+
 /** Tüm env'leri map olarak döner (dump için kullanışlı). */
 export async function getAllEnvs(): Promise<Record<string, string>> {
   const c = await ensureCache()
@@ -196,3 +228,131 @@ export async function getPublicEnvs(): Promise<Record<string, string>> {
   }
   return out
 }
+
+// ── Webhook handler ─────────────────────────────────────────────────────
+
+export interface VaultWebhookPayload {
+  event: "vault.variable.changed"
+  project: string
+  environment: string
+  action: "create" | "update" | "delete"
+  /** Etkilenen key'ler — bulk push'ta birden fazla. */
+  keys: string[]
+  /** Unix ms. */
+  timestamp: number
+}
+
+export interface CreateVaultWebhookHandlerOptions {
+  /**
+   * Sentroy vault dashboard'dan aldığın webhook secret (`whsec_...`).
+   * Receiver bu secret'la HMAC-SHA256 imzayı doğrular; hatalıysa 401 döner.
+   */
+  secret: string
+  /**
+   * Imzayı doğruladıktan sonra çağrılır. Default davranış:
+   *   `await refreshEnvCache()` — bir sonraki getEnv() taze değerleri çeker.
+   * Custom logic için override et (örn. tek bir key'i targeted invalidate).
+   */
+  onChange?: (payload: VaultWebhookPayload) => Promise<void> | void
+  /**
+   * Replay attack'lere karşı body'nin timestamp'i ile şu an arasındaki
+   * maksimum tolerans (ms). Default 5 dk. Sıfır ise check kapalı.
+   */
+  maxAgeMs?: number
+}
+
+const DEFAULT_MAX_AGE_MS = 5 * 60 * 1000
+
+async function timingSafeEqualHex(a: string, b: string): Promise<boolean> {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  }
+  return diff === 0
+}
+
+async function hmacSha256Hex(secret: string, body: string): Promise<string> {
+  // Web Crypto — Node 18+ + browser ikisi de destekler.
+  const encoder = new TextEncoder()
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  )
+  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(body))
+  const bytes = new Uint8Array(sig)
+  let hex = ""
+  for (const b of bytes) hex += b.toString(16).padStart(2, "0")
+  return hex
+}
+
+/**
+ * Bir Sentroy vault webhook receiver'ı için Request → Response handler
+ * üretir. Next.js App Router'da:
+ *
+ *   // app/api/sentroy/vault-webhook/route.ts
+ *   import { createVaultWebhookHandler } from "@sentroy-co/client-sdk/vault"
+ *   export const POST = createVaultWebhookHandler({
+ *     secret: process.env.SENTROY_VAULT_WEBHOOK_SECRET!,
+ *   })
+ *
+ * Default davranış: imza doğruysa cache'i invalidate eder ve 200 döner.
+ * Hatalı/eksik imza → 401, eski timestamp → 401, body parse hatası → 400.
+ */
+export function createVaultWebhookHandler(
+  options: CreateVaultWebhookHandlerOptions,
+): (request: Request) => Promise<Response> {
+  const maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS
+  return async (request: Request) => {
+    const sigHeader = request.headers.get("x-sentroy-signature") || ""
+    const match = sigHeader.match(/^sha256=([a-f0-9]+)$/i)
+    if (!match) {
+      return new Response("missing or malformed X-Sentroy-Signature header", {
+        status: 401,
+      })
+    }
+    const providedSig = match[1].toLowerCase()
+    const body = await request.text()
+    const expected = await hmacSha256Hex(options.secret, body)
+    if (!(await timingSafeEqualHex(providedSig, expected))) {
+      return new Response("signature mismatch", { status: 401 })
+    }
+
+    let payload: VaultWebhookPayload
+    try {
+      payload = JSON.parse(body) as VaultWebhookPayload
+    } catch {
+      return new Response("invalid JSON body", { status: 400 })
+    }
+
+    if (maxAgeMs > 0) {
+      const age = Date.now() - (payload.timestamp ?? 0)
+      if (!Number.isFinite(age) || age < 0 || age > maxAgeMs) {
+        return new Response("payload timestamp outside acceptable window", {
+          status: 401,
+        })
+      }
+    }
+
+    try {
+      if (options.onChange) {
+        await options.onChange(payload)
+      } else {
+        await refreshEnvCache()
+      }
+    } catch (err) {
+      return new Response(
+        `handler error: ${err instanceof Error ? err.message : String(err)}`,
+        { status: 500 },
+      )
+    }
+
+    return new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+}