@kubun/service-controller-log-api 0.14.0

package/LICENSE.md

@@ -0,0 +1,57 @@
+# The Prosperity Public License 3.0.0
+
+Contributor: Paul Le Cam
+
+Source Code: https://github.com/PaulLeCam/kubun
+
+## Purpose
+
+This license allows you to use and share this software for noncommercial purposes for free and to try this software for commercial purposes for thirty days.
+
+## Agreement
+
+In order to receive this license, you have to agree to its rules.  Those rules are both obligations under that agreement and conditions to your license.  Don't do anything with this software that triggers a rule you can't or won't follow.
+
+## Notices
+
+Make sure everyone who gets a copy of any part of this software from you, with or without changes, also gets the text of this license and the contributor and source code lines above.
+
+## Commercial Trial
+
+Limit your use of this software for commercial purposes to a thirty-day trial period.  If you use this software for work, your company gets one trial period for all personnel, not one trial per person.
+
+## Contributions Back
+
+Developing feedback, changes, or additions that you contribute back to the contributor on the terms of a standardized public software license such as [the Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html), [the MIT license](https://spdx.org/licenses/MIT.html), or [the two-clause BSD license](https://spdx.org/licenses/BSD-2-Clause.html) doesn't count as use for a commercial purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, doesn't count as use for a commercial purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution doesn't count as use for a commercial purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Defense
+
+Don't make any legal claim against anyone accusing this software, with or without changes, alone or with other technology, of infringing any patent.
+
+## Copyright
+
+The contributor licenses you to do everything with this software that would otherwise infringe their copyright in it.
+
+## Patent
+
+The contributor licenses you to do everything with this software that would otherwise infringe any patents they can license or become able to license.
+
+## Reliability
+
+The contributor can't revoke this license.
+
+## Excuse
+
+You're excused for unknowingly breaking [Notices](#notices) if you take all practical steps to comply within thirty days of learning you broke the rule.
+
+## No Liability
+
+***As far as the law allows, this software comes as is, without any warranty or condition, and the contributor won't be liable to anyone for any damages related to this software or this license, under any kind of legal claim.***

package/lib/adapter.d.ts

@@ -0,0 +1,4 @@
+import type { Client } from '@enkaku/client';
+import type { ControllerLogSource } from '@kubun/engine';
+import type { ControllerLogServiceProtocol } from './index.js';
+export declare function toControllerLogSource(client: Client<ControllerLogServiceProtocol>): ControllerLogSource;

package/lib/adapter.js

@@ -0,0 +1,20 @@
+// Runtime adapter: turn an authenticated `Client<ControllerLogServiceProtocol>`
+// into a `controller-log-source` the consuming engine consults. Registered with
+// `transport: 'direct'`, it sits between the resolver's local cache (`none`) and
+// p2p's `networked` provider — so a controller log the serving engine holds
+// resolves over the direct link before any group-peer round trip.
+export function toControllerLogSource(client) {
+    return {
+        async fetch (did) {
+            const log = await client.request('controller/resolve', {
+                param: {
+                    did
+                }
+            });
+            // The wire result is a `SignedEvent[]` (typed as object-array for the
+            // schema) or null; a source with no answer yields undefined so the resolver
+            // falls through to the next provider.
+            return log == null ? undefined : log;
+        }
+    };
+}

package/lib/index.d.ts

@@ -0,0 +1,50 @@
+export { toControllerLogSource } from './adapter.js';
+export { createControllerLogService } from './service.js';
+export declare const controllerLogServiceProtocol: {
+    readonly 'controller/resolve': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly did: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["did"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly anyOf: [{
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                };
+            }, {
+                readonly type: "null";
+            }];
+        };
+    };
+    readonly 'controller/ingest': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly did: {
+                    readonly type: "string";
+                };
+                readonly log: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                    };
+                };
+            };
+            readonly required: readonly ["did", "log"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "null";
+        };
+    };
+};
+export type ControllerLogServiceProtocol = typeof controllerLogServiceProtocol;

package/lib/index.js

@@ -0,0 +1,73 @@
+// Cross-plugin contract for the controller-log service: the Enkaku protocol a
+// consuming engine drives over a transport and the controller-log plugin serves
+// as a `service` provider. Alongside the protocol schema it carries the runtime
+// `toControllerLogSource` adapter (see `./adapter.js`), which maps an
+// authenticated client into the `controller-log-source` provider a consuming
+// engine consults, plus the server factory (see `./service.js`).
+export { toControllerLogSource } from './adapter.js';
+export { createControllerLogService } from './service.js';
+// `did` is a request PARAM, not the Enkaku message `sub`: a caller resolving or
+// ingesting another controller's log is not acting as that controller, and the
+// host rejects a `sub` that differs from `iss`. Same convention as
+// `service-credential-api`'s `ownerDID`.
+//
+// `resolve` yields the raw key-event log (a `SignedEvent[]`) or null; the log has
+// no JSON-schema here, so an array-of-object result is enough for the wire and the
+// adapter casts. `ingest` acks with null; its `log` is folded through kokuin's
+// anti-truncation guard server-side, so a truncated or forked push is refused
+// there rather than trusted.
+export const controllerLogServiceProtocol = {
+    'controller/resolve': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                did: {
+                    type: 'string'
+                }
+            },
+            required: [
+                'did'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            anyOf: [
+                {
+                    type: 'array',
+                    items: {
+                        type: 'object'
+                    }
+                },
+                {
+                    type: 'null'
+                }
+            ]
+        }
+    },
+    'controller/ingest': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                did: {
+                    type: 'string'
+                },
+                log: {
+                    type: 'array',
+                    items: {
+                        type: 'object'
+                    }
+                }
+            },
+            required: [
+                'did',
+                'log'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            type: 'null'
+        }
+    }
+};

package/lib/service.d.ts

@@ -0,0 +1,15 @@
+import type { KubunPlugin, PluginFactoryParams } from '@kubun/engine';
+/**
+ * The controller-log service provider. It registers a `service` provider on the
+ * hosting engine exposing `controller/resolve` and `controller/ingest` over a
+ * transport, so a consuming engine resolves or pushes a `did:kokuin:` key-event
+ * log against the hosting engine's authoritative controller store.
+ *
+ * Neither handler subject-gates. A key-event log is public, verifiable material,
+ * not owner-private data: `resolve` must answer for any DID (resolving another
+ * user's controller is normal), and `ingest` is protected by kokuin's fold
+ * guard — not a subject authorizer — so any verified caller may push a log the
+ * guard then arbitrates. The transport access rules therefore grant both to every
+ * verified issuer, and no handler calls `context.authorize`.
+ */
+export declare function createControllerLogService(): (params: PluginFactoryParams) => KubunPlugin;

package/lib/service.js

@@ -0,0 +1,88 @@
+import { createControllerCapabilityVerifier } from '@kokuin/capability';
+import { createControllerResolver } from '@kokuin/controller';
+import { normalizeDID } from '@kokuin/token';
+import { getControllerStore } from '@kubun/store-controller';
+/**
+ * The controller-log service provider. It registers a `service` provider on the
+ * hosting engine exposing `controller/resolve` and `controller/ingest` over a
+ * transport, so a consuming engine resolves or pushes a `did:kokuin:` key-event
+ * log against the hosting engine's authoritative controller store.
+ *
+ * Neither handler subject-gates. A key-event log is public, verifiable material,
+ * not owner-private data: `resolve` must answer for any DID (resolving another
+ * user's controller is normal), and `ingest` is protected by kokuin's fold
+ * guard — not a subject authorizer — so any verified caller may push a log the
+ * guard then arbitrates. The transport access rules therefore grant both to every
+ * verified issuer, and no handler calls `context.authorize`.
+ */ export function createControllerLogService() {
+    return (params)=>{
+        // Per-DID single-flight: the ingest fold reads the stored head then writes,
+        // and the store's `set` is unconditional LWW. Two concurrent ingests of
+        // conflicting valid branches would both read the same head and both write —
+        // last-writer-wins accepts a fork with no `LOG_FORKED` and drops an accepted
+        // event. Chaining each DID's fold+write on the prior one makes the second read
+        // the first's committed head, so its conflicting branch folds as a fork.
+        const ingestChains = new Map();
+        const ingestSerialized = (did, run)=>{
+            const key = normalizeDID(did);
+            const tail = ingestChains.get(key);
+            // `.then(run, run)` so a rejected predecessor still lets the next run rather
+            // than wedging the whole chain.
+            const next = tail == null ? run() : tail.then(run, run);
+            ingestChains.set(key, next);
+            // Cleanup observes `next` on a separate branch that always resolves, so a
+            // losing branch's rejection is not re-propagated by an unawaited derived
+            // promise. The caller still awaits `next` and sees the rejection.
+            const cleanup = ()=>{
+                if (ingestChains.get(key) === next) ingestChains.delete(key);
+            };
+            next.then(cleanup, cleanup);
+            return next;
+        };
+        const handlers = {
+            'controller/resolve': async (context)=>{
+                const param = context.param;
+                const log = await (await getControllerStore(params.db)).get(param.did);
+                return log ?? null;
+            },
+            'controller/ingest': async (context)=>{
+                const param = context.param;
+                return ingestSerialized(param.did, async ()=>{
+                    const store = await getControllerStore(params.db);
+                    // Fold the untrusted incoming log through the same anti-truncation guard
+                    // the engine's controller resolver uses (`authoritativeStates` + a
+                    // write-through `history`), rather than a raw `store.set` that would bypass
+                    // it. A behind/truncated log loses to the stored head, a fork throws
+                    // `LOG_FORKED`, and a valid extension write-throughs — all owned by kokuin.
+                    const resolver = createControllerResolver({
+                        loadLog: async (did)=>did === param.did ? param.log : undefined,
+                        verifyCapability: createControllerCapabilityVerifier(),
+                        history: {
+                            get: (did)=>store.get(did),
+                            set: (did, log)=>store.set(did, log)
+                        }
+                    });
+                    // Resolving triggers the fold and its `history.set` write-through; the
+                    // resolved key is discarded — the store write is the effect we want.
+                    await resolver.resolve(param.did, {});
+                    return null;
+                });
+            }
+        };
+        params.registerProvider('service', {
+            name: 'controller-log',
+            handlers,
+            accessRules: {
+                'controller/resolve': {
+                    allow: true
+                },
+                'controller/ingest': {
+                    allow: true
+                }
+            }
+        });
+        return {
+            name: 'controller-log-service'
+        };
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@kubun/service-controller-log-api",
+  "version": "0.14.0",
+  "keywords": [],
+  "license": "see LICENSE.md",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*",
+    "LICENSE.md"
+  ],
+  "dependencies": {
+    "@enkaku/client": "^0.21.0",
+    "@enkaku/protocol": "^0.21.0",
+    "@kokuin/capability": "^0.3.0",
+    "@kokuin/controller": "^0.1.0",
+    "@kubun/engine": "^0.14.0",
+    "@kubun/plugin-service-api": "^0.14.0",
+    "@kubun/store-controller": "^0.14.0"
+  },
+  "devDependencies": {
+    "@enkaku/transport": "^0.21.0",
+    "@kokuin/token": "^0.5.0",
+    "@kubun/db": "^0.14.0",
+    "@kubun/db-better-sqlite": "^0.14.0",
+    "@kubun/plugin-service-server": "^0.14.0",
+    "@kubun/store-graph": "^0.14.0",
+    "@kubun/test-utils": "^0.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "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",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
+}