@kubun/mutation 0.9.0 → 0.10.1

package/lib/apply.d.ts

@@ -5,12 +5,6 @@ import { DocumentID } from '@kubun/id';
 import type { ChangeDocumentMutation, DocumentData, DocumentModel, DocumentMutation, DocumentNode, SetDocumentMutation } from '@kubun/protocol';
 export type DocumentValidator = Validator<DocumentData>;
 export type ValidatorsRecord = Record<string, Promise<DocumentValidator>>;
-export type AccessChecker = (doc: {
-    id: string;
-    model: string;
-    owner: string;
-    data: DocumentData | null;
-}, permissionType: 'read' | 'write') => Promise<boolean>;
 /**
  * Post-state access gate evaluated AFTER the post-apply `DocumentNode` is
  * computed in memory but BEFORE any persist call. Returning `false` instructs
@@ -44,7 +38,12 @@ export type MutationDB = {
 export type MutationContext = {
     store: MutationDB;
     validators: ValidatorsRecord;
-    accessChecker?: AccessChecker;
+    /**
+     * Capability gate for non-owner writes. When the mutation issuer is not the
+     * document owner, the write is only applied if this returns `true`. Absent an
+     * injected checker, only the owner may write (owner-only safe default).
+     */
+    checkWriteAccess?: (doc: DocumentNode, mutation: DocumentMutation) => Promise<boolean>;
     hlc?: HLC;
     maxDriftMS?: number;
     /**

package/lib/apply.js

@@ -1 +1 @@
-import{fromB64 as t}from"@enkaku/codec";import{applyPatches as e}from"@enkaku/patch";import{asType as a,createValidator as r}from"@enkaku/schema";import{HLC as o}from"@kubun/hlc";import{DocumentID as n}from"@kubun/id";export function getDocumentValidator(t,e){return null==t.validators[e]&&(t.validators[e]=t.store.getDocumentModel(e).then(t=>r({...t.schema,$id:e}))),t.validators[e]}function i(t,e,a){let r=o.parse(t),n=Date.now(),i=r.wallTime-n;if(i>e)throw Error(`HLC timestamp too far in the future: ${i}ms drift exceeds ${e}ms limit`);a&&a.receive(r)}export function getTopLevelField(t){let e=t.indexOf("/",1);return -1===e?t:t.slice(0,e)}export async function applyChangeMutation(t,r){let o=n.fromString(r.sub),l=o.toString(),u=await t.store.getDocument(o);if(null==u)throw Error(`Document not found: ${l}`);if(r.iss!==u.owner)throw Error("Invalid mutation issuer");if(t.accessChecker&&!await t.accessChecker(u,"write"))throw Error(`Access denied: cannot write document ${l}`);null!=t.maxDriftMS&&i(r.hlc,t.maxDriftMS,t.hlc);let s=o.model.toString(),c=await t.store.getFieldHLCs(l)??{};if(1===r.patch.length&&"replace"===r.patch[0].op&&"/"===r.patch[0].path&&null===r.patch[0].value){let e={...c,"/":r.hlc},a=Object.entries(e).every(([t,e])=>"/"===t||r.hlc>=e);if(a&&null!=t.postStateGate){let e={...u,data:null};if(!await t.postStateGate(e))return null}return(await t.store.updateFieldHLCs(o,e),a)?await t.store.saveDocument({id:o,existing:u,data:null}):u}if(null!=c["/"]&&null===u.data)return u;let d=await getDocumentValidator(t,s),p=new Map;for(let t of r.patch){let e=getTopLevelField(t.path),a=p.get(e);null!=a?a.push(t):p.set(e,[t])}let f={...c},m=[];for(let[t,e]of p){let a=c[t];(null==a||r.hlc>a)&&(m.push(...e),f[t]=r.hlc)}if(0===m.length)return u;let h=structuredClone(u.data??{});e(h,m,!1);let w=a(d,h);if(null!=t.postStateGate){let e={...u,data:w};if(!await t.postStateGate(e))return null}return await t.store.updateFieldHLCs(o,f),await t.store.saveDocument({id:o,existing:u,data:w})}export async function applySetMutation(e,r){let o=r.aud??r.iss;if(r.iss!==o)throw Error("Invalid mutation issuer");let l=n.fromString(r.sub),u=l.toString(),s=l.model.toString();null!=e.maxDriftMS&&i(r.hlc,e.maxDriftMS,e.hlc);let[c,d]=await Promise.all([e.store.getDocument(l),getDocumentValidator(e,s)]),p=a(d,r.data),f={};for(let t of Object.keys(p))f[`/${t}`]=r.hlc;if(null===c){if(null!=e.postStateGate){let t={id:u,model:s,owner:o,data:p,createdAt:new Date(0),updatedAt:null};if(!await e.postStateGate(t))return null}let a=await e.store.createDocument({id:l,owner:o,data:p,unique:t(r.unq)});return await e.store.updateFieldHLCs(l,f),a}if(c.owner!==o)throw Error(`Cannot change owner from ${c.owner} to ${o} in document: ${l.toString()}`);if(e.accessChecker&&!await e.accessChecker(c,"write"))throw Error(`Access denied: cannot write document ${l.toString()}`);let m=await e.store.getFieldHLCs(u)??{},h={...c.data??{}},w={...m},g=!1;for(let[t,e]of Object.entries(p)){let a=`/${t}`,o=m[a];(null==o||r.hlc>o)&&(h[t]=e,w[a]=r.hlc,g=!0)}if(!g)return c;let S=a(d,h);if(null!=e.postStateGate){let t={...c,data:S};if(!await e.postStateGate(t))return null}return await e.store.updateFieldHLCs(l,w),await e.store.saveDocument({id:l,existing:c,data:S})}export async function applyMutation(t,e){switch(e.typ){case"change":return await applyChangeMutation(t,e);case"set":return await applySetMutation(t,e);default:throw Error("Unsupported mutation type")}}
+import{fromB64 as t}from"@enkaku/codec";import{applyPatches as e}from"@enkaku/patch";import{asType as a,createValidator as r}from"@enkaku/schema";import{HLC as l}from"@kubun/hlc";import{DocumentID as o}from"@kubun/id";import{WriteAccessDeniedError as n}from"./errors.js";export function getDocumentValidator(t,e){return null==t.validators[e]&&(t.validators[e]=t.store.getDocumentModel(e).then(t=>r({...t.schema,$id:e}))),t.validators[e]}function i(t,e){let a=l.parse(t),r=Date.now(),o=a.wallTime-r;if(o>e)throw Error(`HLC timestamp too far in the future: ${o}ms drift exceeds ${e}ms limit`)}export function getTopLevelField(t){let e=t.indexOf("/",1);return -1===e?t:t.slice(0,e)}export async function applyChangeMutation(t,r){let l=o.fromString(r.sub),u=l.toString(),s=await t.store.getDocument(l);if(null==s)throw Error(`Document not found: ${u}`);if(r.iss!==s.owner&&!(null!=t.checkWriteAccess&&await t.checkWriteAccess(s,r)))throw new n(u);null!=t.maxDriftMS&&i(r.hlc,t.maxDriftMS);let c=l.model.toString(),p=await t.store.getFieldHLCs(u)??{};if(1===r.patch.length&&"replace"===r.patch[0].op&&"/"===r.patch[0].path&&null===r.patch[0].value){let e={...p,"/":r.hlc},a=Object.entries(e).every(([t,e])=>"/"===t||r.hlc>=e);if(a&&null!=t.postStateGate){let e={...s,data:null};if(!await t.postStateGate(e))return null}return(await t.store.updateFieldHLCs(l,e),a)?await t.store.saveDocument({id:l,existing:s,data:null}):s}if(null!=p["/"]&&null===s.data)return s;let f=await getDocumentValidator(t,c),d=new Map;for(let t of r.patch){let e=getTopLevelField(t.path),a=d.get(e);null!=a?a.push(t):d.set(e,[t])}let m={...p},h=[];for(let[t,e]of d){let a=p[t];(null==a||r.hlc>a)&&(h.push(...e),m[t]=r.hlc)}if(0===h.length)return s;let w=structuredClone(s.data??{});e(w,h,!1);let g=a(f,w);if(null!=t.postStateGate){let e={...s,data:g};if(!await t.postStateGate(e))return null}return await t.store.updateFieldHLCs(l,m),await t.store.saveDocument({id:l,existing:s,data:g})}export async function applySetMutation(e,r){let l=r.aud??r.iss,u=o.fromString(r.sub),s=u.toString(),c=u.model.toString();null!=e.maxDriftMS&&i(r.hlc,e.maxDriftMS);let[p,f]=await Promise.all([e.store.getDocument(u),getDocumentValidator(e,c)]),d=a(f,r.data),m={};for(let t of Object.keys(d))m[`/${t}`]=r.hlc;let h={id:s,model:c,owner:l,data:d,createdAt:new Date(0),updatedAt:null};if(r.iss!==l){let t=p??h;if(!(null!=e.checkWriteAccess&&await e.checkWriteAccess(t,r)))throw new n(s)}if(null===p){if(null!=e.postStateGate&&!await e.postStateGate(h))return null;let a=await e.store.createDocument({id:u,owner:l,data:d,unique:t(r.unq)});return await e.store.updateFieldHLCs(u,m),a}if(p.owner!==l)throw Error(`Cannot change owner from ${p.owner} to ${l} in document: ${u.toString()}`);let w=await e.store.getFieldHLCs(s)??{},g={...p.data??{}},S={...w},D=!1;for(let[t,e]of Object.entries(d)){let a=`/${t}`,l=w[a];(null==l||r.hlc>l)&&(g[t]=e,S[a]=r.hlc,D=!0)}if(!D)return p;let x=a(f,g);if(null!=e.postStateGate){let t={...p,data:x};if(!await e.postStateGate(t))return null}return await e.store.updateFieldHLCs(u,S),await e.store.saveDocument({id:u,existing:p,data:x})}export async function applyMutation(t,e){switch(e.typ){case"change":return await applyChangeMutation(t,e);case"set":return await applySetMutation(t,e);default:throw Error("Unsupported mutation type")}}

package/lib/create.d.ts

@@ -9,6 +9,7 @@ export type CreateSetMutationParams<Data extends DocumentData = DocumentData> =
     modelID: DocumentModelID | string;
     owner?: string;
     unique: Uint8Array;
+    cap?: string | Array<string>;
 };
 export declare function createSetMutation<Data extends DocumentData = DocumentData>(params: CreateSetMutationParams<Data>): Promise<SetDocumentMutation>;
 export type CreateChangeMutationParams = {
@@ -16,11 +17,13 @@ export type CreateChangeMutationParams = {
     hlc: HLC;
     issuer: string;
     patch: Array<PatchOperation>;
+    cap?: string | Array<string>;
 };
 export declare function createChangeMutation(params: CreateChangeMutationParams): ChangeDocumentMutation;
 export type CreateRemoveMutationParams = {
     docID: string;
     hlc: HLC;
     issuer: string;
+    cap?: string | Array<string>;
 };
 export declare function createRemoveMutation(params: CreateRemoveMutationParams): ChangeDocumentMutation;

package/lib/create.js

@@ -1 +1 @@
-import{toB64 as e}from"@enkaku/codec";import{HLC as t}from"@kubun/hlc";import{DocumentID as r}from"@kubun/id";export async function createSetMutation(n){let a=n.issuer,o=n.owner??a,u=await r.create(n.modelID,o,n.unique);return{typ:"set",iss:a,aud:o,sub:u.toString(),data:n.data,hlc:t.serialize(n.hlc.now()),unq:e(n.unique)}}export function createChangeMutation(e){return{typ:"change",iss:e.issuer,sub:r.from(e.docID).toString(),patch:e.patch,hlc:t.serialize(e.hlc.now())}}export function createRemoveMutation(e){return{typ:"change",iss:e.issuer,sub:e.docID,patch:[{op:"replace",path:"/",value:null}],hlc:t.serialize(e.hlc.now())}}
+import{toB64 as e}from"@enkaku/codec";import{HLC as t}from"@kubun/hlc";import{DocumentID as a}from"@kubun/id";export async function createSetMutation(c){let n=c.issuer,u=c.owner??n,r=await a.create(c.modelID,u,c.unique);return{typ:"set",iss:n,aud:u,sub:r.toString(),data:c.data,hlc:t.serialize(c.hlc.now()),unq:e(c.unique),...null!=c.cap?{cap:c.cap}:{}}}export function createChangeMutation(e){return{typ:"change",iss:e.issuer,sub:a.from(e.docID).toString(),patch:e.patch,hlc:t.serialize(e.hlc.now()),...null!=e.cap?{cap:e.cap}:{}}}export function createRemoveMutation(e){return{typ:"change",iss:e.issuer,sub:e.docID,patch:[{op:"replace",path:"/",value:null}],hlc:t.serialize(e.hlc.now()),...null!=e.cap?{cap:e.cap}:{}}}

package/lib/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Thrown by the mutation apply path when a non-owner writer's capability
+ * check fails. Tagged with the protocol-level error code `KB07` so callers
+ * — particularly the RPC handler — can translate the throw into a
+ * structured wire response without losing the reason.
+ */
+export declare class WriteAccessDeniedError extends Error {
+    readonly code: "KB07";
+    readonly docID: string;
+    constructor(docID: string);
+}

package/lib/errors.js

@@ -0,0 +1 @@
+export class WriteAccessDeniedError extends Error{code="KB07";docID;constructor(e){super(`Access denied: cannot write document ${e}`),this.name="WriteAccessDeniedError",this.docID=e}}

package/lib/index.d.ts

@@ -3,5 +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 { 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 +1 @@
-export{HLC}from"@kubun/hlc";export{applyChangeMutation,applyMutation,applySetMutation,getTopLevelField}from"./apply.js";export{createChangeMutation,createRemoveMutation,createSetMutation}from"./create.js";export{convertPatchInput,createMutationOperations}from"./operations.js";
+export{HLC}from"@kubun/hlc";export{applyChangeMutation,applyMutation,applySetMutation,getTopLevelField}from"./apply.js";export{createChangeMutation,createRemoveMutation,createSetMutation}from"./create.js";export{WriteAccessDeniedError}from"./errors.js";export{convertPatchInput,createMutationOperations}from"./operations.js";

package/lib/operations.d.ts

@@ -6,6 +6,7 @@ export type CreateMutationOperationsParams<T> = {
     issuer: string;
     hlc: HLC;
     getRandomValues: GetRandomValues;
+    cap?: string | Array<string>;
     processSetMutation(mutation: SetDocumentMutation, transactionID?: string | null): Promise<T>;
     processChangeMutation(mutation: ChangeDocumentMutation, transactionID?: string | null): Promise<T>;
 };

package/lib/operations.js

@@ -1 +1 @@
-import{createChangeMutation as t,createRemoveMutation as e,createSetMutation as r}from"./create.js";export function createMutationOperations(n){let{issuer:a,hlc:c,getRandomValues:u,processSetMutation:o,processChangeMutation:i}=n;return{async createDocument({modelID:t,data:e,transactionID:n}){let i=u(new Uint8Array(12)),m=await r({issuer:a,hlc:c,modelID:t,data:e,unique:i});return await o(m,n)},async setDocument({modelID:t,unique:e,data:n,transactionID:u}){let i=await r({issuer:a,hlc:c,modelID:t,data:n,unique:e});return await o(i,u)},async updateDocument({docID:e,patch:r,transactionID:n}){let u=t({issuer:a,hlc:c,docID:e,patch:r});return await i(u,n)},async removeDocument({docID:t,transactionID:r}){let n=e({docID:t,issuer:a,hlc:c});return await i(n,r)}}}export function convertPatchInput(t){return t.map(t=>{let[e,r]=Object.entries(t)[0];return{...r,op:e}})}
+import{createChangeMutation as t,createRemoveMutation as e,createSetMutation as r}from"./create.js";export function createMutationOperations(n){let{issuer:a,hlc:c,getRandomValues:u,cap:o,processSetMutation:i,processChangeMutation:m}=n;return{async createDocument({modelID:t,data:e,transactionID:n}){let m=u(new Uint8Array(12)),s=await r({issuer:a,hlc:c,modelID:t,data:e,unique:m,cap:o});return await i(s,n)},async setDocument({modelID:t,unique:e,data:n,transactionID:u}){let m=await r({issuer:a,hlc:c,modelID:t,data:n,unique:e,cap:o});return await i(m,u)},async updateDocument({docID:e,patch:r,transactionID:n}){let u=t({issuer:a,hlc:c,docID:e,patch:r,cap:o});return await m(u,n)},async removeDocument({docID:t,transactionID:r}){let n=e({docID:t,issuer:a,hlc:c,cap:o});return await m(n,r)}}}export function convertPatchInput(t){return t.map(t=>{let[e,r]=Object.entries(t)[0];return{...r,op:e}})}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/mutation",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "license": "see LICENSE.md",
   "keywords": [],
   "type": "module",
@@ -15,16 +15,16 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@enkaku/codec": "^0.15.0",
-    "@enkaku/patch": "^0.15.0",
-    "@enkaku/runtime": "^0.15.0",
-    "@enkaku/schema": "^0.15.0",
-    "@kubun/hlc": "^0.9.0",
-    "@kubun/id": "^0.9.0"
+    "@enkaku/codec": "^0.16.0",
+    "@enkaku/patch": "^0.16.0",
+    "@enkaku/runtime": "^0.16.0",
+    "@enkaku/schema": "^0.16.0",
+    "@kubun/hlc": "^0.10.1",
+    "@kubun/id": "^0.10.0"
   },
   "devDependencies": {
-    "@kubun/protocol": "^0.9.0",
-    "@kubun/graphql": "^0.9.0"
+    "@kubun/protocol": "^0.10.0",
+    "@kubun/graphql": "^0.10.1"
   },
   "scripts": {
     "build:clean": "del lib",