@ductape/mcp 0.2.30 → 0.2.31

package/CHANGELOG.md

@@ -6,6 +6,7 @@
 
 ## Unreleased
 
+- Added `cli-authentication` guidance for automatic Google/GitHub browser OAuth, validated loopback callbacks, trusted-terminal handoff, credential non-disclosure, and external session refresh.
 - Added source-verified graph/vector projection guidance to the `features`, `events`, `graphs`, and `vector` docs topics, including exact graph/vector payloads, NestJS consumer routing, replay/idempotency, projection-state ordering, rebuild/drift repair, and an explicit stop condition for the currently missing code-first `ctx.vector` API.
 - Added read-only `ductape_events_topic_setup` and `ductape_events_validate_project` tools and made the canonical one-topic-per-file `ductape/events/<topic-tag>.topic.json` layout explicit and enforceable through the CLI.
 - Mark `ductape_function_setup` as read-only, non-destructive, idempotent, and closed-world in both MCP registration APIs so hosts do not incorrectly require mutation approval for its pure setup-plan generation.

package/dist/index.js

@@ -909,12 +909,13 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   vector.deleteIndex    [{ product, env, vector, name }]
   vector.listIndexes    [{ product, env, vector }]
   vector.count          [{ product, env, vector, namespace? }]
-  vector.actions.create [{ product, vector, actionTag, name, operation, template, description?, parameters? }]
-  vector.actions.update [{ product, vector, actionTag, name?, description?, template?, parameters? }]
-  vector.actions.fetch  [{ product, vector, actionTag }]
-  vector.actions.fetchAll [{ product, vector }]
-  vector.actions.delete [{ product, vector, actionTag }]
-  vector.actions.execute [{ product, env, vector, action, input }]
+  vector.action.create [{ product, vector, actionTag, name, operation, template, description?, parameters? }]
+  vector.action.update [{ product, vector, actionTag, name?, description?, template?, parameters? }]
+  vector.action.fetch  [{ product, vector, actionTag }]
+  vector.action.fetchAll [{ product, vector }]
+  vector.action.delete [{ product, vector, actionTag }]
+  vector.action.execute [{ product, env, vector, action, input, session? }]
+    ← synchronous saved-action execution. Do not use vector.query for a saved action.
 
 ━━━ MODULE: features ━━━
   Feature definitions are code-first. Use features.define in application source; do not call
@@ -1500,6 +1501,7 @@ function runCli(command) {
                     'or use an OAuth flow:',
                     '  ductape login --browser google',
                     '  ductape login --browser github',
+                    'Browser OAuth returns to the CLI automatically through a validated 127.0.0.1 callback.',
                     '',
                     'Do not paste a password, OAuth callback token, or stored CLI credential into an agent prompt.',
                     'After login succeeds, retry the same ductape_cli command.',
@@ -1551,7 +1553,7 @@ const docsInputSchema = z.object({
     topic: z.string().describe('Feature topic to look up. Supported: ' +
         'transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
         'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-        'notifications, resilience, features, portable-functions, events, logs, migration, frontend, frontend-analytics, client, react, vue'),
+        'notifications, resilience, features, portable-functions, events, logs, migration, cli-authentication, frontend, frontend-analytics, client, react, vue'),
 });
 const eventsDiscoveryInputSchema = z.object({
     query: z.string().optional().describe('Capability or recovery search, including DLQ, dead letter, failed messages, retry, poison message, replay, or consumer failure.'),
@@ -1607,6 +1609,34 @@ const migrationInputSchema = z.object({
     write: z.boolean().optional().default(false).describe('Write redacted advisory artifacts only. This never writes application code or executable Ductape assets.'),
 });
 const DOCS = {
+    'cli-authentication': `
+DUCTAPE CLI AUTHENTICATION
+
+For an interactive local login, prefer browser OAuth:
+  ductape login --browser google
+  ductape login --browser github
+
+The CLI opens the provider in the user's browser, starts a temporary loopback listener on
+127.0.0.1, validates the returned OAuth state, exchanges the callback token, stores the resulting
+session in the local Ductape credential store, and then continues workspace selection. The user
+does not copy a callback token or share credentials with an agent.
+
+Run browser login only in the user's trusted local terminal. An MCP tool, agent subprocess, CI
+runner, container, SSH session, or remote development host may not own the browser's loopback
+interface. Do not invoke interactive login through ductape_cli and do not ask the user to paste a
+password, OAuth callback token, auth token, or stored credential into chat.
+
+Use email/password login only when the user deliberately chooses it in their own terminal:
+  ductape login
+
+Use --token only as a compatibility or automation fallback when the user already possesses a
+valid OAuth callback token through a trusted flow. Never solicit that token in an agent prompt.
+
+After login succeeds, retry the original ductape_cli operation. The MCP re-reads a previously
+missing or expired external CLI session without requiring an MCP restart. If a command returns
+HTTP 401 while workspace reads still succeed, treat it as endpoint authorization or command
+routing failure, not as a reason to re-authenticate.
+`.trim(),
     'portable-functions': `
 PORTABLE APPLICATION FUNCTIONS
 
@@ -2551,10 +2581,12 @@ Schema management:
   graph.dropIndex / dropConstraint / listIndexes / listConstraints
 
 Saved actions (parameterized queries stored on the product):
-  graph.createAction [{ graphTag?, name, description?, operation, query, parameters: [{ name, type, required?, defaultValue?, description? }] }, productTag?]
-  graph.listActions  [graphTag?, productTag?]
-  graph.execute      [{ product, env, graph, action, input?, session?, cache? }]
-  graph.dispatch     [data]  ← call ductape_generate_payload FIRST
+  graph.action.create   [{ product, graph|graphTag, name, description?, operation, query, parameters? }]
+  graph.action.fetchAll [{ product, graph|graphTag }]
+  graph.action.fetch    [{ product, graph|graphTag, action|actionTag }]
+  graph.action.execute  [{ product, env, graph, action, input, session? }]
+  graph.action.dispatch [{ product, env, graph, event, input, schedule? }]  ← call ductape_generate_payload FIRST
+  Use graph.action.execute for a saved action. graph.query is only for a direct provider-native query.
 
 Supported index types: btree | fulltext | vector | range | point | text
 Supported constraint types: UNIQUE | EXISTS | NODE_KEY
@@ -4025,6 +4057,14 @@ When you call features.define({ handler }), the handler runs TWICE:
      For loops: supply recordInput and iterate ctx.sampleInput so all iterations are recorded.
      ctx.input is always the runtime operator surface and must never expose recordInput literals.
      For branches: use branchOverrides so each path is captured.
+     Never make an authorization, validation, tenancy, or other security decision by branching on
+     ctx.input during recording. Use ctx.sampleInput only to discover graph shape; enforce security
+     invariants inside a runtime portable Function or recorded step.
+
+     ductape features sync [filter] sets DUCTAPE_SYNC_MODE=1 and, when filtered,
+     DUCTAPE_FEATURE_FILTER=<filter>. This is an administrative catalogue-only lifecycle: framework
+     integrations and project readiness hooks must not start HTTP listeners, provider probes,
+     schedulers, or Event consumers. Apply the filter before booting unrelated service modules.
 
   2. EXECUTION PHASE (at runtime) — handler is called with a real ExecutionContext.
      ctx.step() actually executes. All real Ductape component calls happen.
@@ -5100,8 +5140,10 @@ EXACT CODE-FIRST VECTOR CONTEXT:
     ductape vector actions get <action-tag> --vector <vector-tag> --json
   Always list and inspect first. Reuse an existing action when operation, namespace/filter/template,
   parameters, and output semantics match; do not create a duplicate action under a new name.
-  Update/delete/list use the same \`ductape vector actions\` surface. At runtime the SDK namespace is
-  \`ductape.vector.actions.*\` (plural), while Feature reuse is singular \`ctx.vector.execute(...)\`.
+  Update/delete/list use the same plural \`ductape vector actions\` CLI surface. Runtime SDK/MCP calls
+  use the singular \`ductape.vector.action.*\` namespace; execute saved actions with
+  \`ductape.vector.action.execute({ product, env, vector, action, input })\`. Feature handlers instead
+  use \`ctx.vector.execute({ vector, action, input })\` because product/env/session are inherited.
   Vertex AI Vector Search stores and searches supplied vectors. It does NOT generate embeddings.
   Do not claim that a Vertex Vector Search index embeds text.
 
@@ -5461,7 +5503,9 @@ const cliInputSchema = z.object({
         '"features sync" (runs the project\'s own "features:sync" npm script) — never call ' +
         'features.define from the app\'s normal startup path, since that blocks every boot on ' +
         'Ductape API reachability. See ductape_docs for the full convention.\n\n' +
-        'The CLI uses the user\'s local logged-in session (ductape login) — no key is required.'),
+        'The CLI uses the user\'s local logged-in session. Prefer browser OAuth in a trusted local terminal: ' +
+        'ductape login --browser google (or github). It returns automatically through a validated loopback callback. ' +
+        'Never invoke interactive login through MCP or ask the user for credentials.'),
 });
 async function loadMcpSdk() {
     try {
@@ -5626,6 +5670,25 @@ async function main() {
         const isLocalMigrationGuidance = (firstWord === 'migrate-codebase' && !args.command.includes('--ensure-product')) ||
             firstWord.startsWith('migration-');
         const isDiagnostic = firstWord === 'doctor';
+        if (firstWord === 'login') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            'Ductape login must be completed by the user in a trusted local terminal, not through an MCP tool process.',
+                            '',
+                            'Preferred browser OAuth:',
+                            '  ductape login --browser google',
+                            '  ductape login --browser github',
+                            '',
+                            'The browser returns to the CLI automatically through a validated 127.0.0.1 callback; no token copying is required.',
+                            'Never ask the user to paste a password, OAuth callback token, auth token, or stored CLI credential into the agent.',
+                            'After login succeeds, retry the original ductape_cli operation. The MCP will detect the new session.',
+                        ].join('\n'),
+                    }],
+                isError: true,
+            };
+        }
         if (!isAuthCommand && !isLocalMigrationGuidance && !isDiagnostic) {
             // Cache successful authentication, but re-check a missing/expired session on every call.
             // The user may complete `ductape login` in another terminal while this MCP process remains
@@ -5648,6 +5711,7 @@ async function main() {
                                 'or:',
                                 `  ductape login --browser google${wsFlag}`,
                                 `  ductape login --browser github${wsFlag}`,
+                                'Browser OAuth returns to the CLI automatically through a validated 127.0.0.1 callback.',
                                 '',
                                 'Never ask the user to paste their password, OAuth callback token, or stored CLI credential into the agent.',
                                 'After login succeeds, retry the original ductape_cli command.',
@@ -6082,7 +6146,7 @@ async function main() {
                 'index strategy, operation types) that should be confirmed with the user first.\n\n' +
                 'Available topics: transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
                 'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-                'notifications, resilience, features, portable-functions, events, logs, migration, frontend, frontend-analytics, client, react, vue',
+                'notifications, resilience, features, portable-functions, events, logs, migration, cli-authentication, frontend, frontend-analytics, client, react, vue',
             inputSchema: docsInputSchema,
         }, docsHandler);
         server.registerTool('ductape_events_discover', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",