@kubun/engine 0.12.0 → 0.13.0

package/lib/access-control.d.ts

@@ -1,4 +1,5 @@
 import { type VerifyTokenHook } from '@kokuin/capability';
+import type { DIDMethodResolver } from '@kokuin/token';
 import type { DocumentNode } from '@kubun/protocol';
 import type { AccessLevel, StoredAccessRule } from '@kubun/store-graph';
 /**
@@ -25,6 +26,16 @@ export type AccessControlDB = {
      * without a P2P store (e.g. light clients) where no revocation state exists.
      */
     revocationChecker?: VerifyTokenHook;
+    /**
+     * Optional `did:kokuin:` method resolver passed to `checkCapability` as its
+     * `methods`. When a capability chain is issued/subjected by a controller DID,
+     * this resolves that DID to its current signing keys and deny set — so a
+     * capability signed by a device key the controller has revoked is refused,
+     * and a controller `iss`/`sub` resolves at all. Left undefined on deployments
+     * without controller support, where a `did:kokuin:` issuer is unresolvable
+     * and `checkCapability` fails closed.
+     */
+    controllerResolver?: DIDMethodResolver;
 };
 export type { AccessLevel };
 export type AccessRule = {

package/lib/access-control.js

@@ -151,7 +151,10 @@ atTime) {
                 cap: delegationTokens
             }, {
                 atTime,
-                verifyToken: db.revocationChecker
+                verifyToken: db.revocationChecker,
+                methods: db.controllerResolver ? [
+                    db.controllerResolver
+                ] : undefined
             });
             return true;
         } catch  {
@@ -171,7 +174,10 @@ atTime) {
                     cap: token
                 }, {
                     atTime,
-                    verifyToken: db.revocationChecker
+                    verifyToken: db.revocationChecker,
+                    methods: db.controllerResolver ? [
+                        db.controllerResolver
+                    ] : undefined
                 });
                 return true;
             } catch  {

package/lib/controller-authority.d.ts

@@ -0,0 +1,27 @@
+import { type VerifyTokenHook } from '@kokuin/capability';
+import { type DIDMethodResolver } from '@kokuin/token';
+import { type CredentialAuthority } from '@kubun/credential';
+export type ControllerAuthorityParams = {
+    /** The device making the request; the capability holder and the read/self-owner subject. */
+    viewerDID: string;
+    /**
+     * Intended owner for a NEW key. Under a real delegation this is the controller
+     * the device acts for, supplied by the caller because it is neither the client's
+     * input nor the signer but what the chain resolves to; defaults to a self-owned key.
+     */
+    ownerDID?: string;
+    delegationTokens?: Array<string>;
+    /** Injected so a `did:kokuin:` owner's capability and deny set resolve without a dependency cycle. */
+    controllerResolver?: DIDMethodResolver;
+    /** The delegation-revocation hook, consulted for every capability in the chain. */
+    revocationChecker?: VerifyTokenHook;
+    /** Evaluate capability expiry at this time (epoch seconds) rather than now(). */
+    atTime?: number;
+};
+/**
+ * A superset of {@link createDeviceAuthority}: same owner-equality and wrapping-recipient
+ * read, plus a capability chain that lets a delegate administer a controller-owned key on
+ * its owner's behalf. `administer` alone carries the chain — a recipient already holds a
+ * wrapping that decrypts, so `read` needs no delegation.
+ */
+export declare function createControllerAuthority(params: ControllerAuthorityParams): CredentialAuthority;

package/lib/controller-authority.js

@@ -0,0 +1,83 @@
+import { checkCapability } from '@kokuin/capability';
+import { normalizeDID } from '@kokuin/token';
+import { CREDENTIAL_ADMINISTER_ACTION, credentialUserResource } from '@kubun/credential';
+/**
+ * A superset of {@link createDeviceAuthority}: same owner-equality and wrapping-recipient
+ * read, plus a capability chain that lets a delegate administer a controller-owned key on
+ * its owner's behalf. `administer` alone carries the chain — a recipient already holds a
+ * wrapping that decrypts, so `read` needs no delegation.
+ */ export function createControllerAuthority(params) {
+    const viewerDID = normalizeDID(params.viewerDID);
+    const { delegationTokens, controllerResolver, revocationChecker, atTime } = params;
+    return {
+        async ownerForNewKey () {
+            return normalizeDID(params.ownerDID ?? params.viewerDID);
+        },
+        async authorize (authorization, { key, store }) {
+            const ownerDID = normalizeDID(key.owner_did);
+            if (ownerDID === viewerDID) {
+                return true;
+            }
+            if (authorization === 'administer') {
+                if (!delegationTokens || delegationTokens.length === 0) {
+                    return false;
+                }
+                // The user-wide resource covers all of an owner's credentials; `*` covers any.
+                const resources = [
+                    credentialUserResource(key.owner_did),
+                    '*'
+                ];
+                const methods = controllerResolver ? [
+                    controllerResolver
+                ] : undefined;
+                // First, try the tokens as one delegation chain (an A→B→C grant).
+                for (const res of resources){
+                    try {
+                        await checkCapability({
+                            act: CREDENTIAL_ADMINISTER_ACTION,
+                            res
+                        }, {
+                            iss: viewerDID,
+                            sub: ownerDID,
+                            cap: delegationTokens
+                        }, {
+                            atTime,
+                            verifyToken: revocationChecker,
+                            methods
+                        });
+                        return true;
+                    } catch  {
+                    // This resource does not match the chain — continue.
+                    }
+                }
+                // Then each token independently (several unrelated direct grants).
+                for (const token of delegationTokens){
+                    for (const res of resources){
+                        try {
+                            await checkCapability({
+                                act: CREDENTIAL_ADMINISTER_ACTION,
+                                res
+                            }, {
+                                iss: viewerDID,
+                                sub: ownerDID,
+                                cap: token
+                            }, {
+                                atTime,
+                                verifyToken: revocationChecker,
+                                methods
+                            });
+                            return true;
+                        } catch  {
+                        // This token does not match this resource — continue.
+                        }
+                    }
+                }
+                return false;
+            }
+            // Current version only: a recipient left behind by a rotation or revocation
+            // must read as "not a recipient", not as history.
+            const wrappings = await store.listWrappings(key.key_id, key.version);
+            return wrappings.some((wrapping)=>wrapping.recipient_did != null && normalizeDID(wrapping.recipient_did) === viewerDID);
+        }
+    };
+}

package/lib/engine-events.d.ts

@@ -75,4 +75,21 @@ export type EngineEvents = {
         /** LWW anchor stamped by this peer. */
         hlc: string;
     };
+    /**
+     * Emitted when a controller DID's log is seen to fork: a peer served a
+     * branch that neither supersedes nor is superseded by the one already
+     * stored. The stored authoritative branch is kept; the verification that
+     * hit the fork fails closed. A signal for the app to surface a possible
+     * key-compromise/duplicity, not a recoverable error.
+     *
+     * Unlike the document/mutation events, this one fires from inside the verify
+     * path — while a peer-ingest apply transaction may still be open (and about to
+     * roll back). A listener MUST NOT synchronously read the engine DB in response:
+     * on single-connection SQLite that can deadlock against the open write
+     * transaction. Do notification-only work here (surface a warning, enqueue an
+     * out-of-band task); defer any DB access to a later tick.
+     */
+    'engine:controller:forked': {
+        did: string;
+    };
 };

package/lib/engine.d.ts

@@ -1,5 +1,6 @@
-import type { VerifyTokenHook } from '@kokuin/capability';
-import type { Identity } from '@kokuin/token';
+import { type VerifyTokenHook } from '@kokuin/capability';
+import type { DIDMethodResolver, Identity } from '@kokuin/token';
+import type { CredentialAuthority } from '@kubun/credential';
 import { KubunDB, type StoreProvider } from '@kubun/db';
 import type { Adapter } from '@kubun/db-adapter';
 import { type PatchOperation } from '@kubun/graphql';
@@ -11,7 +12,6 @@ import { type P2PStoreAPI } from '@kubun/store-p2p';
 import { type Runtime } from '@sozai/runtime';
 import type { GraphQLSchema } from 'graphql';
 import { type DefaultAccessLevel } from './access-control.js';
-import { type Cipher } from './cipher.js';
 import type { EngineEvents } from './engine-events.js';
 import { EngineEventBus } from './events.js';
 import type { Engine, EngineGraphParams, GraphQLSource, GraphQLSourceParams } from './executor.js';
@@ -32,6 +32,7 @@ export declare function buildWriteAccessChecker(params: {
     defaultAccessLevel: DefaultAccessLevel;
     extraTokensByIssuer?: Map<string, Array<string>>;
     revocationChecker?: VerifyTokenHook;
+    controllerResolver?: DIDMethodResolver;
 }): (doc: DocumentNode, mutation: DocumentMutation) => Promise<boolean>;
 export type { Engine };
 /**
@@ -41,6 +42,14 @@ export type { Engine };
  */
 export type ExecutionContext = {
     viewerDID: string;
+    /** Delegation tokens the request carried, so a plugin can act under the same chain. */
+    delegationTokens?: Array<string>;
+    /**
+     * Credential read/administer authority for this request, assembled by the engine
+     * from the viewer and the request's delegation tokens. Required: every request
+     * gets one (self-owned when no tokens are present), so plugins never fabricate it.
+     */
+    credentialAuthority: CredentialAuthority;
 };
 /**
  * A function that produces per-request context fields.
@@ -77,13 +86,12 @@ export type EngineParams = {
      */
     maxSubscriptionQueueSize?: number;
     /**
-     * Explicit at-rest cipher override. When omitted the engine derives one from
-     * an `OwnIdentity` (full identity carrying a `privateKey`), and leaves it
-     * undefined for read-only identities. The app/CLI wiring layer is responsible
-     * for building an env-key-based cipher (e.g. from `KUBUN_AT_REST_KEY`) and
-     * passing it here — the engine itself never reads `process.env`.
+     * How long (in milliseconds) a cached `did:kokuin:` controller log is trusted
+     * before a re-pull from a group peer is attempted. Bounds how stale a
+     * controller's device-key revocation may be locally. Defaults to
+     * {@link DEFAULT_CONTROLLER_LOG_TTL_MS} (5 minutes).
      */
-    cipher?: Cipher;
+    controllerLogTTLMs?: number;
 };
 /**
  * Optional pre-persist gate. Receives the synthesized post-apply
@@ -218,6 +226,12 @@ export type ExecuteParams = {
     contextExtensions?: Record<string, unknown>;
     /** Override the store provider for this execution (e.g. transactional provider). */
     stores?: StoreProvider;
+    /**
+     * Delegation tokens the request carries, surfaced on the ExecutionContext so a
+     * plugin's per-request credential authority can authorize a delegated chain.
+     * Independent of the mutation `cap` auto-attach, which happens upstream.
+     */
+    delegationTokens?: Array<string>;
 };
 export declare class KubunEngine implements Engine {
     #private;

package/lib/engine.js

@@ -1,11 +1,15 @@
-import { isOwnIdentity, isSigningIdentity, stringifyToken, verifyToken } from '@kokuin/token';
+import { createControllerCapabilityVerifier } from '@kokuin/capability';
+import { createControllerResolver, LOG_FORKED } from '@kokuin/controller';
+import { isSigningIdentity, stringifyToken, verifyToken } from '@kokuin/token';
 import { KubunDB } from '@kubun/db';
 import { createReadContext, createSchema } from '@kubun/graphql';
 import { HLC } from '@kubun/hlc';
 import { DocumentID } from '@kubun/id';
+import { controllerNodeID } from '@kubun/identity';
 import { getKubunLogger } from '@kubun/logger';
-import { applyMutation, convertPatchInput, createMutationOperations, WriteAccessDeniedError } from '@kubun/mutation';
+import { applyMutation, convertPatchInput, createMutationOperations, DEFAULT_MAX_DRIFT_MS, WriteAccessDeniedError } from '@kubun/mutation';
 import { clusterToRecord, documentMutation, GraphModel } from '@kubun/protocol';
+import { controllerStoreDefinition, getControllerStore } from '@kubun/store-controller';
 import { createDelegationRevocationChecker, delegationStoreDefinition, getDelegationStore } from '@kubun/store-delegation';
 import { GRAPH_STORE, getGraphStore, graphStoreDefinition } from '@kubun/store-graph';
 import { getP2PStore, P2P_STORE } from '@kubun/store-p2p';
@@ -13,7 +17,7 @@ import { createRuntime } from '@sozai/runtime';
 import { asType, createValidator } from '@sozai/schema';
 import { execute, GraphQLError, Kind, parse, subscribe, validate } from 'graphql';
 import { createAccessChecker } from './access-control.js';
-import { createDefaultCipher, deriveAtRestKey } from './cipher.js';
+import { createControllerAuthority } from './controller-authority.js';
 import { isTransactionFatal, MutateGraphWriteRollback } from './errors.js';
 import { EngineEventBus } from './events.js';
 import { checkMembership } from './membership-check.js';
@@ -49,7 +53,7 @@ const validateMutation = createValidator(documentMutation);
  * hand-built map and exercise the union math directly. The Engine method
  * `#buildWriteAccessChecker` delegates to this helper.
  */ export function buildWriteAccessChecker(params) {
-    const { store, defaultAccessLevel, extraTokensByIssuer, revocationChecker } = params;
+    const { store, defaultAccessLevel, extraTokensByIssuer, revocationChecker, controllerResolver } = params;
     // Per-closure cache: a single write-apply transaction enters this helper
     // once and may resolve the same model's interface list multiple times
     // (e.g. during delegation resource enumeration). Memoizing per call keeps
@@ -67,7 +71,8 @@ const validateMutation = createValidator(documentMutation);
             interfaceCache.set(modelID, fetched);
             return fetched;
         },
-        revocationChecker
+        revocationChecker,
+        controllerResolver
     };
     return (doc, mutation)=>{
         const inline = normalizeCap(mutation.cap) ?? [];
@@ -179,6 +184,45 @@ function createContext(params) {
     }
     return coreContext;
 }
+// The honest-case revocation-visibility window: how long a cached controller log
+// is trusted before a re-pull is attempted. A controller `rev` (device-key
+// denial) issued elsewhere becomes locally enforceable at most one TTL late.
+const DEFAULT_CONTROLLER_LOG_TTL_MS = 300_000;
+// Cap the per-DID controller soft-state maps so a long-lived peer (a hub, an
+// always-on relay) syncing documents from many controller owners cannot grow
+// them without bound. Eviction is least-recently-touched; an evicted freshness
+// entry just triggers one extra re-pull, and an evicted fork mark may re-emit —
+// both cheap and self-correcting.
+const MAX_CONTROLLER_DIDS_TRACKED = 4096;
+// Decorate a controller resolver so any resolve method that throws `LOG_FORKED`
+// (a peer served a branch that neither supersedes nor is superseded by the one
+// already seen) fires `onFork(did)` before re-throwing. The throw originates in
+// the resolver's own `authoritativeStates`, before `verifyToken` wraps it, so
+// catching it here is independent of every verify call site. A fork is
+// unverifiable — the error is re-thrown unchanged (fail-closed); only a
+// notification is added. `LOG_NOT_AUTHORITATIVE` (a behind prefix) is not a fork
+// and passes through untouched.
+function withForkDetection(base, onFork) {
+    function wrap(method) {
+        return async (did, ...args)=>{
+            try {
+                return await method(did, ...args);
+            } catch (err) {
+                if (err instanceof Error && err.message.includes(LOG_FORKED)) {
+                    await onFork(did);
+                }
+                throw err;
+            }
+        };
+    }
+    return {
+        method: base.method,
+        resolve: wrap(base.resolve.bind(base)),
+        resolveHistoric: base.resolveHistoric != null ? wrap(base.resolveHistoric.bind(base)) : undefined,
+        resolveAgreementKey: base.resolveAgreementKey != null ? wrap(base.resolveAgreementKey.bind(base)) : undefined,
+        resolveDenySet: base.resolveDenySet != null ? wrap(base.resolveDenySet.bind(base)) : undefined
+    };
+}
 export class KubunEngine {
     /**
    * Plugin-scoped context factories. Each factory's return value is placed
@@ -190,7 +234,13 @@ export class KubunEngine {
    * onto ctx. Escape hatch for test fixtures — not subject to the duplicate
    * plugin namespace check.
    */ #imperativeFactories = [];
-    #cipher;
+    #controllerResolver;
+    // did → ms of its last successful controller-log pull. Engine-local soft state,
+    // not a store column: a pull-failure fallback still writes the cached log to the
+    // store (bumping its `updated_at`), which would mask staleness. A restart clears
+    // this, re-pulling once per DID — accepted.
+    #controllerLogFreshAt = new Map();
+    #controllerLogTTLMs;
     #db;
     #defaultAccessLevel;
     #eventBus;
@@ -221,16 +271,27 @@ export class KubunEngine {
         });
         this.#db.register(graphStoreDefinition);
         this.#db.register(delegationStoreDefinition);
+        this.#db.register(controllerStoreDefinition);
+        // Resolves a `did:kokuin:` issuer to its head signing key from the
+        // controller store, over the main connection. Used only by the two
+        // pre-transaction `verifyToken` sites, which run before any write tx opens,
+        // so the lazy store read cannot deadlock. The in-apply capability path uses
+        // `#controllerResolverFor(provider)` instead — see that helper.
+        this.#controllerResolver = this.#controllerResolverFor(this.#db);
         this.#identity = params.identity;
-        this.#cipher = params.cipher ?? (isOwnIdentity(params.identity) ? createDefaultCipher(deriveAtRestKey(params.identity.privateKey)) : undefined);
         this.#defaultAccessLevel = params.defaultAccessLevel ?? {
             read: 'anyone',
             write: 'only_owner'
         };
+        // A controller DID is one string across every device, so the HLC node must
+        // key off the per-device signing key or concurrent devices collapse to one
+        // node. Read-only identities carry no `publicKey`; they keep their id.
+        const nodeID = isSigningIdentity(params.identity) ? controllerNodeID(params.identity) : params.identity.id;
         this.#hlc = new HLC({
-            nodeID: params.identity.id
+            nodeID
         });
-        this.#maxDriftMS = params.maxDriftMS ?? 3_600_000;
+        this.#maxDriftMS = params.maxDriftMS ?? DEFAULT_MAX_DRIFT_MS;
+        this.#controllerLogTTLMs = params.controllerLogTTLMs ?? DEFAULT_CONTROLLER_LOG_TTL_MS;
         this.#maxSubscriptionQueueSize = params.maxSubscriptionQueueSize;
         this.#logger = params.logger ?? getKubunLogger('engine');
         this.#eventBus = params.eventBus ?? new EngineEventBus({
@@ -255,8 +316,9 @@ export class KubunEngine {
             identity: this.#identity,
             eventBus: this.#eventBus,
             hlc: this.#hlc,
+            maxDriftMS: this.#maxDriftMS,
             getLogger: (name)=>this.#logger.getChild(name),
-            cipher: this.#cipher
+            controllerResolverFor: (stores)=>this.#controllerResolverFor(stores)
         };
         // Call all plugin factories
         for (const factory of pluginFactories){
@@ -418,13 +480,24 @@ export class KubunEngine {
                 // floored wall-time at the bound so local writes always pass; a remote
                 // HLC beyond the bound is already rejected at ingest, so the floor is the
                 // only source that needs clamping.
-                const parsed = HLC.parse(max);
-                const ceiling = Date.now() + this.#maxDriftMS;
-                const flooredWallTime = Math.min(parsed.wallTime, ceiling);
-                this.#hlc.receive({
-                    ...parsed,
-                    wallTime: flooredWallTime
-                });
+                //
+                // Parsed defensively: the log stores a peer's stamp verbatim even when
+                // ingest refused to advance the clock to it, and a malformed one sorts
+                // above every ISO-8601 stamp — so the maximum is exactly where such a row
+                // shows up, on every start, for as long as it is stored.
+                const parsed = HLC.tryParse(max);
+                if (parsed == null) {
+                    this.#logger.warn('stored mutation maximum is an unparseable HLC; clock not floored', {
+                        maxHLC: max
+                    });
+                } else {
+                    const ceiling = Date.now() + this.#maxDriftMS;
+                    const flooredWallTime = Math.min(parsed.wallTime, ceiling);
+                    this.#hlc.receive({
+                        ...parsed,
+                        wallTime: flooredWallTime
+                    });
+                }
             }
         })();
         return await this.#hlcFloorPromise;
@@ -434,8 +507,34 @@ export class KubunEngine {
    * with all registered plugin context factories and any inline extensions.
    */ async #buildRequestContext(params) {
         const viewerDID = params.viewerDID ?? this.#identity.id;
-        const executionContext = this.#createExecutionContext(viewerDID);
         const provider = params.stores ?? this.#db;
+        // Delegation storage is core-registered and always present, so the
+        // delegated-token revocation check is unconditional: a light client with no
+        // p2p store still holds delegation/revocation rows and must honor them when
+        // validating a delegated chain (read ACL below and credential admin here).
+        const delegationStore = await getDelegationStore(provider);
+        // Provider-scoped controller resolver so a controller-issued (`did:kokuin:`)
+        // revocation record verifies. During a mutation `provider` is the open write
+        // tx; building the resolver on it is deadlock-safe because it only executes
+        // (folds the controller log) when a delegated check actually runs, and that
+        // fold does not re-enter this transaction.
+        const controllerResolver = this.#controllerResolverFor(provider);
+        const revocationChecker = createDelegationRevocationChecker(delegationStore, [
+            controllerResolver
+        ]);
+        // Per-request credential authority: assembled from the request's viewer and
+        // delegation tokens (async because of the delegation-store read above), so a
+        // plugin authorizes credential read/administer without capturing request state
+        // in its provider-cached manager. `atTime` is omitted — credential admin is
+        // evaluated at request time (checkCapability's default), unlike a document
+        // mutation whose cap is honored at its HLC signing time.
+        const credentialAuthority = createControllerAuthority({
+            viewerDID,
+            delegationTokens: params.delegationTokens,
+            controllerResolver,
+            revocationChecker
+        });
+        const executionContext = this.#createExecutionContext(viewerDID, params.delegationTokens, credentialAuthority);
         // Plugin-scoped factories: output goes under ctx[pluginName]
         let extensions = {};
         for (const { name, factory } of this.#pluginContextFactories){
@@ -470,12 +569,6 @@ export class KubunEngine {
         } catch  {
             p2pStore = undefined;
         }
-        // Delegation storage is core-registered and always present, so the read
-        // path's delegated-token revocation check is unconditional: a light client
-        // with no p2p store still holds delegation/revocation rows and must honor
-        // them when validating a delegated read chain.
-        const delegationStore = await getDelegationStore(provider);
-        const revocationChecker = createDelegationRevocationChecker(delegationStore);
         let accessControlDB;
         let viewerReadAccess;
         if (p2pStore != null) {
@@ -485,7 +578,8 @@ export class KubunEngine {
                 isMemberOfAnyGroup: (did, groupIDs)=>memberStore.isMemberOfAnyGroup(did, groupIDs),
                 isMemberOfAnyCircle: (did, circleIDs)=>memberStore.isMemberOfAnyCircle(did, circleIDs),
                 getModelInterfaces: (modelID)=>store.getModelInterfaces(modelID),
-                revocationChecker
+                revocationChecker,
+                controllerResolver
             };
             const [groups, circles] = await Promise.all([
                 memberStore.getGroupsForMember(viewerDID),
@@ -506,7 +600,8 @@ export class KubunEngine {
                 isMemberOfAnyGroup: async ()=>false,
                 isMemberOfAnyCircle: async ()=>false,
                 getModelInterfaces: (modelID)=>store.getModelInterfaces(modelID),
-                revocationChecker
+                revocationChecker,
+                controllerResolver
             };
             viewerReadAccess = {
                 viewerDID,
@@ -531,10 +626,14 @@ export class KubunEngine {
         });
     }
     /**
-   * Create an ExecutionContext for a single request.
-   */ #createExecutionContext(viewerDID) {
+   * Create an ExecutionContext for a single request. The credential authority is
+   * built by the caller (`#buildRequestContext`) because assembling it needs an
+   * async delegation-store read against the request's provider.
+   */ #createExecutionContext(viewerDID, delegationTokens, credentialAuthority) {
         return {
-            viewerDID
+            viewerDID,
+            delegationTokens,
+            credentialAuthority
         };
     }
     async #getGraphModel(id) {
@@ -894,15 +993,114 @@ export class KubunEngine {
    * checker unions them with the mutation's inline `cap` so server-side
    * application can authorize a write whose held credentials live in the
    * receiving peer's p2p store rather than on the wire.
-   */ #buildWriteAccessChecker(store, extraTokensByIssuer, revocationChecker) {
+   */ #buildWriteAccessChecker(store, extraTokensByIssuer, revocationChecker, controllerResolver) {
         return buildWriteAccessChecker({
             store,
             defaultAccessLevel: this.#defaultAccessLevel,
             extraTokensByIssuer,
-            revocationChecker
+            revocationChecker,
+            controllerResolver
+        });
+    }
+    /**
+   * Pull a `did:kokuin:` controller's log from a connected group peer, when our
+   * store lacks it. Reaches plugin-p2p by string at call time (no static dep —
+   * plugin-p2p imports engine). A peer with no p2p plugin (read-only clients,
+   * most unit tests) has no fetcher: getAPI throws `API not registered`, which
+   * we treat as "no fetcher available" and return undefined.
+   */ async #fetchControllerLog(did) {
+        let p2p;
+        try {
+            p2p = await this.getAPI('p2p');
+        } catch  {
+            return undefined;
+        }
+        return p2p.fetchControllerLog?.(did);
+    }
+    #isControllerLogFresh(did) {
+        const at = this.#controllerLogFreshAt.get(did);
+        return at != null && Date.now() - at < this.#controllerLogTTLMs;
+    }
+    // Record a successful pull's freshness, bounding the map (least-recently-
+    // refreshed evicted first — delete-then-set moves an existing DID to the end).
+    #markControllerLogFresh(did) {
+        this.#controllerLogFreshAt.delete(did);
+        this.#controllerLogFreshAt.set(did, Date.now());
+        if (this.#controllerLogFreshAt.size > MAX_CONTROLLER_DIDS_TRACKED) {
+            const oldest = this.#controllerLogFreshAt.keys().next().value;
+            if (oldest !== undefined) this.#controllerLogFreshAt.delete(oldest);
+        }
+    }
+    // A controller fork is a persistent condition, so emit once per DID — repeated
+    // resolves against the same fork must not spam listeners. Bounded; an evicted
+    // mark may re-emit, acceptable at this scale.
+    #controllerForkEmitted = new Set();
+    async #emitControllerFork(did) {
+        if (this.#controllerForkEmitted.has(did)) return;
+        this.#controllerForkEmitted.add(did);
+        if (this.#controllerForkEmitted.size > MAX_CONTROLLER_DIDS_TRACKED) {
+            const oldest = this.#controllerForkEmitted.keys().next().value;
+            if (oldest !== undefined) this.#controllerForkEmitted.delete(oldest);
+        }
+        // Immediate emit, not emitBuffered: on the peer-ingest path the verify that
+        // hit the fork runs inside an apply transaction that then rolls back, which
+        // would discard a buffered event — but the fork must surface regardless of
+        // whether the mutation applied. Because it fires while that transaction may
+        // still be open, a listener for `engine:controller:forked` MUST NOT
+        // synchronously read the engine DB (single-connection deadlock risk) — see
+        // the event's declaration in engine-events.ts. `await` so it isn't a floating
+        // promise.
+        await this.#eventBus.emit('engine:controller:forked', {
+            did
         });
     }
     /**
+   * A `did:kokuin:` controller resolver scoped to a specific store provider.
+   *
+   * The capability path (`checkCapability` inside `checkDelegation`) runs inside
+   * the apply write transaction, so its controller-store reads MUST route
+   * through that same transaction provider: reading `this.#db` on a second
+   * connection while the write tx is open deadlocks single-connection SQLite
+   * (and reads a stale snapshot on Postgres). The read path passes its query
+   * `provider` for the same consistency, deadlock-free since it holds no write tx.
+   *
+   * `verifyCapability` IS installed below: a capability-authored revoke otherwise
+   * fails the fold and the DID is unresolvable. It does not re-enter this resolver
+   * for the DID being folded — kokuin folds the verifier's own resolutions against
+   * `subjectAtPosition` (states strictly before the event under verification), so
+   * the DID mid-fold is never re-resolved through here.
+   */ #controllerResolverFor(provider) {
+        return withForkDetection(createControllerResolver({
+            // A revoke authored by a capability-holding device (not the profile's own
+            // key) only folds when the verifier is present; without it the whole log
+            // fails closed and the DID is unresolvable. Zero-arg: no `verifyToken`/`methods`
+            // hook, so nothing re-enters this single-flight resolver for the folded DID.
+            verifyCapability: createControllerCapabilityVerifier(),
+            // A cached controller log is trusted for a bounded TTL; on a miss OR past
+            // the TTL we attempt one re-pull before authorizing, and on pull failure
+            // fall back to the cached log. The resolver's own authoritativeStates keeps
+            // the fold no lower than `history`, so a behind/failed pull can never move
+            // the store back — TTL only decides whether to attempt the re-pull.
+            loadLog: async (did)=>{
+                const cached = await getControllerStore(provider).then((s)=>s.get(did));
+                if (cached != null && this.#isControllerLogFresh(did)) return cached;
+                const pulled = await this.#fetchControllerLog(did);
+                // Freshness is marked on any non-null pull, before the resolver folds it
+                // against `cached`. A pull that then loses to the cache (a behind branch)
+                // still resets the clock — safe (the store never moves back), and it is
+                // what lets the next in-TTL verify recover from the intact cached head.
+                // The user-visible cost: a lagging or hostile group peer can force at
+                // most one fail-closed verification per DID per TTL, which self-heals.
+                if (pulled != null) this.#markControllerLogFresh(did);
+                return pulled ?? cached;
+            },
+            history: {
+                get: (did)=>getControllerStore(provider).then((s)=>s.get(did)),
+                set: (did, log)=>getControllerStore(provider).then((s)=>s.set(did, log))
+            }
+        }), (did)=>this.#emitControllerFork(did));
+    }
+    /**
    * Verify a signed mutation JWT, apply it to the database, and capture it
    * in the mutation log.
    *
@@ -921,9 +1119,19 @@ export class KubunEngine {
         // single-connection SQLite). Harmless before an ingest receive() (receive
         // is monotonic); load-bearing for any local mint that reaches here.
         await this.#ensureHLCFloored(provider);
-        // Verify the JWT signature and validate the payload before opening the
-        // transaction, mirroring the batch path which verifies upfront.
-        const verified = await verifyToken(params.token);
+        // Verify the JWT signature and validate the payload up front. `methods`
+        // resolves a `did:kokuin:` issuer from the controller store. With a
+        // caller-supplied provider (an already-open write tx — e.g. mutateGraph's
+        // signAndApply) the store read MUST route through that provider: reading
+        // the main connection while the caller's tx holds it deadlocks
+        // single-connection SQLite. The no-provider path verifies before opening
+        // its own transaction below, so the main-connection resolver is safe there.
+        const controllerResolver = provider != null ? this.#controllerResolverFor(provider) : this.#controllerResolver;
+        const verified = await verifyToken(params.token, {
+            methods: [
+                controllerResolver
+            ]
+        });
         const mutation = asType(validateMutation, verified.payload);
         // With a caller-supplied provider the caller owns both the transaction and
         // the emit — apply directly and hand back the result.
@@ -977,7 +1185,12 @@ export class KubunEngine {
         if (held.length > 0) {
             extraTokensByIssuer.set(mutation.iss, held.map((row)=>row.token));
         }
-        const revocationChecker = createDelegationRevocationChecker(delegationStore);
+        // Provider-scoped so a controller-issued revocation record resolves; the
+        // capability check runs inside this apply's write tx, so route through
+        // `provider` (not `this.#db`) to stay deadlock-safe.
+        const revocationChecker = createDelegationRevocationChecker(delegationStore, [
+            this.#controllerResolverFor(provider)
+        ]);
         // The MLS/membership gate is the only piece that needs the p2p store. Gate
         // on store registration, not on whether the lookup throws. An unregistered
         // p2p store is a light client with no membership to enforce, so the gate is
@@ -993,7 +1206,9 @@ export class KubunEngine {
             validators: this.#validators,
             hlc: this.#hlc,
             maxDriftMS: this.#maxDriftMS,
-            checkWriteAccess: this.#buildWriteAccessChecker(store, extraTokensByIssuer, revocationChecker),
+            checkWriteAccess: this.#buildWriteAccessChecker(store, extraTokensByIssuer, revocationChecker, // Provider-scoped: the capability check runs inside this apply's write
+            // transaction, so controller-store reads must route through `provider`.
+            this.#controllerResolverFor(provider)),
             // Build the gate from this apply's transaction-scoped stores so its
             // reads run inside the transaction. When no factory is supplied (or it
             // returns undefined), apply.ts takes its existing no-gate branch.
@@ -1052,8 +1267,19 @@ export class KubunEngine {
         // passes drift but loses LWW still advances — it is a real observation. The
         // anchor lets a local write issued right after ingesting an ahead-of-clock
         // remote mutation win last-writer-wins instead of being silently lost.
+        // Guarded: the drift bound cannot reject a malformed stamp (its NaN loses
+        // every comparison), so this is where one would enter the device clock.
         if (origin !== 'local') {
-            this.#hlc.receive(HLC.parse(mutation.hlc));
+            const observed = HLC.tryParse(mutation.hlc);
+            if (observed == null) {
+                this.#logger.warn('mutation carries an unparseable HLC; clock not advanced', {
+                    iss: mutation.iss,
+                    docID: mutation.sub,
+                    mutationHLC: mutation.hlc
+                });
+            } else {
+                this.#hlc.receive(observed);
+            }
         }
         const hash = computeMutationHash(token);
         const authorDID = mutation.iss;
@@ -1105,7 +1331,14 @@ export class KubunEngine {
         await this.#ensureHLCFloored();
         // Verify all tokens upfront — fail fast before starting transaction
         const verified = await Promise.all(tokens.map(async (token)=>{
-            const v = await verifyToken(token);
+            // `methods` resolves a `did:kokuin:` issuer from the controller store.
+            // This runs before the write transaction below opens, so the resolver
+            // reading that store off the main connection cannot deadlock.
+            const v = await verifyToken(token, {
+                methods: [
+                    this.#controllerResolver
+                ]
+            });
             const mutation = asType(validateMutation, v.payload);
             return {
                 token,
@@ -1170,7 +1403,12 @@ export class KubunEngine {
             // the transaction provider `tx` so the lookups run inside this batch's
             // transaction.
             const delegationStore = await getDelegationStore(tx);
-            const revocationChecker = createDelegationRevocationChecker(delegationStore);
+            // Provider-scoped so a controller-issued revocation record resolves; the
+            // batch apply's write transaction is `tx`, so route controller-store reads
+            // through it to stay deadlock-safe.
+            const revocationChecker = createDelegationRevocationChecker(delegationStore, [
+                this.#controllerResolverFor(tx)
+            ]);
             for (const iss of new Set(verified.map((v)=>v.mutation.iss))){
                 const minSigningTime = issuerAtTimes.get(iss);
                 const includeFallback = issuerHasMissingHLC.has(iss) || minSigningTime == null;
@@ -1194,7 +1432,9 @@ export class KubunEngine {
             if (tx.hasStore(P2P_STORE)) {
                 p2pStore = await getP2PStore(tx);
             }
-            const checkWriteAccess = this.#buildWriteAccessChecker(txStore, extraTokensByIssuer, revocationChecker);
+            const checkWriteAccess = this.#buildWriteAccessChecker(txStore, extraTokensByIssuer, revocationChecker, // Provider-scoped: the batch apply's write transaction is `tx`, so the
+            // capability check's controller-store reads must route through it.
+            this.#controllerResolverFor(tx));
             // Build the gate once from the transaction-scoped stores so its reads run
             // inside this transaction; reused for every entry's independent decision.
             const postStateGate = accessGate?.({
@@ -1245,9 +1485,19 @@ export class KubunEngine {
                 // Mirror the single-apply path: skip 'local' (its HLC was just minted
                 // by this.#hlc.now()), advance for 'peer'. Placed after
                 // applyMutation so a future-over-drift mutation never advances the
-                // clock; a drift-ok mutation that loses LWW still advances.
+                // clock; a drift-ok mutation that loses LWW still advances. A malformed
+                // stamp is dropped here, not by the drift bound, which its NaN passes.
                 if (origin !== 'local') {
-                    this.#hlc.receive(HLC.parse(mutation.hlc));
+                    const observed = HLC.tryParse(mutation.hlc);
+                    if (observed == null) {
+                        this.#logger.warn('mutation carries an unparseable HLC; clock not advanced', {
+                            iss: mutation.iss,
+                            docID: mutation.sub,
+                            mutationHLC: mutation.hlc
+                        });
+                    } else {
+                        this.#hlc.receive(observed);
+                    }
                 }
                 const hash = computeMutationHash(token);
                 if (document == null) {
@@ -1319,7 +1569,11 @@ export class KubunEngine {
             graphID: params.id,
             text: params.text,
             variables: params.variables ?? {},
-            viewerDID: params.viewerDID
+            viewerDID: params.viewerDID,
+            // Carried onto the request's credential authority (a delegate reading a
+            // credential presents its chain), not onto any mutation cap — a query
+            // produces none.
+            delegationTokens: params.delegationTokens
         });
     }
     /**
@@ -1728,6 +1982,7 @@ export class KubunEngine {
             text: params.text,
             variables: params.variables ?? {},
             viewerDID: params.viewerDID ?? signingIdentity.id,
+            delegationTokens: params.delegationTokens,
             contextExtensions
         });
     }
@@ -1772,6 +2027,7 @@ export class KubunEngine {
                     text: params.text,
                     variables: params.variables ?? {},
                     viewerDID: params.viewerDID ?? signingIdentity.id,
+                    delegationTokens: params.delegationTokens,
                     stores: tx,
                     contextExtensions: this.#buildGraphMutationContextExtensions({
                         ops,
@@ -1868,7 +2124,9 @@ export class KubunEngine {
             graphID: params.id,
             text: params.text,
             variables: params.variables ?? {},
-            viewerDID: params.viewerDID
+            viewerDID: params.viewerDID,
+            // Carried onto the request's credential authority, not onto a mutation cap.
+            delegationTokens: params.delegationTokens
         });
     }
     async getAPI(name) {

package/lib/executor.d.ts

@@ -16,11 +16,13 @@ export type EngineGraphParams = ExecuteGraphParams & {
      */
     owner?: string;
     /**
-     * Delegation tokens authorizing writes to documents the caller does not own.
-     * Carried on each outgoing mutation's `cap` field (part of the signed payload)
-     * and verified on apply against the owner→delegate capability chain. Used by
-     * `mutateGraph` only — ignored by `queryGraph`/`subscribeToGraph`, which do
-     * not produce mutations.
+     * Delegation tokens authorizing actions the caller cannot take unaided. On
+     * `mutateGraph` they ride each outgoing mutation's `cap` field (part of the
+     * signed payload) and are verified on apply against the owner→delegate chain.
+     * On every operation they are also surfaced on the request's ExecutionContext
+     * so a plugin's credential authority can authorize a delegated read/administer;
+     * `queryGraph`/`subscribeToGraph` produce no mutation cap but still carry them
+     * this way.
      */
     delegationTokens?: Array<string>;
 };

package/lib/index.d.ts

@@ -1,8 +1,7 @@
 export type { AccessChecker, AccessControlDB, AccessLevel, AccessPermissions, AccessRule, DefaultAccessLevel, } from './access-control.js';
 export { createAccessChecker, parseDocumentAccessPermissions, resolveAccessRule, validateDIDs, validateID, validateIDs, } from './access-control.js';
 export { catalogMatchesDoc } from './catalog-match.js';
-export type { Cipher } from './cipher.js';
-export { createDefaultCipher, deriveAtRestKey } from './cipher.js';
+export { type ControllerAuthorityParams, createControllerAuthority, } from './controller-authority.js';
 export type { AccessGate, AccessGateFactory, AccessGateStores, ApplyVerifiedMutationParams, ApplyVerifiedMutationResult, ApplyVerifiedMutationsParams, ApplyVerifiedMutationsResult, ContextFactory, DocumentWrite, EngineParams, ExecuteParams, ExecutionContext, MutateDocumentsParams, } from './engine.js';
 export { KubunEngine } from './engine.js';
 export type { EngineEvents } from './engine-events.js';

package/lib/index.js

@@ -1,6 +1,6 @@
 export { createAccessChecker, parseDocumentAccessPermissions, resolveAccessRule, validateDIDs, validateID, validateIDs } from './access-control.js';
 export { catalogMatchesDoc } from './catalog-match.js';
-export { createDefaultCipher, deriveAtRestKey } from './cipher.js';
+export { createControllerAuthority } from './controller-authority.js';
 export { KubunEngine } from './engine.js';
 export { isTransactionFatal, TransactionFatalError } from './errors.js';
 export { EngineEventBus } from './events.js';

package/lib/plugin.d.ts

@@ -1,11 +1,10 @@
-import type { Identity } from '@kokuin/token';
-import type { KubunDB } from '@kubun/db';
+import type { DIDMethodResolver, Identity } from '@kokuin/token';
+import type { KubunDB, StoreProvider } from '@kubun/db';
 import type { ExtensionResolvers } from '@kubun/graphql';
 import type { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
 import type { Runtime } from '@sozai/runtime';
 import type { ExecutionResult } from 'graphql';
-import type { Cipher } from './cipher.js';
 import type { ApplyVerifiedMutationParams, ApplyVerifiedMutationResult, ApplyVerifiedMutationsParams, ApplyVerifiedMutationsResult, ContextFactory, ExecuteParams, MutateDocumentsParams } from './engine.js';
 import type { EngineEvents } from './engine-events.js';
 import type { EngineEventBus } from './events.js';
@@ -64,9 +63,21 @@ export type PluginFactoryParams = {
     identity: Identity;
     eventBus: EngineEventBus<EngineEvents>;
     hlc: HLC;
+    /**
+     * How far into the future a stamp arriving from a peer may sit, in
+     * milliseconds — the engine's own bound, so a plugin ingesting peer data
+     * bounds it the same way the graph lane does rather than configuring a second
+     * one of its own.
+     */
+    maxDriftMS: number;
     getLogger: (name: string) => Logger;
-    /** Shared at-rest cipher; undefined when no key is available. */
-    cipher: Cipher | undefined;
+    /**
+     * The engine's `did:kokuin:` controller resolver, scoped to a store provider.
+     * A plugin wrapping credentials to a `did:kokuin:` recipient must resolve that
+     * controller through the request's transaction provider — building its own
+     * resolver over the base db would read outside the tx.
+     */
+    controllerResolverFor: (stores: StoreProvider) => DIDMethodResolver;
 };
 /**
  * Plugin descriptor returned by a plugin factory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/engine",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,32 +15,40 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kokuin/capability": "^0.2.1",
-    "@kokuin/token": "^0.3.0",
-    "@noble/ciphers": "^2.2.0",
-    "@noble/hashes": "^2.2.0",
+    "@kokuin/capability": "^0.3.0",
+    "@kokuin/controller": "^0.1.0",
+    "@kokuin/token": "^0.5.0",
+    "@noble/ciphers": "^2.3.0",
+    "@noble/hashes": "^2.3.0",
     "@sozai/async": "^0.2.1",
     "@sozai/codec": "^0.4.0",
     "@sozai/event": "^0.1.3",
     "@sozai/runtime": "^0.1.0",
     "@sozai/schema": "^0.1.1",
     "graphql": "^16.14.2",
-    "@kubun/db": "^0.12.0",
-    "@kubun/hlc": "^0.12.0",
-    "@kubun/db-adapter": "^0.12.0",
-    "@kubun/logger": "^0.12.0",
-    "@kubun/graphql": "^0.12.0",
-    "@kubun/store-delegation": "^0.12.0",
-    "@kubun/mutation": "^0.12.0",
-    "@kubun/protocol": "^0.12.0",
-    "@kubun/store-graph": "^0.12.0",
-    "@kubun/store-p2p": "^0.12.0"
+    "@kubun/db": "^0.13.0",
+    "@kubun/db-adapter": "^0.13.0",
+    "@kubun/graphql": "^0.13.0",
+    "@kubun/credential": "^0.13.0",
+    "@kubun/identity": "^0.13.0",
+    "@kubun/logger": "^0.13.0",
+    "@kubun/protocol": "^0.13.0",
+    "@kubun/store-delegation": "^0.13.0",
+    "@kubun/store-graph": "^0.13.0",
+    "@kubun/store-p2p": "^0.13.0",
+    "@kubun/store-controller": "^0.13.0",
+    "@kubun/mutation": "^0.13.0",
+    "@kubun/hlc": "^0.13.0"
   },
   "devDependencies": {
     "@testcontainers/postgresql": "^12.1.0",
-    "@kubun/id": "^0.12.0",
-    "@kubun/db-postgres": "^0.12.0",
-    "@kubun/test-utils": "^0.12.0"
+    "@kubun/db-postgres": "^0.13.0",
+    "@kubun/id": "^0.13.0",
+    "@kubun/store-credential": "^0.13.0",
+    "@kubun/test-utils": "^0.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
     "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",

package/lib/cipher.d.ts

@@ -1,6 +0,0 @@
-export type Cipher = {
-    encrypt(plaintext: string): string;
-    decrypt(ciphertext: string): string;
-};
-export declare function deriveAtRestKey(ikm: Uint8Array): Uint8Array;
-export declare function createDefaultCipher(key: Uint8Array): Cipher;

package/lib/cipher.js

@@ -1,40 +0,0 @@
-import { gcm } from '@noble/ciphers/aes.js';
-import { randomBytes } from '@noble/ciphers/utils.js';
-import { hkdf } from '@noble/hashes/hkdf.js';
-import { sha256 } from '@noble/hashes/sha2.js';
-import { fromB64, fromUTF, toB64, toUTF } from '@sozai/codec';
-const ENVELOPE_PREFIX = 'v1:';
-const IV_LENGTH = 12;
-const KEY_LENGTH = 32;
-// HKDF-SHA-256 domain separation for keys used to protect data at rest.
-const AT_REST_SALT = fromUTF('kubun/at-rest');
-const AT_REST_INFO = fromUTF('v1');
-export function deriveAtRestKey(ikm) {
-    return hkdf(sha256, ikm, AT_REST_SALT, AT_REST_INFO, KEY_LENGTH);
-}
-export function createDefaultCipher(key) {
-    if (key.length !== KEY_LENGTH) {
-        throw new Error(`Cipher key must be ${KEY_LENGTH} bytes, received ${key.length}`);
-    }
-    return {
-        encrypt (plaintext) {
-            const iv = randomBytes(IV_LENGTH);
-            // gcm().encrypt appends the auth tag, so sealed = ciphertext || tag.
-            const sealed = gcm(key, iv).encrypt(fromUTF(plaintext));
-            const envelope = new Uint8Array(iv.length + sealed.length);
-            envelope.set(iv, 0);
-            envelope.set(sealed, iv.length);
-            return ENVELOPE_PREFIX + toB64(envelope);
-        },
-        decrypt (ciphertext) {
-            if (!ciphertext.startsWith(ENVELOPE_PREFIX)) {
-                throw new Error('Unrecognized cipher envelope, expected v1 prefix');
-            }
-            const envelope = fromB64(ciphertext.slice(ENVELOPE_PREFIX.length));
-            const iv = envelope.subarray(0, IV_LENGTH);
-            const sealed = envelope.subarray(IV_LENGTH);
-            // Wrong key or tampered bytes fail the GCM tag check and throw here.
-            return toUTF(gcm(key, iv).decrypt(sealed));
-        }
-    };
-}