@kubun/service-graph-api 0.17.1 → 0.18.0

package/lib/handlers.d.ts

@@ -15,4 +15,5 @@ export type CreateHandlersParams = {
     signingIdentity: SigningIdentity | null;
     transactionManager: TransactionManager;
 };
-export declare function createGraphHandlers(params: CreateHandlersParams): ProcedureHandlers<GraphProtocol>;
+export type GraphHandlers = ProcedureHandlers<GraphProtocol>;
+export declare function createGraphHandlers(params: CreateHandlersParams): GraphHandlers;

package/lib/handlers.js

@@ -1,8 +1,153 @@
 import { stringifyToken } from '@kokuin/token';
+import { MembershipCheckUnavailableError } from '@kubun/engine';
 import { DocumentID } from '@kubun/id';
 import { convertPatchInput, createMutationOperations, WriteAccessDeniedError } from '@kubun/mutation';
 import { consume } from '@sozai/generator';
-import { GraphQLError } from 'graphql';
+import { GraphQLError, Kind, parse } from 'graphql';
+// The field-name convention the connector plugin's schema extension mints
+// per-model action mutations under (see `createConnectorSchemaExtension` in
+// `@kubun/plugin-connector`). Not a live registry lookup — service-graph-api
+// has no dependency on plugin-connector — the prefix alone identifies a
+// connector spend syntactically, which is all a pre-signed or explicit-tx
+// submission carries before any resolver runs.
+const CONNECTOR_ACTION_FIELD_PREFIXES = [
+    'connectorCreate',
+    'connectorUpdate'
+];
+/**
+ * Walks a selection set counting field selections into `stats`, resolving
+ * `FRAGMENT_SPREAD` and `INLINE_FRAGMENT` selections rather than skipping
+ * them — graphql-js's own execution-time `collectFields` flattens fragments
+ * into their parent selection set, so a field hidden only behind a fragment
+ * still runs alongside whatever else is in the mutation. A walk that treated
+ * "top-level" as "only literal FIELD selections" would let a smuggled field
+ * (or even a second connector-action field) evade both the single-spend
+ * boundary and `containsConnectorActionField`'s detection.
+ *
+ * `visitedFragments` guards against a cyclic/self-referential fragment spread
+ * (A spreads B spreads A) hanging the handler: a fragment name already on the
+ * current recursion path is skipped rather than re-entered. It is removed
+ * again after that branch returns, so the same fragment spread twice in
+ * sibling (non-cyclic) positions is still counted both times. A spread whose
+ * definition is missing from the document contributes nothing — never throws;
+ * that document is already headed for the normal GraphQL-validation error
+ * path, not this gate's concern.
+ */ function collectMutationFields(selectionSet, document, visitedFragments, stats) {
+    for (const selection of selectionSet.selections){
+        if (selection.kind === Kind.FIELD) {
+            stats.totalFieldCount += 1;
+            const name = selection.name.value;
+            if (CONNECTOR_ACTION_FIELD_PREFIXES.some((prefix)=>name.startsWith(prefix))) {
+                stats.connectorFieldCount += 1;
+            }
+            continue;
+        }
+        if (selection.kind === Kind.INLINE_FRAGMENT) {
+            collectMutationFields(selection.selectionSet, document, visitedFragments, stats);
+            continue;
+        }
+        if (selection.kind === Kind.FRAGMENT_SPREAD) {
+            const fragmentName = selection.name.value;
+            if (visitedFragments.has(fragmentName)) continue;
+            const fragmentDef = document.definitions.find((def)=>def.kind === Kind.FRAGMENT_DEFINITION && def.name.value === fragmentName);
+            if (fragmentDef == null) continue;
+            visitedFragments.add(fragmentName);
+            collectMutationFields(fragmentDef.selectionSet, document, visitedFragments, stats);
+            visitedFragments.delete(fragmentName);
+        }
+    }
+}
+/**
+ * Counts a mutation document's top-level field selections (fragment-expanded,
+ * see `collectMutationFields`), and how many of them are connector-action
+ * fields. Connector actions authorize themselves through the
+ * `connector/execute` gate inside `executeAction`, which needs the
+ * `ExecutionContext` (groupID, invocationCaps, authenticated) the engine's own
+ * delegated-mode context factory builds — the pre-signed and explicit-tx
+ * modes below never build one, so a connector field reaching either would run
+ * with no gate at all. Detected on the query text, before any mutation is
+ * applied or buffered.
+ *
+ * Shared by `containsConnectorActionField` (boolean presence, used by the
+ * pre-signed/explicit-transaction gates below) and the delegated-mode
+ * single-spend boundary (which additionally needs the total count to detect
+ * a connector field mixed with other mutations).
+ */ function analyzeMutationFields(text) {
+    let document;
+    try {
+        document = parse(text);
+    } catch  {
+        // A malformed document is a syntax error for the normal execution path to
+        // surface — not this gate's concern.
+        return {
+            totalFieldCount: 0,
+            connectorFieldCount: 0
+        };
+    }
+    const stats = {
+        totalFieldCount: 0,
+        connectorFieldCount: 0
+    };
+    const visitedFragments = new Set();
+    for (const definition of document.definitions){
+        if (definition.kind !== Kind.OPERATION_DEFINITION || definition.operation !== 'mutation') {
+            continue;
+        }
+        collectMutationFields(definition.selectionSet, document, visitedFragments, stats);
+    }
+    return stats;
+}
+function containsConnectorActionField(text) {
+    return analyzeMutationFields(text).connectorFieldCount > 0;
+}
+function connectorActionRequiresDelegatedModeResult() {
+    return toGraphResult({
+        data: null,
+        errors: [
+            new GraphQLError('Connector actions are delegated-mode only', {
+                extensions: {
+                    code: 'CONNECTOR_ACTION_REQUIRES_DELEGATED_MODE'
+                }
+            })
+        ]
+    });
+}
+/**
+ * A connector-action spend must be the sole mutation in the request — not
+ * paired with another connector-action field, nor with any ordinary
+ * mutation field. This is the single-spend boundary: a purely syntactic
+ * count of top-level fields, checked before the request reaches the action
+ * layer (`executeAction` in `@kubun/plugin-connector`).
+ */ function connectorActionSingleSpendOnlyResult() {
+    return toGraphResult({
+        data: null,
+        errors: [
+            new GraphQLError('A connector-action spend must be the only field in the mutation', {
+                extensions: {
+                    code: 'CONNECTOR_ACTION_SINGLE_SPEND_ONLY'
+                }
+            })
+        ]
+    });
+}
+/**
+ * A credential-spend connector-action mutation must carry both envelope ids.
+ * Presence only — their content/format, envelope-reuse (replay/conflict)
+ * detection, and the `primary`-target rejection are all deeper semantic
+ * checks that stay in the action layer; this gate never inspects their
+ * values.
+ */ function connectorActionEnvelopeMissingResult() {
+    return toGraphResult({
+        data: null,
+        errors: [
+            new GraphQLError('A connector-action spend requires operationID and deterministicEventID', {
+                extensions: {
+                    code: 'CONNECTOR_ACTION_ENVELOPE_MISSING'
+                }
+            })
+        ]
+    });
+}
 function toGraphResult(result) {
     const graphResult = {
         data: result.data
@@ -24,27 +169,42 @@ function toGraphResult(result) {
  * The verified `iss` is the only trustworthy viewer: it is the DID that signed
  * the request. A `sub` that differs from `iss` is a forged-subject attempt
  * (running the graph as someone else), so it is rejected outright. The
- * `defaultDID` fallback applies ONLY when no payload is present, which is the
- * explicit `accessRules: false` local mode where authentication is disabled.
+ * `defaultDID` fallback applies when no payload is present (the explicit
+ * `accessRules: false` local mode where authentication is disabled) or when a
+ * payload carries no `iss`.
+ *
+ * `authenticated` is `true` only on the verified-`iss` path — never on the
+ * `defaultDID` substitution — so a caller can forward it onto
+ * `ExecutionContext.authenticated` as trusted provenance.
  */ function resolveViewerDID(payload, defaultDID) {
-    if (payload == null) return defaultDID;
+    if (payload == null) return {
+        viewerDID: defaultDID,
+        authenticated: false
+    };
     const iss = payload.iss;
     const sub = payload.sub;
     if (sub != null && sub !== iss) {
         throw new Error('Access denied: signed payload subject does not match issuer');
     }
-    return iss ?? defaultDID;
+    return iss != null ? {
+        viewerDID: iss,
+        authenticated: true
+    } : {
+        viewerDID: defaultDID,
+        authenticated: false
+    };
 }
 /**
  * Extract EngineGraphParams from a handler context, resolving the viewerDID
  * from the verified issuer of the signed message payload (see resolveViewerDID).
  */ function extractGraphParams(ctx, defaultDID) {
     const payload = ctx.message?.payload;
+    const { viewerDID } = resolveViewerDID(payload, defaultDID);
     return {
         id: ctx.param.id,
         text: ctx.param.text,
         variables: ctx.param.variables ?? {},
-        viewerDID: resolveViewerDID(payload, defaultDID)
+        viewerDID
     };
 }
 export function createGraphHandlers(params) {
@@ -68,8 +228,14 @@ export function createGraphHandlers(params) {
             });
         },
         'graph/mutate': async (ctx)=>{
-            const { viewerDID } = extractGraphParams(ctx, defaultDID);
+            const payload = ctx.message?.payload;
+            const { viewerDID, authenticated } = resolveViewerDID(payload, defaultDID);
             if (ctx.param.mutations != null) {
+                // Connector actions are delegated-mode only — refused before any
+                // mutation is applied (see `containsConnectorActionField`).
+                if (containsConnectorActionField(ctx.param.text)) {
+                    return connectorActionRequiresDelegatedModeResult();
+                }
                 // Pre-signed mode: client submitted JWT tokens keyed by GraphQL field alias
                 const mutations = ctx.param.mutations;
                 const entries = Object.entries(mutations);
@@ -87,6 +253,16 @@ export function createGraphHandlers(params) {
                         tokens
                     });
                 } catch (cause) {
+                    if (cause instanceof MembershipCheckUnavailableError) {
+                        return toGraphResult({
+                            data: null,
+                            errors: [
+                                new GraphQLError(cause.message, {
+                                    extensions: cause.extensions
+                                })
+                            ]
+                        });
+                    }
                     if (cause instanceof WriteAccessDeniedError) {
                         return toGraphResult({
                             data: null,
@@ -155,17 +331,53 @@ export function createGraphHandlers(params) {
             const owner = ctx.param.owner ?? viewerDID;
             // Non-transaction delegated: engine.mutateGraph() handles signing internally
             if (transactionID == null) {
+                // The single spend boundary + envelope presence gate applies only on
+                // this rail — it's the only one a connector-action field can reach
+                // (pre-signed and explicit-transaction both refuse it outright,
+                // above and below). Purely syntactic: field-count and id-presence
+                // only, never the fields' content — see the two result helpers'
+                // docs for what stays in the action layer instead.
+                const fieldStats = analyzeMutationFields(ctx.param.text);
+                if (fieldStats.connectorFieldCount > 0) {
+                    if (fieldStats.totalFieldCount > 1) {
+                        return connectorActionSingleSpendOnlyResult();
+                    }
+                    if (ctx.param.operationID == null || ctx.param.deterministicEventID == null) {
+                        return connectorActionEnvelopeMissingResult();
+                    }
+                }
+                // `groupID` is server-derived from the tunnel binding (see
+                // ServiceHandlerContext.groupID), never a wire field — RequestHandlerContext
+                // has no static `groupID`, so it is read via the same narrowed-cast
+                // pattern as `payload` above.
+                const groupID = ctx.groupID;
                 const result = await engine.mutateGraph({
                     id: ctx.param.id,
                     text: ctx.param.text,
                     variables: ctx.param.variables ?? {},
                     viewerDID,
-                    owner
+                    owner,
+                    authenticated,
+                    groupID,
+                    invocationCaps: ctx.param.invocationCaps,
+                    // The connector operation envelope rides the wire and reaches the
+                    // action layer only through `ExecutionContext` — forward it, or a
+                    // credential spend fails its envelope check downstream.
+                    operationID: ctx.param.operationID,
+                    deterministicEventID: ctx.param.deterministicEventID
                 });
                 return toGraphResult(result);
             }
             // Transaction mode: buffer signed mutations without applying them.
             // Requires custom signing context since mutateGraph() applies immediately.
+            // Connector actions are delegated-mode only — refused before any
+            // mutation is buffered (see `containsConnectorActionField`); the
+            // non-transaction delegated branch above already returned, so reaching
+            // here means an explicit transaction that never builds the engine's
+            // own ExecutionContext (groupID, invocationCaps, authenticated).
+            if (containsConnectorActionField(ctx.param.text)) {
+                return connectorActionRequiresDelegatedModeResult();
+            }
             const signAndBuffer = async (mutation)=>{
                 const signed = await signingIdentity.signToken(mutation);
                 const jwt = stringifyToken(signed);
@@ -282,7 +494,7 @@ export function createGraphHandlers(params) {
         },
         'graph/beginTransaction': async (ctx)=>{
             const payload = ctx.message?.payload;
-            const callerDID = resolveViewerDID(payload, defaultDID);
+            const { viewerDID: callerDID } = resolveViewerDID(payload, defaultDID);
             // Validate that the graph exists before starting a transaction
             await engine.loadGraph({
                 id: ctx.param.id
@@ -304,6 +516,18 @@ export function createGraphHandlers(params) {
                         tokens
                     });
                 } catch (cause) {
+                    if (cause instanceof MembershipCheckUnavailableError) {
+                        // Keep the buffered writes so the caller can retry this transaction.
+                        return {
+                            success: false,
+                            error: {
+                                code: cause.code,
+                                message: cause.message,
+                                docID: cause.docID,
+                                retryable: true
+                            }
+                        };
+                    }
                     if (cause instanceof WriteAccessDeniedError) {
                         // Revocation between begin and commit — surface the reason on the
                         // wire via the typed `error` field so callers can distinguish

package/lib/index.d.ts

@@ -3,7 +3,7 @@ import type { AccessRules } from '@kubun/plugin-service-api';
 import type { TransactionManagerOptions } from './transaction-manager.js';
 export type { GraphProtocol } from '@kubun/protocol';
 export type { CreateHandlersParams } from './handlers.js';
-export { createGraphHandlers } from './handlers.js';
+export { createGraphHandlers, type GraphHandlers } from './handlers.js';
 export type { TransactionManagerOptions } from './transaction-manager.js';
 export { TransactionManager } from './transaction-manager.js';
 export type GraphServicePluginOptions = {

package/lib/index.js

@@ -3,10 +3,29 @@
 // and transaction-manager building blocks the RPC plugin still composes directly.
 // The wire contract itself lives in `@kubun/protocol` and is re-exported here.
 import { isSigningIdentity } from '@kokuin/token';
+import { GRAPH_LONG_LIVED_PROCEDURES, graphProtocol } from '@kubun/protocol';
 import { createGraphHandlers } from './handlers.js';
 import { TransactionManager } from './transaction-manager.js';
 export { createGraphHandlers } from './handlers.js';
 export { TransactionManager } from './transaction-manager.js';
+// The protocol's schemas carry `$id`s that `@kubun/protocol` also registers on the
+// shared validator for standalone use. Compiled again inside the host's message
+// schema they clash as ambiguous references, so the served copy drops them (nothing
+// references them by `$ref`).
+function withoutSchemaIDs(value) {
+    if (Array.isArray(value)) {
+        return value.map(withoutSchemaIDs);
+    }
+    if (value != null && typeof value === 'object') {
+        const copy = {};
+        for (const [key, entry] of Object.entries(value)){
+            if (key !== '$id' || typeof entry !== 'string') copy[key] = withoutSchemaIDs(entry);
+        }
+        return copy;
+    }
+    return value;
+}
+const servedGraphProtocol = withoutSchemaIDs(graphProtocol);
 // The service name the provider registers under and the host toggles via `services`.
 const GRAPH_SERVICE_NAME = 'graph';
 /**
@@ -39,7 +58,9 @@ const GRAPH_SERVICE_NAME = 'graph';
             // The typed `ProcedureHandlers<GraphProtocol>` narrows to the host's
             // structural `Handlers` at this one seam, mirroring the host's serve cast.
             handlers: handlers,
-            accessRules: options?.accessRules ?? {}
+            accessRules: options?.accessRules ?? {},
+            longLivedProcedures: GRAPH_LONG_LIVED_PROCEDURES,
+            protocol: servedGraphProtocol
         });
         return {
             name: 'graph-service',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/service-graph-api",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,30 +15,30 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@enkaku/server": "^0.21.2",
-    "@kokuin/token": "^0.5.0",
-    "@kubun/engine": "^0.17.1",
-    "@kubun/hlc": "^0.17.0",
-    "@kubun/id": "^0.17.0",
-    "@kubun/mutation": "^0.17.0",
-    "@kubun/plugin-service-api": "^0.17.0",
-    "@kubun/protocol": "^0.17.0",
-    "@sozai/generator": "^0.2.0",
+    "@enkaku/server": "^0.21.5",
+    "@kokuin/token": "^0.5.1",
+    "@kubun/engine": "^0.18.0",
+    "@kubun/hlc": "^0.18.0",
+    "@kubun/id": "^0.18.0",
+    "@kubun/mutation": "^0.18.0",
+    "@kubun/plugin-service-api": "^0.18.0",
+    "@kubun/protocol": "^0.18.0",
+    "@sozai/generator": "^0.2.2",
     "@sozai/runtime": "^0.1.0",
     "graphql": "^17.0.2"
   },
   "devDependencies": {
-    "@enkaku/client": "^0.21.2",
-    "@enkaku/transport": "^0.21.0",
-    "@kokuin/capability": "^0.3.0",
+    "@enkaku/client": "^0.21.5",
+    "@enkaku/transport": "^0.21.5",
+    "@kokuin/capability": "^0.4.2",
     "@kokuin/controller": "^0.1.0",
-    "@kubun/client": "^0.17.1",
-    "@kubun/db": "^0.17.0",
-    "@kubun/plugin-service-server": "^0.17.0",
-    "@kubun/store-controller": "^0.17.0",
-    "@kubun/store-delegation": "^0.17.0",
-    "@kubun/store-graph": "^0.17.0",
-    "@kubun/store-p2p": "^0.17.0",
+    "@kubun/client": "^0.18.0",
+    "@kubun/db": "^0.18.0",
+    "@kubun/plugin-service-server": "^0.18.0",
+    "@kubun/store-controller": "^0.18.0",
+    "@kubun/store-delegation": "^0.18.0",
+    "@kubun/store-graph": "^0.18.0",
+    "@kubun/store-p2p": "^0.18.0",
     "@kubun/test-utils": "^0.0.0"
   },
   "publishConfig": {