@yunsoft/yuncms-core 0.1.1 → 0.1.2

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

@@ -103,7 +103,6 @@ export async function createInitialAdmin(pool, { email, password } = {}) {
       password,
       role: roleId,
       status: 'active',
-      emailVerified: true,
     });
 
     return {
@@ -112,4 +111,4 @@ export async function createInitialAdmin(pool, { email, password } = {}) {
       role: roleId,
     };
   });
-}
+}

package/src/system-fields.js

@@ -0,0 +1,146 @@
+import { createHash } from 'node:crypto';
+
+import { compileFieldColumn } from './field-types.js';
+import { quoteIdentifier } from './identifier.js';
+
+export const COLLECTION_SYSTEM_FIELDS = Object.freeze([
+  'created_at',
+  'updated_at',
+  'created_by',
+  'updated_by',
+]);
+
+const SYSTEM_FIELD_DEFINITIONS = Object.freeze({
+  created_at: Object.freeze({
+    field: 'created_at',
+    type: 'timestamp',
+    required: true,
+    readonly: true,
+    interface: 'datetime',
+    special: 'date-created',
+    defaultPreset: 'now',
+  }),
+  updated_at: Object.freeze({
+    field: 'updated_at',
+    type: 'timestamp',
+    required: true,
+    readonly: true,
+    interface: 'datetime',
+    special: 'date-updated',
+    defaultPreset: 'now',
+    autoUpdate: true,
+  }),
+  created_by: Object.freeze({
+    field: 'created_by',
+    type: 'uuid',
+    required: false,
+    readonly: true,
+    interface: 'user',
+    special: 'user-created',
+  }),
+  updated_by: Object.freeze({
+    field: 'updated_by',
+    type: 'uuid',
+    required: false,
+    readonly: true,
+    interface: 'user',
+    special: 'user-updated',
+  }),
+});
+
+function invalidSystemFields(message) {
+  const error = new Error(message);
+  error.code = 'INVALID_SCHEMA_PAYLOAD';
+  return error;
+}
+
+export function normalizeCollectionSystemFields(value) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) throw invalidSystemFields('systemFields must be an array');
+
+  const normalized = [...new Set(value)];
+  for (const field of normalized) {
+    if (!COLLECTION_SYSTEM_FIELDS.includes(field)) {
+      throw invalidSystemFields(`Unsupported system field: ${String(field)}`);
+    }
+  }
+  return COLLECTION_SYSTEM_FIELDS.filter((field) => normalized.includes(field));
+}
+
+export function systemFieldDefinition(field) {
+  return SYSTEM_FIELD_DEFINITIONS[field] ?? null;
+}
+
+function foreignKeyName(collection, field) {
+  const digest = createHash('sha256')
+    .update(`${collection}:${field}:system-user`)
+    .digest('hex')
+    .slice(0, 24);
+  return `ysf_${digest}`;
+}
+
+export function compileCollectionSystemFields(collection, requestedFields) {
+  const fields = normalizeCollectionSystemFields(requestedFields);
+  const columns = [];
+  const constraints = [];
+  const metadata = [];
+
+  for (const field of fields) {
+    const definition = SYSTEM_FIELD_DEFINITIONS[field];
+    const compiled = compileFieldColumn(definition);
+    columns.push(`${quoteIdentifier(field, 'system field')} ${compiled.sql}`);
+    metadata.push({
+      collection,
+      field,
+      type: definition.type,
+      required: definition.required,
+      readonly: true,
+      hidden: false,
+      interface: definition.interface,
+      schemaMetadata: {
+        ...compiled.schemaMetadata,
+        special: definition.special,
+        systemManaged: true,
+      },
+    });
+
+    if (field === 'created_by' || field === 'updated_by') {
+      constraints.push(
+        `CONSTRAINT ${quoteIdentifier(foreignKeyName(collection, field), 'system field constraint')} `
+        + `FOREIGN KEY (${quoteIdentifier(field, 'system field')}) REFERENCES yuncms_users (id) ON DELETE SET NULL`,
+      );
+    }
+  }
+
+  return { fields, columns, constraints, metadata };
+}
+
+function parseSchemaMetadata(value) {
+  if (value == null) return {};
+  if (typeof value === 'object') return value;
+  try {
+    return JSON.parse(value) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+export function fieldSpecial(fieldSchema) {
+  return parseSchemaMetadata(fieldSchema?.schema_metadata).special ?? null;
+}
+
+export function isSystemManagedField(fieldSchema) {
+  return Boolean(fieldSpecial(fieldSchema));
+}
+
+export function systemMutationEntries(schema, accountability, operation, now = new Date()) {
+  const entries = [];
+  for (const fieldSchema of Object.values(schema?.fields ?? {})) {
+    const special = fieldSpecial(fieldSchema);
+    if (operation === 'create' && special === 'date-created') entries.push([fieldSchema.field, now]);
+    if ((operation === 'create' || operation === 'update') && special === 'date-updated') entries.push([fieldSchema.field, now]);
+    if (operation === 'create' && special === 'user-created') entries.push([fieldSchema.field, accountability?.user ?? null]);
+    if ((operation === 'create' || operation === 'update') && special === 'user-updated') entries.push([fieldSchema.field, accountability?.user ?? null]);
+  }
+  return entries;
+}

package/src/system-permissions.js

@@ -0,0 +1,54 @@
+const ALL_ACTIONS = Object.freeze(['read', 'create', 'update', 'delete']);
+
+function parseMetadata(value) {
+  if (value == null) return {};
+  if (typeof value === 'object') return value;
+  try {
+    return JSON.parse(value) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function isEnabledFlag(value) {
+  return value === true || value === 1;
+}
+
+export function systemPermissionConfig(collectionSchema) {
+  if (!collectionSchema?.system) return null;
+  const metadata = parseMetadata(collectionSchema.metadata);
+  if (!isEnabledFlag(metadata.permissionManaged)) return null;
+  const allowedActions = Array.isArray(metadata.allowedActions)
+    ? metadata.allowedActions.filter((action) => ALL_ACTIONS.includes(action))
+    : [];
+  return Object.freeze({
+    resource: metadata.resource ?? collectionSchema.collection,
+    mode: metadata.permissionMode ?? 'action-only',
+    allowedActions: Object.freeze([...new Set(allowedActions)]),
+  });
+}
+
+export function isPermissionManagedSystemResource(collectionSchema) {
+  return Boolean(systemPermissionConfig(collectionSchema));
+}
+
+export function assertSystemResourceAction(collectionSchema, action) {
+  const config = systemPermissionConfig(collectionSchema);
+  if (!config) return null;
+  if (!config.allowedActions.includes(action)) {
+    const error = new Error(`Action ${action} is protected for system resource ${collectionSchema.collection}`);
+    error.code = 'SYSTEM_PERMISSION_ACTION_PROTECTED';
+    throw error;
+  }
+  return config;
+}
+
+export function assertActionOnlyPermissionPayload(collectionSchema, { fields, filter, validation } = {}) {
+  const config = systemPermissionConfig(collectionSchema);
+  if (!config || config.mode !== 'action-only') return;
+  if (fields != null || filter != null || validation != null) {
+    const error = new Error(`System resource ${collectionSchema.collection} supports action-level permissions only`);
+    error.code = 'SYSTEM_PERMISSION_ADVANCED_UNSUPPORTED';
+    throw error;
+  }
+}