@h-ai/serv 0.1.0-alpha.67 → 0.1.0-alpha.68

package/dist/features/storage.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/features/serv-feature-storage.ts"],"names":[],"mappings":"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","file":"storage.js","sourcesContent":["/**\n * @h-ai/serv — Storage 默认 procedures\n *\n * 基于 `@h-ai/storage` 提供开箱即用的 Storage procedures 实现：预签名 URL、列表、元数据、删除。\n *\n * **⚠️ 安全说明（必读）：**\n *\n * 1. **路径穿越防护**：内置 `validateStorageKeyOrFail` 拒绝 `..`、绝对路径、反斜杠、NUL 字节等危险输入。\n * 2. **多租户 / 多用户隔离（需应用层实现）**：默认 procedure 仅使用 `.auth()`，任何登录用户均可访问任意 key。\n *    生产环境必须在应用层重新装配这些 procedure，以强制用 `context.session.userId` 作为 key 前缀。\n * 3. **权限收紧**：推荐把 `.auth()` 改成 `.permission('storage.files.read'|'storage.files.write')`。\n * @module features/serv-feature-storage\n */\n\nimport type { HaiResult } from '@h-ai/core'\nimport type { StorageFunctions } from '@h-ai/storage'\nimport type { ServContext } from '../serv-context.js'\nimport type { ServMessageKey } from '../serv-i18n.js'\nimport { apiContract } from '@h-ai/api-contract'\nimport { err, HaiCommonError, ok } from '@h-ai/core'\nimport { servM } from '../serv-i18n.js'\nimport { implement } from '../serv-router.js'\nimport { mapHaiResult } from './serv-feature-helpers.js'\n\nconst storageContract = apiContract.storage\nconst STORAGE_KEY_MAX_LENGTH = 1024\n\nfunction buildStorageKeyValidationFailure(\n  field: string,\n  locale: string,\n  messageKey: ServMessageKey,\n  params?: Record<string, string | number>,\n): HaiResult<never> {\n  const message = servM(messageKey, { locale, params })\n  return err(\n    HaiCommonError.VALIDATION_ERROR,\n    servM('serv_validationFailed', { locale }),\n    [{ field, message }],\n  )\n}\n\n/**\n * 对业务层再次校验存储 key 是否安全。\n *\n * 这里不额外构造 Zod schema，而是直接按业务规则返回统一的\n * `HaiResult + ValidationFormError[]` 形态，避免把简单路径安全规则包装得过重。\n */\nfunction validateStorageKeyOrFail(key: string, locale: string, field: string = 'key'): HaiResult<string> {\n  if (key.trim() === '')\n    return buildStorageKeyValidationFailure(field, locale, 'serv_storageKeyRequired')\n  if (key.length > STORAGE_KEY_MAX_LENGTH) {\n    return buildStorageKeyValidationFailure(field, locale, 'serv_storageKeyTooLong', {\n      max: STORAGE_KEY_MAX_LENGTH,\n    })\n  }\n  if (key.startsWith('/') || key.includes('\\\\') || key.includes('\\0'))\n    return buildStorageKeyValidationFailure(field, locale, 'serv_storageKeyIllegalChars')\n  if (key.split('/').some(seg => seg === '.' || seg === '..'))\n    return buildStorageKeyValidationFailure(field, locale, 'serv_storageKeyDotSegments')\n  return ok(key)\n}\n\nfunction validateStorageKeysOrFail(keys: string[], locale: string): HaiResult<string[]> {\n  for (const [index, key] of keys.entries()) {\n    const keyResult = validateStorageKeyOrFail(key, locale, `keys.${index}`)\n    if (!keyResult.success)\n      return keyResult\n  }\n  return ok(keys)\n}\n\n/** Storage 默认 procedures 依赖。 */\nexport interface StorageProcedureDeps {\n  readonly storage: StorageFunctions\n}\n\ninterface PresignedResponse {\n  readonly url: string\n  readonly key: string\n  readonly expiresAt?: Date\n}\n\n/** 创建 Storage 默认 procedures。 */\nexport function createStorageProcedures(deps: StorageProcedureDeps) {\n  const { storage } = deps\n\n  return implement(storageContract)\n    .context<ServContext>()\n\n    .route('presignedUrls.createDownload')\n    .auth()\n    .handle(async ({ input, context }) => {\n      const keyResult = validateStorageKeyOrFail(input.key, context.locale)\n      if (!keyResult.success)\n        return keyResult\n      const expiresIn = input.expiresIn ?? 900\n      return toPresignedResult(\n        keyResult.data,\n        expiresIn,\n        await storage.presign.getUrl(keyResult.data, { expiresIn }),\n      )\n    })\n\n    .route('presignedUrls.createUpload')\n    .auth()\n    .handle(async ({ input, context }) => {\n      const keyResult = validateStorageKeyOrFail(input.key, context.locale)\n      if (!keyResult.success)\n        return keyResult\n      const expiresIn = input.expiresIn ?? 900\n      const contentType = input.contentType ?? 'application/octet-stream'\n      const { key: _, ...options } = input\n      return toPresignedResult(\n        keyResult.data,\n        expiresIn,\n        await storage.presign.putUrl(keyResult.data, { ...options, expiresIn, contentType }),\n      )\n    })\n\n    .route('files.list')\n    .auth()\n    .handle(({ input }) => storage.dir.list(input))\n\n    .route('files.getMetadata')\n    .auth()\n    .handle(({ input, context }) => {\n      const keyResult = validateStorageKeyOrFail(input.key, context.locale)\n      if (!keyResult.success)\n        return keyResult\n      return storage.file.head(keyResult.data)\n    })\n\n    .route('files.delete')\n    .auth()\n    .handle(({ input, context }) => {\n      const keyResult = validateStorageKeyOrFail(input.key, context.locale)\n      if (!keyResult.success)\n        return keyResult\n      return storage.file.delete(keyResult.data)\n    })\n\n    .route('files.deleteMany')\n    .auth()\n    .handle(({ input, context }) => {\n      const keysResult = validateStorageKeysOrFail(input.keys, context.locale)\n      if (!keysResult.success)\n        return keysResult\n      return storage.file.deleteMany(keysResult.data)\n    })\n\n    .build()\n}\n\nfunction toPresignedResult(\n  key: string,\n  expiresIn: number | undefined,\n  result: HaiResult<string>,\n): HaiResult<PresignedResponse> {\n  return mapHaiResult(result, url => ({\n    url,\n    key,\n    expiresAt: expiresIn ? new Date(Date.now() + expiresIn * 1000) : undefined,\n  }))\n}\n"]}
+{"version":3,"sources":["../../src/features/serv-feature-storage.ts"],"names":[],"mappings":"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","file":"storage.js","sourcesContent":["/**\n * @h-ai/serv — Storage 默认 procedures\n *\n * 基于 `@h-ai/storage` 提供开箱即用的 Storage procedures 实现：预签名 URL、列表、元数据、删除。\n *\n * 所有操作先验证路径，再调用应用提供的资源授权策略；未提供策略时拒绝访问。\n * 策略必须从已认证 session 确定用户/租户范围，不能信任客户端提供的前缀。\n * @module features/serv-feature-storage\n */\n\nimport type { HaiResult } from '@h-ai/core'\nimport type { StorageFunctions } from '@h-ai/storage'\nimport type { ServContext } from '../serv-context.js'\nimport type { ServMessageKey } from '../serv-i18n.js'\nimport type { AuthenticatedServContext } from '../serv-router.js'\nimport { apiContract } from '@h-ai/api-contract'\nimport { err, HaiCommonError, ok } from '@h-ai/core'\nimport { getStorageKeyIssue, STORAGE_KEY_MAX_BYTES, StorageDeleteKeysSchema } from '@h-ai/storage/schemas'\nimport { servM } from '../serv-i18n.js'\nimport { implement } from '../serv-router.js'\nimport { validateInputOrFail } from '../serv-validation.js'\nimport { mapHaiResult } from './serv-feature-helpers.js'\n\nconst storageContract = apiContract.storage\n\nfunction buildStorageKeyValidationFailure(\n  field: string,\n  locale: string,\n  messageKey: ServMessageKey,\n  params?: Record<string, string | number>,\n): HaiResult<never> {\n  const message = servM(messageKey, { locale, params })\n  return err(\n    HaiCommonError.VALIDATION_ERROR,\n    servM('serv_validationFailed', { locale }),\n    [{ field, message }],\n  )\n}\n\n/**\n * 对业务层再次校验存储 key 是否安全。\n *\n * 与公开 Schema 共用规则，保留业务入口防线；后续仍必须执行授权和 Provider 防逃逸。\n */\nfunction validateStorageKeyOrFail(key: string, locale: string, field: string = 'key'): HaiResult<string> {\n  const issue = getStorageKeyIssue(key)\n  if (issue === 'empty')\n    return buildStorageKeyValidationFailure(field, locale, 'serv_storageKeyRequired')\n  if (issue === 'tooLong') {\n    return buildStorageKeyValidationFailure(field, locale, 'serv_storageKeyTooLong', {\n      max: STORAGE_KEY_MAX_BYTES,\n    })\n  }\n  if (issue === 'characters')\n    return buildStorageKeyValidationFailure(field, locale, 'serv_storageKeyIllegalChars')\n  if (issue === 'segments')\n    return buildStorageKeyValidationFailure(field, locale, 'serv_storageKeyDotSegments')\n  return ok(key)\n}\n\nfunction validateStorageKeysOrFail(keys: string[], locale: string): HaiResult<string[]> {\n  const parsed = validateInputOrFail(StorageDeleteKeysSchema, keys, locale)\n  if (!parsed.success)\n    return parsed\n  for (const [index, key] of keys.entries()) {\n    const keyResult = validateStorageKeyOrFail(key, locale, `keys.${index}`)\n    if (!keyResult.success)\n      return keyResult\n  }\n  return ok(keys)\n}\n\n/**\n * 存储资源授权请求；批量操作只有全部资源获准后才会调用存储。\n *\n * @example\n * ```ts\n * import { storage } from '@h-ai/storage'\n * import { createStorageProcedures } from '@h-ai/serv/features/storage'\n *\n * // 宿主已初始化 Storage；用户根目录来自可信 session，含尾斜杠形成边界。\n * const procedures = createStorageProcedures({ storage, authorize: ({ context, keys }) => {\n *   const root = `users/${encodeURIComponent(context.session.userId)}/`\n *   return keys.length > 0 && keys.every(key => key.startsWith(root))\n * } })\n * // 空列表前缀与相邻用户名前缀均不能匹配此根目录。\n * ```\n */\nexport interface StorageAccessRequest {\n  /** 操作类别；策略可分别授予读取、写入或删除权限。 */\n  readonly operation: 'download' | 'upload' | 'list' | 'metadata' | 'delete' | 'deleteMany'\n  /** 已通过认证的可信请求上下文。 */\n  readonly context: AuthenticatedServContext\n  /** 单项/批量 key；list 操作仅包含请求的 prefix，未提供 prefix 时为空字符串。 */\n  readonly keys: readonly string[]\n}\n\n/**\n * Storage 默认 procedures 依赖。\n *\n * @example\n * ```ts\n * import { storage } from '@h-ai/storage'\n * import { createStorageProcedures } from '@h-ai/serv/features/storage'\n *\n * // 宿主已初始化 Storage；用户根目录来自可信 session，含尾斜杠形成边界。\n * const procedures = createStorageProcedures({ storage, authorize: ({ context, keys }) => {\n *   const root = `users/${encodeURIComponent(context.session.userId)}/`\n *   return keys.length > 0 && keys.every(key => key.startsWith(root))\n * } })\n * // 空列表前缀与相邻用户名前缀均不能匹配此根目录。\n * ```\n */\nexport interface StorageProcedureDeps {\n  readonly storage: StorageFunctions\n  /** 必需的资源授权策略；返回 true 才允许执行，缺失策略时默认拒绝。 */\n  readonly authorize: (request: StorageAccessRequest) => boolean | Promise<boolean>\n}\n\n/**\n * 内部预签名结果投影，包含短期访问 URL 和可选失效时间。\n *\n * @example\n * ```ts\n * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。\n * function safeUrl(value: PresignedResponse) {\n *   return { url: value.url, key: value.key, expiresAt: value.expiresAt }\n * }\n * // URL 是授权后的短期凭据；只返回给已授权调用方，不记录到日志。\n * ```\n */\ninterface PresignedResponse {\n  readonly url: string\n  readonly key: string\n  readonly expiresAt?: Date\n}\n\n/**\n * 创建具有认证、路径校验和资源授权的 Storage procedures。\n *\n * @param deps - 存储服务及必需的资源授权策略。\n * @returns 可挂载至 serv.createApp 的存储 router；拒绝访问返回 FORBIDDEN。\n *\n * @example\n * ```ts\n * import { storage } from '@h-ai/storage'\n * import { createStorageProcedures } from '@h-ai/serv/features/storage'\n *\n * // 宿主已初始化 Storage；用户根目录来自可信 session，含尾斜杠形成边界。\n * const procedures = createStorageProcedures({ storage, authorize: ({ context, keys }) => {\n *   const root = `users/${encodeURIComponent(context.session.userId)}/`\n *   return keys.length > 0 && keys.every(key => key.startsWith(root))\n * } })\n * // 空列表前缀与相邻用户名前缀均不能匹配此根目录。\n * ```\n */\nexport function createStorageProcedures(deps: StorageProcedureDeps) {\n  const { storage } = deps\n\n  async function authorize(request: StorageAccessRequest): Promise<HaiResult<void>> {\n    if (typeof deps.authorize !== 'function' || await deps.authorize(request) !== true)\n      return err(HaiCommonError.FORBIDDEN, servM('serv_errorForbidden', { locale: request.context.locale }))\n    return ok(undefined)\n  }\n\n  return implement(storageContract)\n    .context<ServContext>()\n\n    .route('presignedUrls.createDownload')\n    .auth()\n    .handle(async ({ input, context }) => {\n      const keyResult = validateStorageKeyOrFail(input.key, context.locale)\n      if (!keyResult.success)\n        return keyResult\n      const access = await authorize({ context, operation: 'download', keys: [keyResult.data] })\n      if (!access.success)\n        return access\n      const expiresIn = input.expiresIn ?? 900\n      return toPresignedResult(\n        keyResult.data,\n        expiresIn,\n        await storage.presign.getUrl(keyResult.data, { expiresIn }),\n      )\n    })\n\n    .route('presignedUrls.createUpload')\n    .auth()\n    .handle(async ({ input, context }) => {\n      const keyResult = validateStorageKeyOrFail(input.key, context.locale)\n      if (!keyResult.success)\n        return keyResult\n      const access = await authorize({ context, operation: 'upload', keys: [keyResult.data] })\n      if (!access.success)\n        return access\n      const expiresIn = input.expiresIn ?? 900\n      const contentType = input.contentType ?? 'application/octet-stream'\n      const { key: _, ...options } = input\n      return toPresignedResult(\n        keyResult.data,\n        expiresIn,\n        await storage.presign.putUrl(keyResult.data, { ...options, expiresIn, contentType }),\n      )\n    })\n\n    .route('files.list')\n    .auth()\n    .handle(async ({ input, context }) => {\n      const prefix = input.prefix ?? ''\n      if (prefix) {\n        const prefixResult = validateStorageKeyOrFail(prefix, context.locale, 'prefix')\n        if (!prefixResult.success)\n          return prefixResult\n      }\n      const access = await authorize({ context, operation: 'list', keys: [prefix] })\n      if (!access.success)\n        return access\n      return storage.dir.list(input)\n    })\n\n    .route('files.getMetadata')\n    .auth()\n    .handle(async ({ input, context }) => {\n      const keyResult = validateStorageKeyOrFail(input.key, context.locale)\n      if (!keyResult.success)\n        return keyResult\n      const access = await authorize({ context, operation: 'metadata', keys: [keyResult.data] })\n      if (!access.success)\n        return access\n      return storage.file.head(keyResult.data)\n    })\n\n    .route('files.delete')\n    .auth()\n    .handle(async ({ input, context }) => {\n      const keyResult = validateStorageKeyOrFail(input.key, context.locale)\n      if (!keyResult.success)\n        return keyResult\n      const access = await authorize({ context, operation: 'delete', keys: [keyResult.data] })\n      if (!access.success)\n        return access\n      return storage.file.delete(keyResult.data)\n    })\n\n    .route('files.deleteMany')\n    .auth()\n    .handle(async ({ input, context }) => {\n      const keysResult = validateStorageKeysOrFail(input.keys, context.locale)\n      if (!keysResult.success)\n        return keysResult\n      const access = await authorize({ context, operation: 'deleteMany', keys: keysResult.data })\n      if (!access.success)\n        return access\n      return storage.file.deleteMany(keysResult.data)\n    })\n\n    .build()\n}\n\nfunction toPresignedResult(\n  key: string,\n  expiresIn: number | undefined,\n  result: HaiResult<string>,\n): HaiResult<PresignedResponse> {\n  return mapHaiResult(result, url => ({\n    url,\n    key,\n    expiresAt: expiresIn ? new Date(Date.now() + expiresIn * 1000) : undefined,\n  }))\n}\n"]}