Bitzsoft.Integrations.JiraCloud 1.0.0-alpha.10

Bitzsoft.Integrations.JiraCloud

Jira Cloud ToB 连接器。

安装与兼容性

dotnet add package Bitzsoft.Integrations.JiraCloud

包支持 net5.0、net8.0 和 net10.0。

OAuth 与安全传输

当前认证与安全传输基础提供：

• net5.0;net8.0;net10.0；
• Atlassian resource-level OAuth 2.0 3LO；
• 一个运营方持有并分发的 3LO 应用，不接受用户 API token，也不要求客户逐租户创建应用；
• 显式 cloudId、站点、callback 与可信 endpoint profile；
• tenant/profile/授权主体/cloudId/环境/凭据名称全维度 grant 隔离；
• rotating refresh token 的持久化 CAS 接口与单进程开发实现；
• refresh token 成功 CAS 后才缓存 access token，应用密钥或 grant revision 变化会自动失效缓存；
• 仅显式标记 replay-safe 的请求在 401 后刷新并重放一次；
• token 请求/响应正文按凭据抑制，普通业务正文不设强制大小上限。

生产环境必须实现 IJiraCloudOAuthGrantStore，使用 KMS/Vault 支持的加密持久化 与跨实例 compare-and-swap；InMemoryJiraCloudOAuthGrantStore 仅用于测试和 显式单进程开发。运营应用的 client id/client secret 仍由 IIntegrationCredentialResolver 独立提供，不能与客户 grant 混存。

授权宿主负责生成、持久化并一次性验证绑定用户会话的高熵 state。连接器只在 宿主验证 callback 后交换 authorization code，并要求 token 具备 read:jira-work、manage:jira-webhook，以及由 rotating refresh token 证明的离线授权能力。每次新授权和 token 轮换都会校验 accessible-resources 必须精确匹配一个预配置站点。

Issue 读取与 enhanced search 已提供：

• IJiraCloudClient.GetIssueAsync，返回核心强类型字段和完整未裁剪的 Issue Raw；
• JiraCloudIssueQueryPolicy 由宿主登记项目、可用过滤值、字段和页大小， 调用方只能缩小范围；
• JiraCloudIssueSearchRequest 只接受 project/issue type/status、闭合 updated 范围和最多 50 个 reconcileIssues，不接受任意 JQL；
• updated 时间使用 epoch milliseconds 生成，避免授权用户 Jira 时区改变 查询边界；
• 固定 ORDER BY updated ASC, id ASC，空页和短页只按服务端 isLast 判断是否结束；
• 厂商 nextPageToken 经认证加密后才成为短期 JiraCloudIssueSearchCursor，并绑定 tenant/profile/授权主体/cloudId/ site/query/fields/page size；
• nextPageToken 在请求日志中只做字段级脱敏，其他搜索 JSON 和兆级 Issue 正文仍完整记录。

生产还必须注入跨实例持久化、支持密钥轮换的 IJiraCloudCursorProtector；InMemoryJiraCloudCursorProtector 只适合测试 和显式单进程开发，重启会令旧游标失效。enhanced search 是 eventually consistent；reconcileIssues 只增强最多 50 个明确 Issue 的读后写一致性， 本包不会据此声明 Full/Incremental Sync。

动态 Issue Webhook 生命周期已提供：

• IJiraCloudWebhookClient 注册、完整读取、续期与删除；
• 只允许 jira:issue_created、jira:issue_updated、 jira:issue_deleted，调用方提交 project/issue type/status，由 JiraCloudWebhookPolicy 生成 JQL，不接受任意 JQL；
• callback 必须由宿主策略登记为绝对 HTTPS URI；
• 注册前按“应用 × 授权用户 × 租户”检查五条 OAuth Webhook 总配额，未知但 属于同一调用应用的 Webhook 也会占用配额；
• 注册结果按请求顺序保留成功 ID 或 Provider 校验错误，正确表达部分成功；
• GET 列表只按 isLast 终止，即使中间页为空或短于 maxResults 也不会 提前结束；
• 续期和删除只接受本连接器登记账中、且属于请求策略的 ID，避免 Jira 对未知 ID 的静默忽略被误报为成功；
• DELETE/PUT/POST 都不做 401 自动重放；普通请求与响应正文不抑制、不截断， token 交换仍按凭据抑制；
• 删除采用两小时重投墓碑，等待 Jira 已触发投递的重试窗口结束后再清理。

生产环境必须提供跨实例原子 CAS 的 IJiraCloudWebhookRegistrationStore；内存实现只适合测试和显式单进程开发。 注册是不可安全重放的远程写入：若远程成功后本地持久化失败，宿主应先调用 GetWebhooksAsync 对账，不能盲目重试注册。

动态 Webhook 入站已接入统一 Gateway/Inbox：

• JiraCloudWebhookReceiverProfile 把可信 WebhookRoute.EndpointId 映射到 profile、授权主体和 Webhook 策略，不能根据未验签正文选择租户；
• callback 请求必须为策略登记的精确 HTTPS URI、POST application/json， 并携带唯一的 X-Atlassian-Webhook-Identifier；
• OAuth Bearer JWT 只接受 HS256，使用运营应用当前或上一把 client secret 固定时间验签；拒绝 none、重复 Header、crit、嵌入式 JWK 与远程取钥参数；
• iss、aud、exp 可在 receiver profile 中按真实 Atlassian 应用观测值 强制，标准 exp/nbf/iat 只要出现就会校验；
• 正文只接受三种 Issue 生命周期事件，并校验 timestamp、Issue 核心范围以及 一至五个 matchedWebhookIds；每个 ID 必须存在于相同授权主体/cloudId 的 本地登记账，且仍被对应策略允许；
• X-Atlassian-Webhook-Retry 只接受 1–5，投递 ID 作为 replay/Inbox 幂等键；删除墓碑仅在重试保留窗内继续接受；
• 验签读取原始 Authorization，但 Inbox 信封只保存 ***，不会持久化 Bearer JWT；其他 Header 和完整正文仍按原样保存，不设连接器级大小上限。

Atlassian 官方文档只明确说明 OAuth Webhook token 由应用 client secret 签名，没有公开完整 JWT claim 契约。HS256、实际 issuer/audience、是否总有 expiration，以及 jira:issue_deleted 的真实 payload 字段仍必须使用运营方 控制的公开 3LO 应用做联调认证；本地模拟验签测试不等同于厂商认证。在完成该认证前， 生产 profile 不应凭空强制未观测到的 claim。

生产还必须为统一 Webhook Gateway 提供跨实例持久化的 IWebhookReplayStore 与 IWebhookInboxStore。Jira 官方投递正文当前可能达到 25 MB；宿主可按容量和合规策略在入口限流，但连接器和 RequestLogging 不强制截断。 当前连接器不会把 Issue 写操作声明为幂等。

DI 使用 AddBitzsoftJiraCloud(...) 注册固定站点，或使用四个 resolver 类型参数 的泛型重载接入多租户配置。Provider 目录公开 IJiraCloudOAuthClient、 IJiraCloudClient、IJiraCloudWebhookClient 与 IWebhookVerifier；跨领域 Webhook 路由使用 ProjectManagement:jira-cloud。主注册方法不会选择 IJiraCloudOAuthGrantStore、IJiraCloudCursorProtector、 IJiraCloudWebhookRegistrationStore、应用凭据或统一 Inbox 的生产实现。 AddInMemoryJiraCloudState() 只显式提供前三项进程内状态，仍不会注册凭据或 Inbox/replay store。