@kubun/mutation 0.11.0 → 0.12.0

package/lib/apply.js

@@ -1,5 +1,6 @@
 import { HLC } from '@kubun/hlc';
 import { DocumentID } from '@kubun/id';
+import { isValidAccessRule, RESERVED_DOCUMENT_FIELDS } from '@kubun/protocol';
 import { fromB64 } from '@sozai/codec';
 import { applyPatches } from '@sozai/patch';
 import { asType, createValidator } from '@sozai/schema';
@@ -36,6 +37,77 @@ export function getTopLevelField(path) {
     const secondSlash = path.indexOf('/', 1);
     return secondSlash === -1 ? path : path.slice(0, secondSlash);
 }
+const RESERVED_FIELD_SET = new Set(RESERVED_DOCUMENT_FIELDS);
+const ACCESS_PERMISSIONS_FIELD = 'accessPermissions';
+/**
+ * Salvage a candidate `accessPermissions` value per rule, mirroring the engine
+ * parser (`parseDocumentAccessPermissions`): a malformed `read` or `write` rule
+ * is dropped on its own while a valid sibling — and any unknown extra keys —
+ * survive. Returns `null` only when the value is not a plain object or no valid
+ * rule remains; otherwise a sanitized copy carrying just the valid rules (plus
+ * unrecognized keys the parser ignores). Enforcing per-rule at the storage
+ * boundary means the SQL read predicates only ever see valid shapes or absence,
+ * and a partly-garbage object never discards a legitimate sibling rule.
+ */ function sanitizeAccessPermissions(value) {
+    if (value == null || typeof value !== 'object') {
+        return null;
+    }
+    const perms = value;
+    const readValid = perms.read !== undefined && isValidAccessRule(perms.read);
+    const writeValid = perms.write !== undefined && isValidAccessRule(perms.write);
+    if (!readValid && !writeValid) {
+        return null;
+    }
+    const sanitized = {
+        ...perms
+    };
+    if (perms.read !== undefined && !readValid) {
+        delete sanitized.read;
+    }
+    if (perms.write !== undefined && !writeValid) {
+        delete sanitized.write;
+    }
+    return sanitized;
+}
+/**
+ * Partition a candidate document into model-declared fields and engine-reserved
+ * fields. Only the model half is validated against the model schema; the
+ * reserved half is re-attached to the persisted result unchanged.
+ *
+ * A malformed `accessPermissions` value is sanitized per rule here rather than
+ * rejecting the mutation: rejecting a signed remote mutation the owner's log
+ * already contains would fork merkle sync permanently, whereas sanitizing keeps
+ * document-data convergence and lets access resolve to model/server defaults.
+ * A salvaged value keeps its valid rules (added to `reserved`); the field is
+ * added to `droppedReserved` and left out of `reserved` only when nothing valid
+ * remains. A well-behaved producer never emits garbage (mint-time validation
+ * catches it first), so this only fires on hostile or buggy remote input.
+ */ function splitReservedFields(data) {
+    const model = {};
+    const reserved = {};
+    const droppedReserved = new Set();
+    for (const [key, value] of Object.entries(data)){
+        if (RESERVED_FIELD_SET.has(key)) {
+            if (key === ACCESS_PERMISSIONS_FIELD) {
+                const sanitized = sanitizeAccessPermissions(value);
+                if (sanitized == null) {
+                    droppedReserved.add(key);
+                    continue;
+                }
+                reserved[key] = sanitized;
+                continue;
+            }
+            reserved[key] = value;
+        } else {
+            model[key] = value;
+        }
+    }
+    return {
+        model,
+        reserved,
+        droppedReserved
+    };
+}
 /**
  * Compute the visible document data from the per-field winning values and the
  * reserved set/delete timestamps. A document is alive when it carries a set
@@ -163,16 +235,30 @@ export async function applyChangeMutation(ctx, mutation) {
     }
     const cloned = structuredClone(base);
     applyPatches(cloned, winningPatches, false);
-    let validated;
+    // Reserved fields are engine metadata the model schema never declares. Split
+    // them out before validating the model-declared remainder, then re-attach so
+    // they persist unchanged (a patch on a reserved field applies as normal).
+    const { model: modelFields, reserved, droppedReserved } = splitReservedFields(cloned);
+    let validatedModel;
     try {
-        validated = asType(validator, cloned);
+        validatedModel = asType(validator, modelFields);
     } catch (err) {
         throw new MutationSchemaValidationError(docID, {
             cause: err
         });
     }
+    const validated = {
+        ...validatedModel,
+        ...reserved
+    };
     for (const path of winningFields){
         const field = path.slice(1);
+        // A dropped reserved field (malformed accessPermissions) is neither
+        // persisted nor allowed to advance its field HLC, so a later valid update
+        // from the owner still wins the LWW comparison and applies.
+        if (droppedReserved.has(field)) {
+            continue;
+        }
         fieldValues[path] = validated[field];
         fieldHLCs[path] = mutation.hlc;
     }
@@ -219,9 +305,16 @@ export async function applySetMutation(ctx, mutation) {
         ctx.store.getFieldHLCs(docID),
         ctx.store.getFieldValues(docID)
     ]);
+    // Reserved fields are engine metadata the model schema never declares. Split
+    // them out before validating the model-declared remainder, then re-attach so
+    // they persist unchanged.
+    const { model: modelData, reserved } = splitReservedFields(mutation.data);
     let data;
     try {
-        data = asType(validator, mutation.data);
+        data = {
+            ...asType(validator, modelData),
+            ...reserved
+        };
     } catch (err) {
         throw new MutationSchemaValidationError(docID, {
             cause: err

package/lib/create.js

@@ -1,7 +1,32 @@
 import { HLC } from '@kubun/hlc';
 import { DocumentID } from '@kubun/id';
+import { isValidAccessPermissions } from '@kubun/protocol';
 import { toB64 } from '@sozai/codec';
+import { InvalidAccessPermissionsError } from './errors.js';
+const ACCESS_PERMISSIONS_FIELD = 'accessPermissions';
+const ACCESS_PERMISSIONS_PATH = `/${ACCESS_PERMISSIONS_FIELD}`;
+/**
+ * Reject a mint whose data carries a malformed reserved `accessPermissions`
+ * field. Absent is fine; present must be well-formed.
+ */ function assertSetAccessPermissions(data) {
+    if (ACCESS_PERMISSIONS_FIELD in data && !isValidAccessPermissions(data[ACCESS_PERMISSIONS_FIELD])) {
+        throw new InvalidAccessPermissionsError('set mutation data');
+    }
+}
+/**
+ * Reject a mint whose patch replaces the whole `accessPermissions` object with a
+ * malformed value. Only whole-object `add`/`replace` ops are checked — that is
+ * the shape every producer emits. Deeper sub-paths and removals are left to the
+ * tolerant apply path, which cannot mis-grant on garbage.
+ */ function assertPatchAccessPermissions(patch) {
+    for (const op of patch){
+        if (op.path === ACCESS_PERMISSIONS_PATH && (op.op === 'add' || op.op === 'replace') && !isValidAccessPermissions(op.value)) {
+            throw new InvalidAccessPermissionsError('change mutation patch');
+        }
+    }
+}
 export async function createSetMutation(params) {
+    assertSetAccessPermissions(params.data);
     const issuer = params.issuer;
     const owner = params.owner ?? issuer;
     const docID = await DocumentID.create(params.modelID, owner, params.unique);
@@ -19,6 +44,7 @@ export async function createSetMutation(params) {
     };
 }
 export function createChangeMutation(params) {
+    assertPatchAccessPermissions(params.patch);
     return {
         typ: 'change',
         iss: params.issuer,

package/lib/errors.d.ts

@@ -5,9 +5,10 @@
  * structured wire response without losing the reason.
  */
 export declare class WriteAccessDeniedError extends Error {
-    readonly code: "KB07";
-    readonly docID: string;
+    #private;
     constructor(docID: string);
+    get code(): 'KB07';
+    get docID(): string;
 }
 /**
  * Thrown by the set apply path when the document ID in `sub` does not match the
@@ -19,9 +20,10 @@ export declare class WriteAccessDeniedError extends Error {
  * the throw into a structured wire response without losing the reason.
  */
 export declare class DocumentIDMismatchError extends Error {
-    readonly code: "KB09";
-    readonly docID: string;
+    #private;
     constructor(docID: string);
+    get code(): 'KB09';
+    get docID(): string;
 }
 /**
  * Thrown by the mutation apply path when an incoming mutation's HLC timestamp
@@ -77,6 +79,17 @@ export declare class MutationSchemaValidationError extends Error {
     get code(): 'KB13';
     get docID(): string;
 }
+/**
+ * Thrown at mutation-mint time when a `set`/`change` mutation would carry a
+ * malformed reserved `accessPermissions` field. Minting is strict so a producer
+ * bug is caught at signing; the receive/apply path stays tolerant (an already
+ * signed remote mutation is never re-rejected on this basis, so convergence is
+ * preserved). Not tagged with a KB apply code because it never reaches the apply
+ * path — it fails before the mutation is signed.
+ */
+export declare class InvalidAccessPermissionsError extends Error {
+    constructor(detail?: string);
+}
 /**
  * True when `err` carries a protocol error code identifying a deterministically
  * permanent mutation reject. A permanent reject is one the sender cannot fix by

package/lib/errors.js

@@ -4,12 +4,17 @@
  * — particularly the RPC handler — can translate the throw into a
  * structured wire response without losing the reason.
  */ export class WriteAccessDeniedError extends Error {
-    code = 'KB07';
-    docID;
+    #docID;
     constructor(docID){
         super(`Access denied: cannot write document ${docID}`);
         this.name = 'WriteAccessDeniedError';
-        this.docID = docID;
+        this.#docID = docID;
+    }
+    get code() {
+        return 'KB07';
+    }
+    get docID() {
+        return this.#docID;
     }
 }
 /**
@@ -21,12 +26,17 @@
  * error code `KB09` so callers — particularly the RPC handler — can translate
  * the throw into a structured wire response without losing the reason.
  */ export class DocumentIDMismatchError extends Error {
-    code = 'KB09';
-    docID;
+    #docID;
     constructor(docID){
         super(`Document ID mismatch: ${docID} is not bound to its owner and unique value`);
         this.name = 'DocumentIDMismatchError';
-        this.docID = docID;
+        this.#docID = docID;
+    }
+    get code() {
+        return 'KB09';
+    }
+    get docID() {
+        return this.#docID;
     }
 }
 /**
@@ -113,6 +123,19 @@
         return this.#docID;
     }
 }
+/**
+ * Thrown at mutation-mint time when a `set`/`change` mutation would carry a
+ * malformed reserved `accessPermissions` field. Minting is strict so a producer
+ * bug is caught at signing; the receive/apply path stays tolerant (an already
+ * signed remote mutation is never re-rejected on this basis, so convergence is
+ * preserved). Not tagged with a KB apply code because it never reaches the apply
+ * path — it fails before the mutation is signed.
+ */ export class InvalidAccessPermissionsError extends Error {
+    constructor(detail){
+        super(`Invalid accessPermissions shape${detail != null ? `: ${detail}` : ''}`);
+        this.name = 'InvalidAccessPermissionsError';
+    }
+}
 const PERMANENT_APPLY_ERROR_CODES = new Set([
     'KB07',
     'KB09',

package/lib/index.d.ts

@@ -3,6 +3,6 @@ export type { DocumentValidator, MutationContext, MutationDB, PostStateGate, Val
 export { applyChangeMutation, applyMutation, applySetMutation, getTopLevelField } from './apply.js';
 export type { CreateChangeMutationParams, CreateRemoveMutationParams, CreateSetMutationParams, } from './create.js';
 export { createChangeMutation, createRemoveMutation, createSetMutation } from './create.js';
-export { DocumentIDMismatchError, HLCDriftError, isPermanentApplyError, MutationSchemaValidationError, OwnerChangeError, UnsupportedMutationTypeError, WriteAccessDeniedError, } from './errors.js';
+export { DocumentIDMismatchError, HLCDriftError, InvalidAccessPermissionsError, isPermanentApplyError, MutationSchemaValidationError, OwnerChangeError, UnsupportedMutationTypeError, WriteAccessDeniedError, } from './errors.js';
 export type { CreateDocumentParams, CreateMutationOperationsParams, MutationOperations, RemoveDocumentParams, SetDocumentParams, UpdateDocumentParams, } from './operations.js';
 export { convertPatchInput, createMutationOperations } from './operations.js';

package/lib/index.js

@@ -1,5 +1,5 @@
 export { HLC } from '@kubun/hlc';
 export { applyChangeMutation, applyMutation, applySetMutation, getTopLevelField } from './apply.js';
 export { createChangeMutation, createRemoveMutation, createSetMutation } from './create.js';
-export { DocumentIDMismatchError, HLCDriftError, isPermanentApplyError, MutationSchemaValidationError, OwnerChangeError, UnsupportedMutationTypeError, WriteAccessDeniedError } from './errors.js';
+export { DocumentIDMismatchError, HLCDriftError, InvalidAccessPermissionsError, isPermanentApplyError, MutationSchemaValidationError, OwnerChangeError, UnsupportedMutationTypeError, WriteAccessDeniedError } from './errors.js';
 export { convertPatchInput, createMutationOperations } from './operations.js';

package/package.json

@@ -1,39 +1,39 @@
 {
   "name": "@kubun/mutation",
-  "version": "0.11.0",
-  "license": "see LICENSE.md",
+  "version": "0.12.0",
   "keywords": [],
+  "license": "see LICENSE.md",
+  "sideEffects": false,
   "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "exports": {
     ".": "./lib/index.js"
   },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "files": [
     "lib/*",
     "LICENSE.md"
   ],
-  "sideEffects": false,
   "dependencies": {
-    "@sozai/codec": "^0.1.0",
-    "@sozai/patch": "^0.1.1",
+    "@sozai/codec": "^0.4.0",
+    "@sozai/patch": "^0.1.3",
     "@sozai/runtime": "^0.1.0",
-    "@sozai/schema": "^0.1.0",
-    "@kubun/hlc": "^0.11.0",
-    "@kubun/id": "^0.11.0"
+    "@sozai/schema": "^0.1.1",
+    "@kubun/hlc": "^0.12.0",
+    "@kubun/id": "^0.12.0"
   },
   "devDependencies": {
-    "@kubun/graphql": "^0.11.0",
-    "@kubun/protocol": "^0.11.0"
+    "@kubun/graphql": "^0.12.0",
+    "@kubun/protocol": "^0.12.0"
   },
   "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
     "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
     "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
     "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
-    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "test": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit -p tsconfig.test.json",
-    "test:unit": "vitest run",
-    "test": "pnpm run test:types && pnpm run test:unit"
+    "test:unit": "vitest run"
   }
 }