批准卡
用户在 MimiKey 里看到的每一张批准卡：何时出现、显示什么、各按钮的结果、回调状态与有效期。
概览
批准卡是 MimiKey 为第三方授权渲染的决策界面。所有批准卡都运行在 MimiKey 自己的进程里（iOS App 与 Mac App），接入方无法定制其结构或按钮，只能提供品牌白名单中的名称、图标、品牌色与主页。
| 卡 | 触发 | 主按钮 | 次按钮 |
|---|---|---|---|
| 同意卡 | authorize() / mimikey://authorize | 允许 | 拒绝 |
| 选条目卡 | pick_item | 用这条 | 不给 |
| 读取批准卡 | get_item（ask 策略） | 允许一次 | 拒绝 |
| 安全卡（新建） | create_item | 保存并用于本次任务 | 不用了 |
| 修改卡 | update_item | 保存修改 | 拒绝 |
出卡前的检查
MimiKey 收到深链后，按顺序检查：
- 账号状态。 未登录时显示「请先登录 MimiKey」卡，点「返回应用」后回调
error=not_signed_in。已登录但锁定时，先走正常解锁（面容 ID / 触控 ID / Touch ID 或主密码），解锁后继续出卡；出卡途中被锁定会收起卡片，解锁后重新出卡。 - 深链参数。 回调地址本身不合法时不跳转，只在 MimiKey 内提示。其他参数缺失或格式不对时，回调
error=invalid_request。 - client 与回调地址。 client 不存在、被开发者或平台停用，或回调地址不在登记列表中时，回调
error=invalid_request。 - 请求。 请求不存在或不属于当前账号时，回调
error=request_not_found。
卡片的公共结构
每张卡从上到下包含：
- MimiKey 标识：表明这是 MimiKey 自己渲染的界面。
- 接入方品牌块：图标（加载失败时显示名称首字母）、名称、主页域名；公开客户端在 iOS 上另有「设备内应用」标记。
- 标题：以接入方名称开头，说明它要做什么。
- 用途说明：接入方提供的
reason，原样显示。 - 过期倒计时：到期时卡片自动结束，回调
status=expired。 - 操作按钮：固定的两个按钮，语义由 MimiKey 决定。
同意卡
触发： 接入方调用 authorize()，打开 mimikey://authorize。
显示：
- 标题：「{应用名} 请求连接你的 MimiKey」（Mac 上为「{应用名} 想接入你的 MimiKey」）。
- 「将能做什么」四行：读取你选定的条目、请你选条目、请你在 MimiKey 里新建、请你批准修改。
- 「授权的库」：只列出你拥有的库，个人库默认勾选；共享库的普通成员无法授权该库。
- 「审批策略」：「每次询问」（默认）或「信任此应用」，后者旁注「读取不再逐次询问，仍需你打开 MimiKey 执行」。
- 「审批钥指纹」：16 位十六进制。接入方 App 可以显示同一个指纹供你核对。
结果：
| 操作 | 结果 | 回调 |
|---|---|---|
| 允许 | 生成授权码（10 分钟、单次） | ?mk=authorize&code=…&state=… |
| 拒绝 | 不生成授权 | ?mk=authorize&error=access_denied&state=… |
授权码兑换成令牌后，授权才真正生效。
选条目卡
触发： pick_item 请求。
显示：
- 标题：「{应用名} 请你选一个条目」，以及用途说明。
- 候选列表：来自本授权的库（或请求指定的那个库）中的全部条目，按接入方提示排序——网址同一可注册域优先，其次标题包含提示，再次类型相同。
- 搜索框：按名称、账号或网址筛选。
- 每行显示类型图标、标题与副标题，不显示密码。
结果：
| 操作 | 结果 | 回调 status |
|---|---|---|
| 选中后点「用这条」 | 本机解密该条目、密封给接入方、上传，请求完成 | completed |
| 不给 | 请求被拒绝 | denied |
接入方另外收到一条明文回执 picked_item（id、title、url、kind），不含密码与备注。
读取批准卡
触发： get_item 请求。
ask 策略： 标题「{应用名} 想读取『{条目标题}』」，下方显示所在库与用途说明。
| 操作 | 结果 | 回调 status |
|---|---|---|
| 允许一次 | 批准并由本机立即执行，请求完成 | completed |
| 拒绝 | 请求被拒绝 | denied |
trust 策略： 请求一创建即为已批准。打开 MimiKey 后由本机直接执行，卡上只闪一行「已按你的信任设置提供」，随后跳回接入方。如果打开时没有任何已解锁的设备，请求停在「已批准，等待设备执行」，直到你解锁 MimiKey 或请求过期。
提示 「信任」只免去读取的逐次批准。选条目、新建和修改在两种策略下都必须由你在卡上亲自操作。
安全卡（新建）
触发： create_item 请求。
显示：
- 标题：「{应用名} 请你新建一条{类型}」，以及用途说明。
- 该类型的完整编辑表单（登录、信用卡、银行卡、API 密钥、服务器、安全笔记），接入方提供的标题、网址、用户名等提示已预填，可以修改；密码由你在这里输入，接入方从不经手。
- 「保存到」：默认是请求指定的库，也可以改选你名下的任意库；授权范围之外的库标注「授权范围外」。
结果：
| 操作 | 结果 | 回调 status |
|---|---|---|
| 保存并用于本次任务（存入授权范围内的库） | 条目加密保存；保存即批准本次使用，接入方收到完整条目 | completed |
| 保存并用于本次任务（存入授权范围外的库） | 条目照常保存，但接入方只收到回执（saved_out_of_scope），拿不到这条条目；授权范围不会因此扩大 | completed |
| 不用了 | 请求被拒绝，不保存 | denied |
必填项为空时卡片会直接提示，不会提交。保存后的条目与你手动新建的条目在服务器上完全一样，只有密文。
修改卡
触发： update_item 请求（在接入方上传加密补丁之后）。
显示：
- 标题：「{应用名} 想修改『{条目标题}』」，以及用途说明。
- 「修改内容」差异表：每个被修改的字段显示「原」与「新」两行；密码类字段默认遮挡，可点「显示」/「隐藏」。
- 当前修订号，并注明「保存后生成新修订」。
新值由接入方密封给你的账号身份公钥，只有你已解锁的设备能打开；补丁中出现请求未声明的字段时，MimiKey 会拒绝该请求。
结果：
| 操作 | 结果 | 回调 status |
|---|---|---|
| 保存修改 | 写入新修订；接入方只收到新修订号，不收到明文 | completed |
| 拒绝 | 请求被拒绝，不写入 | denied |
| （保存时条目已被他处修改） | 卡上提示「这条条目刚被别处修改，本次修改未保存」，请求以拒绝结束 | denied |
不操作直接离开
如果你在 MimiKey 里什么都不做就切回接入方 App（在 Mac 上按 Esc 关闭卡片效果相同），MimiKey 不会发送回调，请求保持待处理直到过期。接入方的等待界面会提供「重试」（再次打开 MimiKey 回到这张卡）与「取消」两个出口。
有效期
| 对象 | 有效期 | 到期结果 |
|---|---|---|
| 授权码 | 10 分钟，单次使用 | 兑换失败（code_expired） |
| 选条目、读取请求 | 10 分钟 | expired |
| 新建请求 | 30 分钟 | expired |
| 修改请求草稿（等待接入方上传补丁） | 60 秒 | expired，不会出现在你的设备上 |
| 修改请求（补丁上传后） | 30 分钟 | expired |
| access token | 1 小时 | 接入方自动用 refresh token 续期 |
| refresh token | 30 天，每次续期重新计时 | 需要重新授权 |
卡片上的倒计时与服务器的过期时间一致。授权被撤销时，该授权下所有未完成的请求立即置为 expired。
回调状态汇总
| 场景 | 回调参数 |
|---|---|
| 授权成功 | mk=authorize&code=…&state=… |
| 授权被拒绝 | mk=authorize&error=access_denied&state=… |
| 请求完成 | mk=request&request_id=…&state=…&status=completed |
| 请求被拒绝 / 取消 / 过期 | mk=request&request_id=…&state=…&status=denied（或 cancelled、expired） |
| MimiKey 未登录 | error=not_signed_in |
| 深链或 client 不合法 | error=invalid_request |
| 请求不存在 | error=request_not_found |
回调只告诉接入方「可以去取结果了」，不携带任何结果数据。
在 MimiKey 里管理授权
除了通过深链出卡，你也可以直接在 MimiKey 里处理：
- iOS： 设置 →「第三方授权」。
- Mac： 侧栏「第三方授权」。
这里有两部分：
- 待处理请求：所有等待你处理的请求。点开后出现与深链相同的批准卡；处理完成后只关闭卡片，不跳转到接入方 App，接入方通过轮询拿到结果。
- 已授权应用：每个授权的应用名、授权的库、审批策略与审批钥指纹。你可以在「每次询问」与「信任此应用」之间切换（只影响之后的新请求），或撤销授权。撤销立即生效：该应用的令牌全部失效，未完成的请求全部过期。