@yunsoft/yuncms-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yunsoft Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @yunsoft/yuncms-core
+
+Core services, schema, authentication, permissions, hooks and storage primitives used by YunCMS.
+
+This package is installed by `@yunsoft/yuncms` and `@yunsoft/yuncms-api`. See the [project repository](https://github.com/Yunsoft-Software/yuncms) for architecture and service documentation.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@yunsoft/yuncms-core",
+  "version": "0.1.0",
+  "description": "Core services, schema, authentication, permissions and storage primitives for YunCMS.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Yunsoft-Software/yuncms.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/Yunsoft-Software/yuncms#readme",
+  "bugs": {
+    "url": "https://github.com/Yunsoft-Software/yuncms/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "3.1100.0",
+    "mysql2": "3.23.2",
+    "nodemailer": "9.0.3"
+  }
+}

package/src/accountability.js

@@ -0,0 +1,39 @@
+function normalizeIdentity(value) {
+  return value == null ? null : String(value);
+}
+
+export function createAccountability(input = {}) {
+  const accountability = {
+    user: normalizeIdentity(input.user),
+    role: normalizeIdentity(input.role),
+    admin: input.admin === true,
+    public: input.public === true,
+    system: input.system === true,
+  };
+
+  if (accountability.public && (accountability.user || accountability.admin || accountability.system)) {
+    throw new Error('Public accountability cannot also be user, admin, or system accountability');
+  }
+
+  if (accountability.system && !accountability.admin) {
+    throw new Error('System accountability must explicitly be administrative');
+  }
+
+  return Object.freeze(accountability);
+}
+
+export function createPublicAccountability({ role = null } = {}) {
+  return createAccountability({ role, public: true });
+}
+
+export function createSystemAccountability() {
+  return createAccountability({ admin: true, system: true });
+}
+
+export function requireAccountability(accountability) {
+  if (!accountability || typeof accountability !== 'object') {
+    throw new Error('Explicit accountability is required');
+  }
+
+  return accountability;
+}

package/src/advisory-lock.js

@@ -0,0 +1,30 @@
+export async function withAdvisoryLock(pool, lockName, operation, { timeoutSeconds = 10 } = {}) {
+  if (!pool) throw new Error('Database pool is required');
+  if (!lockName || typeof lockName !== 'string') throw new Error('Advisory lock name is required');
+  if (typeof operation !== 'function') throw new Error('Advisory lock operation is required');
+
+  const connection = await pool.getConnection();
+  let acquired = false;
+
+  try {
+    const [rows] = await connection.query('SELECT GET_LOCK(?, ?) AS acquired', [lockName, timeoutSeconds]);
+    acquired = Number(rows?.[0]?.acquired) === 1;
+
+    if (!acquired) {
+      const error = new Error(`Could not acquire advisory lock: ${lockName}`);
+      error.code = 'SCHEMA_LOCK_UNAVAILABLE';
+      throw error;
+    }
+
+    return await operation(connection);
+  } finally {
+    if (acquired) {
+      try {
+        await connection.query('SELECT RELEASE_LOCK(?) AS released', [lockName]);
+      } catch {
+        // Releasing the connection also drops connection-scoped MySQL locks.
+      }
+    }
+    connection.release();
+  }
+}

package/src/auth/password.js

@@ -0,0 +1,100 @@
+import { randomBytes, scrypt as scryptCallback, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+
+const scrypt = promisify(scryptCallback);
+const DEFAULTS = Object.freeze({
+  N: 65_536,
+  r: 8,
+  p: 1,
+  keyLength: 64,
+  saltLength: 16,
+  maxmem: 128 * 1024 * 1024,
+});
+
+function passwordError(message) {
+  const error = new Error(message);
+  error.code = 'INVALID_PASSWORD';
+  return error;
+}
+
+export function assertPasswordInput(password) {
+  if (typeof password !== 'string') throw passwordError('Password must be a string');
+  if (password.length < 8) throw passwordError('Password must contain at least 8 characters');
+  if (password.length > 1024) throw passwordError('Password is too long');
+  return password;
+}
+
+function assertScryptParameters({ N, r, p, keyLength }) {
+  const powerOfTwo = Number.isInteger(N) && N > 1 && (N & (N - 1)) === 0;
+  if (!powerOfTwo || N > 131_072) throw passwordError('Invalid scrypt cost parameter');
+  if (!Number.isInteger(r) || r < 1 || r > 16) throw passwordError('Invalid scrypt block size');
+  if (!Number.isInteger(p) || p < 1 || p > 4) throw passwordError('Invalid scrypt parallelization');
+  if (!Number.isInteger(keyLength) || keyLength < 32 || keyLength > 128) {
+    throw passwordError('Invalid scrypt key length');
+  }
+}
+
+export async function hashPassword(password, options = {}) {
+  assertPasswordInput(password);
+  const params = { ...DEFAULTS, ...options };
+  assertScryptParameters(params);
+  const salt = randomBytes(params.saltLength);
+  const derived = await scrypt(password, salt, params.keyLength, {
+    N: params.N,
+    r: params.r,
+    p: params.p,
+    maxmem: params.maxmem,
+  });
+
+  return [
+    'scrypt',
+    `N=${params.N},r=${params.r},p=${params.p},keyLength=${params.keyLength}`,
+    salt.toString('base64url'),
+    Buffer.from(derived).toString('base64url'),
+  ].join('$');
+}
+
+function parseHash(encoded) {
+  if (typeof encoded !== 'string') return null;
+  const [algorithm, parameterString, saltValue, hashValue, extra] = encoded.split('$');
+  if (algorithm !== 'scrypt' || !parameterString || !saltValue || !hashValue || extra !== undefined) return null;
+
+  const parameters = Object.fromEntries(
+    parameterString.split(',').map((part) => {
+      const [key, value] = part.split('=');
+      return [key, Number(value)];
+    }),
+  );
+
+  const { N, r, p, keyLength } = parameters;
+  try {
+    assertScryptParameters({ N, r, p, keyLength });
+  } catch {
+    return null;
+  }
+
+  try {
+    const salt = Buffer.from(saltValue, 'base64url');
+    const expected = Buffer.from(hashValue, 'base64url');
+    if (salt.length < 8 || salt.length > 64 || expected.length !== keyLength) return null;
+    return { N, r, p, keyLength, salt, expected };
+  } catch {
+    return null;
+  }
+}
+
+export async function verifyPassword(password, encoded) {
+  if (typeof password !== 'string' || password.length > 1024) return false;
+  const parsed = parseHash(encoded);
+  if (!parsed) return false;
+
+  const maxmem = Math.max(DEFAULTS.maxmem, 128 * parsed.N * parsed.r + 1024 * 1024);
+  const derived = Buffer.from(await scrypt(password, parsed.salt, parsed.keyLength, {
+    N: parsed.N,
+    r: parsed.r,
+    p: parsed.p,
+    maxmem,
+  }));
+
+  return derived.length === parsed.expected.length && timingSafeEqual(derived, parsed.expected);
+}

package/src/auth/tokens.js

@@ -0,0 +1,38 @@
+import { createHash, randomBytes } from 'node:crypto';
+
+const PREFIXES = Object.freeze({
+  access: 'yca',
+  refresh: 'ycr',
+  api: 'yct',
+  reset: 'ycp',
+  verify: 'ycv',
+});
+
+export function hashToken(token) {
+  if (typeof token !== 'string' || token.length === 0) {
+    const error = new Error('Token is required');
+    error.code = 'INVALID_TOKEN';
+    throw error;
+  }
+  return createHash('sha256').update(token, 'utf8').digest('hex');
+}
+
+export function createOpaqueToken(type, { bytes = 32 } = {}) {
+  const prefix = PREFIXES[type];
+  if (!prefix) throw new Error(`Unknown token type: ${type}`);
+  if (!Number.isInteger(bytes) || bytes < 24 || bytes > 128) {
+    throw new Error('Token byte length must be between 24 and 128');
+  }
+
+  const token = `${prefix}_${randomBytes(bytes).toString('base64url')}`;
+  return {
+    token,
+    hash: hashToken(token),
+  };
+}
+
+export function tokenType(token) {
+  if (typeof token !== 'string') return null;
+  const prefix = token.slice(0, 3);
+  return Object.entries(PREFIXES).find(([, value]) => value === prefix)?.[0] ?? null;
+}

package/src/auth/users-repository.js

@@ -0,0 +1,25 @@
+export async function readAuthenticationUserByEmail(database, email) {
+  const [rows] = await database.query(
+    `SELECT u.id, u.email, u.password_hash, u.role, u.status, u.email_verified_at,
+            r.admin AS role_admin, r.public AS role_public
+     FROM yuncms_users u
+     LEFT JOIN yuncms_roles r ON r.id = u.role
+     WHERE u.email = ?
+     LIMIT 1`,
+    [email],
+  );
+  return rows[0] ?? null;
+}
+
+export async function readAuthenticationUserById(database, id) {
+  const [rows] = await database.query(
+    `SELECT u.id, u.email, u.password_hash, u.role, u.status, u.email_verified_at,
+            r.admin AS role_admin, r.public AS role_public
+     FROM yuncms_users u
+     LEFT JOIN yuncms_roles r ON r.id = u.role
+     WHERE u.id = ?
+     LIMIT 1`,
+    [id],
+  );
+  return rows[0] ?? null;
+}

package/src/bootstrap.js

@@ -0,0 +1,41 @@
+import { withAdvisoryLock } from './advisory-lock.js';
+import { applyMigrations, assertMigrationsApplied } from './migrations.js';
+import { systemSchemaMigration } from './migrations/0001-system-schema.js';
+import { sessionAccessTokensMigration } from './migrations/0002-session-access-tokens.js';
+import { publicRoleConstraintsMigration } from './migrations/0003-public-role-constraints.js';
+import { authActionTokensMigration } from './migrations/0004-auth-action-tokens.js';
+import { readSchemaVersion } from './schema-version.js';
+
+export const CORE_MIGRATIONS = Object.freeze([
+  systemSchemaMigration,
+  sessionAccessTokensMigration,
+  publicRoleConstraintsMigration,
+  authActionTokensMigration,
+]);
+
+export const REQUIRED_CORE_MIGRATION_IDS = Object.freeze(
+  CORE_MIGRATIONS.map((migration) => migration.id),
+);
+
+export async function bootstrapDatabase(pool, { lockTimeoutSeconds = 10 } = {}) {
+  return withAdvisoryLock(
+    pool,
+    'yuncms:bootstrap',
+    async (connection) => {
+      const migrationResult = await applyMigrations(connection, CORE_MIGRATIONS);
+      const schemaVersion = await readSchemaVersion(connection);
+
+      return {
+        ...migrationResult,
+        schemaVersion,
+      };
+    },
+    { timeoutSeconds: lockTimeoutSeconds },
+  );
+}
+
+export async function assertDatabaseCompatible(pool) {
+  await assertMigrationsApplied(pool, REQUIRED_CORE_MIGRATION_IDS);
+  await readSchemaVersion(pool);
+  return true;
+}

package/src/config.js

@@ -0,0 +1,106 @@
+import { loadEnvFile } from 'node:process';
+
+function readInteger(value, fallback, name, { min = 0, max = Number.MAX_SAFE_INTEGER } = {}) {
+  if (value === undefined || value === '') return fallback;
+
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    throw new Error(`${name} must be an integer between ${min} and ${max}`);
+  }
+
+  return parsed;
+}
+
+function readBoolean(value, fallback = false) {
+  if (value === undefined || value === '') return fallback;
+  if (value === true || value === 'true' || value === '1') return true;
+  if (value === false || value === 'false' || value === '0') return false;
+  throw new Error(`Expected boolean value, received: ${value}`);
+}
+
+function readString(value, fallback = '') {
+  return value === undefined ? fallback : String(value);
+}
+
+export function loadEnvFileIfPresent(path = '.env') {
+  try {
+    loadEnvFile(path);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export function loadConfig(env = process.env) {
+  const serverPort = readInteger(env.PORT, 3008, 'PORT', { min: 1, max: 65535 });
+  const studioOrigin = readString(env.STUDIO_ORIGIN, `http://localhost:${serverPort}`);
+
+  return {
+    server: {
+      host: readString(env.HOST, '127.0.0.1'),
+      port: serverPort,
+      studioOrigin,
+    },
+    logging: {
+      level: readString(env.LOG_LEVEL, 'info'),
+    },
+    database: {
+      host: readString(env.DB_HOST, '127.0.0.1'),
+      port: readInteger(env.DB_PORT, 3306, 'DB_PORT', { min: 1, max: 65535 }),
+      database: readString(env.DB_DATABASE, 'yuncms'),
+      user: readString(env.DB_USER, 'yuncms'),
+      password: readString(env.DB_PASSWORD, ''),
+      connectionLimit: readInteger(env.DB_CONNECTION_LIMIT, 10, 'DB_CONNECTION_LIMIT', { min: 1, max: 1000 }),
+      ssl: readBoolean(env.DB_SSL, false),
+    },
+    storage: {
+      localRoot: readString(env.FILES_LOCAL_ROOT, '.yuncms/uploads'),
+      maxUploadBytes: readInteger(env.FILES_MAX_UPLOAD_BYTES, 25 * 1024 * 1024, 'FILES_MAX_UPLOAD_BYTES', {
+        min: 1,
+        max: 1024 * 1024 * 1024,
+      }),
+      s3: {
+        bucket: readString(env.S3_BUCKET, ''),
+        region: readString(env.S3_REGION, 'us-east-1'),
+        endpoint: readString(env.S3_ENDPOINT, '') || null,
+        accessKeyId: readString(env.S3_ACCESS_KEY_ID, '') || null,
+        secretAccessKey: readString(env.S3_SECRET_ACCESS_KEY, '') || null,
+        forcePathStyle: readBoolean(env.S3_FORCE_PATH_STYLE, false),
+      },
+    },
+    audit: {
+      retentionDays: readInteger(env.AUDIT_RETENTION_DAYS, 90, 'AUDIT_RETENTION_DAYS', {
+        min: 1,
+        max: 3650,
+      }),
+      cleanupBatchSize: readInteger(env.AUDIT_CLEANUP_BATCH_SIZE, 1000, 'AUDIT_CLEANUP_BATCH_SIZE', {
+        min: 1,
+        max: 5000,
+      }),
+      cleanupMaxBatches: readInteger(env.AUDIT_CLEANUP_MAX_BATCHES, 100, 'AUDIT_CLEANUP_MAX_BATCHES', {
+        min: 1,
+        max: 1000,
+      }),
+    },
+    mail: {
+      host: readString(env.SMTP_HOST, ''),
+      port: readInteger(env.SMTP_PORT, 587, 'SMTP_PORT', { min: 1, max: 65535 }),
+      secure: readBoolean(env.SMTP_SECURE, false),
+      user: readString(env.SMTP_USER, '') || null,
+      password: readString(env.SMTP_PASSWORD, '') || null,
+      from: readString(env.SMTP_FROM, '') || null,
+    },
+    auth: {
+      publicUrl: readString(env.AUTH_PUBLIC_URL, studioOrigin).replace(/\/$/, ''),
+      rateLimit: {
+        loginWindowMs: readInteger(env.AUTH_LOGIN_RATE_WINDOW_MS, 60_000, 'AUTH_LOGIN_RATE_WINDOW_MS', { min: 1000, max: 24 * 60 * 60 * 1000 }),
+        loginMax: readInteger(env.AUTH_LOGIN_RATE_MAX, 10, 'AUTH_LOGIN_RATE_MAX', { min: 1, max: 100_000 }),
+        refreshWindowMs: readInteger(env.AUTH_REFRESH_RATE_WINDOW_MS, 60_000, 'AUTH_REFRESH_RATE_WINDOW_MS', { min: 1000, max: 24 * 60 * 60 * 1000 }),
+        refreshMax: readInteger(env.AUTH_REFRESH_RATE_MAX, 30, 'AUTH_REFRESH_RATE_MAX', { min: 1, max: 100_000 }),
+        actionWindowMs: readInteger(env.AUTH_ACTION_RATE_WINDOW_MS, 15 * 60_000, 'AUTH_ACTION_RATE_WINDOW_MS', { min: 1000, max: 24 * 60 * 60 * 1000 }),
+        actionMax: readInteger(env.AUTH_ACTION_RATE_MAX, 5, 'AUTH_ACTION_RATE_MAX', { min: 1, max: 100_000 }),
+      },
+    },
+  };
+}

package/src/context.js

@@ -0,0 +1,33 @@
+import { requireAccountability } from './accountability.js';
+
+export function createRequestContext({
+  accountability,
+  services,
+  database,
+  schema = null,
+  logger = console,
+  env = {},
+  emitter = null,
+  storage = null,
+  permissionCache = new Map(),
+  requestId = null,
+} = {}) {
+  requireAccountability(accountability);
+
+  if (!services) throw new Error('Service registry is required');
+  if (!database) throw new Error('Database handle is required');
+  if (!(permissionCache instanceof Map)) throw new Error('Permission cache must be a Map');
+
+  return Object.freeze({
+    accountability,
+    services,
+    database,
+    schema,
+    logger,
+    env,
+    emitter,
+    storage,
+    permissionCache,
+    requestId,
+  });
+}

package/src/database.js

@@ -0,0 +1,31 @@
+import mysql from 'mysql2/promise';
+
+export function createDatabasePool(config) {
+  if (!config) throw new Error('Database config is required');
+
+  return mysql.createPool({
+    host: config.host,
+    port: config.port,
+    database: config.database,
+    user: config.user,
+    password: config.password,
+    waitForConnections: true,
+    connectionLimit: config.connectionLimit ?? 10,
+    queueLimit: 0,
+    enableKeepAlive: true,
+    keepAliveInitialDelay: 0,
+    supportBigNumbers: true,
+    bigNumberStrings: true,
+    multipleStatements: false,
+    ssl: config.ssl ? { minVersion: 'TLSv1.2' } : undefined,
+  });
+}
+
+export async function pingDatabase(pool) {
+  const [rows] = await pool.query('SELECT 1 AS ok');
+  return Number(rows?.[0]?.ok) === 1;
+}
+
+export async function closeDatabasePool(pool) {
+  if (pool) await pool.end();
+}

package/src/errors.js

@@ -0,0 +1,35 @@
+const MYSQL_ERROR_CODES = {
+  ER_DUP_ENTRY: 'DUPLICATE_KEY',
+  ER_NO_REFERENCED_ROW_2: 'FOREIGN_KEY_MISSING',
+  ER_ROW_IS_REFERENCED_2: 'FOREIGN_KEY_RESTRICTED',
+  ER_LOCK_DEADLOCK: 'DEADLOCK',
+  ER_LOCK_WAIT_TIMEOUT: 'LOCK_WAIT_TIMEOUT',
+  PROTOCOL_CONNECTION_LOST: 'CONNECTION_LOST',
+  ECONNREFUSED: 'CONNECTION_REFUSED',
+};
+
+export class YunCmsDatabaseError extends Error {
+  constructor(code, message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = 'YunCmsDatabaseError';
+    this.code = code;
+    this.mysqlCode = options.mysqlCode ?? null;
+    this.errno = options.errno ?? null;
+  }
+}
+
+export function normalizeDatabaseError(error) {
+  if (error instanceof YunCmsDatabaseError) return error;
+
+  const mappedCode = MYSQL_ERROR_CODES[error?.code] ?? 'DATABASE_ERROR';
+  return new YunCmsDatabaseError(mappedCode, error?.message ?? 'Database operation failed', {
+    cause: error,
+    mysqlCode: error?.code,
+    errno: error?.errno,
+  });
+}
+
+export function isRetryableDatabaseError(error) {
+  const code = error?.code;
+  return code === 'ER_LOCK_DEADLOCK' || code === 'ER_LOCK_WAIT_TIMEOUT' || code === 'DEADLOCK' || code === 'LOCK_WAIT_TIMEOUT';
+}

package/src/field-types.js

@@ -0,0 +1,110 @@
+const TYPE_NAMES = new Set([
+  'integer',
+  'bigint',
+  'decimal',
+  'string',
+  'text',
+  'boolean',
+  'date',
+  'datetime',
+  'timestamp',
+  'json',
+  'uuid',
+]);
+
+function integerOption(value, fallback, { min, max, label }) {
+  const resolved = value ?? fallback;
+  if (!Number.isInteger(resolved) || resolved < min || resolved > max) {
+    throw new Error(`${label} must be an integer between ${min} and ${max}`);
+  }
+  return resolved;
+}
+
+export function assertFieldType(type) {
+  if (!TYPE_NAMES.has(type)) {
+    const error = new Error(`Unsupported field type: ${String(type)}`);
+    error.code = 'UNSUPPORTED_FIELD_TYPE';
+    throw error;
+  }
+  return type;
+}
+
+export function compileFieldColumn(input = {}) {
+  const type = assertFieldType(input.type);
+  const params = [];
+  let sqlType;
+
+  switch (type) {
+    case 'integer':
+      sqlType = 'INT';
+      break;
+    case 'bigint':
+      sqlType = 'BIGINT';
+      break;
+    case 'decimal': {
+      const precision = integerOption(input.precision, 18, { min: 1, max: 65, label: 'Decimal precision' });
+      const scale = integerOption(input.scale, 2, { min: 0, max: 30, label: 'Decimal scale' });
+      if (scale > precision) throw new Error('Decimal scale cannot exceed precision');
+      sqlType = `DECIMAL(${precision}, ${scale})`;
+      break;
+    }
+    case 'string': {
+      const length = integerOption(input.length, 255, { min: 1, max: 4096, label: 'String length' });
+      sqlType = `VARCHAR(${length})`;
+      break;
+    }
+    case 'text':
+      sqlType = 'TEXT';
+      break;
+    case 'boolean':
+      sqlType = 'TINYINT(1)';
+      break;
+    case 'date':
+      sqlType = 'DATE';
+      break;
+    case 'datetime':
+      sqlType = 'DATETIME(3)';
+      break;
+    case 'timestamp':
+      sqlType = 'TIMESTAMP(3)';
+      break;
+    case 'json':
+      sqlType = 'JSON';
+      break;
+    case 'uuid':
+      sqlType = 'CHAR(36)';
+      break;
+    default:
+      throw new Error(`Unsupported field type: ${type}`);
+  }
+
+  let sql = sqlType;
+  sql += input.required === true ? ' NOT NULL' : ' NULL';
+
+  if (Object.hasOwn(input, 'defaultValue')) {
+    if (type === 'text' || type === 'json') {
+      const error = new Error(`Defaults for ${type} fields are postponed in V1`);
+      error.code = 'UNSUPPORTED_FIELD_DEFAULT';
+      throw error;
+    }
+
+    if (input.defaultValue === null) {
+      if (input.required === true) throw new Error('Required fields cannot default to NULL');
+      sql += ' DEFAULT NULL';
+    } else {
+      sql += ' DEFAULT ?';
+      params.push(type === 'boolean' ? (input.defaultValue ? 1 : 0) : input.defaultValue);
+    }
+  }
+
+  return {
+    sql,
+    params,
+    schemaMetadata: {
+      length: type === 'string' ? (input.length ?? 255) : type === 'uuid' ? 36 : undefined,
+      precision: type === 'decimal' ? (input.precision ?? 18) : undefined,
+      scale: type === 'decimal' ? (input.scale ?? 2) : undefined,
+      defaultValue: Object.hasOwn(input, 'defaultValue') ? input.defaultValue : undefined,
+    },
+  };
+}