refactor(server): extract ZIP security checks into reusable safe-zip module

docs: remove outdated UX API docs (superseded by OpenAPI /api/docs)
fix(crypto): replace deprecated .passthrough() with .loose() (Zod 4)
2026-03-06 16:51:33 +08:00 · 2026-03-06 16:41:15 +08:00 · 2026-03-06 16:40:46 +08:00 · 2026-03-06 16:39:38 +08:00 · 2026-03-06 15:34:04 +08:00 · 2026-03-06 15:33:07 +08:00
53 changed files with 4798 additions and 600 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,11 @@
 # Bun build
 *.bun-build

+# SQLite database files
+*.db
+*.db-wal
+*.db-shm
+
 # Turborepo
 .turbo/

--- a/apps/server/.env.example
+++ b/apps/server/.env.example
@@ -1 +1 @@
-DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres
+DATABASE_PATH=data.db
--- a/apps/server/drizzle.config.ts
+++ b/apps/server/drizzle.config.ts
@@ -1,11 +1,12 @@
 import { defineConfig } from 'drizzle-kit'
-import { env } from '@/env'
+
+const databasePath = process.env.DATABASE_PATH ?? 'data.db'

 export default defineConfig({
  out: './drizzle',
  schema: './src/server/db/schema/index.ts',
-  dialect: 'postgresql',
+  dialect: 'sqlite',
  dbCredentials: {
-    url: env.DATABASE_URL,
+    url: databasePath,
  },
 })
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -14,15 +14,16 @@
    "compile:linux:x64": "bun compile.ts --target bun-linux-x64",
    "compile:windows": "bun run compile:windows:x64",
    "compile:windows:x64": "bun compile.ts --target bun-windows-x64",
-    "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate",
-    "db:push": "drizzle-kit push",
-    "db:studio": "drizzle-kit studio",
+    "db:generate": "bun --bun drizzle-kit generate",
+    "db:migrate": "bun --bun drizzle-kit migrate",
+    "db:push": "bun --bun drizzle-kit push",
+    "db:studio": "bun --bun drizzle-kit studio",
    "dev": "bunx --bun vite dev",
    "fix": "biome check --write",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
+    "@furtherverse/crypto": "workspace:*",
    "@orpc/client": "catalog:",
    "@orpc/contract": "catalog:",
    "@orpc/openapi": "catalog:",
@@ -35,9 +36,10 @@
    "@tanstack/react-router-ssr-query": "catalog:",
    "@tanstack/react-start": "catalog:",
    "drizzle-orm": "catalog:",
-    "postgres": "catalog:",
+    "jszip": "catalog:",
    "react": "catalog:",
    "react-dom": "catalog:",
+    "systeminformation": "catalog:",
    "uuid": "catalog:",
    "zod": "catalog:"
  },
@@ -54,6 +56,7 @@
    "drizzle-kit": "catalog:",
    "nitro": "catalog:",
    "tailwindcss": "catalog:",
-    "vite": "catalog:"
+    "vite": "catalog:",
+    "vite-tsconfig-paths": "catalog:"
  }
 }
--- a/apps/server/src/client/orpc.ts
+++ b/apps/server/src/client/orpc.ts
@@ -24,30 +24,4 @@ const getORPCClient = createIsomorphicFn()

 const client: RouterClient = getORPCClient()

-export const orpc = createTanstackQueryUtils(client, {
-  experimental_defaults: {
-    todo: {
-      create: {
-        mutationOptions: {
-          onSuccess: (_, __, ___, ctx) => {
-            ctx.client.invalidateQueries({ queryKey: orpc.todo.list.key() })
-          },
-        },
-      },
-      update: {
-        mutationOptions: {
-          onSuccess: (_, __, ___, ctx) => {
-            ctx.client.invalidateQueries({ queryKey: orpc.todo.list.key() })
-          },
-        },
-      },
-      remove: {
-        mutationOptions: {
-          onSuccess: (_, __, ___, ctx) => {
-            ctx.client.invalidateQueries({ queryKey: orpc.todo.list.key() })
-          },
-        },
-      },
-    },
-  },
-})
+export const orpc = createTanstackQueryUtils(client)
--- a/apps/server/src/env.ts
+++ b/apps/server/src/env.ts
@@ -3,7 +3,7 @@ import { z } from 'zod'

 export const env = createEnv({
  server: {
-    DATABASE_URL: z.url(),
+    DATABASE_PATH: z.string().min(1).default('data.db'),
  },
  clientPrefix: 'VITE_',
  client: {
--- a/apps/server/src/routes/api/$.ts
+++ b/apps/server/src/routes/api/$.ts
@@ -16,6 +16,7 @@ const handler = new OpenAPIHandler(router, {
        info: {
          title: name,
          version,
+          description: 'UX 授权服务 OpenAPI 文档：设备授权、任务解密、摘要加密与报告签名打包接口。',
        },
      },
      docsPath: '/docs',
--- a/apps/server/src/routes/index.tsx
+++ b/apps/server/src/routes/index.tsx
@@ -1,193 +1,21 @@
-import { useMutation, useSuspenseQuery } from '@tanstack/react-query'
 import { createFileRoute } from '@tanstack/react-router'
-import type { ChangeEventHandler, SubmitEventHandler } from 'react'
-import { useState } from 'react'
-import { orpc } from '@/client/orpc'

 export const Route = createFileRoute('/')({
-  component: Todos,
-  loader: async ({ context }) => {
-    await context.queryClient.ensureQueryData(orpc.todo.list.queryOptions())
-  },
+  component: Home,
 })

-function Todos() {
-  const [newTodoTitle, setNewTodoTitle] = useState('')
-
-  const listQuery = useSuspenseQuery(orpc.todo.list.queryOptions())
-  const createMutation = useMutation(orpc.todo.create.mutationOptions())
-  const updateMutation = useMutation(orpc.todo.update.mutationOptions())
-  const deleteMutation = useMutation(orpc.todo.remove.mutationOptions())
-
-  const handleCreateTodo: SubmitEventHandler<HTMLFormElement> = (e) => {
-    e.preventDefault()
-    if (newTodoTitle.trim()) {
-      createMutation.mutate({ title: newTodoTitle.trim() })
-      setNewTodoTitle('')
-    }
-  }
-
-  const handleInputChange: ChangeEventHandler<HTMLInputElement> = (e) => {
-    setNewTodoTitle(e.target.value)
-  }
-
-  const handleToggleTodo = (id: string, currentCompleted: boolean) => {
-    updateMutation.mutate({
-      id,
-      data: { completed: !currentCompleted },
-    })
-  }
-
-  const handleDeleteTodo = (id: string) => {
-    deleteMutation.mutate({ id })
-  }
-
-  const todos = listQuery.data
-  const completedCount = todos.filter((todo) => todo.completed).length
-  const totalCount = todos.length
-  const progress = totalCount > 0 ? (completedCount / totalCount) * 100 : 0
-
+function Home() {
  return (
-    <div className="min-h-screen bg-slate-50 py-12 px-4 sm:px-6 font-sans">
-      <div className="max-w-2xl mx-auto space-y-8">
-        {/* Header */}
-        <div className="flex items-end justify-between">
-          <div>
-            <h1 className="text-3xl font-bold text-slate-900 tracking-tight">我的待办</h1>
-            <p className="text-slate-500 mt-1">保持专注，逐个击破</p>
-          </div>
-          <div className="text-right">
-            <div className="text-2xl font-semibold text-slate-900">
-              {completedCount}
-              <span className="text-slate-400 text-lg">/{totalCount}</span>
-            </div>
-            <div className="text-xs font-medium text-slate-400 uppercase tracking-wider">已完成</div>
-          </div>
-        </div>
-
-        {/* Add Todo Form */}
-        <form onSubmit={handleCreateTodo} className="relative group z-10">
-          <div className="relative transform transition-all duration-200 focus-within:-translate-y-1">
-            <input
-              type="text"
-              value={newTodoTitle}
-              onChange={handleInputChange}
-              placeholder="添加新任务..."
-              className="w-full pl-6 pr-32 py-5 bg-white rounded-2xl shadow-[0_8px_30px_rgb(0,0,0,0.04)] border-0 ring-1 ring-slate-100 focus:ring-2 focus:ring-indigo-500/50 outline-none transition-all placeholder:text-slate-400 text-lg text-slate-700"
-              disabled={createMutation.isPending}
-            />
-            <button
-              type="submit"
-              disabled={createMutation.isPending || !newTodoTitle.trim()}
-              className="absolute right-3 top-3 bottom-3 px-6 bg-indigo-600 hover:bg-indigo-700 text-white rounded-xl font-medium transition-all shadow-md shadow-indigo-200 disabled:opacity-50 disabled:shadow-none hover:shadow-lg hover:shadow-indigo-300 active:scale-95"
-            >
-              {createMutation.isPending ? '添加中' : '添加'}
-            </button>
-          </div>
-        </form>
-
-        {/* Progress Bar (Only visible when there are tasks) */}
-        {totalCount > 0 && (
-          <div className="h-1.5 w-full bg-slate-200 rounded-full overflow-hidden">
-            <div
-              className="h-full bg-indigo-500 transition-all duration-500 ease-out rounded-full"
-              style={{ width: `${progress}%` }}
-            />
-          </div>
-        )}
-
-        {/* Todo List */}
-        <div className="space-y-3">
-          {todos.length === 0 ? (
-            <div className="py-20 text-center">
-              <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-slate-100 mb-4">
-                <svg
-                  className="w-8 h-8 text-slate-400"
-                  fill="none"
-                  viewBox="0 0 24 24"
-                  stroke="currentColor"
-                  aria-hidden="true"
-                >
-                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M12 6v6m0 0v6m0-6h6m-6 0H6" />
-                </svg>
-              </div>
-              <p className="text-slate-500 text-lg font-medium">没有待办事项</p>
-              <p className="text-slate-400 text-sm mt-1">输入上方内容添加您的第一个任务</p>
-            </div>
-          ) : (
-            todos.map((todo) => (
-              <div
-                key={todo.id}
-                className={`group relative flex items-center p-4 bg-white rounded-xl border border-slate-100 shadow-sm transition-all duration-200 hover:shadow-md hover:border-slate-200 ${
-                  todo.completed ? 'bg-slate-50/50' : ''
-                }`}
-              >
-                <button
-                  type="button"
-                  onClick={() => handleToggleTodo(todo.id, todo.completed)}
-                  className={`flex-shrink-0 w-6 h-6 rounded-full border-2 transition-all duration-200 flex items-center justify-center mr-4 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 ${
-                    todo.completed
-                      ? 'bg-indigo-500 border-indigo-500'
-                      : 'border-slate-300 hover:border-indigo-500 bg-white'
-                  }`}
-                >
-                  {todo.completed && (
-                    <svg
-                      className="w-3.5 h-3.5 text-white"
-                      fill="none"
-                      viewBox="0 0 24 24"
-                      stroke="currentColor"
-                      strokeWidth={3}
-                      aria-hidden="true"
-                    >
-                      <path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
-                    </svg>
-                  )}
-                </button>
-
-                <div className="flex-1 min-w-0">
-                  <p
-                    className={`text-lg transition-all duration-200 truncate ${
-                      todo.completed
-                        ? 'text-slate-400 line-through decoration-slate-300 decoration-2'
-                        : 'text-slate-700'
-                    }`}
-                  >
-                    {todo.title}
+    <div className="min-h-screen bg-slate-50 flex items-center justify-center font-sans">
+      <div className="text-center space-y-4">
+        <h1 className="text-3xl font-bold text-slate-900 tracking-tight">UX Server</h1>
+        <p className="text-slate-500">
+          API:&nbsp;
+          <a href="/api" className="text-indigo-600 hover:text-indigo-700 underline">
+            /api
+          </a>
        </p>
      </div>
-
-                <div className="flex items-center opacity-0 group-hover:opacity-100 transition-opacity duration-200 absolute right-4 pl-4 bg-gradient-to-l from-white via-white to-transparent sm:static sm:bg-none">
-                  <span className="text-xs text-slate-400 mr-3 hidden sm:inline-block">
-                    {new Date(todo.createdAt).toLocaleDateString('zh-CN')}
-                  </span>
-                  <button
-                    type="button"
-                    onClick={() => handleDeleteTodo(todo.id)}
-                    className="p-2 text-slate-400 hover:text-red-500 hover:bg-red-50 rounded-lg transition-colors focus:outline-none"
-                    title="删除"
-                  >
-                    <svg
-                      className="w-5 h-5"
-                      fill="none"
-                      viewBox="0 0 24 24"
-                      stroke="currentColor"
-                      strokeWidth={1.5}
-                      aria-hidden="true"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"
-                      />
-                    </svg>
-                  </button>
-                </div>
-              </div>
-            ))
-          )}
-        </div>
-      </div>
    </div>
  )
 }
--- a/apps/server/src/server/api/contracts/config.contract.ts
+++ b/apps/server/src/server/api/contracts/config.contract.ts
@@ -0,0 +1,82 @@
+import { oc } from '@orpc/contract'
+import { z } from 'zod'
+
+const configOutput = z
+  .object({
+    licence: z.string().nullable().describe('当前本地 licence，未设置时为 null'),
+    fingerprint: z.string().describe('UX 本机计算得到的设备特征码（SHA-256）'),
+    hasPgpPrivateKey: z.boolean().describe('是否已配置 OpenPGP 私钥'),
+  })
+  .meta({
+    examples: [
+      {
+        licence: 'LIC-8F2A-XXXX',
+        fingerprint: '9a3b7c1d2e4f5a6b8c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b',
+        hasPgpPrivateKey: true,
+      },
+      {
+        licence: null,
+        fingerprint: '9a3b7c1d2e4f5a6b8c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b',
+        hasPgpPrivateKey: false,
+      },
+    ],
+  })
+
+export const get = oc
+  .route({
+    method: 'POST',
+    path: '/config/get',
+    operationId: 'configGet',
+    summary: '读取本机身份配置',
+    description:
+      '返回 UX 本地持久化的 licence、本机设备特征码（fingerprint）以及 OpenPGP 私钥配置状态。工具箱端可据此判断是否已完成本地身份初始化。',
+    tags: ['Config'],
+  })
+  .input(z.object({}))
+  .output(configOutput)
+
+export const setLicence = oc
+  .route({
+    method: 'POST',
+    path: '/config/set-licence',
+    operationId: 'configSetLicence',
+    summary: '写入本地 licence',
+    description:
+      '写入或更新本机持久化的 licence。设备特征码（fingerprint）始终由 UX 本机自动计算，无需外部传入。此接口应在设备授权流程前调用。',
+    tags: ['Config'],
+  })
+  .input(
+    z
+      .object({
+        licence: z.string().min(1).describe('本地持久化的 licence'),
+      })
+      .meta({
+        examples: [{ licence: 'LIC-8F2A-XXXX' }],
+      }),
+  )
+  .output(configOutput)
+
+export const setPgpPrivateKey = oc
+  .route({
+    method: 'POST',
+    path: '/config/set-pgp-private-key',
+    operationId: 'configSetPgpPrivateKey',
+    summary: '写入本地 OpenPGP 私钥',
+    description:
+      '写入或更新本机持久化的 OpenPGP 私钥（ASCII armored 格式），用于报告签名。私钥与设备绑定，调用报告签名接口时 UX 自动读取，无需每次传入。',
+    tags: ['Config'],
+  })
+  .input(
+    z
+      .object({
+        pgpPrivateKey: z.string().min(1).describe('OpenPGP 私钥（ASCII armored 格式）'),
+      })
+      .meta({
+        examples: [
+          {
+            pgpPrivateKey: '-----BEGIN PGP PRIVATE KEY BLOCK-----\n\nxcMGBGd...\n-----END PGP PRIVATE KEY BLOCK-----',
+          },
+        ],
+      }),
+  )
+  .output(configOutput)
--- a/apps/server/src/server/api/contracts/crypto.contract.ts
+++ b/apps/server/src/server/api/contracts/crypto.contract.ts
@@ -0,0 +1,150 @@
+import { oc } from '@orpc/contract'
+import { z } from 'zod'
+
+export const encryptDeviceInfo = oc
+  .route({
+    method: 'POST',
+    path: '/crypto/encrypt-device-info',
+    operationId: 'encryptDeviceInfo',
+    summary: '生成设备授权二维码密文',
+    description:
+      '将本机 licence 与 fingerprint 组装为 JSON，使用平台 RSA 公钥（RSA-OAEP + SHA-256）加密后返回 Base64 密文，供工具箱生成设备授权二维码。参见《工具箱端 - 设备授权二维码生成指南》。',
+    tags: ['Crypto'],
+  })
+  .input(
+    z
+      .object({
+        platformPublicKey: z.string().min(1).describe('平台公钥（Base64，SPKI DER）'),
+      })
+      .meta({
+        examples: [
+          {
+            platformPublicKey:
+              'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzDlZvMDVaL+fjl05Hi182JOAUAaN4gh9rOF+1NhKfO4J6e0HLy8lBuylp3A4xoTiyUejNm22h0dqAgDSPnY/xZR76POFTD1soHr2LaFCN8JAbQ96P8gE7wC9qpoTssVvIVRH7QbVd260J6eD0Szwcx9cg591RSN69pMpe5IVRi8T99Hhql6/wnZHORPr18eESLOY93jRskLzc0q18r68RRoTJiQf+9YC8ub5iKp7rCjVnPi1UbIYmXmL08tk5mksYA0NqWQAa1ofKxx/9tQtB9uTjhTxuTu94XU9jlGU87qaHZs+kpqa8CAbYYJFbSP1xHwoZzpU2jpw2aF22HBYxwIDAQAB',
+          },
+        ],
+      }),
+  )
+  .output(
+    z
+      .object({
+        encrypted: z.string().describe('Base64 密文（用于设备授权二维码）'),
+      })
+      .meta({
+        examples: [
+          {
+            encrypted: 'dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIFJTQS1PQUVQIGVuY3J5cHRlZCBkZXZpY2UgaW5mby4uLg==',
+          },
+        ],
+      }),
+  )
+
+export const decryptTask = oc
+  .route({
+    method: 'POST',
+    path: '/crypto/decrypt-task',
+    operationId: 'decryptTask',
+    summary: '解密任务二维码数据',
+    description:
+      '使用本机 licence 与 fingerprint 派生 AES-256-GCM 密钥（SHA-256），解密 App 任务二维码中的 Base64 密文，返回任务信息明文。参见《工具箱端 - 任务二维码解密指南》。',
+    tags: ['Crypto'],
+  })
+  .input(
+    z
+      .object({
+        encryptedData: z.string().min(1).describe('Base64 编码的 AES-256-GCM 密文（来自任务二维码扫描结果）'),
+      })
+      .meta({
+        examples: [
+          {
+            encryptedData: 'uWUcAmp6UQd0w3G3crdsd4613QCxGLoEgslgXJ4G2hQhpQdjtghtQjCBUZwB/JO+NRgH1vSTr8dqBJRq7Qh4nug==',
+          },
+        ],
+      }),
+  )
+  .output(
+    z
+      .object({
+        decrypted: z.string().describe('解密后的任务信息 JSON 字符串'),
+      })
+      .meta({
+        examples: [
+          {
+            decrypted:
+              '{"taskId":"TASK-20260115-4875","enterpriseId":"1173040813421105152","orgName":"超艺科技有限公司","inspectionId":"702286470691215417","inspectionPerson":"警务通","issuedAt":1734571234567}',
+          },
+        ],
+      }),
+  )
+
+export const encryptSummary = oc
+  .route({
+    method: 'POST',
+    path: '/crypto/encrypt-summary',
+    operationId: 'encryptSummary',
+    summary: '加密摘要信息',
+    description:
+      '使用本机 licence 与 fingerprint 通过 HKDF-SHA256 派生密钥，以 AES-256-GCM 加密检查摘要明文并返回 Base64 密文，供工具箱生成摘要信息二维码。参见《工具箱端 - 摘要信息二维码生成指南》。',
+    tags: ['Crypto'],
+  })
+  .input(
+    z
+      .object({
+        salt: z.string().min(1).describe('HKDF salt（即 taskId，从任务二维码中获取）'),
+        plaintext: z.string().min(1).describe('待加密的摘要信息 JSON 明文'),
+      })
+      .meta({
+        examples: [
+          {
+            salt: 'TASK-20260115-4875',
+            plaintext:
+              '{"enterpriseId":"1173040813421105152","inspectionId":"702286470691215417","summary":"检查摘要信息：发现3个高危漏洞，5个中危漏洞","timestamp":1734571234567}',
+          },
+        ],
+      }),
+  )
+  .output(
+    z
+      .object({
+        encrypted: z.string().describe('Base64 密文（用于摘要信息二维码）'),
+      })
+      .meta({
+        examples: [
+          {
+            encrypted: 'uWUcAmp6UQd0w3G3crdsd4613QCxGLoEgslgXJ4G2hQhpQdjtghtQjCBUZwB/JO+NRgH1vSTr8dqBJRq7Qh4nug==',
+          },
+        ],
+      }),
+  )
+
+export const signAndPackReport = oc
+  .route({
+    method: 'POST',
+    path: '/crypto/sign-and-pack-report',
+    operationId: 'signAndPackReport',
+    summary: '签名并打包检查报告',
+    description:
+      '上传包含 summary.json 的原始报告 ZIP，UX 自动从 ZIP 中提取 summary.json，使用本地存储的 licence/fingerprint 计算设备签名（HKDF + HMAC-SHA256），并使用本地 OpenPGP 私钥生成分离式签名。返回包含 summary.json（含 deviceSignature）、META-INF/manifest.json、META-INF/signature.asc 的签名报告 ZIP。参见《工具箱端 - 报告加密与签名生成指南》。',
+    tags: ['Crypto', 'Report'],
+  })
+  .input(
+    z.object({
+      rawZip: z
+        .file()
+        .mime(['application/zip', 'application/x-zip-compressed'])
+        .describe(
+          '原始报告 ZIP 文件（必须包含 summary.json，以及 assets.json、vulnerabilities.json、weakPasswords.json、漏洞评估报告.html 等报告文件）',
+        ),
+      outputFileName: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('返回 ZIP 文件名（可选，默认 signed-report.zip）')
+        .meta({ examples: ['signed-report.zip'] }),
+    }),
+  )
+  .output(
+    z
+      .file()
+      .describe('签名后报告 ZIP 文件（二进制响应，包含 summary.json、META-INF/manifest.json、META-INF/signature.asc）'),
+  )
--- a/apps/server/src/server/api/contracts/index.ts
+++ b/apps/server/src/server/api/contracts/index.ts
@@ -1,7 +1,9 @@
-import * as todo from './todo.contract'
+import * as config from './config.contract'
+import * as crypto from './crypto.contract'

 export const contract = {
-  todo,
+  config,
+  crypto,
 }

 export type Contract = typeof contract
--- a/apps/server/src/server/api/contracts/todo.contract.ts
+++ b/apps/server/src/server/api/contracts/todo.contract.ts
@@ -1,32 +0,0 @@
-import { oc } from '@orpc/contract'
-import { createInsertSchema, createSelectSchema, createUpdateSchema } from 'drizzle-orm/zod'
-import { z } from 'zod'
-import { generatedFieldKeys } from '@/server/db/fields'
-import { todoTable } from '@/server/db/schema'
-
-const selectSchema = createSelectSchema(todoTable)
-
-const insertSchema = createInsertSchema(todoTable).omit(generatedFieldKeys)
-
-const updateSchema = createUpdateSchema(todoTable).omit(generatedFieldKeys)
-
-export const list = oc.input(z.void()).output(z.array(selectSchema))
-
-export const create = oc.input(insertSchema).output(selectSchema)
-
-export const update = oc
-  .input(
-    z.object({
-      id: z.uuid(),
-      data: updateSchema,
-    }),
-  )
-  .output(selectSchema)
-
-export const remove = oc
-  .input(
-    z.object({
-      id: z.uuid(),
-    }),
-  )
-  .output(z.void())
--- a/apps/server/src/server/api/routers/config.router.ts
+++ b/apps/server/src/server/api/routers/config.router.ts
@@ -0,0 +1,24 @@
+import { ensureUxConfig, setUxLicence, setUxPgpPrivateKey } from '@/server/ux-config'
+import { db } from '../middlewares'
+import { os } from '../server'
+
+const toConfigOutput = (config: { licence: string | null; fingerprint: string; pgpPrivateKey: string | null }) => ({
+  licence: config.licence,
+  fingerprint: config.fingerprint,
+  hasPgpPrivateKey: config.pgpPrivateKey != null,
+})
+
+export const get = os.config.get.use(db).handler(async ({ context }) => {
+  const config = await ensureUxConfig(context.db)
+  return toConfigOutput(config)
+})
+
+export const setLicence = os.config.setLicence.use(db).handler(async ({ context, input }) => {
+  const config = await setUxLicence(context.db, input.licence)
+  return toConfigOutput(config)
+})
+
+export const setPgpPrivateKey = os.config.setPgpPrivateKey.use(db).handler(async ({ context, input }) => {
+  const config = await setUxPgpPrivateKey(context.db, input.pgpPrivateKey)
+  return toConfigOutput(config)
+})
--- a/apps/server/src/server/api/routers/crypto.router.ts
+++ b/apps/server/src/server/api/routers/crypto.router.ts
@@ -0,0 +1,171 @@
+import {
+  aesGcmDecrypt,
+  aesGcmEncrypt,
+  hkdfSha256,
+  hmacSha256Base64,
+  pgpSignDetached,
+  rsaOaepEncrypt,
+  sha256,
+  sha256Hex,
+} from '@furtherverse/crypto'
+import { ORPCError } from '@orpc/server'
+import JSZip from 'jszip'
+import { z } from 'zod'
+import { extractSafeZipFiles, ZipValidationError } from '@/server/safe-zip'
+import { getUxConfig } from '@/server/ux-config'
+import { db } from '../middlewares'
+import { os } from '../server'
+
+const summaryPayloadSchema = z
+  .object({
+    taskId: z.string().min(1, 'summary.json must contain a non-empty taskId'),
+    checkId: z.string().optional(),
+    inspectionId: z.string().optional(),
+  })
+  .loose()
+
+const requireIdentity = async (dbInstance: Parameters<typeof getUxConfig>[0]) => {
+  const config = await getUxConfig(dbInstance)
+  if (!config || !config.licence) {
+    throw new ORPCError('PRECONDITION_FAILED', {
+      message: 'Local identity is not initialized. Call config.get and then config.setLicence first.',
+    })
+  }
+  return config as typeof config & { licence: string }
+}
+
+export const encryptDeviceInfo = os.crypto.encryptDeviceInfo.use(db).handler(async ({ context, input }) => {
+  const config = await requireIdentity(context.db)
+
+  const deviceInfoJson = JSON.stringify({
+    licence: config.licence,
+    fingerprint: config.fingerprint,
+  })
+
+  const encrypted = rsaOaepEncrypt(deviceInfoJson, input.platformPublicKey)
+  return { encrypted }
+})
+
+export const decryptTask = os.crypto.decryptTask.use(db).handler(async ({ context, input }) => {
+  const config = await requireIdentity(context.db)
+
+  const key = sha256(config.licence + config.fingerprint)
+  const decrypted = aesGcmDecrypt(input.encryptedData, key)
+  return { decrypted }
+})
+
+export const encryptSummary = os.crypto.encryptSummary.use(db).handler(async ({ context, input }) => {
+  const config = await requireIdentity(context.db)
+
+  const ikm = config.licence + config.fingerprint
+  const aesKey = hkdfSha256(ikm, input.salt, 'inspection_report_encryption')
+  const encrypted = aesGcmEncrypt(input.plaintext, aesKey)
+  return { encrypted }
+})
+
+export const signAndPackReport = os.crypto.signAndPackReport.use(db).handler(async ({ context, input }) => {
+  const config = await requireIdentity(context.db)
+
+  if (!config.pgpPrivateKey) {
+    throw new ORPCError('PRECONDITION_FAILED', {
+      message: 'PGP private key is not configured. Call config.setPgpPrivateKey first.',
+    })
+  }
+
+  const rawZipBytes = Buffer.from(await input.rawZip.arrayBuffer())
+
+  const zipFiles = await extractSafeZipFiles(rawZipBytes).catch((error) => {
+    if (error instanceof ZipValidationError) {
+      throw new ORPCError('BAD_REQUEST', { message: error.message })
+    }
+    throw error
+  })
+
+  // Extract and validate summary.json from the ZIP
+  const summaryFile = zipFiles.find((f) => f.name === 'summary.json')
+  if (!summaryFile) {
+    throw new ORPCError('BAD_REQUEST', {
+      message: 'rawZip must contain a summary.json file',
+    })
+  }
+
+  let rawJson: unknown
+  try {
+    rawJson = JSON.parse(Buffer.from(summaryFile.bytes).toString('utf-8'))
+  } catch {
+    throw new ORPCError('BAD_REQUEST', {
+      message: 'summary.json in the ZIP is not valid JSON',
+    })
+  }
+
+  const parsed = summaryPayloadSchema.safeParse(rawJson)
+  if (!parsed.success) {
+    throw new ORPCError('BAD_REQUEST', {
+      message: `Invalid summary.json: ${z.prettifyError(parsed.error)}`,
+    })
+  }
+
+  const summaryPayload = parsed.data
+  const checkId = summaryPayload.checkId ?? summaryPayload.inspectionId ?? ''
+  const signingContext = `${summaryPayload.taskId}${checkId}`
+
+  // Compute device signature
+  const ikm = config.licence + config.fingerprint
+  const signingKey = hkdfSha256(ikm, 'AUTH_V3_SALT', 'device_report_signature')
+
+  const fileHashEntries = zipFiles
+    .map((item) => ({
+      name: item.name,
+      hash: sha256Hex(Buffer.from(item.bytes)),
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name, 'en'))
+
+  const hashPayload = fileHashEntries.map((item) => `${item.name}:${item.hash}`).join('|')
+  const signPayload = `${signingContext}|${hashPayload}`
+  const deviceSignature = hmacSha256Base64(signingKey, signPayload)
+
+  // Build final summary.json with device signature and identity
+  const finalSummary = {
+    deviceSignature,
+    signingContext,
+    licence: config.licence,
+    fingerprint: config.fingerprint,
+    payload: summaryPayload,
+    timestamp: Date.now(),
+  }
+  const summaryBytes = Buffer.from(JSON.stringify(finalSummary), 'utf-8')
+
+  // Build manifest.json
+  const manifestFiles: Record<string, string> = {
+    'summary.json': sha256Hex(summaryBytes),
+  }
+  for (const item of fileHashEntries) {
+    if (item.name !== 'summary.json') {
+      manifestFiles[item.name] = item.hash
+    }
+  }
+
+  const manifestBytes = Buffer.from(JSON.stringify({ files: manifestFiles }, null, 2), 'utf-8')
+  const signatureAsc = await pgpSignDetached(manifestBytes, config.pgpPrivateKey)
+
+  // Pack signed ZIP
+  const signedZip = new JSZip()
+  signedZip.file('summary.json', summaryBytes)
+  for (const item of zipFiles) {
+    if (item.name !== 'summary.json') {
+      signedZip.file(item.name, item.bytes)
+    }
+  }
+  signedZip.file('META-INF/manifest.json', manifestBytes)
+  signedZip.file('META-INF/signature.asc', signatureAsc)
+
+  const signedZipBytes = await signedZip.generateAsync({
+    type: 'uint8array',
+    compression: 'DEFLATE',
+    compressionOptions: { level: 9 },
+  })
+
+  return new File([Buffer.from(signedZipBytes)], input.outputFileName ?? 'signed-report.zip', {
+    type: 'application/zip',
+  })
+})
--- a/apps/server/src/server/api/routers/index.ts
+++ b/apps/server/src/server/api/routers/index.ts
@@ -1,6 +1,8 @@
 import { os } from '../server'
-import * as todo from './todo.router'
+import * as config from './config.router'
+import * as crypto from './crypto.router'

 export const router = os.router({
-  todo,
+  config,
+  crypto,
 })
--- a/apps/server/src/server/api/routers/todo.router.ts
+++ b/apps/server/src/server/api/routers/todo.router.ts
@@ -1,40 +0,0 @@
-import { ORPCError } from '@orpc/server'
-import { eq } from 'drizzle-orm'
-import { todoTable } from '@/server/db/schema'
-import { db } from '../middlewares'
-import { os } from '../server'
-
-export const list = os.todo.list.use(db).handler(async ({ context }) => {
-  const todos = await context.db.query.todoTable.findMany({
-    orderBy: { createdAt: 'desc' },
-  })
-  return todos
-})
-
-export const create = os.todo.create.use(db).handler(async ({ context, input }) => {
-  const [newTodo] = await context.db.insert(todoTable).values(input).returning()
-
-  if (!newTodo) {
-    throw new ORPCError('INTERNAL_SERVER_ERROR', { message: 'Failed to create todo' })
-  }
-
-  return newTodo
-})
-
-export const update = os.todo.update.use(db).handler(async ({ context, input }) => {
-  const [updatedTodo] = await context.db.update(todoTable).set(input.data).where(eq(todoTable.id, input.id)).returning()
-
-  if (!updatedTodo) {
-    throw new ORPCError('NOT_FOUND')
-  }
-
-  return updatedTodo
-})
-
-export const remove = os.todo.remove.use(db).handler(async ({ context, input }) => {
-  const [deleted] = await context.db.delete(todoTable).where(eq(todoTable.id, input.id)).returning({ id: todoTable.id })
-
-  if (!deleted) {
-    throw new ORPCError('NOT_FOUND')
-  }
-})
--- a/apps/server/src/server/db/fields.ts
+++ b/apps/server/src/server/db/fields.ts
@@ -1,47 +1,28 @@
-import { sql } from 'drizzle-orm'
-import { timestamp, uuid } from 'drizzle-orm/pg-core'
+import { integer, text } from 'drizzle-orm/sqlite-core'
 import { v7 as uuidv7 } from 'uuid'

-// id
-
-const id = (name: string) => uuid(name)
-export const pk = (name: string, strategy?: 'native' | 'extension') => {
-  switch (strategy) {
-    // PG 18+
-    case 'native':
-      return id(name).primaryKey().default(sql`uuidv7()`)
-
-    // PG 13+ with extension
-    case 'extension':
-      return id(name).primaryKey().default(sql`uuid_generate_v7()`)
-
-    // Any PG version
-    default:
-      return id(name)
+export const pk = (name = 'id') =>
+  text(name)
    .primaryKey()
    .$defaultFn(() => uuidv7())
-  }
-}

-// timestamp
-
-export const createdAt = (name = 'created_at') => timestamp(name, { withTimezone: true }).notNull().defaultNow()
+export const createdAt = (name = 'created_at') =>
+  integer(name, { mode: 'timestamp_ms' })
+    .notNull()
+    .$defaultFn(() => new Date())

 export const updatedAt = (name = 'updated_at') =>
-  timestamp(name, { withTimezone: true })
+  integer(name, { mode: 'timestamp_ms' })
    .notNull()
-    .defaultNow()
+    .$defaultFn(() => new Date())
    .$onUpdateFn(() => new Date())

-// generated fields
-
 export const generatedFields = {
  id: pk('id'),
  createdAt: createdAt('created_at'),
  updatedAt: updatedAt('updated_at'),
 }

-// Helper to create omit keys from generatedFields
 const createGeneratedFieldKeys = <T extends Record<string, unknown>>(fields: T): Record<keyof T, true> => {
  return Object.keys(fields).reduce(
    (acc, key) => {
--- a/apps/server/src/server/db/index.ts
+++ b/apps/server/src/server/db/index.ts
@@ -1,12 +1,14 @@
-import { drizzle } from 'drizzle-orm/postgres-js'
+import { Database } from 'bun:sqlite'
+import { drizzle } from 'drizzle-orm/bun-sqlite'
 import { env } from '@/env'
 import { relations } from '@/server/db/relations'

-export const createDB = () =>
-  drizzle({
-    connection: env.DATABASE_URL,
-    relations,
-  })
+export const createDB = () => {
+  const sqlite = new Database(env.DATABASE_PATH)
+  sqlite.exec('PRAGMA journal_mode = WAL')
+  sqlite.exec('PRAGMA foreign_keys = ON')
+  return drizzle({ client: sqlite, relations })
+}

 export type DB = ReturnType<typeof createDB>

--- a/apps/server/src/server/db/relations.ts
+++ b/apps/server/src/server/db/relations.ts
@@ -1,4 +1,4 @@
 import { defineRelations } from 'drizzle-orm'
 import * as schema from './schema'

-export const relations = defineRelations(schema, (_r) => ({}))
+export const relations = defineRelations(schema, () => ({}))
--- a/apps/server/src/server/db/schema/index.ts
+++ b/apps/server/src/server/db/schema/index.ts
@@ -1 +1 @@
-export * from './todo'
+export * from './ux-config'
--- a/apps/server/src/server/db/schema/todo.ts
+++ b/apps/server/src/server/db/schema/todo.ts
@@ -1,8 +0,0 @@
-import { boolean, pgTable, text } from 'drizzle-orm/pg-core'
-import { generatedFields } from '../fields'
-
-export const todoTable = pgTable('todo', {
-  ...generatedFields,
-  title: text('title').notNull(),
-  completed: boolean('completed').notNull().default(false),
-})
--- a/apps/server/src/server/db/schema/ux-config.ts
+++ b/apps/server/src/server/db/schema/ux-config.ts
@@ -0,0 +1,10 @@
+import { sqliteTable, text } from 'drizzle-orm/sqlite-core'
+import { generatedFields } from '../fields'
+
+export const uxConfigTable = sqliteTable('ux_config', {
+  ...generatedFields,
+  singletonKey: text('singleton_key').notNull().unique().default('default'),
+  licence: text('licence'),
+  fingerprint: text('fingerprint').notNull(),
+  pgpPrivateKey: text('pgp_private_key'),
+})
--- a/apps/server/src/server/device-fingerprint.ts
+++ b/apps/server/src/server/device-fingerprint.ts
@@ -0,0 +1,10 @@
+import { sha256Hex } from '@furtherverse/crypto'
+import { system } from 'systeminformation'
+
+export const computeDeviceFingerprint = async (): Promise<string> => {
+  const { uuid, serial, model, manufacturer } = await system()
+  const source = [uuid, serial, model, manufacturer].join('|')
+  const hash = sha256Hex(source)
+
+  return hash
+}
--- a/apps/server/src/server/safe-zip.ts
+++ b/apps/server/src/server/safe-zip.ts
@@ -0,0 +1,96 @@
+import type { JSZipObject } from 'jszip'
+import JSZip from 'jszip'
+
+export class ZipValidationError extends Error {
+  override name = 'ZipValidationError'
+}
+
+export interface ZipFileItem {
+  name: string
+  bytes: Uint8Array
+}
+
+export interface SafeZipOptions {
+  maxRawBytes?: number
+  maxEntries?: number
+  maxSingleFileBytes?: number
+  maxTotalUncompressedBytes?: number
+}
+
+const DEFAULTS = {
+  maxRawBytes: 50 * 1024 * 1024,
+  maxEntries: 64,
+  maxSingleFileBytes: 20 * 1024 * 1024,
+  maxTotalUncompressedBytes: 60 * 1024 * 1024,
+} satisfies Required<SafeZipOptions>
+
+const normalizePath = (name: string): string => name.replaceAll('\\', '/')
+
+const isUnsafePath = (name: string): boolean => {
+  const normalized = normalizePath(name)
+  const segments = normalized.split('/')
+
+  return (
+    normalized.startsWith('/') ||
+    normalized.includes('\0') ||
+    segments.some((segment) => segment === '..' || segment.trim().length === 0)
+  )
+}
+
+export const extractSafeZipFiles = async (
+  rawBytes: Uint8Array | Buffer,
+  options?: SafeZipOptions,
+): Promise<ZipFileItem[]> => {
+  const opts = { ...DEFAULTS, ...options }
+
+  if (rawBytes.byteLength === 0 || rawBytes.byteLength > opts.maxRawBytes) {
+    throw new ZipValidationError('ZIP is empty or exceeds max size limit')
+  }
+
+  const zip = await JSZip.loadAsync(rawBytes, { checkCRC32: true }).catch(() => {
+    throw new ZipValidationError('Not a valid ZIP file')
+  })
+
+  const entries = Object.values(zip.files) as JSZipObject[]
+  if (entries.length > opts.maxEntries) {
+    throw new ZipValidationError(`ZIP contains too many entries: ${entries.length}`)
+  }
+
+  let totalUncompressedBytes = 0
+  const files: ZipFileItem[] = []
+  const seen = new Set<string>()
+
+  for (const entry of entries) {
+    if (entry.dir) {
+      continue
+    }
+
+    if (isUnsafePath(entry.name)) {
+      throw new ZipValidationError(`ZIP contains unsafe entry path: ${entry.name}`)
+    }
+
+    const normalizedName = normalizePath(entry.name)
+    if (seen.has(normalizedName)) {
+      throw new ZipValidationError(`ZIP contains duplicate entry: ${normalizedName}`)
+    }
+    seen.add(normalizedName)
+
+    const content = await entry.async('uint8array')
+    if (content.byteLength > opts.maxSingleFileBytes) {
+      throw new ZipValidationError(`ZIP entry too large: ${normalizedName}`)
+    }
+
+    totalUncompressedBytes += content.byteLength
+    if (totalUncompressedBytes > opts.maxTotalUncompressedBytes) {
+      throw new ZipValidationError('ZIP total uncompressed content exceeds max size limit')
+    }
+
+    files.push({ name: normalizedName, bytes: content })
+  }
+
+  if (files.length === 0) {
+    throw new ZipValidationError('ZIP has no file entries')
+  }
+
+  return files
+}
--- a/apps/server/src/server/ux-config.ts
+++ b/apps/server/src/server/ux-config.ts
@@ -0,0 +1,56 @@
+import { eq } from 'drizzle-orm'
+import type { DB } from '@/server/db'
+import { uxConfigTable } from '@/server/db/schema'
+import { computeDeviceFingerprint } from './device-fingerprint'
+
+const UX_CONFIG_KEY = 'default'
+
+export const getUxConfig = async (db: DB) => {
+  return await db.query.uxConfigTable.findFirst({
+    where: { singletonKey: UX_CONFIG_KEY },
+  })
+}
+
+export const ensureUxConfig = async (db: DB) => {
+  const fingerprint = await computeDeviceFingerprint()
+  const existing = await getUxConfig(db)
+
+  if (existing) {
+    if (existing.fingerprint !== fingerprint) {
+      const rows = await db
+        .update(uxConfigTable)
+        .set({ fingerprint })
+        .where(eq(uxConfigTable.id, existing.id))
+        .returning()
+      return rows[0] as (typeof rows)[number]
+    }
+    return existing
+  }
+
+  const rows = await db
+    .insert(uxConfigTable)
+    .values({
+      singletonKey: UX_CONFIG_KEY,
+      fingerprint,
+      licence: null,
+    })
+    .returning()
+
+  return rows[0] as (typeof rows)[number]
+}
+
+export const setUxLicence = async (db: DB, licence: string) => {
+  const config = await ensureUxConfig(db)
+
+  const rows = await db.update(uxConfigTable).set({ licence }).where(eq(uxConfigTable.id, config.id)).returning()
+
+  return rows[0] as (typeof rows)[number]
+}
+
+export const setUxPgpPrivateKey = async (db: DB, pgpPrivateKey: string) => {
+  const config = await ensureUxConfig(db)
+
+  const rows = await db.update(uxConfigTable).set({ pgpPrivateKey }).where(eq(uxConfigTable.id, config.id)).returning()
+
+  return rows[0] as (typeof rows)[number]
+}
--- a/apps/server/vite.config.ts
+++ b/apps/server/vite.config.ts
@@ -4,12 +4,14 @@ import { tanstackStart } from '@tanstack/react-start/plugin/vite'
 import react from '@vitejs/plugin-react'
 import { nitro } from 'nitro/vite'
 import { defineConfig } from 'vite'
+import tsconfigPaths from 'vite-tsconfig-paths'

 export default defineConfig({
  clearScreen: false,
  plugins: [
    tanstackDevtools(),
    tailwindcss(),
+    tsconfigPaths(),
    tanstackStart(),
    react({
      babel: {
@@ -21,9 +23,6 @@ export default defineConfig({
      serveStatic: 'inline',
    }),
  ],
-  resolve: {
-    tsconfigPaths: true,
-  },
  server: {
    port: 3000,
    strictPort: true,
--- a/bun.lock
+++ b/bun.lock
--- a/docs/工具箱端-授权对接指南/utils/AesGcmUtil.kt
+++ b/docs/工具箱端-授权对接指南/utils/AesGcmUtil.kt
@@ -0,0 +1,124 @@
+package top.tangyh.lamp.filing.utils
+
+import io.github.oshai.kotlinlogging.KotlinLogging
+import java.nio.charset.StandardCharsets
+import java.util.*
+import javax.crypto.Cipher
+import javax.crypto.spec.GCMParameterSpec
+import javax.crypto.spec.SecretKeySpec
+
+private val logger = KotlinLogging.logger {}
+
+/**
+ * AES-256-GCM 加密解密工具类
+ * 
+ * 安全设计说明：
+ * - 使用 AES-256-GCM 提供认证加密（AEAD）
+ * - GCM 模式自动提供认证标签（tag），防止数据被篡改
+ * - IV（初始化向量）长度为 12 字节（96位），符合 GCM 推荐
+ * - 认证标签长度为 16 字节（128位），提供强认证
+ * - 加密数据格式：IV (12字节) + Ciphertext (变长) + Tag (16字节)
+ * 
+ * 为什么第三方无法伪造：
+ * - 只有拥有正确 licence + fingerprint 的设备才能派生正确的 AES 密钥
+ * - GCM 模式会验证认证标签，任何篡改都会导致解密失败
+ * - 即使第三方获取了加密数据，也无法解密（缺少密钥）
+ */
+object AesGcmUtil {
+
+    private const val ALGORITHM = "AES"
+    private const val TRANSFORMATION = "AES/GCM/NoPadding"
+    private const val IV_LENGTH = 12 // 12 bytes = 96 bits (GCM 推荐)
+    private const val TAG_LENGTH = 16 // 16 bytes = 128 bits (GCM 认证标签长度)
+    private const val GCM_TAG_LENGTH_BITS = TAG_LENGTH * 8 // 128 bits
+
+    /**
+     * 解密 AES-256-GCM 加密的数据
+     * 
+     * @param encryptedData Base64 编码的加密数据（格式：iv + ciphertext + tag）
+     * @param key AES 密钥（32字节）
+     * @return 解密后的明文（UTF-8 字符串）
+     * @throws RuntimeException 如果解密失败（密钥错误、数据被篡改等）
+     */
+    fun decrypt(encryptedData: String, key: ByteArray): String {
+        return try {
+            // 1. Base64 解码
+            val encryptedBytes = Base64.getDecoder().decode(encryptedData)
+
+            // 2. 提取 IV、密文和认证标签
+            if (encryptedBytes.size < IV_LENGTH + TAG_LENGTH) {
+                throw IllegalArgumentException("加密数据长度不足，无法提取 IV 和 Tag")
+            }
+
+            val iv = encryptedBytes.copyOfRange(0, IV_LENGTH)
+            val tag = encryptedBytes.copyOfRange(encryptedBytes.size - TAG_LENGTH, encryptedBytes.size)
+            val ciphertext = encryptedBytes.copyOfRange(IV_LENGTH, encryptedBytes.size - TAG_LENGTH)
+
+            // 3. 创建 SecretKeySpec
+            val secretKey = SecretKeySpec(key, ALGORITHM)
+
+            // 4. 创建 GCMParameterSpec（包含 IV 和认证标签长度）
+            val gcmSpec = GCMParameterSpec(GCM_TAG_LENGTH_BITS, iv)
+
+            // 5. 初始化 Cipher 进行解密
+            val cipher = Cipher.getInstance(TRANSFORMATION)
+            cipher.init(Cipher.DECRYPT_MODE, secretKey, gcmSpec)
+
+            // 6. 执行解密（GCM 模式会自动验证认证标签）
+            // 如果认证标签验证失败，会抛出异常
+            val decryptedBytes = cipher.doFinal(ciphertext + tag)
+
+            // 7. 转换为 UTF-8 字符串
+            String(decryptedBytes, StandardCharsets.UTF_8)
+        } catch (e: javax.crypto.AEADBadTagException) {
+            logger.error(e) { "AES-GCM 认证标签验证失败，数据可能被篡改或密钥错误" }
+            throw RuntimeException("解密失败：认证标签验证失败，数据可能被篡改或密钥错误", e)
+        } catch (e: Exception) {
+            logger.error(e) { "AES-GCM 解密失败" }
+            throw RuntimeException("解密失败: ${e.message}", e)
+        }
+    }
+
+    /**
+     * 加密数据（用于测试或客户端实现参考）
+     * 
+     * @param plaintext 明文数据
+     * @param key AES 密钥（32字节）
+     * @return Base64 编码的加密数据（格式：iv + ciphertext + tag）
+     */
+    fun encrypt(plaintext: String, key: ByteArray): String {
+        return try {
+            // 1. 生成随机 IV
+            val iv = ByteArray(IV_LENGTH)
+            java.security.SecureRandom().nextBytes(iv)
+
+            // 2. 创建 SecretKeySpec
+            val secretKey = SecretKeySpec(key, ALGORITHM)
+
+            // 3. 创建 GCMParameterSpec
+            val gcmSpec = GCMParameterSpec(GCM_TAG_LENGTH_BITS, iv)
+
+            // 4. 初始化 Cipher 进行加密
+            val cipher = Cipher.getInstance(TRANSFORMATION)
+            cipher.init(Cipher.ENCRYPT_MODE, secretKey, gcmSpec)
+
+            // 5. 执行加密
+            val plaintextBytes = plaintext.toByteArray(StandardCharsets.UTF_8)
+            val encryptedBytes = cipher.doFinal(plaintextBytes)
+
+            // 6. 组装：IV + Ciphertext + Tag
+            // GCM 模式会将认证标签附加到密文末尾
+            val ciphertext = encryptedBytes.copyOfRange(0, encryptedBytes.size - TAG_LENGTH)
+            val tag = encryptedBytes.copyOfRange(encryptedBytes.size - TAG_LENGTH, encryptedBytes.size)
+
+            val result = iv + ciphertext + tag
+
+            // 7. Base64 编码返回
+            Base64.getEncoder().encodeToString(result)
+        } catch (e: Exception) {
+            logger.error(e) { "AES-GCM 加密失败" }
+            throw RuntimeException("加密失败: ${e.message}", e)
+        }
+    }
+}
+
--- a/docs/工具箱端-授权对接指南/utils/DateUtil.kt
+++ b/docs/工具箱端-授权对接指南/utils/DateUtil.kt
@@ -0,0 +1,42 @@
+package top.tangyh.lamp.filing.utils
+
+import java.text.SimpleDateFormat
+import java.util.*
+
+class DateUtil {
+
+    companion object {
+        // 获取当前时间戳
+        fun getCurrentTimestamp(): Long {
+            return System.currentTimeMillis()
+        }
+
+        // 格式化日期
+        fun formatDate(date: Date, format: String = "yyyy-MM-dd HH:mm:ss"): String {
+            val sdf = SimpleDateFormat(format)
+            return sdf.format(date)
+        }
+
+        // 解析日期字符串
+        fun parseDate(dateString: String, format: String = "yyyy-MM-dd HH:mm:ss"): Date? {
+            val sdf = SimpleDateFormat(format)
+            return try {
+                sdf.parse(dateString)
+            } catch (e: Exception) {
+                null
+            }
+        }
+
+        // 计算两个日期之间的天数差
+        fun getDaysBetweenDates(date1: Date, date2: Date): Long {
+            val diff = Math.abs(date1.time - date2.time)
+            return diff / (24 * 60 * 60 * 1000)
+        }
+
+        // 获取当前时间并格式化为 yyyy-MM-dd_HH-mm-ss
+        fun getCurrentFormattedTime(format: String = "yyyy-MM-dd_HH-mm-ss"): String {
+            val sdf = SimpleDateFormat(format)
+            return sdf.format(Date())
+        }
+    }
+}
--- a/docs/工具箱端-授权对接指南/utils/DeviceSignatureUtil.kt
+++ b/docs/工具箱端-授权对接指南/utils/DeviceSignatureUtil.kt
@@ -0,0 +1,129 @@
+package top.tangyh.lamp.filing.utils
+
+import io.github.oshai.kotlinlogging.KotlinLogging
+import java.nio.charset.StandardCharsets
+import java.security.MessageDigest
+import java.util.*
+import javax.crypto.Mac
+import javax.crypto.spec.SecretKeySpec
+
+private val logger = KotlinLogging.logger {}
+
+/**
+ * 设备签名工具类
+ * 用于生成和验证设备报告签名
+ * 
+ * 签名算法：HMAC-SHA256
+ * 签名数据（严格顺序）：
+ *   sign_payload = taskId + inspectionId + 
+ *                  SHA256(assets.json) + 
+ *                  SHA256(vulnerabilities.json) + 
+ *                  SHA256(weakPasswords.json) + 
+ *                  SHA256(漏洞评估报告.html)
+ * 
+ * 安全设计说明：
+ * - 使用 HMAC-SHA256 提供消息认证，防止伪造和篡改
+ * - 签名包含 taskId 和 inspectionId，确保签名与特定任务绑定
+ * - 包含多个报告文件的 SHA256，确保报告内容完整性
+ * - 只有拥有正确 licence + fingerprint 的设备才能生成有效签名
+ */
+object DeviceSignatureUtil {
+
+    private const val HMAC_ALGORITHM = "HmacSHA256"
+
+    /**
+     * 签名数据文件列表（严格顺序）
+     */
+    data class SignatureFileHashes(
+        val assetsJsonSha256: String,
+        val vulnerabilitiesJsonSha256: String,
+        val weakPasswordsJsonSha256: String,
+        val reportHtmlSha256: String
+    )
+
+    /**
+     * 生成设备签名
+     * 
+     * @param key 派生密钥（32字节）
+     * @param taskId 任务ID
+     * @param inspectionId 检查ID
+     * @param fileHashes 各个文件的 SHA256 哈希值（hex字符串）
+     * @return Base64 编码的签名
+     */
+    fun generateSignature(
+        key: ByteArray,
+        taskId: String,
+        inspectionId: Long,
+        fileHashes: SignatureFileHashes
+    ): String {
+        return try {
+            // 组装签名数据（严格顺序）：
+            // taskId + inspectionId + SHA256(assets.json) + SHA256(vulnerabilities.json) + 
+            // SHA256(weakPasswords.json) + SHA256(漏洞评估报告.html)
+            val signatureData = buildString {
+                append(taskId)
+                append(inspectionId)
+                append(fileHashes.assetsJsonSha256)
+                append(fileHashes.vulnerabilitiesJsonSha256)
+                append(fileHashes.weakPasswordsJsonSha256)
+                append(fileHashes.reportHtmlSha256)
+            }
+            val dataBytes = signatureData.toByteArray(StandardCharsets.UTF_8)
+
+            // 使用 HMAC-SHA256 计算签名
+            val mac = Mac.getInstance(HMAC_ALGORITHM)
+            val secretKey = SecretKeySpec(key, HMAC_ALGORITHM)
+            mac.init(secretKey)
+            val signatureBytes = mac.doFinal(dataBytes)
+
+            // Base64 编码返回
+            Base64.getEncoder().encodeToString(signatureBytes)
+        } catch (e: Exception) {
+            logger.error(e) { "生成设备签名失败: taskId=$taskId, inspectionId=$inspectionId" }
+            throw RuntimeException("生成设备签名失败: ${e.message}", e)
+        }
+    }
+
+    /**
+     * 验证设备签名
+     * 
+     * @param key 派生密钥（32字节）
+     * @param taskId 任务ID
+     * @param inspectionId 检查ID
+     * @param fileHashes 各个文件的 SHA256 哈希值（hex字符串）
+     * @param expectedSignature Base64 编码的期望签名
+     * @return true 如果签名匹配，false 否则
+     */
+    fun verifySignature(
+        key: ByteArray,
+        taskId: String,
+        inspectionId: Long,
+        fileHashes: SignatureFileHashes,
+        expectedSignature: String
+    ): Boolean {
+        return try {
+            val calculatedSignature = generateSignature(key, taskId, inspectionId, fileHashes)
+            // 使用时间安全的比较，防止时序攻击
+            MessageDigest.isEqual(
+                Base64.getDecoder().decode(expectedSignature),
+                Base64.getDecoder().decode(calculatedSignature)
+            )
+        } catch (e: Exception) {
+            logger.error(e) { "验证设备签名失败: taskId=$taskId, inspectionId=$inspectionId" }
+            false
+        }
+    }
+
+    /**
+     * 计算文件的 SHA256 哈希值（hex字符串）
+     * 
+     * @param fileContent 文件内容
+     * @return SHA256 哈希值的 hex 字符串
+     */
+    fun calculateSha256(fileContent: ByteArray): String {
+        val digest = MessageDigest.getInstance("SHA-256")
+        val hashBytes = digest.digest(fileContent)
+        return hashBytes.joinToString("") { "%02x".format(it) }
+    }
+}
+
--- a/docs/工具箱端-授权对接指南/utils/DistributedIdUtil.kt
+++ b/docs/工具箱端-授权对接指南/utils/DistributedIdUtil.kt
@@ -0,0 +1,12 @@
+package top.tangyh.lamp.filing.utils
+
+object DistributedIdUtil {
+    fun generateId(platformId: Long, localId: Long): Long {
+        require(platformId in 0..0xFFFF) { "platformId must be 0-65535" }
+        val safeLocalId = localId and 0xFFFFFFFFFFFF
+        return (platformId shl 48) or safeLocalId
+    }
+
+    fun parsePlatform(id: Long): Long = id ushr 48
+    fun parseLocal(id: Long): Long = id and 0xFFFFFFFFFFFF
+}
--- a/docs/工具箱端-授权对接指南/utils/HashUtil.kt
+++ b/docs/工具箱端-授权对接指南/utils/HashUtil.kt
@@ -0,0 +1,18 @@
+package top.tangyh.lamp.filing.utils
+
+import java.io.InputStream
+import java.security.MessageDigest
+
+object HashUtil {
+    fun calculateFileHash(inputStream: InputStream): String {
+        val digest = MessageDigest.getInstance("SHA-256")
+        val buffer = ByteArray(8192)
+        var bytesRead: Int
+
+        while (inputStream.read(buffer).also { bytesRead = it } != -1) {
+            digest.update(buffer, 0, bytesRead)
+        }
+
+        return digest.digest().joinToString("") { "%02x".format(it) }
+    }
+}
--- a/docs/工具箱端-授权对接指南/utils/HkdfUtil.kt
+++ b/docs/工具箱端-授权对接指南/utils/HkdfUtil.kt
@@ -0,0 +1,66 @@
+package top.tangyh.lamp.filing.utils
+
+import io.github.oshai.kotlinlogging.KotlinLogging
+import org.bouncycastle.crypto.digests.SHA256Digest
+import org.bouncycastle.crypto.generators.HKDFBytesGenerator
+import org.bouncycastle.crypto.params.HKDFParameters
+import java.nio.charset.StandardCharsets
+
+private val logger = KotlinLogging.logger {}
+
+/**
+ * HKDF (HMAC-based Key Derivation Function) 工具类
+ * 用于从 licence + fingerprint 派生设备签名密钥
+ * 
+ * 安全设计说明：
+ * - 使用 HKDF 而非直接哈希，提供更好的密钥分离和扩展性
+ * - Salt 固定为 "AUTH_V3_SALT"，确保同一输入产生相同密钥
+ * - Info 参数用于区分不同用途的密钥派生（device_report_signature）
+ * - 输出长度 32 字节（256位），适用于 HMAC-SHA256
+ */
+object HkdfUtil {
+
+    private const val SALT = "AUTH_V3_SALT"
+    private const val INFO = "device_report_signature"
+    private const val KEY_LENGTH = 32 // 32 bytes = 256 bits
+
+    /**
+     * 使用 HKDF 派生密钥（使用默认 salt 和 info）
+     * 
+     * @param input 输入密钥材料（licence + fingerprint）
+     * @return 派生出的密钥（32字节）
+     */
+    fun deriveKey(input: String): ByteArray {
+        return deriveKey(input, SALT, INFO)
+    }
+
+    /**
+     * 使用 HKDF 派生密钥（支持自定义 salt 和 info）
+     * 
+     * @param input 输入密钥材料（licence + fingerprint）
+     * @param salt Salt 值（用于密钥派生）
+     * @param info Info 值（用于区分不同用途的密钥）
+     * @param keyLength 输出密钥长度（默认32字节）
+     * @return 派生出的密钥
+     */
+    fun deriveKey(input: String, salt: String, info: String, keyLength: Int = KEY_LENGTH): ByteArray {
+        return try {
+            val inputBytes = input.toByteArray(StandardCharsets.UTF_8)
+            val saltBytes = salt.toByteArray(StandardCharsets.UTF_8)
+            val infoBytes = info.toByteArray(StandardCharsets.UTF_8)
+
+            val hkdf = HKDFBytesGenerator(SHA256Digest())
+            val params = HKDFParameters(inputBytes, saltBytes, infoBytes)
+            hkdf.init(params)
+
+            val derivedKey = ByteArray(keyLength)
+            hkdf.generateBytes(derivedKey, 0, keyLength)
+
+            derivedKey
+        } catch (e: Exception) {
+            logger.error(e) { "HKDF 密钥派生失败: input=$input, salt=$salt, info=$info" }
+            throw RuntimeException("HKDF 密钥派生失败: ${e.message}", e)
+        }
+    }
+}
+
--- a/docs/工具箱端-授权对接指南/utils/JwtUtil.kt
+++ b/docs/工具箱端-授权对接指南/utils/JwtUtil.kt
@@ -0,0 +1,50 @@
+package top.tangyh.lamp.filing.utils
+
+import io.jsonwebtoken.Jwts
+import io.jsonwebtoken.SignatureAlgorithm
+import io.jsonwebtoken.security.Keys
+import org.springframework.beans.factory.annotation.Value
+import org.springframework.stereotype.Component
+import java.time.LocalDateTime
+import java.time.ZoneId
+import java.util.*
+import javax.crypto.SecretKey
+
+@Component
+class JwtUtil(
+    @Value("\${jwt.secret}")
+    private val secretKey: String
+) {
+
+
+    // 生成签名 Key（HS256）
+    private val signingKey: SecretKey = Keys.hmacShaKeyFor(Base64.getDecoder().decode(secretKey))
+
+    /**
+     * 生成 Token
+     * */
+    fun generateToken(subject: String, claims: Map<String, Any> = emptyMap(), expireDays: Long = 7): String {
+        val now = LocalDateTime.now()
+        val expiration = now.plusDays(expireDays)
+
+        return Jwts.builder()
+            .setSubject(subject)
+            .setClaims(claims)
+            .setIssuedAt(Date.from(now.atZone(ZoneId.systemDefault()).toInstant()))
+            .setExpiration(Date.from(expiration.atZone(ZoneId.systemDefault()).toInstant()))
+            .signWith(signingKey, SignatureAlgorithm.HS256)
+            .compact()
+    }
+
+
+    /**
+     * 解析 Token 获取 Claims
+     */
+    fun parseToken(token: String): Map<String, Any> {
+        return Jwts.parserBuilder()
+            .setSigningKey(signingKey)
+            .build()
+            .parseClaimsJws(token)
+            .body
+    }
+}
--- a/docs/工具箱端-授权对接指南/utils/RegionUtil.kt
+++ b/docs/工具箱端-授权对接指南/utils/RegionUtil.kt
@@ -0,0 +1,22 @@
+package top.tangyh.lamp.filing.utils
+
+import kotlin.text.substring
+
+object RegionUtil {
+    fun getLevel(code: String?): String {
+        if (code == null || code.length != 6) {
+            return "无效编码"
+        }
+
+        val province = code.substring(0, 2)
+        val city = code.substring(2, 4)
+        val county = code.substring(4, 6)
+
+        return when {
+            city == "00" && county == "00" -> "province"
+            city != "00" && county == "00" -> "city"
+            county != "00" -> "county"
+            else -> "未知级别"
+        }
+    }
+}
--- a/docs/工具箱端-授权对接指南/utils/RsaOaepDecryptionUtil.kt
+++ b/docs/工具箱端-授权对接指南/utils/RsaOaepDecryptionUtil.kt
@@ -0,0 +1,115 @@
+package top.tangyh.lamp.filing.utils
+
+import io.github.oshai.kotlinlogging.KotlinLogging
+import org.springframework.beans.factory.annotation.Value
+import org.springframework.stereotype.Component
+import java.nio.charset.StandardCharsets
+import java.security.KeyFactory
+import java.security.PublicKey
+import java.security.spec.PKCS8EncodedKeySpec
+import java.security.spec.X509EncodedKeySpec
+import java.util.*
+import javax.crypto.Cipher
+
+private val logger = KotlinLogging.logger {}
+
+/**
+ * RSA-OAEP 解密工具类
+ * 用于设备身份首次绑定时解密设备信息
+ * 
+ * 使用场景：设备使用平台的公钥加密数据，平台使用私钥解密
+ */
+@Component
+class RsaOaepDecryptionUtil(
+    @Value("\${device.encrypt.privateKey:}")
+    private val privateKeyBase64: String
+) {
+
+    private val keyFactory = KeyFactory.getInstance("RSA")
+    private val cipherAlgorithm = "RSA/ECB/OAEPWithSHA-256AndMGF1Padding"
+    
+    // 缓存私钥，避免每次解密都重新加载
+    private val privateKey by lazy {
+        if (privateKeyBase64.isBlank()) {
+            throw IllegalStateException("RSA私钥未配置，无法解密设备信息")
+        }
+        val privateKeyBytes = Base64.getDecoder().decode(privateKeyBase64)
+        val keySpec = PKCS8EncodedKeySpec(privateKeyBytes)
+        keyFactory.generatePrivate(keySpec)
+    }
+
+    init {
+        if (privateKeyBase64.isBlank()) {
+            logger.warn { "RSA私钥未配置，设备授权解密功能可能无法使用" }
+        }
+    }
+
+    /**
+     * 使用RSA-OAEP解密设备信息
+     * @param encryptedData Base64编码的加密数据
+     * @return 解密后的JSON字符串
+     */
+    fun decrypt(encryptedData: String): String {
+        if (privateKeyBase64.isBlank()) {
+            throw IllegalStateException("RSA私钥未配置，无法解密设备信息")
+        }
+
+        return try {
+            // 创建新的Cipher实例（Cipher不是线程安全的）
+            val cipher = Cipher.getInstance(cipherAlgorithm)
+            
+            // 初始化解密器
+            cipher.init(Cipher.DECRYPT_MODE, privateKey)
+
+            // Base64解码加密数据
+            val encryptedBytes = Base64.getDecoder().decode(encryptedData)
+
+            // 解密数据
+            val decryptedBytes = cipher.doFinal(encryptedBytes)
+
+            // 返回解密后的字符串
+            String(decryptedBytes, StandardCharsets.UTF_8)
+        } catch (e: Exception) {
+            logger.error(e) { "RSA-OAEP解密设备信息失败" }
+            throw RuntimeException("RSA-OAEP解密设备信息失败: ${e.message}", e)
+        }
+    }
+
+
+    /**
+     * 使用平台公钥加密数据
+     *
+     * @param plainText 原始JSON字符串（设备信息）
+     * @param publicKeyBase64 平台公钥（Base64）
+     * @return Base64编码的密文
+     */
+    fun  encrypt1(
+        plainText: String,
+        publicKeyBase64: String
+    ): String {
+        try {
+            val publicKey = loadPublicKey(publicKeyBase64)
+
+            val cipher = Cipher.getInstance(cipherAlgorithm)
+            cipher.init(Cipher.ENCRYPT_MODE, publicKey)
+
+            val encryptedBytes = cipher.doFinal(
+                plainText.toByteArray(StandardCharsets.UTF_8)
+            )
+
+            return Base64.getEncoder().encodeToString(encryptedBytes)
+        } catch (e: Exception) {
+            logger.error(e) { "RSA-OAEP 加密失败" }
+            throw RuntimeException("RSA-OAEP 加密失败: ${e.message}", e)
+        }
+    }
+
+    private fun loadPublicKey(base64Key: String): PublicKey {
+        val keyBytes = Base64.getDecoder().decode(base64Key)
+        val keySpec = X509EncodedKeySpec(keyBytes)
+        return keyFactory.generatePublic(keySpec)
+    }
+
+}
+
+
--- a/docs/工具箱端-授权对接指南/utils/RsaOaepDecryptionUtilV2.kt
+++ b/docs/工具箱端-授权对接指南/utils/RsaOaepDecryptionUtilV2.kt
@@ -0,0 +1,103 @@
+package top.tangyh.lamp.filing.utils
+
+import java.nio.charset.StandardCharsets
+import java.security.KeyFactory
+import java.security.KeyPairGenerator
+import java.security.PublicKey
+import java.security.spec.PKCS8EncodedKeySpec
+import java.security.spec.X509EncodedKeySpec
+import java.util.*
+import javax.crypto.Cipher
+
+
+object RsaOaepCryptoUtil {
+
+    private const val cipherAlgorithm =
+        "RSA/ECB/OAEPWithSHA-256AndMGF1Padding"
+
+    private val keyFactory = KeyFactory.getInstance("RSA")
+
+    fun encrypt(
+        plainText: String,
+        publicKeyBase64: String
+    ): String {
+        val publicKey = loadPublicKey(publicKeyBase64)
+
+        val cipher = Cipher.getInstance(cipherAlgorithm)
+        cipher.init(Cipher.ENCRYPT_MODE, publicKey)
+
+        val encryptedBytes = cipher.doFinal(
+            plainText.toByteArray(StandardCharsets.UTF_8)
+        )
+        return Base64.getEncoder().encodeToString(encryptedBytes)
+    }
+
+    fun decrypt(
+        encryptedData: String,
+        privateKeyBase64: String
+    ): String {
+        val privateKeyBytes = Base64.getDecoder().decode(privateKeyBase64)
+        val keySpec = PKCS8EncodedKeySpec(privateKeyBytes)
+        val privateKey = keyFactory.generatePrivate(keySpec)
+
+        val cipher = Cipher.getInstance(cipherAlgorithm)
+        cipher.init(Cipher.DECRYPT_MODE, privateKey)
+
+        val decryptedBytes = cipher.doFinal(
+            Base64.getDecoder().decode(encryptedData)
+        )
+        return String(decryptedBytes, StandardCharsets.UTF_8)
+    }
+
+    private fun loadPublicKey(base64Key: String): PublicKey {
+        val keyBytes = Base64.getDecoder().decode(base64Key)
+        val keySpec = X509EncodedKeySpec(keyBytes)
+        return keyFactory.generatePublic(keySpec)
+    }
+}
+
+
+object Test {
+    @JvmStatic
+    fun main(args: Array<String>) {
+        val keyPairGenerator = KeyPairGenerator.getInstance("RSA")
+        keyPairGenerator.initialize(2048)
+        val keyPair = keyPairGenerator.generateKeyPair()
+
+//        val publicKey = Base64.getEncoder().encodeToString(keyPair.public.encoded)
+//        val privateKey = Base64.getEncoder().encodeToString(keyPair.private.encoded)
+
+        val publicKey = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzDlZvMDVaL+fjl05Hi182JOAUAaN4gh9rOF+1NhKfO4J6e0HLy8lBuylp3A4xoTiyUejNm22h0dqAgDSPnY/xZR76POFTD1soHr2LaFCN8JAbQ96P8gE7wC9qpoTssVvIVRH7QbVd260J6eD0Szwcx9cg591RSN69pMpe5IVRi8T99Hhql6/wnZHORPr18eESLOY93jRskLzc0q18r68RRoTJiQf+9YC8ub5iKp7rCjVnPi1UbIYmXmL08tk5mksYA0NqWQAa1ofKxx/9tQtB9uTjhTxuTu94XU9jlGU87qaHZs+kpqa8CAbYYJFbSP1xHwoZzpU2jpw2aF22HBYxwIDAQAB"
+        val privateKey = "MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDMOVm8wNVov5+OXTkeLXzYk4BQBo3iCH2s4X7U2Ep87gnp7QcvLyUG7KWncDjGhOLJR6M2bbaHR2oCANI+dj/FlHvo84VMPWygevYtoUI3wkBtD3o/yATvAL2qmhOyxW8hVEftBtV3brQnp4PRLPBzH1yDn3VFI3r2kyl7khVGLxP30eGqXr/Cdkc5E+vXx4RIs5j3eNGyQvNzSrXyvrxFGhMmJB/71gLy5vmIqnusKNWc+LVRshiZeYvTy2TmaSxgDQ2pZABrWh8rHH/21C0H25OOFPG5O73hdT2OUZTzupodmz6SmprwIBthgkVtI/XEfChnOlTaOnDZoXbYcFjHAgMBAAECggEBAKUDagjj3wwmWWwU00QZCRmOBU2kHhyXM8Tu5yZgJb/QLt5/ESEE/OwdZrRmLtnpIb31TmF6QNQJ1hQMSdUCgwDIu1489mXl89GvyR6RgAnBwYDd0q+alLHxbU9d87CtauAJU5ynuvAn2RV5ez8XCqpamswXmg/lXUPDIO+h1+K+UJPwYFhzHL3WpZQXHofcSUCRn0JONbz7c9OwVFYe0v1g18wwAvIAsEEimcnXFZaIJ/md2md0Jk4+LOFUsbgCM5skNTooXarDiHGCRFMJXxvYpavC6hhhcWfh3K2ydHMhFdF70ZOs169ShDtYq4i/hkaZ+p7kFVo8Z6oxVUpC8IECgYEA+OQxfc2iGMD9uus/r1yjUx0kdhYKik202tE53C4ikAn490+Lb8qcY/kykFj721MHBc73ijq/ZNU21JxyMx4T1jbdvl+5Kv9EUFAQmsJuTSudC1Dud3MlUgYEtVUhau2WOexUIRyCda6V4NUYkJG4vLRyMloPprF3xThmJRgG9qcCgYEA0g6QrU1e/DjADSpymRfqoOX4ASp7G++CRHTB2NZvA6ZxnWoEX59TO3mW4z4fgJkIwevkPUA9nfO2bRQWph+aom5qAczsPmZ2OpR9cjel63AIV1AboUV2Gr/H4IfHs7qGX7JWmW1SnZyvvGuI5MdBHEcysJO+L5V1OVyFRzvj8OECgYAO21A4+jVa1OpQZgp/JUB6jZrHkbk/WDQbe7HAeuCFSJMb8BuaqLV9IjrqcuVVyjb5Gcmc7rTOCAwl1NDcTEdS2iOSYZRkBKjHQoA7PK/o21mce1BAwRbRNprBWDuObnAxNPIwp8sBy1IXAaFdv9UPLpZCey3D/YPwudUfEbgYsQKBgQCZax3sFYh8ew56Dzin7Dnnzk72uwozexkP2p8COovWhKiSqi4LkRh/Zez4iBUGHb+xsxJ+Uf8u8CObQ4LPTmHopPAz5HHfmYJcgrukwlQiwy60ZsPnZA5AtzXLHiCTenZOSrjJUnl2uEv6OChBv+4kMzQol5/erTBy9so5Htr6wQKBgQC3apeFD/x+0FjABleVITzGyAWj/Kxl/OOiL4dQAYW49wVD/j0ujG3CvbK0GHZFwy/Ju+pWlHISbiZiKYko/4GBtp+JwxG9fFmbHdl4BZSTwfQMYdNq8hN+0hBfWwcceIhbEZcFLIvG/ZhkcT3yh874XRn1A5V/AR8W9YFH1EWYwQ=="
+
+//        val plainText = "{\n" +
+//                "    \"taskId\": 723047797139586052,\n" +
+//                "    \"licence\": \"LIC-8F2A-XXXX\",\n" +
+//                "    \"fingerprint\": \"FP-2c91e9f3\",\n" +
+//                "    \"enterpriseId\": \"1173040813421105152\",\n" +
+//                "    \"inspectionId\": \"702286470691215417\",\n" +
+//                "    \"summary\": \"1\"\n" +
+//                "}"
+
+        val plainText = "{\n" +
+                "    \"licence\": \"lic-1234567890\",\n" +
+                "    \"fingerprint\": \"e19c60d21c544c1118e3b633eae1bb935e2762ebddbc671b60b8b61c65c05d1c\"\n" +
+                "}"
+
+        val encryptedText =
+            RsaOaepCryptoUtil.encrypt(plainText, publicKey)
+
+        val decryptedText =
+            RsaOaepCryptoUtil.decrypt(encryptedText, privateKey)
+
+        println("Plain Text: $plainText")
+
+        println("Public Key: $publicKey")
+        println("Private Key: $privateKey")
+
+
+        println("Encrypted: $encryptedText")
+        println("Decrypted: $decryptedText")
+    }
+}
+
--- a/docs/工具箱端-授权对接指南/utils/TaskEncryptionUtil.kt
+++ b/docs/工具箱端-授权对接指南/utils/TaskEncryptionUtil.kt
@@ -0,0 +1,120 @@
+package top.tangyh.lamp.filing.utils
+
+import io.github.oshai.kotlinlogging.KotlinLogging
+import java.nio.charset.StandardCharsets
+import java.security.MessageDigest
+import java.security.SecureRandom
+import java.util.*
+import javax.crypto.Cipher
+import javax.crypto.spec.GCMParameterSpec
+import javax.crypto.spec.SecretKeySpec
+
+private val logger = KotlinLogging.logger {}
+
+/**
+ * 任务加密工具类
+ * 使用 licence + fingerprint 作为密钥对任务数据进行 AES-256-GCM 对称加密
+ * 
+ * GCM 模式提供认证加密，比 ECB 模式更安全
+ * 加密数据格式：IV(12字节) + 加密数据 + 认证标签(16字节)
+ */
+object TaskEncryptionUtil {
+
+    private const val ALGORITHM = "AES"
+    private const val TRANSFORMATION = "AES/GCM/NoPadding"
+    private const val GCM_IV_LENGTH = 12 // GCM 推荐使用 12 字节 IV
+    private const val GCM_TAG_LENGTH = 16 // GCM 认证标签长度（128位）
+    private const val KEY_LENGTH = 32 // AES-256 密钥长度（256位 = 32字节）
+
+    private val secureRandom = SecureRandom()
+
+    /**
+     * 使用 licence + fingerprint 加密任务数据（AES-256-GCM）
+     * @param data 待加密的数据（JSON字符串）
+     * @param licence 授权码
+     * @param fingerprint 硬件指纹
+     * @return Base64编码的加密数据（包含IV + 加密数据 + 认证标签）
+     */
+    fun encrypt(data: String, licence: String, fingerprint: String): String {
+        return try {
+            // 使用 licence + fingerprint 生成密钥
+            val key = generateKey(licence, fingerprint)
+            
+            // 生成随机 IV（12字节）
+            val iv = ByteArray(GCM_IV_LENGTH)
+            secureRandom.nextBytes(iv)
+            
+            // 创建加密器
+            val cipher = Cipher.getInstance(TRANSFORMATION)
+            val parameterSpec = GCMParameterSpec(GCM_TAG_LENGTH * 8, iv) // 标签长度以位为单位
+            cipher.init(Cipher.ENCRYPT_MODE, key, parameterSpec)
+            
+            // 加密数据
+            val encryptedBytes = cipher.doFinal(data.toByteArray(StandardCharsets.UTF_8))
+            
+            // 组合：IV + 加密数据（包含认证标签）
+            val combined = ByteArray(iv.size + encryptedBytes.size)
+            System.arraycopy(iv, 0, combined, 0, iv.size)
+            System.arraycopy(encryptedBytes, 0, combined, iv.size, encryptedBytes.size)
+            
+            // 返回 Base64 编码的加密数据
+            Base64.getEncoder().encodeToString(combined)
+        } catch (e: Exception) {
+            logger.error(e) { "AES-256-GCM加密任务数据失败" }
+            throw RuntimeException("加密任务数据失败: ${e.message}", e)
+        }
+    }
+
+    /**
+     * 使用 licence + fingerprint 解密任务数据（AES-256-GCM）
+     * @param encryptedData Base64编码的加密数据（包含IV + 加密数据 + 认证标签）
+     * @param licence 授权码
+     * @param fingerprint 硬件指纹
+     * @return 解密后的数据（JSON字符串）
+     */
+    fun decrypt(encryptedData: String, licence: String, fingerprint: String): String {
+        return try {
+            // 使用 licence + fingerprint 生成密钥
+            val key = generateKey(licence, fingerprint)
+            
+            // Base64 解码
+            val combined = Base64.getDecoder().decode(encryptedData)
+            
+            // 分离 IV 和加密数据
+            if (combined.size < GCM_IV_LENGTH) {
+                throw IllegalArgumentException("加密数据格式错误：数据长度不足")
+            }
+            
+            val iv = combined.sliceArray(0 until GCM_IV_LENGTH)
+            val cipherText = combined.sliceArray(GCM_IV_LENGTH until combined.size)
+            
+            // 创建解密器
+            val cipher = Cipher.getInstance(TRANSFORMATION)
+            val parameterSpec = GCMParameterSpec(GCM_TAG_LENGTH * 8, iv)
+            cipher.init(Cipher.DECRYPT_MODE, key, parameterSpec)
+            
+            // 解密数据（GCM 会自动验证认证标签）
+            val decryptedBytes = cipher.doFinal(cipherText)
+            
+            // 返回解密后的字符串
+            String(decryptedBytes, StandardCharsets.UTF_8)
+        } catch (e: Exception) {
+            logger.error(e) { "AES-256-GCM解密任务数据失败" }
+            throw RuntimeException("解密任务数据失败: ${e.message}", e)
+        }
+    }
+
+    /**
+     * 使用 licence + fingerprint 生成 AES-256 密钥（256位 = 32字节）
+     * 使用 SHA-256 哈希的全部32字节作为密钥
+     */
+    private fun generateKey(licence: String, fingerprint: String): SecretKeySpec {
+        val combined = "$licence$fingerprint"
+        val digest = MessageDigest.getInstance("SHA-256")
+        val hash = digest.digest(combined.toByteArray(StandardCharsets.UTF_8))
+        
+        // 使用全部32字节作为 AES-256 密钥
+        return SecretKeySpec(hash, ALGORITHM)
+    }
+}
+
--- a/docs/工具箱端-授权对接指南/utils/ZipVerifierUtil.kt
+++ b/docs/工具箱端-授权对接指南/utils/ZipVerifierUtil.kt
@@ -0,0 +1,134 @@
+package top.tangyh.lamp.filing.utils
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import io.github.oshai.kotlinlogging.KotlinLogging
+import org.bouncycastle.openpgp.*
+import org.bouncycastle.openpgp.operator.jcajce.JcaKeyFingerprintCalculator
+import org.bouncycastle.openpgp.operator.jcajce.JcaPGPContentVerifierBuilderProvider
+import java.io.ByteArrayInputStream
+import java.io.InputStream
+import java.security.MessageDigest
+import java.security.Security
+import java.util.zip.ZipFile
+
+object ZipVerifierUtil {
+
+    private val logger = KotlinLogging.logger {}
+
+//    @JvmStatic
+//    fun main(args: Array<String>) {
+//        verifyZip("signed.zip", "public.key")
+//    }
+
+    /**
+     * 验证 ZIP 文件
+     */
+    @Throws(Exception::class)
+    fun verifyZip(zipPath: String, pubkeyContent: String):Boolean {
+
+            println(Security.getProviders().joinToString { it.name })
+            val publicKey = readPublicKey(
+                ByteArrayInputStream(pubkeyContent.toByteArray())
+            )
+
+            val zip = ZipFile(zipPath)
+
+            // 1. 读取 manifest.json
+            val manifestEntry = zip.getEntry("META-INF/manifest.json")
+                ?: throw RuntimeException("manifest.json is missing!")
+            val manifestJson = zip.getInputStream(manifestEntry).readAllBytes().toString(Charsets.UTF_8)
+
+            // 2. 读取 signature.asc
+            val sigEntry = zip.getEntry("META-INF/signature.asc")
+                ?: throw RuntimeException("signature.asc is missing!")
+            val signature = zip.getInputStream(sigEntry).readAllBytes()
+
+            // 3. 使用 OpenPGP 验证签名
+            val ok = verifyDetachedSignature(publicKey, manifestJson.toByteArray(), signature)
+            if (!ok) throw RuntimeException("PGP signature invalid!")
+
+            // 4. 校验 manifest 里每个文件的 SHA-256
+            val mapper = ObjectMapper()
+            val manifest = mapper.readValue(manifestJson, Map::class.java)
+            val files = manifest["files"] as? Map<String, String>
+                ?: throw RuntimeException("Invalid manifest.json: missing 'files'")
+
+            for ((name, expectedHash) in files) {
+                val entry = zip.getEntry(name)
+                    ?: throw RuntimeException("文件不存在: $name")
+
+                val data = zip.getInputStream(entry).readAllBytes()
+                val hash = sha256Hex(data)
+
+                if (!hash.equals(expectedHash, ignoreCase = true)) {
+                    throw RuntimeException("Hash mismatch: $name")
+                }
+            }
+        return true
+    }
+
+    @Throws(Exception::class)
+    private fun sha256Hex(data: ByteArray): String {
+        val md = MessageDigest.getInstance("SHA-256")
+        return bytesToHex(md.digest(data))
+    }
+
+    private fun bytesToHex(bytes: ByteArray): String {
+        return bytes.joinToString("") { "%02x".format(it) }
+    }
+
+    @Throws(Exception::class)
+    private fun readPublicKey(keyIn: InputStream): PGPPublicKey {
+        val keyRings = PGPPublicKeyRingCollection(
+            PGPUtil.getDecoderStream(keyIn),
+            JcaKeyFingerprintCalculator()
+        )
+
+        for (keyRing in keyRings) {
+            for (key in keyRing) {
+                if (key.isEncryptionKey || key.isMasterKey) {
+                    return key
+                }
+            }
+        }
+
+        throw IllegalArgumentException("Can't find public key")
+    }
+
+    @Throws(Exception::class)
+    private fun verifyDetachedSignature(
+        key: PGPPublicKey,
+        data: ByteArray,
+        sigBytes: ByteArray
+    ): Boolean {
+
+        val decoder = PGPUtil.getDecoderStream(ByteArrayInputStream(sigBytes))
+        val factory = PGPObjectFactory(decoder, JcaKeyFingerprintCalculator())
+
+        val message = factory.nextObject()
+            ?: throw IllegalArgumentException("Invalid signature file")
+
+        val sigList = when (message) {
+            is PGPSignatureList -> message
+            is PGPCompressedData -> {
+                val compressedFactory = PGPObjectFactory(
+                    message.dataStream,
+                    JcaKeyFingerprintCalculator()
+                )
+                val compressedObj = compressedFactory.nextObject()
+                compressedObj as? PGPSignatureList
+                    ?: throw IllegalArgumentException("Invalid PGP signature (not signature list)")
+            }
+            else ->
+                throw IllegalArgumentException("Unsupported PGP signature format: ${message::class.java}")
+        }
+
+        val sig = sigList[0]
+
+        sig.init(JcaPGPContentVerifierBuilderProvider().setProvider("BC"), key)
+        sig.update(data)
+
+        return sig.verify()
+    }
+
+}
--- a/docs/工具箱端-授权对接指南/工具箱端-任务二维码解密指南.md
+++ b/docs/工具箱端-授权对接指南/工具箱端-任务二维码解密指南.md
@@ -0,0 +1,644 @@
+# 工具箱端 - 任务二维码解密指南
+
+## 概述
+
+本文档说明工具箱端如何解密任务二维码数据。App 创建任务后，平台会生成加密的任务数据并返回给 App，App 将其生成二维码。工具箱扫描二维码后，需要使用自己的 `licence` 和 `fingerprint` 解密任务数据。
+
+> ### UX 集成模式补充（当前项目实现）
+>
+> 在当前集成模式中，工具箱扫描二维码后将密文提交给 UX 的 `crypto.decryptTask`。
+> UX 从本地配置读取 licence/fingerprint 执行底层解密并返回明文字符串。
+
+## 一、业务流程
+
+```
+App创建任务 → 平台加密任务数据 → 返回加密数据 → App生成二维码
+                                                      ↓
+工具箱扫描二维码 → 提取加密数据 → AES-256-GCM解密 → 获取任务信息
+```
+
+## 二、任务数据结构
+
+### 2.1 任务数据 JSON 格式
+
+解密后的任务数据为 JSON 格式，包含以下字段：
+
+```json
+{
+  "taskId": "TASK-20260115-4875",
+  "enterpriseId": "1173040813421105152",
+  "orgName": "超艺科技有限公司",
+  "inspectionId": "702286470691215417",
+  "inspectionPerson": "警务通",
+  "issuedAt": 1734571234567
+}
+```
+
+### 2.2 字段说明
+
+| 字段名 | 类型 | 说明 | 示例 |
+|--------|------|------|------|
+| `taskId` | String | 任务唯一ID（格式：TASK-YYYYMMDD-XXXX） | `"TASK-20260115-4875"` |
+| `enterpriseId` | String | 企业ID | `"1173040813421105152"` |
+| `orgName` | String | 单位名称 | `"超艺科技有限公司"` |
+| `inspectionId` | String | 检查ID | `"702286470691215417"` |
+| `inspectionPerson` | String | 检查人 | `"警务通"` |
+| `issuedAt` | Number | 任务发布时间戳（毫秒） | `1734571234567` |
+
+## 三、加密算法说明
+
+### 3.1 加密方式
+
+- **算法**：AES-256-GCM（Galois/Counter Mode）
+- **密钥长度**：256 位（32 字节）
+- **IV 长度**：12 字节（96 位）
+- **认证标签长度**：16 字节（128 位）
+
+### 3.2 密钥生成
+
+密钥由工具箱的 `licence` 和 `fingerprint` 生成：
+
+```
+密钥 = SHA-256(licence + fingerprint)
+```
+
+**重要说明**：
+- `licence` 和 `fingerprint` 直接字符串拼接（无分隔符）
+- 使用 SHA-256 哈希算法的全部 32 字节作为 AES-256 密钥
+- 工具箱必须使用与平台绑定时相同的 `licence` 和 `fingerprint`
+
+### 3.3 加密数据格式
+
+加密后的数据格式（Base64 编码前）：
+
+```
+[IV(12字节)] + [加密数据] + [认证标签(16字节)]
+```
+
+**数据布局**：
+```
+------------------+------------------+------------------+
+|   IV (12字节)    |   加密数据       |   认证标签(16字节)|
+------------------+------------------+------------------+
+```
+
+## 四、解密步骤
+
+### 4.1 解密流程
+
+1. **扫描二维码**：获取 Base64 编码的加密数据
+2. **Base64 解码**：将 Base64 字符串解码为字节数组
+3. **分离数据**：从字节数组中分离 IV、加密数据和认证标签
+4. **生成密钥**：使用 `licence + fingerprint` 生成 AES-256 密钥
+5. **解密数据**：使用 AES-256-GCM 解密（自动验证认证标签）
+6. **解析 JSON**：将解密后的字符串解析为 JSON 对象
+
+### 4.2 Python 实现示例
+
+```python
+import base64
+import json
+import hashlib
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.backends import default_backend
+
+def decrypt_task_data(
+    encrypted_data_base64: str,
+    licence: str,
+    fingerprint: str
+) -> dict:
+    """
+    解密任务二维码数据
+    
+    Args:
+        encrypted_data_base64: Base64编码的加密数据
+        licence: 设备授权码
+        fingerprint: 设备硬件指纹
+    
+    Returns:
+        解密后的任务数据（字典）
+    """
+    # 1. Base64 解码
+    encrypted_bytes = base64.b64decode(encrypted_data_base64)
+    
+    # 2. 分离 IV 和加密数据（包含认证标签）
+    if len(encrypted_bytes) < 12:
+        raise ValueError("加密数据格式错误：数据长度不足")
+    
+    iv = encrypted_bytes[:12]  # IV: 前12字节
+    ciphertext_with_tag = encrypted_bytes[12:]  # 加密数据 + 认证标签
+    
+    # 3. 生成密钥：SHA-256(licence + fingerprint)
+    combined = licence + fingerprint
+    key = hashlib.sha256(combined.encode('utf-8')).digest()
+    
+    # 4. 使用 AES-256-GCM 解密
+    aesgcm = AESGCM(key)
+    decrypted_bytes = aesgcm.decrypt(iv, ciphertext_with_tag, None)
+    
+    # 5. 解析 JSON
+    decrypted_json = decrypted_bytes.decode('utf-8')
+    task_data = json.loads(decrypted_json)
+    
+    return task_data
+
+# 使用示例
+if __name__ == "__main__":
+    # 从二维码扫描获取的加密数据
+    encrypted_data = "Base64编码的加密数据..."
+    
+    # 工具箱的授权信息（必须与平台绑定时一致）
+    licence = "LIC-8F2A-XXXX"
+    fingerprint = "FP-2c91e9f3"
+    
+    # 解密任务数据
+    task_data = decrypt_task_data(encrypted_data, licence, fingerprint)
+    
+    print("任务ID:", task_data["taskId"])
+    print("企业ID:", task_data["enterpriseId"])
+    print("单位名称:", task_data["orgName"])
+    print("检查ID:", task_data["inspectionId"])
+    print("检查人:", task_data["inspectionPerson"])
+    print("发布时间:", task_data["issuedAt"])
+```
+
+### 4.3 Java/Kotlin 实现示例
+
+```kotlin
+import com.fasterxml.jackson.databind.ObjectMapper
+import java.nio.charset.StandardCharsets
+import java.security.MessageDigest
+import java.util.Base64
+import javax.crypto.Cipher
+import javax.crypto.spec.GCMParameterSpec
+import javax.crypto.spec.SecretKeySpec
+
+object TaskDecryptionUtil {
+    
+    private const val ALGORITHM = "AES"
+    private const val TRANSFORMATION = "AES/GCM/NoPadding"
+    private const val GCM_IV_LENGTH = 12 // GCM 推荐使用 12 字节 IV
+    private const val GCM_TAG_LENGTH = 16 // GCM 认证标签长度（128位）
+    private const val KEY_LENGTH = 32 // AES-256 密钥长度（256位 = 32字节）
+    
+    private val objectMapper = ObjectMapper()
+    
+    /**
+     * 解密任务二维码数据
+     * 
+     * @param encryptedDataBase64 Base64编码的加密数据
+     * @param licence 设备授权码
+     * @param fingerprint 设备硬件指纹
+     * @return 解密后的任务数据（Map）
+     */
+    fun decryptTaskData(
+        encryptedDataBase64: String,
+        licence: String,
+        fingerprint: String
+    ): Map<String, Any> {
+        // 1. Base64 解码
+        val encryptedBytes = Base64.getDecoder().decode(encryptedDataBase64)
+        
+        // 2. 分离 IV 和加密数据（包含认证标签）
+        if (encryptedBytes.size < GCM_IV_LENGTH) {
+            throw IllegalArgumentException("加密数据格式错误：数据长度不足")
+        }
+        
+        val iv = encryptedBytes.sliceArray(0 until GCM_IV_LENGTH)
+        val ciphertextWithTag = encryptedBytes.sliceArray(GCM_IV_LENGTH until encryptedBytes.size)
+        
+        // 3. 生成密钥：SHA-256(licence + fingerprint)
+        val combined = "$licence$fingerprint"
+        val digest = MessageDigest.getInstance("SHA-256")
+        val keyBytes = digest.digest(combined.toByteArray(StandardCharsets.UTF_8))
+        val key = SecretKeySpec(keyBytes, ALGORITHM)
+        
+        // 4. 使用 AES-256-GCM 解密
+        val cipher = Cipher.getInstance(TRANSFORMATION)
+        val parameterSpec = GCMParameterSpec(GCM_TAG_LENGTH * 8, iv) // 标签长度以位为单位
+        cipher.init(Cipher.DECRYPT_MODE, key, parameterSpec)
+        
+        // 解密数据（GCM 会自动验证认证标签）
+        val decryptedBytes = cipher.doFinal(ciphertextWithTag)
+        
+        // 5. 解析 JSON
+        val decryptedJson = String(decryptedBytes, StandardCharsets.UTF_8)
+        @Suppress("UNCHECKED_CAST")
+        return objectMapper.readValue(decryptedJson, Map::class.java) as Map<String, Any>
+    }
+}
+
+// 使用示例
+fun main() {
+    // 从二维码扫描获取的加密数据
+    val encryptedData = "Base64编码的加密数据..."
+    
+    // 工具箱的授权信息（必须与平台绑定时一致）
+    val licence = "LIC-8F2A-XXXX"
+    val fingerprint = "FP-2c91e9f3"
+    
+    // 解密任务数据
+    val taskData = TaskDecryptionUtil.decryptTaskData(encryptedData, licence, fingerprint)
+    
+    println("任务ID: ${taskData["taskId"]}")
+    println("企业ID: ${taskData["enterpriseId"]}")
+    println("单位名称: ${taskData["orgName"]}")
+    println("检查ID: ${taskData["inspectionId"]}")
+    println("检查人: ${taskData["inspectionPerson"]}")
+    println("发布时间: ${taskData["issuedAt"]}")
+}
+```
+
+### 4.4 C# 实现示例
+
+```csharp
+using System;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+
+public class TaskDecryptionUtil
+{
+    private const int GcmIvLength = 12; // GCM 推荐使用 12 字节 IV
+    private const int GcmTagLength = 16; // GCM 认证标签长度（128位）
+    
+    /// <summary>
+    /// 解密任务二维码数据
+    /// </summary>
+    public static Dictionary<string, object> DecryptTaskData(
+        string encryptedDataBase64,
+        string licence,
+        string fingerprint
+    )
+    {
+        // 1. Base64 解码
+        byte[] encryptedBytes = Convert.FromBase64String(encryptedDataBase64);
+        
+        // 2. 分离 IV 和加密数据（包含认证标签）
+        if (encryptedBytes.Length < GcmIvLength)
+        {
+            throw new ArgumentException("加密数据格式错误：数据长度不足");
+        }
+        
+        byte[] iv = new byte[GcmIvLength];
+        Array.Copy(encryptedBytes, 0, iv, 0, GcmIvLength);
+        
+        byte[] ciphertextWithTag = new byte[encryptedBytes.Length - GcmIvLength];
+        Array.Copy(encryptedBytes, GcmIvLength, ciphertextWithTag, 0, ciphertextWithTag.Length);
+        
+        // 3. 生成密钥：SHA-256(licence + fingerprint)
+        string combined = licence + fingerprint;
+        byte[] keyBytes = SHA256.Create().ComputeHash(Encoding.UTF8.GetBytes(combined));
+        
+        // 4. 使用 AES-256-GCM 解密
+        using (AesGcm aesGcm = new AesGcm(keyBytes))
+        {
+            byte[] decryptedBytes = new byte[ciphertextWithTag.Length - GcmTagLength];
+            byte[] tag = new byte[GcmTagLength];
+            Array.Copy(ciphertextWithTag, ciphertextWithTag.Length - GcmTagLength, tag, 0, GcmTagLength);
+            Array.Copy(ciphertextWithTag, 0, decryptedBytes, 0, decryptedBytes.Length);
+            
+            aesGcm.Decrypt(iv, decryptedBytes, tag, null, decryptedBytes);
+            
+            // 5. 解析 JSON
+            string decryptedJson = Encoding.UTF8.GetString(decryptedBytes);
+            return JsonSerializer.Deserialize<Dictionary<string, object>>(decryptedJson);
+        }
+    }
+}
+
+// 使用示例
+class Program
+{
+    static void Main()
+    {
+        // 从二维码扫描获取的加密数据
+        string encryptedData = "Base64编码的加密数据...";
+        
+        // 工具箱的授权信息（必须与平台绑定时一致）
+        string licence = "LIC-8F2A-XXXX";
+        string fingerprint = "FP-2c91e9f3";
+        
+        // 解密任务数据
+        var taskData = TaskDecryptionUtil.DecryptTaskData(encryptedData, licence, fingerprint);
+        
+        Console.WriteLine($"任务ID: {taskData["taskId"]}");
+        Console.WriteLine($"企业ID: {taskData["enterpriseId"]}");
+        Console.WriteLine($"单位名称: {taskData["orgName"]}");
+        Console.WriteLine($"检查ID: {taskData["inspectionId"]}");
+        Console.WriteLine($"检查人: {taskData["inspectionPerson"]}");
+        Console.WriteLine($"发布时间: {taskData["issuedAt"]}");
+    }
+}
+```
+
+## 五、完整流程示例
+
+### 5.1 Python 完整示例（包含二维码扫描）
+
+```python
+import base64
+import json
+import hashlib
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from pyzbar import pyzbar
+from PIL import Image
+
+class TaskQRCodeDecoder:
+    """任务二维码解码器"""
+    
+    def __init__(self, licence: str, fingerprint: str):
+        """
+        初始化解码器
+        
+        Args:
+            licence: 设备授权码
+            fingerprint: 设备硬件指纹
+        """
+        self.licence = licence
+        self.fingerprint = fingerprint
+        self._key = self._generate_key()
+    
+    def _generate_key(self) -> bytes:
+        """生成 AES-256 密钥"""
+        combined = self.licence + self.fingerprint
+        return hashlib.sha256(combined.encode('utf-8')).digest()
+    
+    def scan_qr_code(self, qr_image_path: str) -> dict:
+        """
+        扫描二维码并解密任务数据
+        
+        Args:
+            qr_image_path: 二维码图片路径
+        
+        Returns:
+            解密后的任务数据（字典）
+        """
+        # 1. 扫描二维码
+        image = Image.open(qr_image_path)
+        qr_codes = pyzbar.decode(image)
+        
+        if not qr_codes:
+            raise ValueError("未找到二维码")
+        
+        # 获取二维码内容（Base64编码的加密数据）
+        encrypted_data_base64 = qr_codes[0].data.decode('utf-8')
+        print(f"扫描到二维码内容: {encrypted_data_base64[:50]}...")
+        
+        # 2. 解密任务数据
+        return self.decrypt_task_data(encrypted_data_base64)
+    
+    def decrypt_task_data(self, encrypted_data_base64: str) -> dict:
+        """
+        解密任务数据
+        
+        Args:
+            encrypted_data_base64: Base64编码的加密数据
+        
+        Returns:
+            解密后的任务数据（字典）
+        """
+        # 1. Base64 解码
+        encrypted_bytes = base64.b64decode(encrypted_data_base64)
+        
+        # 2. 分离 IV 和加密数据（包含认证标签）
+        if len(encrypted_bytes) < 12:
+            raise ValueError("加密数据格式错误：数据长度不足")
+        
+        iv = encrypted_bytes[:12]  # IV: 前12字节
+        ciphertext_with_tag = encrypted_bytes[12:]  # 加密数据 + 认证标签
+        
+        # 3. 使用 AES-256-GCM 解密
+        aesgcm = AESGCM(self._key)
+        decrypted_bytes = aesgcm.decrypt(iv, ciphertext_with_tag, None)
+        
+        # 4. 解析 JSON
+        decrypted_json = decrypted_bytes.decode('utf-8')
+        task_data = json.loads(decrypted_json)
+        
+        return task_data
+
+# 使用示例
+if __name__ == "__main__":
+    # 工具箱的授权信息（必须与平台绑定时一致）
+    licence = "LIC-8F2A-XXXX"
+    fingerprint = "FP-2c91e9f3"
+    
+    # 创建解码器
+    decoder = TaskQRCodeDecoder(licence, fingerprint)
+    
+    # 扫描二维码并解密
+    try:
+        task_data = decoder.scan_qr_code("task_qr_code.png")
+        
+        print("\n=== 任务信息 ===")
+        print(f"任务ID: {task_data['taskId']}")
+        print(f"企业ID: {task_data['enterpriseId']}")
+        print(f"单位名称: {task_data['orgName']}")
+        print(f"检查ID: {task_data['inspectionId']}")
+        print(f"检查人: {task_data['inspectionPerson']}")
+        print(f"发布时间: {task_data['issuedAt']}")
+        
+        # 可以使用任务信息执行检查任务
+        # execute_inspection_task(task_data)
+        
+    except Exception as e:
+        print(f"解密失败: {e}")
+```
+
+### 5.2 Java/Kotlin 完整示例（包含二维码扫描）
+
+```kotlin
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.google.zxing.BinaryBitmap
+import com.google.zxing.MultiFormatReader
+import com.google.zxing.Result
+import com.google.zxing.client.j2se.BufferedImageLuminanceSource
+import com.google.zxing.common.HybridBinarizer
+import java.awt.image.BufferedImage
+import java.io.File
+import java.nio.charset.StandardCharsets
+import java.security.MessageDigest
+import java.util.Base64
+import javax.crypto.Cipher
+import javax.crypto.spec.GCMParameterSpec
+import javax.crypto.spec.SecretKeySpec
+import javax.imageio.ImageIO
+
+class TaskQRCodeDecoder(
+    private val licence: String,
+    private val fingerprint: String
+) {
+    
+    private val key: SecretKeySpec by lazy {
+        val combined = "$licence$fingerprint"
+        val digest = MessageDigest.getInstance("SHA-256")
+        val keyBytes = digest.digest(combined.toByteArray(StandardCharsets.UTF_8))
+        SecretKeySpec(keyBytes, "AES")
+    }
+    
+    private val objectMapper = ObjectMapper()
+    
+    /**
+     * 扫描二维码并解密任务数据
+     */
+    fun scanAndDecrypt(qrImagePath: String): Map<String, Any> {
+        // 1. 扫描二维码
+        val image: BufferedImage = ImageIO.read(File(qrImagePath))
+        val source = BufferedImageLuminanceSource(image)
+        val bitmap = BinaryBitmap(HybridBinarizer(source))
+        val reader = MultiFormatReader()
+        val result: Result = reader.decode(bitmap)
+        
+        // 获取二维码内容（Base64编码的加密数据）
+        val encryptedDataBase64 = result.text
+        println("扫描到二维码内容: ${encryptedDataBase64.take(50)}...")
+        
+        // 2. 解密任务数据
+        return decryptTaskData(encryptedDataBase64)
+    }
+    
+    /**
+     * 解密任务数据
+     */
+    fun decryptTaskData(encryptedDataBase64: String): Map<String, Any> {
+        // 1. Base64 解码
+        val encryptedBytes = Base64.getDecoder().decode(encryptedDataBase64)
+        
+        // 2. 分离 IV 和加密数据（包含认证标签）
+        if (encryptedBytes.size < 12) {
+            throw IllegalArgumentException("加密数据格式错误：数据长度不足")
+        }
+        
+        val iv = encryptedBytes.sliceArray(0 until 12)
+        val ciphertextWithTag = encryptedBytes.sliceArray(12 until encryptedBytes.size)
+        
+        // 3. 使用 AES-256-GCM 解密
+        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+        val parameterSpec = GCMParameterSpec(16 * 8, iv) // 标签长度以位为单位
+        cipher.init(Cipher.DECRYPT_MODE, key, parameterSpec)
+        
+        // 解密数据（GCM 会自动验证认证标签）
+        val decryptedBytes = cipher.doFinal(ciphertextWithTag)
+        
+        // 4. 解析 JSON
+        val decryptedJson = String(decryptedBytes, StandardCharsets.UTF_8)
+        @Suppress("UNCHECKED_CAST")
+        return objectMapper.readValue(decryptedJson, Map::class.java) as Map<String, Any>
+    }
+}
+
+// 使用示例
+fun main() {
+    // 工具箱的授权信息（必须与平台绑定时一致）
+    val licence = "LIC-8F2A-XXXX"
+    val fingerprint = "FP-2c91e9f3"
+    
+    // 创建解码器
+    val decoder = TaskQRCodeDecoder(licence, fingerprint)
+    
+    // 扫描二维码并解密
+    try {
+        val taskData = decoder.scanAndDecrypt("task_qr_code.png")
+        
+        println("\n=== 任务信息 ===")
+        println("任务ID: ${taskData["taskId"]}")
+        println("企业ID: ${taskData["enterpriseId"]}")
+        println("单位名称: ${taskData["orgName"]}")
+        println("检查ID: ${taskData["inspectionId"]}")
+        println("检查人: ${taskData["inspectionPerson"]}")
+        println("发布时间: ${taskData["issuedAt"]}")
+        
+        // 可以使用任务信息执行检查任务
+        // executeInspectionTask(taskData)
+        
+    } catch (e: Exception) {
+        println("解密失败: ${e.message}")
+    }
+}
+```
+
+## 六、常见错误和注意事项
+
+### 6.1 解密失败
+
+**可能原因**：
+1. **密钥不匹配**：`licence` 或 `fingerprint` 与平台绑定时不一致
+   - 确保使用与设备授权时相同的 `licence` 和 `fingerprint`
+   - 检查字符串拼接是否正确（无分隔符）
+   
+2. **数据格式错误**：Base64 编码或数据布局错误
+   - 确保 Base64 解码正确
+   - 确保 IV 长度正确（12 字节）
+   
+3. **认证标签验证失败**：数据被篡改或损坏
+   - GCM 模式会自动验证认证标签
+   - 如果验证失败，说明数据被篡改或密钥错误
+
+4. **算法不匹配**：必须使用 `AES/GCM/NoPadding`
+   - 确保使用正确的加密算法
+   - 确保认证标签长度为 128 位（16 字节）
+
+### 6.2 二维码扫描失败
+
+**可能原因**：
+1. **二维码图片质量差**：确保图片清晰，有足够的对比度
+2. **二维码内容过长**：如果加密数据过长，可能需要更高版本的二维码
+3. **扫描库不支持**：确保使用支持 Base64 字符串的二维码扫描库
+
+### 6.3 JSON 解析失败
+
+**可能原因**：
+1. **字符编码错误**：确保使用 UTF-8 编码
+2. **JSON 格式错误**：确保解密后的字符串是有效的 JSON
+3. **字段缺失**：确保所有必需字段都存在
+
+## 七、安全设计说明
+
+### 7.1 为什么使用 AES-256-GCM
+
+1. **认证加密（AEAD）**：GCM 模式提供加密和认证，防止数据被篡改
+2. **强安全性**：AES-256 提供 256 位密钥强度
+3. **自动验证**：GCM 模式会自动验证认证标签，任何篡改都会导致解密失败
+
+### 7.2 为什么第三方无法解密
+
+1. **密钥绑定**：只有拥有正确 `licence + fingerprint` 的工具箱才能生成正确的密钥
+2. **认证标签**：GCM 模式会验证认证标签，任何篡改都会导致解密失败
+3. **密钥唯一性**：每个设备的 `licence + fingerprint` 组合是唯一的
+
+### 7.3 密钥生成的安全性
+
+1. **SHA-256 哈希**：使用强哈希算法生成密钥
+2. **密钥长度**：使用全部 32 字节作为 AES-256 密钥
+3. **密钥隔离**：每个设备的密钥是独立的，互不影响
+
+## 八、测试建议
+
+1. **单元测试**：
+   - 测试密钥生成是否正确
+   - 测试解密功能是否正常
+   - 测试 JSON 解析是否正确
+
+2. **集成测试**：
+   - 使用真实平台生成的二维码进行测试
+   - 测试不同长度的任务数据
+   - 测试错误的密钥是否会导致解密失败
+
+3. **边界测试**：
+   - 测试超长的任务数据
+   - 测试特殊字符的处理
+   - 测试错误的 Base64 格式
+
+## 九、参考实现
+
+- **Python**：`cryptography` 库（AES-GCM 加密）、`pyzbar` 库（二维码扫描）
+- **Java/Kotlin**：JDK `javax.crypto`（AES-GCM 加密）、ZXing 库（二维码扫描）
+- **C#**：`System.Security.Cryptography`（AES-GCM 加密）、ZXing.Net 库（二维码扫描）
+
+## 十、联系支持
+
+如有问题，请联系平台技术支持团队获取：
+- 测试环境地址
+- 技术支持
+
--- a/docs/工具箱端-授权对接指南/工具箱端-报告加密与签名生成指南.md
+++ b/docs/工具箱端-授权对接指南/工具箱端-报告加密与签名生成指南.md
@@ -0,0 +1,647 @@
+# 工具箱端 - 报告加密与签名生成指南
+
+## 概述
+
+本文档说明工具箱端如何生成加密和签名的检查报告 ZIP 文件，以确保：
+1. **授权校验**：只有合法授权的工具箱才能生成有效的报告
+2. **防篡改校验**：确保报告内容在传输过程中未被篡改
+
+> ### UX 集成模式补充（当前项目实现）
+>
+> 在当前集成模式中，工具箱可将原始报告 ZIP 直接上传到 UX 的 `crypto.signAndPackReport`：
+>
+> 1. 工具箱先通过 `config.setLicence` 完成本地 licence 配置；
+> 2. 工具箱传入 `pgpPrivateKey`、`signingContext`、`summaryJson` 与 `rawZip`；
+> 3. UX 从本地配置读取 licence/fingerprint，执行签名与打包能力，生成 `summary.json`、`META-INF/manifest.json`、`META-INF/signature.asc`；
+> 4. UX 返回签名后的 ZIP（二进制文件响应），工具箱再用于离线介质回传平台。
+
+## 一、ZIP 文件结构要求
+
+工具箱生成的 ZIP 文件必须包含以下文件：
+
+```
+report.zip
+├── summary.json              # 摘要信息（必须包含授权和签名字段）
+├── assets.json               # 资产信息（用于签名校验）
+├── vulnerabilities.json      # 漏洞信息（用于签名校验）
+├── weakPasswords.json        # 弱密码信息（用于签名校验）
+├── 漏洞评估报告.html         # 漏洞评估报告（用于签名校验）
+└── META-INF/
+    ├── manifest.json         # 文件清单（用于 OpenPGP 签名）
+    └── signature.asc         # OpenPGP 签名文件（防篡改）
+```
+
+## 二、授权校验 - 设备签名（device_signature）
+
+### 2.1 目的
+
+设备签名用于验证报告是由合法授权的工具箱生成的，防止第三方伪造扫描结果。
+
+### 2.2 密钥派生
+
+使用 **HKDF-SHA256** 从设备的 `licence` 和 `fingerprint` 派生签名密钥：
+
+```
+K = HKDF(
+    input = licence + fingerprint,        # 输入密钥材料（字符串拼接）
+    salt = "AUTH_V3_SALT",                # 固定盐值
+    info = "device_report_signature",     # 固定信息参数
+    hash = SHA-256,                       # 哈希算法
+    length = 32                           # 输出密钥长度（32字节 = 256位）
+)
+```
+
+**伪代码示例**：
+```python
+import hkdf
+
+# 输入密钥材料
+ikm = licence + fingerprint  # 字符串直接拼接
+
+# HKDF 参数
+salt = "AUTH_V3_SALT"
+info = "device_report_signature"
+key_length = 32  # 32字节 = 256位
+
+# 派生密钥
+derived_key = hkdf.HKDF(
+    algorithm=hashlib.sha256,
+    length=key_length,
+    salt=salt.encode('utf-8'),
+    info=info.encode('utf-8'),
+    ikm=ikm.encode('utf-8')
+).derive()
+```
+
+### 2.3 签名数据组装（严格顺序）
+
+签名数据必须按照以下**严格顺序**组装：
+
+```
+sign_payload = 
+    taskId +                                    # 任务ID（字符串）
+    inspectionId +                              # 检查ID（数字转字符串）
+    SHA256(assets.json) +                      # assets.json 的 SHA256（hex字符串，小写）
+    SHA256(vulnerabilities.json) +             # vulnerabilities.json 的 SHA256（hex字符串，小写）
+    SHA256(weakPasswords.json) +               # weakPasswords.json 的 SHA256（hex字符串，小写）
+    SHA256(漏洞评估报告.html)                   # 漏洞评估报告.html 的 SHA256（hex字符串，小写）
+```
+
+**重要说明**：
+- 所有字符串直接拼接，**不添加任何分隔符**
+- SHA256 哈希值必须是 **hex 字符串（小写）**，例如：`a1b2c3d4...`
+- 文件内容必须是**原始字节**，不能进行任何编码转换
+- 顺序必须严格一致，任何顺序错误都会导致签名验证失败
+
+**伪代码示例**：
+```python
+import hashlib
+
+# 1. 读取文件内容（原始字节）
+assets_content = read_file("assets.json")
+vulnerabilities_content = read_file("vulnerabilities.json")
+weak_passwords_content = read_file("weakPasswords.json")
+report_html_content = read_file("漏洞评估报告.html")
+
+# 2. 计算 SHA256（hex字符串，小写）
+def sha256_hex(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+assets_sha256 = sha256_hex(assets_content)
+vulnerabilities_sha256 = sha256_hex(vulnerabilities_content)
+weak_passwords_sha256 = sha256_hex(weak_passwords_content)
+report_html_sha256 = sha256_hex(report_html_content)
+
+# 3. 组装签名数据（严格顺序，直接拼接）
+sign_payload = (
+    str(task_id) +
+    str(inspection_id) +
+    assets_sha256 +
+    vulnerabilities_sha256 +
+    weak_passwords_sha256 +
+    report_html_sha256
+)
+```
+
+### 2.4 生成设备签名
+
+使用 **HMAC-SHA256** 计算签名：
+
+```
+device_signature = Base64(HMAC-SHA256(key=K, data=sign_payload))
+```
+
+**伪代码示例**：
+```python
+import hmac
+import base64
+
+# 使用派生密钥计算 HMAC-SHA256
+mac = hmac.new(
+    key=derived_key,                    # 派生密钥（32字节）
+    msg=sign_payload.encode('utf-8'),  # 签名数据（UTF-8编码）
+    digestmod=hashlib.sha256
+)
+
+# 计算签名
+signature_bytes = mac.digest()
+
+# Base64 编码
+device_signature = base64.b64encode(signature_bytes).decode('utf-8')
+```
+
+### 2.5 写入 summary.json
+
+将 `device_signature` 写入 `summary.json`：
+
+```json
+{
+  "orgId": 1173040813421105152,
+  "checkId": 702286470691215417,
+  "taskId": "TASK-20260115-4875",
+  "licence": "LIC-8F2A-XXXX",
+  "fingerprint": "FP-2c91e9f3",
+  "deviceSignature": "Base64编码的签名值",
+  "summary": "检查摘要信息",
+  ...其他字段...
+}
+```
+
+**必需字段**：
+- `licence`：设备授权码（字符串）
+- `fingerprint`：设备硬件指纹（字符串）
+- `taskId`：任务ID（字符串）
+- `deviceSignature`：设备签名（Base64字符串）
+- `checkId` 或 `inspectionId`：检查ID（数字）
+
+## 三、防篡改校验 - OpenPGP 签名
+
+### 3.1 目的
+
+OpenPGP 签名用于验证 ZIP 文件在传输过程中未被篡改，确保文件完整性。
+
+### 3.2 生成 manifest.json
+
+创建 `META-INF/manifest.json` 文件，包含所有文件的 SHA-256 哈希值：
+
+```json
+{
+  "files": {
+    "summary.json": "a1b2c3d4e5f6...",
+    "assets.json": "b2c3d4e5f6a1...",
+    "vulnerabilities.json": "c3d4e5f6a1b2...",
+    "weakPasswords.json": "d4e5f6a1b2c3...",
+    "漏洞评估报告.html": "e5f6a1b2c3d4..."
+  }
+}
+```
+
+**伪代码示例**：
+```python
+import hashlib
+import json
+
+def calculate_sha256_hex(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+# 计算所有文件的 SHA256
+files_hashes = {
+    "summary.json": calculate_sha256_hex(summary_content),
+    "assets.json": calculate_sha256_hex(assets_content),
+    "vulnerabilities.json": calculate_sha256_hex(vulnerabilities_content),
+    "weakPasswords.json": calculate_sha256_hex(weak_passwords_content),
+    "漏洞评估报告.html": calculate_sha256_hex(report_html_content)
+}
+
+# 生成 manifest.json
+manifest = {
+    "files": files_hashes
+}
+
+manifest_json = json.dumps(manifest, ensure_ascii=False, indent=2)
+```
+
+### 3.3 生成 OpenPGP 签名
+
+使用工具箱的**私钥**对 `manifest.json` 进行 OpenPGP 签名，生成 `META-INF/signature.asc`：
+
+**伪代码示例（使用 Python gnupg）**：
+```python
+import gnupg
+
+# 初始化 GPG
+gpg = gnupg.GPG()
+
+# 导入私钥（或使用已配置的密钥）
+# gpg.import_keys(private_key_data)
+
+# 对 manifest.json 进行签名
+with open('META-INF/manifest.json', 'rb') as f:
+    signed_data = gpg.sign_file(
+        f,
+        detach=True,           # 分离式签名
+        clearsign=False,      # 不使用明文签名
+        output='META-INF/signature.asc'
+    )
+```
+
+**伪代码示例（使用 BouncyCastle - Java/Kotlin）**：
+```kotlin
+import org.bouncycastle.openpgp.*
+import org.bouncycastle.openpgp.operator.jcajce.JcaPGPContentSignerBuilder
+import org.bouncycastle.openpgp.operator.jcajce.JcaPGPPrivateKey
+import java.io.ByteArrayOutputStream
+import java.io.FileOutputStream
+
+fun generatePGPSignature(
+    manifestContent: ByteArray,
+    privateKey: PGPPrivateKey,
+    publicKey: PGPPublicKey
+): ByteArray {
+    val signatureGenerator = PGPSignatureGenerator(
+        JcaPGPContentSignerBuilder(publicKey.algorithm, PGPUtil.SHA256)
+    )
+    signatureGenerator.init(PGPSignature.BINARY_DOCUMENT, privateKey)
+    signatureGenerator.update(manifestContent)
+    
+    val signature = signatureGenerator.generate()
+    val signatureList = PGPSignatureList(signature)
+    
+    val out = ByteArrayOutputStream()
+    val pgpOut = PGPObjectFactory(PGPUtil.getEncoderStream(out))
+    signatureList.encode(out)
+    
+    return out.toByteArray()
+}
+```
+
+### 3.4 打包 ZIP 文件
+
+将所有文件打包成 ZIP 文件，确保包含：
+- 所有报告文件（summary.json、assets.json 等）
+- `META-INF/manifest.json`
+- `META-INF/signature.asc`
+
+**伪代码示例**：
+```python
+import zipfile
+
+def create_signed_zip(output_path: str):
+    with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zipf:
+        # 添加报告文件
+        zipf.write('summary.json', 'summary.json')
+        zipf.write('assets.json', 'assets.json')
+        zipf.write('vulnerabilities.json', 'vulnerabilities.json')
+        zipf.write('weakPasswords.json', 'weakPasswords.json')
+        zipf.write('漏洞评估报告.html', '漏洞评估报告.html')
+        
+        # 添加签名文件
+        zipf.write('META-INF/manifest.json', 'META-INF/manifest.json')
+        zipf.write('META-INF/signature.asc', 'META-INF/signature.asc')
+```
+
+## 四、完整流程示例
+
+### 4.1 Python 完整示例
+
+```python
+import hashlib
+import hmac
+import base64
+import json
+import zipfile
+import hkdf
+import gnupg
+
+def generate_report_zip(
+    licence: str,
+    fingerprint: str,
+    task_id: str,
+    inspection_id: int,
+    output_path: str
+):
+    """
+    生成带签名和加密的检查报告 ZIP 文件
+    """
+    
+    # ========== 1. 读取报告文件 ==========
+    assets_content = read_file("assets.json")
+    vulnerabilities_content = read_file("vulnerabilities.json")
+    weak_passwords_content = read_file("weakPasswords.json")
+    report_html_content = read_file("漏洞评估报告.html")
+    
+    # ========== 2. 生成设备签名 ==========
+    
+    # 2.1 密钥派生
+    ikm = licence + fingerprint
+    salt = "AUTH_V3_SALT"
+    info = "device_report_signature"
+    key_length = 32
+    
+    derived_key = hkdf.HKDF(
+        algorithm=hashlib.sha256,
+        length=key_length,
+        salt=salt.encode('utf-8'),
+        info=info.encode('utf-8'),
+        ikm=ikm.encode('utf-8')
+    ).derive()
+    
+    # 2.2 计算文件 SHA256
+    def sha256_hex(content: bytes) -> str:
+        return hashlib.sha256(content).hexdigest()
+    
+    assets_sha256 = sha256_hex(assets_content)
+    vulnerabilities_sha256 = sha256_hex(vulnerabilities_content)
+    weak_passwords_sha256 = sha256_hex(weak_passwords_content)
+    report_html_sha256 = sha256_hex(report_html_content)
+    
+    # 2.3 组装签名数据（严格顺序）
+    sign_payload = (
+        str(task_id) +
+        str(inspection_id) +
+        assets_sha256 +
+        vulnerabilities_sha256 +
+        weak_passwords_sha256 +
+        report_html_sha256
+    )
+    
+    # 2.4 计算 HMAC-SHA256
+    mac = hmac.new(
+        key=derived_key,
+        msg=sign_payload.encode('utf-8'),
+        digestmod=hashlib.sha256
+    )
+    device_signature = base64.b64encode(mac.digest()).decode('utf-8')
+    
+    # 2.5 生成 summary.json
+    summary = {
+        "orgId": 1173040813421105152,
+        "checkId": inspection_id,
+        "taskId": task_id,
+        "licence": licence,
+        "fingerprint": fingerprint,
+        "deviceSignature": device_signature,
+        "summary": "检查摘要信息"
+    }
+    summary_content = json.dumps(summary, ensure_ascii=False).encode('utf-8')
+    
+    # ========== 3. 生成 OpenPGP 签名 ==========
+    
+    # 3.1 生成 manifest.json
+    files_hashes = {
+        "summary.json": sha256_hex(summary_content),
+        "assets.json": assets_sha256,
+        "vulnerabilities.json": vulnerabilities_sha256,
+        "weakPasswords.json": weak_passwords_sha256,
+        "漏洞评估报告.html": report_html_sha256
+    }
+    manifest = {"files": files_hashes}
+    manifest_content = json.dumps(manifest, ensure_ascii=False, indent=2).encode('utf-8')
+    
+    # 3.2 生成 OpenPGP 签名
+    gpg = gnupg.GPG()
+    with open('META-INF/manifest.json', 'wb') as f:
+        f.write(manifest_content)
+    
+    with open('META-INF/manifest.json', 'rb') as f:
+        signed_data = gpg.sign_file(
+            f,
+            detach=True,
+            output='META-INF/signature.asc'
+        )
+    
+    # ========== 4. 打包 ZIP 文件 ==========
+    with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zipf:
+        zipf.writestr('summary.json', summary_content)
+        zipf.writestr('assets.json', assets_content)
+        zipf.writestr('vulnerabilities.json', vulnerabilities_content)
+        zipf.writestr('weakPasswords.json', weak_passwords_content)
+        zipf.writestr('漏洞评估报告.html', report_html_content)
+        zipf.writestr('META-INF/manifest.json', manifest_content)
+        zipf.write('META-INF/signature.asc', 'META-INF/signature.asc')
+    
+    print(f"报告 ZIP 文件生成成功: {output_path}")
+```
+
+### 4.2 Java/Kotlin 完整示例
+
+```kotlin
+import org.bouncycastle.crypto.digests.SHA256Digest
+import org.bouncycastle.crypto.generators.HKDFBytesGenerator
+import org.bouncycastle.crypto.params.HKDFParameters
+import java.security.MessageDigest
+import javax.crypto.Mac
+import javax.crypto.spec.SecretKeySpec
+import java.util.Base64
+import java.util.zip.ZipOutputStream
+import java.io.FileOutputStream
+
+fun generateReportZip(
+    licence: String,
+    fingerprint: String,
+    taskId: String,
+    inspectionId: Long,
+    outputPath: String
+) {
+    // ========== 1. 读取报告文件 ==========
+    val assetsContent = readFile("assets.json")
+    val vulnerabilitiesContent = readFile("vulnerabilities.json")
+    val weakPasswordsContent = readFile("weakPasswords.json")
+    val reportHtmlContent = readFile("漏洞评估报告.html")
+    
+    // ========== 2. 生成设备签名 ==========
+    
+    // 2.1 密钥派生
+    val ikm = (licence + fingerprint).toByteArray(Charsets.UTF_8)
+    val salt = "AUTH_V3_SALT".toByteArray(Charsets.UTF_8)
+    val info = "device_report_signature".toByteArray(Charsets.UTF_8)
+    val keyLength = 32
+    
+    val hkdf = HKDFBytesGenerator(SHA256Digest())
+    hkdf.init(HKDFParameters(ikm, salt, info))
+    val derivedKey = ByteArray(keyLength)
+    hkdf.generateBytes(derivedKey, 0, keyLength)
+    
+    // 2.2 计算文件 SHA256
+    fun sha256Hex(content: ByteArray): String {
+        val digest = MessageDigest.getInstance("SHA-256")
+        val hashBytes = digest.digest(content)
+        return hashBytes.joinToString("") { "%02x".format(it) }
+    }
+    
+    val assetsSha256 = sha256Hex(assetsContent)
+    val vulnerabilitiesSha256 = sha256Hex(vulnerabilitiesContent)
+    val weakPasswordsSha256 = sha256Hex(weakPasswordsContent)
+    val reportHtmlSha256 = sha256Hex(reportHtmlContent)
+    
+    // 2.3 组装签名数据（严格顺序）
+    val signPayload = buildString {
+        append(taskId)
+        append(inspectionId)
+        append(assetsSha256)
+        append(vulnerabilitiesSha256)
+        append(weakPasswordsSha256)
+        append(reportHtmlSha256)
+    }
+    
+    // 2.4 计算 HMAC-SHA256
+    val mac = Mac.getInstance("HmacSHA256")
+    val secretKey = SecretKeySpec(derivedKey, "HmacSHA256")
+    mac.init(secretKey)
+    val signatureBytes = mac.doFinal(signPayload.toByteArray(Charsets.UTF_8))
+    val deviceSignature = Base64.getEncoder().encodeToString(signatureBytes)
+    
+    // 2.5 生成 summary.json
+    val summary = mapOf(
+        "orgId" to 1173040813421105152L,
+        "checkId" to inspectionId,
+        "taskId" to taskId,
+        "licence" to licence,
+        "fingerprint" to fingerprint,
+        "deviceSignature" to deviceSignature,
+        "summary" to "检查摘要信息"
+    )
+    val summaryContent = objectMapper.writeValueAsString(summary).toByteArray(Charsets.UTF_8)
+    
+    // ========== 3. 生成 OpenPGP 签名 ==========
+    
+    // 3.1 生成 manifest.json
+    val filesHashes = mapOf(
+        "summary.json" to sha256Hex(summaryContent),
+        "assets.json" to assetsSha256,
+        "vulnerabilities.json" to vulnerabilitiesSha256,
+        "weakPasswords.json" to weakPasswordsSha256,
+        "漏洞评估报告.html" to reportHtmlSha256
+    )
+    val manifest = mapOf("files" to filesHashes)
+    val manifestContent = objectMapper.writeValueAsString(manifest).toByteArray(Charsets.UTF_8)
+    
+    // 3.2 生成 OpenPGP 签名（使用 BouncyCastle）
+    val signatureAsc = generatePGPSignature(manifestContent, privateKey, publicKey)
+    
+    // ========== 4. 打包 ZIP 文件 ==========
+    ZipOutputStream(FileOutputStream(outputPath)).use { zipOut ->
+        zipOut.putNextEntry(ZipEntry("summary.json"))
+        zipOut.write(summaryContent)
+        zipOut.closeEntry()
+        
+        zipOut.putNextEntry(ZipEntry("assets.json"))
+        zipOut.write(assetsContent)
+        zipOut.closeEntry()
+        
+        zipOut.putNextEntry(ZipEntry("vulnerabilities.json"))
+        zipOut.write(vulnerabilitiesContent)
+        zipOut.closeEntry()
+        
+        zipOut.putNextEntry(ZipEntry("weakPasswords.json"))
+        zipOut.write(weakPasswordsContent)
+        zipOut.closeEntry()
+        
+        zipOut.putNextEntry(ZipEntry("漏洞评估报告.html"))
+        zipOut.write(reportHtmlContent)
+        zipOut.closeEntry()
+        
+        zipOut.putNextEntry(ZipEntry("META-INF/manifest.json"))
+        zipOut.write(manifestContent)
+        zipOut.closeEntry()
+        
+        zipOut.putNextEntry(ZipEntry("META-INF/signature.asc"))
+        zipOut.write(signatureAsc)
+        zipOut.closeEntry()
+    }
+    
+    println("报告 ZIP 文件生成成功: $outputPath")
+}
+```
+
+## 五、平台端验证流程
+
+平台端会按以下顺序验证：
+
+1. **OpenPGP 签名验证**（防篡改）
+   - 读取 `META-INF/manifest.json` 和 `META-INF/signature.asc`
+   - 使用平台公钥验证签名
+   - 验证所有文件的 SHA256 是否与 manifest.json 中的哈希值匹配
+
+2. **设备签名验证**（授权）
+   - 从 `summary.json` 提取 `licence`、`fingerprint`、`taskId`、`deviceSignature`
+   - 验证 `licence + fingerprint` 是否已绑定
+   - 验证 `taskId` 是否存在且属于该设备
+   - 使用相同的 HKDF 派生密钥
+   - 重新计算签名并与 `deviceSignature` 比较
+
+## 六、常见错误和注意事项
+
+### 6.1 设备签名验证失败
+
+**可能原因**：
+1. **密钥派生错误**：确保使用正确的 `salt` 和 `info` 参数
+2. **签名数据顺序错误**：必须严格按照 `taskId + inspectionId + SHA256(...)` 的顺序
+3. **SHA256 格式错误**：必须是 hex 字符串（小写），不能包含分隔符
+4. **文件内容错误**：确保使用原始文件内容，不能进行编码转换
+5. **licence 或 fingerprint 不匹配**：确保与平台绑定的值一致
+
+### 6.2 OpenPGP 签名验证失败
+
+**可能原因**：
+1. **私钥不匹配**：确保使用与平台公钥对应的私钥
+2. **manifest.json 格式错误**：确保 JSON 格式正确
+3. **文件哈希值错误**：确保 manifest.json 中的哈希值与实际文件匹配
+
+### 6.3 文件缺失
+
+**必需文件**：
+- `summary.json`（必须包含授权字段）
+- `assets.json`
+- `vulnerabilities.json`
+- `weakPasswords.json`（文件名大小写不敏感）
+- `漏洞评估报告.html`（文件名包含"漏洞评估报告"且以".html"结尾）
+- `META-INF/manifest.json`
+- `META-INF/signature.asc`
+
+## 七、安全设计说明
+
+### 7.1 为什么第三方无法伪造
+
+1. **设备签名**：
+   - 只有拥有正确 `licence + fingerprint` 的设备才能派生正确的签名密钥
+   - 即使第三方获取了某个设备的签名，也无法用于其他任务（`taskId` 绑定）
+   - 即使第三方修改了报告内容，签名也会失效（多个文件的 SHA256 绑定）
+
+2. **OpenPGP 签名**：
+   - 只有拥有私钥的工具箱才能生成有效签名
+   - 任何文件修改都会导致哈希值不匹配
+
+### 7.2 密钥分离
+
+使用 HKDF 的 `info` 参数区分不同用途的密钥：
+- `device_report_signature`：用于设备签名
+- 其他用途可以使用不同的 `info` 值，确保密钥隔离
+
+## 八、测试建议
+
+1. **单元测试**：
+   - 测试密钥派生是否正确
+   - 测试签名生成和验证是否匹配
+   - 测试文件 SHA256 计算是否正确
+
+2. **集成测试**：
+   - 使用真实数据生成 ZIP 文件
+   - 上传到平台验证是否通过
+   - 测试篡改文件后验证是否失败
+
+3. **边界测试**：
+   - 测试文件缺失的情况
+   - 测试签名数据顺序错误的情况
+   - 测试错误的 `licence` 或 `fingerprint` 的情况
+
+## 九、参考实现
+
+- **HKDF 实现**：BouncyCastle（Java/Kotlin）、`hkdf` 库（Python）
+- **HMAC-SHA256**：Java `javax.crypto.Mac`、Python `hmac`
+- **OpenPGP**：BouncyCastle（Java/Kotlin）、`gnupg` 库（Python）
+
+## 十、联系支持
+
+如有问题，请联系平台技术支持团队。
+
--- a/docs/工具箱端-授权对接指南/工具箱端-摘要信息二维码生成指南.md
+++ b/docs/工具箱端-授权对接指南/工具箱端-摘要信息二维码生成指南.md
@@ -0,0 +1,756 @@
+# 工具箱端 - 摘要信息二维码生成指南
+
+## 概述
+
+本文档说明工具箱端如何生成摘要信息二维码。工具箱完成检查任务后，需要将摘要信息加密并生成二维码，供 App 扫描后上传到平台。
+
+> ### UX 集成模式补充（当前项目实现）
+>
+> 在当前集成模式中，工具箱将明文文本传给 UX 的 `crypto.encryptSummary`，并提供 `salt`。
+> UX 从本地配置读取 licence/fingerprint，执行 HKDF + AES-256-GCM 并返回 Base64 密文。
+
+## 一、业务流程
+
+```
+工具箱完成检查 → 准备摘要信息 → HKDF派生密钥 → AES-256-GCM加密 → 组装二维码内容 → 生成二维码
+                                                                                    ↓
+App扫描二维码 → 提取taskId和encrypted → 提交到平台 → 平台解密验证 → 保存摘要信息
+```
+
+## 二、二维码内容格式
+
+二维码内容为 JSON 格式，包含以下字段：
+
+```json
+{
+  "taskId": "TASK-20260115-4875",
+  "encrypted": "uWUcAmp6UQd0w3G3crdsd4613QCxGLoEgslgXJ4G2hQhpQdjtghtQjCBUZwB/JO+NRgH1vSTr8dqBJRq7Qh4nugESrB2jUSGASTf4+5E7cLlDOmtDw7QlqS+6Hb7sn3daMSOovcna07huchHeesrJCiHV8ntEDXdCCdQOEHfkZAvy5gS8jQY41x5Qcnmqbz3qqHTmceIihTj4uqRVyKOE8jxzY6ko76jx0gW239gyFysJUTrqSPiFAr+gToi2l9SWP8ISViBmYmCY2cQtKvPfTKXwxGMid0zE/nDmb9n38X1oR05nAP0v1KaVY7iPcjsWySDGqO2iIbPzV8tQzq5TNuYqn9gvxIX/oRTFECP+aosfmOD5I8H8rVFTebyTHw+ONV3KoN2IMRqnG+a2lucbhzwQk7/cX1hs9lYm+yapmp+0MbLCtf2KMWqJPdeZqTVZgi3R181BCxo3OIwcCFTnZ/b9pdw+q8ai6SJpso5mA0TpUCvqYlGlKMZde0nj07kmLpdAm3AOg3GtPezfJu8iHmsc4PTa8RDsPgTIxcdyxNSMqo1Ws3VLQXm6DHK/kma/vbvSA/N7upPzi7wLvboig=="
+}
+```
+
+### 2.1 字段说明
+
+| 字段名 | 类型 | 说明 | 示例 |
+|--------|------|------|------|
+| `taskId` | String | 任务ID（从任务二维码中获取） | `"TASK-20260115-4875"` |
+| `encrypted` | String | Base64编码的加密数据 | `"uWUcAmp6UQd0w3G3..."` |
+
+## 三、摘要信息数据结构
+
+### 3.1 明文数据 JSON 格式
+
+加密前的摘要信息为 JSON 格式，包含以下字段：
+
+```json
+{
+  "enterpriseId": "1173040813421105152",
+  "inspectionId": "702286470691215417",
+  "summary": "检查摘要信息",
+  "timestamp": 1734571234567
+}
+```
+
+### 3.2 字段说明
+
+| 字段名 | 类型 | 说明 | 示例 |
+|--------|------|------|------|
+| `enterpriseId` | String | 企业ID（从任务数据中获取） | `"1173040813421105152"` |
+| `inspectionId` | String | 检查ID（从任务数据中获取） | `"702286470691215417"` |
+| `summary` | String | 检查摘要信息 | `"检查摘要信息"` |
+| `timestamp` | Number | 时间戳（毫秒） | `1734571234567` |
+
+## 四、密钥派生（HKDF-SHA256）
+
+### 4.1 密钥派生参数
+
+使用 **HKDF-SHA256** 从 `licence + fingerprint` 派生 AES 密钥：
+
+```
+AES Key = HKDF(
+    input = licence + fingerprint,              # 输入密钥材料（字符串拼接）
+    salt = taskId,                              # Salt值（任务ID）
+    info = "inspection_report_encryption",     # Info值（固定值）
+    hash = SHA-256,                             # 哈希算法
+    length = 32                                 # 输出密钥长度（32字节 = 256位）
+)
+```
+
+**重要说明**：
+- `ikm`（输入密钥材料）= `licence + fingerprint`（直接字符串拼接，无分隔符）
+- `salt` = `taskId`（从任务二维码中获取的任务ID）
+- `info` = `"inspection_report_encryption"`（固定值，区分不同用途的密钥）
+- `length` = `32` 字节（AES-256 密钥长度）
+
+### 4.2 Python 实现示例
+
+```python
+import hashlib
+import hkdf
+
+def derive_aes_key(licence: str, fingerprint: str, task_id: str) -> bytes:
+    """
+    使用 HKDF-SHA256 派生 AES-256 密钥
+    
+    Args:
+        licence: 设备授权码
+        fingerprint: 设备硬件指纹
+        task_id: 任务ID
+    
+    Returns:
+        派生出的密钥（32字节）
+    """
+    # 输入密钥材料
+    ikm = licence + fingerprint  # 直接字符串拼接
+    
+    # HKDF 参数
+    salt = task_id
+    info = "inspection_report_encryption"
+    key_length = 32  # 32字节 = 256位
+    
+    # 派生密钥
+    derived_key = hkdf.HKDF(
+        algorithm=hashlib.sha256,
+        length=key_length,
+        salt=salt.encode('utf-8'),
+        info=info.encode('utf-8'),
+        ikm=ikm.encode('utf-8')
+    ).derive()
+    
+    return derived_key
+```
+
+### 4.3 Java/Kotlin 实现示例
+
+```kotlin
+import org.bouncycastle.crypto.digests.SHA256Digest
+import org.bouncycastle.crypto.generators.HKDFBytesGenerator
+import org.bouncycastle.crypto.params.HKDFParameters
+import java.nio.charset.StandardCharsets
+
+fun deriveAesKey(licence: String, fingerprint: String, taskId: String): ByteArray {
+    // 输入密钥材料
+    val ikm = (licence + fingerprint).toByteArray(StandardCharsets.UTF_8)
+    
+    // HKDF 参数
+    val salt = taskId.toByteArray(StandardCharsets.UTF_8)
+    val info = "inspection_report_encryption".toByteArray(StandardCharsets.UTF_8)
+    val keyLength = 32  // 32字节 = 256位
+    
+    // 派生密钥
+    val hkdf = HKDFBytesGenerator(SHA256Digest())
+    val params = HKDFParameters(ikm, salt, info)
+    hkdf.init(params)
+    
+    val derivedKey = ByteArray(keyLength)
+    hkdf.generateBytes(derivedKey, 0, keyLength)
+    
+    return derivedKey
+}
+```
+
+## 五、AES-256-GCM 加密
+
+### 5.1 加密算法
+
+- **算法**：AES-256-GCM（Galois/Counter Mode）
+- **密钥长度**：256 位（32 字节）
+- **IV 长度**：12 字节（96 位）
+- **认证标签长度**：16 字节（128 位）
+
+### 5.2 加密数据格式
+
+加密后的数据格式（Base64 编码前）：
+
+```
+[IV(12字节)] + [加密数据] + [认证标签(16字节)]
+```
+
+**数据布局**：
+```
+------------------+------------------+------------------+
+|   IV (12字节)    |   加密数据       |   认证标签(16字节)|
+------------------+------------------+------------------+
+```
+
+### 5.3 Python 实现示例
+
+```python
+import base64
+import hashlib
+import hkdf
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.backends import default_backend
+import json
+import time
+
+def encrypt_summary_data(
+    enterprise_id: str,
+    inspection_id: str,
+    summary: str,
+    licence: str,
+    fingerprint: str,
+    task_id: str
+) -> str:
+    """
+    加密摘要信息数据
+    
+    Args:
+        enterprise_id: 企业ID
+        inspection_id: 检查ID
+        summary: 摘要信息
+        licence: 设备授权码
+        fingerprint: 设备硬件指纹
+        task_id: 任务ID
+    
+    Returns:
+        Base64编码的加密数据
+    """
+    # 1. 组装明文数据（JSON格式）
+    timestamp = int(time.time() * 1000)  # 毫秒时间戳
+    plaintext_map = {
+        "enterpriseId": str(enterprise_id),
+        "inspectionId": str(inspection_id),
+        "summary": summary,
+        "timestamp": timestamp
+    }
+    plaintext = json.dumps(plaintext_map, ensure_ascii=False)
+    
+    # 2. 使用 HKDF-SHA256 派生 AES 密钥
+    ikm = licence + fingerprint
+    salt = task_id
+    info = "inspection_report_encryption"
+    key_length = 32
+    
+    aes_key = hkdf.HKDF(
+        algorithm=hashlib.sha256,
+        length=key_length,
+        salt=salt.encode('utf-8'),
+        info=info.encode('utf-8'),
+        ikm=ikm.encode('utf-8')
+    ).derive()
+    
+    # 3. 使用 AES-256-GCM 加密数据
+    aesgcm = AESGCM(aes_key)
+    iv = os.urandom(12)  # 生成12字节随机IV
+    encrypted_bytes = aesgcm.encrypt(iv, plaintext.encode('utf-8'), None)
+    
+    # 4. 组装：IV + 加密数据（包含认证标签）
+    # AESGCM.encrypt 返回的格式已经是：加密数据 + 认证标签
+    combined = iv + encrypted_bytes
+    
+    # 5. Base64 编码
+    encrypted_base64 = base64.b64encode(combined).decode('utf-8')
+    
+    return encrypted_base64
+```
+
+### 5.4 Java/Kotlin 实现示例
+
+```kotlin
+import com.fasterxml.jackson.databind.ObjectMapper
+import org.bouncycastle.crypto.digests.SHA256Digest
+import org.bouncycastle.crypto.generators.HKDFBytesGenerator
+import org.bouncycastle.crypto.params.HKDFParameters
+import java.nio.charset.StandardCharsets
+import java.security.SecureRandom
+import java.util.Base64
+import javax.crypto.Cipher
+import javax.crypto.spec.GCMParameterSpec
+import javax.crypto.spec.SecretKeySpec
+
+object SummaryEncryptionUtil {
+    
+    private const val ALGORITHM = "AES"
+    private const val TRANSFORMATION = "AES/GCM/NoPadding"
+    private const val GCM_IV_LENGTH = 12 // 12 bytes = 96 bits
+    private const val GCM_TAG_LENGTH = 16 // 16 bytes = 128 bits
+    private const val GCM_TAG_LENGTH_BITS = GCM_TAG_LENGTH * 8 // 128 bits
+    
+    private val objectMapper = ObjectMapper()
+    private val secureRandom = SecureRandom()
+    
+    /**
+     * 加密摘要信息数据
+     */
+    fun encryptSummaryData(
+        enterpriseId: String,
+        inspectionId: String,
+        summary: String,
+        licence: String,
+        fingerprint: String,
+        taskId: String
+    ): String {
+        // 1. 组装明文数据（JSON格式）
+        val timestamp = System.currentTimeMillis()
+        val plaintextMap = mapOf(
+            "enterpriseId" to enterpriseId,
+            "inspectionId" to inspectionId,
+            "summary" to summary,
+            "timestamp" to timestamp
+        )
+        val plaintext = objectMapper.writeValueAsString(plaintextMap)
+        
+        // 2. 使用 HKDF-SHA256 派生 AES 密钥
+        val ikm = (licence + fingerprint).toByteArray(StandardCharsets.UTF_8)
+        val salt = taskId.toByteArray(StandardCharsets.UTF_8)
+        val info = "inspection_report_encryption".toByteArray(StandardCharsets.UTF_8)
+        val keyLength = 32
+        
+        val hkdf = HKDFBytesGenerator(SHA256Digest())
+        val params = HKDFParameters(ikm, salt, info)
+        hkdf.init(params)
+        
+        val aesKey = ByteArray(keyLength)
+        hkdf.generateBytes(aesKey, 0, keyLength)
+        
+        // 3. 使用 AES-256-GCM 加密数据
+        val iv = ByteArray(GCM_IV_LENGTH)
+        secureRandom.nextBytes(iv)
+        
+        val secretKey = SecretKeySpec(aesKey, ALGORITHM)
+        val gcmSpec = GCMParameterSpec(GCM_TAG_LENGTH_BITS, iv)
+        
+        val cipher = Cipher.getInstance(TRANSFORMATION)
+        cipher.init(Cipher.ENCRYPT_MODE, secretKey, gcmSpec)
+        
+        val plaintextBytes = plaintext.toByteArray(StandardCharsets.UTF_8)
+        val encryptedBytes = cipher.doFinal(plaintextBytes)
+        
+        // 4. 组装：IV + 加密数据（包含认证标签）
+        // GCM 模式会将认证标签附加到密文末尾
+        val ciphertext = encryptedBytes.sliceArray(0 until encryptedBytes.size - GCM_TAG_LENGTH)
+        val tag = encryptedBytes.sliceArray(encryptedBytes.size - GCM_TAG_LENGTH until encryptedBytes.size)
+        
+        val combined = iv + ciphertext + tag
+        
+        // 5. Base64 编码
+        return Base64.getEncoder().encodeToString(combined)
+    }
+}
+```
+
+## 六、组装二维码内容
+
+### 6.1 二维码内容 JSON
+
+将 `taskId` 和加密后的 `encrypted` 组装成 JSON 格式：
+
+```json
+{
+  "taskId": "TASK-20260115-4875",
+  "encrypted": "Base64编码的加密数据"
+}
+```
+
+### 6.2 Python 实现示例
+
+```python
+import json
+
+def generate_qr_code_content(task_id: str, encrypted: str) -> str:
+    """
+    生成二维码内容（JSON格式）
+    
+    Args:
+        task_id: 任务ID
+        encrypted: Base64编码的加密数据
+    
+    Returns:
+        JSON格式的字符串
+    """
+    qr_content = {
+        "taskId": task_id,
+        "encrypted": encrypted
+    }
+    return json.dumps(qr_content, ensure_ascii=False)
+```
+
+## 七、完整流程示例
+
+### 7.1 Python 完整示例
+
+```python
+import base64
+import json
+import time
+import hashlib
+import hkdf
+import qrcode
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+import os
+
+class SummaryQRCodeGenerator:
+    """摘要信息二维码生成器"""
+    
+    def __init__(self, licence: str, fingerprint: str):
+        """
+        初始化生成器
+        
+        Args:
+            licence: 设备授权码
+            fingerprint: 设备硬件指纹
+        """
+        self.licence = licence
+        self.fingerprint = fingerprint
+    
+    def generate_summary_qr_code(
+        self,
+        task_id: str,
+        enterprise_id: str,
+        inspection_id: str,
+        summary: str,
+        output_path: str = "summary_qr.png"
+    ) -> str:
+        """
+        生成摘要信息二维码
+        
+        Args:
+            task_id: 任务ID（从任务二维码中获取）
+            enterprise_id: 企业ID（从任务数据中获取）
+            inspection_id: 检查ID（从任务数据中获取）
+            summary: 摘要信息
+            output_path: 二维码图片保存路径
+        
+        Returns:
+            二维码内容（JSON字符串）
+        """
+        # 1. 组装明文数据（JSON格式）
+        timestamp = int(time.time() * 1000)  # 毫秒时间戳
+        plaintext_map = {
+            "enterpriseId": str(enterprise_id),
+            "inspectionId": str(inspection_id),
+            "summary": summary,
+            "timestamp": timestamp
+        }
+        plaintext = json.dumps(plaintext_map, ensure_ascii=False)
+        print(f"明文数据: {plaintext}")
+        
+        # 2. 使用 HKDF-SHA256 派生 AES 密钥
+        ikm = self.licence + self.fingerprint
+        salt = task_id
+        info = "inspection_report_encryption"
+        key_length = 32
+        
+        aes_key = hkdf.HKDF(
+            algorithm=hashlib.sha256,
+            length=key_length,
+            salt=salt.encode('utf-8'),
+            info=info.encode('utf-8'),
+            ikm=ikm.encode('utf-8')
+        ).derive()
+        print(f"密钥派生成功: {len(aes_key)} 字节")
+        
+        # 3. 使用 AES-256-GCM 加密数据
+        aesgcm = AESGCM(aes_key)
+        iv = os.urandom(12)  # 生成12字节随机IV
+        encrypted_bytes = aesgcm.encrypt(iv, plaintext.encode('utf-8'), None)
+        
+        # 组装：IV + 加密数据（包含认证标签）
+        combined = iv + encrypted_bytes
+        
+        # Base64 编码
+        encrypted_base64 = base64.b64encode(combined).decode('utf-8')
+        print(f"加密成功: {encrypted_base64[:50]}...")
+        
+        # 4. 组装二维码内容（JSON格式）
+        qr_content = {
+            "taskId": task_id,
+            "encrypted": encrypted_base64
+        }
+        qr_content_json = json.dumps(qr_content, ensure_ascii=False)
+        print(f"二维码内容: {qr_content_json[:100]}...")
+        
+        # 5. 生成二维码
+        qr = qrcode.QRCode(
+            version=1,
+            error_correction=qrcode.constants.ERROR_CORRECT_M,
+            box_size=10,
+            border=4,
+        )
+        qr.add_data(qr_content_json)
+        qr.make(fit=True)
+        
+        img = qr.make_image(fill_color="black", back_color="white")
+        img.save(output_path)
+        print(f"二维码已生成: {output_path}")
+        
+        return qr_content_json
+
+# 使用示例
+if __name__ == "__main__":
+    # 工具箱的授权信息（必须与平台绑定时一致）
+    licence = "LIC-8F2A-XXXX"
+    fingerprint = "FP-2c91e9f3"
+    
+    # 创建生成器
+    generator = SummaryQRCodeGenerator(licence, fingerprint)
+    
+    # 从任务二维码中获取的信息
+    task_id = "TASK-20260115-4875"
+    enterprise_id = "1173040813421105152"
+    inspection_id = "702286470691215417"
+    summary = "检查摘要信息：发现3个高危漏洞，5个中危漏洞"
+    
+    # 生成二维码
+    qr_content = generator.generate_summary_qr_code(
+        task_id=task_id,
+        enterprise_id=enterprise_id,
+        inspection_id=inspection_id,
+        summary=summary,
+        output_path="summary_qr_code.png"
+    )
+    
+    print(f"\n二维码内容:\n{qr_content}")
+```
+
+### 7.2 Java/Kotlin 完整示例
+
+```kotlin
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.google.zxing.BarcodeFormat
+import com.google.zxing.EncodeHintType
+import com.google.zxing.qrcode.QRCodeWriter
+import com.google.zxing.qrcode.decoder.ErrorCorrectionLevel
+import org.bouncycastle.crypto.digests.SHA256Digest
+import org.bouncycastle.crypto.generators.HKDFBytesGenerator
+import org.bouncycastle.crypto.params.HKDFParameters
+import java.awt.image.BufferedImage
+import java.nio.charset.StandardCharsets
+import java.security.SecureRandom
+import java.util.Base64
+import javax.crypto.Cipher
+import javax.crypto.spec.GCMParameterSpec
+import javax.crypto.spec.SecretKeySpec
+import javax.imageio.ImageIO
+import java.io.File
+
+class SummaryQRCodeGenerator(
+    private val licence: String,
+    private val fingerprint: String
+) {
+    
+    private const val ALGORITHM = "AES"
+    private const val TRANSFORMATION = "AES/GCM/NoPadding"
+    private const val GCM_IV_LENGTH = 12
+    private const val GCM_TAG_LENGTH = 16
+    private const val GCM_TAG_LENGTH_BITS = GCM_TAG_LENGTH * 8
+    
+    private val objectMapper = ObjectMapper()
+    private val secureRandom = SecureRandom()
+    
+    /**
+     * 生成摘要信息二维码
+     */
+    fun generateSummaryQRCode(
+        taskId: String,
+        enterpriseId: String,
+        inspectionId: String,
+        summary: String,
+        outputPath: String = "summary_qr.png"
+    ): String {
+        // 1. 组装明文数据（JSON格式）
+        val timestamp = System.currentTimeMillis()
+        val plaintextMap = mapOf(
+            "enterpriseId" to enterpriseId,
+            "inspectionId" to inspectionId,
+            "summary" to summary,
+            "timestamp" to timestamp
+        )
+        val plaintext = objectMapper.writeValueAsString(plaintextMap)
+        println("明文数据: $plaintext")
+        
+        // 2. 使用 HKDF-SHA256 派生 AES 密钥
+        val ikm = (licence + fingerprint).toByteArray(StandardCharsets.UTF_8)
+        val salt = taskId.toByteArray(StandardCharsets.UTF_8)
+        val info = "inspection_report_encryption".toByteArray(StandardCharsets.UTF_8)
+        val keyLength = 32
+        
+        val hkdf = HKDFBytesGenerator(SHA256Digest())
+        val params = HKDFParameters(ikm, salt, info)
+        hkdf.init(params)
+        
+        val aesKey = ByteArray(keyLength)
+        hkdf.generateBytes(aesKey, 0, keyLength)
+        println("密钥派生成功: ${aesKey.size} 字节")
+        
+        // 3. 使用 AES-256-GCM 加密数据
+        val iv = ByteArray(GCM_IV_LENGTH)
+        secureRandom.nextBytes(iv)
+        
+        val secretKey = SecretKeySpec(aesKey, ALGORITHM)
+        val gcmSpec = GCMParameterSpec(GCM_TAG_LENGTH_BITS, iv)
+        
+        val cipher = Cipher.getInstance(TRANSFORMATION)
+        cipher.init(Cipher.ENCRYPT_MODE, secretKey, gcmSpec)
+        
+        val plaintextBytes = plaintext.toByteArray(StandardCharsets.UTF_8)
+        val encryptedBytes = cipher.doFinal(plaintextBytes)
+        
+        // 组装：IV + 加密数据（包含认证标签）
+        val ciphertext = encryptedBytes.sliceArray(0 until encryptedBytes.size - GCM_TAG_LENGTH)
+        val tag = encryptedBytes.sliceArray(encryptedBytes.size - GCM_TAG_LENGTH until encryptedBytes.size)
+        
+        val combined = iv + ciphertext + tag
+        
+        // Base64 编码
+        val encryptedBase64 = Base64.getEncoder().encodeToString(combined)
+        println("加密成功: ${encryptedBase64.take(50)}...")
+        
+        // 4. 组装二维码内容（JSON格式）
+        val qrContent = mapOf(
+            "taskId" to taskId,
+            "encrypted" to encryptedBase64
+        )
+        val qrContentJson = objectMapper.writeValueAsString(qrContent)
+        println("二维码内容: ${qrContentJson.take(100)}...")
+        
+        // 5. 生成二维码
+        val hints = hashMapOf<EncodeHintType, Any>().apply {
+            put(EncodeHintType.ERROR_CORRECTION, ErrorCorrectionLevel.M)
+            put(EncodeHintType.CHARACTER_SET, "UTF-8")
+            put(EncodeHintType.MARGIN, 1)
+        }
+        
+        val writer = QRCodeWriter()
+        val bitMatrix = writer.encode(qrContentJson, BarcodeFormat.QR_CODE, 300, 300, hints)
+        
+        val width = bitMatrix.width
+        val height = bitMatrix.height
+        val image = BufferedImage(width, height, BufferedImage.TYPE_INT_RGB)
+        
+        for (x in 0 until width) {
+            for (y in 0 until height) {
+                image.setRGB(x, y, if (bitMatrix[x, y]) 0x000000 else 0xFFFFFF)
+            }
+        }
+        
+        ImageIO.write(image, "PNG", File(outputPath))
+        println("二维码已生成: $outputPath")
+        
+        return qrContentJson
+    }
+}
+
+// 使用示例
+fun main() {
+    // 工具箱的授权信息（必须与平台绑定时一致）
+    val licence = "LIC-8F2A-XXXX"
+    val fingerprint = "FP-2c91e9f3"
+    
+    // 创建生成器
+    val generator = SummaryQRCodeGenerator(licence, fingerprint)
+    
+    // 从任务二维码中获取的信息
+    val taskId = "TASK-20260115-4875"
+    val enterpriseId = "1173040813421105152"
+    val inspectionId = "702286470691215417"
+    val summary = "检查摘要信息：发现3个高危漏洞，5个中危漏洞"
+    
+    // 生成二维码
+    val qrContent = generator.generateSummaryQRCode(
+        taskId = taskId,
+        enterpriseId = enterpriseId,
+        inspectionId = inspectionId,
+        summary = summary,
+        outputPath = "summary_qr_code.png"
+    )
+    
+    println("\n二维码内容:\n$qrContent")
+}
+```
+
+## 八、平台端验证流程
+
+平台端会按以下流程验证：
+
+1. **接收请求**：App 扫描二维码后，将 `taskId` 和 `encrypted` 提交到平台
+2. **查询任务**：根据 `taskId` 查询任务记录，获取 `deviceLicenceId`
+3. **获取设备信息**：根据 `deviceLicenceId` 查询设备授权记录，获取 `licence` 和 `fingerprint`
+4. **密钥派生**：使用相同的 HKDF 参数派生 AES 密钥
+5. **解密数据**：使用 AES-256-GCM 解密（自动验证认证标签）
+6. **时间戳校验**：验证 `timestamp` 是否在合理范围内（防止重放攻击）
+7. **保存摘要**：将摘要信息保存到数据库
+
+## 九、常见错误和注意事项
+
+### 9.1 加密失败
+
+**可能原因**：
+1. **密钥派生错误**：确保使用正确的 HKDF 参数
+   - `ikm` = `licence + fingerprint`（直接字符串拼接）
+   - `salt` = `taskId`（必须与任务二维码中的 taskId 一致）
+   - `info` = `"inspection_report_encryption"`（固定值）
+   - `length` = `32` 字节
+
+2. **数据格式错误**：确保 JSON 格式正确
+   - 字段名和类型必须匹配
+   - 时间戳必须是数字类型（毫秒）
+
+3. **IV 生成错误**：确保使用安全的随机数生成器生成 12 字节 IV
+
+### 9.2 平台验证失败
+
+**可能原因**：
+1. **taskId 不匹配**：确保二维码中的 `taskId` 与任务二维码中的 `taskId` 一致
+2. **密钥不匹配**：确保 `licence` 和 `fingerprint` 与平台绑定时一致
+3. **时间戳过期**：平台会验证时间戳，确保时间戳在合理范围内
+4. **认证标签验证失败**：数据被篡改或密钥错误
+
+### 9.3 二维码生成失败
+
+**可能原因**：
+1. **内容过长**：如果加密数据过长，可能需要更高版本的二维码
+2. **JSON 格式错误**：确保 JSON 格式正确
+3. **字符编码错误**：确保使用 UTF-8 编码
+
+## 十、安全设计说明
+
+### 10.1 为什么使用 HKDF
+
+1. **密钥分离**：使用 `info` 参数区分不同用途的密钥
+2. **Salt 随机性**：使用 `taskId` 作为 salt，确保每个任务的密钥不同
+3. **密钥扩展**：HKDF 提供更好的密钥扩展性
+
+### 10.2 为什么第三方无法伪造
+
+1. **密钥绑定**：只有拥有正确 `licence + fingerprint` 的工具箱才能生成正确的密钥
+2. **任务绑定**：使用 `taskId` 作为 salt，确保密钥与特定任务绑定
+3. **认证加密**：GCM 模式提供认证加密，任何篡改都会导致解密失败
+4. **时间戳校验**：平台会验证时间戳，防止重放攻击
+
+### 10.3 密钥派生参数的重要性
+
+- **ikm**：`licence + fingerprint` 是设备唯一标识
+- **salt**：`taskId` 确保每个任务使用不同的密钥
+- **info**：`"inspection_report_encryption"` 区分不同用途的密钥
+- **length**：`32` 字节提供 256 位密钥强度
+
+## 十一、测试建议
+
+1. **单元测试**：
+   - 测试密钥派生是否正确
+   - 测试加密和解密是否匹配
+   - 测试 JSON 格式是否正确
+
+2. **集成测试**：
+   - 使用真实任务数据生成二维码
+   - App 扫描二维码并提交到平台
+   - 验证平台是否能正确解密和验证
+
+3. **边界测试**：
+   - 测试超长的摘要信息
+   - 测试特殊字符的处理
+   - 测试错误的 taskId 是否会导致解密失败
+
+## 十二、参考实现
+
+- **Python**：`hkdf` 库（HKDF）、`cryptography` 库（AES-GCM）、`qrcode` 库（二维码生成）
+- **Java/Kotlin**：BouncyCastle（HKDF）、JDK `javax.crypto`（AES-GCM）、ZXing 库（二维码生成）
+- **C#**：BouncyCastle.Net（HKDF）、`System.Security.Cryptography`（AES-GCM）、ZXing.Net 库（二维码生成）
+
+## 十三、联系支持
+
+如有问题，请联系平台技术支持团队获取：
+- 测试环境地址
+- 技术支持
+
--- a/docs/工具箱端-授权对接指南/工具箱端-设备授权二维码生成指南.md
+++ b/docs/工具箱端-授权对接指南/工具箱端-设备授权二维码生成指南.md
@@ -0,0 +1,601 @@
+# 工具箱端 - 设备授权二维码生成指南
+
+## 概述
+
+本文档说明工具箱端如何生成设备授权二维码，用于设备首次授权和绑定。App 扫描二维码后，会将加密的设备信息提交到平台完成授权校验和绑定。
+
+> ### UX 集成模式补充（当前项目实现）
+>
+> 调用前提：工具箱先调用 `config.setLicence` 写入本地 licence（fingerprint 由 UX 本机计算并持久化）。
+>
+> 在当前集成模式中，工具箱调用 UX 的 `crypto.encryptDeviceInfo`，直接传入
+> `platformPublicKey` 获取加密后的 Base64 密文。
+> UX 不保存业务设备实体，仅保存本机身份材料（licence/fingerprint）。
+
+## 一、业务流程
+
+```
+工具箱 → 生成设备信息 → RSA-OAEP加密 → Base64编码 → 生成二维码
+                                                          ↓
+App扫描二维码 → 提取加密数据 → 调用平台接口 → 平台解密验证 → 授权成功
+```
+
+## 二、设备信息准备
+
+### 2.1 设备信息字段
+
+工具箱需要准备以下设备信息：
+
+| 字段名 | 类型 | 说明 | 示例 |
+|--------|------|------|------|
+| `licence` | String | 设备授权码（工具箱唯一标识） | `"LIC-8F2A-XXXX"` |
+| `fingerprint` | String | 设备硬件指纹（设备唯一标识） | `"FP-2c91e9f3"` |
+
+### 2.2 生成设备信息 JSON
+
+将设备信息组装成 JSON 格式：
+
+```json
+{
+  "licence": "LIC-8F2A-XXXX",
+  "fingerprint": "FP-2c91e9f3"
+}
+```
+
+**重要说明**：
+- `licence` 和 `fingerprint` 必须是字符串类型
+- JSON 格式必须正确，不能有多余的逗号或格式错误
+- 建议使用标准的 JSON 库生成，避免手动拼接
+
+**伪代码示例**：
+```python
+import json
+
+device_info = {
+    "licence": "LIC-8F2A-XXXX",      # 工具箱授权码
+    "fingerprint": "FP-2c91e9f3"     # 设备硬件指纹
+}
+
+# 转换为 JSON 字符串
+device_info_json = json.dumps(device_info, ensure_ascii=False)
+# 结果: {"licence":"LIC-8F2A-XXXX","fingerprint":"FP-2c91e9f3"}
+```
+
+## 三、RSA-OAEP 加密
+
+### 3.1 加密算法
+
+使用 **RSA-OAEP** 非对称加密算法：
+
+- **算法名称**：`RSA/ECB/OAEPWithSHA-256AndMGF1Padding`
+- **密钥长度**：2048 位（推荐）
+- **填充方式**：OAEP with SHA-256 and MGF1
+- **加密方向**：使用**平台公钥**加密，平台使用私钥解密
+
+### 3.2 获取平台公钥
+
+平台公钥需要从平台获取，通常以 **Base64 编码**的字符串形式提供。
+
+**公钥格式**：
+- 格式：X.509 标准格式（DER 编码）
+- 存储：Base64 编码的字符串
+- 示例：`MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzDlZvMDVaL+fjl05Hi182JOAUAaN4gh9rOF+1NhKfO4J6e0HLy8lBuylp3A4xoTiyUejNm22h0dqAgDSPnY/xZR76POFTD1soHr2LaFCN8JAbQ96P8gE7wC9qpoTssVvIVRH7QbVd260J6eD0Szwcx9cg591RSN69pMpe5IVRi8T99Hhql6/wnZHORPr18eESLOY93jRskLzc0q18r68RRoTJiQf+9YC8ub5iKp7rCjVnPi1UbIYmXmL08tk5mksYA0NqWQAa1ofKxx/9tQtB9uTjhTxuTu94XU9jlGU87qaHZs+kpqa8CAbYYJFbSP1xHwoZzpU2jpw2aF22HBYxwIDAQAB`
+
+### 3.3 加密步骤
+
+1. **加载平台公钥**：从 Base64 字符串加载公钥对象
+2. **初始化加密器**：使用 `RSA/ECB/OAEPWithSHA-256AndMGF1Padding` 算法
+3. **加密数据**：使用公钥加密设备信息 JSON 字符串（UTF-8 编码）
+4. **Base64 编码**：将加密后的字节数组进行 Base64 编码
+
+### 3.4 Python 实现示例
+
+```python
+import base64
+import json
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.backends import default_backend
+
+def encrypt_device_info(licence: str, fingerprint: str, platform_public_key_base64: str) -> str:
+    """
+    使用平台公钥加密设备信息
+    
+    Args:
+        licence: 设备授权码
+        fingerprint: 设备硬件指纹
+        platform_public_key_base64: 平台公钥（Base64编码）
+    
+    Returns:
+        Base64编码的加密数据
+    """
+    # 1. 组装设备信息 JSON
+    device_info = {
+        "licence": licence,
+        "fingerprint": fingerprint
+    }
+    device_info_json = json.dumps(device_info, ensure_ascii=False)
+    
+    # 2. 加载平台公钥
+    public_key_bytes = base64.b64decode(platform_public_key_base64)
+    public_key = serialization.load_der_public_key(
+        public_key_bytes,
+        backend=default_backend()
+    )
+    
+    # 3. 使用 RSA-OAEP 加密
+    # OAEP padding with SHA-256 and MGF1
+    encrypted_bytes = public_key.encrypt(
+        device_info_json.encode('utf-8'),
+        padding.OAEP(
+            mgf=padding.MGF1(algorithm=hashes.SHA256()),
+            algorithm=hashes.SHA256(),
+            label=None
+        )
+    )
+    
+    # 4. Base64 编码
+    encrypted_base64 = base64.b64encode(encrypted_bytes).decode('utf-8')
+    
+    return encrypted_base64
+```
+
+### 3.5 Java/Kotlin 实现示例
+
+```kotlin
+import java.security.KeyFactory
+import java.security.PublicKey
+import java.security.spec.X509EncodedKeySpec
+import java.util.Base64
+import javax.crypto.Cipher
+import java.nio.charset.StandardCharsets
+
+object DeviceAuthorizationUtil {
+    
+    private const val CIPHER_ALGORITHM = "RSA/ECB/OAEPWithSHA-256AndMGF1Padding"
+    
+    /**
+     * 使用平台公钥加密设备信息
+     * 
+     * @param licence 设备授权码
+     * @param fingerprint 设备硬件指纹
+     * @param platformPublicKeyBase64 平台公钥（Base64编码）
+     * @return Base64编码的加密数据
+     */
+    fun encryptDeviceInfo(
+        licence: String,
+        fingerprint: String,
+        platformPublicKeyBase64: String
+    ): String {
+        // 1. 组装设备信息 JSON
+        val deviceInfo = mapOf(
+            "licence" to licence,
+            "fingerprint" to fingerprint
+        )
+        val deviceInfoJson = objectMapper.writeValueAsString(deviceInfo)
+        
+        // 2. 加载平台公钥
+        val publicKeyBytes = Base64.getDecoder().decode(platformPublicKeyBase64)
+        val keySpec = X509EncodedKeySpec(publicKeyBytes)
+        val keyFactory = KeyFactory.getInstance("RSA")
+        val publicKey = keyFactory.generatePublic(keySpec)
+        
+        // 3. 使用 RSA-OAEP 加密
+        val cipher = Cipher.getInstance(CIPHER_ALGORITHM)
+        cipher.init(Cipher.ENCRYPT_MODE, publicKey)
+        val encryptedBytes = cipher.doFinal(deviceInfoJson.toByteArray(StandardCharsets.UTF_8))
+        
+        // 4. Base64 编码
+        return Base64.getEncoder().encodeToString(encryptedBytes)
+    }
+}
+```
+
+### 3.6 C# 实现示例
+
+```csharp
+using System;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+
+public class DeviceAuthorizationUtil
+{
+    private const string CipherAlgorithm = "RSA/ECB/OAEPWithSHA-256AndMGF1Padding";
+    
+    /// <summary>
+    /// 使用平台公钥加密设备信息
+    /// </summary>
+    public static string EncryptDeviceInfo(
+        string licence, 
+        string fingerprint, 
+        string platformPublicKeyBase64)
+    {
+        // 1. 组装设备信息 JSON
+        var deviceInfo = new
+        {
+            licence = licence,
+            fingerprint = fingerprint
+        };
+        var deviceInfoJson = JsonSerializer.Serialize(deviceInfo);
+        
+        // 2. 加载平台公钥
+        var publicKeyBytes = Convert.FromBase64String(platformPublicKeyBase64);
+        using var rsa = RSA.Create();
+        rsa.ImportSubjectPublicKeyInfo(publicKeyBytes, out _);
+        
+        // 3. 使用 RSA-OAEP 加密
+        var encryptedBytes = rsa.Encrypt(
+            Encoding.UTF8.GetBytes(deviceInfoJson),
+            RSAEncryptionPadding.OaepSHA256
+        );
+        
+        // 4. Base64 编码
+        return Convert.ToBase64String(encryptedBytes);
+    }
+}
+```
+
+## 四、生成二维码
+
+### 4.1 二维码内容
+
+二维码内容就是加密后的 **Base64 编码字符串**（不是 JSON 格式）。
+
+**示例**：
+```
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzDlZvMDVaL+fjl05Hi182JOAUAaN4gh9rOF+1NhKfO4J6e0HLy8lBuylp3A4xoTiyUejNm22h0dqAgDSPnY/xZR76POFTD1soHr2LaFCN8JAbQ96P8gE7wC9qpoTssVvIVRH7QbVd260J6eD0Szwcx9cg591RSN69pMpe5IVRi8T99Hhql6/wnZHORPr18eESLOY93jRskLzc0q18r68RRoTJiQf+9YC8ub5iKp7rCjVnPi1UbIYmXmL08tk5mksYA0NqWQAa1ofKxx/9tQtB9uTjhTxuTu94XU9jlGU87qaHZs+kpqa8CAbYYJFbSP1xHwoZzpU2jpw2aF22HBYxwIDAQAB...
+```
+
+### 4.2 二维码生成
+
+使用标准的二维码生成库生成二维码图片。
+
+**Python 示例（使用 qrcode 库）**：
+```python
+import qrcode
+from PIL import Image
+
+def generate_qr_code(encrypted_data: str, output_path: str = "device_qr.png"):
+    """
+    生成设备授权二维码
+    
+    Args:
+        encrypted_data: Base64编码的加密数据
+        output_path: 二维码图片保存路径
+    """
+    qr = qrcode.QRCode(
+        version=1,                      # 控制二维码大小（1-40）
+        error_correction=qrcode.constants.ERROR_CORRECT_M,  # 错误纠正级别
+        box_size=10,                    # 每个小方块的像素数
+        border=4,                       # 边框的厚度
+    )
+    qr.add_data(encrypted_data)
+    qr.make(fit=True)
+    
+    # 创建二维码图片
+    img = qr.make_image(fill_color="black", back_color="white")
+    img.save(output_path)
+    
+    print(f"二维码已生成: {output_path}")
+```
+
+**Java/Kotlin 示例（使用 ZXing 库）**：
+```kotlin
+import com.google.zxing.BarcodeFormat
+import com.google.zxing.EncodeHintType
+import com.google.zxing.qrcode.QRCodeWriter
+import com.google.zxing.qrcode.decoder.ErrorCorrectionLevel
+import java.awt.image.BufferedImage
+import javax.imageio.ImageIO
+import java.io.File
+
+fun generateQRCode(encryptedData: String, outputPath: String = "device_qr.png") {
+    val hints = hashMapOf<EncodeHintType, Any>().apply {
+        put(EncodeHintType.ERROR_CORRECTION, ErrorCorrectionLevel.M)
+        put(EncodeHintType.CHARACTER_SET, "UTF-8")
+        put(EncodeHintType.MARGIN, 1)
+    }
+    
+    val writer = QRCodeWriter()
+    val bitMatrix = writer.encode(encryptedData, BarcodeFormat.QR_CODE, 300, 300, hints)
+    
+    val width = bitMatrix.width
+    val height = bitMatrix.height
+    val image = BufferedImage(width, height, BufferedImage.TYPE_INT_RGB)
+    
+    for (x in 0 until width) {
+        for (y in 0 until height) {
+            image.setRGB(x, y, if (bitMatrix[x, y]) 0x000000 else 0xFFFFFF)
+        }
+    }
+    
+    ImageIO.write(image, "PNG", File(outputPath))
+    println("二维码已生成: $outputPath")
+}
+```
+
+## 五、完整流程示例
+
+### 5.1 Python 完整示例
+
+```python
+import json
+import base64
+import qrcode
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.backends import default_backend
+
+def generate_device_authorization_qr(
+    licence: str,
+    fingerprint: str,
+    platform_public_key_base64: str,
+    qr_output_path: str = "device_qr.png"
+) -> str:
+    """
+    生成设备授权二维码
+    
+    Args:
+        licence: 设备授权码
+        fingerprint: 设备硬件指纹
+        platform_public_key_base64: 平台公钥（Base64编码）
+        qr_output_path: 二维码图片保存路径
+    
+    Returns:
+        加密后的Base64字符串（二维码内容）
+    """
+    # 1. 组装设备信息 JSON
+    device_info = {
+        "licence": licence,
+        "fingerprint": fingerprint
+    }
+    device_info_json = json.dumps(device_info, ensure_ascii=False)
+    print(f"设备信息 JSON: {device_info_json}")
+    
+    # 2. 加载平台公钥
+    public_key_bytes = base64.b64decode(platform_public_key_base64)
+    public_key = serialization.load_der_public_key(
+        public_key_bytes,
+        backend=default_backend()
+    )
+    
+    # 3. 使用 RSA-OAEP 加密
+    encrypted_bytes = public_key.encrypt(
+        device_info_json.encode('utf-8'),
+        padding.OAEP(
+            mgf=padding.MGF1(algorithm=hashes.SHA256()),
+            algorithm=hashes.SHA256(),
+            label=None
+        )
+    )
+    
+    # 4. Base64 编码
+    encrypted_base64 = base64.b64encode(encrypted_bytes).decode('utf-8')
+    print(f"加密后的 Base64: {encrypted_base64[:100]}...")  # 只显示前100个字符
+    
+    # 5. 生成二维码
+    qr = qrcode.QRCode(
+        version=1,
+        error_correction=qrcode.constants.ERROR_CORRECT_M,
+        box_size=10,
+        border=4,
+    )
+    qr.add_data(encrypted_base64)
+    qr.make(fit=True)
+    
+    img = qr.make_image(fill_color="black", back_color="white")
+    img.save(qr_output_path)
+    print(f"二维码已生成: {qr_output_path}")
+    
+    return encrypted_base64
+
+# 使用示例
+if __name__ == "__main__":
+    # 平台公钥（示例，实际使用时需要从平台获取）
+    platform_public_key = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzDlZvMDVaL+fjl05Hi182JOAUAaN4gh9rOF+1NhKfO4J6e0HLy8lBuylp3A4xoTiyUejNm22h0dqAgDSPnY/xZR76POFTD1soHr2LaFCN8JAbQ96P8gE7wC9qpoTssVvIVRH7QbVd260J6eD0Szwcx9cg591RSN69pMpe5IVRi8T99Hhql6/wnZHORPr18eESLOY93jRskLzc0q18r68RRoTJiQf+9YC8ub5iKp7rCjVnPi1UbIYmXmL08tk5mksYA0NqWQAa1ofKxx/9tQtB9uTjhTxuTu94XU9jlGU87qaHZs+kpqa8CAbYYJFbSP1xHwoZzpU2jpw2aF22HBYxwIDAQAB"
+    
+    # 设备信息
+    licence = "LIC-8F2A-XXXX"
+    fingerprint = "FP-2c91e9f3"
+    
+    # 生成二维码
+    encrypted_data = generate_device_authorization_qr(
+        licence=licence,
+        fingerprint=fingerprint,
+        platform_public_key_base64=platform_public_key,
+        qr_output_path="device_authorization_qr.png"
+    )
+    
+    print(f"\n二维码内容（加密后的Base64）:\n{encrypted_data}")
+```
+
+### 5.2 Java/Kotlin 完整示例
+
+```kotlin
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.google.zxing.BarcodeFormat
+import com.google.zxing.EncodeHintType
+import com.google.zxing.qrcode.QRCodeWriter
+import com.google.zxing.qrcode.decoder.ErrorCorrectionLevel
+import java.awt.image.BufferedImage
+import java.security.KeyFactory
+import java.security.PublicKey
+import java.security.spec.X509EncodedKeySpec
+import java.util.Base64
+import javax.crypto.Cipher
+import javax.imageio.ImageIO
+import java.io.File
+import java.nio.charset.StandardCharsets
+
+object DeviceAuthorizationQRGenerator {
+    
+    private const val CIPHER_ALGORITHM = "RSA/ECB/OAEPWithSHA-256AndMGF1Padding"
+    private val objectMapper = ObjectMapper()
+    
+    /**
+     * 生成设备授权二维码
+     */
+    fun generateDeviceAuthorizationQR(
+        licence: String,
+        fingerprint: String,
+        platformPublicKeyBase64: String,
+        qrOutputPath: String = "device_qr.png"
+    ): String {
+        // 1. 组装设备信息 JSON
+        val deviceInfo = mapOf(
+            "licence" to licence,
+            "fingerprint" to fingerprint
+        )
+        val deviceInfoJson = objectMapper.writeValueAsString(deviceInfo)
+        println("设备信息 JSON: $deviceInfoJson")
+        
+        // 2. 加载平台公钥
+        val publicKeyBytes = Base64.getDecoder().decode(platformPublicKeyBase64)
+        val keySpec = X509EncodedKeySpec(publicKeyBytes)
+        val keyFactory = KeyFactory.getInstance("RSA")
+        val publicKey = keyFactory.generatePublic(keySpec)
+        
+        // 3. 使用 RSA-OAEP 加密
+        val cipher = Cipher.getInstance(CIPHER_ALGORITHM)
+        cipher.init(Cipher.ENCRYPT_MODE, publicKey)
+        val encryptedBytes = cipher.doFinal(deviceInfoJson.toByteArray(StandardCharsets.UTF_8))
+        
+        // 4. Base64 编码
+        val encryptedBase64 = Base64.getEncoder().encodeToString(encryptedBytes)
+        println("加密后的 Base64: ${encryptedBase64.take(100)}...")
+        
+        // 5. 生成二维码
+        val hints = hashMapOf<EncodeHintType, Any>().apply {
+            put(EncodeHintType.ERROR_CORRECTION, ErrorCorrectionLevel.M)
+            put(EncodeHintType.CHARACTER_SET, "UTF-8")
+            put(EncodeHintType.MARGIN, 1)
+        }
+        
+        val writer = QRCodeWriter()
+        val bitMatrix = writer.encode(encryptedBase64, BarcodeFormat.QR_CODE, 300, 300, hints)
+        
+        val width = bitMatrix.width
+        val height = bitMatrix.height
+        val image = BufferedImage(width, height, BufferedImage.TYPE_INT_RGB)
+        
+        for (x in 0 until width) {
+            for (y in 0 until height) {
+                image.setRGB(x, y, if (bitMatrix[x, y]) 0x000000 else 0xFFFFFF)
+            }
+        }
+        
+        ImageIO.write(image, "PNG", File(qrOutputPath))
+        println("二维码已生成: $qrOutputPath")
+        
+        return encryptedBase64
+    }
+}
+
+// 使用示例
+fun main() {
+    // 平台公钥（示例，实际使用时需要从平台获取）
+    val platformPublicKey = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzDlZvMDVaL+fjl05Hi182JOAUAaN4gh9rOF+1NhKfO4J6e0HLy8lBuylp3A4xoTiyUejNm22h0dqAgDSPnY/xZR76POFTD1soHr2LaFCN8JAbQ96P8gE7wC9qpoTssVvIVRH7QbVd260J6eD0Szwcx9cg591RSN69pMpe5IVRi8T99Hhql6/wnZHORPr18eESLOY93jRskLzc0q18r68RRoTJiQf+9YC8ub5iKp7rCjVnPi1UbIYmXmL08tk5mksYA0NqWQAa1ofKxx/9tQtB9uTjhTxuTu94XU9jlGU87qaHZs+kpqa8CAbYYJFbSP1xHwoZzpU2jpw2aF22HBYxwIDAQAB"
+    
+    // 设备信息
+    val licence = "LIC-8F2A-XXXX"
+    val fingerprint = "FP-2c91e9f3"
+    
+    // 生成二维码
+    val encryptedData = DeviceAuthorizationQRGenerator.generateDeviceAuthorizationQR(
+        licence = licence,
+        fingerprint = fingerprint,
+        platformPublicKeyBase64 = platformPublicKey,
+        qrOutputPath = "device_authorization_qr.png"
+    )
+    
+    println("\n二维码内容（加密后的Base64）:\n$encryptedData")
+}
+```
+
+## 六、平台端验证流程
+
+平台端会按以下流程验证：
+
+1. **接收请求**：App 扫描二维码后，将 `encryptedDeviceInfo` 和 `appid` 提交到平台
+2. **RSA-OAEP 解密**：使用平台私钥解密 `encryptedDeviceInfo`
+3. **提取设备信息**：从解密后的 JSON 中提取 `licence` 和 `fingerprint`
+4. **设备验证**：
+   - 检查 `filing_device_licence` 表中是否存在该 `licence`
+   - 如果存在，验证 `fingerprint` 是否匹配
+   - 如果 `fingerprint` 不匹配，记录非法授权日志并返回错误
+5. **App 绑定**：检查 `filing_app_licence` 表中是否存在绑定关系
+   - 如果不存在，创建新的绑定记录
+   - 如果已存在，返回已绑定信息
+6. **返回响应**：返回 `deviceLicenceId` 和 `licence`
+
+## 七、常见错误和注意事项
+
+### 7.1 加密失败
+
+**可能原因**：
+1. **公钥格式错误**：确保使用正确的 Base64 编码的公钥
+2. **算法不匹配**：必须使用 `RSA/ECB/OAEPWithSHA-256AndMGF1Padding`
+3. **数据长度超限**：RSA-2048 最多加密 245 字节（设备信息 JSON 通常不会超过）
+4. **字符编码错误**：确保使用 UTF-8 编码
+
+### 7.2 二维码扫描失败
+
+**可能原因**：
+1. **二维码内容过长**：如果加密后的数据过长，可能需要使用更高版本的二维码（version）
+2. **错误纠正级别过低**：建议使用 `ERROR_CORRECT_M` 或更高
+3. **二维码图片质量差**：确保二维码图片清晰，有足够的对比度
+
+### 7.3 平台验证失败
+
+**可能原因**：
+1. **licence 已存在但 fingerprint 不匹配**：设备被替换或授权码被复用
+2. **JSON 格式错误**：确保 JSON 格式正确，字段名和类型匹配
+3. **加密数据损坏**：确保 Base64 编码和解码正确
+
+## 八、安全设计说明
+
+### 8.1 为什么使用 RSA-OAEP
+
+1. **非对称加密**：只有平台拥有私钥，可以解密数据
+2. **OAEP 填充**：提供更好的安全性，防止某些攻击
+3. **SHA-256**：使用强哈希算法，提供更好的安全性
+
+### 8.2 为什么第三方无法伪造
+
+1. **只有平台能解密**：第三方无法获取平台私钥，无法解密数据
+2. **fingerprint 验证**：平台会验证硬件指纹，防止授权码被复用
+3. **非法授权日志**：平台会记录所有非法授权尝试
+
+## 九、测试建议
+
+1. **单元测试**：
+   - 测试 JSON 生成是否正确
+   - 测试加密和解密是否匹配
+   - 测试 Base64 编码和解码是否正确
+
+2. **集成测试**：
+   - 使用真实平台公钥生成二维码
+   - App 扫描二维码并提交到平台
+   - 验证平台是否能正确解密和验证
+
+3. **边界测试**：
+   - 测试超长的 licence 或 fingerprint
+   - 测试特殊字符的处理
+   - 测试错误的公钥格式
+
+## 十、参考实现
+
+- **Python**：`cryptography` 库（RSA 加密）、`qrcode` 库（二维码生成）
+- **Java/Kotlin**：JDK `javax.crypto`（RSA 加密）、ZXing 库（二维码生成）
+- **C#**：`System.Security.Cryptography`（RSA 加密）、ZXing.Net 库（二维码生成）
+
+## 十一、联系支持
+
+如有问题，请联系平台技术支持团队获取：
+- 平台公钥（Base64 编码）
+- 测试环境地址
+- 技术支持
+
--- a/package.json
+++ b/package.json
@@ -22,45 +22,48 @@
    "typecheck": "turbo run typecheck"
  },
  "devDependencies": {
-    "@biomejs/biome": "^2.4.8",
-    "turbo": "^2.8.20",
+    "@biomejs/biome": "^2.4.5",
+    "turbo": "^2.8.13",
    "typescript": "^5.9.3"
  },
  "catalog": {
-    "@orpc/client": "^1.13.9",
-    "@orpc/contract": "^1.13.9",
-    "@orpc/openapi": "^1.13.9",
-    "@orpc/server": "^1.13.9",
-    "@orpc/tanstack-query": "^1.13.9",
-    "@orpc/zod": "^1.13.9",
+    "@orpc/client": "^1.13.6",
+    "@orpc/contract": "^1.13.6",
+    "@orpc/openapi": "^1.13.6",
+    "@orpc/server": "^1.13.6",
+    "@orpc/tanstack-query": "^1.13.6",
+    "@orpc/zod": "^1.13.6",
    "@t3-oss/env-core": "^0.13.10",
-    "@tailwindcss/vite": "^4.2.2",
-    "@tanstack/devtools-vite": "^0.5.5",
-    "@tanstack/react-devtools": "^0.9.13",
-    "@tanstack/react-query": "^5.94.4",
-    "@tanstack/react-query-devtools": "^5.94.4",
-    "@tanstack/react-router": "^1.168.1",
-    "@tanstack/react-router-devtools": "^1.166.10",
-    "@tanstack/react-router-ssr-query": "^1.166.10",
-    "@tanstack/react-start": "^1.167.2",
-    "@types/bun": "^1.3.11",
-    "@types/node": "^24.12.0",
-    "@vitejs/plugin-react": "^5.2.0",
+    "@tailwindcss/vite": "^4.2.1",
+    "@tanstack/devtools-vite": "^0.5.3",
+    "@tanstack/react-devtools": "^0.9.9",
+    "@tanstack/react-query": "^5.90.21",
+    "@tanstack/react-query-devtools": "^5.91.3",
+    "@tanstack/react-router": "^1.166.2",
+    "@tanstack/react-router-devtools": "^1.166.2",
+    "@tanstack/react-router-ssr-query": "^1.166.2",
+    "@tanstack/react-start": "^1.166.2",
+    "@types/bun": "^1.3.10",
+    "@types/node": "^24.11.0",
+    "@vitejs/plugin-react": "^5.1.4",
    "babel-plugin-react-compiler": "^1.0.0",
    "drizzle-kit": "1.0.0-beta.15-859cf75",
    "drizzle-orm": "1.0.0-beta.15-859cf75",
    "electron": "^34.0.0",
    "electron-builder": "^26.8.1",
    "electron-vite": "^5.0.0",
-    "motion": "^12.38.0",
-    "nitro": "npm:nitro-nightly@3.0.1-20260320-182900-2218d454",
-    "postgres": "^3.4.8",
+    "jszip": "^3.10.1",
+    "motion": "^12.35.0",
+    "nitro": "npm:nitro-nightly@3.0.1-20260227-181935-bfbb207c",
+    "openpgp": "^6.0.1",
    "react": "^19.2.4",
    "react-dom": "^19.2.4",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.1",
    "tree-kill": "^1.2.2",
    "uuid": "^13.0.0",
-    "vite": "^8.0.1",
+    "vite": "^8.0.0-beta.16",
+    "vite-tsconfig-paths": "^6.1.1",
+    "systeminformation": "^5.31.3",
    "zod": "^4.3.6"
  },
  "overrides": {
--- a/packages/crypto/package.json
+++ b/packages/crypto/package.json
@@ -0,0 +1,18 @@
+{
+  "name": "@furtherverse/crypto",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "node-forge": "^1.3.3",
+    "openpgp": "catalog:"
+  },
+  "devDependencies": {
+    "@furtherverse/tsconfig": "workspace:*",
+    "@types/bun": "catalog:",
+    "@types/node-forge": "^1.3.14"
+  }
+}
--- a/packages/crypto/src/aes-gcm.ts
+++ b/packages/crypto/src/aes-gcm.ts
@@ -0,0 +1,53 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
+
+const GCM_IV_LENGTH = 12 // 96 bits
+const GCM_TAG_LENGTH = 16 // 128 bits
+const ALGORITHM = 'aes-256-gcm'
+
+/**
+ * AES-256-GCM encrypt.
+ *
+ * Output format (before Base64): [IV (12 bytes)] + [ciphertext] + [auth tag (16 bytes)]
+ *
+ * @param plaintext - UTF-8 string to encrypt
+ * @param key - 32-byte AES key
+ * @returns Base64-encoded encrypted data
+ */
+export const aesGcmEncrypt = (plaintext: string, key: Buffer): string => {
+  const iv = randomBytes(GCM_IV_LENGTH)
+  const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: GCM_TAG_LENGTH })
+
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()])
+  const tag = cipher.getAuthTag()
+
+  // Layout: IV + ciphertext + tag
+  const combined = Buffer.concat([iv, encrypted, tag])
+  return combined.toString('base64')
+}
+
+/**
+ * AES-256-GCM decrypt.
+ *
+ * Input format (after Base64 decode): [IV (12 bytes)] + [ciphertext] + [auth tag (16 bytes)]
+ *
+ * @param encryptedBase64 - Base64-encoded encrypted data
+ * @param key - 32-byte AES key
+ * @returns Decrypted UTF-8 string
+ */
+export const aesGcmDecrypt = (encryptedBase64: string, key: Buffer): string => {
+  const data = Buffer.from(encryptedBase64, 'base64')
+
+  if (data.length < GCM_IV_LENGTH + GCM_TAG_LENGTH) {
+    throw new Error('Encrypted data too short: must contain IV + tag at minimum')
+  }
+
+  const iv = data.subarray(0, GCM_IV_LENGTH)
+  const tag = data.subarray(data.length - GCM_TAG_LENGTH)
+  const ciphertext = data.subarray(GCM_IV_LENGTH, data.length - GCM_TAG_LENGTH)
+
+  const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: GCM_TAG_LENGTH })
+  decipher.setAuthTag(tag)
+
+  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()])
+  return decrypted.toString('utf-8')
+}
--- a/packages/crypto/src/hash.ts
+++ b/packages/crypto/src/hash.ts
@@ -0,0 +1,15 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * Compute SHA-256 hash and return raw Buffer.
+ */
+export const sha256 = (data: string | Buffer): Buffer => {
+  return createHash('sha256').update(data).digest()
+}
+
+/**
+ * Compute SHA-256 hash and return lowercase hex string.
+ */
+export const sha256Hex = (data: string | Buffer): string => {
+  return createHash('sha256').update(data).digest('hex')
+}
--- a/packages/crypto/src/hkdf.ts
+++ b/packages/crypto/src/hkdf.ts
@@ -0,0 +1,15 @@
+import { hkdfSync } from 'node:crypto'
+
+/**
+ * Derive a key using HKDF-SHA256.
+ *
+ * @param ikm - Input keying material (string, will be UTF-8 encoded)
+ * @param salt - Salt value (string, will be UTF-8 encoded)
+ * @param info - Info/context string (will be UTF-8 encoded)
+ * @param length - Output key length in bytes (default: 32 for AES-256)
+ * @returns Derived key as Buffer
+ */
+export const hkdfSha256 = (ikm: string, salt: string, info: string, length = 32): Buffer => {
+  const derived = hkdfSync('sha256', ikm, salt, info, length)
+  return Buffer.from(derived)
+}
--- a/packages/crypto/src/hmac.ts
+++ b/packages/crypto/src/hmac.ts
@@ -0,0 +1,23 @@
+import { createHmac } from 'node:crypto'
+
+/**
+ * Compute HMAC-SHA256 and return Base64-encoded signature.
+ *
+ * @param key - HMAC key (Buffer)
+ * @param data - Data to sign (UTF-8 string)
+ * @returns Base64-encoded HMAC-SHA256 signature
+ */
+export const hmacSha256Base64 = (key: Buffer, data: string): string => {
+  return createHmac('sha256', key).update(data, 'utf-8').digest('base64')
+}
+
+/**
+ * Compute HMAC-SHA256 and return raw Buffer.
+ *
+ * @param key - HMAC key (Buffer)
+ * @param data - Data to sign (UTF-8 string)
+ * @returns HMAC-SHA256 digest as Buffer
+ */
+export const hmacSha256 = (key: Buffer, data: string): Buffer => {
+  return createHmac('sha256', key).update(data, 'utf-8').digest()
+}
--- a/packages/crypto/src/index.ts
+++ b/packages/crypto/src/index.ts
@@ -0,0 +1,6 @@
+export { aesGcmDecrypt, aesGcmEncrypt } from './aes-gcm'
+export { sha256, sha256Hex } from './hash'
+export { hkdfSha256 } from './hkdf'
+export { hmacSha256, hmacSha256Base64 } from './hmac'
+export { generatePgpKeyPair, pgpSignDetached, pgpVerifyDetached } from './pgp'
+export { rsaOaepEncrypt } from './rsa-oaep'
--- a/packages/crypto/src/pgp.ts
+++ b/packages/crypto/src/pgp.ts
@@ -0,0 +1,75 @@
+import * as openpgp from 'openpgp'
+
+/**
+ * Generate an OpenPGP RSA key pair.
+ *
+ * @param name - User name for the key
+ * @param email - User email for the key
+ * @returns ASCII-armored private and public keys
+ */
+export const generatePgpKeyPair = async (
+  name: string,
+  email: string,
+): Promise<{ privateKey: string; publicKey: string }> => {
+  const { privateKey, publicKey } = await openpgp.generateKey({
+    type: 'rsa',
+    rsaBits: 2048,
+    userIDs: [{ name, email }],
+    format: 'armored',
+  })
+
+  return { privateKey, publicKey }
+}
+
+/**
+ * Create a detached OpenPGP signature for the given data.
+ *
+ * @param data - Raw data to sign (Buffer or Uint8Array)
+ * @param armoredPrivateKey - ASCII-armored private key
+ * @returns ASCII-armored detached signature (signature.asc content)
+ */
+export const pgpSignDetached = async (data: Uint8Array, armoredPrivateKey: string): Promise<string> => {
+  const privateKey = await openpgp.readPrivateKey({ armoredKey: armoredPrivateKey })
+  const message = await openpgp.createMessage({ binary: data })
+
+  const signature = await openpgp.sign({
+    message,
+    signingKeys: privateKey,
+    detached: true,
+    format: 'armored',
+  })
+
+  return signature as string
+}
+
+/**
+ * Verify a detached OpenPGP signature.
+ *
+ * @param data - Original data (Buffer or Uint8Array)
+ * @param armoredSignature - ASCII-armored detached signature
+ * @param armoredPublicKey - ASCII-armored public key
+ * @returns true if signature is valid
+ */
+export const pgpVerifyDetached = async (
+  data: Uint8Array,
+  armoredSignature: string,
+  armoredPublicKey: string,
+): Promise<boolean> => {
+  const publicKey = await openpgp.readKey({ armoredKey: armoredPublicKey })
+  const signature = await openpgp.readSignature({ armoredSignature })
+  const message = await openpgp.createMessage({ binary: data })
+
+  const verificationResult = await openpgp.verify({
+    message,
+    signature,
+    verificationKeys: publicKey,
+  })
+
+  const { verified } = verificationResult.signatures[0]!
+  try {
+    await verified
+    return true
+  } catch {
+    return false
+  }
+}
--- a/packages/crypto/src/rsa-oaep.ts
+++ b/packages/crypto/src/rsa-oaep.ts
@@ -0,0 +1,32 @@
+import forge from 'node-forge'
+
+/**
+ * RSA-OAEP encrypt with platform public key.
+ *
+ * Matches Java's {@code Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding")}
+ * with **default SunJCE parameters**:
+ *
+ * | Parameter | Value  |
+ * |-----------|--------|
+ * | OAEP hash | SHA-256|
+ * | MGF1 hash | SHA-1  |
+ *
+ * Node.js `crypto.publicEncrypt({ oaepHash })` ties both hashes together,
+ * so we use `node-forge` which allows independent configuration.
+ *
+ * @param plaintext - UTF-8 string to encrypt
+ * @param publicKeyBase64 - Platform RSA public key (X.509 / SPKI DER, Base64)
+ * @returns Base64-encoded ciphertext
+ */
+export const rsaOaepEncrypt = (plaintext: string, publicKeyBase64: string): string => {
+  const derBytes = forge.util.decode64(publicKeyBase64)
+  const asn1 = forge.asn1.fromDer(derBytes)
+  const publicKey = forge.pki.publicKeyFromAsn1(asn1) as forge.pki.rsa.PublicKey
+
+  const encrypted = publicKey.encrypt(plaintext, 'RSA-OAEP', {
+    md: forge.md.sha256.create(),
+    mgf1: { md: forge.md.sha1.create() },
+  })
+
+  return forge.util.encode64(encrypted)
+}
--- a/packages/crypto/tsconfig.json
+++ b/packages/crypto/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "extends": "@furtherverse/tsconfig/bun.json",
+  "compilerOptions": {
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
Author	SHA1	Message	Date
imbytecat	8be32bf15b	refactor(server): extract ZIP security checks into reusable safe-zip module	2026-03-06 16:51:33 +08:00
imbytecat	1110edc974	docs: remove outdated UX API docs (superseded by OpenAPI /api/docs)	2026-03-06 16:41:15 +08:00
imbytecat	a5fd9c1833	fix(crypto): replace deprecated .passthrough() with .loose() (Zod 4)	2026-03-06 16:40:46 +08:00
imbytecat	3d27f8ccfa	refactor(crypto): use Zod safeParse for summary.json validation instead of manual checks	2026-03-06 16:39:38 +08:00
imbytecat	4d64cfb93d	docs: 添加管理平台标准加密算法 Kotlin 参考实现	2026-03-06 15:34:04 +08:00
imbytecat	2651ec0835	fix(crypto): 修复 RSA-OAEP 加密与 Java SunJCE 的 MGF1 哈希不兼容问题 Node.js publicEncrypt({ oaepHash }) 会将 OAEP hash 和 MGF1 hash 绑定为同一算法，而 Java OAEPWithSHA-256AndMGF1Padding 默认使用 SHA-256(OAEP) + SHA-1(MGF1)。改用 node-forge 独立配置两个哈希，确保密文可被管理平台正确解密。	2026-03-06 15:33:07 +08:00
imbytecat	122dead202	refactor(server): 简化 signAndPackReport 接口，PGP 私钥本地存储、summary.json 从 ZIP 提取 - DB schema 新增 pgpPrivateKey 字段 - 新增 config.setPgpPrivateKey 接口，私钥与设备绑定 - signAndPackReport 只需传 rawZip，signingContext 自动从 summary.json 派生 - configOutput 新增 hasPgpPrivateKey 字段 - 抽取 requireIdentity 减少重复校验代码	2026-03-06 14:55:12 +08:00
imbytecat	ec41a4cfc7	docs(contract): 为所有 API 的 input/output 添加 OpenAPI examples，便于厂商测试	2026-03-06 14:37:50 +08:00
imbytecat	86754f73c1	docs(contract): 优化 API summary/description，对齐工具箱端对接指南文档	2026-03-06 14:30:09 +08:00
imbytecat	9296ab31e4	fix(server): 每次启动重新计算设备特征码，环境变化时自动更新	2026-03-06 11:28:14 +08:00
imbytecat	72d1727eb6	refactor(server): 设备特征码直接使用完整 SHA-256，移除 FP- 前缀和截断	2026-03-06 11:23:52 +08:00
imbytecat	aabd60e619	refactor(server): 使用 systeminformation 替代手动采集生成设备特征码硬件级 SMBIOS 标识（uuid/serial/model/manufacturer）跨平台稳定，不再依赖 Linux 独有的 machine-id 和易变的 OS release/内存/MAC 地址。	2026-03-06 11:16:17 +08:00
imbytecat	cdb3298f6d	refactor(db): 删除去业务化后残留的 device/task 表定义	2026-03-06 10:39:09 +08:00
imbytecat	060ddd8e12	docs: 更新 UX 本地身份配置流程与对接说明	2026-03-06 10:02:56 +08:00
imbytecat	b50d2eaf10	refactor(server): 重构为本地身份配置 + 底层 crypto 能力接口	2026-03-06 10:02:26 +08:00
imbytecat	46e2c94faf	fix(db): 修正 drizzle-kit 在 Bun SQLite 下的配置与脚本	2026-03-05 16:59:25 +08:00
imbytecat	b1062a5aed	refactor(api): signAndPackReport 直接返回签名 ZIP 文件	2026-03-05 16:58:59 +08:00
imbytecat	b193759e90	docs: 新增第三方 OpenAPI 对接指南	2026-03-05 16:44:01 +08:00
imbytecat	eb941c06c0	docs(api): 补全 OpenAPI 元数据与字段描述	2026-03-05 16:43:53 +08:00
imbytecat	eb2f6554b2	docs: 更新 signAndPackReport 为 multipart 文件上传说明	2026-03-05 16:32:49 +08:00
imbytecat	58d57fa148	refactor(server): 使用 multipart File 替代报告 ZIP 的 base64 上传	2026-03-05 16:32:41 +08:00
imbytecat	509860bba8	docs: 补充 UX 集成模式与授权对接说明	2026-03-05 16:24:21 +08:00
imbytecat	4e7c4e1aa5	feat(server): 实现设备授权与报告 ZIP 签名打包接口	2026-03-05 16:24:10 +08:00
imbytecat	8261409d7d	refactor(server): 切换 SQLite 并重建设备/任务表结构	2026-03-05 16:23:30 +08:00
imbytecat	d2eb98d612	feat: 新增共享加密包并引入 ZIP/PGP 依赖	2026-03-05 16:23:13 +08:00