@pikku/core 0.12.78 → 0.12.80

package/src/function/function-runner.ts

@@ -4,7 +4,7 @@ import {
   combineChannelMiddleware,
   wrapChannelWithMiddleware,
 } from '../wirings/channel/channel-middleware-runner.js'
-import { runPermissions } from '../permissions.js'
+import { runPermissions, type PermissionWire } from '../permissions.js'
 import { withoutSecrets } from '../services/secretless.js'
 import { pikkuState } from '../pikku-state.js'
 import {
@@ -248,6 +248,28 @@ export const runPikkuFunc = async <In = any, Out = any>(
     invocationWire,
     'rpc'
   )
+
+  // knowledge: decisions/internals/core-function-runner-restores-the-wire-fields-it-overwrites.md
+  const restoreInvocationWire = () => {
+    if (previousRpcDescriptor) {
+      Object.defineProperty(invocationWire, 'rpc', previousRpcDescriptor)
+    }
+    restoreField('functionId', previousFunctionId)
+    restoreField('audit', previousAudit)
+    restoreField('addonNamespace', previousAddonNamespace)
+  }
+
+  function restoreField<K extends 'functionId' | 'audit' | 'addonNamespace'>(
+    key: K,
+    previous: PikkuWire[K]
+  ) {
+    if (previous === undefined) {
+      delete invocationWire[key]
+    } else {
+      invocationWire[key] = previous
+    }
+  }
+
   invocationWire.functionId = resolvedFunctionId
   invocationWire.audit = resolvedAuditConfig
   // Track which addon instance is executing so intra-addon sibling calls
@@ -294,7 +316,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
       }
     }
 
-    if ((session as any)?.readonly && !funcMeta.readonly) {
+    if (session?.readonly && !funcMeta.readonly) {
       throw new ReadonlySessionError()
     }
 
@@ -347,7 +369,8 @@ export const runPikkuFunc = async <In = any, Out = any>(
             resolvedSingletonServices,
             'a permission'
           ) as CoreSingletonServices),
-      wire: invocationWire as any,
+      // knowledge: decisions/security/a-permission-gets-a-wire-it-cannot-reply-on.md
+      wire: invocationWire as PermissionWire,
       data: actualData,
       packageName,
     })
@@ -435,47 +458,13 @@ export const runPikkuFunc = async <In = any, Out = any>(
         executeFunction
       )) as Out
     } finally {
-      if (previousRpcDescriptor) {
-        Object.defineProperty(invocationWire, 'rpc', previousRpcDescriptor)
-      }
-      if (previousFunctionId === undefined) {
-        delete (invocationWire as any).functionId
-      } else {
-        invocationWire.functionId = previousFunctionId
-      }
-      if (previousAudit === undefined) {
-        delete (invocationWire as any).audit
-      } else {
-        invocationWire.audit = previousAudit
-      }
-      if (previousAddonNamespace === undefined) {
-        delete (invocationWire as any).addonNamespace
-      } else {
-        invocationWire.addonNamespace = previousAddonNamespace
-      }
+      restoreInvocationWire()
     }
   }
 
   try {
     return (await executeFunction()) as Out
   } finally {
-    if (previousRpcDescriptor) {
-      Object.defineProperty(invocationWire, 'rpc', previousRpcDescriptor)
-    }
-    if (previousFunctionId === undefined) {
-      delete (invocationWire as any).functionId
-    } else {
-      invocationWire.functionId = previousFunctionId
-    }
-    if (previousAudit === undefined) {
-      delete (invocationWire as any).audit
-    } else {
-      invocationWire.audit = previousAudit
-    }
-    if (previousAddonNamespace === undefined) {
-      delete (invocationWire as any).addonNamespace
-    } else {
-      invocationWire.addonNamespace = previousAddonNamespace
-    }
+    restoreInvocationWire()
   }
 }

package/src/function/functions.types.ts

@@ -14,12 +14,6 @@ import type { CoreNodeConfig } from '../wirings/node/node.types.js'
 import type { ScenarioSurface } from '../wirings/workflow/scenario-step.types.js'
 import type { Safe } from '../secret-value.js'
 
-/**
- * @deprecated Use StandardSchemaV1 from @standard-schema/spec instead.
- * This alias exists only for backward compatibility with generated code.
- */
-export type ZodLike<T = any> = StandardSchemaV1<T, T>
-
 export type CorePikkuFunction<
   In,
   Out,
@@ -141,6 +135,14 @@ export type CorePikkuAuthConfig<
   description?: string
 }
 
+/**
+ * Marks a permission produced by `pikkuAuth`, so agent tool filtering can tell a
+ * session check apart from an ordinary permission.
+ *
+ * knowledge: decisions/security/permission-auth-filtering-requires-live-permission-functions.md
+ */
+export type AuthBranded = { __pikkuAuth?: true }
+
 export const pikkuAuth = <
   Services extends CoreSecretlessSingletonServices =
     SecretlessServices<CoreServices>,
@@ -151,13 +153,17 @@ export const pikkuAuth = <
     | CorePikkuAuthConfig<Services, Session>
 ): CorePikkuPermission<any, Services, any> => {
   const fn = typeof auth === 'function' ? auth : auth.func
-  const wrapper = async (services: Services, _data: any, wire: any) => {
+  const wrapper: CorePikkuPermission<any, Services, any> & AuthBranded = async (
+    services: Services,
+    _data: any,
+    wire: any
+  ) => {
     const session = wire.session
     if (!session) return false
     return fn(services, session as Session)
   }
-  ;(wrapper as any).__pikkuAuth = true
-  return wrapper as any
+  wrapper.__pikkuAuth = true
+  return wrapper
 }
 
 export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =

package/src/handle-error.ts

@@ -33,7 +33,7 @@ export const handleHTTPError = (
         e.message !== 'An error occurred'
           ? e.message
           : errorResponse.message,
-      payload: clientFacing ? (e as any).payload : undefined,
+      payload: clientFacing ? (e as { payload?: unknown }).payload : undefined,
       errorId: traceId,
     })
 

package/src/index.ts

@@ -63,7 +63,6 @@ export type {
   CorePikkuPermissionFactory,
   CorePikkuApprovalDescription,
   CorePermissionGroup,
-  ZodLike,
 } from './function/functions.types.js'
 export {
   pikkuAuth,
@@ -71,7 +70,7 @@ export {
   pikkuPermissionFactory,
   pikkuApprovalDescription,
 } from './function/functions.types.js'
-export { addFunction, getAllFunctionNames } from './function/index.js'
+export { getAllFunctionNames } from './function/index.js'
 export type {
   ListInput,
   ListOutput,
@@ -79,6 +78,7 @@ export type {
   LeafFilter,
   LeafValue,
 } from './function/list.types.js'
+export { pikkuCLIRender } from './wirings/cli/cli-runner.js'
 export { PikkuRequest } from './pikku-request.js'
 export {
   getRelativeTimeOffsetFromNow,
@@ -90,7 +90,6 @@ export {
   isVersionedId,
   parseVersionedId,
 } from './version.js'
-export { runPikkuFunc } from './function/function-runner.js'
 export {
   AbandonedError,
   beginChanges,
@@ -98,20 +97,12 @@ export {
   runInAbortScope,
   type AbortScope,
 } from './function/abort-scope.js'
-export { runCLICommand, pikkuCLIRender } from './wirings/cli/cli-runner.js'
 export { fetch } from './wirings/http/http-runner.js'
-export {
-  runMCPTool,
-  runMCPResource,
-  runMCPPrompt,
-} from './wirings/mcp/mcp-runner.js'
 export type {
   MCPToolResponse,
   MCPResourceResponse,
   MCPPromptResponse,
 } from './wirings/mcp/mcp.types.js'
-export { runQueueJob } from './wirings/queue/queue-runner.js'
-export { runScheduledTask } from './wirings/scheduler/scheduler-runner.js'
 export {
   AIProviderAuthError,
   AIProviderNotConfiguredError,
@@ -254,12 +245,7 @@ export type {
   RemoteAddonAuth,
 } from './wirings/rpc/wire-remote-addon.js'
 export type { PikkuPackageState } from './types/state.types.js'
-export {
-  runMiddleware,
-  addTagMiddleware,
-  addTagMiddleware as addMiddleware,
-  addGlobalMiddleware,
-} from './middleware-runner.js'
+export { runMiddleware, addTagMiddleware } from './middleware-runner.js'
 export { addGlobalPermission, checkAuthPermissions } from './permissions.js'
 export { hasScopes, verifyScopes } from './scopes.js'
 export {
@@ -267,11 +253,6 @@ export {
   stopSingletonServices,
   pikkuServerLifecycle,
 } from './utils.js'
-export {
-  getSingletonServices,
-  getCreateWireServices,
-  setSingletonServices,
-} from './pikku-state.js'
 export { clearPikkuRuntimeState } from './test-utils.js'
 export {
   type ScheduledTaskInfo,

package/src/middleware/auth-cookie.test.ts

@@ -131,6 +131,56 @@ describe('authCookie middleware', () => {
     assert(setCookies[0].options.expires instanceof Date)
   })
 
+  test('clears the cookie on logout instead of re-minting a credential', async () => {
+    const SessionService = new PikkuSessionService<CoreUserSession>()
+    let encodeCalled = false
+    const jwtService = {
+      // A JWT of an absent session still decodes to a truthy {iat,exp} the
+      // runner accepts — so encode must never be called on logout.
+      encode: async () => {
+        encodeCalled = true
+        return 'reminted-jwt'
+      },
+      decode: async () => ({ userId: 'user123' }),
+    }
+
+    const middleware = authCookie({
+      name: 'session',
+      expiresIn: { value: 30, unit: 'day' },
+      options: { httpOnly: true },
+    })
+
+    const mockResponse = createMockHTTPResponse()
+
+    await middleware(
+      { jwt: jwtService, logger: createMockLogger() } as any,
+      {
+        ...createMiddlewareSessionWireProps(SessionService),
+        http: {
+          request: createMockHTTPRequest({ session: 'existing-jwt' }),
+          response: mockResponse,
+        },
+      } as any,
+      async () => {
+        // The logout handler clears the session.
+        SessionService.clear()
+      }
+    )
+
+    const setCookies = mockResponse.getCookies()
+    assert.equal(setCookies.length, 1, 'a clearing cookie must be written')
+    const cleared = setCookies[0]!
+    assert.equal(cleared.name, 'session')
+    assert.equal(cleared.value, '', 'the cookie value must be empty')
+    assert.equal(cleared.options.maxAge, 0)
+    assert.ok(
+      cleared.options.expires instanceof Date &&
+        cleared.options.expires.getTime() === 0,
+      'the cookie must expire at the epoch'
+    )
+    assert.equal(encodeCalled, false, 'must not sign an absent session')
+  })
+
   test('should not set cookie when session does not change', async () => {
     const mockUserSession: CoreUserSession = { userId: 'user789' }
     const SessionService = new PikkuSessionService<CoreUserSession>()

package/src/middleware/auth-cookie.ts

@@ -7,6 +7,27 @@ import { getRelativeTimeOffsetFromNow } from '../time-utils.js'
  * Reads a JWT session from a cookie, and re-issues the cookie after the
  * request whenever the session changed (e.g. after login).
  */
+/** Standard JWT registered claims — present on a token even with no session. */
+const JWT_REGISTERED_CLAIMS = new Set([
+  'iat',
+  'exp',
+  'nbf',
+  'iss',
+  'aud',
+  'sub',
+  'jti',
+])
+
+/**
+ * Whether a decoded payload carries an actual session, as opposed to being
+ * absent or a bare JWT envelope of `{ iat, exp }`. True only for a non-null
+ * object with at least one key that is not a registered JWT claim.
+ */
+const hasSessionIdentity = (session: unknown): boolean => {
+  if (!session || typeof session !== 'object') return false
+  return Object.keys(session).some((key) => !JWT_REGISTERED_CLAIMS.has(key))
+}
+
 export const authCookie = pikkuMiddlewareFactory<{
   name: string
   options: SerializeOptions
@@ -32,7 +53,12 @@ export const authCookie = pikkuMiddlewareFactory<{
       const cookieValue = http.request.cookie(name)
       if (cookieValue && jwtService) {
         const userSession = await jwtService.decode(cookieValue)
-        if (userSession) {
+        // Not just truthy: a JWT of an absent session still decodes to a
+        // `{ iat, exp }` object, which is truthy and which the function runner
+        // would accept as a session. Require at least one claim that is not a
+        // standard JWT timestamp, so an identity-less token is treated as no
+        // session rather than as an authenticated one.
+        if (userSession && hasSessionIdentity(userSession)) {
           setSession?.(userSession)
         }
       }
@@ -45,7 +71,17 @@ export const authCookie = pikkuMiddlewareFactory<{
 
       if (hasSessionChanged?.()) {
         const currentSession = await getSession?.()
-        if (jwtService) {
+        // Logout path: `clearSession()` marks the session changed while leaving
+        // it absent. Re-signing that into a fresh, unexpired cookie would hand
+        // the browser a credential on the way out — so clear the cookie instead
+        // of minting one, and never call `encode` with an absent session.
+        if (!hasSessionIdentity(currentSession)) {
+          http.response.cookie(name, '', {
+            ...mergedOptions,
+            expires: new Date(0),
+            maxAge: 0,
+          })
+        } else if (jwtService) {
           http.response.cookie(
             name,
             await jwtService.encode(expiresIn, currentSession),

package/src/middleware/cors.ts

@@ -72,7 +72,8 @@ export const cors = pikkuMiddlewareFactory<{
 
         if (request.method() === 'options') {
           response.header('Access-Control-Max-Age', String(maxAge))
-          response.status(204).json(undefined as any)
+          // 204 carries no body, and `json` has no no-content overload.
+          response.status(204).json(undefined as never)
           return
         }
 

package/src/middleware/index.ts

@@ -10,4 +10,4 @@ export {
   addGlobalMiddleware,
   runMiddleware,
 } from '../middleware-runner.js'
-export { addGlobalPermission, addTagPermission } from '../permissions.js'
+export { addGlobalPermission } from '../permissions.js'

package/src/middleware/remote-auth.test.ts

@@ -263,6 +263,49 @@ describe('pikkuRemoteAuthMiddleware', () => {
       )
     })
 
+    test('enforces the fn binding even when the path prefix varies in case', async () => {
+      // The router matches /remote/rpc/ case-insensitively, so /Remote/RPC/
+      // reaches the same handler. The fn-binding check must run for it too, or
+      // a token scoped to one function invokes any other by varying the case.
+      await assert.rejects(
+        () =>
+          pikkuRemoteAuthMiddleware(
+            {
+              secrets: createMockSecrets(TEST_SECRET),
+              jwt: createMockJWT({ aud: 'pikku-remote', fn: 'allowedFunc' }),
+            } as any,
+            {
+              http: {
+                request: createMockRequest(
+                  { authorization: 'Bearer valid-token' },
+                  '/Remote/RPC/otherFunc'
+                ),
+              },
+            } as any,
+            async () => {}
+          ),
+        (err: any) => err instanceof UnauthorizedError
+      )
+    })
+
+    test('requires authorization for a case-varied remote path when no secret is set', async () => {
+      // The no-secret branch must also treat /REMOTE/RPC/ as remote, or a
+      // misconfigured mesh silently serves it unauthenticated.
+      await assert.rejects(
+        () =>
+          pikkuRemoteAuthMiddleware(
+            { secrets: createMockSecrets(undefined) } as any,
+            {
+              http: {
+                request: createMockRequest({}, '/REMOTE/RPC/anyFunc'),
+              },
+            } as any,
+            async () => {}
+          ),
+        (err: any) => err instanceof UnauthorizedError
+      )
+    })
+
     test('should allow when token fn matches requested function', async () => {
       let nextCalled = false
       await pikkuRemoteAuthMiddleware(

package/src/middleware/remote-auth.ts

@@ -6,6 +6,18 @@ import {
   REMOTE_SESSION_INFO,
 } from '../crypto-utils.js'
 
+const REMOTE_RPC_PREFIX = '/remote/rpc/'
+
+/**
+ * Whether this request targets the remote-RPC surface. Compared case-insensitively
+ * because the router matches routes that way (path-to-regexp defaults to
+ * `sensitive: false`), so `/Remote/RPC/fn` reaches the same handler as
+ * `/remote/rpc/fn`. A case-sensitive check here let a case-varied path slip
+ * past the trust gate and the token's `fn` binding while still being dispatched.
+ */
+const isRemoteRpcPath = (path: string): boolean =>
+  path.toLowerCase().startsWith(REMOTE_RPC_PREFIX)
+
 export const pikkuRemoteAuthMiddleware = pikkuMiddleware(
   async ({ secrets, jwt }, { http, setSession }, next) => {
     if (!http?.request || !secrets) {
@@ -16,7 +28,7 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(
     try {
       secret = (await secrets.getSecret('PIKKU_REMOTE_SECRET')).reveal()
     } catch {
-      if (http.request.path().startsWith('/remote/rpc/')) {
+      if (isRemoteRpcPath(http.request.path())) {
         throw new UnauthorizedError()
       }
       return next()
@@ -51,9 +63,11 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(
       throw new UnauthorizedError()
     }
 
-    if (payload?.fn && http.request.path().startsWith('/remote/rpc/')) {
+    if (payload?.fn && isRemoteRpcPath(http.request.path())) {
+      // The prefix length is the same in any case, so slicing the raw path
+      // keeps the requested function name in its original case for the compare.
       const fn = decodeURIComponent(
-        http.request.path().slice('/remote/rpc/'.length)
+        http.request.path().slice(REMOTE_RPC_PREFIX.length)
       )
       if (fn && payload.fn !== fn) {
         throw new UnauthorizedError()

package/src/middleware-runner.ts

@@ -47,8 +47,10 @@ export const runMiddleware = async <
   let result: any
   const dispatch = async (index: number): Promise<any> => {
     if (sorted && index < sorted.length) {
-      return await sorted[index]!(services as any, wire, () =>
-        dispatch(index + 1)
+      return await sorted[index]!(
+        services as Parameters<Middleware>[0],
+        wire,
+        () => dispatch(index + 1)
       )
     } else if (main) {
       result = await main()

package/src/no-any-casts.test.ts

@@ -0,0 +1,57 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname, relative } from 'node:path'
+
+const srcRoot = dirname(fileURLToPath(import.meta.url))
+const thisFile = fileURLToPath(import.meta.url)
+
+/**
+ * `as any` in a cast position. The word boundary and the following delimiter
+ * keep prose such as "as any URL a browser can load" out of the match.
+ */
+const AS_ANY = /\bas any\b(?!\s+[A-Za-z])/
+
+const collectSourceFiles = (directory: string): string[] =>
+  readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const entryPath = join(directory, entry.name)
+    if (entry.isDirectory()) {
+      return entry.name === 'dist' ? [] : collectSourceFiles(entryPath)
+    }
+    return entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')
+      ? [entryPath]
+      : []
+  })
+
+describe('core asserts to named types, never to any', () => {
+  test('no non-test module casts through `as any`', () => {
+    const offenders = collectSourceFiles(srcRoot)
+      .filter((file) => file !== thisFile)
+      .flatMap((file) =>
+        readFileSync(file, 'utf-8')
+          .split('\n')
+          .flatMap((line, index) =>
+            AS_ANY.test(line)
+              ? [`${relative(srcRoot, file)}:${index + 1}  ${line.trim()}`]
+              : []
+          )
+      )
+
+    assert.deepEqual(
+      offenders,
+      [],
+      '`as any` discards the target type, so a wrong value passes as readily as ' +
+        'a right one. Assert to the type actually wanted — and if the narrowing ' +
+        'cannot be expressed, say why in a knowledge note and point at it:\n' +
+        offenders.join('\n')
+    )
+  })
+
+  test('the matcher finds a cast and ignores the prose that reads like one', () => {
+    // Guards the test above: a regex that matched nothing would pass forever.
+    assert.equal(AS_ANY.test('const x = y as any'), true)
+    assert.equal(AS_ANY.test('foo(bar as any)'), true)
+    assert.equal(AS_ANY.test('a picture, as any URL a browser can load'), false)
+  })
+})

package/src/permissions.test.ts

@@ -72,7 +72,9 @@ describe('runPermissions — function permissions (OR gate)', () => {
       run({ funcPermissions: { grp: [async () => true, async () => false] } }),
       { message: 'Permission denied' }
     )
-    await run({ funcPermissions: { grp: [async () => true, async () => true] } })
+    await run({
+      funcPermissions: { grp: [async () => true, async () => true] },
+    })
   })
 
   test('accepts a bare permission array as a single AND branch', async () => {

package/src/permissions.ts

@@ -3,7 +3,24 @@ import type {
   CoreUserSession,
   PikkuWire,
 } from './types/core.types.js'
+import type { PikkuRPC } from './wirings/rpc/rpc-types.js'
+
+/**
+ * The wire a permission function sees. `Out = never` denies it `channel.send`.
+ *
+ * knowledge: decisions/security/a-permission-gets-a-wire-it-cannot-reply-on.md
+ */
+export type PermissionWire = PikkuWire<
+  any,
+  never,
+  false,
+  any,
+  PikkuRPC,
+  never,
+  never
+>
 import type {
+  AuthBranded,
   CorePermissionGroup,
   CorePikkuPermission,
 } from './function/functions.types.js'
@@ -14,7 +31,7 @@ const verifyPermissions = async (
   permissions: CorePermissionGroup,
   services: CoreServices,
   data: any,
-  wire: PikkuWire<any, never, any, CoreUserSession, never, never, never>
+  wire: PermissionWire
 ): Promise<boolean> => {
   if (!permissions) {
     return true
@@ -34,7 +51,7 @@ const verifyPermissions = async (
         return true
       }
     } else {
-      if (await funcs(services, data, wire as any)) {
+      if (await funcs(services, data, wire)) {
         return true
       }
     }
@@ -42,7 +59,6 @@ const verifyPermissions = async (
   return false
 }
 
-
 const globalPermissionsCache: Record<
   string,
   readonly (CorePermissionGroup | CorePikkuPermission)[]
@@ -71,24 +87,6 @@ export const addGlobalPermission = (
   return permissions
 }
 
-/**
- * @deprecated Tag-level permissions were removed in #972 — permissions are now
- * function-scoped only (declare them on the function via `pikkuFunc({ permissions })`).
- * This throwing stub exists solely so the pinned bootstrap CLI (which still
- * generates an `addTagPermission` wrapper) can resolve the import at build time;
- * it is never called. Delete once `PIKKU_CLI_VERSION` in the CLI build is bumped
- * past the release that removes tag permissions.
- */
-export const addTagPermission = (
-  _tag: string,
-  _permissions: CorePermissionGroup | CorePikkuPermission[],
-  _packageName: string | null = null
-): never => {
-  throw new Error(
-    'addTagPermission was removed in #972 — tag-level permissions no longer exist. Declare permissions on the function definition instead: pikkuFunc({ permissions }).'
-  )
-}
-
 const bucket = (
   packageName: string | null
 ): (CorePermissionGroup | CorePikkuPermission)[] =>
@@ -141,7 +139,7 @@ export const runPermissions = async ({
 }: {
   funcPermissions?: CorePermissionGroup | CorePikkuPermission[]
   services: CoreServices
-  wire: PikkuWire<any, never, any, CoreUserSession, never, never, never>
+  wire: PermissionWire
   data: any
   packageName?: string | null
   /** What the non-global gate is called in debug logs, e.g. 'function', 'agent'. */
@@ -188,14 +186,14 @@ export const checkAuthPermissions = async (
 
   const collect = (perm: CorePermissionGroup | CorePikkuPermission) => {
     if (typeof perm === 'function') {
-      if ((perm as any).__pikkuAuth) {
+      if ((perm as AuthBranded).__pikkuAuth) {
         authPerms.push(perm)
       }
     } else if (perm && typeof perm === 'object') {
       for (const funcs of Object.values(perm)) {
         const arr = Array.isArray(funcs) ? funcs : [funcs]
         for (const fn of arr) {
-          if (typeof fn === 'function' && (fn as any).__pikkuAuth) {
+          if (typeof fn === 'function' && (fn as AuthBranded).__pikkuAuth) {
             authPerms.push(fn)
           }
         }