@easy-cms/core 0.14.0 → 0.16.0

package/dist/index.js

@@ -3,6 +3,132 @@ var anyone = () => true;
 var isLoggedIn = ({ user }) => user !== null;
 var isAdmin = ({ user }) => user?.role === "admin";
 
+// src/api-keys.ts
+import { createHash, randomBytes, timingSafeEqual } from "crypto";
+var API_KEYS = "api-keys";
+var API_KEY_OPERATIONS = ["read", "create", "update", "delete", "publish"];
+var API_KEY_GLOBAL_OPERATIONS = ["read", "update", "publish"];
+var API_KEY_EXCLUDED = /* @__PURE__ */ new Set(["users", API_KEYS]);
+var KEY_PATTERN = /^ecms_([0-9a-f]{8})_([A-Za-z0-9_-]{32,})$/;
+function isApiKey(token) {
+  return token.startsWith("ecms_");
+}
+function newApiKey() {
+  const prefix = randomBytes(4).toString("hex");
+  const secret = randomBytes(32).toString("base64url");
+  return { key: `ecms_${prefix}_${secret}`, prefix, hash: hashSecret(secret) };
+}
+function hashSecret(secret) {
+  return createHash("sha256").update(secret).digest("hex");
+}
+function parseApiKey(token) {
+  const match = KEY_PATTERN.exec(token);
+  return match ? { prefix: match[1], secret: match[2] } : null;
+}
+function secretMatches(secret, hash) {
+  if (typeof hash !== "string") return false;
+  const a = Buffer.from(hashSecret(secret), "hex");
+  const b = Buffer.from(hash, "hex");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function keyAllows(user, target, operation) {
+  const key2 = user?.apiKey;
+  if (!key2) return true;
+  if ("collection" in target) {
+    if (API_KEY_EXCLUDED.has(target.collection)) return false;
+    return key2.permissions.collections?.[target.collection]?.includes(operation) ?? false;
+  }
+  const allowed2 = key2.permissions.globals?.[target.global];
+  return allowed2?.includes(operation) ?? false;
+}
+var isAdmin2 = (user) => user?.role === "admin";
+var ownKeys = ({ user }) => !user || user.apiKey ? false : isAdmin2(user) ? true : { user: { equals: user.id } };
+var system = { update: () => false };
+var apiKeysCollection = {
+  slug: API_KEYS,
+  labels: {
+    singular: { en: "API key", th: "API key" },
+    plural: { en: "API keys", th: "API keys" }
+  },
+  icon: "key",
+  useAsTitle: "name",
+  access: {
+    read: ownKeys,
+    // Through `createApiKey` (POST <api>/api-keys), which generates the secret.
+    create: ({ user }) => !!user && !user.apiKey,
+    update: ownKeys,
+    delete: ownKeys
+  },
+  fields: [
+    { name: "name", type: "text", required: true, label: { en: "Name", th: "\u0E0A\u0E37\u0E48\u0E2D" } },
+    {
+      name: "permissions",
+      type: "json",
+      label: { en: "Permissions", th: "\u0E2A\u0E34\u0E17\u0E18\u0E34\u0E4C" },
+      admin: { component: "ecms-api-key-permissions" }
+    },
+    {
+      name: "expiresAt",
+      type: "date",
+      label: { en: "Expires", th: "\u0E2B\u0E21\u0E14\u0E2D\u0E32\u0E22\u0E38" },
+      position: "sidebar"
+    },
+    {
+      name: "prefix",
+      type: "text",
+      index: true,
+      label: { en: "Key starts with", th: "\u0E02\u0E36\u0E49\u0E19\u0E15\u0E49\u0E19\u0E14\u0E49\u0E27\u0E22" },
+      position: "sidebar",
+      access: system
+    },
+    {
+      name: "user",
+      type: "relationship",
+      to: "users",
+      label: { en: "Owner", th: "\u0E40\u0E08\u0E49\u0E32\u0E02\u0E2D\u0E07" },
+      position: "sidebar",
+      access: system
+    },
+    {
+      name: "lastUsedAt",
+      type: "date",
+      label: { en: "Last used", th: "\u0E43\u0E0A\u0E49\u0E25\u0E48\u0E32\u0E2A\u0E38\u0E14" },
+      position: "sidebar",
+      access: system
+    },
+    { name: "keyHash", type: "text", hidden: true }
+  ],
+  hooks: {
+    // Only real collections, globals and operations are kept.
+    beforeChange: [
+      ({ data, cms }) => data.permissions === void 0 ? data : {
+        ...data,
+        permissions: cleanPermissions(data.permissions, {
+          collections: cms.config.collections.map((c) => c.slug),
+          globals: cms.config.globals.map((g) => g.slug)
+        })
+      }
+    ]
+  }
+};
+function cleanPermissions(value, known) {
+  const input = typeof value === "object" && value !== null ? value : {};
+  const pick = (group, slugs, operations) => {
+    const out = {};
+    if (typeof group !== "object" || group === null) return out;
+    for (const [slug, ops] of Object.entries(group)) {
+      if (!slugs.includes(slug) || API_KEY_EXCLUDED.has(slug) || !Array.isArray(ops)) continue;
+      const valid = operations.filter((op) => ops.includes(op));
+      if (valid.length) out[slug] = valid;
+    }
+    return out;
+  };
+  return {
+    collections: pick(input.collections, known.collections, API_KEY_OPERATIONS),
+    globals: pick(input.globals, known.globals, API_KEY_GLOBAL_OPERATIONS)
+  };
+}
+
 // src/errors.ts
 var ConfigError = class _ConfigError extends Error {
   issues;
@@ -412,7 +538,7 @@ var webhookDeliveriesCollection = {
 };
 
 // src/auth/password.ts
-import { randomBytes, scrypt, timingSafeEqual } from "crypto";
+import { randomBytes as randomBytes2, scrypt, timingSafeEqual as timingSafeEqual2 } from "crypto";
 var MIN_PASSWORD_LENGTH = 8;
 var N = 2 ** 17;
 var R = 8;
@@ -431,7 +557,7 @@ function derive(password, salt, n, r, p, length) {
   });
 }
 async function hashPassword(password) {
-  const salt = randomBytes(16);
+  const salt = randomBytes2(16);
   const key2 = await derive(password, salt, N, R, P, KEY_LENGTH);
   return ["scrypt", N, R, P, salt.toString("base64url"), key2.toString("base64url")].join("$");
 }
@@ -447,7 +573,7 @@ async function verifyPassword(password, stored) {
     Number(p),
     expected.length
   );
-  return key2.length === expected.length && timingSafeEqual(key2, expected);
+  return key2.length === expected.length && timingSafeEqual2(key2, expected);
 }
 var dummyHash;
 async function fakeVerify(password) {
@@ -457,12 +583,12 @@ async function fakeVerify(password) {
 }
 
 // src/auth/tokens.ts
-import { createHash, createHmac, randomBytes as randomBytes2, timingSafeEqual as timingSafeEqual2 } from "crypto";
+import { createHash as createHash2, createHmac, randomBytes as randomBytes3, timingSafeEqual as timingSafeEqual3 } from "crypto";
 function newToken() {
-  return randomBytes2(32).toString("base64url");
+  return randomBytes3(32).toString("base64url");
 }
 function hashToken(token) {
-  return createHash("sha256").update(token).digest("hex");
+  return createHash2("sha256").update(token).digest("hex");
 }
 function hmac(secret, value) {
   return createHmac("sha256", secret).update(value).digest("base64url");
@@ -482,7 +608,7 @@ function csrfToken(secret, token) {
 function safeEqual(a, b) {
   const left = Buffer.from(a);
   const right = Buffer.from(b);
-  return left.length === right.length && timingSafeEqual2(left, right);
+  return left.length === right.length && timingSafeEqual3(left, right);
 }
 function signPreviewToken(secret, target, expiresAt) {
   const payload = Buffer.from(
@@ -568,9 +694,13 @@ var Auth = class {
     const session = await this.findSession(token);
     if (session) await this.db.delete({ collection: SESSIONS, id: session.id });
   }
-  /** Returns the user for a signed session token, or `null` if it is invalid or expired. */
+  /**
+   * Returns the user for a signed session token, or for an API key (`ecms_…`, with `apiKey` set
+   * on the user), or `null` if it is invalid or expired.
+   */
   async verify(signedToken) {
     if (!signedToken) return null;
+    if (isApiKey(signedToken)) return this.verifyApiKey(signedToken);
     const token = unsignToken(this.config.secret, signedToken);
     if (!token) return null;
     const session = await this.findSession(token);
@@ -606,6 +736,40 @@ var Auth = class {
     for (const session of sessions.docs)
       await this.db.delete({ collection: SESSIONS, id: session.id });
   }
+  /** The owner of an API key, limited by the key; `null` when unknown, expired or disabled. */
+  async verifyApiKey(token) {
+    if (!this.cms.config.collections.some((c) => c.slug === API_KEYS)) return null;
+    const parsed = parseApiKey(token);
+    if (!parsed) return null;
+    const { docs } = await this.db.find({
+      collection: API_KEYS,
+      where: { prefix: { equals: parsed.prefix } },
+      sort: [],
+      limit: 1,
+      page: 1
+    });
+    const key2 = docs[0];
+    if (!key2 || !secretMatches(parsed.secret, key2.keyHash)) return null;
+    const now = /* @__PURE__ */ new Date();
+    if (typeof key2.expiresAt === "string" && key2.expiresAt <= now.toISOString()) return null;
+    const owner = await this.db.findById({ collection: USERS, id: key2.user });
+    if (!owner || owner.active === false) return null;
+    const last = typeof key2.lastUsedAt === "string" ? Date.parse(key2.lastUsedAt) : 0;
+    if (now.getTime() - last > 6e4) {
+      const { id: _id, ...rest } = key2;
+      await this.db.update({
+        collection: API_KEYS,
+        id: key2.id,
+        data: { ...rest, lastUsedAt: now.toISOString() }
+      });
+    }
+    const apiKey = {
+      id: key2.id,
+      name: String(key2.name ?? ""),
+      permissions: key2.permissions ?? {}
+    };
+    return { ...await this.toAuthUser(owner), apiKey };
+  }
   // -------------------------------------------------------------------------
   async startSession(user) {
     const token = newToken();
@@ -744,7 +908,8 @@ var ADMIN_ICONS = [
   "circle-help",
   "award",
   "ticket",
-  "camera"
+  "camera",
+  "key"
 ];
 function defineConfig(config) {
   return config;
@@ -1285,6 +1450,7 @@ var RESERVED_SLUGS = /* @__PURE__ */ new Set([
   "document-versions",
   "scheduled-jobs",
   "webhook-deliveries",
+  "api-keys",
   "jobs",
   "migrations",
   "access"
@@ -1333,6 +1499,8 @@ function validateConfig(config) {
     checkSlug(global2, `globals[${i}]`, seenGlobals, add);
   });
   validateEndpoints(config, collectionSlugs, add);
+  const apiKeys = config.apiKeys;
+  if (apiKeys !== void 0 && typeof apiKeys !== "boolean") add("apiKeys", "must be true or false");
   collections.forEach((collection2, i) => {
     const path = `collections.${collection2.slug ?? `[${i}]`}`;
     validateContainer(collection2, path, collectionSlugs, add);
@@ -1804,7 +1972,7 @@ function validateComponents(components, path, add) {
 }
 var ENDPOINT_METHODS = ["get", "post", "put", "patch", "delete"];
 var ENDPOINT_SEGMENT = /^(:[A-Za-z_][A-Za-z0-9_]*|[A-Za-z0-9._~-]+)$/;
-var RESERVED_ENDPOINT_ROOTS = /* @__PURE__ */ new Set(["users", "globals", "admin", "jobs", "media"]);
+var RESERVED_ENDPOINT_ROOTS = /* @__PURE__ */ new Set(["users", "globals", "admin", "jobs", "media", "api-keys"]);
 function validateEndpoints(config, collectionSlugs, add) {
   const endpoints = config.endpoints;
   if (endpoints === void 0) return;
@@ -1953,7 +2121,8 @@ async function resolveConfig(input) {
       ...internalCollections,
       ...usesVersions(config) ? [versionsCollection] : [],
       ...usesSchedule(config) ? [scheduledJobsCollection] : [],
-      ...(config.webhooks?.length ?? 0) > 0 ? [webhookDeliveriesCollection] : []
+      ...(config.webhooks?.length ?? 0) > 0 ? [webhookDeliveriesCollection] : [],
+      ...config.apiKeys ? [apiKeysCollection] : []
     ],
     globals: config.globals ?? [],
     endpoints: config.endpoints ?? []
@@ -2014,7 +2183,7 @@ async function loadConfig(options = {}) {
 }
 
 // src/local-api.ts
-import { randomBytes as randomBytes3 } from "crypto";
+import { randomBytes as randomBytes4 } from "crypto";
 
 // src/localization.ts
 var ALL_LOCALES = "all";
@@ -2593,6 +2762,7 @@ var EasyCMS = class {
     const config = this.collection(MEDIA);
     const guard = guardOf(options);
     if (guard.enforce) {
+      this.checkKey(guard, { collection: MEDIA }, "create");
       const allowed2 = await evaluateAccess(config.access?.create, { user: guard.user, data });
       if (allowed2 !== true) throw deny(guard.user);
     }
@@ -2611,7 +2781,7 @@ var EasyCMS = class {
         }
       ]);
     }
-    const random = randomBytes3(4).toString("hex");
+    const random = randomBytes4(4).toString("hex");
     const filename = storageKey(file.name, mimeType, random);
     const stored = [];
     try {
@@ -2642,6 +2812,41 @@ var EasyCMS = class {
       throw error;
     }
   }
+  /**
+   * Creates an API key (needs `apiKeys: true`) and returns it once: only a hash is stored.
+   * With access enforced the key belongs to `user`; trusted calls name the owner in `data.user`.
+   */
+  async createApiKey(data, options = {}) {
+    if (!this.config.collections.some((c) => c.slug === API_KEYS))
+      throw new QueryError("API keys are off: set `apiKeys: true` in the config");
+    const config = this.collection(API_KEYS);
+    const guard = guardOf(options);
+    if (guard.enforce) {
+      const allowed2 = await evaluateAccess(config.access?.create, { user: guard.user });
+      if (allowed2 !== true) throw deny(guard.user);
+    }
+    const owner = guard.enforce ? guard.user?.id : data.user;
+    if (owner === void 0 || owner === null)
+      throw new ValidationError(API_KEYS, [{ field: "user", message: "is required" }]);
+    const { key: key2, prefix, hash } = newApiKey();
+    const expiresAt = data.expiresAt instanceof Date ? data.expiresAt.toISOString() : data.expiresAt;
+    const created = await this.createDocument(
+      config,
+      {
+        name: data.name,
+        permissions: data.permissions ?? {},
+        expiresAt: expiresAt ?? null,
+        prefix,
+        user: owner
+      },
+      { depth: 0 },
+      guard
+    );
+    const raw = await this.db.findById({ collection: API_KEYS, id: created.id });
+    const { id: _id, ...rest } = raw;
+    await this.db.update({ collection: API_KEYS, id: created.id, data: { ...rest, keyHash: hash } });
+    return { key: key2, doc: created };
+  }
   /** Public URL of a stored file. */
   mediaURL(key2) {
     const custom = this.storage.url?.(key2);
@@ -2739,6 +2944,7 @@ var EasyCMS = class {
     let parsed;
     if (id === null) {
       if (guard.enforce) {
+        this.checkKey(guard, { collection: collection2 }, "create");
         const allowed2 = await evaluateAccess(config.access?.create, { user: guard.user, data: raw });
         if (allowed2 !== true) throw deny(guard.user);
       }
@@ -2813,7 +3019,7 @@ var EasyCMS = class {
     return { doc: global2, url: this.previewURL(config, global2, options) };
   }
   /** Coerces preview input like a save would, keeping values that would fail validation. */
-  async previewDoc(config, data, system, options = {}) {
+  async previewDoc(config, data, system2, options = {}) {
     const locale = this.localeOf(options);
     const { data: clean } = await validateFields(config.fields, data, {
       operation: "update",
@@ -2826,7 +3032,7 @@ var EasyCMS = class {
       ...data,
       ...clean,
       ...config.drafts ? { status: data.status } : {},
-      ...system,
+      ...system2,
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
   }
@@ -2857,6 +3063,8 @@ var EasyCMS = class {
     const existing = parsed === void 0 ? null : await this.db.findById({ collection: collection2, id: parsed });
     if (!existing || parsed === void 0) throw new NotFoundError(collection2, id);
     await this.checkDocumentAccess(config, "update", guard, parsed, raw);
+    if (config.drafts && (mode === "unpublish" || raw.status === "published"))
+      this.checkKey(guard, { collection: collection2 }, "publish");
     const [current] = await this.withDrafts(config, [existing]);
     const { input, password } = splitPassword(config, raw);
     const filtered = await filterInput(
@@ -3043,6 +3251,8 @@ var EasyCMS = class {
     const config = this.global(slug);
     const guard = guardOf(options);
     await this.checkGlobalAccess(config, "update", guard);
+    if (config.drafts && (mode === "unpublish" || raw.status === "published"))
+      this.checkKey(guard, { global: slug }, "publish");
     const input = await filterInput(
       config.fields,
       raw,
@@ -3276,12 +3486,14 @@ var EasyCMS = class {
     const existing = parsed === void 0 ? null : await this.db.findById({ collection: collection2, id: parsed });
     if (!existing || parsed === void 0) throw new NotFoundError(collection2, id);
     await this.checkDocumentAccess(config, "update", guardOf(options), parsed, void 0);
+    this.checkKey(guardOf(options), { collection: collection2 }, "publish");
     return { config, parsed };
   }
   async globalScheduleTarget(slug, options) {
     const config = this.global(slug);
     if (!config.schedule) throw new QueryError(`"${slug}" has no schedule`);
     await this.checkGlobalAccess(config, "update", guardOf(options));
+    this.checkKey(guardOf(options), { global: slug }, "publish");
   }
   async addJob(parent, doc, job, options) {
     const runAt = new Date(job.at);
@@ -3380,15 +3592,23 @@ var EasyCMS = class {
     if (!config) throw new QueryError(`Unknown global "${slug}"`);
     return config;
   }
+  /** Refuses what a request's API key does not allow (see `ApiKeyPermissions`). */
+  checkKey(guard, target, operation) {
+    if (!guard.enforce || keyAllows(guard.user, target, operation)) return;
+    const name = "collection" in target ? target.collection : target.global;
+    throw new ForbiddenError(`This API key may not ${operation} "${name}"`);
+  }
   /** The query constraint read access adds, or `undefined` when there is none. Throws when denied. */
   async readWhere(config, guard, where) {
     if (!guard.enforce) return where;
+    this.checkKey(guard, { collection: config.slug }, "read");
     const access = await evaluateAccess(config.access?.read, { user: guard.user });
     if (access === false) throw deny(guard.user);
     return andWhere(where, access);
   }
   async checkDocumentAccess(config, operation, guard, id, data) {
     if (!guard.enforce) return;
+    this.checkKey(guard, { collection: config.slug }, operation);
     const access = await evaluateAccess(config.access?.[operation], {
       user: guard.user,
       id,
@@ -3406,6 +3626,7 @@ var EasyCMS = class {
   }
   async checkGlobalAccess(config, operation, guard) {
     if (!guard.enforce) return;
+    this.checkKey(guard, { global: config.slug }, operation);
     const access = await evaluateAccess(config.access?.[operation], { user: guard.user });
     if (typeof access === "object")
       throw new QueryError(`${operation} access of global "${config.slug}" must return a boolean`);
@@ -3459,6 +3680,9 @@ var EasyCMS = class {
     const guard = guardOf(options);
     const collection2 = config.slug;
     if (guard.enforce) {
+      this.checkKey(guard, { collection: collection2 }, "create");
+      if (config.drafts && raw.status === "published")
+        this.checkKey(guard, { collection: collection2 }, "publish");
       const allowed2 = await evaluateAccess(config.access?.create, { user: guard.user, data: raw });
       if (typeof allowed2 === "object")
         throw new QueryError(`create access of "${collection2}" must return a boolean`);
@@ -3823,7 +4047,7 @@ function asObject(data, name) {
 }
 
 // src/rest/admin-modules.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import { readFile as readFile2 } from "fs/promises";
 import { createRequire } from "module";
 import { join as join2 } from "path";
@@ -3864,7 +4088,7 @@ async function readAdminModule(cms, index) {
   if (!file) return void 0;
   const body = await readFile2(file, "utf8").catch(() => void 0);
   if (body === void 0) return void 0;
-  return { body, etag: `"${createHash2("sha1").update(body).digest("base64url")}"` };
+  return { body, etag: `"${createHash3("sha1").update(body).digest("base64url")}"` };
 }
 
 // src/rest/admin-schema.ts
@@ -4130,6 +4354,8 @@ function createRestHandler(instance, options = {}) {
       const segments = url.pathname.slice(basePath.length).split("/").filter(Boolean).map((s) => decodeURIComponent(s));
       const { token, via } = readToken(request);
       const user = token ? await cms.auth.verify(token) : null;
+      if (!user && via === "bearer" && token?.startsWith("ecms_"))
+        throw new UnauthorizedError("Invalid or expired API key");
       const ctx = { request, url, user, via: user ? via : null, token, headers };
       const method = request.method.toUpperCase();
       if (method !== "GET" && method !== "HEAD") checkCsrf(cms, ctx);
@@ -4331,6 +4557,18 @@ async function route(cms, ctx, method, segments, options) {
       body: await cms.upload(file, data, { ...access, ...parseDepth(ctx.url) })
     };
   }
+  if (first === API_KEYS && second === void 0 && method === "POST") {
+    const body = await readJson(ctx.request);
+    const { key: key2, doc } = await cms.createApiKey(
+      {
+        name: typeof body.name === "string" ? body.name : "",
+        ...body.permissions !== void 0 ? { permissions: body.permissions } : {},
+        ...typeof body.expiresAt === "string" ? { expiresAt: body.expiresAt } : {}
+      },
+      access
+    );
+    return { status: 201, body: { ...doc, key: key2 } };
+  }
   const collection2 = first;
   if (INTERNAL_COLLECTIONS.has(collection2) || !cms.config.collections.some((c) => c.slug === collection2)) {
     throw new HttpError(`Unknown collection "${collection2}"`, 404);
@@ -4817,6 +5055,9 @@ ${map(n.globals)}
 }
 export {
   ADMIN_ICONS,
+  API_KEYS,
+  API_KEY_GLOBAL_OPERATIONS,
+  API_KEY_OPERATIONS,
   Auth,
   BUILTIN_COLLECTIONS,
   CONFIG_FILE_NAMES,
@@ -4866,6 +5107,7 @@ export {
   importConfig,
   isAdmin,
   isLoggedIn,
+  keyAllows,
   loadConfig,
   localStorage,
   mergeForUpdate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easy-cms/core",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Embedded, code-first headless CMS for Nuxt and Next.js",
   "license": "MIT",
   "type": "module",