@citeark/agent 0.3.20

package/src/gcp/auth.mjs

@@ -0,0 +1,106 @@
+import { captureProcess } from "../process.mjs";
+import { CiteArkError } from "../util.mjs";
+import { executeObservedExternalRequest } from "../observability/event-contract.mjs";
+
+const METADATA_TOKEN_URL = "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token";
+// accessToken() refreshes cached credentials 60 seconds early. A one-minute
+// gcloud cache therefore had an effective lifetime of zero and retried the
+// unavailable GCE metadata endpoint before every local API request.
+const GCLOUD_TOKEN_CACHE_MS = 5 * 60_000;
+
+export class GoogleAccessTokenProvider {
+  constructor({
+    accessToken,
+    fetchImpl = fetch,
+    captureProcessImpl = captureProcess,
+    now = () => Date.now(),
+    observe,
+    correlation,
+  } = {}) {
+    this.explicitAccessToken = nonEmpty(accessToken) ?? nonEmpty(process.env.GOOGLE_OAUTH_ACCESS_TOKEN);
+    this.fetchImpl = fetchImpl;
+    this.captureProcessImpl = captureProcessImpl;
+    this.now = now;
+    this.observe = observe;
+    this.correlation = correlation;
+    this.cached = null;
+  }
+
+  async headers() {
+    return { Authorization: `Bearer ${await this.accessToken()}` };
+  }
+
+  invalidate() {
+    this.cached = null;
+  }
+
+  async accessToken() {
+    if (this.explicitAccessToken) return this.explicitAccessToken;
+    if (this.cached && this.cached.expiresAt - 60_000 > this.now()) return this.cached.value;
+
+    const metadata = await this.#fromMetadata();
+    if (metadata) {
+      this.cached = metadata;
+      return metadata.value;
+    }
+    const gcloud = await this.#fromGcloud();
+    if (gcloud) {
+      // `gcloud auth print-access-token` does not report the token's actual
+      // remaining lifetime. Keep this cache deliberately short and let the
+      // REST layer invalidate it immediately when Google returns 401.
+      this.cached = { value: gcloud, expiresAt: this.now() + GCLOUD_TOKEN_CACHE_MS };
+      return gcloud;
+    }
+    throw new CiteArkError(
+      "无法取得 Google Cloud 访问令牌。请在 GCP 运行身份中执行，或先运行 gcloud auth application-default login。",
+    );
+  }
+
+  async #fromMetadata() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 1_000);
+    timeout.unref?.();
+    try {
+      const response = await executeObservedExternalRequest({
+        request: async () => await this.fetchImpl(METADATA_TOKEN_URL, {
+          headers: { "Metadata-Flavor": "Google" },
+          signal: controller.signal,
+        }),
+        observe: this.observe,
+        component: "gcp_auth",
+        service: "metadata.google.internal",
+        operation: "service_account_token",
+        url: METADATA_TOKEN_URL,
+        correlation: this.correlation,
+      });
+      if (!response.ok) return null;
+      const payload = await response.json();
+      if (!nonEmpty(payload?.access_token)) return null;
+      return {
+        value: payload.access_token,
+        expiresAt: this.now() + Math.max(60, Number(payload.expires_in) || 3600) * 1000,
+      };
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  async #fromGcloud() {
+    const environment = { ...process.env, CLOUDSDK_CORE_DISABLE_PROMPTS: "1" };
+    for (const args of [
+      ["auth", "application-default", "print-access-token"],
+      ["auth", "print-access-token"],
+    ]) {
+      const result = await this.captureProcessImpl("gcloud", args, { env: environment }).catch(() => null);
+      const token = nonEmpty(result?.code === 0 ? result.stdout : null);
+      if (token) return token;
+    }
+    return null;
+  }
+}
+
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/src/gcp/batch-client.mjs

@@ -0,0 +1,120 @@
+import { watchRemoteTranscript } from '../terminal/remote-stream.mjs';
+import { googleJsonRequest } from "./rest.mjs";
+import { CiteArkError } from "../util.mjs";
+
+const TERMINAL_STATES = new Set(["SUCCEEDED", "FAILED", "CANCELLED"]);
+
+export class GcpBatchClient {
+  constructor({
+    projectId,
+    region,
+    auth,
+    fetchImpl = fetch,
+    sleep = defaultSleep,
+    observe,
+    correlation,
+    budget,
+  } = {}) {
+    this.projectId = required(projectId, "projectId");
+    this.region = required(region, "region");
+    this.auth = auth;
+    this.fetchImpl = fetchImpl;
+    this.sleep = sleep;
+    this.observe = observe;
+    this.correlation = correlation;
+    this.budget = budget;
+  }
+
+  jobName(jobId) {
+    return `projects/${this.projectId}/locations/${this.region}/jobs/${jobId}`;
+  }
+
+  async createJob(jobId, job) {
+    await this.budget?.beforeCreate(jobId, job, { projectId: this.projectId, region: this.region });
+    const url = new URL(`https://batch.googleapis.com/v1/projects/${encodeURIComponent(this.projectId)}/locations/${encodeURIComponent(this.region)}/jobs`);
+    url.searchParams.set("job_id", jobId);
+    return await googleJsonRequest({
+      url,
+      auth: this.auth,
+      fetchImpl: this.fetchImpl,
+      method: "POST",
+      body: job,
+      observe: this.observe,
+      operation: "batch_create_job",
+      correlation: { ...this.correlation, gcpJobId: jobId },
+    });
+  }
+
+  async findJob(name) {
+    const job = await googleJsonRequest({ url: `https://batch.googleapis.com/v1/${name}`, auth: this.auth,
+      fetchImpl: this.fetchImpl, acceptedStatuses: [404], observe: this.observe, operation: "batch_find_recovery_job",
+      correlation: { ...this.correlation, gcpJobName: name } });
+    if (job?.error?.code === 404) return null;
+    if (job?.name) await this.budget?.adopt?.(job);
+    return job;
+  }
+
+  async getJob(name) {
+    return await googleJsonRequest({
+      url: `https://batch.googleapis.com/v1/${name}`,
+      auth: this.auth,
+      fetchImpl: this.fetchImpl,
+      observe: this.observe,
+      operation: "batch_get_job",
+      correlation: { ...this.correlation, gcpJobName: name },
+    });
+  }
+
+  async deleteJob(name) {
+    return await googleJsonRequest({
+      url: `https://batch.googleapis.com/v1/${name}`,
+      auth: this.auth,
+      fetchImpl: this.fetchImpl,
+      method: "DELETE",
+      acceptedStatuses: [404],
+      observe: this.observe,
+      operation: "batch_delete_job",
+      correlation: { ...this.correlation, gcpJobName: name },
+    });
+  }
+
+  async waitForTerminal(name, {
+    timeoutMs,
+    pollIntervalMs = 10_000,
+    onState = () => {},
+    onPoll = () => {},
+    liveOutput,
+  }) {
+    const stopOutput = liveOutput ? watchRemoteTranscript(liveOutput) : async () => {};
+    try {
+      const deadline = Date.now() + timeoutMs;
+      let lastState = null;
+      while (Date.now() < deadline) {
+        const job = await this.getJob(name);
+        const state = job?.status?.state ?? "STATE_UNSPECIFIED";
+        await onPoll(job, state);
+        if (state !== lastState) {
+          lastState = state;
+          await onState(state, job);
+        }
+        if (TERMINAL_STATES.has(state)) {
+          await this.budget?.onTerminal(job);
+          return job;
+        }
+        await this.budget?.onPoll?.(job, () => this.deleteJob(name));
+        await this.sleep(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now())));
+      }
+      if (this.budget) await this.deleteJob(name);
+      throw new CiteArkError(`Timed out waiting for GCP Batch job: ${name}`);
+    } finally { await stopOutput(); }
+  }
+}
+
+function required(value, field) {
+  if (typeof value !== "string" || !value.trim()) throw new CiteArkError(`GCP Batch 缺少 ${field}`);
+  return value.trim();
+}
+
+function defaultSleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/src/gcp/resource-discovery.mjs

@@ -0,0 +1,177 @@
+import { GoogleAccessTokenProvider } from "./auth.mjs";
+import { googleJsonRequest } from "./rest.mjs";
+import { sha256Value } from "../util.mjs";
+
+export const GCP_DISCOVERY_READ_PERMISSIONS = [
+  "compute.machineTypes.list", "compute.acceleratorTypes.list",
+  "compute.regions.list", "compute.projects.get",
+];
+const GPU_SPECS = {
+  "nvidia-tesla-k80": ["K80", 12], "nvidia-tesla-p4": ["P4", 8],
+  "nvidia-tesla-p100": ["P100", 16], "nvidia-tesla-v100": ["V100", 16],
+  "nvidia-tesla-t4": ["T4", 16], "nvidia-l4": ["L4", 24],
+  "nvidia-tesla-a100": ["A100", 40], "nvidia-a100-80gb": ["A100 80GB", 80],
+  "nvidia-h100-80gb": ["H100", 80], "nvidia-h100-mega-80gb": ["H100 Mega", 80],
+  "nvidia-h200-141gb": ["H200", 141], "nvidia-b200": ["B200", 180],
+};
+const GPU_SPEC_SOURCE = "https://cloud.google.com/compute/docs/gpus";
+const tail = (value) => String(value ?? "").split("/").at(-1);
+
+// Discovery only reads provider metadata. Neither quota nor a successful IAM
+// probe is a reservation, a runtime validation, or proof of physical capacity.
+export async function discoverGcpResources({ projectId, auth,
+  fetchImpl = fetch, observe, now = () => Date.now(), ttlMs = 30 * 60_000 } = {}) {
+  if (!projectId || !/^[a-z][a-z0-9-]{4,61}[a-z0-9]$/.test(projectId)) throw new TypeError("资源发现需要 GCP projectId");
+  auth ??= new GoogleAccessTokenProvider({ fetchImpl, observe });
+  await auth.headers();
+  const startedAt = now();
+  const deadline = AbortSignal.timeout(180_000);
+  const request = (url, options = {}) => googleJsonRequest({ url, auth, observe,
+    fetchImpl: (target, init) => fetchImpl(target, { ...init,
+      signal: AbortSignal.any([deadline, AbortSignal.timeout(30_000)]) }),
+    operation: "compute_resource_discovery", ...options });
+  async function pages(url, extract) {
+    const rows = []; const warnings = []; const seen = new Set();
+    for (;;) {
+      const page = await request(url.toString());
+      rows.push(...extract(page));
+      if (page.warning) warnings.push(page.warning);
+      for (const scope of Object.values(page.items ?? {})) {
+        if (scope?.warning && scope.warning.code !== "NO_RESULTS_ON_PAGE") warnings.push(scope.warning);
+      }
+      if (!page.nextPageToken) return { rows, warnings };
+      if (seen.has(page.nextPageToken)) throw Error("资源发现分页游标重复");
+      seen.add(page.nextPageToken);
+      url.searchParams.set("pageToken", page.nextPageToken);
+    }
+  }
+  const base = `https://compute.googleapis.com/compute/v1/projects/${projectId}`;
+  const aggregated = (kind, fields) => {
+    const url = new URL(`${base}/aggregated/${kind}`);
+    url.searchParams.set("maxResults", "500");
+    url.searchParams.set("returnPartialSuccess", "true");
+    url.searchParams.set("fields", `nextPageToken,warning,items/*/${kind}(${fields}),items/*/warning`);
+    return pages(url, (page) => Object.values(page.items ?? {}).flatMap((scope) => scope[kind] ?? []));
+  };
+  const sources = {
+    machineTypes: () => aggregated("machineTypes", "name,guestCpus,memoryMb,zone,accelerators,architecture,deprecated"),
+    acceleratorTypes: () => aggregated("acceleratorTypes", "name,description,zone,maximumCardsPerInstance,deprecated"),
+    regions: () => pages(new URL(`${base}/regions?maxResults=500`), (page) => page.items ?? []),
+    projectQuotas: () => request(base),
+    permissions: () => request(`https://cloudresourcemanager.googleapis.com/v1/projects/${projectId}:testIamPermissions`, {
+      method: "POST", body: { permissions: [...GCP_DISCOVERY_READ_PERMISSIONS, "batch.jobs.create"] },
+    }),
+    prices: () => pages(new URL("https://cloudbilling.googleapis.com/v1/services/6F81-5844-456A/skus?currencyCode=USD&pageSize=5000"), (page) => page.skus ?? []),
+  };
+  const keys = Object.keys(sources);
+  const results = await Promise.allSettled(keys.map((key) => sources[key]()));
+  const data = {}; const checks = {};
+  results.forEach((result, index) => {
+    const key = keys[index];
+    if (result.status === "fulfilled") {
+      data[key] = result.value;
+      checks[key] = { status: result.value.warnings?.length ? "partial" : "ok", warnings: result.value.warnings ?? [] };
+    } else {
+      checks[key] = { status: "unknown", error: String(result.reason?.message ?? result.reason).slice(0, 1200) };
+    }
+  });
+  const machines = groupByZones(data.machineTypes?.rows ?? [], (m) => ({
+    name: m.name, cpuCores: m.guestCpus, memoryGb: m.memoryMb / 1024,
+    architecture: m.architecture ?? "unknown", deprecated: m.deprecated?.state ?? null,
+    accelerators: (m.accelerators ?? []).map((g) => ({ type: tail(g.guestAcceleratorType), count: Number(g.guestAcceleratorCount) })),
+  }));
+  const accelerators = groupByZones(data.acceleratorTypes?.rows ?? [], (a) => ({
+    name: a.name, description: a.description, maximumCardsPerInstance: a.maximumCardsPerInstance,
+    type: GPU_SPECS[a.name]?.[0] ?? a.name, vramGb: GPU_SPECS[a.name]?.[1] ?? null,
+    specificationSource: GPU_SPECS[a.name] ? GPU_SPEC_SOURCE : null,
+    deprecated: a.deprecated?.state ?? null,
+  }));
+  const permissions = data.permissions?.permissions ?? [];
+  const snapshot = {
+    schemaVersion: "0.1", kind: "citeark.compute-resource-discovery", provider: "gcp", projectId,
+    observedAt: new Date(startedAt).toISOString(), expiresAt: new Date(startedAt + ttlMs).toISOString(),
+    status: Object.values(checks).every((c) => c.status === "ok") ? "complete" : "partial",
+    sources: checks, capacity: { status: "unknown", reason: "Listing and quotas do not establish live capacity; allocation is confirmed only by the provider." },
+    inventory: { machines, accelerators },
+    regions: (data.regions?.rows ?? []).map((r) => ({ name: r.name, status: r.status,
+      zones: (r.zones ?? []).map(tail), quotas: normalizeQuotas(r.quotas) })),
+    projectQuotas: normalizeQuotas(data.projectQuotas?.quotas),
+    permissions: { status: checks.permissions.status, granted: permissions,
+      missing: checks.permissions.status === "ok" ? [...GCP_DISCOVERY_READ_PERMISSIONS, "batch.jobs.create"].filter((p) => !permissions.includes(p)) : [],
+      scope: "Caller permissions only; excludes service-agent, service-account, organization-policy and runtime checks." },
+    prices: normalizePrices(data.prices?.rows ?? [], startedAt),
+  };
+  return { ...snapshot, digest: `sha256:${sha256Value(snapshot)}` };
+}
+
+function groupByZones(rows, project) {
+  const groups = new Map();
+  for (const row of rows) {
+    const value = project(row); const key = JSON.stringify(value);
+    const entry = groups.get(key) ?? { ...value, zones: [] };
+    const zone = tail(row.zone);
+    if (zone && !entry.zones.includes(zone)) entry.zones.push(zone);
+    groups.set(key, entry);
+  }
+  return [...groups.values()].map((g) => ({ ...g, zones: g.zones.sort() })).sort((a, b) => a.name.localeCompare(b.name));
+}
+function normalizeQuotas(quotas = []) {
+  return quotas.map((q) => ({ metric: q.metric, limit: q.limit, usage: q.usage,
+    remaining: Number.isFinite(q.limit) && Number.isFinite(q.usage) ? Math.max(0, q.limit - q.usage) : null }));
+}
+
+// Exact ordinary on-demand SKU descriptions avoid accidental Spot, commitment,
+// DWS or sole-tenancy prices. Unknown and ambiguous prices stay unknown.
+export function normalizePrices(skus, at = Date.now()) {
+  return skus.flatMap((sku) => {
+    if (sku.category?.usageType !== "OnDemand") return [];
+    const match = /^(E2 Instance|N2 Instance|N1 Predefined Instance|G2 Instance) (Core|Ram) running in /i.exec(sku.description ?? "");
+    const gpu = /^Nvidia (Tesla T4|L4) GPU running in /i.exec(sku.description ?? "");
+    if (!match && !gpu) return [];
+    const info = (sku.pricingInfo ?? []).filter((p) => !p.effectiveTime || Date.parse(p.effectiveTime) <= at)
+      .sort((a, b) => Date.parse(b.effectiveTime ?? 0) - Date.parse(a.effectiveTime ?? 0))[0];
+    const expression = info?.pricingExpression;
+    const tier = expression?.tieredRates?.length === 1 ? expression.tieredRates[0] : null;
+    if (!tier || Number(tier.startUsageAmount) !== 0 || tier.unitPrice?.currencyCode !== "USD") return [];
+    const component = gpu ? "gpu" : match[2].toLowerCase() === "core" ? "cpu" : "memory";
+    if (expression.usageUnit !== (component === "memory" ? "GiBy.h" : "h")) return [];
+    const unitUsd = Number(tier.unitPrice.units ?? 0) + Number(tier.unitPrice.nanos ?? 0) / 1e9;
+    if (!Number.isFinite(unitUsd) || unitUsd <= 0) return [];
+    return [{ skuId: sku.skuId, description: sku.description, regions: sku.serviceRegions ?? [], component,
+      family: gpu ? (gpu[1].toUpperCase().includes("T4") ? "T4" : "L4") : match[1].split(" ")[0].toLowerCase(),
+      unitUsd, effectiveTime: info.effectiveTime ?? null, source: "Google Cloud Billing Catalog API" }];
+  });
+}
+
+export function discoveredGcpPrice(snapshot, { family, region, cpuCores, memoryGb, gpu }) {
+  const parts = [[family, "cpu", cpuCores], [family, "memory", memoryGb]];
+  if (gpu) parts.push([gpu.type, "gpu", gpu.count]);
+  const lines = [];
+  for (const [key, component, units] of parts) {
+    const prices = snapshot.prices.filter((p) => p.family === key && p.component === component && p.regions.includes(region));
+    if (prices.length !== 1 || !Number.isFinite(units) || units <= 0) return null;
+    lines.push({ skuId: prices[0].skuId, units, unitUsd: prices[0].unitUsd, effectiveTime: prices[0].effectiveTime });
+  }
+  return { hourlyUsd: lines.reduce((total, p) => total + p.units * p.unitUsd, 0), lines,
+    source: "Google Cloud Billing Catalog API", region, provisioningModel: "STANDARD", observedAt: snapshot.observedAt };
+}
+
+export function gcpDiscoverySummary(snapshot) {
+  const families = new Map();
+  for (const m of snapshot.inventory.machines) {
+    const family = m.name.split("-")[0];
+    const f = families.get(family) ?? { family, machineTypes: 0, cpuCores: [Infinity, 0], memoryGb: [Infinity, 0], regions: new Set() };
+    f.machineTypes++;
+    f.cpuCores = [Math.min(f.cpuCores[0], m.cpuCores), Math.max(f.cpuCores[1], m.cpuCores)];
+    f.memoryGb = [Math.min(f.memoryGb[0], m.memoryGb), Math.max(f.memoryGb[1], m.memoryGb)];
+    m.zones.forEach((z) => f.regions.add(z.replace(/-[a-z]$/, "")));
+    families.set(family, f);
+  }
+  return { digest: snapshot.digest, observedAt: snapshot.observedAt, expiresAt: snapshot.expiresAt,
+    status: snapshot.status, projectId: snapshot.projectId, sources: snapshot.sources, capacity: snapshot.capacity,
+    permissions: snapshot.permissions, projectQuotas: snapshot.projectQuotas.filter(q => /^(CPUS|GPUS)_ALL_REGIONS$/.test(q.metric)),
+    machineFamilies: [...families.values()].map((f) => ({ ...f, regions: [...f.regions].sort() })),
+    accelerators: snapshot.inventory.accelerators.map(({ zones, ...a }) => ({ ...a, regions: [...new Set(zones.map((z) => z.replace(/-[a-z]$/, "")))].sort() })),
+    scope: "Provider inventory is broader than executable profiles. Missing price, runtime support, policy or quota prevents automatic admission; unknown live capacity is not a scientific blocker.",
+  };
+}

package/src/gcp/rest.mjs

@@ -0,0 +1,82 @@
+import { CiteArkError } from "../util.mjs";
+import {
+  emitStructuredObservation,
+  executeObservedExternalRequest,
+} from "../observability/event-contract.mjs";
+
+export async function googleJsonRequest({
+  url,
+  auth,
+  fetchImpl = fetch,
+  method = "GET",
+  body,
+  acceptedStatuses = [],
+  observe = emitStructuredObservation,
+  operation = "google_cloud_api",
+  correlation,
+}) {
+  let attempt = 0;
+  const request = async () => {
+    attempt += 1;
+    return executeObservedExternalRequest({
+      request: async () => await fetchImpl(url, {
+        method,
+        headers: {
+          ...(await auth.headers()),
+          Accept: "application/json",
+          ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+      }),
+      observe,
+      component: "gcp_client",
+      service: new URL(url).hostname,
+      operation,
+      method,
+      url,
+      attempt,
+      maxAttempts: 2,
+      retryableStatus: (status) => status === 401
+        || new Set([408, 425, 429, 500, 502, 503, 504]).has(status),
+      correlation,
+    });
+  };
+  let response = await request();
+  if (response.status === 401 && typeof auth.invalidate === "function") {
+    auth.invalidate();
+    await response.body?.cancel?.().catch?.(() => {});
+    response = await request();
+  }
+  if (!response.ok && !acceptedStatuses.includes(response.status)) {
+    throw await googleApiError(response, method, url);
+  }
+  if (response.status === 204 || response.headers.get("content-length") === "0") return null;
+  const text = await response.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new CiteArkError(`Google Cloud API 返回了无效 JSON：${method} ${redactUrl(url)}`, { cause: error });
+  }
+}
+
+export async function googleApiError(response, method, url) {
+  let detail = "";
+  try {
+    const payload = await response.json();
+    detail = payload?.error?.message ?? payload?.message ?? "";
+  } catch {
+    detail = await response.text().catch(() => "");
+  }
+  return new CiteArkError(
+    `Google Cloud API 请求失败（${response.status}）：${method} ${redactUrl(url)}${detail ? `\n${detail}` : ""}`,
+  );
+}
+
+function redactUrl(value) {
+  const url = new URL(value);
+  for (const key of [...url.searchParams.keys()]) {
+    if (/token|key|secret/i.test(key)) url.searchParams.set(key, "<redacted>");
+  }
+  return url.toString();
+}

package/src/gcp/secret-manager.mjs

@@ -0,0 +1,34 @@
+import { GoogleAccessTokenProvider } from "./auth.mjs";
+import { googleJsonRequest } from "./rest.mjs";
+import { CiteArkError } from "../util.mjs";
+
+export class GcpSecretManagerClient {
+  constructor({ auth, fetchImpl = fetch } = {}) {
+    this.auth = auth ?? new GoogleAccessTokenProvider();
+    this.fetchImpl = fetchImpl;
+  }
+
+  async accessVersion(resource) {
+    const name = requiredSecretVersion(resource);
+    const payload = await googleJsonRequest({
+      url: `https://secretmanager.googleapis.com/v1/${name}:access`,
+      auth: this.auth,
+      fetchImpl: this.fetchImpl,
+    });
+    const encoded = payload?.payload?.data;
+    if (typeof encoded !== "string" || !encoded) {
+      throw new CiteArkError("Secret Manager 未返回密钥内容");
+    }
+    return Buffer.from(encoded, "base64").toString("utf8");
+  }
+}
+
+function requiredSecretVersion(value) {
+  if (
+    typeof value !== "string"
+    || !/^projects\/[^/]+\/secrets\/[^/]+\/versions\/[^/]+$/.test(value.trim())
+  ) {
+    throw new TypeError("Secret Manager 版本必须是 projects/.../secrets/.../versions/... 格式");
+  }
+  return value.trim();
+}

package/src/gcp/signed-url.mjs

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+
+import { googleApiError } from "./rest.mjs";
+import { CiteArkError } from "../util.mjs";
+
+const SIGNING_ALGORITHM = "GOOG4-RSA-SHA256";
+const SIGNING_TERMINATOR = "goog4_request";
+const MAXIMUM_EXPIRATION_SECONDS = 7 * 24 * 60 * 60;
+
+export class GcpIamCredentialsSigner {
+  constructor({ auth, fetchImpl = fetch } = {}) {
+    if (!auth || typeof auth.headers !== "function") {
+      throw new TypeError("IAM Credentials signer 需要 Google 认证提供器");
+    }
+    this.auth = auth;
+    this.fetchImpl = fetchImpl;
+  }
+
+  async signBlob({ serviceAccount, payload }) {
+    const account = required(serviceAccount, "serviceAccount");
+    const bytes = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload), "utf8");
+    const url = new URL(
+      `https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${encodeURIComponent(account)}:signBlob`,
+    );
+    const response = await this.fetchImpl(url, {
+      method: "POST",
+      headers: {
+        ...await this.auth.headers(),
+        "content-type": "application/json; charset=UTF-8",
+      },
+      body: JSON.stringify({ payload: bytes.toString("base64") }),
+    });
+    if (!response.ok) throw await googleApiError(response, "POST", url);
+    const signed = Buffer.from(String((await response.json())?.signedBlob ?? ""), "base64");
+    if (!signed.length) throw new CiteArkError("IAM Credentials signBlob 没有返回签名");
+    return signed;
+  }
+}
+
+export async function createGcsV4SignedReadUrl({
+  bucket,
+  object,
+  serviceAccount,
+  signer,
+  expiresSeconds = 30 * 60,
+  now = new Date(),
+}) {
+  const normalizedBucket = required(bucket, "bucket");
+  const normalizedObject = required(object, "object");
+  const account = required(serviceAccount, "serviceAccount");
+  if (!signer || typeof signer.signBlob !== "function") {
+    throw new TypeError("GCS 签名 URL 需要 signBlob 实现");
+  }
+  const expiration = positiveInteger(expiresSeconds, "expiresSeconds");
+  if (expiration > MAXIMUM_EXPIRATION_SECONDS) {
+    throw new TypeError("GCS V4 签名 URL 有效期不能超过 7 天");
+  }
+  const instant = now instanceof Date ? now : new Date(now);
+  if (!Number.isFinite(instant.getTime())) throw new TypeError("GCS 签名时间无效");
+
+  const timestamp = instant.toISOString().replaceAll(/[-:]|\.\d{3}/g, "");
+  const date = timestamp.slice(0, 8);
+  const credentialScope = `${date}/auto/storage/${SIGNING_TERMINATOR}`;
+  const canonicalUri = `/${encodePathSegment(normalizedBucket)}/${normalizedObject
+    .split("/")
+    .map(encodePathSegment)
+    .join("/")}`;
+  const canonicalQuery = canonicalQueryString({
+    "X-Goog-Algorithm": SIGNING_ALGORITHM,
+    "X-Goog-Credential": `${account}/${credentialScope}`,
+    "X-Goog-Date": timestamp,
+    "X-Goog-Expires": String(expiration),
+    "X-Goog-SignedHeaders": "host",
+  });
+  const canonicalRequest = [
+    "GET",
+    canonicalUri,
+    canonicalQuery,
+    "host:storage.googleapis.com\n",
+    "host",
+    "UNSIGNED-PAYLOAD",
+  ].join("\n");
+  const stringToSign = [
+    SIGNING_ALGORITHM,
+    timestamp,
+    credentialScope,
+    createHash("sha256").update(canonicalRequest).digest("hex"),
+  ].join("\n");
+  const signature = await signer.signBlob({
+    serviceAccount: account,
+    payload: Buffer.from(stringToSign, "utf8"),
+  });
+  return `https://storage.googleapis.com${canonicalUri}?${canonicalQuery}&X-Goog-Signature=${signature.toString("hex")}`;
+}
+
+function canonicalQueryString(values) {
+  return Object.entries(values)
+    .map(([key, value]) => [strictEncode(key), strictEncode(value)])
+    .sort(([leftKey, leftValue], [rightKey, rightValue]) => (
+      compareAscii(leftKey, rightKey) || compareAscii(leftValue, rightValue)
+    ))
+    .map(([key, value]) => `${key}=${value}`)
+    .join("&");
+}
+
+function compareAscii(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function strictEncode(value) {
+  return encodeURIComponent(String(value)).replaceAll(/[!'()*]/g, (character) => (
+    `%${character.charCodeAt(0).toString(16).toUpperCase()}`
+  ));
+}
+
+function encodePathSegment(value) {
+  return strictEncode(value);
+}
+
+function required(value, field) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new TypeError(`GCS 签名 URL 缺少 ${field}`);
+  }
+  return value.trim();
+}
+
+function positiveInteger(value, field) {
+  const numeric = Number(value);
+  if (!Number.isInteger(numeric) || numeric <= 0) {
+    throw new TypeError(`GCS 签名 URL ${field} 必须是正整数`);
+  }
+  return numeric;
+}