@pikku/core 0.12.63 → 0.12.66

package/src/wirings/gateway/gateway.types.ts

@@ -4,11 +4,7 @@ import type {
   CorePikkuMiddlewareGroup,
   CoreSingletonServices,
 } from '../../types/core.types.js'
-import type {
-  CorePikkuFunctionConfig,
-  CorePermissionGroup,
-  CorePikkuPermission,
-} from '../../function/functions.types.js'
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import type { PikkuHTTPRequest } from '../http/http.types.js'
 
 /**
@@ -124,7 +120,6 @@ export type GatewayTransportType = 'webhook' | 'websocket' | 'listener'
  */
 export type CoreGateway<
   PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>,
-  PikkuPermission extends CorePikkuPermission = CorePikkuPermission,
   PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware,
 > = Partial<
   Pick<CommonWireMeta, 'title' | 'summary' | 'description' | 'errors'>
@@ -143,11 +138,14 @@ export type CoreGateway<
   func: PikkuFunctionConfig
   /** Optional middleware chain (e.g., auth) */
   middleware?: CorePikkuMiddlewareGroup<any, any>
-  /** Optional permissions */
-  permissions?: CorePermissionGroup | PikkuPermission[]
   /** Optional tags for categorization */
   tags?: string[]
-  /** Whether authentication is required (default: true) */
+  /**
+   * Whether the handler requires a session. Left unset, the handler's own
+   * `auth` governs, and a gateway handler is sessionless by default — inbound
+   * gateway traffic is platform-authenticated by the adapter, not
+   * session-bearing. Set `true` to require a session for every message.
+   */
   auth?: boolean
 }
 

package/src/wirings/http/http-routes.ts

@@ -128,7 +128,6 @@ function processRouteMap(
  * - tags: Merges (parent + child)
  * - middleware: Merges (parent runs first)
  * - auth: Inner overrides outer
- * - permissions: Inner overrides outer
  */
 function mergeGroupConfig(
   parent: HTTPRoutesGroupConfig,
@@ -139,7 +138,6 @@ function mergeGroupConfig(
     tags: [...(parent.tags || []), ...(child.tags || [])],
     middleware: [...(parent.middleware || []), ...(child.middleware || [])],
     auth: child.auth ?? parent.auth,
-    permissions: child.permissions ?? parent.permissions,
   }
 }
 
@@ -162,7 +160,6 @@ function registerRoute(
       ...(groupConfig.middleware || []),
       ...(route.middleware || []),
     ],
-    permissions: route.permissions ?? groupConfig.permissions,
     contentType: route.contentType,
     timeout: route.timeout,
     headers: route.headers,

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

@@ -4,7 +4,6 @@ import { NotFoundError } from '../../errors/errors.js'
 import type { JSONValue, CorePikkuMiddleware } from '../../types/core.types.js'
 import {
   addHTTPMiddleware,
-  addHTTPPermission,
   createHTTPWire,
   fetch,
   fetchData,
@@ -253,23 +252,14 @@ describe('http-runner helpers', () => {
     } as any)
   })
 
-  test('addHTTPMiddleware and addHTTPPermission register route groups', () => {
+  test('addHTTPMiddleware registers a route middleware group', () => {
     const middleware = [sessionMiddleware]
-    const permissions = [async () => true]
 
     assert.strictEqual(addHTTPMiddleware('/api/*', middleware), middleware)
-    assert.strictEqual(
-      addHTTPPermission('/api/*', permissions as any),
-      permissions
-    )
     assert.strictEqual(
       pikkuState(null, 'middleware', 'httpGroup')['/api/*'],
       middleware
     )
-    assert.strictEqual(
-      pikkuState(null, 'permissions', 'httpGroup')['/api/*'],
-      permissions
-    )
   })
 
   test('addHTTPMiddleware composes repeated registrations for the same pattern', () => {

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

@@ -11,7 +11,6 @@ import type {
   CorePikkuFunction,
   CorePikkuFunctionSessionless,
   CorePikkuPermission,
-  CorePermissionGroup,
 } from '../../function/functions.types.js'
 import type {
   CoreUserSession,
@@ -106,42 +105,23 @@ export const addHTTPMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
 }
 
 /**
- * Registers HTTP permissions for a specific route pattern.
- *
- * This function registers permissions at runtime that will be applied to
- * HTTP routes matching the specified pattern.
- *
- * For tree-shaking benefits, wrap in a factory function:
- * `export const x = () => addHTTPPermission('pattern', [...])`
- *
- * @template PikkuPermission The permission type.
- * @param {string} pattern - Route pattern (e.g., '*' for all routes, '/api/*' for specific routes).
- * @param {CorePermissionGroup | CorePikkuPermission[]} permissions - Permissions for this route pattern.
- *
- * @returns {CorePermissionGroup | CorePikkuPermission[]} The permissions (for chaining/wrapping).
- *
- * @example
- * ```typescript
- * // Recommended: tree-shakeable
- * export const httpGlobalPermissions = () => addHTTPPermission('*', [
- *   authenticatedPermission,
- *   rateLimitPermission
- * ])
- *
- * // Also works: no tree-shaking
- * export const apiPermissions = addHTTPPermission('/api/*', [
- *   adminPermission
- * ])
- * ```
+ * @deprecated HTTP-route-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 `addHTTPPermission` 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
+ * HTTP-route permissions.
  */
-export const addHTTPPermission = <PikkuPermission extends CorePikkuPermission>(
-  pattern: string,
-  permissions: CorePermissionGroup | CorePikkuPermission[],
-  packageName: string | null = null
-): CorePermissionGroup | CorePikkuPermission[] => {
-  const httpGroups = pikkuState(packageName, 'permissions', 'httpGroup')
-  httpGroups[pattern] = permissions
-  return permissions
+export const addHTTPPermission = (
+  _pattern: string,
+  _permissions:
+    | Record<string, CorePikkuPermission | CorePikkuPermission[]>
+    | CorePikkuPermission[]
+): never => {
+  throw new Error(
+    'addHTTPPermission was removed in #972 — HTTP-route-level permissions no longer exist. Declare permissions on the function definition instead: pikkuFunc({ permissions }).'
+  )
 }
 
 /**
@@ -233,7 +213,6 @@ const getMatchingRoute = (requestType: string, requestPath: string) => {
       matchedPath,
       params: matchedPath.params,
       route,
-      permissions: route.permissions,
       meta: meta!,
     }
   }
@@ -432,8 +411,6 @@ const executeRoute = async (
         data,
         inheritedMiddleware: meta.middleware,
         wireMiddleware: route.middleware,
-        inheritedPermissions: meta.permissions,
-        wirePermissions: route.permissions,
         coerceDataFromSchema: options.coerceDataFromSchema,
         tags: route.tags,
         wire,

package/src/wirings/http/http.types.ts

@@ -8,7 +8,6 @@ import type {
   CorePikkuFunction,
   CorePikkuFunctionSessionless,
   CorePikkuPermission,
-  CorePermissionGroup,
   CorePikkuFunctionConfig,
 } from '../../function/functions.types.js'
 
@@ -127,8 +126,10 @@ export type CoreHTTPFunctionWiring<
   > = CorePikkuFunctionSessionless<In, Out>,
   PikkuPermission extends CorePikkuPermission<In, any, any> =
     CorePikkuPermission<In, any, any>,
-  PikkuMiddleware extends CorePikkuMiddleware<any, any> =
-    CorePikkuMiddleware<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
 > =
   | (CoreHTTPFunction & {
       route: R
@@ -138,7 +139,6 @@ export type CoreHTTPFunctionWiring<
         PikkuPermission,
         PikkuMiddleware
       >
-      permissions?: CorePermissionGroup<PikkuPermission>
       auth?: true
       middleware?: PikkuMiddleware[]
       sse?: undefined
@@ -151,7 +151,6 @@ export type CoreHTTPFunctionWiring<
         PikkuPermission,
         PikkuMiddleware
       >
-      permissions?: undefined
       auth?: false
       middleware?: PikkuMiddleware[]
       sse?: undefined
@@ -164,7 +163,6 @@ export type CoreHTTPFunctionWiring<
         PikkuPermission,
         PikkuMiddleware
       >
-      permissions?: CorePermissionGroup<PikkuPermission>
       auth?: true
       middleware?: PikkuMiddleware[]
       sse?: boolean
@@ -177,7 +175,6 @@ export type CoreHTTPFunctionWiring<
         PikkuPermission,
         PikkuMiddleware
       >
-      permissions?: undefined
       auth?: false
       middleware?: PikkuMiddleware[]
       sse?: boolean
@@ -190,7 +187,6 @@ export type CoreHTTPFunctionWiring<
         PikkuPermission,
         PikkuMiddleware
       >
-      permissions?: CorePermissionGroup<PikkuPermission>
       auth?: true
       middleware?: PikkuMiddleware[]
       query?: Array<keyof In>
@@ -204,7 +200,6 @@ export type CoreHTTPFunctionWiring<
         PikkuPermission,
         PikkuMiddleware
       >
-      permissions?: undefined
       auth?: false
       middleware?: PikkuMiddleware[]
       query?: Array<keyof In>
@@ -294,7 +289,7 @@ export type HTTPRouteConfig<
     | CorePikkuFunction<any, any, any, any, any>
     | CorePikkuFunctionSessionless<any, any, any, any, any>,
   PikkuPermission extends CorePikkuPermission<any, any, any> =
-    CorePikkuPermission<any>,
+    CorePikkuPermission<any, any, any>,
   PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
     any,
     any
@@ -305,9 +300,8 @@ export type HTTPRouteConfig<
   route: string
   func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>
 
-  // Auth & permissions
+  // Auth
   auth?: boolean
-  permissions?: CorePermissionGroup<PikkuPermission>
 
   // Middleware
   middleware?: PikkuMiddleware[]
@@ -321,7 +315,7 @@ export type HTTPRouteConfig<
  */
 export type HTTPRoutesGroupConfig<
   PikkuPermission extends CorePikkuPermission<any, any, any> =
-    CorePikkuPermission<any>,
+    CorePikkuPermission<any, any, any>,
   PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
     any,
     any
@@ -331,7 +325,6 @@ export type HTTPRoutesGroupConfig<
   tags?: string[]
   auth?: boolean
   middleware?: PikkuMiddleware[]
-  permissions?: CorePermissionGroup<PikkuPermission>
 }
 
 /**

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

@@ -252,8 +252,6 @@ async function runMCPPikkuFunc(
         data: () => request.params,
         inheritedMiddleware: meta?.middleware,
         wireMiddleware: mcp?.middleware,
-        inheritedPermissions: meta?.permissions,
-        wirePermissions: mcp?.permissions,
         tags: mcp?.tags,
         wire,
         sessionService: mcpSessionService,

package/src/wirings/mcp/mcp.types.ts

@@ -1,5 +1,4 @@
 import type {
-  CorePermissionGroup,
   CorePikkuFunctionConfig,
   CorePikkuFunctionSessionless,
   CorePikkuPermission,
@@ -7,7 +6,6 @@ import type {
 import type {
   CorePikkuMiddleware,
   MiddlewareMetadata,
-  PermissionMetadata,
 } from '../../types/core.types.js'
 
 /**
@@ -49,12 +47,11 @@ export type PikkuMCP<Tools extends string = any> = {
  */
 export type MCPResourceMeta = Record<
   string,
-  Omit<CoreMCPResource, 'func' | 'middleware' | 'permissions'> & {
+  Omit<CoreMCPResource, 'func' | 'middleware'> & {
     pikkuFuncId: string
     inputSchema: string | null
     outputSchema: string | null
     middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
-    permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
   }
 >
 
@@ -63,12 +60,11 @@ export type MCPResourceMeta = Record<
  */
 export type MCPToolMeta = Record<
   string,
-  Omit<CoreMCPTool, 'func' | 'middleware' | 'permissions'> & {
+  Omit<CoreMCPTool, 'func' | 'middleware'> & {
     pikkuFuncId: string
     inputSchema: string | null
     outputSchema: string | null
     middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
-    permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
   }
 >
 
@@ -77,7 +73,7 @@ export type MCPToolMeta = Record<
  */
 export type MCPPromptMeta = Record<
   string,
-  Omit<CoreMCPPrompt, 'func' | 'middleware' | 'permissions'> & {
+  Omit<CoreMCPPrompt, 'func' | 'middleware'> & {
     pikkuFuncId: string
     inputSchema: string | null
     outputSchema: string | null
@@ -87,7 +83,6 @@ export type MCPPromptMeta = Record<
       required: boolean
     }>
     middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
-    permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
   }
 >
 
@@ -112,7 +107,6 @@ export type CoreMCPResource<
   func: PikkuFunctionConfig
   tags?: string[]
   middleware?: PikkuMiddleware[]
-  permissions?: CorePermissionGroup<PikkuPermission>
 }
 
 /**
@@ -134,7 +128,6 @@ export type CoreMCPTool<
   tags?: string[]
   streaming?: boolean
   middleware?: PikkuMiddleware[]
-  permissions?: CorePermissionGroup<PikkuPermission>
 }
 
 /**
@@ -154,7 +147,6 @@ export type CoreMCPPrompt<
   func: PikkuFunctionConfig
   tags?: string[]
   middleware?: PikkuMiddleware[]
-  permissions?: CorePermissionGroup<PikkuPermission>
 }
 
 export type JsonRpcRequest = {

package/src/wirings/oauth2/index.ts

@@ -1,4 +1 @@
-export { OAuth2Client } from './oauth2-client.js'
-export { createOAuth2Handler } from './oauth2-routes.js'
-export type { CreateOAuth2HandlerOptions } from './oauth2-routes.js'
 export type { OAuth2AppCredential, OAuth2Token } from './oauth2.types.js'

package/src/wirings/rpc/addon-runner.ts

@@ -0,0 +1,233 @@
+import { pikkuState } from '../../pikku-state.js'
+import type {
+  CoreConfig,
+  CoreSingletonServices,
+} from '../../types/core.types.js'
+import type { SecretService } from '../../services/secret-service.js'
+import type { VariablesService } from '../../services/variables-service.js'
+
+/**
+ * A single wired addon instance: a namespace (wireAddon `name`) plus the
+ * per-instance name-aliases that remap the logical names the addon reads to
+ * the actual project secret/variable/credential names.
+ */
+export type AddonInstance = {
+  namespace: string
+  secretOverrides?: Record<string, string>
+  variableOverrides?: Record<string, string>
+  credentialOverrides?: Record<string, string>
+}
+
+/**
+ * Wrap a SecretService so that the logical secret names an addon reads are
+ * remapped to the actual project secret names via the instance's overrides.
+ */
+const aliasSecretService = (
+  secrets: SecretService,
+  overrides: Record<string, string>
+): SecretService => {
+  const map = (key: string) => overrides[key] ?? key
+  return {
+    getSecret: <T = string>(key: string) => secrets.getSecret<T>(map(key)),
+    hasSecret: (key: string) => secrets.hasSecret(map(key)),
+    setSecret: (key: string, value: unknown) =>
+      secrets.setSecret(map(key), value),
+    deleteSecret: (key: string) => secrets.deleteSecret(map(key)),
+    getSecrets: async (keys) => {
+      const result = await secrets.getSecrets(keys.map(map))
+      const out: Record<string, unknown> = {}
+      for (const logical of keys) {
+        const real = map(logical)
+        if (real in result)
+          out[logical] = (result as Record<string, unknown>)[real]
+      }
+      return out as never
+    },
+  }
+}
+
+/**
+ * Wrap a VariablesService so that the logical variable names an addon reads
+ * are remapped to the actual project variable names via the instance's overrides.
+ */
+const aliasVariablesService = (
+  variables: VariablesService,
+  overrides: Record<string, string>
+): VariablesService => {
+  const map = (name: string) => overrides[name] ?? name
+  return {
+    get: <T = string>(name: string) => variables.get<T>(map(name)),
+    getVariables: (names) => {
+      const result = variables.getVariables(names.map(map) as never)
+      const remap = (r: Record<string, unknown>) => {
+        const out: Record<string, unknown> = {}
+        for (const logical of names) {
+          const real = map(logical)
+          if (real in r) out[logical] = r[real]
+        }
+        return out
+      }
+      return result instanceof Promise
+        ? (result.then(remap) as never)
+        : (remap(result as Record<string, unknown>) as never)
+    },
+    getAll: () => variables.getAll(),
+    set: (name: string, value: unknown) => variables.set(map(name), value),
+    has: (name: string) => variables.has(map(name)),
+    delete: (name: string) => variables.delete(map(name)),
+  }
+}
+
+/**
+ * Find the consumer-defined namespace (from wireAddon) for a given addon package.
+ * Returns null if the package isn't registered as an addon.
+ */
+const findAddonNamespaceForPackage = (packageName: string): string | null => {
+  const addons = pikkuState(null, 'addons', 'packages')
+  if (!addons) return null
+  for (const [namespace, cfg] of addons.entries()) {
+    if (cfg?.package === packageName) return namespace
+  }
+  return null
+}
+
+/**
+ * Wrap a workflow service so that bare workflow names passed from inside an
+ * addon function are auto-prefixed with the addon's consumer-facing namespace.
+ * Without this, `runToCompletion('myWorkflow')` from inside an addon misses
+ * the workflow registered under the addon's package scope and throws
+ * WorkflowNotFoundError — forcing addons to hardcode their consumer-defined
+ * namespace, which couples the addon to its caller.
+ *
+ * Explicit `'ns:name'` and bare names that already exist in root meta are
+ * unaffected; only bare names that would otherwise miss resolution get
+ * prefixed.
+ */
+const wrapWorkflowServiceForPackage = <T extends object>(
+  service: T,
+  packageName: string,
+  namespace: string | null
+): T => {
+  return new Proxy(service, {
+    get(target, prop, receiver) {
+      if (prop === 'startWorkflow' || prop === 'runToCompletion') {
+        const original = Reflect.get(target, prop, receiver) as Function
+        return function (this: any, name: string, ...rest: any[]) {
+          if (typeof name === 'string' && !name.includes(':')) {
+            // Prefer the known instance namespace; fall back to the
+            // package's sole namespace when invoked without an instance.
+            const ns = namespace ?? findAddonNamespaceForPackage(packageName)
+            if (ns) {
+              name = `${ns}:${name}`
+            }
+          }
+          return original.call(this, name, ...rest)
+        }
+      }
+      return Reflect.get(target, prop, receiver)
+    },
+  })
+}
+
+/**
+ * Get or create singleton services for an addon instance.
+ * Services are cached in pikkuState to avoid recreation on each call.
+ *
+ * @param packageName - The addon package name
+ * @param parentServices - The parent/caller's singleton services (used as base)
+ * @param addonInstance - The wired instance whose overrides shape the services
+ * @returns The instance's singleton services
+ */
+export const getOrCreatePackageSingletonServices = async (
+  packageName: string,
+  parentServices: CoreSingletonServices,
+  addonInstance?: AddonInstance
+): Promise<CoreSingletonServices> => {
+  // Cache per instance (namespace), not per package, so two instances of one
+  // package get separate services built with their own overrides. A bare
+  // package-scoped call (no instance) falls back to per-package caching.
+  const cacheKey = addonInstance?.namespace ?? packageName
+
+  const cachedServices = pikkuState(cacheKey, 'package', 'singletonServices')
+  if (cachedServices) {
+    return cachedServices
+  }
+
+  const factories = pikkuState(packageName, 'package', 'factories')
+  if (!factories || !factories.createSingletonServices) {
+    // No factories registered, use parent services
+    return parentServices
+  }
+
+  // Apply this instance's secret/variable overrides by aliasing the resolver
+  // services the addon reads from, so its createSingletonServices resolves
+  // instance-specific secrets/variables.
+  let existingServices = parentServices
+  if (addonInstance?.secretOverrides && parentServices.secrets) {
+    existingServices = {
+      ...existingServices,
+      secrets: aliasSecretService(
+        parentServices.secrets,
+        addonInstance.secretOverrides
+      ),
+    }
+  }
+  if (addonInstance?.variableOverrides && parentServices.variables) {
+    existingServices = {
+      ...existingServices,
+      variables: aliasVariablesService(
+        parentServices.variables,
+        addonInstance.variableOverrides
+      ),
+    }
+  }
+
+  // Create config for the package (use parent config if no factory)
+  let config: CoreConfig = existingServices.config
+  if (factories.createConfig) {
+    config = await factories.createConfig(existingServices.variables)
+  }
+
+  // Create singleton services for the package, passing parent services as existing
+  const packageServices = await factories.createSingletonServices(
+    config,
+    existingServices
+  )
+
+  // Wrap workflowService so that bare names used inside the addon's functions
+  // resolve to workflows registered under the addon's package scope.
+  if (
+    packageServices.workflowService &&
+    typeof packageServices.workflowService === 'object'
+  ) {
+    packageServices.workflowService = wrapWorkflowServiceForPackage(
+      packageServices.workflowService as object,
+      packageName,
+      addonInstance?.namespace ?? null
+    ) as typeof packageServices.workflowService
+  }
+
+  pikkuState(cacheKey, 'package', 'singletonServices', packageServices)
+
+  return packageServices
+}
+
+/**
+ * Build the addon instance descriptor (namespace + per-instance overrides) for
+ * a bare intra-addon call, using the namespace currently executing on the wire.
+ * Returns undefined unless that namespace maps to the resolved package.
+ */
+export const addonInstanceForNamespace = (
+  namespace: string | undefined,
+  expectedPackage: string
+): AddonInstance | undefined => {
+  if (!namespace) return undefined
+  const cfg = pikkuState(null, 'addons', 'packages').get(namespace)
+  if (!cfg || cfg.package !== expectedPackage) return undefined
+  return {
+    namespace,
+    secretOverrides: cfg.secretOverrides,
+    variableOverrides: cfg.variableOverrides,
+    credentialOverrides: cfg.credentialOverrides,
+  }
+}

package/src/wirings/rpc/index.ts

@@ -1,4 +1,20 @@
-export { PikkuRPCService, rpcService, RPCNotFoundError } from './rpc-runner.js'
+export {
+  PikkuRPCService,
+  rpcService,
+  RPCNotFoundError,
+  RemoteAddonConfigError,
+  RemoteAddonRequestError,
+} from './rpc-runner.js'
+export {
+  resolveRemoteAddonToken,
+  RemoteAddonAuthError,
+} from './remote-addon-auth.js'
+export type { RemoteAddonAuthBinding } from './remote-addon-auth.js'
 export type { PikkuRPC, RPCMeta } from './rpc-types.js'
 export { wireAddon } from './wire-addon.js'
 export type { WireAddonConfig } from './wire-addon.js'
+export { wireRemoteAddon } from './wire-remote-addon.js'
+export type {
+  WireRemoteAddonConfig,
+  RemoteAddonAuth,
+} from './wire-remote-addon.js'