@h-ai/serv 0.1.0-alpha.15

package/dist/index.js

@@ -0,0 +1,809 @@
+import { WILDCARD_PERMISSION, requirePermission } from './chunk-YQV2OMQK.js';
+import { servM, mapHaiError, requireAuth, normalizeServLocale, buildHaiErrorBody } from './chunk-4QBF4PUG.js';
+import { implement } from '@orpc/server';
+import process from 'process';
+import { serve } from '@hono/node-server';
+import { core, err, HaiCommonError, ok } from '@h-ai/core';
+import { OpenAPIHandler } from '@orpc/openapi/fetch';
+import { RPCHandler } from '@orpc/server/fetch';
+import { Hono } from 'hono';
+import { z } from 'zod';
+import { IAM_AUTH_ROUTES } from '@h-ai/api-contract';
+import { getCookie } from 'hono/cookie';
+import { readFile } from 'fs/promises';
+import { OpenAPIGenerator } from '@orpc/openapi';
+import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4';
+import { TRANSPORT_PROTOCOL } from '@h-ai/crypto';
+
+// src/adapters/serv-adapter-fetch.ts
+function toFetch(app) {
+  const handler = (input, init) => {
+    const request = input instanceof Request ? input : new Request(typeof input === "string" ? input : input.toString(), init);
+    return Promise.resolve(app.fetch(request));
+  };
+  return handler;
+}
+var DEFAULT_SERV_HOST = "127.0.0.1";
+var DEFAULT_SERV_PORT = 3e3;
+function listen(app, options = {}) {
+  const host = options.host ?? process.env.HOST ?? DEFAULT_SERV_HOST;
+  const port = options.port ?? (process.env.PORT ? Number(process.env.PORT) : DEFAULT_SERV_PORT);
+  const server = serve(
+    { fetch: app.fetch, hostname: host, port },
+    options.onListening
+  );
+  const handle = {
+    server,
+    address: { host, port },
+    close: () => new Promise((resolve, reject) => {
+      server.close((error) => {
+        if (error)
+          reject(error);
+        else resolve();
+      });
+    })
+  };
+  if (options.onClose) {
+    const onClose = options.onClose;
+    let shuttingDown = false;
+    const shutdown = async () => {
+      if (shuttingDown)
+        return;
+      shuttingDown = true;
+      try {
+        await handle.close();
+      } catch {
+      }
+      try {
+        await onClose();
+      } catch {
+      }
+    };
+    process.once("SIGINT", () => void shutdown());
+    process.once("SIGTERM", () => void shutdown());
+  }
+  return handle;
+}
+var WILDCARD_ROLE = "*";
+function requireRole(role, handler) {
+  return requireAuth(async (options) => {
+    const roles = options.context.session?.roles ?? [];
+    if (!roles.includes(role) && !roles.includes(WILDCARD_ROLE))
+      return err(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale: options.context.locale }));
+    return handler(options);
+  });
+}
+var DEFAULT_LOCALE = "zh-CN";
+function resolveRequestLocale(headers) {
+  const get = (name) => {
+    if (headers instanceof Headers)
+      return headers.get(name) ?? void 0;
+    return headers[name] ?? headers[name.toLowerCase()];
+  };
+  const explicit = get("x-hai-locale");
+  if (explicit)
+    return normalizeServLocale(explicit);
+  return normalizeServLocale(get("accept-language") ?? get("Accept-Language") ?? DEFAULT_LOCALE);
+}
+function localizeZodError(zodError, locale) {
+  const resolvedLocale = normalizeServLocale(locale);
+  return core.zodValidation.mapZodErrorToFormErrors(
+    zodError,
+    core.zodValidation.createPrefixedZodMessageGetter(
+      "serv",
+      (messageKey, params) => servM(messageKey, { locale: resolvedLocale, params })
+    )
+  );
+}
+function validateInputOrFail(schema, input, locale = DEFAULT_LOCALE) {
+  const resolvedLocale = normalizeServLocale(locale);
+  const result = schema.safeParse(input);
+  if (result.success)
+    return ok(result.data);
+  const errors = localizeZodError(result.error, resolvedLocale);
+  return err(HaiCommonError.VALIDATION_ERROR, servM("serv_validationFailed", { locale: resolvedLocale }), errors);
+}
+
+// src/pipelines/serv-pipeline-require-internal-rpc.ts
+var pipelineLogger = core.logger.child({ module: "serv", scope: "pipeline" });
+var cachedGetConnInfo;
+async function resolveGetConnInfo() {
+  if (cachedGetConnInfo !== void 0)
+    return cachedGetConnInfo;
+  try {
+    const mod = await import('@hono/node-server/conninfo');
+    cachedGetConnInfo = mod.getConnInfo;
+  } catch (cause) {
+    pipelineLogger.warn("getConnInfo unavailable in this runtime; loopback/private-network access modes will fail closed", { error: cause });
+    cachedGetConnInfo = null;
+  }
+  return cachedGetConnInfo;
+}
+var LOOPBACK_IPS = /* @__PURE__ */ new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1", "localhost"]);
+function requireInternalRPC(config) {
+  return async (c, next) => {
+    const locale = resolveRequestLocale(c.req.raw.headers);
+    if (config.access === "gateway-only") {
+      const headerName = config.gatewayHeader ?? "x-hai-internal-rpc";
+      const received = c.req.header(headerName);
+      if (!config.gatewaySecret || !received || !core.string.constantTimeEqual(received, config.gatewaySecret))
+        return c.json(buildHaiErrorBody(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale })), 403);
+      return next();
+    }
+    const ip = await getRequestRemoteAddress(c) ?? "";
+    if (config.access === "loopback" && !isLoopbackIP(ip))
+      return c.json(buildHaiErrorBody(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale })), 403);
+    if (config.access === "private-network" && !isPrivateNetworkIP(ip))
+      return c.json(buildHaiErrorBody(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale })), 403);
+    return next();
+  };
+}
+async function getRequestRemoteAddress(c) {
+  const getConnInfo = await resolveGetConnInfo();
+  if (!getConnInfo)
+    return void 0;
+  try {
+    return getConnInfo(c).remote.address;
+  } catch {
+    return void 0;
+  }
+}
+function normalizeIpAddress(ip) {
+  return ip.startsWith("::ffff:") ? ip.slice("::ffff:".length) : ip;
+}
+function isLoopbackIP(ip) {
+  const normalized = normalizeIpAddress(ip);
+  return LOOPBACK_IPS.has(ip) || LOOPBACK_IPS.has(normalized);
+}
+function isPrivateNetworkIP(ip) {
+  const normalized = normalizeIpAddress(ip);
+  if (isLoopbackIP(ip))
+    return true;
+  if (normalized.startsWith("10.") || normalized.startsWith("192.168."))
+    return true;
+  const second = Number(normalized.split(".")[1]);
+  return normalized.startsWith("172.") && Number.isInteger(second) && second >= 16 && second <= 31;
+}
+
+// src/pipelines/serv-pipeline-security-headers.ts
+function securityHeaders() {
+  return async (c, next) => {
+    c.header("X-Content-Type-Options", "nosniff");
+    c.header("X-Frame-Options", "DENY");
+    c.header("Referrer-Policy", "no-referrer");
+    await next();
+  };
+}
+var ApiPrefixSchema = z.custom(
+  (value) => typeof value === "string" && value.startsWith("/api/"),
+  "apiPrefix must start with /api/"
+);
+var AbsolutePathSchema = z.custom(
+  (value) => typeof value === "string" && value.startsWith("/"),
+  "path must start with /"
+);
+var OpenAPIHttpConfigInputSchema = z.union([
+  z.literal(false),
+  z.object({ path: AbsolutePathSchema.default("/openapi.json") })
+]);
+var DocsHttpConfigInputSchema = z.union([
+  z.literal(false),
+  z.object({
+    path: AbsolutePathSchema.default("/docs"),
+    requireAuth: z.boolean().optional()
+  })
+]);
+var HealthHttpConfigInputSchema = z.union([
+  z.literal(false),
+  z.object({
+    path: AbsolutePathSchema.default("/health"),
+    readyPath: AbsolutePathSchema.optional().default("/ready")
+  })
+]);
+var RpcHttpConfigInputSchema = z.union([
+  z.literal(false),
+  z.object({
+    prefix: AbsolutePathSchema.default("/rpc"),
+    access: z.enum(["loopback", "private-network", "gateway-only"]).default("loopback"),
+    gatewayHeader: z.string().optional(),
+    gatewaySecret: z.string().optional()
+  })
+]);
+var TransportRuntimeConfigInputSchema = z.union([
+  z.literal(false),
+  z.object({
+    keyExchangePath: AbsolutePathSchema.default("/_hai/key-exchange"),
+    excludePaths: z.array(AbsolutePathSchema).default([]),
+    maxClients: z.number().int().positive().default(1e4)
+  })
+]);
+var ServHttpConfigInputSchema = z.object({
+  apiPrefix: ApiPrefixSchema.default("/api/v1"),
+  openapi: OpenAPIHttpConfigInputSchema.default(false),
+  docs: DocsHttpConfigInputSchema.default(false),
+  health: HealthHttpConfigInputSchema.default({ path: "/health", readyPath: "/ready" }),
+  rpc: RpcHttpConfigInputSchema.default(false)
+});
+var ServConfigSchema = z.object({
+  http: ServHttpConfigInputSchema.optional(),
+  transport: TransportRuntimeConfigInputSchema.optional()
+}).transform(({ http, transport }) => ({
+  http: resolveServHttpConfig(http ?? {}),
+  transport: resolveServTransportRuntimeConfig(transport ?? false)
+}));
+function resolveServHttpConfig(input = {}) {
+  return ServHttpConfigInputSchema.parse(input);
+}
+function resolveServTransportRuntimeConfig(input = false) {
+  return TransportRuntimeConfigInputSchema.parse(input);
+}
+var HEADER_REQUEST_ID = "x-request-id";
+var HEADER_FORWARDED_FOR = "x-forwarded-for";
+var HEADER_REAL_IP = "x-real-ip";
+var HEADER_AUTHORIZATION = "authorization";
+var HEADER_USER_AGENT = "user-agent";
+function extractBearerToken(value) {
+  if (!value)
+    return void 0;
+  const [scheme, token] = value.split(" ");
+  if (scheme?.toLowerCase() !== "bearer" || !token)
+    return void 0;
+  return token;
+}
+function parseRequestContext(input) {
+  const headers = input.request.headers;
+  const requestId = headers.get(HEADER_REQUEST_ID) ?? core.id.uuid();
+  const forwardedFor = headers.get(HEADER_FORWARDED_FOR);
+  const ip = headers.get(HEADER_REAL_IP) ?? forwardedFor?.split(",")[0]?.trim();
+  const locale = resolveRequestLocale(headers);
+  const accessToken = extractBearerToken(headers.get(HEADER_AUTHORIZATION));
+  return {
+    requestId,
+    locale,
+    ip,
+    userAgent: headers.get(HEADER_USER_AGENT) ?? void 0,
+    accessToken,
+    request: input.request,
+    logger: core.logger.child({ module: "serv", requestId })
+  };
+}
+function buildAuthContextFactory(verifyToken) {
+  return async (input) => {
+    const base = parseRequestContext(input);
+    if (!base.accessToken)
+      return base;
+    try {
+      const result = await verifyToken(base.accessToken);
+      if (!result.success)
+        return base;
+      return { ...base, session: result.data };
+    } catch {
+      return base;
+    }
+  };
+}
+function resolveRefreshCookieConfig(apiPrefix, config, iam) {
+  const onRefresh = config.onRefresh ?? (iam ? (refreshToken) => iam.session.refresh(refreshToken) : void 0);
+  if (!onRefresh) {
+    throw core.error.buildHaiErrorInst(
+      HaiCommonError.INTERNAL_ERROR,
+      "[serv] refreshCookie requires either top-level `iam` (recommended) or `refreshCookie.onRefresh` callback"
+    );
+  }
+  return {
+    cookieName: config.cookieName ?? "hai_refresh_token",
+    maxAge: config.maxAge ?? 30 * 24 * 3600,
+    isSecure: config.secure ?? process.env.NODE_ENV === "production",
+    refreshCookiePath: `${apiPrefix}${IAM_AUTH_ROUTES.refresh}`,
+    onRefresh
+  };
+}
+function buildSetCookieHeader(name, value, path, maxAge, secure) {
+  const parts = [
+    `${name}=${encodeURIComponent(value)}`,
+    `Path=${path}`,
+    `Max-Age=${maxAge}`,
+    "HttpOnly",
+    "SameSite=Strict"
+  ];
+  if (secure)
+    parts.push("Secure");
+  return parts.join("; ");
+}
+function buildClearCookieHeader(name, path) {
+  return `${name}=; Path=${path}; Max-Age=0; HttpOnly; SameSite=Strict`;
+}
+function extractRefreshTokenFromData(data) {
+  if (!data || typeof data !== "object")
+    return void 0;
+  const d = data;
+  const tokens = d.tokens;
+  if (!tokens || typeof tokens !== "object")
+    return void 0;
+  const t = tokens;
+  return typeof t.refreshToken === "string" && t.refreshToken ? t.refreshToken : void 0;
+}
+function stripRefreshTokenFromData(data) {
+  if (!data || typeof data !== "object" || Array.isArray(data))
+    return data;
+  const d = data;
+  const tokens = d.tokens;
+  if (!tokens || typeof tokens !== "object" || Array.isArray(tokens))
+    return data;
+  const safeTokens = {};
+  for (const [key, value] of Object.entries(tokens)) {
+    if (key !== "refreshToken")
+      safeTokens[key] = value;
+  }
+  return { ...d, tokens: safeTokens };
+}
+function stripRefreshTokenFromPair(tokens) {
+  return {
+    accessToken: tokens.accessToken,
+    ...tokens.expiresIn === void 0 ? {} : { expiresIn: tokens.expiresIn },
+    ...tokens.tokenType === void 0 ? {} : { tokenType: tokens.tokenType }
+  };
+}
+function mountRefreshCookieRoutes(app, apiPrefix, config, iam) {
+  const { cookieName, maxAge, isSecure, refreshCookiePath, onRefresh } = resolveRefreshCookieConfig(apiPrefix, config, iam);
+  const loginPaths = [
+    `${apiPrefix}${IAM_AUTH_ROUTES.login}`,
+    `${apiPrefix}${IAM_AUTH_ROUTES.loginWithOtp}`,
+    `${apiPrefix}${IAM_AUTH_ROUTES.register}`
+  ];
+  for (const path of loginPaths) {
+    app.post(path, async (c, next) => {
+      await next();
+      if (c.res.status !== 200)
+        return;
+      const bodyText = await c.res.text();
+      const headers = new Headers(c.res.headers);
+      let responseBody = bodyText;
+      try {
+        const body = JSON.parse(bodyText);
+        if (body.success) {
+          const refreshToken = extractRefreshTokenFromData(body.data);
+          if (refreshToken)
+            headers.append("Set-Cookie", buildSetCookieHeader(cookieName, refreshToken, refreshCookiePath, maxAge, isSecure));
+          body.data = stripRefreshTokenFromData(body.data);
+          responseBody = JSON.stringify(body);
+          headers.delete("Content-Length");
+        }
+      } catch {
+      }
+      c.res = new Response(responseBody, { status: c.res.status, statusText: c.res.statusText, headers });
+    });
+  }
+  app.post(`${apiPrefix}${IAM_AUTH_ROUTES.logout}`, async (c, next) => {
+    await next();
+    if (c.res.status !== 200)
+      return;
+    const bodyText = await c.res.text();
+    const headers = new Headers(c.res.headers);
+    try {
+      const body = JSON.parse(bodyText);
+      if (body.success)
+        headers.append("Set-Cookie", buildClearCookieHeader(cookieName, refreshCookiePath));
+    } catch {
+    }
+    c.res = new Response(bodyText, { status: c.res.status, statusText: c.res.statusText, headers });
+  });
+  app.post(`${apiPrefix}${IAM_AUTH_ROUTES.refresh}`, async (c) => {
+    const refreshToken = getCookie(c, cookieName);
+    if (!refreshToken) {
+      const locale = resolveRequestLocale(c.req.raw.headers);
+      return c.json(buildHaiErrorBody(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", { locale })), 401);
+    }
+    const result = await onRefresh(refreshToken);
+    if (!result.success) {
+      const status = result.error.httpStatus ?? 401;
+      const clearCookie = buildClearCookieHeader(cookieName, refreshCookiePath);
+      return new Response(JSON.stringify({ success: false, error: result.error }), {
+        status,
+        headers: {
+          "Content-Type": "application/json",
+          "Set-Cookie": clearCookie
+        }
+      });
+    }
+    const tokens = result.data;
+    const setCookie = buildSetCookieHeader(cookieName, tokens.refreshToken, refreshCookiePath, maxAge, isSecure);
+    return new Response(JSON.stringify({ success: true, data: { tokens: stripRefreshTokenFromPair(tokens) } }), {
+      status: 200,
+      headers: {
+        "Content-Type": "application/json",
+        "Set-Cookie": setCookie
+      }
+    });
+  });
+}
+var SCALAR_ROUTE = "/_hai/scalar.js";
+var SCALAR_BROWSER_ENTRY_FALLBACK = "./dist/browser/standalone.js";
+var scalarScriptCache;
+async function generateSpec(contract, options = {}) {
+  const generator = new OpenAPIGenerator({
+    schemaConverters: [new ZodToJsonSchemaConverter()]
+  });
+  return generator.generate(contract, {
+    info: {
+      title: options.title ?? "hai-framework API",
+      version: options.version ?? "0.1.0",
+      description: options.description
+    },
+    servers: options.apiPrefix ? [{ url: options.apiPrefix }] : void 0,
+    security: [{ bearerAuth: [] }],
+    components: {
+      securitySchemes: {
+        bearerAuth: { type: "http", scheme: "bearer" }
+      }
+    }
+  });
+}
+async function getScalarScript() {
+  if (scalarScriptCache !== void 0)
+    return scalarScriptCache || void 0;
+  try {
+    const fileUrl = await resolveScalarBrowserScriptUrl();
+    scalarScriptCache = await readFile(fileUrl, "utf8");
+  } catch {
+    scalarScriptCache = "";
+  }
+  return scalarScriptCache || void 0;
+}
+function createDocsPage(spec, options = {}) {
+  const title = escapeHtml(options.title ?? spec.info.title);
+  const specUrl = options.specUrl;
+  const scriptUrl = escapeHtml(options.scriptUrl ?? SCALAR_ROUTE);
+  if (specUrl) {
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${title}</title></head><body><script id="api-reference" data-url="${escapeHtml(specUrl)}"></script><script src="${scriptUrl}"></script></body></html>`;
+  }
+  const encodedSpec = escapeScript(JSON.stringify(spec));
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${title}</title></head><body><script id="api-reference" type="application/json">${encodedSpec}</script><script src="${scriptUrl}"></script></body></html>`;
+}
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll(String.fromCharCode(39), "&#39;");
+}
+function escapeScript(value) {
+  return value.replaceAll("</script", "<\\/script");
+}
+async function resolveScalarBrowserScriptUrl() {
+  const packageEntryUrl = import.meta.resolve("@scalar/api-reference");
+  const packageJsonUrl = new URL("../package.json", packageEntryUrl);
+  const packageInfo = JSON.parse(await readFile(packageJsonUrl, "utf8"));
+  const browserEntry = readScalarBrowserEntry(packageInfo) ?? SCALAR_BROWSER_ENTRY_FALLBACK;
+  return new URL(browserEntry, packageJsonUrl);
+}
+function readScalarBrowserEntry(packageInfo) {
+  if (typeof packageInfo !== "object" || packageInfo === null || Array.isArray(packageInfo))
+    return void 0;
+  const browser = packageInfo.browser;
+  return typeof browser === "string" ? browser : void 0;
+}
+var logger = core.logger.child({ module: "serv", scope: "transport" });
+var MAX_ENCRYPTED_BODY = 1048576;
+var ENCRYPTABLE_RESPONSE_CONTENT_TYPES = ["application/json"];
+function createTransportMiddleware(manager, keyExchangePath, excludePaths = []) {
+  return async (c, next) => {
+    const pathname = new URL(c.req.url).pathname;
+    if (pathname === keyExchangePath && c.req.method === "POST")
+      return handleKeyExchange(c.req.raw, manager);
+    if (shouldExclude(pathname, excludePaths, keyExchangePath))
+      return next();
+    const clientId = c.req.header(TRANSPORT_PROTOCOL.CLIENT_ID_HEADER);
+    if (!clientId)
+      return jsonError(servM("serv_transportClientIdRequired"), 400);
+    const clientPublicKey = await manager.getClientPublicKey(clientId);
+    if (!clientPublicKey)
+      return jsonError(servM("serv_transportClientKeyNotFound"), 400);
+    if (hasBody(c.req.method) && !isEmptyBody(c.req.raw)) {
+      const decErr = await decryptRequestInPlace(c, manager);
+      if (decErr)
+        return decErr;
+    }
+    await next();
+    const response = c.res;
+    if (!response)
+      return;
+    const contentType = response.headers.get("Content-Type") ?? "";
+    if (isEmptyResponse(response))
+      return;
+    if (!canEncryptResponseContentType(contentType)) {
+      c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
+      return;
+    }
+    const contentLength = response.headers.get("Content-Length");
+    if (contentLength && Number.parseInt(contentLength, 10) > MAX_ENCRYPTED_BODY) {
+      c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
+      return;
+    }
+    let bodyText;
+    try {
+      bodyText = await response.clone().text();
+    } catch (cause) {
+      logger.warn("Failed to read response body for encryption", { error: cause });
+      c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
+      return;
+    }
+    if (!bodyText)
+      return;
+    if (bodyText.length > MAX_ENCRYPTED_BODY) {
+      c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
+      return;
+    }
+    const encResult = await manager.encryptResponse(clientId, bodyText);
+    if (!encResult.success) {
+      logger.warn("Failed to encrypt response", { error: encResult.error });
+      c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
+      return;
+    }
+    const headers = new Headers(response.headers);
+    headers.set("Content-Type", "application/json; charset=utf-8");
+    headers.set(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER, TRANSPORT_PROTOCOL.ENCRYPTED_HEADER_VALUE);
+    headers.delete("Content-Length");
+    c.res = new Response(JSON.stringify(encResult.data), {
+      status: response.status,
+      statusText: response.statusText,
+      headers
+    });
+  };
+}
+async function handleKeyExchange(request, manager) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return jsonError(servM("serv_transportInvalidPayload"), 400);
+  }
+  if (typeof body.clientPublicKey !== "string" || body.clientPublicKey.length === 0)
+    return jsonError(servM("serv_transportInvalidPayload"), 400);
+  try {
+    const clientId = await manager.registerClientKey(body.clientPublicKey);
+    const serverPublicKey = manager.getServerPublicKey();
+    return new Response(JSON.stringify({ serverPublicKey, clientId }), {
+      status: 200,
+      headers: { "Content-Type": "application/json; charset=utf-8" }
+    });
+  } catch (cause) {
+    logger.error("Key exchange failed", { error: cause });
+    return jsonError(servM("serv_transportKeyExchangeFailed"), 500);
+  }
+}
+async function decryptRequestInPlace(c, manager) {
+  const isEncrypted = c.req.header(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER) === TRANSPORT_PROTOCOL.ENCRYPTED_HEADER_VALUE;
+  if (!isEncrypted)
+    return jsonError(servM("serv_transportInvalidPayload"), 400);
+  let payload;
+  try {
+    payload = await c.req.raw.clone().json();
+  } catch {
+    return jsonError(servM("serv_transportInvalidPayload"), 400);
+  }
+  if (!isEncryptedPayloadShape(payload))
+    return jsonError(servM("serv_transportInvalidPayload"), 400);
+  const decResult = manager.decryptRequest(payload);
+  if (!decResult.success) {
+    logger.warn("Failed to decrypt request", { error: decResult.error });
+    return jsonError(servM("serv_transportDecryptFailed"), 400);
+  }
+  const original = c.req.raw;
+  const newHeaders = new Headers(original.headers);
+  newHeaders.delete(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER);
+  newHeaders.delete("Content-Length");
+  newHeaders.set("Content-Type", "application/json; charset=utf-8");
+  const newRequest = new Request(original.url, {
+    method: original.method,
+    headers: newHeaders,
+    body: decResult.data,
+    // @ts-expect-error Node fetch 需要 duplex 才能携带流式 body。
+    duplex: "half"
+  });
+  c.req.raw = newRequest;
+  return void 0;
+}
+function shouldExclude(pathname, excludePaths, keyExchangePath) {
+  if (pathname === keyExchangePath)
+    return true;
+  return excludePaths.some((p) => pathname === p || pathname.startsWith(`${p}/`));
+}
+function canEncryptResponseContentType(contentType) {
+  return ENCRYPTABLE_RESPONSE_CONTENT_TYPES.some((type) => contentType.includes(type));
+}
+function isEmptyResponse(response) {
+  if ([204, 304].includes(response.status))
+    return true;
+  return response.headers.get("Content-Length") === "0";
+}
+function hasBody(method) {
+  return ["POST", "PUT", "PATCH", "DELETE"].includes(method.toUpperCase());
+}
+function isEmptyBody(req) {
+  if (req.body === null)
+    return true;
+  const cl = req.headers.get("Content-Length");
+  if (cl !== null)
+    return Number.parseInt(cl, 10) === 0;
+  return !req.headers.get("Content-Type");
+}
+function jsonError(message, status) {
+  return new Response(JSON.stringify({ error: message }), {
+    status,
+    headers: { "Content-Type": "application/json; charset=utf-8" }
+  });
+}
+function isEncryptedPayloadShape(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const p = value;
+  return typeof p.encryptedKey === "string" && typeof p.ciphertext === "string" && typeof p.iv === "string";
+}
+
+// src/serv-app.ts
+var API_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+function createApp(options) {
+  const http = resolveServHttpConfig(options.http);
+  const app = new Hono();
+  const iamRef = options.iam;
+  const verifyToken = options.verifyToken ?? (iamRef ? (token) => iamRef.session.verifyToken(token) : void 0);
+  const createContext = options.createContext ?? (verifyToken ? buildAuthContextFactory(verifyToken) : parseRequestContext);
+  let cachedSpec;
+  const getSpec = () => {
+    cachedSpec ??= generateSpec(options.contract, { apiPrefix: http.apiPrefix });
+    return cachedSpec;
+  };
+  app.use("*", securityHeaders());
+  if (options.transport) {
+    const mgr = options.transport.crypto.transport.createServer({ maxClients: options.transport.maxClients });
+    if (!mgr.success) {
+      throw core.error.buildHaiErrorInst(
+        HaiCommonError.INTERNAL_ERROR,
+        mgr.error.message,
+        mgr.error
+      );
+    }
+    const keyExchangePath = `${http.apiPrefix}${options.transport.keyExchangePath ?? "/_hai/key-exchange"}`;
+    app.use("*", createTransportMiddleware(mgr.data, keyExchangePath, options.transport.excludePaths));
+  }
+  if (options.middlewares)
+    mountCustomMiddlewares(app, options.middlewares);
+  if (http.health !== false)
+    mountHealthRoutes(app, http.health);
+  if (options.refreshCookie)
+    mountRefreshCookieRoutes(app, http.apiPrefix, options.refreshCookie, options.iam);
+  mountOpenAPIRoutes(app, options.procedures, http.apiPrefix, createContext);
+  if (http.rpc !== false)
+    mountRPCRoutes(app, options.procedures, http.rpc, createContext);
+  if (http.openapi !== false) {
+    app.get(http.openapi.path, async (c) => c.json(await getSpec()));
+  }
+  if (http.docs !== false) {
+    const docs = http.docs;
+    app.get(SCALAR_ROUTE, async (c) => {
+      const content = await getScalarScript();
+      if (!content)
+        return c.notFound();
+      c.header("Content-Type", "application/javascript; charset=utf-8");
+      c.header("Cache-Control", "public, max-age=86400, immutable");
+      return c.body(content);
+    });
+    app.get(docs.path, async (c) => {
+      if (docs.requireAuth) {
+        const context = await createContext({ request: c.req.raw });
+        if (!context.session)
+          return c.json(buildHaiErrorBody(HaiCommonError.UNAUTHORIZED, servM("serv_errorUnauthorized", { locale: resolveRequestLocale(c.req.raw.headers) })), 401);
+      }
+      const specUrl = http.openapi === false ? void 0 : http.openapi.path;
+      return c.html(createDocsPage(await getSpec(), { specUrl }));
+    });
+  }
+  return app;
+}
+function mountCustomMiddlewares(app, middlewares) {
+  for (const entry of middlewares)
+    app.use(entry.path ?? "*", entry.middleware);
+}
+function mountHealthRoutes(app, config) {
+  app.get(config.path, (c) => c.json({ status: "ok" }));
+  if (config.readyPath)
+    app.get(config.readyPath, (c) => c.json({ status: "ready" }));
+}
+function mountOpenAPIRoutes(app, procedures, apiPrefix, createContext) {
+  const handler = new OpenAPIHandler(procedures);
+  app.on([...API_METHODS], `${apiPrefix}/*`, (c, next) => handleORPC(c, next, apiPrefix, handler, createContext));
+}
+function mountRPCRoutes(app, procedures, rpcConfig, createContext) {
+  const handler = new RPCHandler(procedures);
+  const prefix = rpcConfig.prefix;
+  app.use(`${prefix}/*`, requireInternalRPC(rpcConfig));
+  app.on([...API_METHODS], `${prefix}/*`, (c, next) => handleORPC(c, next, prefix, handler, createContext));
+}
+async function handleORPC(c, next, prefix, handler, createContext) {
+  const context = await createContext({ request: c.req.raw });
+  const { matched, response } = await handler.handle(c.req.raw, { prefix, context });
+  if (!matched) {
+    await next();
+    return;
+  }
+  return localizeValidationResponse(response, c.req.raw.headers);
+}
+async function localizeValidationResponse(response, requestHeaders) {
+  if (response.status !== 400)
+    return response;
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("application/json"))
+    return response;
+  let payload;
+  try {
+    payload = await response.clone().json();
+  } catch {
+    return response;
+  }
+  if (!isOrpcValidationErrorPayload(payload))
+    return response;
+  const issues = payload.data.issues;
+  const locale = resolveRequestLocale(requestHeaders);
+  const errors = localizeZodError({ issues }, locale);
+  const body = {
+    success: false,
+    error: {
+      code: HaiCommonError.VALIDATION_ERROR.code,
+      message: servM("serv_validationFailed", { locale }),
+      httpStatus: HaiCommonError.VALIDATION_ERROR.httpStatus,
+      system: HaiCommonError.VALIDATION_ERROR.system,
+      module: HaiCommonError.VALIDATION_ERROR.module,
+      cause: errors
+    },
+    errors
+  };
+  const headers = new Headers(response.headers);
+  headers.set("content-type", "application/json; charset=utf-8");
+  return new Response(JSON.stringify(body), {
+    status: HaiCommonError.VALIDATION_ERROR.httpStatus,
+    headers
+  });
+}
+function isOrpcValidationErrorPayload(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const obj = value;
+  if (obj.code !== "BAD_REQUEST")
+    return false;
+  if (typeof obj.status !== "number" || obj.status !== 400)
+    return false;
+  const data = obj.data;
+  if (!data || typeof data !== "object")
+    return false;
+  const issues = data.issues;
+  return Array.isArray(issues);
+}
+
+// src/serv-main.ts
+var serv = {
+  // 应用与上下文
+  createApp,
+  parseRequestContext,
+  buildAuthContextFactory,
+  resolveRequestLocale,
+  // 运行时适配器
+  listen,
+  toFetch,
+  // OpenAPI / 导出
+  generateSpec,
+  // Procedure 装配（contract 路由定义统一使用 `apiContract.route`）。
+  /** 基于 contract 创建可注入 context 的 procedure builder（封装 `@orpc/server` 的 `implement`）。 */
+  implement,
+  // oRPC procedure 包装器
+  requireAuth,
+  requirePermission,
+  requireRole,
+  mapHaiError,
+  validateInputOrFail,
+  // 通配符常量
+  WILDCARD_PERMISSION,
+  WILDCARD_ROLE,
+  // Serv 模块 i18n 消息获取器（支持 `options.locale` 单次调用本地化）。
+  m: servM
+};
+
+export { ServConfigSchema, serv };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map