Skip to content

feat: add sourceId. - #51

Closed
qyl27 wants to merge 2 commits into
HyperZoneLogin:masterfrom
qyl27:feat/add-source-id
Closed

qyl27 wants to merge 2 commits into
HyperZoneLogin:masterfrom
qyl27:feat/add-source-id

Conversation

@qyl27

@qyl27 qyl27 commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

变更说明

(本PR应当在#50 合并以后审阅)

SourceId用于标识唯一上游认证来源。
对于Offline和Floodgate,它就是对应的channelId(即offline和floodgate);
对于Yggdrasil,它是yggdrasil:<entryId>。

本PR的修改曾是#46的草案,并被引入properties的实现代替。

我现在认为sourceId还是应该加回来:

  1. 对于Yggdrasil来说,channalId是yggdrasil,而不包含entryId;但是在实际应用中,确定一个credential究竟是来自official(官方正版验证)还是属于littleskin(随便一个yggdrasil兼容认证服务器)可能更实用。
  2. 白名单模块就希望有这样一个东西,于是创造了sourceId概念,曾希望把它作为公开API引入。但当时看上去只有白名单一个模块想要用,因此ksqeib认为把它当作白名单模块内部实现的一部分比较好,而为HyperZoneCredential引入了一个通用的properties,由YggdrasilHyperZoneCredential暴露yggdrasil-entry-id属性(feat: add credential properties. #46),在白名单模块内部进行字符串拼接、匹配。
  3. 目前在着手实现[Feature]: 需要一个Bukkit端用于和Velocity端打配合 #27,我们希望分辨玩家究竟是来自mojang还是来自littleskin的,我认为把整个sourceId整体作为context提供给luckperms更合适。因此重新提出把sourceId加入公开API的PR。
  4. SourceId也可以为未来引入其他可能聚合多个上游auth子模块留出空间,这样就不必再单独修改whitelist和luckperms-compat模块。例如,曾经在HZL群里当作一个饼提到,但还没新建文件夹的,“26.4新增的hostName字段的有趣用法”,我觉得也有可能用到这种东西。

关联范围

  • openvc
  • auth-yggd
  • auth-offline
  • data-merge
  • profile-skin
  • api
  • 文档
  • GitHub 工作流 / 仓库配置

变更类型

  • Bug 修复
  • 新功能
  • 重构
  • 文档更新
  • 构建 / CI 调整
  • 其他

测试与验证

请说明你做了哪些验证,例如:

  • 已本地构建通过
  • 已运行相关测试
  • 已验证配置生成 / 加载正常
  • 已验证迁移逻辑或命令行为
  • 已更新相关文档

兼容性与风险

这是一个API的breaking change,影响所有实现了HyperZoneCredential接口的插件。

其他补充

如有截图、日志、配置示例或后续 TODO,请在此补充。

@sourcery-ai

sourcery-ai Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

API

Add sourceId to the public credential contract so consumers can distinguish credentials from different upstream authentication sources.

  • api/src/main/kotlin/icu/h2l/api/profile/HyperZoneCredential.kt L47-51

Change the properties-holder contract to expose a mutable map and return nullable property values, avoiding a newly created map on each getter call.

  • api/src/main/kotlin/icu/h2l/api/util/IPropertiesHolder.kt L25-28, L42 (removed lines)

Implementation

Provide a concurrent-map-backed properties holder for credentials that delegate the properties API.

  • api/src/main/kotlin/icu/h2l/api/util/PropertiesHolder.kt L1-28

Implement the new source identifier for Floodgate and Offline credentials using their channel IDs, and provide the properties-holder implementation required by the revised API.

  • subplugin/auth-floodgate/src/main/kotlin/icu/h2l/login/auth/floodgate/credential/FloodgateHyperZoneCredential.kt L25-26, L37-40
  • subplugin/auth-offline/src/main/kotlin/icu/h2l/login/auth/offline/service/OfflineHyperZoneCredential.kt L25-26, L39-42

Identify Yggdrasil credentials by channel and entry ID, and retain the entry ID property without lowercasing it using the default locale.

  • subplugin/auth-yggd/src/main/kotlin/icu/h2l/login/auth/online/credential/YggdrasilHyperZoneCredential.kt L25-26, L37-43

Tests

Update the test credential fakes to implement the new source ID contract and delegate property handling to the shared holder.

  • velocity/src/test/kotlin/icu/h2l/login/profile/UserBindingCodeServiceTest.kt L31-32, L267-270
  • velocity/src/test/kotlin/icu/h2l/login/profile/UserUnbindServiceTest.kt L31-32, L105-108

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@qyl27
qyl27 marked this pull request as draft November 12, 2026 13:02

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 2 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="subplugin/auth-floodgate/src/main/kotlin/icu/h2l/login/auth/floodgate/credential/FloodgateHyperZoneCredential.kt" line_range="37" />
<code_context>
     private val suggestedProfileCreateUuid: UUID?,
     private val knownUserUUID: UUID? = null,
-) : HyperZoneCredential {
+) : HyperZoneCredential, IPropertiesHolder by PropertiesHolder() {
     override val channelId: String = CHANNEL_ID
     override val credentialId: String = trustedUuid.toString()
</code_context>
<issue_to_address>
**Rename drops credential properties**

When custom properties are set on a pending Offline or Floodgate credential before it is renamed, `withNewName` creates a replacement credential with a fresh `PropertiesHolder` and does not copy the original properties, so the rename flow replaces the credential and downstream consumers see its metadata missing.

Have both credential `withNewName` implementations preserve the original properties when creating the renamed credential.

Also at `subplugin/auth-offline/src/main/kotlin/icu/h2l/login/auth/offline/service/OfflineHyperZoneCredential.kt:39`.
</issue_to_address>

### Comment 2
<location path="subplugin/auth-yggd/src/main/kotlin/icu/h2l/login/auth/online/credential/YggdrasilHyperZoneCredential.kt" line_range="40" />
<code_context>
+) : HyperZoneCredential, IPropertiesHolder by PropertiesHolder() {
     override val channelId: String = CHANNEL_ID
     override val credentialId: String = "$entryId:$authenticatedUUID"
+    override val sourceId: String = "$channelId:${entryId}"

     init {
</code_context>
<issue_to_address>
**Equivalent entries get different identifiers**

When the configured Yggdrasil entry ID contains uppercase letters or differs in casing from another reference, `sourceId` and the `yggdrasil-entry-id` property preserve the configured casing, while `EntryTableManager` normalizes IDs to lowercase; consumers matching canonical IDs treat the same upstream entry as a different source.

Normalize `entryId` to lowercase using the same canonicalization as `EntryTableManager` before constructing `sourceId` and setting `YGGDRASIL_ENTRY_ID_PROPERTY`.

Also at `subplugin/auth-yggd/src/main/kotlin/icu/h2l/login/auth/online/credential/YggdrasilHyperZoneCredential.kt:43`.
</issue_to_address>

Sourcery assessment

Approval pending. 2 findings to address first.

Blocking findings: subplugin/auth-floodgate/src/main/kotlin/icu/h2l/login/auth/floodgate/credential/FloodgateHyperZoneCredential.kt:37, subplugin/auth-yggd/src/main/kotlin/icu/h2l/login/auth/online/credential/YggdrasilHyperZoneCredential.kt:40


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

private val suggestedProfileCreateUuid: UUID?,
private val knownUserUUID: UUID? = null,
) : HyperZoneCredential {
) : HyperZoneCredential, IPropertiesHolder by PropertiesHolder() {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Rename drops credential properties

When custom properties are set on a pending Offline or Floodgate credential before it is renamed, withNewName creates a replacement credential with a fresh PropertiesHolder and does not copy the original properties, so the rename flow replaces the credential and downstream consumers see its metadata missing.

Have both credential withNewName implementations preserve the original properties when creating the renamed credential.

Also at subplugin/auth-offline/src/main/kotlin/icu/h2l/login/auth/offline/service/OfflineHyperZoneCredential.kt:39.

Prompt for AI agents
In `subplugin/auth-floodgate/src/main/kotlin/icu/h2l/login/auth/floodgate/credential/FloodgateHyperZoneCredential.kt` at line 37:

**Rename drops credential properties**

When custom properties are set on a pending Offline or Floodgate credential before it is renamed, `withNewName` creates a replacement credential with a fresh `PropertiesHolder` and does not copy the original properties, so the rename flow replaces the credential and downstream consumers see its metadata missing.

Have both credential `withNewName` implementations preserve the original properties when creating the renamed credential.

Also at `subplugin/auth-offline/src/main/kotlin/icu/h2l/login/auth/offline/service/OfflineHyperZoneCredential.kt:39`.

) : HyperZoneCredential, IPropertiesHolder by PropertiesHolder() {
override val channelId: String = CHANNEL_ID
override val credentialId: String = "$entryId:$authenticatedUUID"
override val sourceId: String = "$channelId:${entryId}"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Equivalent entries get different identifiers

When the configured Yggdrasil entry ID contains uppercase letters or differs in casing from another reference, sourceId and the yggdrasil-entry-id property preserve the configured casing, while EntryTableManager normalizes IDs to lowercase; consumers matching canonical IDs treat the same upstream entry as a different source.

Normalize entryId to lowercase using the same canonicalization as EntryTableManager before constructing sourceId and setting YGGDRASIL_ENTRY_ID_PROPERTY.

Also at subplugin/auth-yggd/src/main/kotlin/icu/h2l/login/auth/online/credential/YggdrasilHyperZoneCredential.kt:43.

Prompt for AI agents
In `subplugin/auth-yggd/src/main/kotlin/icu/h2l/login/auth/online/credential/YggdrasilHyperZoneCredential.kt` at line 40:

**Equivalent entries get different identifiers**

When the configured Yggdrasil entry ID contains uppercase letters or differs in casing from another reference, `sourceId` and the `yggdrasil-entry-id` property preserve the configured casing, while `EntryTableManager` normalizes IDs to lowercase; consumers matching canonical IDs treat the same upstream entry as a different source.

Normalize `entryId` to lowercase using the same canonicalization as `EntryTableManager` before constructing `sourceId` and setting `YGGDRASIL_ENTRY_ID_PROPERTY`.

Also at `subplugin/auth-yggd/src/main/kotlin/icu/h2l/login/auth/online/credential/YggdrasilHyperZoneCredential.kt:43`.

@qyl27
qyl27 marked this pull request as ready for review November 12, 2026 13:05
@ksqeib

ksqeib commented Nov 12, 2026

Copy link
Copy Markdown
Member

我认为并不合适,如果属性清单已经置入entryId,那么实际上只需要检查入场凭据的类型即可,那么给凭据添加一个固定的getType就好了,不需要这种组合

@qyl27 qyl27 closed this Nov 13, 2026
@qyl27
qyl27 deleted the feat/add-source-id branch November 13, 2026 11:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants