@yunsoft/yuncms-core 0.1.0 → 0.1.2

package/src/services/permissions-service.js

@@ -3,6 +3,11 @@ import { randomUUID } from 'node:crypto';
 import { assertPermissionValidationRule } from '../permission-validation.js';
 import { compileFilter } from '../query.js';
 import { SchemaCache } from '../schema.js';
+import {
+  assertActionOnlyPermissionPayload,
+  assertSystemResourceAction,
+  isPermissionManagedSystemResource,
+} from '../system-permissions.js';
 import { BaseService } from './base-service.js';
 
 const ACTIONS = new Set(['create', 'read', 'update', 'delete']);
@@ -81,6 +86,17 @@ export class PermissionsService extends BaseService {
     this.schemaCache = options.schemaCache ?? defaultSchemaCache;
   }
 
+  async #collectionSchema(collection) {
+    const snapshot = this.schema ?? await this.schemaCache.get(this.database);
+    const collectionSchema = snapshot.collections?.[collection];
+    if (!collectionSchema) {
+      const error = new Error(`Unknown permission collection: ${collection}`);
+      error.code = 'COLLECTION_NOT_FOUND';
+      throw error;
+    }
+    return collectionSchema;
+  }
+
   async resolve(action, collection) {
     assertAction(action);
     const key = cacheKey(this.accountability, action, collection);
@@ -102,6 +118,19 @@ export class PermissionsService extends BaseService {
         throw forbidden(`No role is available for ${action} access to ${collection}`);
       }
 
+      const collectionSchema = await this.#collectionSchema(collection);
+      if (collectionSchema.system) {
+        if (!isPermissionManagedSystemResource(collectionSchema)) {
+          throw forbidden(`System resource is not delegatable: ${collection}`);
+        }
+        try {
+          assertSystemResourceAction(collectionSchema, action);
+        } catch (error) {
+          if (error.code === 'SYSTEM_PERMISSION_ACTION_PROTECTED') throw forbidden(error.message);
+          throw error;
+        }
+      }
+
       const [rows] = await this.database.query(
         `SELECT id, role, collection, action, fields, filter, validation
          FROM yuncms_permissions
@@ -154,17 +183,6 @@ export class PermissionsService extends BaseService {
     return normalizePermissionRow(rows[0]);
   }
 
-  async #collectionSchema(collection) {
-    const snapshot = this.schema ?? await this.schemaCache.get(this.database);
-    const collectionSchema = snapshot.collections?.[collection];
-    if (!collectionSchema) {
-      const error = new Error(`Unknown permission collection: ${collection}`);
-      error.code = 'COLLECTION_NOT_FOUND';
-      throw error;
-    }
-    return collectionSchema;
-  }
-
   async createOne(input = {}) {
     assertPermissionManager(this.accountability);
     const action = assertAction(input.action);
@@ -180,6 +198,16 @@ export class PermissionsService extends BaseService {
     }
 
     const collectionSchema = await this.#collectionSchema(input.collection);
+    if (collectionSchema.system) {
+      if (!isPermissionManagedSystemResource(collectionSchema)) {
+        const error = new Error(`System resource permissions are protected: ${input.collection}`);
+        error.code = 'SYSTEM_PERMISSION_RESOURCE_PROTECTED';
+        throw error;
+      }
+      assertSystemResourceAction(collectionSchema, action);
+      assertActionOnlyPermissionPayload(collectionSchema, input);
+    }
+
     const fields = normalizePermissionFields(input.fields ?? null, collectionSchema);
     const filter = input.filter ?? null;
     const validation = input.validation ?? null;
@@ -187,14 +215,20 @@ export class PermissionsService extends BaseService {
     assertPermissionValidationRule(validation, collectionSchema);
 
     const [roleRows] = await this.database.query(
-      'SELECT id FROM yuncms_roles WHERE id = ? LIMIT 1',
+      'SELECT id, admin, public FROM yuncms_roles WHERE id = ? LIMIT 1',
       [input.role],
     );
-    if (!roleRows[0]) {
+    const role = roleRows[0];
+    if (!role) {
       const error = new Error(`Unknown permission role: ${input.role}`);
       error.code = 'ROLE_NOT_FOUND';
       throw error;
     }
+    if (collectionSchema.system && role.public) {
+      const error = new Error('Public role cannot be granted access to protected system resources');
+      error.code = 'PUBLIC_SYSTEM_ACCESS_FORBIDDEN';
+      throw error;
+    }
 
     const id = randomUUID();
     await this.database.query(
@@ -235,6 +269,7 @@ export class PermissionsService extends BaseService {
       throw error;
     }
     const collectionSchema = await this.#collectionSchema(existing.collection);
+    if (collectionSchema.system) assertActionOnlyPermissionPayload(collectionSchema, patch);
 
     const assignments = [];
     const params = [];

package/src/services/roles-service.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 
 import { BaseService } from './base-service.js';
+import { resolveSystemResourceAccess } from './system-resource-access.js';
 
 function assertRoleManager(accountability) {
   if (accountability.admin === true || accountability.system === true) return;
@@ -26,7 +27,7 @@ function normalizeRoleName(name) {
 
 export class RolesService extends BaseService {
   async readMany() {
-    assertRoleManager(this.accountability);
+    await resolveSystemResourceAccess(this, 'read', 'yuncms_roles');
     const [rows] = await this.database.query(
       `SELECT id, name, description, admin, public, created_at, updated_at
        FROM yuncms_roles
@@ -36,7 +37,7 @@ export class RolesService extends BaseService {
   }
 
   async readOne(id) {
-    assertRoleManager(this.accountability);
+    await resolveSystemResourceAccess(this, 'read', 'yuncms_roles');
     const [rows] = await this.database.query(
       `SELECT id, name, description, admin, public, created_at, updated_at
        FROM yuncms_roles
@@ -157,4 +158,4 @@ export class RolesService extends BaseService {
     }
     return true;
   }
-}
+}

package/src/services/sessions-service.js

@@ -20,6 +20,7 @@ function identityFromRow(row) {
   return {
     user: row.user,
     role: row.role ?? null,
+    role_name: row.role_name ?? null,
     admin: Boolean(row.role_admin),
     email: row.email,
     session: row.session_id,
@@ -71,7 +72,7 @@ export class SessionsService extends BaseService {
     const hash = hashToken(token);
     const [rows] = await this.database.query(
       `SELECT s.id AS session_id, s.user, u.email, u.role, u.status,
-              r.admin AS role_admin
+              r.name AS role_name, r.admin AS role_admin
        FROM yuncms_sessions s
        INNER JOIN yuncms_users u ON u.id = s.user
        LEFT JOIN yuncms_roles r ON r.id = u.role
@@ -105,7 +106,7 @@ export class SessionsService extends BaseService {
     const oldHash = hashToken(token);
     const [rows] = await this.database.query(
       `SELECT s.id AS session_id, s.user, u.email, u.role, u.status,
-              r.admin AS role_admin
+              r.name AS role_name, r.admin AS role_admin
        FROM yuncms_sessions s
        INNER JOIN yuncms_users u ON u.id = s.user
        LEFT JOIN yuncms_roles r ON r.id = u.role
@@ -164,7 +165,6 @@ export class SessionsService extends BaseService {
       error.code = 'FORBIDDEN';
       throw error;
     }
-
     const [result] = await this.database.query(
       'DELETE FROM yuncms_sessions WHERE user = ?',
       [userId],

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/services/system-resource-access.js

@@ -0,0 +1,23 @@
+import { PermissionsService } from './permissions-service.js';
+
+export async function resolveSystemResourceAccess(service, action, collection) {
+  if (service.accountability.admin === true || service.accountability.system === true) {
+    return {
+      fullAccess: true,
+      action,
+      collection,
+      role: service.accountability.role ?? null,
+    };
+  }
+
+  const permissions = new PermissionsService({
+    accountability: service.accountability,
+    database: service.database,
+    schema: service.schema,
+    emitter: service.emitter,
+    logger: service.logger,
+    permissionCache: service.permissionCache,
+    requestId: service.requestId,
+  });
+  return permissions.resolve(action, collection);
+}

package/src/services/users-service.js

@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto';
 import { hashPassword } from '../auth/password.js';
 import { withTransaction } from '../transaction.js';
 import { BaseService } from './base-service.js';
+import { resolveSystemResourceAccess } from './system-resource-access.js';
 
 const USER_STATUSES = new Set(['active', 'suspended', 'disabled']);
 const USER_UPDATE_KEYS = new Set(['email', 'role', 'status']);
@@ -22,11 +23,10 @@ function normalizeEmail(email) {
   return normalized;
 }
 
-function assertUserManager(accountability) {
-  if (accountability.admin === true || accountability.system === true) return;
-  const error = new Error('User management requires administrator accountability');
+function forbidden(message) {
+  const error = new Error(message);
   error.code = 'FORBIDDEN';
-  throw error;
+  return error;
 }
 
 function assertStatus(status) {
@@ -38,19 +38,65 @@ function assertStatus(status) {
   return status;
 }
 
-async function assertRoleExists(database, role) {
+function assertCredentialManager(accountability) {
+  if (accountability.admin === true || accountability.system === true) return;
+  throw forbidden('Changing another user password requires administrator accountability');
+}
+
+async function assertRoleAssignable(database, role, accountability) {
   if (role == null) return;
-  const [roleRows] = await database.query('SELECT id FROM yuncms_roles WHERE id = ? LIMIT 1', [role]);
-  if (!roleRows[0]) {
+  const [roleRows] = await database.query(
+    'SELECT id, admin, public FROM yuncms_roles WHERE id = ? LIMIT 1',
+    [role],
+  );
+  const targetRole = roleRows[0];
+  if (!targetRole) {
     const error = new Error(`Unknown role: ${role}`);
     error.code = 'ROLE_NOT_FOUND';
     throw error;
   }
+  if (targetRole.public) {
+    const error = new Error('The public role cannot be assigned to an authenticated user');
+    error.code = 'INVALID_ROLE';
+    throw error;
+  }
+  if (targetRole.admin && accountability.admin !== true && accountability.system !== true) {
+    throw forbidden('Only an administrator can assign the administrator role');
+  }
+}
+
+async function assertTargetManageable(database, id, accountability) {
+  if (accountability.admin === true || accountability.system === true) return;
+  const [rows] = await database.query(
+    `SELECT u.id, r.admin AS role_admin
+     FROM yuncms_users u
+     LEFT JOIN yuncms_roles r ON r.id = u.role
+     WHERE u.id = ?
+     LIMIT 1`,
+    [id],
+  );
+  if (!rows[0]) {
+    const error = new Error(`Unknown user: ${id}`);
+    error.code = 'USER_NOT_FOUND';
+    throw error;
+  }
+  if (rows[0].role_admin) throw forbidden('Delegated user managers cannot modify administrator accounts');
 }
 
 export class UsersService extends BaseService {
+  async #readOneUnsafe(id) {
+    const [rows] = await this.database.query(
+      `SELECT id, email, role, status, email_verified_at, last_access, created_at, updated_at
+       FROM yuncms_users
+       WHERE id = ?
+       LIMIT 1`,
+      [id],
+    );
+    return rows[0] ?? null;
+  }
+
   async readMany() {
-    assertUserManager(this.accountability);
+    await resolveSystemResourceAccess(this, 'read', 'yuncms_users');
     const [rows] = await this.database.query(
       `SELECT id, email, role, status, email_verified_at, last_access, created_at, updated_at
        FROM yuncms_users
@@ -61,26 +107,19 @@ export class UsersService extends BaseService {
 
   async readOne(id) {
     const self = this.accountability.user === id;
-    if (!self) assertUserManager(this.accountability);
-
-    const [rows] = await this.database.query(
-      `SELECT id, email, role, status, email_verified_at, last_access, created_at, updated_at
-       FROM yuncms_users
-       WHERE id = ?
-       LIMIT 1`,
-      [id],
-    );
-    return rows[0] ?? null;
+    if (!self) await resolveSystemResourceAccess(this, 'read', 'yuncms_users');
+    return this.#readOneUnsafe(id);
   }
 
   async createOne(input = {}) {
-    assertUserManager(this.accountability);
+    await resolveSystemResourceAccess(this, 'create', 'yuncms_users');
     const email = normalizeEmail(input.email);
     const status = assertStatus(input.status ?? 'active');
-    await assertRoleExists(this.database, input.role ?? null);
+    await assertRoleAssignable(this.database, input.role ?? null, this.accountability);
 
     const passwordHash = await hashPassword(input.password);
     const id = randomUUID();
+    const verifiedAt = new Date();
     await this.database.query(
       `INSERT INTO yuncms_users (id, email, password_hash, role, status, email_verified_at)
        VALUES (?, ?, ?, ?, ?, ?)`,
@@ -90,15 +129,16 @@ export class UsersService extends BaseService {
         passwordHash,
         input.role ?? null,
         status,
-        input.emailVerified === true ? new Date() : null,
+        verifiedAt,
       ],
     );
 
-    return this.readOne(id);
+    return this.#readOneUnsafe(id);
   }
 
   async updateOne(id, patch = {}) {
-    assertUserManager(this.accountability);
+    await resolveSystemResourceAccess(this, 'update', 'yuncms_users');
+    await assertTargetManageable(this.database, id, this.accountability);
     if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
       const error = new Error('User patch must be an object');
       error.code = 'INVALID_PAYLOAD';
@@ -114,12 +154,14 @@ export class UsersService extends BaseService {
     if (Object.hasOwn(patch, 'status')) {
       assertStatus(patch.status);
       if (this.accountability.user === id && patch.status !== 'active') {
-        const error = new Error('An administrator cannot suspend or disable their own active session');
+        const error = new Error('A user cannot suspend or disable their own active session');
         error.code = 'SELF_ADMIN_MUTATION_FORBIDDEN';
         throw error;
       }
     }
-    if (Object.hasOwn(patch, 'role')) await assertRoleExists(this.database, patch.role);
+    if (Object.hasOwn(patch, 'role')) {
+      await assertRoleAssignable(this.database, patch.role, this.accountability);
+    }
 
     return withTransaction(this.database, async (connection) => {
       const assignments = [];
@@ -163,9 +205,10 @@ export class UsersService extends BaseService {
   }
 
   async deleteOne(id) {
-    assertUserManager(this.accountability);
+    await resolveSystemResourceAccess(this, 'delete', 'yuncms_users');
+    await assertTargetManageable(this.database, id, this.accountability);
     if (this.accountability.user === id) {
-      const error = new Error('An administrator cannot delete their own user account');
+      const error = new Error('A user cannot delete their own account from an active session');
       error.code = 'SELF_ADMIN_MUTATION_FORBIDDEN';
       throw error;
     }
@@ -180,7 +223,7 @@ export class UsersService extends BaseService {
 
   async updatePassword(id, password) {
     const self = this.accountability.user === id;
-    if (!self) assertUserManager(this.accountability);
+    if (!self) assertCredentialManager(this.accountability);
 
     const passwordHash = await hashPassword(password);
     const connection = await this.database.getConnection();

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();
@@ -54,7 +103,6 @@ export async function createInitialAdmin(pool, { email, password } = {}) {
       password,
       role: roleId,
       status: 'active',
-      emailVerified: true,
     });
 
     return {
@@ -63,4 +111,4 @@ export async function createInitialAdmin(pool, { email, password } = {}) {
       role: roleId,
     };
   });
-}
+}