@pikku/core 0.12.71 → 0.12.74

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

@@ -6,11 +6,6 @@ import type {
 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>
@@ -18,10 +13,6 @@ export type AddonInstance = {
   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>
@@ -46,10 +37,6 @@ const aliasSecretService = (
   }
 }
 
-/**
- * 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>
@@ -78,10 +65,6 @@ const aliasVariablesService = (
   }
 }
 
-/**
- * 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
@@ -91,18 +74,6 @@ const findAddonNamespaceForPackage = (packageName: string): string | null => {
   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,
@@ -114,8 +85,6 @@ const wrapWorkflowServiceForPackage = <T extends object>(
         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}`
@@ -129,23 +98,11 @@ const wrapWorkflowServiceForPackage = <T extends object>(
   })
 }
 
-/**
- * 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')
@@ -155,13 +112,9 @@ export const getOrCreatePackageSingletonServices = async (
 
   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 = {
@@ -182,20 +135,16 @@ export const getOrCreatePackageSingletonServices = async (
     }
   }
 
-  // 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'
@@ -212,11 +161,6 @@ export const getOrCreatePackageSingletonServices = async (
   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

package/src/wirings/rpc/addon-scopes.test.ts

@@ -0,0 +1,225 @@
+import { beforeEach, describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import { MissingScopeError } from '../../errors/errors.js'
+import { ContextAwareRPCService } from './rpc-runner.js'
+import { wireAddon } from './wire-addon.js'
+
+const ADDON_PACKAGE = '@addon/console'
+
+const createServices = () =>
+  ({
+    logger: {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+    },
+  }) as never
+
+const registerAddonFunction = (
+  funcName: string,
+  { scopes }: { scopes?: string[] } = {}
+) => {
+  addFunction(funcName, { func: async () => 'ok' } as never, ADDON_PACKAGE)
+  pikkuState(ADDON_PACKAGE, 'function', 'meta')[funcName] = {
+    name: funcName,
+    sessionless: true,
+    permissions: [],
+    scopes,
+  } as never
+}
+
+const session = (scopes?: string[]) => ({ userId: 'u1', scopes }) as never
+
+/** How an addon function is reached over RPC: `namespace:function`. */
+const callOverRPC = (namespacedFunction: string, sessionScopes?: string[]) => {
+  const service = new ContextAwareRPCService(
+    createServices(),
+    { session: session(sessionScopes) } as never,
+    { requiresAuth: false }
+  )
+  return service.rpc(namespacedFunction, {})
+}
+
+/**
+ * How an addon function is reached over a directly-wired HTTP route: the
+ * inspector records the addon package on the route meta and the HTTP runner
+ * hands it to `runPikkuFunc`, never passing through namespace resolution.
+ */
+const callOverDirectWiring = (
+  funcName: string,
+  sessionScopes?: string[],
+  wireType: string = 'http',
+  wireId: string = 'get:/console/thing'
+) =>
+  runPikkuFunc(wireType as never, wireId, funcName, {
+    singletonServices: createServices(),
+    data: () => ({}),
+    auth: false,
+    packageName: ADDON_PACKAGE,
+    wire: { session: session(sessionScopes) } as never,
+  })
+
+beforeEach(() => {
+  resetPikkuState()
+  pikkuState(null, 'package', 'singletonServices', createServices())
+})
+
+describe('wireAddon scopes', () => {
+  test('denies a session lacking the addon scope', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, scopes: ['admin'] })
+    registerAddonFunction('credentialGet')
+
+    await assert.rejects(
+      () => callOverRPC('console:credentialGet', ['billing:read']),
+      MissingScopeError
+    )
+  })
+
+  test('allows a session holding the addon scope', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, scopes: ['admin'] })
+    registerAddonFunction('credentialGet')
+
+    assert.equal(await callOverRPC('console:credentialGet', ['admin']), 'ok')
+  })
+
+  test('denies a session with no scopes at all', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, scopes: ['admin'] })
+    registerAddonFunction('credentialGet')
+
+    await assert.rejects(
+      () => callOverRPC('console:credentialGet'),
+      MissingScopeError
+    )
+  })
+
+  test('unions addon scopes with the function’s own scopes', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, scopes: ['admin'] })
+    registerAddonFunction('installAddon', { scopes: ['packages:install'] })
+
+    await assert.rejects(
+      () => callOverRPC('console:installAddon', ['admin']),
+      MissingScopeError
+    )
+    await assert.rejects(
+      () => callOverRPC('console:installAddon', ['packages:install']),
+      MissingScopeError
+    )
+    assert.equal(
+      await callOverRPC('console:installAddon', ['admin', 'packages:install']),
+      'ok'
+    )
+  })
+
+  test('satisfies an addon scope through the scope hierarchy', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, scopes: ['admin'] })
+    registerAddonFunction('credentialGet')
+
+    assert.equal(await callOverRPC('console:credentialGet', ['admin:*']), 'ok')
+    assert.equal(await callOverRPC('console:credentialGet', ['*']), 'ok')
+  })
+
+  test('leaves an addon wired without scopes ungated', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE })
+    registerAddonFunction('credentialGet')
+
+    assert.equal(await callOverRPC('console:credentialGet', []), 'ok')
+  })
+
+  test('leaves the function’s own scopes intact on an unscoped addon', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE })
+    registerAddonFunction('installAddon', { scopes: ['packages:install'] })
+
+    await assert.rejects(
+      () => callOverRPC('console:installAddon', ['admin']),
+      MissingScopeError
+    )
+    assert.equal(
+      await callOverRPC('console:installAddon', ['packages:install']),
+      'ok'
+    )
+  })
+
+  test('gates a directly-wired route into the addon package', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, scopes: ['admin'] })
+    registerAddonFunction('streamWorkflowRun')
+
+    await assert.rejects(
+      () => callOverDirectWiring('streamWorkflowRun', ['billing:read']),
+      MissingScopeError
+    )
+    assert.equal(
+      await callOverDirectWiring('streamWorkflowRun', ['admin']),
+      'ok'
+    )
+  })
+
+  test('gates a directly-wired route when the package is wired under several namespaces', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, scopes: ['admin'] })
+    wireAddon({ name: 'consoleReadonly', package: ADDON_PACKAGE })
+    registerAddonFunction('streamWorkflowRun')
+
+    await assert.rejects(
+      () => callOverDirectWiring('streamWorkflowRun', []),
+      MissingScopeError
+    )
+  })
+
+  test('leaves a directly-wired route into an unscoped addon package ungated', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE })
+    registerAddonFunction('streamWorkflowRun')
+
+    assert.equal(await callOverDirectWiring('streamWorkflowRun', []), 'ok')
+  })
+
+  test('gates every wiring kind, not just http', async () => {
+    // The inspector writes the addon package onto all of these, and each
+    // runner calls runPikkuFunc without ever resolving a namespace.
+    const wireTypes = [
+      'http',
+      'channel',
+      'queue',
+      'scheduler',
+      'cli',
+      'mcp',
+      'trigger',
+      'gateway',
+    ]
+
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, scopes: ['admin'] })
+    registerAddonFunction('streamWorkflowRun')
+
+    for (const wireType of wireTypes) {
+      await assert.rejects(
+        () =>
+          callOverDirectWiring(
+            'streamWorkflowRun',
+            ['billing:read'],
+            wireType,
+            `${wireType}:console`
+          ),
+        MissingScopeError,
+        `${wireType} did not gate on the addon scope`
+      )
+      assert.equal(
+        await callOverDirectWiring(
+          'streamWorkflowRun',
+          ['admin'],
+          wireType,
+          `${wireType}:console`
+        ),
+        'ok',
+        `${wireType} rejected a session holding the addon scope`
+      )
+    }
+  })
+
+  test('leaves a non-addon package untouched', async () => {
+    registerAddonFunction('streamWorkflowRun')
+
+    assert.equal(await callOverDirectWiring('streamWorkflowRun', []), 'ok')
+  })
+})

package/src/wirings/rpc/remote-addon-auth.ts

@@ -1,10 +1,6 @@
 import type { CoreServices, PikkuRawWire } from '../../types/core.types.js'
 import { PikkuError, addError } from '../../errors/error-handler.js'
 
-/**
- * How a `wireRemoteAddon` consumer supplies the token the hosted addon expects.
- * This is a CLIENT authenticating to a hosted library — not the trusted mesh.
- */
 export type RemoteAddonAuthBinding =
   | { credentialId: string }
   | { secretId: string }
@@ -15,7 +11,6 @@ export type RemoteAddonAuthBinding =
       ) => string | Promise<string>
     }
 
-/** The addon's auth was bound but the source produced no token — fail closed. */
 export class RemoteAddonAuthError extends PikkuError {
   public readonly namespace: string
   constructor(namespace: string, detail: string) {
@@ -28,13 +23,7 @@ addError(RemoteAddonAuthError, {
   message: 'Remote addon authentication could not be resolved.',
 })
 
-/**
- * Resolve the bearer token for a remote addon call from the consumer's bound
- * source. Returns `null` only when no auth is bound (a public surface).
- *
- * Security: the resolved token is never logged or traced; per-user credentials
- * are read via the wire (scoped to `pikkuUserId`); an empty result fails closed.
- */
+/** Returns `null` only when no auth is bound; an empty resolved token throws. */
 export async function resolveRemoteAddonToken(
   auth: RemoteAddonAuthBinding | undefined,
   services: CoreServices,
@@ -42,7 +31,6 @@ export async function resolveRemoteAddonToken(
   namespace: string
 ): Promise<string | null> {
   if (!auth) {
-    // No auth bound → the addon declares its remote surface public.
     return null
   }
 

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

@@ -259,6 +259,192 @@ describe('ContextAwareRPCService.rpc', () => {
   })
 })
 
+describe('RPCNotFoundError raised from inside a resolved function', () => {
+  test('a local function that throws RPCNotFoundError is not re-dispatched remotely', async () => {
+    const sideEffects: string[] = []
+    const remoteCalls: unknown[][] = []
+
+    pikkuState(null, 'rpc', 'meta').chargeCard = 'chargeCardFunc'
+    registerFunction('chargeCardFunc', async () => {
+      sideEffects.push('charged')
+      throw new RPCNotFoundError('doesNotExist')
+    })
+
+    const service = new ContextAwareRPCService(
+      createServices({
+        deploymentService: {
+          invoke: async (...args: unknown[]) => {
+            remoteCalls.push(args)
+            return { remote: true }
+          },
+        },
+      }),
+      {} as never,
+      {}
+    )
+
+    await assert.rejects(
+      () => service.rpc('chargeCard', { amount: 10 }),
+      (error: unknown) => {
+        assert.ok(error instanceof RPCNotFoundError)
+        assert.equal(error.rpcName, 'doesNotExist')
+        return true
+      }
+    )
+
+    assert.deepEqual(sideEffects, ['charged'])
+    assert.deepEqual(remoteCalls, [])
+  })
+
+  test('an addon function that throws RPCNotFoundError is not retried locally or remotely', async () => {
+    const sideEffects: string[] = []
+    const remoteCalls: unknown[][] = []
+
+    pikkuState(null, 'addons', 'packages').set('stripe', {
+      package: '@addon/stripe',
+    } as never)
+    registerFunction(
+      'createCharge',
+      async () => {
+        sideEffects.push('charged')
+        throw new RPCNotFoundError('doesNotExist')
+      },
+      { packageName: '@addon/stripe' }
+    )
+
+    const service = new ContextAwareRPCService(
+      createServices({
+        deploymentService: {
+          invoke: async (...args: unknown[]) => {
+            remoteCalls.push(args)
+            return { remote: true }
+          },
+        },
+      }),
+      {} as never,
+      {}
+    )
+
+    await assert.rejects(
+      () => service.rpc('stripe:createCharge', { amount: 10 }),
+      (error: unknown) => {
+        assert.ok(error instanceof RPCNotFoundError)
+        assert.equal(error.rpcName, 'doesNotExist')
+        return true
+      }
+    )
+
+    assert.deepEqual(sideEffects, ['charged'])
+    assert.deepEqual(remoteCalls, [])
+  })
+
+  test('rpcWithWire does not re-dispatch a local function that throws RPCNotFoundError', async () => {
+    const sideEffects: string[] = []
+    const remoteCalls: unknown[][] = []
+
+    pikkuState(null, 'rpc', 'meta').chargeCard = 'chargeCardFunc'
+    registerFunction('chargeCardFunc', async () => {
+      sideEffects.push('charged')
+      throw new RPCNotFoundError('doesNotExist')
+    })
+
+    const service = new ContextAwareRPCService(
+      createServices({
+        deploymentService: {
+          invoke: async (...args: unknown[]) => {
+            remoteCalls.push(args)
+            return { remote: true }
+          },
+        },
+      }),
+      {} as never,
+      {}
+    )
+
+    await assert.rejects(
+      () => service.rpcWithWire('chargeCard', { amount: 10 }, {} as never),
+      RPCNotFoundError
+    )
+
+    assert.deepEqual(sideEffects, ['charged'])
+    assert.deepEqual(remoteCalls, [])
+  })
+
+  test('a genuinely missing namespaced rpc still throws RPCNotFoundError', async () => {
+    pikkuState(null, 'addons', 'packages').set('stripe', {
+      package: '@addon/stripe',
+    } as never)
+
+    const service = new ContextAwareRPCService(
+      createServices(),
+      {} as never,
+      {}
+    )
+
+    await assert.rejects(
+      () => service.rpc('stripe:missingFunc', {}),
+      (error: unknown) => {
+        assert.ok(error instanceof RPCNotFoundError)
+        assert.equal(
+          error.message,
+          'RPC function not found: stripe:missingFunc'
+        )
+        return true
+      }
+    )
+  })
+
+  test('a missing namespaced rpc still reaches deploymentService when one is configured', async () => {
+    const remoteCalls: unknown[][] = []
+    pikkuState(null, 'addons', 'packages').set('stripe', {
+      package: '@addon/stripe',
+    } as never)
+
+    const service = new ContextAwareRPCService(
+      createServices({
+        deploymentService: {
+          invoke: async (...args: unknown[]) => {
+            remoteCalls.push(args)
+            return { remote: true }
+          },
+        },
+      }),
+      { traceId: 'trace-addon' } as never,
+      {}
+    )
+
+    const result = await service.rpc('stripe:missingFunc', { value: 3 })
+
+    assert.deepEqual(result, { remote: true })
+    assert.deepEqual(remoteCalls, [
+      ['stripe:missingFunc', { value: 3 }, undefined, 'trace-addon'],
+    ])
+  })
+
+  test('an unknown namespace still falls through to the local/remote lookup', async () => {
+    const remoteCalls: unknown[][] = []
+    const service = new ContextAwareRPCService(
+      createServices({
+        deploymentService: {
+          invoke: async (...args: unknown[]) => {
+            remoteCalls.push(args)
+            return { remote: true }
+          },
+        },
+      }),
+      { traceId: 'trace-ns' } as never,
+      {}
+    )
+
+    const result = await service.rpc('unknownNs:someFunc', { value: 1 })
+
+    assert.deepEqual(result, { remote: true })
+    assert.deepEqual(remoteCalls, [
+      ['unknownNs:someFunc', { value: 1 }, undefined, 'trace-ns'],
+    ])
+  })
+})
+
 describe('ContextAwareRPCService.rpcExposed', () => {
   test('resolves unversioned exposed rpc names through latest rpc metadata', async () => {
     pikkuState(null, 'rpc', 'meta').listCards = 'listCards@v2'
@@ -316,8 +502,6 @@ describe('ContextAwareRPCService.rpcExposed', () => {
   })
 
   test('a scenario step is not callable over the network, even if marked exposed', async () => {
-    // A step may drive a browser or assert against fixtures, so it is a step
-    // RPC — dispatched by name inside a run, never reachable from outside it.
     pikkuState(null, 'rpc', 'meta').seesAddonCard = 'seesAddonCard'
     registerFunction('seesAddonCard', async () => ({ visible: true }), {
       expose: true,