@crowi/api-contract 2.0.0-alpha.15 → 2.0.0-alpha.16

package/dist/index.mjs

@@ -108,6 +108,11 @@ var ERROR_CODES = [
   // --- federated sign-in (RFC-0014) ---
   "FEDERATED_HANDOFF_INVALID",
   "FEDERATED_HANDOFF_CONSUMED",
+  // --- federated account linking (RFC-0014 §5.4) ---
+  "FEDERATED_IDENTITY_IN_USE",
+  "FEDERATED_LINK_AUTH_STATE_CHANGED",
+  "FEDERATED_LINK_NOT_LINKED",
+  "LINK_COMPLETION_CONSUMED",
   // --- admin subsystems ---
   "ENCRYPTION_NOT_CONFIGURED",
   "MAIL_FROM_NOT_CONFIGURED",
@@ -6053,12 +6058,28 @@ var FederatedHandoffResponseSchema = TokenAuthResponseSchema;
 var LinkedAuthProviderListResponseSchema = z52.object({
   identities: z52.array(z52.object({ provider: z52.string() }))
 });
-var CreateLinkGrantRequestSchema = z52.object({
-  /** RFC 7638 thumbprint of the P-256 public key this browser will use at `/start` — binds the grant to this browser (AC-2). */
-  handoffChallenge: z52.string().min(1)
+var LinkCompletionCodeSchema = z52.string().regex(/^[A-Za-z0-9_-]{43}$/, "must be a 43-character base64url completion code");
+var StartProviderLinkResponseSchema = z52.object({
+  authorizationUrl: z52.string().url()
 });
-var CreateLinkGrantResponseSchema = z52.object({
-  linkGrant: z52.string()
+var PendingLinkCompletionResponseSchema = z52.object({
+  provider: z52.string(),
+  accountLabel: z52.string().optional()
+});
+var CompleteProviderLinkResponseSchema = z52.object({
+  result: z52.literal("linked")
+});
+var LinkCompletionConsumedErrorSchema = ApiErrorSchema.extend({
+  error: z52.object({
+    code: z52.literal("LINK_COMPLETION_CONSUMED"),
+    message: z52.string()
+  })
+});
+var CompleteProviderLinkConflictErrorSchema = ApiErrorSchema.extend({
+  error: z52.object({
+    code: z52.enum(["FEDERATED_IDENTITY_IN_USE", "FEDERATED_LINK_AUTH_STATE_CHANGED", "FEDERATED_LINK_NOT_LINKED"]),
+    message: z52.string()
+  })
 });
 var UnlinkAuthProviderErrorSchema = z52.object({
   error: z52.object({
@@ -6089,7 +6110,7 @@ var startFederatedProviderRoute = createRoute29({
   method: "get",
   path: "/auth/providers/{name}/start",
   tags: ["federatedAuth"],
-  summary: "Top-level navigation that redirects the browser to the named provider",
+  summary: "Top-level navigation that redirects the browser to the named provider (public sign-in ONLY)",
   request: {
     params: z53.object({ name: z53.string() }),
     query: z53.object({
@@ -6097,31 +6118,13 @@ var startFederatedProviderRoute = createRoute29({
       /** base64url(JSON) of the sender's P-256 public JWK. */
       handoff_jwk: z53.string().min(1),
       /** base64url ES256 signature over the start canonical message. */
-      handoff_proof: z53.string().min(1),
-      /**
-       * RFC-0014 phase 3 — `'1'` switches this start into LINK mode: the
-       * request must carry a web-session JWT, and the flow attaches the
-       * resulting identity to that session's user instead of signing
-       * anyone in. Absent (the ordinary sign-in start) the route stays
-       * fully public.
-       */
-      link: z53.literal("1").optional(),
-      /** The opaque id from `POST /auth/providers/{name}/link-grants`. Required when `link=1`, ignored otherwise. */
-      link_grant: z53.string().min(1).optional()
+      handoff_proof: z53.string().min(1)
     })
   },
   responses: {
     302: { description: "Redirect to the provider authorization endpoint" },
     400: {
-      description: "Malformed continue / sender proof, or an invalid/expired/mismatched link grant",
-      content: { "application/json": { schema: ApiErrorSchema } }
-    },
-    401: {
-      description: "link=1 without a web-session JWT \u2014 never downgraded to the public sign-in start",
-      content: { "application/json": { schema: ApiErrorSchema } }
-    },
-    403: {
-      description: "link=1 with a non-web credential (PAT / OAuth access token)",
+      description: "Malformed continue / sender proof, OR a raw `link` query key is present (any value) \u2014 the retired link-via-GET flow is gone entirely; a raw `link` key is always rejected rather than silently downgraded to public sign-in.",
       content: { "application/json": { schema: ApiErrorSchema } }
     },
     404: {
@@ -6154,32 +6157,113 @@ var listLinkedAuthProvidersRoute = createRoute29({
     }
   }
 });
-var createAuthProviderLinkGrantRoute = createRoute29({
+var startProviderLinkRoute = createRoute29({
   method: "post",
-  path: "/auth/providers/{name}/link-grants",
+  path: "/auth/providers/{name}/link-start",
   tags: ["federatedAuth"],
-  summary: "Mint a short-lived, opaque grant that authorizes ONE link start for the current web session",
+  summary: "Mint an IdP authorization URL + flow-specific state cookie for the current web session (stage 1 of 3)",
   request: {
-    params: z53.object({ name: z53.string() }),
-    body: { content: { "application/json": { schema: CreateLinkGrantRequestSchema } } }
+    params: z53.object({ name: z53.string() })
   },
   responses: {
     200: {
-      description: "Opaque single-use grant id",
-      content: { "application/json": { schema: CreateLinkGrantResponseSchema } }
+      description: "Authorization URL to navigate the browser to. Sets a flow-specific, 300s state cookie.",
+      content: { "application/json": { schema: StartProviderLinkResponseSchema } }
+    },
+    400: {
+      description: "The signed link-state cookie value would exceed its per-cookie byte limit, or the aggregate Cookie-header admission budget cannot be satisfied even after pruning \u2014 no Set-Cookie or authorizationUrl is returned.",
+      content: { "application/json": { schema: ApiErrorSchema } }
     },
     401: {
-      description: "Authentication required",
+      description: "Authentication required (credential missing/invalid \u2014 resolved by middleware before this route's own validation)",
       content: { "application/json": { schema: AuthenticationRequiredErrorSchema } }
     },
     403: {
-      description: "Non-web credential (PAT / OAuth access token)",
+      description: "Non-web credential (PAT / OAuth access token) \u2014 linking is a session-level account change",
       content: { "application/json": { schema: ApiErrorSchema } }
     },
     404: {
       description: "Unknown, unconfigured, or credential-kind provider",
       content: { "application/json": { schema: ApiErrorSchema } }
     },
+    500: {
+      description: "Internal server error (e.g. a declared multi-instance topology with no reachable Redis)",
+      content: { "application/json": { schema: InternalServerErrorSchema } }
+    }
+  }
+});
+var getProviderLinkCompletionRoute = createRoute29({
+  method: "get",
+  path: "/auth/providers/{name}/link-completions/{code}",
+  tags: ["federatedAuth"],
+  summary: "Read a pending link completion's confirmation details (stage 3a \u2014 non-destructive)",
+  request: {
+    params: z53.object({ name: z53.string(), code: LinkCompletionCodeSchema })
+  },
+  responses: {
+    200: {
+      description: "Pending, unconsumed completion bound to the caller \u2014 provider label fallback + optional display-only accountLabel",
+      content: { "application/json": { schema: PendingLinkCompletionResponseSchema } }
+    },
+    400: {
+      description: "Authenticated but `{code}` fails the 43-character base64url shape (VALIDATION_ERROR)",
+      content: { "application/json": { schema: ValidationErrorSchema } }
+    },
+    401: {
+      description: "Authentication required \u2014 resolved by middleware before this route's own `{code}` shape validation, so an unauthenticated + malformed code is still 401, never 400",
+      content: { "application/json": { schema: AuthenticationRequiredErrorSchema } }
+    },
+    403: {
+      description: "Non-web credential (PAT / OAuth access token)",
+      content: { "application/json": { schema: ApiErrorSchema } }
+    },
+    404: {
+      description: "Never-issued, expired, retention-expired, or bound to a different user/provider/authVersion \u2014 all collapse to the same generic NOT_FOUND (no result-unknown code exists)",
+      content: { "application/json": { schema: ApiErrorSchema } }
+    },
+    409: {
+      description: "The caller's own completion was already consumed",
+      content: { "application/json": { schema: LinkCompletionConsumedErrorSchema } }
+    },
+    500: {
+      description: "Internal server error",
+      content: { "application/json": { schema: InternalServerErrorSchema } }
+    }
+  }
+});
+var completeProviderLinkRoute = createRoute29({
+  method: "post",
+  path: "/auth/providers/{name}/link-completions/{code}",
+  tags: ["federatedAuth"],
+  summary: "Atomically consume a link completion code and insert the identity (stage 3b \u2014 terminal)",
+  request: {
+    params: z53.object({ name: z53.string(), code: LinkCompletionCodeSchema })
+  },
+  responses: {
+    200: {
+      description: "Linked (fresh winner OR an already-consumed replay that resolves to the same owner) \u2014 the same body either way",
+      content: { "application/json": { schema: CompleteProviderLinkResponseSchema } }
+    },
+    400: {
+      description: "Authenticated but `{code}` fails the 43-character base64url shape (VALIDATION_ERROR)",
+      content: { "application/json": { schema: ValidationErrorSchema } }
+    },
+    401: {
+      description: "Authentication required \u2014 resolved by middleware before this route's own `{code}` shape validation, so an unauthenticated + malformed code is still 401, never 400",
+      content: { "application/json": { schema: AuthenticationRequiredErrorSchema } }
+    },
+    403: {
+      description: "Non-web credential (PAT / OAuth access token)",
+      content: { "application/json": { schema: ApiErrorSchema } }
+    },
+    404: {
+      description: "Never-issued, expired, retention-expired, or bound to a different user/provider \u2014 all collapse to the same generic NOT_FOUND",
+      content: { "application/json": { schema: ApiErrorSchema } }
+    },
+    409: {
+      description: "FEDERATED_IDENTITY_IN_USE (provider account owned by someone else, or this user already has a different account of this provider), FEDERATED_LINK_AUTH_STATE_CHANGED (fresh User re-read found the session inactive or authVersion changed since link-start), or FEDERATED_LINK_NOT_LINKED (an already-consumed replay whose original insert has not landed) \u2014 no other conflict code exists.",
+      content: { "application/json": { schema: CompleteProviderLinkConflictErrorSchema } }
+    },
     500: {
       description: "Internal server error",
       content: { "application/json": { schema: InternalServerErrorSchema } }
@@ -6233,7 +6317,7 @@ var callbackFederatedProviderRoute = createRoute29({
   },
   responses: {
     302: {
-      description: "Redirect to the trusted web login/complete page on success, or back to the trusted web /login on failure"
+      description: "Ordinary sign-in: redirect to the trusted web login/complete page on success, or back to the trusted web /login on failure. Link flow (query `state` in the reserved crowilnk_ namespace): success redirects to `/me?provider=<name>&link_completion=<code>` (provider + completion code ONLY); failure redirects to `/me?provider=<name>&link=link_failed` (provider + the generic marker ONLY \u2014 never a completion code, never accountLabel, never the underlying reason)."
     },
     404: {
       description: "Unknown or unconfigured provider (also used when trusted origins cannot be resolved)",
@@ -6278,7 +6362,9 @@ var federatedAuthRoutes = {
   callbackFederatedProviderRoute,
   federatedHandoffRoute,
   listLinkedAuthProvidersRoute,
-  createAuthProviderLinkGrantRoute,
+  startProviderLinkRoute,
+  getProviderLinkCompletionRoute,
+  completeProviderLinkRoute,
   unlinkAuthProviderRoute
 };
 
@@ -7214,7 +7300,7 @@ var lateContractApp = new OpenAPIHono().openapi(draftRoutes.createDraftRoute, (c
 var adminSettingsContractApp = new OpenAPIHono().openapi(adminAppRoutes.getAppSettingsRoute, (c) => c.json(stubGetAppSettings, 200)).openapi(adminAppRoutes.updateAppSettingsRoute, (c) => c.json(stubUpdateAppSettings, 200)).openapi(adminAuthRoutes.getAuthSettingsRoute, (c) => c.json(stubAuthSettings, 200)).openapi(adminAuthRoutes.updateAuthSettingsRoute, (c) => c.json(stubAuthSettings, 200)).openapi(adminSecurityRoutes.getSecuritySettingsRoute, (c) => c.json(stubSecuritySettings, 200)).openapi(adminSecurityRoutes.updateSecuritySettingsRoute, (c) => c.json(stubSecuritySettings, 200)).openapi(adminMailRoutes.getMailSettingsRoute, (c) => c.json(stubMailSettings, 200)).openapi(adminMailRoutes.updateMailSettingsRoute, (c) => c.json(stubUpdateMailSettings, 200)).openapi(adminMailRoutes.sendTestMailRoute, (c) => c.json(stubSendTestMail, 200)).openapi(adminStorageRoutes.getStorageStatusRoute, (c) => c.json(stubStorageStatus, 200)).openapi(adminSearchRoutes.getSearchStatusRoute, (c) => c.json(stubSearchStatus, 200));
 var adminUsersPluginsContractApp = new OpenAPIHono().openapi(adminUsersRoutes.listUsersRoute, (c) => c.json(stubListAdminUsers, 200)).openapi(adminUsersRoutes.searchUsersByEmailRoute, (c) => c.json(stubSearchAdminUsersByEmail, 200)).openapi(adminUsersRoutes.pendingUsersCountRoute, (c) => c.json(stubPendingUsersCount, 200)).openapi(adminUsersRoutes.inviteUsersRoute, (c) => c.json(stubInviteUsers, 200)).openapi(adminUsersRoutes.editUserRoute, (c) => c.json(stubAdminUserMutation, 200)).openapi(adminUsersRoutes.makeAdminRoute, (c) => c.json(stubAdminUserMutation, 200)).openapi(adminUsersRoutes.removeFromAdminRoute, (c) => c.json(stubAdminUserMutation, 200)).openapi(adminUsersRoutes.activateUserRoute, (c) => c.json(stubAdminUserMutation, 200)).openapi(adminUsersRoutes.suspendUserRoute, (c) => c.json(stubAdminUserMutation, 200)).openapi(adminUsersRoutes.resetPasswordRoute, (c) => c.json(stubResetPassword, 200)).openapi(adminUsersRoutes.resendInviteRoute, (c) => c.json(stubAdminUserMutation, 200)).openapi(adminUsersRoutes.updateUserEmailRoute, (c) => c.json(stubAdminUserMutation, 200)).openapi(adminUsersRoutes.unlinkUserIdentityRoute, (c) => c.json(stubUnlinkUserIdentity, 200)).openapi(adminUsersRoutes.deleteUserRoute, (c) => c.json(stubDeleteAdminUser, 200)).openapi(adminPluginsRoutes.listPluginsRoute, (c) => c.json(stubListPlugins, 200)).openapi(adminPluginsRoutes.getPluginConfigRoute, (c) => c.json(stubPluginConfig, 200)).openapi(adminPluginsRoutes.updatePluginConfigRoute, (c) => c.json(stubUpdatePluginConfig, 200)).openapi(adminPluginsRoutes.getPluginReadinessRoute, (c) => c.json(stubPluginReadiness, 200)).openapi(adminPluginsRoutes.clearRenderCacheAllRoute, (c) => c.json(stubClearRenderCache, 200)).openapi(adminPluginsRoutes.clearRenderCachePluginRoute, (c) => c.json(stubClearRenderCache, 200));
 var oauthContractApp = new OpenAPIHono().openapi(oauthRoutes.authorizeRoute, (c) => c.json(stubAuthorize, 200)).openapi(oauthRoutes.tokenRoute, (c) => c.json(stubToken, 200)).openapi(oauthRoutes.revokeRoute, (c) => c.json(stubRevoke, 200)).openapi(oauthRoutes.discoveryRoute, (c) => c.json(stubDiscovery, 200)).openapi(oauthRoutes.deviceAuthorizeRoute, (c) => c.json(stubDeviceAuthorize, 200)).openapi(oauthRoutes.deviceInfoRoute, (c) => c.json(stubDeviceInfo, 200)).openapi(oauthRoutes.deviceVerifyRoute, (c) => c.json(stubDeviceVerify, 200)).openapi(oauthRoutes.clientInfoRoute, (c) => c.json(stubClientInfo, 200));
-var federatedAuthContractApp = new OpenAPIHono().openapi(federatedAuthRoutes.listFederatedProvidersRoute, (c) => c.json(stubProviderList, 200)).openapi(federatedAuthRoutes.startFederatedProviderRoute, (c) => c.redirect("", 302)).openapi(federatedAuthRoutes.callbackFederatedProviderRoute, (c) => c.redirect("", 302)).openapi(federatedAuthRoutes.federatedHandoffRoute, (c) => c.json(stubTokens, 200)).openapi(federatedAuthRoutes.listLinkedAuthProvidersRoute, (c) => c.json({ identities: [] }, 200)).openapi(federatedAuthRoutes.createAuthProviderLinkGrantRoute, (c) => c.json({ linkGrant: "" }, 200)).openapi(federatedAuthRoutes.unlinkAuthProviderRoute, (c) => c.body(null, 204));
+var federatedAuthContractApp = new OpenAPIHono().openapi(federatedAuthRoutes.listFederatedProvidersRoute, (c) => c.json(stubProviderList, 200)).openapi(federatedAuthRoutes.startFederatedProviderRoute, (c) => c.redirect("", 302)).openapi(federatedAuthRoutes.callbackFederatedProviderRoute, (c) => c.redirect("", 302)).openapi(federatedAuthRoutes.federatedHandoffRoute, (c) => c.json(stubTokens, 200)).openapi(federatedAuthRoutes.listLinkedAuthProvidersRoute, (c) => c.json({ identities: [] }, 200)).openapi(federatedAuthRoutes.startProviderLinkRoute, (c) => c.json({ authorizationUrl: "" }, 200)).openapi(federatedAuthRoutes.getProviderLinkCompletionRoute, (c) => c.json({ provider: "" }, 200)).openapi(federatedAuthRoutes.completeProviderLinkRoute, (c) => c.json({ result: "linked" }, 200)).openapi(federatedAuthRoutes.unlinkAuthProviderRoute, (c) => c.body(null, 204));
 var federatedRegistrationContractApp = new OpenAPIHono().openapi(federatedRegistrationRoutes.getFederatedRegistrationRoute, (c) => c.json(stubFederatedRegistrationSnapshot, 200)).openapi(federatedRegistrationRoutes.submitFederatedRegistrationRoute, (c) => c.json({ status: "approval_required" }, 200)).openapi(federatedRegistrationRoutes.logoutFederatedRegistrationRoute, (c) => c.body(null, 204));
 var createClient = (baseUrl, options = {}) => hc(baseUrl, {
   headers: options.headers,
@@ -7487,6 +7573,8 @@ export {
   CommentInvalidRequestErrorSchema,
   CommentNotFoundErrorSchema,
   CommentSchema,
+  CompleteProviderLinkConflictErrorSchema,
+  CompleteProviderLinkResponseSchema,
   ConfigReadinessIssueSchema,
   ConfigReadinessResponseSchema,
   ConfirmEmailChangeRequestSchema,
@@ -7499,8 +7587,6 @@ export {
   CreateAdminResponseSchema,
   CreateDraftRequestSchema,
   CreateDraftResponseSchema,
-  CreateLinkGrantRequestSchema,
-  CreateLinkGrantResponseSchema,
   CreatePageRequestSchema,
   CrowiCodeSidecarSchema,
   CrowiDiagramNodeSchema,
@@ -7591,6 +7677,8 @@ export {
   LanguageSchema,
   LikerSchema,
   LikersResponseSchema,
+  LinkCompletionCodeSchema,
+  LinkCompletionConsumedErrorSchema,
   LinkedAuthProviderListResponseSchema,
   ListAccessTokensResponseSchema,
   ListAdminUsersRequestSchema,
@@ -7655,6 +7743,7 @@ export {
   PasswordErrorResponseSchema,
   PasswordUpdateSuccessSchema,
   PastAttachmentUsageSchema,
+  PendingLinkCompletionResponseSchema,
   PendingUsersCountResponseSchema,
   PictureUploadResponseSchema,
   PluginAdminPlacementSchema,
@@ -7734,6 +7823,7 @@ export {
   ShikiTokenLinesSchema,
   ShikiTokenSchema,
   ShikiTokenStyleSchema,
+  StartProviderLinkResponseSchema,
   StorageDriverEntrySchema,
   SuccessResponseSchema,
   ThemeSchema,
@@ -7822,10 +7912,10 @@ export {
   clearRenderCachePluginRoute,
   clientInfoRoute,
   commentRoutes,
+  completeProviderLinkRoute,
   confirmEmailChangeRoute,
   createAccessTokenRoute,
   createAdminRoute,
-  createAuthProviderLinkGrantRoute,
   createClient,
   createDraftRoute,
   createPageRoute,
@@ -7863,6 +7953,7 @@ export {
   getPluginReadinessRoute,
   getPresenceTokenRoute,
   getProfileRoute,
+  getProviderLinkCompletionRoute,
   getRevisionRoute,
   getRevisionsRoute,
   getSearchStatusRoute,
@@ -7936,6 +8027,7 @@ export {
   setPageGrantRoute,
   setWatchStatusRoute,
   startFederatedProviderRoute,
+  startProviderLinkRoute,
   stripKnownHtmlTags,
   submitFederatedRegistrationRoute,
   suspendUserRoute,