# key-manager

**Repository Path**: nowsun/key-manager

## Basic Information

- **Project Name**: key-manager
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-12
- **Last Updated**: 2026-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KM 密码管理小工具：设计说明

本文档以当前 `km.html` 的实现为准，并整合最初的设计目标：使用单文件网页管理个人密码，以“大类—小类—密码条目”组织数据，保持简洁、低依赖且便于本地使用。后续维护若与早期设想不同，应优先参考“当前设计”和实际代码。

## 使用范围

本软件是一个HTML文件，打开浏览器即可运行，放在浏览器收藏栏，当登录网站/邮箱/远程等需要密码时方便取用。

![KM 界面预览：左侧分类栏与密码卡片](screenshot.png)

## 1. 产品定位

KM 是一个轻量、单页面、无需后端服务的个人密码管理小工具。整个应用集中在 `km.html` 中，由原生 HTML、CSS 和 JavaScript 实现，不依赖前端框架或服务器。数据默认保存在当前浏览器的 `localStorage`，用户可手动导入或导出 JSON 格式的 `km.ini` 备份；在支持的浏览器中也可以打开 `km.ini` 后把改动直接写回原文件。

设计目标是让个人账号资料便于分类、查找、查看和复制，同时尽量减少部署和使用成本。

## 2. 软件风格

- **简洁、清爽、工具型**：以浅灰背景、白色内容面板、细边框和适度圆角构成界面，避免装饰干扰资料管理。
- **蓝色作为主要操作色**：用于选中状态、主要按钮、链接和焦点反馈；红色用于删除等危险操作及待备份提醒。
- **低干扰的信息层级**：分类与字段标签使用较浅的辅助色，条目名称突出显示，描述以小字呈现在名称下方。
- **卡片化展示**：每笔密码以独立卡片呈现，卡片间距统一，字段对齐，复制、显示、移动、编辑和删除等操作就近放置。
- **统一的交互语言**：新增、重命名、删除确认、移动和导入异常确认均使用页面内模态对话框，避免浏览器原生弹窗造成风格割裂。
- **水印式落款**：密码卡片区底部显示“© 2026 初心﹡点亮未来”，使用低对比度、居中的小字，不与主要内容争夺注意力。

## 3. 界面布局

### 顶部工具栏

- 左侧显示锁形标识、应用名称和待备份提醒。
- 中间为搜索框，便于快速过滤密码条目。
- 右侧放置“导入文件”“保存”和“导出备份”三个按钮。其中“保存”默认隐藏，仅在已打开可写文件后出现（详见“数据文件读写”）。
- 数据修改后，顶部以红色提示用户及时保存或导出备份；提示文字会随是否持有可写文件而不同（“请及时「保存」或「导出备份」”／“请及时导出备份”）。

### 状态提示条

顶部工具栏下方显示本地存储、导入、导出或错误状态。提示可通过右侧关闭图标收起；成功、警告等状态采用不同的背景色。

### 主工作区

- **左侧分类栏**：显示主分类及条目数，可新增、重命名和删除分类。
- **右侧内容区**：顶部是小类标签和小类/密码新增操作，下方展示密码卡片。
- “全部”是浏览视图，不是实际小类；它后面的“未分类”是默认小类，并保持优先显示。
- **当前实现说明**：新建分类时暂不自动创建“未分类”小类；用户可添加小类。移动到没有小类的分类时，可以选择“未分类”，确认移动后才创建它。
- 内容区可以独立滚动；卡片区下方是水印落款。

### 密码卡片

卡片可展示名称、补充描述、所在分类/小类、账号、密码、网址、连接地址与端口、备注。名称旁的复制图标可将整张密码卡片复制到当前小类，并自动在新名称后追加“（副本）”；其他图标可执行显示/隐藏密码、复制字段、移动、编辑和删除等操作。删除某小类的最后一张卡片会连同该小类一起删除；移走最后一张卡片后源小类为空时也会被删除；移动时若目标小类已有同名卡片，会自动追加“（副本）”后缀以避免同名。密码卡片之间保持紧凑而清晰的间距。

### 对话框

- 密码新增/编辑：包含名称、描述、账号、密码、地址、端口、网址及备注。
- 移动密码：显示正在移动的条目名称，并选择目标分类和小类。
- 其他操作共用统一风格的操作对话框，支持输入、校验、错误提示、确认和取消。
- 导入文件格式错误时显示实际文件名，并询问是否清空所有分类、小类和密码重新开始；取消不会覆盖现有数据。

## 4. 数据与交互设计

### 数据组织

当前数据结构为版本 2：

```json
{
  "version": 2,
  "categories": {
    "分类名称": {
      "subcategories": {
        "未分类": [
          {
            "title": "条目名称",
            "description": "补充描述",
            "username": "账号",
            "password": "密码",
            "endpointHost": "地址",
            "endpointPort": "端口",
            "url": "网址",
            "note": "备注"
          }
        ]
      }
    }
  }
}
```

规范化逻辑兼容旧版分类/条目结构，并将旧名称“默认小类”迁移为“未分类”。备份文件采用易迁移的 JSON 数据；导出备份不会将其加密。

### 浏览、搜索与分类

- 支持按条目名称、描述、账号、连接地址/端口、网址和备注搜索。
- 分类内可按小类筛选；“全部”视图汇总当前分类的小类内容。
- 新增密码要求先选定具体小类。
- 小类名称须非空、在当前分类中唯一，并禁止使用系统视图名称“全部”。
- 移动时，若目标分类尚无小类，可选择“未分类”；确认时创建该小类。
- 删除密码卡片时，若该小类仅剩这一条，确认弹窗会额外提示小类也将被删除，确认后连同小类（含“未分类”）一起删除。
- 移动密码卡片后，若源小类变为空，会一并删除该小类。
- 条目名称（title）不作为唯一标识（条目以数组位置定位），允许同名；仅在移动时，若目标小类已存在同名卡片，自动为移入卡片改名（原名 → “（副本）” → “（副本2）”，依次递增），并通过提示说明改名结果。

### 密码安全与便捷操作

- 编辑表单默认遮蔽密码；卡片默认也遮蔽密码。
- 卡片中手动显示的密码在 15 秒后自动隐藏。
- 随机密码使用浏览器安全随机数生成，并通过拒绝采样避免字符取样偏差。
- 复制账号、密码、网址和连接信息使用同一复制流程，并反馈成功或失败。

### 本地存储与备份

- 保存到 `localStorage` 的应用数据使用 AES-GCM 加密；每次加密生成新的随机 IV。
- 页面内置密钥并从 Base64 导入 Web Crypto；无法解密既有内容时会暂停本地写入，避免以空数据覆盖原数据。
- 导入合法备份后，本地数据会按应用规则规范化并加密保存。
- 变更后显示待备份提醒；用户可导出 JSON 文件用于迁移或离线备份。

### 数据文件读写

除浏览器本地存储外，应用还支持直接读写磁盘上的数据文件，省去每次导入导出的往返。以 `file://` 直接打开，或用 `km.bat` 起一个本地服务器后访问 `http://localhost:8080/km.html`，都能用上这一能力。

- **导入文件**：优先使用 `showOpenFilePicker` 取得文件句柄；浏览器不支持该 API 时回退到 `<input type="file">`，此时只能读入数据，不能写回。
- **保存**：顶部“保存”按钮默认隐藏，仅在已打开可写文件后出现。点击后把当前数据以两空格缩进的 JSON 写回原文件，同时照常更新浏览器本地存储；首次写回会申请读写权限。
- **句柄记忆**：文件句柄保存在 IndexedDB 中，需要用户点“导入文件”手动选中一次才会产生——浏览器不会让网页自行取得本地文件的写权限，这一步省不掉。句柄按来源隔离，`file://` 与 `http://localhost:端口` 各存一份，换一种打开方式就要各自授权一次。若浏览器已收回权限，状态提示条会给出“恢复访问”按钮，由用户确认后重新载入。
- **打开时自动载入**：优先尝试恢复上次授权的句柄，恢复成功就直接载入该文件并显示“保存”按钮。没有可用句柄时，`http(s)://` 下再回退为 `fetch` 同目录的 `km.ini`，此时只能**只读**载入（`fetch` 只取得到字节、拿不到可写句柄）；点“导入文件”选中该文件后即可写回，且下次打开会自动恢复。
- **失败回退**：原文件被删除、移动或未取得写权限时，应用放弃本次写回并给出提示，数据仍加密保存在浏览器本地，重新“导入文件”即可恢复文件读写。

## 5. 设计优点

1. **易部署、易维护**：单 HTML 文件可直接打开，不需要服务器、构建流程或第三方依赖。
2. **操作路径直接**：分类、小类、密码条目层级清楚，常用复制和密码显示功能位于卡片内。
3. **兼顾不同场景**：描述适用于环境说明；地址和端口分栏，适合数据库、服务器等连接资料。
4. **防误操作反馈明确**：危险操作需要页面内确认；错误保留在统一对话框或状态提示中。
5. **具有基本的本地数据保护**：localStorage 不直接保存可读 JSON 密码；随机 IV 和 AES-GCM 提供加密及篡改检测。
6. **备份可移植**：导出的 JSON 可用于手动保存和在其他浏览器中导入。
7. **响应式基础布局**：窄屏下可调整工具栏与侧栏布局，卡片采用自适应网格。
8. **小类自动清理与同名防冲突**：删除或移走小类中的最后一条会清理空小类；移动遇到同名卡片时自动改名，减少整理时的空壳和混淆。
9. **可直接写回数据文件**：在 Chromium 系浏览器中导入 `km.ini` 后，改动可一键写回原文件，免去反复导入导出；浏览器不支持时自动回退为本地存储加手动备份，不影响使用。

## 6. 缺点与安全边界

1. **内置密钥不构成强访问控制**：密钥与解密代码都在 `km.html` 中。能读取或修改该文件、运行页面脚本的人，仍有可能取得密钥或读取解密后的数据。因此，这种加密主要避免直接查看 localStorage 原文，不等同于由主密码保护的密码库。
2. **备份文件为明文 JSON**：导出的 `km.ini` 包含可读密码，应妥善存放；遗失或外泄会暴露其中内容。“保存”写回原文件走的也是同一份明文 JSON，因此数据文件的存放位置需要同样谨慎。
3. **没有主密码、账户或远程同步**：数据只存在于当前浏览器的本地存储和用户自己选择的 `km.ini` 文件中，不会自动同步到设备间，也没有恢复账户或密钥找回机制。
4. **清除浏览器数据可能导致数据丢失**：若没有手动导出备份，清理站点数据、浏览器配置文件损坏或更换设备都可能使数据无法恢复。
5. **浏览器能力和运行环境有影响**：本地存储或 Web Crypto 不可用时无法正常完成加密保存；不同浏览器/文件 URL 的存储隔离也可能导致数据看起来不共享。
6. **单文件应用不利于规模化扩展**：代码、结构、样式和逻辑集中于一个 HTML 文件，功能继续增长后会更难测试和维护。
7. **无复杂协作和权限模型**：当前定位是单人本地使用，不适合多人共享、审计或组织级密码治理。

## 7. 后续优化建议

建议按优先级考虑以下方向，实施前需确认是否改变当前“无需主密码、单文件、本地优先”的定位：

1. **提升密钥保护**：若安全性要求提高，可改为用户主密码派生密钥（例如 PBKDF2 配合随机盐），启动时解锁；不能继续将固定密钥直接放在 HTML 中作为安全边界。
2. **备份加密选项**：提供加密备份，并清楚区分明文兼容备份与加密备份，避免用户误认为导出文件已受保护。
3. **恢复与备份保障**：增加备份时间、数据条目数量和恢复前预览；重要操作前提供可恢复的本地快照。
4. **补充自动化测试**：覆盖旧数据迁移、加密/解密、损坏数据保护、无效导入的取消/确认、分类小类操作和密码自动隐藏。
5. **改善可访问性与窄屏体验**：持续检查键盘焦点、对话框关闭方式、图标替代文本、移动端侧栏和长字段布局。
6. **按需拆分代码**：若功能继续扩展，可将样式、数据层和交互逻辑拆分，并保留简单的本地启动方式。

## 8. 未来维护约定

- 维持本地优先、轻量、低依赖的默认体验；新增外部依赖或后端前先确认需求。
- 修改数据字段时同步更新规范化逻辑、导入/导出兼容性和本文档中的数据结构。
- 不要静默覆盖无法解密或无法解析的现有数据；错误应可见，且优先保护原始数据。
- 涉及加密格式、密钥或导入清空逻辑的变更，要验证成功、失败、取消和旧数据兼容路径。
- 删除或清空类操作应继续使用明确的确认对话框；图标操作保留可读的 `title` 和 `aria-label`。
- 单文件改动后至少运行内联 JavaScript 语法检查，并验证关键 UI 交互。