endpoint-permissions-kit 0.2.0 → 0.2.1

package/README.md

@@ -66,6 +66,7 @@ Until you run `pkit generate`, TypeScript only knows the role `general`; the rol
 - **One-hop grants.** Access received through a grant never counts as an assignment that activates another grant. Cycles between different names are allowed; only self-reference is rejected.
 - **Data properties.** The keys of `data` are the fields the request touches, walked structurally and compared path by path with the permission. A declared property matches the exact leaf path: `'unicorn'` allows `unicorn` only when it is an empty object or array, and `'unicorn.name'` is what allows `{ unicorn: { name: 'x' } }`. Each `*` stands for exactly one segment and never the first one, so `'unicorn.*'` allows `unicorn.name` but not `unicorn.treasures.id`, and `'*.name'` is rejected at registration. Array elements share their container's path, so `treasures[0].id` is compared as `treasures.id` and `tags: ['a', 'b']` as `tags`; an object key is always a path segment, so `{ treasures: { '0': { id: 1 } } }` is compared as `treasures.0.id`, not `treasures.id`. No key is exempt: `constructor`, `prototype` and `__proto__` are compared and filtered like any other field.
 - **Deny or crop.** With the default `cropper: false` any path outside the permission denies the request, and `fields` lists the index-free paths. With `pkit.context.set('cropper', true)` nothing is denied: the allowed part of `data` is copied out, arrays are compacted and the containers the crop emptied are pruned. Containers that arrived empty and are allowed stay. The `data` object you pass is never mutated.
+- **Reserved fields.** `pkit.context.set('reservedFields', ['id', 'meta.version'])` adds paths that every permission with a property list allows, in both modes: they are never denied and always kept by the crop. The list starts empty, replaces the previous one on each call, is validated once with the rules of declared properties, and is frozen by `seal()`. Matching is exact, like any declared property.
 - **Direct assignment precedence.** If the user holds a name of the requested module directly, that definition decides completely, even when a grant to the same target would be wider. Only when no name of the module is assigned are the applicable grants combined, and their fields are unioned.
 - **One name per module.** A user holds at most one name of a given `role::module`, and at most one name of a module is reachable by grant. Two of either is `AMBIGUOUS_PERMISSION`: the request names no name, so the library denies instead of choosing between a wider and a narrower variant.
 
@@ -131,7 +132,7 @@ The registry lives in `globalThis[Symbol.for('endpoint-permissions-kit')]`, so t
 | `src/constants.ts` | Available methods, the `general` role, the global hook owner marker and the field wildcard |
 | `src/errors.ts` | Creates `PkitError` exceptions with a `code` and renders untrusted values for their messages |
 | `src/state.ts` | Creates and returns the shared registry stored on `globalThis`, and guards its open/sealed lifecycle |
-| `src/context.ts` | Declares and reads the role catalog and the `cropper` flag |
+| `src/context.ts` | Declares and reads the role catalog, the `cropper` flag and the `reservedFields` paths |
 | `src/identifiers.ts` | The `[role]::[module]::[name]` format: builds identifiers, parses them and checks each segment |
 | `src/definitions.ts` | Reads a `registerActions` literal into the frozen definition the registry stores; grant restrictions |
 | `src/registry.ts` | Module, name, role and grant builders; registers actions, grants and hooks |

package/dist/cjs/index.cjs

@@ -120,13 +120,216 @@ function invalidIdentifier(value, code, subject) {
 }
 var identifiers_default = identifiers;
 
+// src/properties.ts
+var PRUNED = Symbol("pruned");
+var MAX_DEPTH = 1000;
+var properties = {
+  checkDeclaredPath(property, permissionPath) {
+    if (property.includes("[") || property.includes("]")) {
+      throw errors_default.create("INVALID_DEFINITION", `${permissionPath}: array indexes are not allowed in properties: "${property}"`);
+    }
+    const segments = segmentsOf(property);
+    for (const segment of segments) {
+      if (segment.length === 0)
+        throw errors_default.create("INVALID_DEFINITION", `${permissionPath}: empty segment in property path: "${property}"`);
+    }
+    if (segments[0] === constants_default.ALL_FIELDS) {
+      throw errors_default.create("INVALID_DEFINITION", `${permissionPath}: a property path cannot start with "${constants_default.ALL_FIELDS}": "${property}"`);
+    }
+  },
+  resolve(data, allowed, reserved, cropper) {
+    if (allowed === constants_default.ALL_FIELDS)
+      return data;
+    const patterns = [];
+    for (const pattern of allowed.concat(reserved))
+      patterns.push(segmentsOf(pattern));
+    const walk = { patterns, segments: [], ancestors: new Set([data]) };
+    if (cropper)
+      return cropData(data, walk);
+    rejectForbiddenPaths(data, walk);
+    return data;
+  }
+};
+function segmentsOf(path) {
+  const segments = [];
+  let segment = "";
+  let index = 0;
+  while (index < path.length) {
+    const character = path[index];
+    if (character === "\\") {
+      segment += path[index + 1] ?? "";
+      index += 2;
+      continue;
+    }
+    if (character === ".") {
+      segments.push(segment);
+      segment = "";
+      index += 1;
+      continue;
+    }
+    segment += character;
+    index += 1;
+  }
+  segments.push(segment);
+  return segments;
+}
+function isAllowedPath(segments, patterns) {
+  for (const pattern of patterns) {
+    if (pattern.length !== segments.length)
+      continue;
+    let isMatch = true;
+    for (let index = 0;index < segments.length; index += 1) {
+      const patternSegment = pattern[index];
+      if (patternSegment === constants_default.ALL_FIELDS)
+        continue;
+      if (patternSegment === segments[index])
+        continue;
+      isMatch = false;
+      break;
+    }
+    if (isMatch)
+      return true;
+  }
+  return false;
+}
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function requireDepth(walk) {
+  if (walk.ancestors.size < MAX_DEPTH)
+    return;
+  throw new RangeError(`data is nested deeper than ${MAX_DEPTH} levels`);
+}
+function setField(target, key, value) {
+  if (key === "__proto__") {
+    Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+    return;
+  }
+  target[key] = value;
+}
+function cropValue(value, walk) {
+  if (Array.isArray(value)) {
+    if (value.length === 0)
+      return isAllowedPath(walk.segments, walk.patterns) ? [] : PRUNED;
+    if (walk.ancestors.has(value))
+      throw new RangeError("data contains a circular reference");
+    requireDepth(walk);
+    walk.ancestors.add(value);
+    const items = [];
+    for (const item of value) {
+      const croppedItem = cropValue(item, walk);
+      if (croppedItem === PRUNED)
+        continue;
+      items.push(croppedItem);
+    }
+    walk.ancestors.delete(value);
+    return items.length === 0 ? PRUNED : items;
+  }
+  if (isPlainObject(value)) {
+    const container = value;
+    const keys = Object.keys(container);
+    if (keys.length === 0)
+      return isAllowedPath(walk.segments, walk.patterns) ? {} : PRUNED;
+    if (walk.ancestors.has(container))
+      throw new RangeError("data contains a circular reference");
+    requireDepth(walk);
+    walk.ancestors.add(container);
+    const cropped = {};
+    let keptCount = 0;
+    for (const key of keys) {
+      walk.segments.push(key);
+      const croppedValue = cropValue(container[key], walk);
+      walk.segments.pop();
+      if (croppedValue === PRUNED)
+        continue;
+      setField(cropped, key, croppedValue);
+      keptCount += 1;
+    }
+    walk.ancestors.delete(container);
+    return keptCount === 0 ? PRUNED : cropped;
+  }
+  return isAllowedPath(walk.segments, walk.patterns) ? value : PRUNED;
+}
+function cropData(data, walk) {
+  const cropped = {};
+  for (const key of Object.keys(data)) {
+    walk.segments.push(key);
+    const croppedValue = cropValue(data[key], walk);
+    walk.segments.pop();
+    if (croppedValue === PRUNED)
+      continue;
+    setField(cropped, key, croppedValue);
+  }
+  return cropped;
+}
+function collectForbiddenPaths(value, walk, forbidden) {
+  if (Array.isArray(value)) {
+    if (value.length === 0 || walk.ancestors.has(value)) {
+      reportPath(walk, forbidden);
+      return;
+    }
+    requireDepth(walk);
+    walk.ancestors.add(value);
+    for (const item of value)
+      collectForbiddenPaths(item, walk, forbidden);
+    walk.ancestors.delete(value);
+    return;
+  }
+  if (isPlainObject(value)) {
+    const container = value;
+    const keys = Object.keys(container);
+    if (keys.length === 0 || walk.ancestors.has(container)) {
+      reportPath(walk, forbidden);
+      return;
+    }
+    requireDepth(walk);
+    walk.ancestors.add(container);
+    for (const key of keys) {
+      walk.segments.push(key);
+      collectForbiddenPaths(container[key], walk, forbidden);
+      walk.segments.pop();
+    }
+    walk.ancestors.delete(container);
+    return;
+  }
+  reportPath(walk, forbidden);
+}
+function reportPath(walk, forbidden) {
+  if (isAllowedPath(walk.segments, walk.patterns))
+    return;
+  forbidden.add(walk.segments.join("."));
+}
+function rejectForbiddenPaths(data, walk) {
+  const forbidden = new Set;
+  for (const key of Object.keys(data)) {
+    walk.segments.push(key);
+    collectForbiddenPaths(data[key], walk, forbidden);
+    walk.segments.pop();
+  }
+  if (forbidden.size === 0)
+    return;
+  const fields = [...forbidden];
+  const error = errors_default.create("PROPERTIES_NOT_ALLOWED", `fields not allowed: ${fields.join(", ")}`);
+  throw Object.assign(error, { fields });
+}
+var properties_default = properties;
+
 // src/state.ts
 var STATE_KEY = Symbol.for("endpoint-permissions-kit");
 var state = {
   getOrCreate() {
     const stateHost = globalThis;
     if (stateHost[STATE_KEY] === undefined) {
-      stateHost[STATE_KEY] = { roles: new Set([constants_default.GENERAL_ROLE]), cropper: false, modules: new Map, snapshot: null };
+      stateHost[STATE_KEY] = {
+        roles: new Set([constants_default.GENERAL_ROLE]),
+        cropper: false,
+        reservedFields: [],
+        modules: new Map,
+        snapshot: null
+      };
     }
     return stateHost[STATE_KEY];
   },
@@ -155,16 +358,23 @@ var context = Object.freeze({
       currentState.cropper = value;
       return;
     }
+    if (contextKey === "reservedFields") {
+      currentState.reservedFields = Object.freeze(readReservedFields(value));
+      return;
+    }
     currentState.roles = new Set(readRoleCatalog(value, currentState.modules.size));
   },
   get(key) {
     const contextKey = checkKey(key);
     const currentState = state_default.getOrCreate();
-    return contextKey === "cropper" ? currentState.cropper : [...currentState.roles];
+    if (contextKey === "cropper")
+      return currentState.cropper;
+    const paths = contextKey === "roles" ? [...currentState.roles] : [...currentState.reservedFields];
+    return paths;
   }
 });
 function checkKey(key) {
-  if (key === "roles" || key === "cropper")
+  if (key === "roles" || key === "cropper" || key === "reservedFields")
     return key;
   throw errors_default.create("INVALID_DEFINITION", `unknown context key: "${errors_default.describe(key)}"`);
 }
@@ -186,6 +396,18 @@ function readRoleCatalog(value, registeredModuleCount) {
     identifiers_default.checkRole(role);
   return catalog;
 }
+function readReservedFields(value) {
+  if (!Array.isArray(value))
+    throw errors_default.create("INVALID_DEFINITION", "reservedFields must be an array of property paths");
+  const fields = [];
+  for (const field of value) {
+    if (typeof field !== "string")
+      throw errors_default.create("INVALID_DEFINITION", "reservedFields must be an array of property paths");
+    properties_default.checkDeclaredPath(field, "reservedFields");
+    fields.push(field);
+  }
+  return fields;
+}
 var context_default = context;
 
 // src/resolve.ts
@@ -317,202 +539,6 @@ var permissions = Object.freeze({
 });
 var permissions_default = permissions;
 
-// src/properties.ts
-var PRUNED = Symbol("pruned");
-var MAX_DEPTH = 1000;
-var properties = {
-  checkDeclaredPath(property, permissionPath) {
-    if (property.includes("[") || property.includes("]")) {
-      throw errors_default.create("INVALID_DEFINITION", `${permissionPath}: array indexes are not allowed in properties: "${property}"`);
-    }
-    const segments = segmentsOf(property);
-    for (const segment of segments) {
-      if (segment.length === 0)
-        throw errors_default.create("INVALID_DEFINITION", `${permissionPath}: empty segment in property path: "${property}"`);
-    }
-    if (segments[0] === constants_default.ALL_FIELDS) {
-      throw errors_default.create("INVALID_DEFINITION", `${permissionPath}: a property path cannot start with "${constants_default.ALL_FIELDS}": "${property}"`);
-    }
-  },
-  resolve(data, allowed, cropper) {
-    if (allowed === constants_default.ALL_FIELDS)
-      return data;
-    const patterns = [];
-    for (const pattern of allowed)
-      patterns.push(segmentsOf(pattern));
-    const walk = { patterns, segments: [], ancestors: new Set([data]) };
-    if (cropper)
-      return cropData(data, walk);
-    rejectForbiddenPaths(data, walk);
-    return data;
-  }
-};
-function segmentsOf(path) {
-  const segments = [];
-  let segment = "";
-  let index = 0;
-  while (index < path.length) {
-    const character = path[index];
-    if (character === "\\") {
-      segment += path[index + 1] ?? "";
-      index += 2;
-      continue;
-    }
-    if (character === ".") {
-      segments.push(segment);
-      segment = "";
-      index += 1;
-      continue;
-    }
-    segment += character;
-    index += 1;
-  }
-  segments.push(segment);
-  return segments;
-}
-function isAllowedPath(segments, patterns) {
-  for (const pattern of patterns) {
-    if (pattern.length !== segments.length)
-      continue;
-    let isMatch = true;
-    for (let index = 0;index < segments.length; index += 1) {
-      const patternSegment = pattern[index];
-      if (patternSegment === constants_default.ALL_FIELDS)
-        continue;
-      if (patternSegment === segments[index])
-        continue;
-      isMatch = false;
-      break;
-    }
-    if (isMatch)
-      return true;
-  }
-  return false;
-}
-function isPlainObject(value) {
-  if (value === null || typeof value !== "object" || Array.isArray(value))
-    return false;
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-function requireDepth(walk) {
-  if (walk.ancestors.size < MAX_DEPTH)
-    return;
-  throw new RangeError(`data is nested deeper than ${MAX_DEPTH} levels`);
-}
-function setField(target, key, value) {
-  if (key === "__proto__") {
-    Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
-    return;
-  }
-  target[key] = value;
-}
-function cropValue(value, walk) {
-  if (Array.isArray(value)) {
-    if (value.length === 0)
-      return isAllowedPath(walk.segments, walk.patterns) ? [] : PRUNED;
-    if (walk.ancestors.has(value))
-      throw new RangeError("data contains a circular reference");
-    requireDepth(walk);
-    walk.ancestors.add(value);
-    const items = [];
-    for (const item of value) {
-      const croppedItem = cropValue(item, walk);
-      if (croppedItem === PRUNED)
-        continue;
-      items.push(croppedItem);
-    }
-    walk.ancestors.delete(value);
-    return items.length === 0 ? PRUNED : items;
-  }
-  if (isPlainObject(value)) {
-    const container = value;
-    const keys = Object.keys(container);
-    if (keys.length === 0)
-      return isAllowedPath(walk.segments, walk.patterns) ? {} : PRUNED;
-    if (walk.ancestors.has(container))
-      throw new RangeError("data contains a circular reference");
-    requireDepth(walk);
-    walk.ancestors.add(container);
-    const cropped = {};
-    let keptCount = 0;
-    for (const key of keys) {
-      walk.segments.push(key);
-      const croppedValue = cropValue(container[key], walk);
-      walk.segments.pop();
-      if (croppedValue === PRUNED)
-        continue;
-      setField(cropped, key, croppedValue);
-      keptCount += 1;
-    }
-    walk.ancestors.delete(container);
-    return keptCount === 0 ? PRUNED : cropped;
-  }
-  return isAllowedPath(walk.segments, walk.patterns) ? value : PRUNED;
-}
-function cropData(data, walk) {
-  const cropped = {};
-  for (const key of Object.keys(data)) {
-    walk.segments.push(key);
-    const croppedValue = cropValue(data[key], walk);
-    walk.segments.pop();
-    if (croppedValue === PRUNED)
-      continue;
-    setField(cropped, key, croppedValue);
-  }
-  return cropped;
-}
-function collectForbiddenPaths(value, walk, forbidden) {
-  if (Array.isArray(value)) {
-    if (value.length === 0 || walk.ancestors.has(value)) {
-      reportPath(walk, forbidden);
-      return;
-    }
-    requireDepth(walk);
-    walk.ancestors.add(value);
-    for (const item of value)
-      collectForbiddenPaths(item, walk, forbidden);
-    walk.ancestors.delete(value);
-    return;
-  }
-  if (isPlainObject(value)) {
-    const container = value;
-    const keys = Object.keys(container);
-    if (keys.length === 0 || walk.ancestors.has(container)) {
-      reportPath(walk, forbidden);
-      return;
-    }
-    requireDepth(walk);
-    walk.ancestors.add(container);
-    for (const key of keys) {
-      walk.segments.push(key);
-      collectForbiddenPaths(container[key], walk, forbidden);
-      walk.segments.pop();
-    }
-    walk.ancestors.delete(container);
-    return;
-  }
-  reportPath(walk, forbidden);
-}
-function reportPath(walk, forbidden) {
-  if (isAllowedPath(walk.segments, walk.patterns))
-    return;
-  forbidden.add(walk.segments.join("."));
-}
-function rejectForbiddenPaths(data, walk) {
-  const forbidden = new Set;
-  for (const key of Object.keys(data)) {
-    walk.segments.push(key);
-    collectForbiddenPaths(data[key], walk, forbidden);
-    walk.segments.pop();
-  }
-  if (forbidden.size === 0)
-    return;
-  const fields = [...forbidden];
-  throw Object.assign(errors_default.create("PROPERTIES_NOT_ALLOWED", `fields not allowed: ${fields.join(", ")}`), { fields });
-}
-var properties_default = properties;
-
 // src/definitions.ts
 var METHODS = new Set(constants_default.METHODS);
 var definitions = {
@@ -837,7 +863,8 @@ function prepareRequest(input, currentState) {
     if (group)
       hooks.push(...group);
   }
-  return { hooks, context, permissions, data: properties_default.resolve(data, access.properties, currentState.cropper) };
+  const allowedData = properties_default.resolve(data, access.properties, currentState.reservedFields, currentState.cropper);
+  return { hooks, context, permissions, data: allowedData };
 }
 function readOptionalObject(value, message) {
   if (value === undefined)
@@ -876,4 +903,4 @@ var defineModule = registry_default.defineModule;
 var pkit = Object.freeze({ context: context_default, module: defineModule, seal, permissions: permissions_default, validate });
 var src_default = pkit;
 
-//# debugId=1BE6B3EEE711E91164756E2164756E21
+//# debugId=276C6E13E676044E64756E2164756E21