@pikku/core 0.12.79 → 0.12.82

package/src/wirings/channel/local/local-channel-runner.ts

@@ -206,14 +206,21 @@ export const runLocalChannel = async ({
 
       const { onMessage, onBinaryMessage } = processMessageHandlers(
         services,
-        channelConfig as any,
+        channelConfig,
         channelHandler,
         userSession
       )
       channelHandler.registerOnMessage(async (data) => {
         try {
           const result = await onMessage(data)
-          await channel.send(result)
+          // Guarded exactly as the connect path above is. A handler with nothing
+          // to say is normal — a gateway websocket's generated message handler
+          // always returns undefined — and sending that raised `send requires a
+          // non-empty message`, which surfaced as a channel that accepted a
+          // connection and then silently delivered nothing.
+          if (result !== undefined) {
+            await channel.send(result)
+          }
         } catch (e: any) {
           singletonServices.logger.error(e)
           const errorResponse = getErrorResponse(e)

package/src/wirings/channel/pikku-abstract-channel-handler.ts

@@ -34,7 +34,8 @@ export abstract class PikkuAbstractChannelHandler<
         setState: (s) => {
           channelState = s
         },
-        getState: () => channelState as any,
+        // knowledge: decisions/internals/channel-state-accessors-are-unsound-generics-that-every-implementation-asserts.md
+        getState: () => channelState as never,
         clearState: () => {
           channelState = undefined
         },

package/src/wirings/channel/serverless/serverless-channel-runner.ts

@@ -117,7 +117,8 @@ export const runChannelConnect = async ({
       channelName: channelConfig.name,
     })
     channel.setState = (state) => channelStore.setState(channelId, state)
-    channel.getState = () => channelStore.getState(channelId) as any
+    // knowledge: decisions/internals/channel-state-accessors-are-unsound-generics-that-every-implementation-asserts.md
+    channel.getState = () => channelStore.getState(channelId) as never
     channel.clearState = () => channelStore.clearState(channelId)
 
     const wire: PikkuRawWire = {
@@ -198,7 +199,8 @@ export const runChannelDisconnect = async ({
     channelName,
   })
   channel.setState = (state) => channelStore.setState(channelId, state)
-  channel.getState = () => channelStore.getState(channelId) as any
+  // knowledge: decisions/internals/channel-state-accessors-are-unsound-generics-that-every-implementation-asserts.md
+  channel.getState = () => channelStore.getState(channelId) as never
   channel.clearState = () => channelStore.clearState(channelId)
 
   const userSession = new PikkuSessionService<CoreUserSession>(
@@ -271,7 +273,8 @@ export const runChannelMessage = async (
     channelName,
   })
   channel.setState = (state) => channelStore.setState(channelId, state)
-  channel.getState = () => channelStore.getState(channelId) as any
+  // knowledge: decisions/internals/channel-state-accessors-are-unsound-generics-that-every-implementation-asserts.md
+  channel.getState = () => channelStore.getState(channelId) as never
   channel.clearState = () => channelStore.clearState(channelId)
 
   const userSession = new PikkuSessionService<CoreUserSession>(

package/src/wirings/cli/channel/cli-channel-runner.ts

@@ -90,7 +90,9 @@ export async function executeCLIViaChannel({
         return
       }
 
-      renderer(null as any, response, undefined)
+      // A CLI channel response is rendered off-process: there are no services
+      // to hand the renderer, and every CLI renderer ignores the argument.
+      renderer(null as never, response, undefined)
     }
 
     commandRoute.subscribe(commandId, responseHandler)

package/src/wirings/cli/channel/cli-raw-channel-runner.test.ts

@@ -103,6 +103,29 @@ describe('handleRawCLI', () => {
     assert.match(result.error!, /deploy plan is red/)
   })
 
+  test('masks the raw error message to the client in production', async () => {
+    const prior = process.env.NODE_ENV
+    process.env.NODE_ENV = 'production'
+    try {
+      wireTestCLI(() => {
+        throw new Error('connection to internal-db:5432 failed: bad password')
+      })
+
+      const result = await handleRawCLI({
+        programName: 'fabric',
+        args: ['deploy'],
+        singletonServices,
+      })
+
+      assert.equal(result.exitCode, 1)
+      assert.equal(result.error, 'Command failed')
+      assert.doesNotMatch(result.error!, /internal-db|password/)
+    } finally {
+      if (prior === undefined) delete process.env.NODE_ENV
+      else process.env.NODE_ENV = prior
+    }
+  })
+
   test('exits 0 on help and 1 on an unknown command', async () => {
     wireTestCLI(() => ({}))
 

package/src/wirings/cli/channel/cli-raw-channel-runner.ts

@@ -1,4 +1,5 @@
 import { pikkuState } from '../../../pikku-state.js'
+import { isProduction } from '../../../env.js'
 import type { CLIMeta } from '../cli.types.js'
 import { parseCLIArguments, generateCommandHelp } from '../command-parser.js'
 import { runCLICommand } from '../cli-runner.js'
@@ -132,6 +133,16 @@ export async function handleRawCLI({
     // A command can throw anything; `.message` off a string is undefined, and
     // the run would then exit 1 saying nothing at all.
     const message = e instanceof Error ? e.message : String(e)
-    return { error: message || 'Command failed', exitCode: 1, commandId }
+    // The raw message can carry internals (a stack, a DB error, a path). This
+    // runs over a channel that may be remote, so return a generic error in
+    // production and keep the detail server-side. Dev keeps the message inline.
+    singletonServices.logger.error?.(
+      `CLI channel command failed: ${message}`,
+      e
+    )
+    const clientError = isProduction()
+      ? 'Command failed'
+      : message || 'Command failed'
+    return { error: clientError, exitCode: 1, commandId }
   }
 }

package/src/wirings/cli/channel/cli-raw-client-runner.ts

@@ -32,7 +32,10 @@ export type CorePikkuCLIClientRender<Data> = (
 ) => void | Promise<void>
 
 /** The normal case once the server owns the command tree. */
-const defaultJSONRenderer: CorePikkuCLIClientRender<any> = (_services, data) => {
+const defaultJSONRenderer: CorePikkuCLIClientRender<any> = (
+  _services,
+  data
+) => {
   console.log(JSON.stringify(data))
 }
 

package/src/wirings/cli/channel/index.ts

@@ -3,13 +3,6 @@ export { handleRawCLI } from './cli-raw-channel-runner.js'
 export type { RawCLIFrame, RawCLIResult } from './cli-raw-channel-runner.js'
 export { executeRawCLIViaChannel } from './cli-raw-client-runner.js'
 export type {
-  ClientCLIRenderServices,
   CorePikkuCLIClientRender,
 } from './cli-raw-client-runner.js'
-export {
-  APPROVAL_FLAGS,
-  approverForMode,
-  createTerminalApprover,
-  takeApprovalFlags,
-} from './cli-approval.js'
 export type { ApprovalMode } from './cli-approval.js'

package/src/wirings/cli/cli-runner.test.ts

@@ -396,6 +396,74 @@ describe('CLI Runner', () => {
       const programs = pikkuState(null, 'cli', 'programs')
       assert.strictEqual(programs['nonexistent'], undefined)
     })
+
+    test('enforces command-level permissions declared on a CLI command', async () => {
+      let functionRan = false
+
+      pikkuState(null, 'cli', 'meta', {
+        programs: {
+          'sec-cli': {
+            program: 'sec-cli',
+            commands: {
+              secret: {
+                command: 'secret',
+                pikkuFuncId: 'secretFunc',
+                positionals: [],
+                options: {},
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+      pikkuState(null, 'function', 'meta', {
+        secretFunc: {
+          pikkuFuncId: 'secretFunc',
+          inputSchemaName: null,
+          outputSchemaName: null,
+          sessionless: true,
+        },
+      })
+
+      wireCLI({
+        program: 'sec-cli',
+        commands: {
+          // command.func is a function-config object, so unwrapFunc reads the
+          // inner func's auth/permissions and previously dropped the
+          // command-level ones — the branch this fix restores.
+          secret: {
+            func: {
+              func: async () => {
+                functionRan = true
+                return {}
+              },
+            },
+            // A permission that always denies.
+            permissions: { deny: async () => false },
+          } as any,
+        },
+      })
+
+      const result = await runCLICommand({
+        program: 'sec-cli',
+        commandPath: ['secret'],
+        data: {},
+        singletonServices,
+        createWireServices,
+      }).catch((error) => ({ success: false, error }))
+
+      assert.equal(
+        functionRan,
+        false,
+        'the function must not run when a declared permission denies'
+      )
+      assert.notEqual(
+        (result as any).success,
+        true,
+        'the command must not report success when permission is denied'
+      )
+    })
   })
 
   describe('pikkuCLIRender', () => {

package/src/wirings/cli/cli-runner.ts

@@ -16,6 +16,7 @@ import type {
   CLIMeta,
 } from './cli.types.js'
 import type {
+  CoreConfig,
   CoreSingletonServices,
   CoreServices,
   CreateWireServices,
@@ -24,7 +25,7 @@ import type {
   CreateSingletonServices,
 } from '../../types/core.types.js'
 import type { PikkuChannel } from '../channel/channel.types.js'
-import { unsupportedChannelRemote } from '../channel/channel-rpc.js'
+import { unsupportedChannelRemote } from '../channel/channel-rpc.types.js'
 import {
   PikkuSessionService,
   createMiddlewareSessionWireProps,
@@ -168,7 +169,24 @@ function registerCLICommands(
       }
     }
 
-    addFunction(funcName, unwrapFunc(command), currentMeta?.packageName)
+    // Merge the command-level auth/permissions into the registered config so
+    // they are actually enforced by the function runner. They were accepted by
+    // the types but dropped here, making a command's declared access control a
+    // silent no-op. Command-level wins over the handler's own, then falls back
+    // to it.
+    const unwrapped = unwrapFunc(command)
+    const commandAuth = typeof command === 'object' ? command.auth : undefined
+    const commandPermissions =
+      typeof command === 'object' ? command.permissions : undefined
+    addFunction(
+      funcName,
+      {
+        ...unwrapped,
+        auth: commandAuth ?? unwrapped.auth,
+        permissions: commandPermissions ?? unwrapped.permissions,
+      },
+      currentMeta?.packageName
+    )
 
     if (typeof command === 'object' && command.render) {
       if (programs[program]) {
@@ -321,7 +339,8 @@ export async function runCLICommand({
     setState: (s) => {
       cliState = s
     },
-    getState: () => cliState as any,
+    // knowledge: decisions/internals/channel-state-accessors-are-unsound-generics-that-every-implementation-asserts.md
+    getState: () => cliState as never,
     clearState: () => {
       cliState = undefined
     },
@@ -372,7 +391,8 @@ export async function runCLICommand({
     if (result !== undefined && !onOutput) {
       const commandRenderer = programData?.renderers[commandId]
       const jsonMode =
-        (data as any).json === true || (data as any).output === 'json'
+        (data as { json?: unknown; output?: unknown }).json === true ||
+        (data as { json?: unknown; output?: unknown }).output === 'json'
       const finalRenderer: CorePikkuCLIRender<any> | undefined =
         jsonMode && commandRenderer !== undefined
           ? defaultJSONRenderer
@@ -491,7 +511,7 @@ export async function executeCLI({
 
     const config = createConfig
       ? await createConfig(new LocalVariablesService(), data)
-      : ({} as any)
+      : ({} as CoreConfig)
 
     const singletonServices = await createSingletonServices(config)
     pikkuState(null, 'package', 'singletonServices', singletonServices)

package/src/wirings/cli/cli.types.ts

@@ -197,18 +197,6 @@ export type ValidateParameters<Params extends string, Input> =
     ? Params
     : never
 
-/**
- * Extract output type from a Pikku function config type
- */
-export type ExtractFunctionOutput<Func> =
-  Func extends CorePikkuFunctionConfig<infer FuncType, any, any>
-    ? FuncType extends
-        | CorePikkuFunction<any, infer Output, any, any, any>
-        | CorePikkuFunctionSessionless<any, infer Output, any, any, any>
-      ? Output
-      : never
-    : never
-
 /**
  * CLI command configuration that infers options from function input type.
  * This is a helper type for creating type-safe CLI commands.
@@ -290,33 +278,6 @@ export type CLICommandShorthand<
   >,
 > = PikkuFunctionConfig
 
-/**
- * Command definition (either full or shorthand)
- */
-export type CLICommandDefinition<
-  In,
-  Out,
-  PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any, any>
-  >,
-  PikkuPermission extends CorePikkuPermission<any, any, any>,
-  PikkuMiddleware extends CorePikkuMiddleware,
-  Options = any,
-  Subcommands extends Record<string, CoreCLICommandConfig<any, any, any>> =
-    Record<string, CoreCLICommandConfig<any, any, any>>,
-> =
-  | CoreCLICommand<
-      In,
-      Out,
-      PikkuFunctionConfig,
-      PikkuPermission,
-      PikkuMiddleware,
-      Options,
-      Subcommands
-    >
-  | CLICommandShorthand<In, Out, PikkuFunctionConfig>
-
 /**
  * CLI wiring configuration
  */

package/src/wirings/cli/command-parser.test.ts

@@ -710,5 +710,24 @@ describe('Command Parser', () => {
       assert.ok(result.errors.some((e) => e.includes('Unknown option: -x')))
       assert.deepStrictEqual(result.warnings, [])
     })
+    describe('short-flag cluster is bounded (DoS)', () => {
+      test('a huge short-flag cluster yields a single error, not one per char', () => {
+        const huge = '-' + 'a'.repeat(200_000)
+        const result = parseCLIArguments(
+          ['greet', 'Alice', huge],
+          'test-cli',
+          testMeta
+        )
+        const clusterErrors = result.errors.filter((e) =>
+          e.includes('Unknown option')
+        )
+        // Without the cap this would be ~200k errors (one per character).
+        assert.ok(
+          clusterErrors.length <= 2,
+          `expected the oversized cluster to collapse to a single error, got ${clusterErrors.length}`
+        )
+        assert.ok(result.errors.some((e) => e.includes('too long')))
+      })
+    })
   })
 })

package/src/wirings/cli/command-parser.ts

@@ -86,6 +86,15 @@ export interface ParsedCommand {
   warnings: string[]
 }
 
+/**
+ * A real short-flag cluster is a handful of characters (`-abc`). Anything past
+ * this is treated as a single malformed token rather than scanned per
+ * character — the parser runs over untrusted CLI-channel frames, and a
+ * multi-megabyte `-aaaa…` would otherwise be O(length) work that also pushed
+ * one error per character.
+ */
+const MAX_SHORT_FLAG_CLUSTER = 64
+
 export function parseCLIArguments(
   args: string[],
   programName: string,
@@ -238,6 +247,13 @@ export function parseCLIArguments(
         }
       }
     } else if (arg.startsWith('-') && arg.length > 1) {
+      if (arg.length > MAX_SHORT_FLAG_CLUSTER) {
+        result.errors.push(
+          `Unknown option: ${arg.slice(0, MAX_SHORT_FLAG_CLUSTER)}… (too long)`
+        )
+        currentIndex++
+        continue
+      }
       for (let i = 1; i < arg.length; i++) {
         const shortFlag = arg[i]
 
@@ -354,7 +370,7 @@ function parseOptionValue(value: string, optionDef?: CLIOption): any {
     return parseFloat(value)
   }
 
-  if (optionDef.choices && !optionDef.choices.includes(value as any)) {
+  if (optionDef.choices && !optionDef.choices.includes(value as never)) {
     // Deliberately not an error here — applyOptionDefaults reports bad choices.
     return value
   }

package/src/wirings/credential/index.ts

@@ -2,7 +2,6 @@ export { defineCredential } from './define-credential.js'
 export { validateAndBuildCredentialDefinitionsMeta } from './validate-credential-definitions.js'
 export type {
   CoreCredential,
-  CredentialDefinitionMeta,
   CredentialDefinitionsMeta,
   CredentialDefinitions,
 } from './credential.types.js'

package/src/wirings/gateway/gateway-channel-meta.test.ts

@@ -0,0 +1,44 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import { wireGateway } from './gateway-runner.js'
+
+const wireWebsocketGateway = (name: string) => {
+  resetPikkuState()
+  wireGateway({
+    name,
+    type: 'websocket',
+    route: `/${name}`,
+    adapter: { name: 'test', parse: () => null, send: async () => {} },
+    func: { func: async () => undefined },
+  } as any)
+  return pikkuState(null, 'channel', 'meta')[name]!
+}
+
+describe('a gateway-wired websocket channel writes complete channel meta', () => {
+  test('the fields every channel reader indexes are present', () => {
+    const meta = wireWebsocketGateway('chatGateway')
+
+    // channel-handler.ts indexes messageWirings without a guard, and the
+    // serverless and local runners read disconnect directly.
+    assert.deepEqual(
+      meta.messageWirings,
+      {},
+      'messageWirings must be an object — channel-handler indexes it unguarded'
+    )
+    assert.equal(meta.disconnect, null)
+    assert.equal(meta.input, null)
+  })
+
+  test('it is marked as gateway-wired', () => {
+    assert.equal(wireWebsocketGateway('flagged').gateway, true)
+  })
+
+  test('connect and message point at the generated handlers', () => {
+    const meta = wireWebsocketGateway('handlers')
+
+    assert.equal(meta.connect?.pikkuFuncId, 'gateway__handlers__connect')
+    assert.equal(meta.message?.pikkuFuncId, 'gateway__handlers__message')
+  })
+})

package/src/wirings/gateway/gateway-runner.ts

@@ -3,6 +3,7 @@ import { NotFoundError, UnauthorizedError } from '../../errors/errors.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { runMiddleware } from '../../middleware-runner.js'
 import { httpRouter } from '../http/routers/http-router.js'
+import type { CoreHTTPFunctionWiring } from '../http/http.types.js'
 import type {
   CoreGateway,
   GatewayAdapter,
@@ -50,7 +51,7 @@ const registerGatewayHandler = (config: CoreGateway): string => {
     outputSchemaName: declared?.outputSchemaName ?? null,
     sessionless: declared?.sessionless ?? true,
   }
-  addFunction(funcId, config.func as any)
+  addFunction(funcId, config.func)
   return funcId
 }
 
@@ -99,7 +100,7 @@ export const wireGateway = (config: CoreGateway): void => {
       break
     default:
       throw new Error(
-        `Unknown gateway type '${(config as any).type}' for gateway '${config.name}'`
+        `Unknown gateway type '${config.type}' for gateway '${config.name}'`
       )
   }
 }
@@ -118,7 +119,7 @@ const wireWebhookGateway = (config: CoreGateway): void => {
     func: createWebhookPostHandler(config),
   }
 
-  addFunction(postFuncId, postHandler as any)
+  addFunction(postFuncId, postHandler)
 
   if (!routes.has('post')) {
     routes.set('post', new Map())
@@ -128,7 +129,10 @@ const wireWebhookGateway = (config: CoreGateway): void => {
     route,
     func: postHandler,
     auth: false,
-  } as any)
+    // A gateway handler takes (services, data, wire) rather than a pikku
+    // function's shape, so it never matches CorePikkuFunctionConfig. It is only
+    // ever invoked through runPikkuFunc, which is what makes that safe.
+  } as unknown as CoreHTTPFunctionWiring<unknown, unknown, string>)
 
   // knowledge: decisions/internals/gateway-adapters-resolve-lazily-and-are-promise-cached.md
   if (typeof adapter === 'function' || adapter.verifyWebhook) {
@@ -139,7 +143,7 @@ const wireWebhookGateway = (config: CoreGateway): void => {
       func: createWebhookVerifyHandler(config),
     }
 
-    addFunction(verifyFuncId, verifyHandler as any)
+    addFunction(verifyFuncId, verifyHandler)
 
     if (!routes.has('get')) {
       routes.set('get', new Map())
@@ -151,7 +155,7 @@ const wireWebhookGateway = (config: CoreGateway): void => {
       auth: false,
       // knowledge: decisions/internals/gateway-webhook-challenges-echo-bytes-not-json.md
       returnsJSON: false,
-    } as any)
+    } as unknown as CoreHTTPFunctionWiring<unknown, unknown, string>)
   }
 
   httpRouter.reset()
@@ -187,17 +191,17 @@ const createWebhookPostHandler = (config: CoreGateway) => {
       platform: adapter.name,
       send: (msg: GatewayOutboundMessage) => adapter.send(parsed.senderId, msg),
     }
-    ;(wire as any).gateway = gateway
+    wire.gateway = gateway
 
     // Gateway middleware runs outside the gate so it can establish the session the gate checks.
     const invoke = async () => {
-      await bridgeMiddlewareSession(wire as any)
+      await bridgeMiddlewareSession(wire)
       return await runPikkuFunc('gateway', name, handlerFuncId, {
         singletonServices: services,
         data: () => parsed,
         auth: config.auth,
         inheritedMiddleware,
-        wire: wire as any,
+        wire,
       })
     }
 
@@ -275,9 +279,12 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
     name,
     route,
     gateway: true,
+    input: null,
     connect: { pikkuFuncId: connectFuncId },
+    disconnect: null,
     message: { pikkuFuncId: messageFuncId },
-  } as any
+    messageWirings: {},
+  }
 
   const userMiddleware = config.middleware as CorePikkuMiddleware[] | undefined
   const handlerFuncId = registerGatewayHandler(config)
@@ -287,7 +294,7 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
     auth: false,
     func: async (services: any, _data: unknown, wire: PikkuWire) => {
       const adapter = await resolveGatewayAdapter(config, services)
-      ;(wire as any).gateway = {
+      wire.gateway = {
         gatewayName: name,
         senderId: '',
         platform: adapter.name,
@@ -296,7 +303,7 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
         },
       } satisfies PikkuGateway
     },
-  } as any)
+  })
 
   addFunction(messageFuncId, {
     auth: false,
@@ -313,16 +320,16 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
           wire.channel?.send(msg)
         },
       }
-      ;(wire as any).gateway = gateway
+      wire.gateway = gateway
 
       const invoke = async () => {
-        await bridgeMiddlewareSession(wire as any)
+        await bridgeMiddlewareSession(wire)
         return await runPikkuFunc('gateway', name, handlerFuncId, {
           singletonServices: services,
           data: () => parsed,
           auth: config.auth,
           inheritedMiddleware,
-          wire: wire as any,
+          wire,
         })
       }
 
@@ -337,7 +344,7 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
         wire.channel?.send(result)
       }
     },
-  } as any)
+  })
 
   // knowledge: decisions/internals/gateway-wiring-is-a-meta-wiring-over-http-and-channels.md
   channels.set(name, {
@@ -346,7 +353,7 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
     auth: false,
     onConnect: { func: async () => {} },
     onMessage: { func: async () => {} },
-  } as any)
+  })
 
   httpRouter.reset()
 }
@@ -377,7 +384,7 @@ export const createListenerMessageHandler = (
       platform: adapter.name,
       send: (msg: GatewayOutboundMessage) => adapter.send(parsed.senderId, msg),
     }
-    ;(wire as any).gateway = gateway
+    wire.gateway = gateway
 
     const invoke = async () => {
       await bridgeMiddlewareSession(wire)
@@ -390,10 +397,11 @@ export const createListenerMessageHandler = (
       })
     }
 
+    // knowledge: decisions/internals/gateway-listener-middleware-runs-without-an-rpc-on-the-wire.md
     const result: any = userMiddleware?.length
       ? await runMiddleware(
           singletonServices,
-          wire as any,
+          wire as PikkuWire,
           userMiddleware,
           invoke
         )

package/src/wirings/gateway/index.ts

@@ -6,13 +6,10 @@ export {
 export type {
   GatewayAdapter,
   GatewayAdapterFactory,
-  GatewayAttachment,
   GatewayInboundMessage,
   GatewayOutboundMessage,
-  GatewayMeta,
   GatewaysMeta,
   GatewayTransportType,
   CoreGateway,
-  PikkuGateway,
   WebhookVerificationResult,
 } from './gateway.types.js'