@pikku/core 0.12.63 → 0.12.64

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'

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

@@ -0,0 +1,69 @@
+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 }
+  | {
+      resolve: (
+        services: CoreServices,
+        wire: PikkuRawWire
+      ) => 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) {
+    super(`Remote addon '${namespace}' auth could not be resolved: ${detail}`)
+    this.namespace = namespace
+  }
+}
+addError(RemoteAddonAuthError, {
+  status: 401,
+  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.
+ */
+export async function resolveRemoteAddonToken(
+  auth: RemoteAddonAuthBinding | undefined,
+  services: CoreServices,
+  wire: PikkuRawWire,
+  namespace: string
+): Promise<string | null> {
+  if (!auth) {
+    // No auth bound → the addon declares its remote surface public.
+    return null
+  }
+
+  let token: unknown
+  if ('credentialId' in auth) {
+    if (typeof wire.getCredential !== 'function') {
+      throw new RemoteAddonAuthError(
+        namespace,
+        `credentialId '${auth.credentialId}' requires a wire with credential access`
+      )
+    }
+    token = await wire.getCredential(auth.credentialId)
+  } else if ('secretId' in auth) {
+    token = await services.secrets.getSecret(auth.secretId)
+  } else if (typeof auth.resolve === 'function') {
+    token = await auth.resolve(services, wire)
+  }
+
+  if (token === null || token === undefined || token === '') {
+    throw new RemoteAddonAuthError(namespace, 'resolved token was empty')
+  }
+
+  return String(token)
+}

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

@@ -6,9 +6,13 @@ import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 import {
   ContextAwareRPCService,
   RPCNotFoundError,
+  RemoteAddonRequestError,
   resolveNamespace,
   rpcService,
 } from './rpc-runner.js'
+import { RemoteAddonAuthError } from './remote-addon-auth.js'
+import { wireAddon } from './wire-addon.js'
+import { wireRemoteAddon } from './wire-remote-addon.js'
 
 const createLogger = () => ({
   debug: () => {},
@@ -207,28 +211,12 @@ describe('ContextAwareRPCService.rpc', () => {
       { requiresAuth: true }
     )
 
-    const seenTags: string[][] = []
-    const addonTagGroup = pikkuState('@addon/stripe', 'permissions', 'tagGroup')
-    addonTagGroup['addon-tag'] = [
-      async (_services: any, _data: any, wire: any) => {
-        seenTags.push(['addon-tag', wire.wireType])
-        return true
-      },
-    ] as never
-    addonTagGroup['function-tag'] = [
-      async (_services: any, _data: any, wire: any) => {
-        seenTags.push(['function-tag', wire.wireType])
-        return true
-      },
-    ] as never
-
     const result = await service.rpc('stripe:createCharge', { amount: 10 })
 
     assert.deepEqual(result, {
       data: { amount: 10 },
       auth: 'http',
     })
-    assert.deepEqual(seenTags, [['addon-tag', 'http']])
   })
 
   test('falls back to deploymentService when rpc meta is missing', async () => {
@@ -492,6 +480,321 @@ describe('ContextAwareRPCService.remote', () => {
   })
 })
 
+describe('multi-instance addons', () => {
+  const createSecretService = () => ({
+    getSecret: async (key: string) => `secret:${key}`,
+    hasSecret: async () => true,
+    setSecret: async () => {},
+    deleteSecret: async () => {},
+    getSecrets: async () => ({}),
+  })
+
+  test('resolves per-instance secretOverrides and caches singletons per namespace', async () => {
+    const createdServices: any[] = []
+    pikkuState('@addon/slack', 'package', 'factories', {
+      createSingletonServices: async (_config: any, parent: any) => {
+        const token = await parent.secrets.getSecret('slackToken')
+        const svc = { logger: createLogger(), token }
+        createdServices.push(svc)
+        return svc
+      },
+    } as never)
+    registerFunction(
+      'send',
+      async (services: any) => ({ token: services.token }),
+      {
+        packageName: '@addon/slack',
+      }
+    )
+
+    wireAddon({
+      name: 'slack-marketing',
+      package: '@addon/slack',
+      secretOverrides: { slackToken: 'marketing_secret' },
+    })
+    wireAddon({
+      name: 'slack-support',
+      package: '@addon/slack',
+      secretOverrides: { slackToken: 'support_secret' },
+    })
+
+    const service = new ContextAwareRPCService(
+      createServices({ secrets: createSecretService() }),
+      {} as never,
+      { requiresAuth: false }
+    )
+
+    const marketing = await service.rpc('slack-marketing:send', {})
+    const support = await service.rpc('slack-support:send', {})
+
+    assert.deepEqual(marketing, { token: 'secret:marketing_secret' })
+    assert.deepEqual(support, { token: 'secret:support_secret' })
+    assert.equal(createdServices.length, 2)
+    assert.notEqual(createdServices[0], createdServices[1])
+  })
+
+  test('reuses the same per-namespace singleton across intra-addon sibling calls', async () => {
+    let factoryCalls = 0
+    pikkuState('@addon/slack', 'package', 'factories', {
+      createSingletonServices: async (_config: any, parent: any) => {
+        factoryCalls++
+        return {
+          logger: createLogger(),
+          token: await parent.secrets.getSecret('slackToken'),
+        }
+      },
+    } as never)
+
+    registerFunction(
+      'leaf',
+      async (services: any) => ({ token: services.token }),
+      {
+        packageName: '@addon/slack',
+      }
+    )
+    registerFunction(
+      'root',
+      async (_services: any, _data: any, wire: any) =>
+        wire.rpc.invoke('leaf', {}),
+      { packageName: '@addon/slack' }
+    )
+
+    wireAddon({
+      name: 'slack-marketing',
+      package: '@addon/slack',
+      secretOverrides: { slackToken: 'marketing_secret' },
+    })
+
+    const service = new ContextAwareRPCService(
+      createServices({ secrets: createSecretService() }),
+      {} as never,
+      { requiresAuth: false }
+    )
+
+    const result = await service.rpc('slack-marketing:root', {})
+
+    assert.deepEqual(result, { token: 'secret:marketing_secret' })
+    assert.equal(factoryCalls, 1)
+  })
+
+  test('resolves per-instance credentialOverrides via wire.getCredential', async () => {
+    pikkuState('@addon/slack', 'package', 'factories', {
+      createSingletonServices: async () => ({ logger: createLogger() }),
+    } as never)
+    registerFunction(
+      'whoami',
+      async (_services: any, _data: any, wire: any) => ({
+        cred: await wire.getCredential('slack'),
+      }),
+      { packageName: '@addon/slack' }
+    )
+
+    wireAddon({
+      name: 'slack-marketing',
+      package: '@addon/slack',
+      credentialOverrides: { slack: 'marketing_cred' },
+    })
+    wireAddon({
+      name: 'slack-support',
+      package: '@addon/slack',
+      credentialOverrides: { slack: 'support_cred' },
+    })
+
+    const credentialService = {
+      getAll: async (_userId: string) => ({
+        marketing_cred: { token: 'm' },
+        support_cred: { token: 's' },
+      }),
+    }
+
+    const service = new ContextAwareRPCService(
+      createServices({ credentialService }),
+      { pikkuUserId: 'user-1' } as never,
+      { requiresAuth: false }
+    )
+
+    const marketing = await service.rpc('slack-marketing:whoami', {})
+    const support = await service.rpc('slack-support:whoami', {})
+
+    assert.deepEqual(marketing, { cred: { token: 'm' } })
+    assert.deepEqual(support, { cred: { token: 's' } })
+  })
+})
+
+describe('wireRemoteAddon dispatch', () => {
+  const realFetch = globalThis.fetch
+  let calls: Array<{ url: string; init: any }> = []
+
+  const stubFetch = (
+    response: { status?: number; body?: unknown } = {}
+  ): void => {
+    const { status = 200, body = { ok: true } } = response
+    calls = []
+    globalThis.fetch = (async (url: any, init: any) => {
+      calls.push({ url: String(url), init })
+      return {
+        ok: status >= 200 && status < 300,
+        status,
+        text: async () => (body === undefined ? '' : JSON.stringify(body)),
+      }
+    }) as any
+  }
+
+  const restoreFetch = () => {
+    globalThis.fetch = realFetch
+  }
+
+  const secretService = () =>
+    ({
+      getSecret: async (key: string) => `secret-value-for-${key}`,
+      getSecrets: async () => ({}),
+      hasSecret: async () => true,
+      setSecret: async () => {},
+      deleteSecret: async () => {},
+    }) as never
+
+  test('POSTs to /remote/rpc/<fn> with { rpcName, data } and a platform bearer token', async () => {
+    stubFetch({ body: { echoed: 42 } })
+    try {
+      wireRemoteAddon({
+        name: 'registry',
+        package: '@pikkufabric/addon-registry',
+        serverUrl: 'https://api.example.com/',
+        auth: { secretId: 'REGISTRY_TOKEN' },
+      })
+
+      const service = new ContextAwareRPCService(
+        createServices({ secrets: secretService() }),
+        { traceId: 'trace-r' } as never,
+        {}
+      )
+
+      const result = await service.rpc('registry:getOpenApi', { name: 'stripe' })
+
+      assert.deepEqual(result, { echoed: 42 })
+      assert.equal(calls.length, 1)
+      assert.equal(
+        calls[0]!.url,
+        'https://api.example.com/remote/rpc/getOpenApi'
+      )
+      assert.equal(calls[0]!.init.method, 'POST')
+      assert.deepEqual(JSON.parse(calls[0]!.init.body), {
+        rpcName: 'getOpenApi',
+        data: { name: 'stripe' },
+      })
+      assert.equal(
+        calls[0]!.init.headers.authorization,
+        'Bearer secret-value-for-REGISTRY_TOKEN'
+      )
+      assert.equal(calls[0]!.init.headers['x-trace-id'], 'trace-r')
+    } finally {
+      restoreFetch()
+    }
+  })
+
+  test('resolves a per-user credential token via wire.getCredential', async () => {
+    stubFetch()
+    try {
+      wireRemoteAddon({
+        name: 'registry',
+        package: '@pikkufabric/addon-registry',
+        serverUrl: () => 'https://api.example.com',
+        auth: { credentialId: 'fabricRegistryToken' },
+      })
+
+      const service = new ContextAwareRPCService(
+        createServices(),
+        {
+          pikkuUserId: 'user-9',
+          getCredential: async (name: string) =>
+            name === 'fabricRegistryToken' ? 'user-token-9' : null,
+        } as never,
+        {}
+      )
+
+      await service.rpc('registry:getOpenApi', {})
+      assert.equal(
+        calls[0]!.init.headers.authorization,
+        'Bearer user-token-9'
+      )
+    } finally {
+      restoreFetch()
+    }
+  })
+
+  test('omits the Authorization header for a public (no auth) surface', async () => {
+    stubFetch()
+    try {
+      wireRemoteAddon({
+        name: 'registry',
+        package: '@pikkufabric/addon-registry',
+        serverUrl: 'https://api.example.com',
+      })
+
+      const service = new ContextAwareRPCService(
+        createServices(),
+        {} as never,
+        {}
+      )
+
+      await service.rpc('registry:listOpenApis', {})
+      assert.equal(calls[0]!.init.headers.authorization, undefined)
+    } finally {
+      restoreFetch()
+    }
+  })
+
+  test('fails closed when a bound credential resolves empty', async () => {
+    stubFetch()
+    try {
+      wireRemoteAddon({
+        name: 'registry',
+        package: '@pikkufabric/addon-registry',
+        serverUrl: 'https://api.example.com',
+        auth: { credentialId: 'fabricRegistryToken' },
+      })
+
+      const service = new ContextAwareRPCService(
+        createServices(),
+        { getCredential: async () => null } as never,
+        {}
+      )
+
+      await assert.rejects(
+        () => service.rpc('registry:getOpenApi', {}),
+        RemoteAddonAuthError
+      )
+      assert.equal(calls.length, 0)
+    } finally {
+      restoreFetch()
+    }
+  })
+
+  test('throws RemoteAddonRequestError on a non-2xx response', async () => {
+    stubFetch({ status: 503, body: { error: 'down' } })
+    try {
+      wireRemoteAddon({
+        name: 'registry',
+        package: '@pikkufabric/addon-registry',
+        serverUrl: 'https://api.example.com',
+      })
+
+      const service = new ContextAwareRPCService(
+        createServices(),
+        {} as never,
+        {}
+      )
+
+      await assert.rejects(
+        () => service.rpc('registry:getOpenApi', {}),
+        RemoteAddonRequestError
+      )
+    } finally {
+      restoreFetch()
+    }
+  })
+})
+
 describe('rpcService.getContextRPCService', () => {
   test('builds a typed rpc facade with depth and bound methods', async () => {
     pikkuState(null, 'rpc', 'meta').echo = 'echoFunc'