@kubun/service-graph-api 0.17.0 → 0.17.2

package/lib/handlers.js

@@ -2,7 +2,151 @@ import { stringifyToken } from '@kokuin/token';
 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 +168,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 +227,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);
@@ -155,17 +320,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 +483,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/service-graph-api",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -17,27 +17,27 @@
   "dependencies": {
     "@enkaku/server": "^0.21.2",
     "@kokuin/token": "^0.5.0",
-    "@kubun/engine": "^0.17.0",
+    "@kubun/engine": "^0.17.2",
     "@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",
+    "@kubun/mutation": "^0.17.1",
+    "@kubun/plugin-service-api": "^0.17.1",
+    "@kubun/protocol": "^0.17.1",
     "@sozai/generator": "^0.2.0",
     "@sozai/runtime": "^0.1.0",
-    "graphql": "^16.14.2"
+    "graphql": "^17.0.2"
   },
   "devDependencies": {
     "@enkaku/client": "^0.21.2",
     "@enkaku/transport": "^0.21.0",
     "@kokuin/capability": "^0.3.0",
     "@kokuin/controller": "^0.1.0",
-    "@kubun/client": "^0.17.0",
+    "@kubun/client": "^0.17.2",
     "@kubun/db": "^0.17.0",
-    "@kubun/plugin-service-server": "^0.17.0",
+    "@kubun/plugin-service-server": "^0.17.1",
     "@kubun/store-controller": "^0.17.0",
     "@kubun/store-delegation": "^0.17.0",
-    "@kubun/store-graph": "^0.17.0",
+    "@kubun/store-graph": "^0.17.1",
     "@kubun/store-p2p": "^0.17.0",
     "@kubun/test-utils": "^0.0.0"
   },