chore(core): add comments

packages/core/src/env-set/GlobalValues.ts

@@ -14,10 +14,42 @@ export default class GlobalValues {
   public readonly httpsKey = process.env.HTTPS_KEY_PATH;
   public readonly isHttpsEnabled = Boolean(this.httpsCert && this.httpsKey);
 
+  /**
+   * The UrlSet with no prefix for Logto core service. It serves requests to the OIDC Provider and Management APIs
+   * from all tenants.
+   *
+   * Especially, a glob (`*`) is allowed for the hostname of its property `endpoint` to indicate if the domain-based multi-tenancy (DBMT)
+   * is enabled which affects some critical behaviors of Logto.
+   *
+   * **When DBMT is enabled**
+   *
+   * - For non-admin tenants, tenant endpoint will be generated by replacing the glob in the `urlSet.endpoint`.
+   * - For admin tenant, if `adminUrlSet` has no endpoint available, tenant endpoint will be generated by replacing the glob in the `urlSet.endpoint`.
+   * - Admin Console will NOT be served under admin tenant since the cloud service will do.
+   * - Incoming requests will use glob matching to parse the tenant ID from the request URL.
+   *
+   * **When DBMT is disabled**
+   *
+   * - For non-admin tenants, tenant endpoint will always be `urlSet.endpoint`.
+   * - For admin tenant, tenant endpoint will always be `adminUrlSet.endpoint`.
+   * - Admin Console will be served under admin tenant.
+   * - Incoming requests will check whether the URL matches adminUrlSet.endpoint, which indicates the admin tenant ID. If there is no match, the default tenant ID will be used.
+   */
   public readonly urlSet = new UrlSet(this.isHttpsEnabled, 3001);
+  /**
+   * The UrlSet with prefix `ADMIN_` for Logto admin tenant. To completely disable it, set `ADMIN_DISABLE_LOCALHOST` to a truthy value and leave `ADMIN_ENDPOINT` unset.
+   *
+   * Should be disabled on the cloud.
+   *
+   * @see urlSet For mutual effects between these two sets.
+   */
   public readonly adminUrlSet = new UrlSet(this.isHttpsEnabled, 3002, 'ADMIN_');
+  /**
+   * The UrlSet with prefix `CLOUD_` for Logto cloud service. It affects Admin Console Redirect URIs and some CORS configuration.
+   */
   public readonly cloudUrlSet = new UrlSet(this.isHttpsEnabled, 3003, 'CLOUD_');
 
+  /** @see urlSet For detailed explanation. */
   public readonly isDomainBasedMultiTenancy = this.urlSet.endpoint.hostname.includes('*');
 
   // eslint-disable-next-line unicorn/consistent-function-scoping

packages/core/src/env-set/UrlSet.ts

@@ -1,11 +1,30 @@
 import { deduplicate, getEnv, trySafe, yes } from '@silverhand/essentials';
 
+/**
+ * A class to store a set of URLs which may include a localhost URL and/or a custom domain URL.
+ *
+ * It's useful for aggregating URLs for the same purpose, e.g. to serve the core service.
+ */
 export default class UrlSet {
   readonly #port = Number(getEnv(this.envPrefix + 'PORT') || this.defaultPort);
   readonly #endpoint = getEnv(this.envPrefix + 'ENDPOINT');
 
   public readonly isLocalhostDisabled = yes(getEnv(this.envPrefix + 'DISABLE_LOCALHOST'));
 
+  /**
+   * Construct a new UrlSet instance by reading the following env variables:
+   *
+   * - `${envPrefix}PORT` for getting the port number to listen; fall back to `defaultPort` if not found.
+   * - `${envPrefix}ENDPOINT` for the custom endpoint. The value keeps raw and does not affected by `isHttpEnabled` or `envPrefix`.
+   * - `${envPrefix}DISABLE_LOCALHOST` for disabling (or removing) localhost in the UrlSet if it's truthy (`1`, `true`, `yes`).
+   *
+   * Note: The constructor will take the parameters and read all corresponding env variables instantly,
+   * thus instance properties will NOT change afterwards.
+   *
+   * @param isHttpsEnabled Indicates if Node-based HTTPS is enabled. It ONLY affects localhost URL protocol.
+   * @param defaultPort The port number to fall back if no env variable found for specifying the port to listen.
+   * @param envPrefix The prefix to add for all env variables, i.e. `PORT`, `ENDPOINT`, and `DISABLE_LOCALHOST`.
+   */
   constructor(
     public readonly isHttpsEnabled: boolean,
     protected readonly defaultPort: number,

packages/core/src/env-set/index.ts

@@ -29,6 +29,7 @@ export enum AdminApps {
 }
 
 export class EnvSet {
+  /** The value set for global configurations.  */
   static values = new GlobalValues();
 
   static get isTest() {

packages/core/src/middleware/koa-auth/utils.ts

@@ -27,7 +27,7 @@ export const getAdminTenantTokenValidationSet = async (): Promise<{
   keys: JWK[];
   issuer: string[];
 }> => {
-  const { isDomainBasedMultiTenancy, urlSet, adminUrlSet } = EnvSet.values;
+  const { isDomainBasedMultiTenancy, adminUrlSet } = EnvSet.values;
 
   if (!isDomainBasedMultiTenancy && adminUrlSet.deduplicated().length === 0) {
     return { keys: [], issuer: [] };

packages/core/src/oidc/adapter.ts

@@ -18,24 +18,24 @@ import { getConstantClientMetadata } from './utils.js';
  * as Admin Console is attached to the admin tenant in OSS and its endpoints are dynamic (from env variable).
  */
 const transpileMetadata = (clientId: string, data: AllClientMetadata): AllClientMetadata => {
+  if (clientId !== adminConsoleApplicationId) {
+    return data;
+  }
+
   const { adminUrlSet, cloudUrlSet } = EnvSet.values;
   const urls = [
     ...adminUrlSet.deduplicated().map((url) => appendPath(url, '/console').toString()),
     ...cloudUrlSet.deduplicated().map(String),
   ];
 
-  if (clientId === adminConsoleApplicationId) {
-    return {
-      ...data,
-      redirect_uris: [
-        ...(data.redirect_uris ?? []),
-        ...urls.map((url) => appendPath(url, '/callback').toString()),
-      ],
-      post_logout_redirect_uris: [...(data.post_logout_redirect_uris ?? []), ...urls],
-    };
-  }
-
-  return data;
+  return {
+    ...data,
+    redirect_uris: [
+      ...(data.redirect_uris ?? []),
+      ...urls.map((url) => appendPath(url, '/callback').toString()),
+    ],
+    post_logout_redirect_uris: [...(data.post_logout_redirect_uris ?? []), ...urls],
+  };
 };
 
 const buildDemoAppClientMetadata = (envSet: EnvSet): AllClientMetadata => {