@yunsoft/yuncms-core 0.1.0

package/src/services/sessions-service.js

@@ -0,0 +1,179 @@
+import { randomUUID } from 'node:crypto';
+
+import { createOpaqueToken, hashToken, tokenType } from '../auth/tokens.js';
+import { BaseService } from './base-service.js';
+
+const ACCESS_TTL_MS = 15 * 60 * 1000;
+const REFRESH_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+function invalidCredentials() {
+  const error = new Error('Invalid or expired authentication token');
+  error.code = 'INVALID_CREDENTIALS';
+  return error;
+}
+
+function addMilliseconds(now, milliseconds) {
+  return new Date(now.getTime() + milliseconds);
+}
+
+function identityFromRow(row) {
+  return {
+    user: row.user,
+    role: row.role ?? null,
+    admin: Boolean(row.role_admin),
+    email: row.email,
+    session: row.session_id,
+    authMethod: 'session',
+  };
+}
+
+export class SessionsService extends BaseService {
+  async createForUser(user, {
+    ip = null,
+    userAgent = null,
+    now = new Date(),
+    accessTtlMs = ACCESS_TTL_MS,
+    refreshTtlMs = REFRESH_TTL_MS,
+  } = {}) {
+    const sessionId = randomUUID();
+    const access = createOpaqueToken('access');
+    const refresh = createOpaqueToken('refresh', { bytes: 48 });
+    const accessExpiresAt = addMilliseconds(now, accessTtlMs);
+    const refreshExpiresAt = addMilliseconds(now, refreshTtlMs);
+
+    await this.database.query(
+      `INSERT INTO yuncms_sessions
+       (id, user, token_hash, access_token_hash, access_expires_at, expires_at, ip, user_agent)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        sessionId,
+        user.id,
+        refresh.hash,
+        access.hash,
+        accessExpiresAt,
+        refreshExpiresAt,
+        ip,
+        userAgent,
+      ],
+    );
+
+    return {
+      access_token: access.token,
+      access_expires_at: accessExpiresAt,
+      refresh_token: refresh.token,
+      refresh_expires_at: refreshExpiresAt,
+      session: sessionId,
+    };
+  }
+
+  async authenticateAccessToken(token) {
+    if (tokenType(token) !== 'access') throw invalidCredentials();
+    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
+       FROM yuncms_sessions s
+       INNER JOIN yuncms_users u ON u.id = s.user
+       LEFT JOIN yuncms_roles r ON r.id = u.role
+       WHERE s.access_token_hash = ?
+         AND s.access_expires_at > CURRENT_TIMESTAMP(3)
+         AND s.expires_at > CURRENT_TIMESTAMP(3)
+         AND u.status = 'active'
+       LIMIT 1`,
+      [hash],
+    );
+    const row = rows[0];
+    if (!row) throw invalidCredentials();
+
+    await this.database.query(
+      `UPDATE yuncms_sessions s
+       INNER JOIN yuncms_users u ON u.id = s.user
+       SET s.last_used_at = CURRENT_TIMESTAMP(3), u.last_access = CURRENT_TIMESTAMP(3)
+       WHERE s.id = ?`,
+      [row.session_id],
+    );
+
+    return identityFromRow(row);
+  }
+
+  async rotateRefreshToken(token, {
+    now = new Date(),
+    accessTtlMs = ACCESS_TTL_MS,
+    refreshTtlMs = REFRESH_TTL_MS,
+  } = {}) {
+    if (tokenType(token) !== 'refresh') throw invalidCredentials();
+    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
+       FROM yuncms_sessions s
+       INNER JOIN yuncms_users u ON u.id = s.user
+       LEFT JOIN yuncms_roles r ON r.id = u.role
+       WHERE s.token_hash = ?
+         AND s.expires_at > CURRENT_TIMESTAMP(3)
+         AND u.status = 'active'
+       LIMIT 1`,
+      [oldHash],
+    );
+    const row = rows[0];
+    if (!row) throw invalidCredentials();
+
+    const access = createOpaqueToken('access');
+    const refresh = createOpaqueToken('refresh', { bytes: 48 });
+    const accessExpiresAt = addMilliseconds(now, accessTtlMs);
+    const refreshExpiresAt = addMilliseconds(now, refreshTtlMs);
+    const [result] = await this.database.query(
+      `UPDATE yuncms_sessions
+       SET token_hash = ?, access_token_hash = ?, access_expires_at = ?, expires_at = ?,
+           last_used_at = CURRENT_TIMESTAMP(3)
+       WHERE id = ? AND token_hash = ?`,
+      [
+        refresh.hash,
+        access.hash,
+        accessExpiresAt,
+        refreshExpiresAt,
+        row.session_id,
+        oldHash,
+      ],
+    );
+
+    if (result.affectedRows !== 1) throw invalidCredentials();
+
+    return {
+      ...identityFromRow(row),
+      access_token: access.token,
+      access_expires_at: accessExpiresAt,
+      refresh_token: refresh.token,
+      refresh_expires_at: refreshExpiresAt,
+    };
+  }
+
+  async revokeByAccessToken(token) {
+    if (tokenType(token) !== 'access') throw invalidCredentials();
+    const [result] = await this.database.query(
+      'DELETE FROM yuncms_sessions WHERE access_token_hash = ?',
+      [hashToken(token)],
+    );
+    return result.affectedRows > 0;
+  }
+
+  async revokeAllForUser(userId) {
+    const self = this.accountability.user === userId;
+    if (!self && this.accountability.admin !== true && this.accountability.system !== true) {
+      const error = new Error('Session revocation requires self or administrator accountability');
+      error.code = 'FORBIDDEN';
+      throw error;
+    }
+
+    const [result] = await this.database.query(
+      'DELETE FROM yuncms_sessions WHERE user = ?',
+      [userId],
+    );
+    return result.affectedRows;
+  }
+}
+
+export const SESSION_DEFAULTS = Object.freeze({
+  accessTtlMs: ACCESS_TTL_MS,
+  refreshTtlMs: REFRESH_TTL_MS,
+});

package/src/services/users-service.js

@@ -0,0 +1,215 @@
+import { randomUUID } from 'node:crypto';
+
+import { hashPassword } from '../auth/password.js';
+import { withTransaction } from '../transaction.js';
+import { BaseService } from './base-service.js';
+
+const USER_STATUSES = new Set(['active', 'suspended', 'disabled']);
+const USER_UPDATE_KEYS = new Set(['email', 'role', 'status']);
+
+function normalizeEmail(email) {
+  if (typeof email !== 'string') {
+    const error = new Error('Email is required');
+    error.code = 'INVALID_PAYLOAD';
+    throw error;
+  }
+  const normalized = email.trim().toLowerCase();
+  if (!normalized || normalized.length > 191 || !normalized.includes('@')) {
+    const error = new Error('Email is invalid');
+    error.code = 'INVALID_PAYLOAD';
+    throw error;
+  }
+  return normalized;
+}
+
+function assertUserManager(accountability) {
+  if (accountability.admin === true || accountability.system === true) return;
+  const error = new Error('User management requires administrator accountability');
+  error.code = 'FORBIDDEN';
+  throw error;
+}
+
+function assertStatus(status) {
+  if (!USER_STATUSES.has(status)) {
+    const error = new Error(`Unsupported user status: ${status}`);
+    error.code = 'INVALID_PAYLOAD';
+    throw error;
+  }
+  return status;
+}
+
+async function assertRoleExists(database, role) {
+  if (role == null) return;
+  const [roleRows] = await database.query('SELECT id FROM yuncms_roles WHERE id = ? LIMIT 1', [role]);
+  if (!roleRows[0]) {
+    const error = new Error(`Unknown role: ${role}`);
+    error.code = 'ROLE_NOT_FOUND';
+    throw error;
+  }
+}
+
+export class UsersService extends BaseService {
+  async readMany() {
+    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
+       ORDER BY email ASC`,
+    );
+    return rows;
+  }
+
+  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;
+  }
+
+  async createOne(input = {}) {
+    assertUserManager(this.accountability);
+    const email = normalizeEmail(input.email);
+    const status = assertStatus(input.status ?? 'active');
+    await assertRoleExists(this.database, input.role ?? null);
+
+    const passwordHash = await hashPassword(input.password);
+    const id = randomUUID();
+    await this.database.query(
+      `INSERT INTO yuncms_users (id, email, password_hash, role, status, email_verified_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [
+        id,
+        email,
+        passwordHash,
+        input.role ?? null,
+        status,
+        input.emailVerified === true ? new Date() : null,
+      ],
+    );
+
+    return this.readOne(id);
+  }
+
+  async updateOne(id, patch = {}) {
+    assertUserManager(this.accountability);
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+      const error = new Error('User patch must be an object');
+      error.code = 'INVALID_PAYLOAD';
+      throw error;
+    }
+    const keys = Object.keys(patch);
+    if (keys.length === 0 || keys.some((key) => !USER_UPDATE_KEYS.has(key))) {
+      const error = new Error('User update supports email, role and status only');
+      error.code = 'INVALID_PAYLOAD';
+      throw error;
+    }
+
+    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');
+        error.code = 'SELF_ADMIN_MUTATION_FORBIDDEN';
+        throw error;
+      }
+    }
+    if (Object.hasOwn(patch, 'role')) await assertRoleExists(this.database, patch.role);
+
+    return withTransaction(this.database, async (connection) => {
+      const assignments = [];
+      const params = [];
+
+      if (Object.hasOwn(patch, 'email')) {
+        assignments.push('email = ?');
+        params.push(normalizeEmail(patch.email));
+      }
+      if (Object.hasOwn(patch, 'role')) {
+        assignments.push('role = ?');
+        params.push(patch.role ?? null);
+      }
+      if (Object.hasOwn(patch, 'status')) {
+        assignments.push('status = ?');
+        params.push(patch.status);
+      }
+
+      params.push(id);
+      const [result] = await connection.query(
+        `UPDATE yuncms_users SET ${assignments.join(', ')} WHERE id = ?`,
+        params,
+      );
+      if (result.affectedRows !== 1) {
+        const error = new Error(`Unknown user: ${id}`);
+        error.code = 'USER_NOT_FOUND';
+        throw error;
+      }
+
+      if (Object.hasOwn(patch, 'status') && patch.status !== 'active') {
+        await connection.query('DELETE FROM yuncms_sessions WHERE user = ?', [id]);
+      }
+
+      const [rows] = await connection.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 deleteOne(id) {
+    assertUserManager(this.accountability);
+    if (this.accountability.user === id) {
+      const error = new Error('An administrator cannot delete their own user account');
+      error.code = 'SELF_ADMIN_MUTATION_FORBIDDEN';
+      throw error;
+    }
+    const [result] = await this.database.query('DELETE FROM yuncms_users WHERE id = ?', [id]);
+    if (result.affectedRows !== 1) {
+      const error = new Error(`Unknown user: ${id}`);
+      error.code = 'USER_NOT_FOUND';
+      throw error;
+    }
+    return true;
+  }
+
+  async updatePassword(id, password) {
+    const self = this.accountability.user === id;
+    if (!self) assertUserManager(this.accountability);
+
+    const passwordHash = await hashPassword(password);
+    const connection = await this.database.getConnection();
+
+    try {
+      await connection.beginTransaction();
+      const [result] = await connection.query(
+        'UPDATE yuncms_users SET password_hash = ? WHERE id = ?',
+        [passwordHash, id],
+      );
+      if (result.affectedRows !== 1) {
+        const error = new Error(`Unknown user: ${id}`);
+        error.code = 'USER_NOT_FOUND';
+        throw error;
+      }
+      await connection.query('DELETE FROM yuncms_sessions WHERE user = ?', [id]);
+      await connection.commit();
+      return true;
+    } catch (error) {
+      try {
+        await connection.rollback();
+      } catch (rollbackError) {
+        error.rollbackError = rollbackError;
+      }
+      throw error;
+    } finally {
+      connection.release();
+    }
+  }
+}
+
+export { normalizeEmail };

package/src/setup.js

@@ -0,0 +1,66 @@
+import { createSystemAccountability } from './accountability.js';
+import { withTransaction } from './transaction.js';
+import { RolesService } from './services/roles-service.js';
+import { UsersService } from './services/users-service.js';
+
+export async function findExistingAdmin(database) {
+  if (!database) throw new Error('Database handle is required');
+  const [rows] = await database.query(
+    `SELECT u.id, u.email, u.role
+     FROM yuncms_users u
+     INNER JOIN yuncms_roles r ON r.id = u.role
+     WHERE r.admin = 1
+     ORDER BY u.created_at ASC
+     LIMIT 1`,
+  );
+  return rows[0] ?? null;
+}
+
+export async function createInitialAdmin(pool, { email, password } = {}) {
+  if (!pool) throw new Error('Database pool is required');
+  const accountability = createSystemAccountability();
+
+  return withTransaction(pool, async (connection) => {
+    const existingAdmin = await findExistingAdmin(connection);
+    if (existingAdmin) {
+      const error = new Error(`An administrator user already exists: ${existingAdmin.email}`);
+      error.code = 'INITIAL_ADMIN_EXISTS';
+      error.admin = existingAdmin;
+      throw error;
+    }
+
+    const [adminRoles] = await connection.query(
+      `SELECT id, name
+       FROM yuncms_roles
+       WHERE admin = 1
+       ORDER BY created_at ASC
+       LIMIT 1`,
+    );
+
+    let roleId = adminRoles[0]?.id ?? null;
+    if (!roleId) {
+      const roles = new RolesService({ accountability, database: connection });
+      const role = await roles.createOne({
+        name: 'Administrator',
+        description: 'Full YunCMS administrator access',
+        admin: true,
+      });
+      roleId = role.id;
+    }
+
+    const users = new UsersService({ accountability, database: connection });
+    const user = await users.createOne({
+      email,
+      password,
+      role: roleId,
+      status: 'active',
+      emailVerified: true,
+    });
+
+    return {
+      id: user.id,
+      email: user.email,
+      role: roleId,
+    };
+  });
+}

package/src/storage/local-storage-driver.js

@@ -0,0 +1,105 @@
+import { mkdir, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+
+const STORAGE_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,190}$/;
+
+function storageError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function assertStorageKey(key) {
+  if (typeof key !== 'string' || !STORAGE_KEY.test(key) || key.includes('..')) {
+    throw storageError('INVALID_STORAGE_KEY', 'Storage key contains unsupported path characters');
+  }
+  return key;
+}
+
+export class LocalStorageDriver {
+  constructor({ root }) {
+    if (!root || typeof root !== 'string') throw new Error('Local storage root is required');
+    this.root = resolve(root);
+  }
+
+  pathFor(key) {
+    const safeKey = assertStorageKey(key);
+    const path = resolve(this.root, safeKey);
+    const fromRoot = relative(this.root, path);
+    if (!fromRoot || fromRoot.startsWith('..') || isAbsolute(fromRoot)) {
+      throw storageError('INVALID_STORAGE_KEY', 'Storage key escaped the configured root');
+    }
+    return path;
+  }
+
+  async put(key, contents) {
+    const path = this.pathFor(key);
+    if (!Buffer.isBuffer(contents) && !(contents instanceof Uint8Array)) {
+      throw storageError('INVALID_FILE_CONTENT', 'Local storage put requires Buffer or Uint8Array content');
+    }
+    await mkdir(this.root, { recursive: true });
+    await writeFile(path, contents, { flag: 'wx' });
+    return { key, size: contents.byteLength };
+  }
+
+  async get(key) {
+    return readFile(this.pathFor(key));
+  }
+
+  async stat(key) {
+    try {
+      const info = await stat(this.pathFor(key));
+      return {
+        key,
+        size: info.size,
+        modifiedAt: info.mtime,
+      };
+    } catch (error) {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    }
+  }
+
+  async list() {
+    let entries;
+    try {
+      entries = await readdir(this.root, { withFileTypes: true });
+    } catch (error) {
+      if (error?.code === 'ENOENT') return [];
+      throw error;
+    }
+
+    const objects = [];
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      try {
+        const key = assertStorageKey(entry.name);
+        const info = await stat(this.pathFor(key));
+        objects.push({
+          key,
+          size: info.size,
+          modifiedAt: info.mtime,
+        });
+      } catch (error) {
+        if (error?.code !== 'INVALID_STORAGE_KEY') throw error;
+      }
+    }
+    return objects;
+  }
+
+  async delete(key) {
+    try {
+      await unlink(this.pathFor(key));
+      return true;
+    } catch (error) {
+      if (error?.code === 'ENOENT') return false;
+      throw error;
+    }
+  }
+
+  async getSignedUrl() {
+    return null;
+  }
+}
+
+export { assertStorageKey };

package/src/storage/s3-storage-driver.js

@@ -0,0 +1,150 @@
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand,
+  S3Client,
+} from '@aws-sdk/client-s3';
+
+import { assertStorageKey } from './local-storage-driver.js';
+
+async function bodyToBuffer(body) {
+  if (!body) return Buffer.alloc(0);
+  if (typeof body.transformToByteArray === 'function') {
+    return Buffer.from(await body.transformToByteArray());
+  }
+  if (Symbol.asyncIterator in Object(body)) {
+    const chunks = [];
+    for await (const chunk of body) chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks);
+  }
+  throw new Error('Unsupported S3 response body type');
+}
+
+function credentialsFromConfig({ accessKeyId, secretAccessKey }) {
+  if (!accessKeyId && !secretAccessKey) return undefined;
+  if (!accessKeyId || !secretAccessKey) {
+    throw new Error('S3 access key id and secret access key must be configured together');
+  }
+  return { accessKeyId, secretAccessKey };
+}
+
+export class S3StorageDriver {
+  constructor({
+    bucket,
+    region = 'us-east-1',
+    endpoint = undefined,
+    accessKeyId = undefined,
+    secretAccessKey = undefined,
+    forcePathStyle = false,
+    client = null,
+  } = {}) {
+    if (!bucket || typeof bucket !== 'string') throw new Error('S3 bucket is required');
+    this.bucket = bucket;
+    this.client = client ?? new S3Client({
+      region,
+      ...(endpoint ? { endpoint } : {}),
+      ...(credentialsFromConfig({ accessKeyId, secretAccessKey })
+        ? { credentials: credentialsFromConfig({ accessKeyId, secretAccessKey }) }
+        : {}),
+      forcePathStyle: forcePathStyle === true,
+    });
+  }
+
+  async put(key, contents) {
+    const safeKey = assertStorageKey(key);
+    if (!Buffer.isBuffer(contents) && !(contents instanceof Uint8Array)) {
+      const error = new Error('S3 storage put requires Buffer or Uint8Array content');
+      error.code = 'INVALID_FILE_CONTENT';
+      throw error;
+    }
+    await this.client.send(new PutObjectCommand({
+      Bucket: this.bucket,
+      Key: safeKey,
+      Body: contents,
+    }));
+    return { key: safeKey, size: contents.byteLength };
+  }
+
+  async get(key) {
+    const safeKey = assertStorageKey(key);
+    const response = await this.client.send(new GetObjectCommand({
+      Bucket: this.bucket,
+      Key: safeKey,
+    }));
+    return bodyToBuffer(response.Body);
+  }
+
+  async stat(key) {
+    const safeKey = assertStorageKey(key);
+    try {
+      const response = await this.client.send(new HeadObjectCommand({
+        Bucket: this.bucket,
+        Key: safeKey,
+      }));
+      return {
+        key: safeKey,
+        size: Number(response.ContentLength ?? 0),
+        modifiedAt: response.LastModified ?? null,
+        etag: response.ETag ?? null,
+      };
+    } catch (error) {
+      if (error?.$metadata?.httpStatusCode === 404 || error?.name === 'NotFound' || error?.name === 'NoSuchKey') {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async list() {
+    const objects = [];
+    let continuationToken;
+
+    do {
+      const response = await this.client.send(new ListObjectsV2Command({
+        Bucket: this.bucket,
+        ...(continuationToken ? { ContinuationToken: continuationToken } : {}),
+      }));
+
+      for (const object of response.Contents ?? []) {
+        if (!object.Key) continue;
+        try {
+          const key = assertStorageKey(object.Key);
+          objects.push({
+            key,
+            size: Number(object.Size ?? 0),
+            modifiedAt: object.LastModified ?? null,
+            etag: object.ETag ?? null,
+          });
+        } catch (error) {
+          if (error?.code !== 'INVALID_STORAGE_KEY') throw error;
+        }
+      }
+
+      continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined;
+      if (response.IsTruncated && !continuationToken) {
+        const error = new Error('S3 inventory response was truncated without a continuation token');
+        error.code = 'STORAGE_INVENTORY_FAILED';
+        throw error;
+      }
+    } while (continuationToken);
+
+    return objects;
+  }
+
+  async delete(key) {
+    const safeKey = assertStorageKey(key);
+    await this.client.send(new DeleteObjectCommand({
+      Bucket: this.bucket,
+      Key: safeKey,
+    }));
+    return true;
+  }
+
+  async getSignedUrl() {
+    return null;
+  }
+}
+
+export { bodyToBuffer, credentialsFromConfig };