chore: add SAML app API docs

packages/core/src/routes/saml-application/anonymous.ts

@@ -16,17 +16,15 @@
 import assertThat from '#src/utils/assert-that.js';
 import { getConsoleLogFromContext } from '#src/utils/console.js';
 
-const samlApplicationSignInCallbackQueryParametersGuard = z.union([
-  z.object({
+const samlApplicationSignInCallbackQueryParametersGuard = z
+  .object({
     code: z.string(),
-    state: z.string().optional(),
-    redirectUri: z.string().optional(),
-  }),
-  z.object({
+    state: z.string(),
+    redirectUri: z.string(),
     error: z.string(),
-    error_description: z.string().optional(),
-  }),
-]);
+    error_description: z.string(),
+  })
+  .partial();
 
 export default function samlApplicationAnonymousRoutes<T extends AnonymousRouter>(
   ...[router, { id: tenantId, libraries, queries, envSet }]: RouterInitArgs<T>
@@ -70,28 +68,71 @@
       status: [200, 400, 404],
     }),
     koaAuditLog(queries),
+    // eslint-disable-next-line complexity
     async (ctx, next) => {
       const consoleLog = getConsoleLogFromContext(ctx);
       const {
         params: { id },
         query,
       } = ctx.guard;
 
-      const log = ctx.createLog('SamlApplication.Callback');
+      /**
+       * When generating swagger.json, we build path/query guards and verify whether the query/path guard is an instance of ZodObject. Previously, our query guard was a Union of Zod Objects, which failed the validation. Now, we directly use ZodObject guards and perform additional validations within the API.
+       */
+      /* === query guard === */
+      // Validate query parameters
+      if (!query.code && !query.error) {
+        throw new RequestError({
+          code: 'guard.invalid_input',
+          message: 'Either code or error must be present',
+          type: 'query',
+        });
+      }
 
-      log.append({
-        query,
-        applicationId: id,
-      });
+      // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+      if (query.code && (query.error || query.error_description)) {
+        throw new RequestError({
+          code: 'guard.invalid_input',
+          type: 'query',
+          message: 'Cannot have both code and error fields',
+        });
+      }
+
+      // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+      if (query.error && (query.code || query.state || query.redirectUri)) {
+        throw new RequestError({
+          code: 'guard.invalid_input',
+          type: 'query',
+          message: 'When error is present, only error_description is allowed',
+        });
+      }
 
       // Handle error in query parameters
-      if ('error' in query) {
+      if (query.error) {
         throw new RequestError({
           code: 'oidc.invalid_request',
           message: query.error_description,
+          type: 'query',
         });
       }
 
+      assertThat(
+        query.code,
+        new RequestError({
+          code: 'guard.invalid_input',
+          type: 'query',
+          message: '`code` is required.',
+        })
+      );
+      /* === End query guard === */
+
+      const log = ctx.createLog('SamlApplication.Callback');
+
+      log.append({
+        query,
+        applicationId: id,
+      });
+
       const details = await getSamlApplicationDetailsById(id);
       const samlApplication = new SamlApplication(details, id, envSet.oidc.issuer, tenantId);