From 0320c206230a1d22c9246fe73032b172f4e25a99 Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Thu, 30 Jul 2026 19:35:08 +0800 Subject: [PATCH] docs(auth): document authority recovery contract Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> --- docs/verification/issue-640.md | 10 +++---- .../IdentityProviderAdminController.java | 24 +++++++++++++++++ web/src/api/generated/schema.d.ts | 27 ++++++++++++++++++- 3 files changed, 54 insertions(+), 7 deletions(-) diff --git a/docs/verification/issue-640.md b/docs/verification/issue-640.md index 8abb99b0..fb1ebc0d 100644 --- a/docs/verification/issue-640.md +++ b/docs/verification/issue-640.md @@ -5,7 +5,7 @@ - Issue: - Pull request: - Integration target: `big-main` -- Validation environment: dedicated Hong Kong test server +- Validation environment: isolated, production-equivalent test deployment - Production/default branch: not modified This record covers P1 / PR 1 from @@ -15,7 +15,7 @@ plugins remain outside this PR. ## Automated gates -The following checks ran on the Hong Kong test server: +The following checks ran against the isolated test deployment: | Gate | Result | |---|---| @@ -27,11 +27,9 @@ The following checks ran on the Hong Kong test server: | DCO | passed | | CLA | passed | -The server image used for pre-integration runtime validation was -`skillhub-server:identity-core-9818333c`, image ID -`sha256:a9055606ad2a551f12319e66f7056e4bda072a8e14a238882cdbdbeb871cf6c8`. The clean PR branch was rebuilt from the latest `big-main`; its unified-identity -file tree is identical to the validated feature tree. +file tree is identical to the validated feature tree. Runtime artifact identity +and operational logs are intentionally omitted from the public repository. ## PostgreSQL and runtime scenarios diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/admin/IdentityProviderAdminController.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/admin/IdentityProviderAdminController.java index b98e1037..5b6629bd 100644 --- a/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/admin/IdentityProviderAdminController.java +++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/admin/IdentityProviderAdminController.java @@ -7,6 +7,9 @@ import com.iflytek.skillhub.dto.ApiResponseFactory; import com.iflytek.skillhub.dto.IdentityProviderAuthorityRecoveryResponse; import com.iflytek.skillhub.service.AuditRequestContext; import com.iflytek.skillhub.service.IdentityProviderAdminAppService; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.responses.ApiResponses; import jakarta.servlet.http.HttpServletRequest; import org.springframework.security.access.prepost.PreAuthorize; import org.springframework.security.core.annotation.AuthenticationPrincipal; @@ -31,6 +34,27 @@ public class IdentityProviderAdminController extends BaseApiController { this.providerAdminAppService = providerAdminAppService; } + @Operation( + summary = "Recover an identity provider authority lock", + description = "Restores a provider from AUTHORITY_MISMATCH only when the current " + + "trusted configuration matches its pinned authority.") + @ApiResponses({ + @io.swagger.v3.oas.annotations.responses.ApiResponse( + responseCode = "200", + description = "Provider recovered or already ready"), + @io.swagger.v3.oas.annotations.responses.ApiResponse( + responseCode = "403", + description = "Caller is not a super administrator", + content = @Content), + @io.swagger.v3.oas.annotations.responses.ApiResponse( + responseCode = "404", + description = "Enabled provider configuration not found", + content = @Content), + @io.swagger.v3.oas.annotations.responses.ApiResponse( + responseCode = "409", + description = "Current configuration does not match the pinned authority", + content = @Content) + }) @PostMapping("/{providerCode}/authority/recover") @PreAuthorize("hasRole('SUPER_ADMIN')") public ApiResponse diff --git a/web/src/api/generated/schema.d.ts b/web/src/api/generated/schema.d.ts index 7f766cbb..706fe894 100644 --- a/web/src/api/generated/schema.d.ts +++ b/web/src/api/generated/schema.d.ts @@ -1629,6 +1629,10 @@ export interface paths { }; get?: never; put?: never; + /** + * Recover an identity provider authority lock + * @description Restores a provider from AUTHORITY_MISMATCH only when the current trusted configuration matches its pinned authority. + */ post: operations["recoverSameAuthority"]; delete?: never; options?: never; @@ -8367,7 +8371,7 @@ export interface operations { }; requestBody?: never; responses: { - /** @description OK */ + /** @description Provider recovered or already ready */ 200: { headers: { [name: string]: unknown; @@ -8376,6 +8380,27 @@ export interface operations { "*/*": components["schemas"]["ApiResponseIdentityProviderAuthorityRecoveryResponse"]; }; }; + /** @description Caller is not a super administrator */ + 403: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Enabled provider configuration not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Current configuration does not match the pinned authority */ + 409: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; }; }; verify: {