feat(core): add error_code_key query string param (#6519)

* feat(core): add error_key query string param
feat(core): add error_key query string param
add error_key query string param

 Please enter the commit message for your changes. Lines starting

* chore(core): rename

rename the query param name

* fix(core): safe parse

safe parse

* chore: add changeset

add changeset

.changeset/tiny-fishes-bake.md

@@ -0,0 +1,26 @@
+---
+"@logto/core": patch
+---
+
+introduce new `error_code_key` query parameter in the `koaErrorHandler`.
+
+By default, Logto uses `code` as the error code key in the error response body.
+For some third-party connectors, like Google, `code` is considered as a reserved OIDC key,
+can't be used as the error code key in the error response body. Any oidc error response body containing `code` will be rejected by Google.
+
+To workaround this, we introduce a new `error_code_key` query parameter to customize the error code key in the error response body.
+In the oidc requests, if the `error_code_key` is present in the query string, we will use the value of `error_code_key` as the error code key in the error response body.
+
+example:
+
+```curl
+curl -X POST "http://localhost:3001/oidc/token?error_code_key=error_code"
+```
+
+```json
+{
+  "error_code": "oidc.invalid_grant",
+  "error": "invalid_grant",
+  "error_description": "Invalid value for parameter 'code': 'invalid_code'."
+}
+```

packages/core/src/middleware/koa-oidc-error-handler.ts

@@ -82,6 +82,7 @@ const isSessionNotFound = (description?: string) =>
  * @see {@link errorUris} for the list of error URIs.
  */
 export default function koaOidcErrorHandler<StateT, ContextT>(): Middleware<StateT, ContextT> {
+  // eslint-disable-next-line complexity
   return async (ctx, next) => {
     try {
       await next();
@@ -114,8 +115,23 @@ export default function koaOidcErrorHandler<StateT, ContextT>(): Middleware<Stat
           : `oidc.${data.error}`;
         const uri = errorUris[data.error];
 
+        // Parse the `error_code_key` from the query string.
+        // This is used to customize the error key in the response body.
+        // For some third-party connectors, like Google, `code` is considered as a reserved OIDC key,
+        // can't be used as the error code key in the error response body.
+        // We add `error_code_key` to the query string to customize the error key in the response body.
+        const errorKeyQueryResult = z
+          .object({
+            error_code_key: z.string().optional(),
+          })
+          .safeParse(ctx.query);
+
+        const errorKey = errorKeyQueryResult.success
+          ? errorKeyQueryResult.data.error_code_key ?? 'code'
+          : 'code';
+
         ctx.body = {
-          code,
+          [errorKey]: code,
           message: i18next.t(['errors:' + code, 'errors:oidc.provider_error_fallback'], { code }),
           error_uri: uri,
           ...ctx.body,