@pikku/inspector 0.12.13 → 0.12.16

package/dist/utils/serialize-inspector-state.js

@@ -98,6 +98,10 @@ export function serializeInspectorState(state) {
             meta: state.nodes.meta,
             files: Array.from(state.nodes.files),
         },
+        auth: {
+            providers: state.auth.providers,
+            files: Array.from(state.auth.files),
+        },
         secrets: {
             definitions: state.secrets.definitions,
             files: Array.from(state.secrets.files),
@@ -246,6 +250,10 @@ export function deserializeInspectorState(data) {
             meta: data.nodes?.meta || {},
             files: new Set(data.nodes?.files || []),
         },
+        auth: {
+            providers: data.auth?.providers || [],
+            files: new Set(data.auth?.files || []),
+        },
         secrets: {
             definitions: data.secrets?.definitions || [],
             files: new Set(data.secrets?.files || []),

package/dist/utils/workflow/dsl/extract-dsl-workflow.js

@@ -293,21 +293,32 @@ function extractExpressionStatement(statement, context) {
         if (ts.isIdentifier(expr.left)) {
             outputVar = expr.left.text;
             // Check if this is an assignment to a context variable (set step)
+            // But if the RHS is a workflow.do() call, fall through to RPC extraction —
+            // reassigning a pre-declared variable with a workflow step is valid and common.
             if (context.contextVars.has(outputVar)) {
-                const literalValue = extractLiteralValue(expr.right);
-                if (literalValue !== undefined) {
+                const rhs = expr.right;
+                const rhsCall = ts.isAwaitExpression(rhs) && ts.isCallExpression(rhs.expression)
+                    ? rhs.expression
+                    : null;
+                const isWorkflowCall = rhsCall
+                    ? isWorkflowDoCall(rhsCall, context.checker)
+                    : false;
+                if (!isWorkflowCall) {
+                    const literalValue = extractLiteralValue(expr.right);
+                    if (literalValue !== undefined) {
+                        return {
+                            type: 'set',
+                            variable: outputVar,
+                            value: literalValue,
+                        };
+                    }
+                    // Non-literal assignment to context var - use expression as string
                     return {
                         type: 'set',
                         variable: outputVar,
-                        value: literalValue,
+                        value: getSourceText(expr.right),
                     };
                 }
-                // Non-literal assignment to context var - use expression as string
-                return {
-                    type: 'set',
-                    variable: outputVar,
-                    value: getSourceText(expr.right),
-                };
             }
         }
         // Use right side as the expression to extract from

package/dist/visit.js

@@ -17,6 +17,7 @@ import { addWireAddon } from './add/add-wire-addon.js';
 import { addMiddleware } from './add/add-middleware.js';
 import { addPermission } from './add/add-permission.js';
 import { addCLI, addCLIRenderers } from './add/add-cli.js';
+import { addAuth } from './add/add-auth.js';
 import { addSecret } from './add/add-secret.js';
 import { addCredential } from './add/add-credential.js';
 import { addVariable } from './add/add-variable.js';
@@ -41,6 +42,7 @@ export const visitSetup = (logger, checker, node, state, options) => {
 };
 export const visitRoutes = (logger, checker, node, state, options) => {
     addFunctions(logger, node, checker, state, options);
+    addAuth(logger, node, checker, state, options);
     addSecret(logger, node, checker, state, options);
     addCredential(logger, node, checker, state, options);
     addVariable(logger, node, checker, state, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.13",
+  "version": "0.12.16",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.25",
+    "@pikku/core": "^0.12.27",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "^2.5.0",
     "tsx": "^4.21.0",

package/src/add/add-ai-agent.ts

@@ -252,7 +252,7 @@ export const addAIAgent: AddWiring = (
 
     const nameValue = getPropertyValue(obj, 'name') as string | null
     const { disabled, tags, summary, description, errors } =
-      getCommonWireMetaData(obj, 'AI agent', nameValue, logger)
+      getCommonWireMetaData(obj, 'AI agent', nameValue, logger, checker)
 
     if (disabled) return
 

package/src/add/add-auth.test.ts

@@ -0,0 +1,175 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+
+const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
+  ({
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    critical: (code: ErrorCode, message: string) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  }) satisfies InspectorLogger
+
+describe('addAuth inspector', () => {
+  test('extracts provider string literals from wireAuth call', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-'))
+    const file = join(rootDir, 'auth.ts')
+
+    await writeFile(
+      file,
+      [
+        "import { wireAuth } from '@pikku/auth-js'",
+        "wireAuth({ providers: ['github', 'google'] })",
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      assert.equal(criticals.length, 0)
+      assert.deepEqual(state.auth.providers, ['github', 'google'])
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('deduplicates providers across multiple wireAuth calls', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-dedup-'))
+    const file = join(rootDir, 'auth.ts')
+
+    await writeFile(
+      file,
+      [
+        "import { wireAuth } from '@pikku/auth-js'",
+        "wireAuth({ providers: ['github'] })",
+        "wireAuth({ providers: ['github', 'google'] })",
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      assert.equal(criticals.length, 0)
+      assert.deepEqual(state.auth.providers, ['github', 'google'])
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('logs critical error when a provider is a non-literal reference', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-nonlit-'))
+    const file = join(rootDir, 'auth.ts')
+
+    await writeFile(
+      file,
+      [
+        "import { wireAuth } from '@pikku/auth-js'",
+        "const PROVIDER = 'github'",
+        'wireAuth({ providers: [PROVIDER] })',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      await inspect(makeLogger(criticals), [file], { rootDir })
+      const hit = criticals.find(
+        (e) => e.code === ErrorCode.NON_LITERAL_WIRE_NAME
+      )
+      assert.ok(hit, 'expected NON_LITERAL_WIRE_NAME critical')
+      assert.match(hit!.message, /PROVIDER/)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('does not error when providers is absent (credentials-only wireAuth)', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-creds-only-'))
+    const file = join(rootDir, 'auth.ts')
+
+    await writeFile(
+      file,
+      [
+        "import { wireAuth } from '@pikku/auth-js'",
+        'wireAuth({ credentials: { authorize: async () => null } })',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      assert.equal(
+        criticals.length,
+        0,
+        'credentials-only wireAuth must not produce errors'
+      )
+      assert.deepEqual(
+        state.auth.providers,
+        [],
+        'no providers should be extracted'
+      )
+      assert.ok(state.auth.files.has(file), 'source file still tracked')
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('logs critical error when providers is not an array literal', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-nonarray-'))
+    const file = join(rootDir, 'auth.ts')
+
+    await writeFile(
+      file,
+      [
+        "import { wireAuth } from '@pikku/auth-js'",
+        "const PROVIDERS = ['github']",
+        'wireAuth({ providers: PROVIDERS })',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      await inspect(makeLogger(criticals), [file], { rootDir })
+      const hit = criticals.find((e) => e.code === ErrorCode.MISSING_NAME)
+      assert.ok(
+        hit,
+        'expected MISSING_NAME critical for non-array-literal providers'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('tracks source file in state.auth.files', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-files-'))
+    const file = join(rootDir, 'auth.wiring.ts')
+
+    await writeFile(
+      file,
+      [
+        "import { wireAuth } from '@pikku/auth-js'",
+        "wireAuth({ providers: ['discord'] })",
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      assert.equal(criticals.length, 0)
+      assert.ok(
+        state.auth.files.has(file),
+        'source file should be tracked in state.auth.files'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/add-auth.ts

@@ -0,0 +1,49 @@
+import * as ts from 'typescript'
+import type { AddWiring } from '../types.js'
+import { ErrorCode } from '../error-codes.js'
+
+export const addAuth: AddWiring = (logger, node, _checker, state) => {
+  if (!ts.isCallExpression(node)) return
+
+  const expression = node.expression
+  if (!ts.isIdentifier(expression) || expression.text !== 'wireAuth') return
+
+  const firstArg = node.arguments[0]
+  if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return
+
+  const providersProp = firstArg.properties.find(
+    (p) =>
+      ts.isPropertyAssignment(p) &&
+      (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+      p.name.text === 'providers'
+  ) as ts.PropertyAssignment | undefined
+
+  const sourceFile = node.getSourceFile().fileName
+  state.auth.files.add(sourceFile)
+
+  if (!providersProp) {
+    return
+  }
+
+  if (!ts.isArrayLiteralExpression(providersProp.initializer)) {
+    logger.critical(
+      ErrorCode.MISSING_NAME,
+      'wireAuth: providers must be an array literal of string literals.'
+    )
+    return
+  }
+
+  for (const element of (providersProp.initializer as ts.ArrayLiteralExpression)
+    .elements) {
+    if (!ts.isStringLiteral(element)) {
+      logger.critical(
+        ErrorCode.NON_LITERAL_WIRE_NAME,
+        `wireAuth: each provider must be a string literal. Found: ${element.getText()}`
+      )
+      return
+    }
+    if (!state.auth.providers.includes(element.text)) {
+      state.auth.providers.push(element.text)
+    }
+  }
+}

package/src/add/add-channel.ts

@@ -238,7 +238,8 @@ export function addMessagesRoutes(
                             init,
                             'Channel message',
                             routeKey,
-                            logger
+                            logger,
+                            checker
                           ).tags
                         : undefined
                       const routeMiddleware = ts.isObjectLiteralExpression(init)
@@ -270,7 +271,8 @@ export function addMessagesRoutes(
                           init,
                           'Channel message',
                           routeKey,
-                          logger
+                          logger,
+                          checker
                         ).tags
                       : undefined
                     const routeMiddleware = ts.isObjectLiteralExpression(init)
@@ -319,7 +321,8 @@ export function addMessagesRoutes(
                                 init,
                                 'Channel message',
                                 routeKey,
-                                logger
+                                logger,
+                                checker
                               ).tags
                             : undefined
                           const routeMiddleware = ts.isObjectLiteralExpression(
@@ -350,7 +353,8 @@ export function addMessagesRoutes(
                                 init,
                                 'Channel message',
                                 routeKey,
-                                logger
+                                logger,
+                                checker
                               ).tags
                             : undefined
                           const routeMiddleware = ts.isObjectLiteralExpression(
@@ -438,7 +442,8 @@ export function addMessagesRoutes(
                       init,
                       'Channel message',
                       routeKey,
-                      logger
+                      logger,
+                      checker
                     ).tags
                   : undefined
                 const routeMiddleware = ts.isObjectLiteralExpression(init)
@@ -481,7 +486,13 @@ export function addMessagesRoutes(
       // Resolve middleware and permissions for this route
       // Check if the route config is an object literal with middleware/permissions
       const routeTags = ts.isObjectLiteralExpression(init)
-        ? getCommonWireMetaData(init, 'Channel message', routeKey, logger).tags
+        ? getCommonWireMetaData(
+            init,
+            'Channel message',
+            routeKey,
+            logger,
+            checker
+          ).tags
         : undefined
       const routeMiddleware = ts.isObjectLiteralExpression(init)
         ? resolveMiddleware(state, init, routeTags, checker)
@@ -540,7 +551,7 @@ export const addChannel: AddWiring = (
     : []
 
   const { disabled, tags, summary, description, errors } =
-    getCommonWireMetaData(obj, 'Channel', name, logger)
+    getCommonWireMetaData(obj, 'Channel', name, logger, checker)
 
   if (disabled) return
 
@@ -630,6 +641,25 @@ export const addChannel: AddWiring = (
     state.serviceAggregation.usedFunctions.add(disconnectFuncId)
   }
 
+  // Synthesize function meta for connect/disconnect handlers that are defined
+  // with pikkuChannelConnectionFunc/pikkuChannelDisconnectionFunc (not pikkuFunc/
+  // pikkuSessionlessFunc), so the runtime has correct sessionless info without
+  // needing to inject it at runtime.
+  {
+    const routeAuth = getPropertyValue(obj, 'auth')
+    const sessionless = routeAuth === false ? true : undefined
+    for (const funcId of [connectFuncId, disconnectFuncId]) {
+      if (funcId && !state.functions.meta[funcId]) {
+        state.functions.meta[funcId] = {
+          pikkuFuncId: funcId,
+          sessionless,
+          inputSchemaName: null,
+          outputSchemaName: null,
+        }
+      }
+    }
+  }
+
   if (message) {
     state.serviceAggregation.usedFunctions.add(message.pikkuFuncId)
   }

package/src/add/add-functions.ts

@@ -462,7 +462,13 @@ export const addFunctions: AddWiring = (
   // Extract config properties if using object form
   if (ts.isObjectLiteralExpression(firstArg)) {
     objectNode = firstArg
-    const metadata = getCommonWireMetaData(firstArg, 'Function', name, logger)
+    const metadata = getCommonWireMetaData(
+      firstArg,
+      'Function',
+      name,
+      logger,
+      checker
+    )
     if (metadata.disabled) return
     title = metadata.title
     tags = metadata.tags
@@ -883,24 +889,50 @@ export const addFunctions: AddWiring = (
     }
   }
 
-  // ── PII brand check ───────────────────────────────────────────────────────
-  // Walk the function body's ACTUAL inferred return type looking for Private<T>
-  // / Secret<T> brands (__pii__ property).  This runs for every function,
-  // including those with a Zod output schema, because the TS return type
-  // reflects what the body actually returns before any Zod coercion.
+  const sessionless = expression.text !== 'pikkuFunc'
+
+  // ── Classification brand check ─────────────────────────────────────────────
+  // Walk the function body's ACTUAL inferred return type looking for classification
+  // brands (__classification__ property on Private<T>, Pii<T>, Secret<T>).
+  //
+  // Semantics:
+  //   secret  → never returned by any exposed function (sessioned or not)
+  //   private → only visible to authenticated (sessioned) users; ok for pikkuFunc
+  //   public  → safe for sessionless functions
   {
     const sig = checker.getSignatureFromDeclaration(handler)
     if (sig) {
       const rawRet = checker.getReturnTypeOfSignature(sig)
       const unwrapped = unwrapPromise(checker, rawRet)
-      const piiPaths = findPiiPaths(checker, unwrapped)
-      if (piiPaths.length > 0) {
+      const classifiedFields = findPiiPaths(checker, unwrapped)
+
+      const secretPaths = classifiedFields
+        .filter((f) => f.classification === 'secret')
+        .map((f) => f.path)
+
+      const privatePaths = classifiedFields
+        .filter(
+          (f) => f.classification === 'private' || f.classification === 'pii'
+        )
+        .map((f) => f.path)
+
+      if (secretPaths.length > 0) {
+        logger.critical(
+          ErrorCode.PII_IN_OUTPUT,
+          `Function '${name}' exposes secret-classified field(s) in its return type: ` +
+            secretPaths.map((p) => `'${p}'`).join(', ') +
+            `.\n  Secret fields must never appear in function output. ` +
+            `Strip these fields before returning or change the column classification.`
+        )
+      }
+
+      if (sessionless && privatePaths.length > 0) {
         logger.critical(
           ErrorCode.PII_IN_OUTPUT,
-          `Function '${name}' exposes PII-classified field(s) in its return type: ` +
-            piiPaths.map((p) => `'${p}'`).join(', ') +
-            `.\n  Either strip these fields before returning or mark the column ` +
-            `@public in the migration if it is safe to expose.`
+          `Sessionless function '${name}' exposes private-classified field(s) in its return type: ` +
+            privatePaths.map((p) => `'${p}'`).join(', ') +
+            `.\n  Private fields are only safe to return from authenticated (sessioned) functions. ` +
+            `Either require a session (use pikkuFunc) or mark the column @public if it is safe to expose publicly.`
         )
       }
     }
@@ -946,7 +978,6 @@ export const addFunctions: AddWiring = (
     }
   }
 
-  const sessionless = expression.text !== 'pikkuFunc'
   const implementationHash = computeImplementationHash({
     wrapper: expression.text,
     handler,

package/src/add/add-gateway.ts

@@ -45,7 +45,7 @@ export const addGateway: AddWiring = (
   const typeValue = getPropertyValue(obj, 'type') as GatewayTransportType | null
   const routeValue = getPropertyValue(obj, 'route') as string | undefined
   const { disabled, tags, summary, description, errors } =
-    getCommonWireMetaData(obj, 'Gateway', nameValue, logger)
+    getCommonWireMetaData(obj, 'Gateway', nameValue, logger, checker)
 
   if (disabled) return
 

package/src/add/add-http-route.ts

@@ -175,7 +175,7 @@ export function registerHTTPRoute({
     summary,
     description,
     errors,
-  } = getCommonWireMetaData(obj, 'HTTP route', fullRoute, logger)
+  } = getCommonWireMetaData(obj, 'HTTP route', fullRoute, logger, checker)
 
   if (disabled) return
 
@@ -248,6 +248,31 @@ export function registerHTTPRoute({
     extracted.isHelper
   )
 
+  // Propagate sessionless from the addon target so the runtime can correctly
+  // determine whether a session is required for ref()-based routes.
+  if (refAddonTarget) {
+    const targetMeta = resolveFunctionMeta(state, refAddonTarget)
+    const inlineMeta = state.functions.meta[funcName]
+    if (targetMeta && inlineMeta && targetMeta.sessionless !== undefined) {
+      inlineMeta.sessionless = targetMeta.sessionless
+    }
+  }
+
+  // For inline functions (e.g. oauth2 handlers), propagate sessionless: true
+  // when auth is explicitly disabled at the route or group level — the
+  // developer opted out of auth so no session is required.
+  {
+    const inlineMeta = state.functions.meta[funcName]
+    if (inlineMeta && inlineMeta.sessionless === undefined) {
+      const routeAuth = getPropertyValue(obj, 'auth')
+      const resolvedAuth =
+        routeAuth === true || routeAuth === false ? routeAuth : inheritedAuth
+      if (resolvedAuth === false) {
+        inlineMeta.sessionless = true
+      }
+    }
+  }
+
   // Lookup existing function metadata
   const fnMeta = resolveFunctionMeta(state, funcName)
   if (!fnMeta) {

package/src/add/add-mcp-prompt.ts

@@ -45,7 +45,7 @@ export const addMCPPrompt: AddWiring = (
 
     const nameValue = getPropertyValue(obj, 'name') as string | null
     const { disabled, tags, summary, description, errors } =
-      getCommonWireMetaData(obj, 'MCP prompt', nameValue, logger)
+      getCommonWireMetaData(obj, 'MCP prompt', nameValue, logger, checker)
 
     if (disabled) return
 

package/src/add/add-mcp-resource.ts

@@ -46,7 +46,7 @@ export const addMCPResource: AddWiring = (
     const uriValue = getPropertyValue(obj, 'uri') as string | null
     const titleValue = getPropertyValue(obj, 'title') as string | null
     const { disabled, tags, summary, description, errors } =
-      getCommonWireMetaData(obj, 'MCP resource', uriValue, logger)
+      getCommonWireMetaData(obj, 'MCP resource', uriValue, logger, checker)
 
     if (disabled) return
 

package/src/add/add-queue-worker.ts

@@ -37,7 +37,7 @@ export const addQueueWorker: AddWiring = (logger, node, checker, state) => {
 
     const name = getPropertyValue(obj, 'name') as string | null
     const { disabled, tags, summary, description, errors } =
-      getCommonWireMetaData(obj, 'Queue worker', name, logger)
+      getCommonWireMetaData(obj, 'Queue worker', name, logger, checker)
 
     if (disabled) return
 

package/src/add/add-schedule.ts

@@ -44,7 +44,7 @@ export const addSchedule: AddWiring = (
     const nameValue = getPropertyValue(obj, 'name') as string | null
     const scheduleValue = getPropertyValue(obj, 'schedule') as string | null
     const { disabled, tags, summary, description, errors } =
-      getCommonWireMetaData(obj, 'Scheduler', nameValue, logger)
+      getCommonWireMetaData(obj, 'Scheduler', nameValue, logger, checker)
 
     if (disabled) return
 

package/src/add/add-trigger.ts

@@ -55,7 +55,7 @@ const addWireTrigger: (
 
   const nameValue = getPropertyValue(obj, 'name') as string | null
   const { disabled, tags, summary, description, errors } =
-    getCommonWireMetaData(obj, 'Trigger', nameValue, logger)
+    getCommonWireMetaData(obj, 'Trigger', nameValue, logger, checker)
 
   if (disabled) return