lazycat-auth-integration

懒猫微服认证接入

先确认目标 lzcos 与 lzc-cli 版本；编写配置前必须读取 references/spec-sync.md，按其中流程现场核对官方原文。LPK V2 示例要求 lzcos >= 1.5.0、lzc-cli >= 2.0.0；更老目标不能直接套用。

先选机制

OIDC 最小流程

1. 从上游应用文档确认准确回调路径。
2. 在 lzc-manifest.yml 设置 application.oidc_redirect_path；没有此字段就不会生成 OIDC 环境变量。
3. 仅把应用需要的 OIDC 变量传入对应服务，优先使用 issuer discovery。
4. 不把动态生成的 client secret 写入镜像、数据库或文档。

以下沿用官方 Outline 镜像与回调，只展示 OIDC 相关片段；Outline 所需数据库、Redis、存储及其他环境变量仍须按其部署文档配置，本片段不能独立启动。

# package.yml（LPK V2 静态元数据片段）
package: cloud.lazycat.app.outline
version: 0.0.1
name: Outline

左侧变量名来自 Outline 官方接入要求；适配其他应用时必须按该应用文档调整。右侧 LAZYCAT_AUTH_OIDC_* 是平台变量。

身份 Header 的边界

• 仅在请求确定经过平台 Ingress 的信任边界时，才把平台生成的 X-HC-* 当作身份依据；不要信任客户端自行传入的同名值。
• 普通已登录客户端请求通常包含用户与设备上下文；API Auth Token 不注入 X-HC-Device-ID/X-HC-Device-PeerID，委托请求也不带完整客户端设备上下文。
• public_path 上鉴权失败时，平台会清空身份 Header。因此代码必须先检查 X-HC-User-ID 是否存在，不能把“路径可访问”当作“用户已登录”。

API Auth Token 的正确语义

请求使用 Lzc-Api-Auth-Token: ${LZC_API_TOKEN} 做平台鉴权，该敏感 Header 在转发到应用前会被移除。移除 Token 不等于鉴权后的请求不能到达应用；它只表示后端收不到该 Token。若应用接口还有自己的业务鉴权，调用方必须另行满足，不能把平台 Token 当作业务 Token。

public_path 最小权限原则

默认不要配置。确需 webhook、分享下载等入口时，只放行经过风险审查的精确窄路径，并在应用层校验签名、一次性令牌或等价凭据；不要无条件开放 /、管理接口、文件读取接口或调试接口。

交付检查

• package.yml 与 lzc-manifest.yml 已按 LPK V2 分离，字段与目标版本匹配。
• OIDC 回调路径与应用实际回调完全一致，issuer/endpoints 未凭空拼接。
• 无真实 Token、client secret、弱口令或真实设备域名。
• Header 信任边界明确，缺少设备 Header 时能够安全降级。
• public_path 已缩到最小范围，并有应用层鉴权与未登录测试。
• 应用互访只申请 self_delegate/user_delegate 中实际需要的一项。