@logto/core-kit 2.10.0 → 2.12.0

package/lib/email-blocklist.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Validates an email blocklist item.
+ *
+ * An item can be either a full email address (`foo@example.com`) or a domain entry
+ * prefixed with `@` (`@example.com`). `*` can be used inside the local part or
+ * domain while keeping the same email/domain shapes.
+ */
+export declare const isEmailBlocklistItem: (value: string) => boolean;
+/**
+ * Checks whether an email address matches an email blocklist item.
+ *
+ * Matching is case-insensitive. Domain items (`@example.com`) match only the email
+ * domain, while full email items match the complete email address.
+ */
+export declare const matchesEmailBlocklistItem: (item: string, email: string) => boolean;

package/lib/email-blocklist.js

@@ -0,0 +1,65 @@
+import { emailOrEmailDomainRegEx } from './regex.js';
+const wildcard = '*';
+const emailSeparator = '@';
+const domainSeparator = '.';
+const whitespaceRegEx = /\s/u;
+const wildcardOnlyDomainRegEx = /^[*.]+$/u;
+const hasWildcard = (value) => value.includes(wildcard);
+const escapeRegExp = (value) => value.replaceAll(/[.+?^${}()|[\]\\]/gu, '\\$&');
+const buildWildcardRegExp = (pattern) => new RegExp(`^${escapeRegExp(pattern).replaceAll(wildcard, '.*')}$`, 'u');
+const isValidWildcardLocalPart = (localPart) => localPart.length > 0 && !localPart.includes(emailSeparator) && !whitespaceRegEx.test(localPart);
+const isValidWildcardDomain = (domain) => domain.length > 0 &&
+    domain.includes(domainSeparator) &&
+    !domain.includes(emailSeparator) &&
+    !domain.includes(`${domainSeparator}${domainSeparator}`) &&
+    !domain.startsWith(domainSeparator) &&
+    !domain.endsWith(domainSeparator) &&
+    !whitespaceRegEx.test(domain) &&
+    !wildcardOnlyDomainRegEx.test(domain);
+/**
+ * Validates an email blocklist item.
+ *
+ * An item can be either a full email address (`foo@example.com`) or a domain entry
+ * prefixed with `@` (`@example.com`). `*` can be used inside the local part or
+ * domain while keeping the same email/domain shapes.
+ */
+export const isEmailBlocklistItem = (value) => {
+    if (!hasWildcard(value)) {
+        return emailOrEmailDomainRegEx.test(value);
+    }
+    if (whitespaceRegEx.test(value)) {
+        return false;
+    }
+    if (value.startsWith(emailSeparator)) {
+        return isValidWildcardDomain(value.slice(1));
+    }
+    const emailParts = value.split(emailSeparator);
+    if (emailParts.length !== 2) {
+        return false;
+    }
+    const [localPart, domain] = emailParts;
+    return (localPart !== undefined &&
+        domain !== undefined &&
+        isValidWildcardLocalPart(localPart) &&
+        isValidWildcardDomain(domain));
+};
+/**
+ * Checks whether an email address matches an email blocklist item.
+ *
+ * Matching is case-insensitive. Domain items (`@example.com`) match only the email
+ * domain, while full email items match the complete email address.
+ */
+export const matchesEmailBlocklistItem = (item, email) => {
+    const normalizedItem = item.toLowerCase();
+    const normalizedEmail = email.toLowerCase();
+    const domain = normalizedEmail.split(emailSeparator)[1];
+    if (normalizedItem.startsWith(emailSeparator)) {
+        return Boolean(domain &&
+            (hasWildcard(normalizedItem.slice(1))
+                ? buildWildcardRegExp(normalizedItem.slice(1)).test(domain)
+                : domain === normalizedItem.slice(1)));
+    }
+    return hasWildcard(normalizedItem)
+        ? buildWildcardRegExp(normalizedItem).test(normalizedEmail)
+        : normalizedEmail === normalizedItem;
+};

package/lib/index.d.ts

@@ -1,7 +1,9 @@
 export * from './utils/index.js';
 export * from './custom-ui-csp.js';
+export * from './email-blocklist.js';
 export * from './regex.js';
 export * from './openid.js';
 export * from './models/index.js';
 export * from './http.js';
 export * from './password-policy.js';
+export * from './username-policy.js';

package/lib/index.js

@@ -1,7 +1,9 @@
 export * from './utils/index.js';
 export * from './custom-ui-csp.js';
+export * from './email-blocklist.js';
 export * from './regex.js';
 export * from './openid.js';
 export * from './models/index.js';
 export * from './http.js';
 export * from './password-policy.js';
+export * from './username-policy.js';

package/lib/regex.js

@@ -1,6 +1,6 @@
 export const emailRegEx = /^\S+@\S+\.\S+$/;
 /** Validates full email address or email domain. */
-export const emailOrEmailDomainRegEx = /^\S+@\S+\.\S+|^@\S+\.\S+$/;
+export const emailOrEmailDomainRegEx = /^(?:[^\s@]+@[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+|@[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+)$(?![\s\S])/u;
 export const phoneRegEx = /^\d+$/;
 export const phoneInputRegEx = /^\+?[\d-( )]+$/;
 export const usernameRegEx = /^[A-Z_a-z]\w*$/;

package/lib/username-policy.d.ts

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+/** Per-tenant username policy: case sensitivity, length bounds, and allowed character classes. */
+export type UsernamePolicy = {
+    caseSensitive: boolean;
+    /** Integer in [1, 128], inclusive. */
+    minLength: number;
+    /** Integer in [1, 128], inclusive. Must be >= minLength. */
+    maxLength: number;
+    /** At least one of lowercase, uppercase, or underscore must be enabled (see usernamePolicyGuard). */
+    allowedChars: {
+        lowercase: boolean;
+        uppercase: boolean;
+        numbers: boolean;
+        underscore: boolean;
+    };
+};
+export declare const usernamePolicyGuard: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    caseSensitive: z.ZodBoolean;
+    minLength: z.ZodNumber;
+    maxLength: z.ZodNumber;
+    allowedChars: z.ZodObject<{
+        lowercase: z.ZodBoolean;
+        uppercase: z.ZodBoolean;
+        numbers: z.ZodBoolean;
+        underscore: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        lowercase: boolean;
+        uppercase: boolean;
+        numbers: boolean;
+        underscore: boolean;
+    }, {
+        lowercase: boolean;
+        uppercase: boolean;
+        numbers: boolean;
+        underscore: boolean;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    caseSensitive: boolean;
+    minLength: number;
+    maxLength: number;
+    allowedChars: {
+        lowercase: boolean;
+        uppercase: boolean;
+        numbers: boolean;
+        underscore: boolean;
+    };
+}, {
+    caseSensitive: boolean;
+    minLength: number;
+    maxLength: number;
+    allowedChars: {
+        lowercase: boolean;
+        uppercase: boolean;
+        numbers: boolean;
+        underscore: boolean;
+    };
+}>, {
+    caseSensitive: boolean;
+    minLength: number;
+    maxLength: number;
+    allowedChars: {
+        lowercase: boolean;
+        uppercase: boolean;
+        numbers: boolean;
+        underscore: boolean;
+    };
+}, {
+    caseSensitive: boolean;
+    minLength: number;
+    maxLength: number;
+    allowedChars: {
+        lowercase: boolean;
+        uppercase: boolean;
+        numbers: boolean;
+        underscore: boolean;
+    };
+}>, {
+    caseSensitive: boolean;
+    minLength: number;
+    maxLength: number;
+    allowedChars: {
+        lowercase: boolean;
+        uppercase: boolean;
+        numbers: boolean;
+        underscore: boolean;
+    };
+}, {
+    caseSensitive: boolean;
+    minLength: number;
+    maxLength: number;
+    allowedChars: {
+        lowercase: boolean;
+        uppercase: boolean;
+        numbers: boolean;
+        underscore: boolean;
+    };
+}>;
+/**
+ * Mirrors current username behavior so the policy is a no-op when unset: `usernameRegEx` charset
+ * (all classes), length 1-128 (`z.string().min(1)` + `users.username varchar(128)`), case-sensitive
+ * (the `CASE_SENSITIVE_USERNAME` env default).
+ */
+export declare const defaultUsernamePolicy: UsernamePolicy;
+export type UsernameViolation = 'required' | 'starts_with_number' | 'invalid_charset_hard' | 'too_short' | 'too_long' | 'uppercase_not_allowed' | 'lowercase_not_allowed' | 'numbers_not_allowed' | 'underscore_not_allowed';
+/**
+ * The always-on baseline, independent of any per-tenant policy: non-empty, no leading digit, and
+ * matching the existing `usernameRegEx` charset. Applies to admin writes too.
+ */
+export declare const validateUsernameHardFloor: (username: string) => UsernameViolation | undefined;
+/** Returns the first violation against the hard floor then the per-tenant policy, or undefined. */
+export declare const validateUsernameAgainstPolicy: (username: string, policy: UsernamePolicy) => UsernameViolation | undefined;

package/lib/username-policy.js

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import { usernameRegEx } from './regex.js';
+export const usernamePolicyGuard = z
+    .object({
+    caseSensitive: z.boolean(),
+    minLength: z.number().int().min(1).max(128),
+    maxLength: z.number().int().min(1).max(128),
+    allowedChars: z.object({
+        lowercase: z.boolean(),
+        uppercase: z.boolean(),
+        numbers: z.boolean(),
+        underscore: z.boolean(),
+    }),
+})
+    .refine((policy) => policy.minLength <= policy.maxLength, {
+    message: 'Minimum length cannot exceed maximum length.',
+    path: ['maxLength'],
+})
+    // Messages are full sentences on purpose: koaGuard returns them verbatim in the 400 response,
+    // so a Management API caller posting an invalid policy reads exactly why.
+    .refine((policy) => policy.allowedChars.lowercase ||
+    policy.allowedChars.uppercase ||
+    policy.allowedChars.underscore, {
+    message: 'At least one of lowercase, uppercase, or underscore must be enabled. Usernames cannot start with a number, so numbers alone are not allowed.',
+    path: ['allowedChars'],
+});
+/**
+ * Mirrors current username behavior so the policy is a no-op when unset: `usernameRegEx` charset
+ * (all classes), length 1-128 (`z.string().min(1)` + `users.username varchar(128)`), case-sensitive
+ * (the `CASE_SENSITIVE_USERNAME` env default).
+ */
+export const defaultUsernamePolicy = Object.freeze({
+    caseSensitive: true,
+    minLength: 1,
+    maxLength: 128,
+    allowedChars: Object.freeze({
+        lowercase: true,
+        uppercase: true,
+        numbers: true,
+        underscore: true,
+    }),
+});
+/**
+ * The always-on baseline, independent of any per-tenant policy: non-empty, no leading digit, and
+ * matching the existing `usernameRegEx` charset. Applies to admin writes too.
+ */
+export const validateUsernameHardFloor = (username) => {
+    if (username.length === 0) {
+        return 'required';
+    }
+    if (/^\d/.test(username)) {
+        return 'starts_with_number';
+    }
+    if (!usernameRegEx.test(username)) {
+        return 'invalid_charset_hard';
+    }
+};
+const checkAllowedChars = (username, allowedChars) => {
+    if (!allowedChars.uppercase && /[A-Z]/.test(username)) {
+        return 'uppercase_not_allowed';
+    }
+    if (!allowedChars.lowercase && /[a-z]/.test(username)) {
+        return 'lowercase_not_allowed';
+    }
+    if (!allowedChars.numbers && /\d/.test(username)) {
+        return 'numbers_not_allowed';
+    }
+    if (!allowedChars.underscore && username.includes('_')) {
+        return 'underscore_not_allowed';
+    }
+};
+/** Returns the first violation against the hard floor then the per-tenant policy, or undefined. */
+export const validateUsernameAgainstPolicy = (username, policy) => {
+    const hardFloor = validateUsernameHardFloor(username);
+    if (hardFloor) {
+        return hardFloor;
+    }
+    if (username.length < policy.minLength) {
+        return 'too_short';
+    }
+    if (username.length > policy.maxLength) {
+        return 'too_long';
+    }
+    return checkAllowedChars(username, policy.allowedChars);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logto/core-kit",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "author": "Silverhand Inc. <contact@silverhand.io>",
   "homepage": "https://github.com/logto-io/toolkit#readme",
   "repository": {
@@ -36,7 +36,7 @@
     "@silverhand/essentials": "^2.9.1",
     "color": "^4.2.3",
     "@logto/language-kit": "^1.3.0",
-    "@logto/shared": "^3.4.0"
+    "@logto/shared": "^3.4.2"
   },
   "optionalDependencies": {
     "zod": "3.24.3"
@@ -49,14 +49,14 @@
     "@types/color": "^4.0.0",
     "@types/node": "^22.14.0",
     "@types/react": "^18.3.3",
-    "@vitest/coverage-v8": "^3.1.1",
+    "@vitest/coverage-v8": "^4.1.8",
     "eslint": "^8.56.0",
     "lint-staged": "^15.0.0",
-    "postcss": "^8.4.31",
+    "postcss": "^8.5.18",
     "prettier": "^3.5.3",
     "stylelint": "^15.0.0",
     "typescript": "^5.5.3",
-    "vitest": "^3.1.1"
+    "vitest": "^4.1.8"
   },
   "eslintConfig": {
     "extends": "@silverhand"