@yunsoft/yuncms-core 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunsoft/yuncms-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Core services, schema, authentication, permissions and storage primitives for YunCMS.",
   "license": "MIT",
   "type": "module",

package/src/bootstrap.js

@@ -4,13 +4,18 @@ 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 { defaultPublicRoleMigration } from './migrations/0005-default-public-role.js';
+import { studioSettingsMigration } from './migrations/0006-studio-settings.js';
 import { readSchemaVersion } from './schema-version.js';
+import { ensurePublicRole } from './setup.js';
 
 export const CORE_MIGRATIONS = Object.freeze([
   systemSchemaMigration,
   sessionAccessTokensMigration,
   publicRoleConstraintsMigration,
   authActionTokensMigration,
+  defaultPublicRoleMigration,
+  studioSettingsMigration,
 ]);
 
 export const REQUIRED_CORE_MIGRATION_IDS = Object.freeze(
@@ -23,10 +28,17 @@ export async function bootstrapDatabase(pool, { lockTimeoutSeconds = 10 } = {})
     'yuncms:bootstrap',
     async (connection) => {
       const migrationResult = await applyMigrations(connection, CORE_MIGRATIONS);
+      const publicRole = await ensurePublicRole(connection);
       const schemaVersion = await readSchemaVersion(connection);
+      const publicRoleMigrated = migrationResult.newlyApplied.includes(defaultPublicRoleMigration.id);
 
       return {
         ...migrationResult,
+        publicRole: {
+          id: publicRole.id,
+          name: publicRole.name,
+          created: publicRole.created || publicRoleMigrated,
+        },
         schemaVersion,
       };
     },

package/src/config.js

@@ -41,6 +41,7 @@ export function loadConfig(env = process.env) {
       host: readString(env.HOST, '127.0.0.1'),
       port: serverPort,
       studioOrigin,
+      trustProxyHops: readInteger(env.TRUST_PROXY_HOPS, 0, 'TRUST_PROXY_HOPS', { min: 0, max: 10 }),
     },
     logging: {
       level: readString(env.LOG_LEVEL, 'info'),

package/src/index.js

@@ -11,7 +11,12 @@ export {
   requireAccountability,
 } from './accountability.js';
 export { createRequestContext } from './context.js';
-export { createInitialAdmin, findExistingAdmin } from './setup.js';
+export {
+  createInitialAdmin,
+  findExistingAdmin,
+  findPublicRole,
+  ensurePublicRole,
+} from './setup.js';
 export { HookEmitter } from './hooks.js';
 export { createJsonLogger, LEVELS as LOG_LEVELS } from './logger.js';
 export { deleteM2MJunction } from './m2m-lifecycle.js';
@@ -41,6 +46,7 @@ export { RolesService } from './services/roles-service.js';
 export { PermissionsService } from './services/permissions-service.js';
 export { FilesService } from './services/files-service.js';
 export { FileReconciliationService } from './services/file-reconciliation-service.js';
+export { StudioSettingsService, STUDIO_SETTING_DEFAULTS } from './services/studio-settings-service.js';
 export { SchemaMetadataRepository } from './schema-metadata-repository.js';
 export { loadSchemaSnapshot, SchemaCache } from './schema.js';
 export { assertFieldType, compileFieldColumn } from './field-types.js';

package/src/migrations/0005-default-public-role.js

@@ -0,0 +1,16 @@
+export const defaultPublicRoleMigration = {
+  id: '0005-default-public-role',
+  statements: [
+    `INSERT INTO yuncms_roles (id, name, description, admin, public)
+     SELECT UUID(),
+            CASE
+              WHEN EXISTS (SELECT 1 FROM yuncms_roles AS named WHERE named.name = 'Public')
+                THEN CONCAT('Public ', LEFT(REPLACE(UUID(), '-', ''), 8))
+              ELSE 'Public'
+            END,
+            'Unauthenticated public API access. No collection access is granted by default.',
+            0,
+            1
+     WHERE NOT EXISTS (SELECT 1 FROM yuncms_roles AS existing WHERE existing.public = 1)`,
+  ],
+};

package/src/migrations/0006-studio-settings.js

@@ -0,0 +1,20 @@
+export const studioSettingsMigration = {
+  id: '0006-studio-settings',
+  statements: [
+    `CREATE TABLE IF NOT EXISTS yuncms_studio_settings (
+      id TINYINT UNSIGNED NOT NULL PRIMARY KEY,
+      brand_name VARCHAR(100) NOT NULL DEFAULT 'YunCMS',
+      logo_url VARCHAR(512) NOT NULL DEFAULT 'https://yunsoft.com/light-logo.png',
+      accent_color CHAR(7) NOT NULL DEFAULT '#2563eb',
+      theme VARCHAR(16) NOT NULL DEFAULT 'system',
+      default_locale VARCHAR(5) NOT NULL DEFAULT 'en',
+      updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+      CONSTRAINT chk_yuncms_studio_settings_singleton CHECK (id = 1),
+      CONSTRAINT chk_yuncms_studio_settings_theme CHECK (theme IN ('system', 'light', 'dark')),
+      CONSTRAINT chk_yuncms_studio_settings_locale CHECK (default_locale IN ('en', 'tr'))
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`,
+    `INSERT IGNORE INTO yuncms_studio_settings
+      (id, brand_name, logo_url, accent_color, theme, default_locale)
+     VALUES (1, 'YunCMS', 'https://yunsoft.com/light-logo.png', '#2563eb', 'system', 'en')`,
+  ],
+};

package/src/services/collections-service.js

@@ -21,11 +21,15 @@ function assertUserCollectionName(collection) {
   return collection;
 }
 
+function invalidSchemaPayload(message) {
+  const error = new Error(message);
+  error.code = 'INVALID_SCHEMA_PAYLOAD';
+  return error;
+}
+
 function assertCollectionMetadataPatch(patch) {
   if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
-    const error = new Error('Collection metadata patch must be an object');
-    error.code = 'INVALID_SCHEMA_PAYLOAD';
-    throw error;
+    throw invalidSchemaPayload('Collection metadata patch must be an object');
   }
   for (const key of Object.keys(patch)) {
     if (!COLLECTION_METADATA_KEYS.has(key)) {
@@ -35,9 +39,36 @@ function assertCollectionMetadataPatch(patch) {
     }
   }
   if (Object.keys(patch).length === 0) {
-    const error = new Error('Collection metadata patch cannot be empty');
-    error.code = 'INVALID_SCHEMA_PAYLOAD';
-    throw error;
+    throw invalidSchemaPayload('Collection metadata patch cannot be empty');
+  }
+  for (const key of ['singleton', 'hidden']) {
+    if (Object.hasOwn(patch, key) && typeof patch[key] !== 'boolean') {
+      throw invalidSchemaPayload(`Collection ${key} must be a boolean`);
+    }
+  }
+  if (Object.hasOwn(patch, 'note') && patch.note != null && typeof patch.note !== 'string') {
+    throw invalidSchemaPayload('Collection note must be a string or null');
+  }
+  if (Object.hasOwn(patch, 'metadata') && patch.metadata != null && (
+    typeof patch.metadata !== 'object' || Array.isArray(patch.metadata)
+  )) {
+    throw invalidSchemaPayload('Collection metadata must be an object or null');
+  }
+}
+
+function assertCollectionCreateMetadata(input) {
+  for (const key of ['singleton', 'hidden']) {
+    if (Object.hasOwn(input, key) && typeof input[key] !== 'boolean') {
+      throw invalidSchemaPayload(`Collection ${key} must be a boolean`);
+    }
+  }
+  if (Object.hasOwn(input, 'note') && input.note != null && typeof input.note !== 'string') {
+    throw invalidSchemaPayload('Collection note must be a string or null');
+  }
+  if (Object.hasOwn(input, 'metadata') && input.metadata != null && (
+    typeof input.metadata !== 'object' || Array.isArray(input.metadata)
+  )) {
+    throw invalidSchemaPayload('Collection metadata must be an object or null');
   }
 }
 
@@ -59,6 +90,7 @@ export class CollectionsService extends BaseService {
 
   async createOne(input = {}) {
     assertSchemaManager(this.accountability);
+    assertCollectionCreateMetadata(input);
     const collection = assertUserCollectionName(input.collection);
     const primaryKey = input.primaryKey ?? 'id';
 

package/src/services/core-services.js

@@ -10,6 +10,7 @@ import { ItemsService } from './items-service.js';
 import { PermissionsService } from './permissions-service.js';
 import { RelationsService } from './relations-service.js';
 import { RolesService } from './roles-service.js';
+import { StudioSettingsService } from './studio-settings-service.js';
 import { UsersService } from './users-service.js';
 import { createServiceRegistry } from './service-registry.js';
 
@@ -28,5 +29,6 @@ export function createCoreServiceRegistry() {
     PermissionsService,
     FilesService,
     FileReconciliationService,
+    StudioSettingsService,
   });
 }

package/src/services/studio-settings-service.js

@@ -0,0 +1,140 @@
+import { BaseService } from './base-service.js';
+
+const THEMES = new Set(['system', 'light', 'dark']);
+const LOCALES = new Set(['en', 'tr']);
+const ACCENT_PATTERN = /^#[0-9a-f]{6}$/i;
+
+function invalid(message) {
+  const error = new Error(message);
+  error.code = 'INVALID_PAYLOAD';
+  return error;
+}
+
+function assertManager(accountability) {
+  if (accountability.admin === true || accountability.system === true) return;
+  const error = new Error('Studio settings require administrator accountability');
+  error.code = 'FORBIDDEN';
+  throw error;
+}
+
+function normalizeBrandName(value) {
+  if (typeof value !== 'string' || !value.trim()) throw invalid('Brand name is required');
+  const normalized = value.trim();
+  if (normalized.length > 100) throw invalid('Brand name cannot exceed 100 characters');
+  return normalized;
+}
+
+function normalizeLogoUrl(value) {
+  if (typeof value !== 'string' || !value.trim()) throw invalid('Logo URL is required');
+  const normalized = value.trim();
+  if (normalized.length > 512) throw invalid('Logo URL cannot exceed 512 characters');
+  let url;
+  try {
+    url = new URL(normalized);
+  } catch {
+    throw invalid('Logo URL must be a valid URL');
+  }
+  if (!['http:', 'https:'].includes(url.protocol)) throw invalid('Logo URL must use HTTP or HTTPS');
+  return normalized;
+}
+
+function normalizeAccent(value) {
+  const normalized = String(value ?? '').trim();
+  if (!ACCENT_PATTERN.test(normalized)) throw invalid('Accent color must be a six-digit hex color');
+  return normalized.toLowerCase();
+}
+
+function normalizeTheme(value) {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (!THEMES.has(normalized)) throw invalid('Theme must be system, light or dark');
+  return normalized;
+}
+
+function normalizeLocale(value) {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (!LOCALES.has(normalized)) throw invalid('Default locale must be en or tr');
+  return normalized;
+}
+
+function publicSettings(row) {
+  return {
+    brand_name: row.brand_name,
+    logo_url: row.logo_url,
+    accent_color: row.accent_color,
+    theme: row.theme,
+    default_locale: row.default_locale,
+    updated_at: row.updated_at ?? null,
+  };
+}
+
+export class StudioSettingsService extends BaseService {
+  async readPublic() {
+    const [rows] = await this.database.query(
+      `SELECT brand_name, logo_url, accent_color, theme, default_locale, updated_at
+       FROM yuncms_studio_settings
+       WHERE id = 1
+       LIMIT 1`,
+    );
+    const row = rows[0];
+    if (!row) {
+      const error = new Error('Studio settings are missing; run YunCMS bootstrap');
+      error.code = 'DATABASE_MIGRATION_REQUIRED';
+      throw error;
+    }
+    return publicSettings(row);
+  }
+
+  async readOne() {
+    assertManager(this.accountability);
+    return this.readPublic();
+  }
+
+  async updateOne(patch = {}) {
+    assertManager(this.accountability);
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw invalid('Studio settings patch must be an object');
+
+    const keys = Object.keys(patch);
+    const allowed = new Set(['brand_name', 'logo_url', 'accent_color', 'theme', 'default_locale']);
+    if (keys.length === 0 || keys.some((key) => !allowed.has(key))) {
+      throw invalid('Studio settings patch contains unsupported properties');
+    }
+
+    const assignments = [];
+    const params = [];
+    if (Object.hasOwn(patch, 'brand_name')) {
+      assignments.push('brand_name = ?');
+      params.push(normalizeBrandName(patch.brand_name));
+    }
+    if (Object.hasOwn(patch, 'logo_url')) {
+      assignments.push('logo_url = ?');
+      params.push(normalizeLogoUrl(patch.logo_url));
+    }
+    if (Object.hasOwn(patch, 'accent_color')) {
+      assignments.push('accent_color = ?');
+      params.push(normalizeAccent(patch.accent_color));
+    }
+    if (Object.hasOwn(patch, 'theme')) {
+      assignments.push('theme = ?');
+      params.push(normalizeTheme(patch.theme));
+    }
+    if (Object.hasOwn(patch, 'default_locale')) {
+      assignments.push('default_locale = ?');
+      params.push(normalizeLocale(patch.default_locale));
+    }
+
+    params.push(1);
+    await this.database.query(
+      `UPDATE yuncms_studio_settings SET ${assignments.join(', ')} WHERE id = ?`,
+      params,
+    );
+    return this.readPublic();
+  }
+}
+
+export const STUDIO_SETTING_DEFAULTS = Object.freeze({
+  brand_name: 'YunCMS',
+  logo_url: 'https://yunsoft.com/light-logo.png',
+  accent_color: '#2563eb',
+  theme: 'system',
+  default_locale: 'en',
+});

package/src/setup.js

@@ -1,8 +1,12 @@
+import { randomUUID } from 'node:crypto';
+
 import { createSystemAccountability } from './accountability.js';
 import { withTransaction } from './transaction.js';
 import { RolesService } from './services/roles-service.js';
 import { UsersService } from './services/users-service.js';
 
+const PUBLIC_ROLE_NAMES = Object.freeze(['Public', 'Public API', 'Anonymous']);
+
 export async function findExistingAdmin(database) {
   if (!database) throw new Error('Database handle is required');
   const [rows] = await database.query(
@@ -16,6 +20,51 @@ export async function findExistingAdmin(database) {
   return rows[0] ?? null;
 }
 
+export async function findPublicRole(database) {
+  if (!database) throw new Error('Database handle is required');
+  const [rows] = await database.query(
+    `SELECT id, name, description, admin, public
+     FROM yuncms_roles
+     WHERE public = 1
+     ORDER BY created_at ASC
+     LIMIT 2`,
+  );
+  if (rows.length > 1) {
+    const error = new Error('Multiple public roles are configured');
+    error.code = 'PUBLIC_ROLE_AMBIGUOUS';
+    throw error;
+  }
+  return rows[0] ?? null;
+}
+
+async function availablePublicRoleName(database) {
+  for (const candidate of PUBLIC_ROLE_NAMES) {
+    const [rows] = await database.query(
+      'SELECT id FROM yuncms_roles WHERE name = ? LIMIT 1',
+      [candidate],
+    );
+    if (!rows[0]) return candidate;
+  }
+  return `Public ${randomUUID().slice(0, 8)}`;
+}
+
+export async function ensurePublicRole(database) {
+  if (!database) throw new Error('Database handle is required');
+  const existing = await findPublicRole(database);
+  if (existing) return { ...existing, created: false };
+
+  const roles = new RolesService({
+    accountability: createSystemAccountability(),
+    database,
+  });
+  const role = await roles.createOne({
+    name: await availablePublicRoleName(database),
+    description: 'Unauthenticated public API access. No collection access is granted by default.',
+    public: true,
+  });
+  return { ...role, created: true };
+}
+
 export async function createInitialAdmin(pool, { email, password } = {}) {
   if (!pool) throw new Error('Database pool is required');
   const accountability = createSystemAccountability();