@adobe/helix-config-storage 2.10.2 → 2.10.4

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.10.4](https://github.com/adobe/helix-config-storage/compare/v2.10.3...v2.10.4) (2025-12-17)
+
+
+### Bug Fixes
+
+* create version on delete ([#208](https://github.com/adobe/helix-config-storage/issues/208)) ([4725f40](https://github.com/adobe/helix-config-storage/commit/4725f40720bc544cea8dd23038c8addf3445d932))
+
+## [2.10.3](https://github.com/adobe/helix-config-storage/compare/v2.10.2...v2.10.3) (2025-12-01)
+
+
+### Bug Fixes
+
+* **deps:** update external fixes ([#202](https://github.com/adobe/helix-config-storage/issues/202)) ([e9d4694](https://github.com/adobe/helix-config-storage/commit/e9d46942b7807561aa2121aba526109b2f6cb5e6))
+
 ## [2.10.2](https://github.com/adobe/helix-config-storage/compare/v2.10.1...v2.10.2) (2025-11-27)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/helix-config-storage",
-  "version": "2.10.2",
+  "version": "2.10.4",
   "description": "Helix Config Storage",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -36,18 +36,18 @@
     "reporter-options": "configFile=.mocha-multi.json"
   },
   "devDependencies": {
-    "@adobe/eslint-config-helix": "3.0.14",
-    "@eslint/config-helpers": "0.4.2",
+    "@adobe/eslint-config-helix": "3.0.15",
+    "@eslint/config-helpers": "0.5.0",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",
-    "@semantic-release/npm": "13.1.1",
+    "@semantic-release/npm": "13.1.2",
     "ajv-cli": "5.0.0",
     "c8": "10.1.3",
     "eslint": "9.4.0",
     "husky": "9.1.7",
     "json-schema-to-typescript": "15.0.4",
     "junit-report-builder": "5.1.1",
-    "lint-staged": "16.2.6",
+    "lint-staged": "16.2.7",
     "mocha": "11.7.5",
     "mocha-multi-reporters": "1.5.1",
     "mocha-suppress-logs": "0.6.0",
@@ -69,6 +69,6 @@
     "@adobe/helix-shared-utils": "^3.0.2",
     "ajv": "8.17.1",
     "ajv-formats": "3.0.1",
-    "jose": "6.1.1"
+    "jose": "6.1.2"
   }
 }

package/src/config-store.js

@@ -10,197 +10,24 @@
  * governing permissions and limitations under the License.
  */
 /* eslint-disable no-param-reassign */
-import crypto from 'crypto';
-import { decodeJwt } from 'jose';
 import { HelixStorage } from '@adobe/helix-shared-storage';
 import processQueue from '@adobe/helix-shared-process-queue';
 import { StatusCodeError } from './status-code-error.js';
 import {
-  createToken, createUser,
-  migrateToken,
+  createUser,
   updateCodeSource,
   updateContentSource,
-  deepGetOrCreate, deepPut, prune, createSecret, migrateSecret, isDeepEqual, base64ToBase64Url,
+  deepGetOrCreate,
+  deepPut,
+  prune,
+  isDeepEqual,
+  validateUniqueEmail,
 } from './utils.js';
 import { validate as validateSchema } from './config-validator.js';
 import { getMergedConfig } from './config-merge.js';
 import { ValidationError } from './ValidationError.js';
 import { ConfigVersioning } from './config-versioning.js';
-
-const FRAGMENTS_COMMON = {
-  content: 'object',
-  code: 'object',
-  folders: 'object',
-  headers: 'object',
-  metadata: 'object',
-  sidekick: 'object',
-  cdn: {
-    '.': 'object',
-    prod: 'object',
-    preview: 'object',
-    live: 'object',
-  },
-  secrets: {
-    '.': 'secrets',
-    '.param': {
-      name: 'id',
-      '.': 'secret',
-    },
-    '.allowEmpty': true,
-  },
-  access: {
-    '.': 'object',
-    site: 'object',
-    admin: {
-      '.': 'object',
-      role: {
-        '.': 'object',
-        admin: 'object',
-        author: 'object',
-        publish: 'object',
-        develop: 'object',
-        basic_author: 'object',
-        basic_publish: 'object',
-        config: 'object',
-        config_admin: 'object',
-      },
-    },
-    preview: 'object',
-    live: 'object',
-  },
-  tokens: {
-    '.': 'tokens',
-    '.param': {
-      name: 'id',
-      '.': 'token',
-    },
-    '.allowEmpty': true,
-  },
-  groups: {
-    '.': 'object',
-    '.param': {
-      '.': 'object',
-      members: 'object',
-    },
-  },
-  public: '*',
-  features: {
-    '.': '*',
-    '.allowEmpty': true,
-
-  },
-  limits: {
-    '.': '*',
-    '.allowEmpty': true,
-  },
-  robots: 'object',
-  events: {
-    github: 'object',
-  },
-};
-
-const FRAGMENTS = {
-  sites: {
-    ...FRAGMENTS_COMMON,
-    extends: 'object',
-    apiKeys: {
-      '.': 'apiKeys',
-      '.param': {
-        name: 'id',
-        '.': 'apiKey',
-      },
-    },
-  },
-  profiles: FRAGMENTS_COMMON,
-  org: {
-    secrets: {
-      '.': 'secrets',
-      '.param': {
-        name: 'id',
-        '.': 'secret',
-      },
-      '.allowEmpty': true,
-    },
-    apiKeys: {
-      '.': 'apiKeys',
-      '.param': {
-        name: 'id',
-        '.': 'apiKey',
-      },
-      '.allowEmpty': true,
-    },
-    tokens: {
-      '.': 'tokens',
-      '.param': {
-        name: 'id',
-        '.': 'token',
-      },
-      '.allowEmpty': true,
-    },
-    users: {
-      '.': 'users',
-      '.param': {
-        name: 'id',
-        '.': 'user',
-      },
-    },
-    groups: {
-      '.': 'object',
-      '.param': {
-        '.': 'object',
-        members: 'object',
-      },
-    },
-    access: {
-      '.': 'object',
-      admin: 'object',
-    },
-  },
-};
-
-/**
- * Returns the fragment info for a given type and relative path.
- * @param {string} type
- * @param {string|array} relPath
- * @returns {{relPath}|null}
- */
-export function getFragmentInfo(type, relPath = '') {
-  if (!relPath) {
-    return null;
-  }
-  relPath = relPath.split('/');
-  let fragment = FRAGMENTS[type];
-  const info = {
-    relPath,
-    name: relPath[relPath.length - 1],
-  };
-  for (const part of relPath) {
-    let next = fragment[part];
-    if (next === '*') {
-      fragment = '*';
-      break;
-    }
-    if (typeof next === 'object' && next['.'] === '*') {
-      fragment = next;
-      break;
-    }
-    if (!next) {
-      next = fragment['.param'];
-      if (!next) {
-        throw new StatusCodeError(400, 'invalid object path.');
-      }
-      info[next.name] = part;
-    }
-    fragment = next;
-  }
-  if (typeof fragment === 'string') {
-    info.type = fragment;
-  } else {
-    info.type = fragment['.'];
-  }
-  info.allowEmpty = fragment['.allowEmpty'] || false;
-  return info;
-}
+import { Fragment } from './fragment.js';
 
 /**
  * Redact / transform the secret config
@@ -248,54 +75,6 @@ function redact(config, frag) {
   return ret;
 }
 
-/**
- * Updates a secret based on its type. if type is 'key' the value is updated.
- * @param {string} type
- * @param {string} id
- * @param {object} oldData
- * @param {object} data
- * @returns {object} the updated secret data
- */
-function updateSecret(type, id, oldData, data) {
-  oldData.type = type;
-  oldData.id = id;
-  const now = new Date().toISOString();
-
-  // keep the description if missing in data
-  if ('description' in data) {
-    oldData.description = data.description;
-  }
-
-  // handle value specifically, as we don't allow deletion
-  if (type === 'key' && data.value) {
-    oldData.value = data.value;
-    oldData.lastModified = now;
-  }
-  if (!oldData.created) {
-    oldData.created = now;
-  }
-  if (!oldData.lastModified) {
-    oldData.lastModified = oldData.created;
-  }
-  return prune(oldData);
-}
-
-/**
- * Ensures that the given email is not used by another user.
- * @param {string} email
- * @param {User[]} users
- * @throws {StatusCodeError} a 400 status code error if the email is already used
- */
-function validateUniqueEmail(email, users) {
-  if (!email) {
-    throw new StatusCodeError(400, 'missing email');
-  }
-  const existing = users.find((user) => user.email === email);
-  if (existing) {
-    throw new StatusCodeError(400, `email already in use by '${existing.id}'`);
-  }
-}
-
 /**
  * General purpose config store.
  */
@@ -471,7 +250,7 @@ export class ConfigStore {
 
   /**
    * Checks if the permissions allow to update the config.
-   * @param {AdminConfig} ctx
+   * @param {UniversalContext} ctx
    * @param {object} oldConfig
    * @param {object} newConfig
    * @returns {Promise<void>}
@@ -534,6 +313,14 @@ export class ConfigStore {
     }
   }
 
+  /**
+     * Creates a new config entry.
+     * @param {Object} ctx - The context object.
+     * @param {Object} data - The configuration data to create.
+     * @param {string} [relPath=''] - The relative path for substructures (not supported).
+     * @returns {Promise<void>}
+     * @throws {StatusCodeError} If creation is not supported or config already exists.
+     */
   async create(ctx, data, relPath = '') {
     if (relPath) {
       throw new StatusCodeError(409, 'create not supported on substructures.');
@@ -586,6 +373,12 @@ export class ConfigStore {
     await this.purge(ctx, null, config);
   }
 
+  /**
+   * Reads the config or a substructure based on the relative path.
+   * @param {Object} ctx - The context object.
+   * @param {string} [relPath=''] - The relative path for substructures or versions.
+   * @returns {Promise<Object|null>} The config object or null if not found.
+   */
   async read(ctx, relPath = '') {
     if (this.name === '' && (this.type === 'sites' || this.type === 'profiles')) {
       return this.#list(ctx);
@@ -605,22 +398,30 @@ export class ConfigStore {
       return null;
     }
     let obj = JSON.parse(buf);
-    const frag = getFragmentInfo(this.type, relPath);
+    const frag = Fragment.createFragment(this.org, this.type, relPath);
     if (frag) {
       obj = deepGetOrCreate(obj, frag.relPath);
     }
     return redact(obj, frag) ?? null;
   }
 
+  /**
+   * Updates the config or a substructure based on the relative path.
+   * @param {Object} ctx - The context object.
+   * @param {Object} data - The configuration data to update.
+   * @param {string} [relPath=''] - The relative path for substructures or versions.
+   * @returns {Promise<Object|null>} The updated config object or null.
+   */
   async update(ctx, data, relPath = '') {
     if (relPath.startsWith('versions/')) {
       return this.#versioning.updateVersion(ctx, Number.parseInt(relPath.substring('versions/'.length), 10), data.name);
     }
-    const frag = getFragmentInfo(this.type, relPath);
+    const frag = Fragment.createFragment(this.org, this.type, relPath);
     const { restoreVersion } = data ?? {};
     if (restoreVersion && frag) {
       throw new StatusCodeError(400, 'restoreVersion not allowed with object path.');
     }
+
     const storage = HelixStorage.fromContext(ctx).configBus();
     const buf = await storage.get(this.key);
     let old = buf ? JSON.parse(buf) : null;
@@ -638,10 +439,10 @@ export class ConfigStore {
       config = null;
     }
 
-    let ret = null;
     if (!config && frag?.type !== 'secrets' && frag?.type !== 'secret' && frag?.type !== 'tokens' && frag?.type !== 'token') {
       throw new StatusCodeError(400, 'no config in body.');
     }
+    let returnValue = null;
     if (frag) {
       if (!old) {
         if (this.type === 'profiles' && frag.allowEmpty) {
@@ -650,140 +451,9 @@ export class ConfigStore {
           throw new StatusCodeError(404, 'config not found.');
         }
       }
-      if (frag.type === 'token') {
-        // don't allow to update individual token
-        throw new StatusCodeError(400, 'invalid object path.');
-      } else if (frag.type === 'tokens') {
-        // TODO: remove support after all helix4 projects are migrated
-        let token;
-        if (data.jwt) {
-          token = await migrateToken(this.org, data.jwt);
-        } else {
-          // create new token
-          token = createToken(this.org);
-        }
-
-        data = {
-          ...token,
-        };
-        // don't store token value in the config
-        delete data.value;
-        frag.name = token.id;
-        frag.type = 'token';
-        frag.relPath.push(frag.name);
-        ret = token;
-        // don't expose hash in return value
-        delete ret.hash;
-      }
-      if (frag.type === 'apiKeys') {
-        if (!data.jwt) {
-          throw new StatusCodeError(400, 'jwt missing for new keys');
-        }
-        try {
-          const payload = await decodeJwt(data.jwt);
-          data.id = payload.jti;
-          data.roles = payload.roles;
-          data.subject = payload.sub;
-          data.expiration = new Date(payload.exp * 1000).toISOString();
-          delete data.jwt;
-        } catch (e) {
-          throw new StatusCodeError(400, e.message);
-        }
-        data.created = new Date().toISOString();
-        frag.name = base64ToBase64Url(data.id);
-        frag.type = 'apiKey';
-        frag.relPath.push(frag.name);
-      } else if (frag.type === 'apiKey') {
-        if (Object.keys(data).some((key) => key !== 'description')) {
-          throw new StatusCodeError(400, 'not allowed to alter properties other than "description" in apiKey');
-        }
-        const oldData = deepGetOrCreate(old, frag.relPath, false);
-        if (!oldData) {
-          throw new StatusCodeError(404, 'object not found.');
-        }
-        data = Object.assign(oldData, data);
-      }
-      if (frag.type === 'secrets') {
-        // create new secret with random id
-        frag.name = crypto.randomBytes(32).toString('base64url');
-        frag.type = 'secret';
-        frag.relPath.push(frag.name);
-      }
-      if (frag.type === 'secret') {
-        const oldData = deepGetOrCreate(old, frag.relPath);
-        if (oldData) {
-          if (oldData.type === 'hashed') {
-            data = updateSecret('hashed', frag.name, oldData, data);
-          } else {
-            data = updateSecret('key', frag.name, oldData, data);
-          }
-        } else {
-          if (data.value) {
-            data = updateSecret('key', frag.name, { id: frag.name }, data);
-          } else {
-            // TODO: remove support after all helix4 projects are migrated
-            let token;
-            if (data.jwt) {
-              token = await migrateSecret(this.org, data.jwt);
-              frag.name = token.id;
-              frag.relPath.splice(-1, 1, token.id);
-            } else {
-              // create new token
-              token = createSecret(this.org, 'hlx', data);
-              token.id = frag.name;
-            }
-            data = {
-              ...token,
-            };
-            // don't store token value in the config
-            delete data.value;
-            ret = token;
-            // don't expose hash in return value
-            delete ret.hash;
-          }
-          data = prune(data);
-        }
-      } else if (frag.type === 'users') {
-        // todo: define via "schema"
-        if (!old.users) {
-          old.users = [];
-        }
-        if (Array.isArray(data)) {
-          const users = [...old.users];
-          for (const userData of data) {
-            validateUniqueEmail(userData.email, users);
-            users.push(Object.assign(
-              Object.create(null),
-              createUser(),
-              userData,
-            ));
-          }
-          data = users;
-        } else {
-          data = Object.assign(
-            Object.create(null),
-            createUser(),
-            data,
-          );
-          validateUniqueEmail(data.email, old.users);
-          frag.name = data.id;
-          frag.relPath.push(data.id);
-          frag.type = 'user';
-        }
-      } else if (frag.type === 'user') {
-        const user = deepGetOrCreate(old, frag.relPath);
-        if (!user) {
-          throw new StatusCodeError(404, 'object not found.');
-        }
-        if (data.id) {
-          if (data.id !== user.id) {
-            throw new StatusCodeError(400, 'object id mismatch.');
-          }
-        } else {
-          data.id = user.id;
-        }
-      }
-      config = deepPut(old, frag.relPath, data);
+      const result = await Fragment.applyFragment(old, frag, data);
+      config = result.config;
+      returnValue = result.returnValue;
     } else if (config) {
       if (!config.features && old?.features) {
         config.features = old.features;
@@ -805,6 +475,11 @@ export class ConfigStore {
       updateCodeSource(ctx, config.code);
     }
 
+    await this.#store(ctx, storage, buf, config, restoreVersion, versionName);
+    return returnValue ?? redact(deepGetOrCreate(config, frag?.relPath || []), frag);
+  }
+
+  async #store(ctx, storage, buf, config, restoreVersion = false, versionName = '') {
     let oldConfig = null;
     let modified = true;
     if (buf) {
@@ -840,7 +515,6 @@ export class ConfigStore {
     }
     await storage.put(this.key, JSON.stringify(config), 'application/json');
     await this.purge(ctx, purgeConfig, newConfig);
-    return ret ?? redact(data, frag);
   }
 
   async remove(ctx, relPath) {
@@ -854,25 +528,19 @@ export class ConfigStore {
     if (!buf) {
       throw new StatusCodeError(404, 'config not found.');
     }
-    const frag = getFragmentInfo(this.type, relPath);
-    let oldConfig = JSON.parse(buf);
-    if (this.type === 'sites') {
-      // apply profile
-      oldConfig = await this.getAggregatedConfig(ctx, oldConfig);
-    }
-
+    const frag = Fragment.createFragment(this.org, this.type, relPath);
     if (frag) {
-      const data = deepPut(JSON.parse(buf), relPath, null);
-      this.#updateTimeStamps(data);
-      const newConfig = await this.getAggregatedConfig(ctx, data);
-      await this.validate(ctx, newConfig);
-      await storage.put(this.key, JSON.stringify(data), 'application/json');
-      await this.purge(ctx, oldConfig, newConfig);
-      return;
+      const config = deepPut(JSON.parse(buf), relPath, null);
+      await this.#store(ctx, storage, buf, config);
+    } else {
+      await storage.remove(this.key);
+      let oldConfig = JSON.parse(buf);
+      if (this.type === 'sites') {
+        // apply profile
+        oldConfig = await this.getAggregatedConfig(ctx, oldConfig);
+      }
+      await this.purge(ctx, oldConfig, null);
     }
-
-    await storage.remove(this.key);
-    await this.purge(ctx, oldConfig, null);
   }
 
   /**

package/src/fragment.js

@@ -0,0 +1,474 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+/* eslint-disable no-param-reassign */
+import crypto from 'crypto';
+import { decodeJwt } from 'jose';
+import { StatusCodeError } from './status-code-error.js';
+import {
+  createToken,
+  createUser,
+  migrateToken,
+  deepGetOrCreate,
+  prune,
+  createSecret,
+  migrateSecret,
+  base64ToBase64Url,
+  validateUniqueEmail,
+  deepPut,
+} from './utils.js';
+
+const FRAGMENTS_COMMON = {
+  content: 'object',
+  code: 'object',
+  folders: 'object',
+  headers: 'object',
+  metadata: 'object',
+  sidekick: 'object',
+  cdn: {
+    '.': 'object',
+    prod: 'object',
+    preview: 'object',
+    live: 'object',
+  },
+  secrets: {
+    '.': 'secrets',
+    '.param': {
+      name: 'id',
+      '.': 'secret',
+    },
+    '.allowEmpty': true,
+  },
+  access: {
+    '.': 'object',
+    site: 'object',
+    admin: {
+      '.': 'object',
+      role: {
+        '.': 'object',
+        admin: 'object',
+        author: 'object',
+        publish: 'object',
+        develop: 'object',
+        basic_author: 'object',
+        basic_publish: 'object',
+        config: 'object',
+        config_admin: 'object',
+      },
+    },
+    preview: 'object',
+    live: 'object',
+  },
+  tokens: {
+    '.': 'tokens',
+    '.param': {
+      name: 'id',
+      '.': 'token',
+    },
+    '.allowEmpty': true,
+  },
+  groups: {
+    '.': 'object',
+    '.param': {
+      '.': 'object',
+      members: 'object',
+    },
+  },
+  public: '*',
+  features: {
+    '.': '*',
+    '.allowEmpty': true,
+
+  },
+  limits: {
+    '.': '*',
+    '.allowEmpty': true,
+  },
+  robots: 'object',
+  events: {
+    github: 'object',
+  },
+};
+
+const FRAGMENTS = {
+  sites: {
+    ...FRAGMENTS_COMMON,
+    extends: 'object',
+    apiKeys: {
+      '.': 'apiKeys',
+      '.param': {
+        name: 'id',
+        '.': 'apiKey',
+      },
+    },
+  },
+  profiles: FRAGMENTS_COMMON,
+  org: {
+    secrets: {
+      '.': 'secrets',
+      '.param': {
+        name: 'id',
+        '.': 'secret',
+      },
+      '.allowEmpty': true,
+    },
+    apiKeys: {
+      '.': 'apiKeys',
+      '.param': {
+        name: 'id',
+        '.': 'apiKey',
+      },
+      '.allowEmpty': true,
+    },
+    tokens: {
+      '.': 'tokens',
+      '.param': {
+        name: 'id',
+        '.': 'token',
+      },
+      '.allowEmpty': true,
+    },
+    users: {
+      '.': 'users',
+      '.param': {
+        name: 'id',
+        '.': 'user',
+      },
+    },
+    groups: {
+      '.': 'object',
+      '.param': {
+        '.': 'object',
+        members: 'object',
+      },
+    },
+    access: {
+      '.': 'object',
+      admin: 'object',
+    },
+  },
+};
+
+/**
+ * Updates a secret based on its type. if type is 'key' the value is updated.
+ * @param {string} type
+ * @param {string} id
+ * @param {object} oldData
+ * @param {object} data
+ * @returns {object} the updated secret data
+ */
+function updateSecret(type, id, oldData, data) {
+  oldData.type = type;
+  oldData.id = id;
+  const now = new Date().toISOString();
+
+  // keep the description if missing in data
+  if ('description' in data) {
+    oldData.description = data.description;
+  }
+
+  // handle value specifically, as we don't allow deletion
+  if (type === 'key' && data.value) {
+    oldData.value = data.value;
+    oldData.lastModified = now;
+  }
+  if (!oldData.created) {
+    oldData.created = now;
+  }
+  if (!oldData.lastModified) {
+    oldData.lastModified = oldData.created;
+  }
+  return prune(oldData);
+}
+
+export class Fragment {
+  /**
+   * Fragment name
+   * @type string
+   */
+  name;
+
+  /**
+   * Fragment type
+   * @type string
+   */
+  type;
+
+  /**
+   * Config type
+   * @type string
+   */
+  configType;
+
+  /**
+   * object path segments
+   * @type [string]
+   */
+  relPath;
+
+  /**
+   * org of the config
+   * @type string
+   */
+  org;
+
+  /**
+   * Returns the fragment info for a given type and relative path.
+   * @param {string} org config org
+   * @param {string} configType type of the config, org|site|profile
+   * @param {string|array} relPath
+   * @returns {Fragment|null}
+   */
+  static createFragment(org, configType, relPath = '') {
+    if (!relPath) {
+      return null;
+    }
+    relPath = relPath.split('/');
+    let fragment = FRAGMENTS[configType];
+    const info = new Fragment(org, configType, relPath);
+    for (const part of relPath) {
+      let next = fragment[part];
+      if (next === '*') {
+        fragment = '*';
+        break;
+      }
+      if (typeof next === 'object' && next['.'] === '*') {
+        fragment = next;
+        break;
+      }
+      if (!next) {
+        next = fragment['.param'];
+        if (!next) {
+          throw new StatusCodeError(400, 'invalid object path.');
+        }
+        info[next.name] = part;
+      }
+      fragment = next;
+    }
+    if (typeof fragment === 'string') {
+      info.type = fragment;
+    } else {
+      info.type = fragment['.'];
+    }
+    info.allowEmpty = fragment['.allowEmpty'] || false;
+    return info;
+  }
+
+  constructor(org, configType, relPath) {
+    this.org = org;
+    this.configType = configType;
+    this.relPath = relPath;
+    this.name = relPath.at(-1);
+  }
+
+  static async applyFragment(oldConfig, frag, payload) {
+    let result = await frag.#preProcess(oldConfig, payload);
+    if (result.reprocess) {
+      result = await frag.#preProcess(oldConfig, result.data);
+    }
+    return {
+      config: deepPut(oldConfig, [...frag.relPath], result.data),
+      ...result,
+    };
+  }
+
+  #handlers = {
+    token: this.#updateToken,
+    tokens: this.#updateTokens,
+    apiKey: this.#updateApiKey,
+    apiKeys: this.#updateApiKeys,
+    user: this.#updateUser,
+    users: this.#updateUsers,
+    secret: this.#updateSecret,
+    secrets: this.#updateSecrets,
+  };
+
+  async #preProcess(oldConfig, data) {
+    if (this.#handlers[this.type]) {
+      return this.#handlers[this.type].bind(this)(oldConfig, data);
+    }
+    return {
+      data,
+    };
+  }
+
+  // eslint-disable-next-line class-methods-use-this,no-unused-vars
+  #updateToken(oldConfig, data) {
+    // don't allow to update individual token
+    throw new StatusCodeError(400, 'invalid object path.');
+  }
+
+  async #updateTokens(oldConfig, data) {
+    // TODO: remove support after all helix4 projects are migrated
+    let token;
+    if (data.jwt) {
+      token = await migrateToken(this.org, data.jwt);
+    } else {
+      // create new token
+      token = createToken(this.org);
+    }
+
+    data = {
+      ...token,
+    };
+    // don't store token value in the config
+    delete data.value;
+    this.name = token.id;
+    this.type = 'token';
+    this.relPath.push(this.name);
+    const ret = token;
+    // don't expose hash in return value
+    delete ret.hash;
+    return {
+      data,
+      returnValue: ret,
+    };
+  }
+
+  async #updateApiKeys(oldConfig, data) {
+    if (!data.jwt) {
+      throw new StatusCodeError(400, 'jwt missing for new keys');
+    }
+    try {
+      const payload = await decodeJwt(data.jwt);
+      data.id = payload.jti;
+      data.roles = payload.roles;
+      data.subject = payload.sub;
+      data.expiration = new Date(payload.exp * 1000).toISOString();
+      delete data.jwt;
+    } catch (e) {
+      throw new StatusCodeError(400, e.message);
+    }
+    data.created = new Date().toISOString();
+    this.name = base64ToBase64Url(data.id);
+    this.type = 'apiKey';
+    this.relPath.push(this.name);
+    return {
+      data,
+    };
+  }
+
+  async #updateApiKey(oldConfig, data) {
+    if (Object.keys(data).some((key) => key !== 'description')) {
+      throw new StatusCodeError(400, 'not allowed to alter properties other than "description" in apiKey');
+    }
+    const oldData = deepGetOrCreate(oldConfig, this.relPath, false);
+    if (!oldData) {
+      throw new StatusCodeError(404, 'object not found.');
+    }
+    return {
+      data: Object.assign(oldData, data),
+    };
+  }
+
+  async #updateSecrets(oldConfig, data) {
+    this.name = crypto.randomBytes(32).toString('base64url');
+    this.type = 'secret';
+    this.relPath.push(this.name);
+    return {
+      data,
+      // tell processor to re-apply the data to the next (secret) handler.
+      reprocess: true,
+    };
+  }
+
+  async #updateSecret(oldConfig, data) {
+    const oldData = deepGetOrCreate(oldConfig, this.relPath);
+    let returnValue;
+
+    if (oldData) {
+      if (oldData.type === 'hashed') {
+        data = updateSecret('hashed', this.name, oldData, data);
+      } else {
+        data = updateSecret('key', this.name, oldData, data);
+      }
+    } else {
+      if (data.value) {
+        data = updateSecret('key', this.name, { id: this.name }, data);
+      } else {
+        // TODO: remove support after all helix4 projects are migrated
+        let token;
+        if (data.jwt) {
+          token = await migrateSecret(this.org, data.jwt);
+          this.name = token.id;
+          this.relPath.splice(-1, 1, token.id);
+        } else {
+          // create new token
+          token = createSecret(this.org, 'hlx', data);
+          token.id = this.name;
+        }
+        data = {
+          ...token,
+        };
+        // don't store token value in the config
+        delete data.value;
+        returnValue = token;
+        // don't expose hash in return value
+        delete returnValue.hash;
+      }
+      data = prune(data);
+    }
+    return {
+      data,
+      returnValue,
+    };
+  }
+
+  async #updateUsers(oldConfig, data) {
+    // todo: define via "schema"
+    if (!oldConfig.users) {
+      oldConfig.users = [];
+    }
+    if (Array.isArray(data)) {
+      const users = [...oldConfig.users];
+      for (const userData of data) {
+        validateUniqueEmail(userData.email, users);
+        users.push(Object.assign(
+          Object.create(null),
+          createUser(),
+          userData,
+        ));
+      }
+      return {
+        data: users,
+      };
+    }
+
+    data = Object.assign(
+      Object.create(null),
+      createUser(),
+      data,
+    );
+    validateUniqueEmail(data.email, oldConfig.users);
+    this.name = data.id;
+    this.relPath.push(data.id);
+    this.type = 'user';
+    return {
+      data,
+    };
+  }
+
+  async #updateUser(oldConfig, data) {
+    const user = deepGetOrCreate(oldConfig, this.relPath);
+    if (!user) {
+      throw new StatusCodeError(404, 'object not found.');
+    }
+    if (data.id && data.id !== user.id) {
+      throw new StatusCodeError(400, 'object id mismatch.');
+    }
+    return {
+      data: {
+        ...data,
+        id: user.id,
+      },
+    };
+  }
+}

package/src/utils.js

@@ -328,3 +328,19 @@ export function deepPut(obj, path, value) {
 export function isDeepEqual(o0, o1) {
   return JSON.stringify(o0) === JSON.stringify(o1);
 }
+
+/**
+ * Ensures that the given email is not used by another user.
+ * @param {string} email
+ * @param {User[]} users
+ * @throws {StatusCodeError} a 400 status code error if the email is already used
+ */
+export function validateUniqueEmail(email, users) {
+  if (!email) {
+    throw new StatusCodeError(400, 'missing email');
+  }
+  const existing = users.find((user) => user.email === email);
+  if (existing) {
+    throw new StatusCodeError(400, `email already in use by '${existing.id}'`);
+  }
+}