@pikku/core 0.12.80 → 0.12.83

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

@@ -4,6 +4,8 @@ import type {
   CoreSingletonServices,
 } from '../../types/core.types.js'
 import type { SecretService } from '../../services/secret-service.js'
+import { ScopedSecretService } from '../../services/scoped-secret-service.js'
+import { ScopedCredentialService } from '../../services/scoped-credential-service.js'
 import type { VariablesService } from '../../services/variables-service.js'
 
 export type AddonInstance = {
@@ -11,8 +13,32 @@ export type AddonInstance = {
   secretOverrides?: Record<string, string>
   variableOverrides?: Record<string, string>
   credentialOverrides?: Record<string, string>
+  /** Set by the consuming app: secrets it lends this instance, as the addon names them. */
+  secretGrants?: string[]
+  /** Set by the consuming app: credentials it lends this instance, as the addon names them. */
+  credentialGrants?: string[]
+  /** Set by the consuming app to opt this instance out of secret scoping. */
+  globalSecrets?: string
+  /** Set by the consuming app to opt this instance out of credential scoping. */
+  globalCredentials?: string
 }
 
+/**
+ * What the addon declared, plus what the host lent it. Scoping runs outside the
+ * aliaser, so every name here is the one the addon reads — which is why an
+ * override's *key* grants, and its value does not.
+ */
+const allowedNames = (
+  declared: string[] | null | undefined,
+  grants: string[] | undefined,
+  overrides: Record<string, string> | undefined
+): Set<string> =>
+  new Set([
+    ...(declared ?? []),
+    ...(grants ?? []),
+    ...Object.keys(overrides ?? {}),
+  ])
+
 const aliasSecretService = (
   secrets: SecretService,
   overrides: Record<string, string>
@@ -111,9 +137,6 @@ export const getOrCreatePackageSingletonServices = async (
   }
 
   const factories = pikkuState(packageName, 'package', 'factories')
-  if (!factories || !factories.createSingletonServices) {
-    return parentServices
-  }
 
   let existingServices = parentServices
   if (addonInstance?.secretOverrides && parentServices.secrets) {
@@ -134,6 +157,38 @@ export const getOrCreatePackageSingletonServices = async (
       ),
     }
   }
+  if (!addonInstance?.globalSecrets && existingServices.secrets) {
+    existingServices = {
+      ...existingServices,
+      secrets: new ScopedSecretService(
+        existingServices.secrets,
+        allowedNames(
+          pikkuState(packageName, 'package', 'declaredSecrets'),
+          addonInstance?.secretGrants,
+          addonInstance?.secretOverrides
+        )
+      ),
+    }
+  }
+  if (!addonInstance?.globalCredentials && existingServices.credentialService) {
+    existingServices = {
+      ...existingServices,
+      credentialService: new ScopedCredentialService(
+        existingServices.credentialService,
+        allowedNames(
+          Object.keys(
+            pikkuState(packageName, 'package', 'credentialsMeta') ?? {}
+          ),
+          addonInstance?.credentialGrants,
+          addonInstance?.credentialOverrides
+        )
+      ),
+    }
+  }
+
+  if (!factories || !factories.createSingletonServices) {
+    return existingServices
+  }
 
   let config: CoreConfig = existingServices.config
   if (factories.createConfig) {
@@ -173,5 +228,9 @@ export const addonInstanceForNamespace = (
     secretOverrides: cfg.secretOverrides,
     variableOverrides: cfg.variableOverrides,
     credentialOverrides: cfg.credentialOverrides,
+    secretGrants: cfg.secretGrants,
+    credentialGrants: cfg.credentialGrants,
+    globalSecrets: cfg.globalSecrets,
+    globalCredentials: cfg.globalCredentials,
   }
 }

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

@@ -0,0 +1,391 @@
+import { beforeEach, describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import { getOrCreatePackageSingletonServices } from './addon-runner.js'
+import { wireAddon } from './wire-addon.js'
+import type { SecretService } from '../../services/secret-service.js'
+import type { CredentialService } from '../../services/credential-service.js'
+import type { CoreSingletonServices } from '../../types/core.types.js'
+
+const ADDON_PACKAGE = '@addon/example'
+
+const createSecretService = (): SecretService =>
+  ({
+    getSecret: async (key: string) => `value-of-${key}` as never,
+    hasSecret: async () => true,
+    setSecret: async () => {},
+    deleteSecret: async () => {},
+    getSecrets: async (keys: string[]) =>
+      Object.fromEntries(keys.map((k) => [k, `value-of-${k}`])) as never,
+  }) as SecretService
+
+const createCredentialService = (): CredentialService =>
+  ({
+    get: async (name: string) => `credential-of-${name}`,
+    set: async () => {},
+    delete: async () => {},
+    has: async () => true,
+    getAll: async () => ({ slack: 'a', stripe: 'b' }),
+    getUsersWithCredential: async () => ['user-1'],
+    getAllUsers: async () => ['user-1'],
+  }) as unknown as CredentialService
+
+const createParentServices = () =>
+  ({
+    config: {},
+    logger: {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+    },
+    secrets: createSecretService(),
+    credentialService: createCredentialService(),
+  }) as unknown as CoreSingletonServices
+
+/**
+ * Registers an addon package whose singleton factory hands back whatever
+ * secrets service the host decided it should see.
+ */
+const registerAddon = (
+  declaredSecrets: string[] | null,
+  declaredCredentials?: string[]
+) => {
+  pikkuState(ADDON_PACKAGE, 'package', 'factories', {
+    createSingletonServices: (async (_config: unknown, parent: any) => ({
+      ...parent,
+      secretsSeenByAddon: parent.secrets,
+      credentialsSeenByAddon: parent.credentialService,
+    })) as never,
+  })
+  if (declaredSecrets) {
+    pikkuState(ADDON_PACKAGE, 'package', 'declaredSecrets', declaredSecrets)
+  }
+  if (declaredCredentials) {
+    pikkuState(
+      ADDON_PACKAGE,
+      'package',
+      'credentialsMeta',
+      Object.fromEntries(
+        declaredCredentials.map((name) => [
+          name,
+          { name, displayName: name, type: 'singleton' },
+        ])
+      )
+    )
+  }
+}
+
+const servicesHandedToAddon = async (namespace: string) =>
+  (await getOrCreatePackageSingletonServices(
+    ADDON_PACKAGE,
+    createParentServices(),
+    pikkuState(null, 'addons', 'packages').get(namespace) as never
+  )) as any
+
+const secretsHandedToAddon = async (namespace: string) =>
+  (await servicesHandedToAddon(namespace)).secretsSeenByAddon as SecretService
+
+const credentialsHandedToAddon = async (namespace: string) =>
+  (await servicesHandedToAddon(namespace))
+    .credentialsSeenByAddon as CredentialService
+
+describe('addon secrets are scoped to what the addon declared', () => {
+  beforeEach(() => {
+    resetPikkuState()
+  })
+
+  test('a declared secret is readable', async () => {
+    registerAddon(['ADDON_KEY'])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    assert.equal(await secrets.getSecret('ADDON_KEY'), 'value-of-ADDON_KEY')
+  })
+
+  test('an undeclared secret is denied', async () => {
+    registerAddon(['ADDON_KEY'])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    await assert.rejects(
+      () => secrets.getSecret('SOMEONE_ELSES_KEY'),
+      /denied/i
+    )
+  })
+
+  test('a scoped addon cannot write secrets', async () => {
+    registerAddon(['ADDON_KEY'])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    await assert.rejects(() => secrets.setSecret('ADDON_KEY', 'x'))
+  })
+
+  test('an addon that declares nothing is scoped to nothing', async () => {
+    registerAddon([])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    await assert.rejects(() => secrets.getSecret('ADDON_KEY'), /denied/i)
+  })
+
+  test('globalSecrets, set by the host, hands over the whole service', async () => {
+    registerAddon(['ADDON_KEY'])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      globalSecrets: 'administers secrets named by the operator at runtime',
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    assert.equal(
+      await secrets.getSecret('SOMEONE_ELSES_KEY'),
+      'value-of-SOMEONE_ELSES_KEY'
+    )
+    await assert.doesNotReject(() => secrets.setSecret('ADDON_KEY', 'x'))
+  })
+
+  test('an addon with no singleton factory is still scoped', async () => {
+    pikkuState(ADDON_PACKAGE, 'package', 'declaredSecrets', ['ADDON_KEY'])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+    })
+
+    const services = await getOrCreatePackageSingletonServices(
+      ADDON_PACKAGE,
+      createParentServices(),
+      pikkuState(null, 'addons', 'packages').get('example') as never
+    )
+
+    assert.equal(
+      await services.secrets.getSecret('ADDON_KEY'),
+      'value-of-ADDON_KEY'
+    )
+    await assert.rejects(
+      () => services.secrets.getSecret('SOMEONE_ELSES_KEY'),
+      /denied/i
+    )
+  })
+
+  test('scoping applies to the key the addon asks for, not the aliased one', async () => {
+    registerAddon(['ADDON_KEY'])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretOverrides: { ADDON_KEY: 'PROD_ADDON_KEY' },
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    assert.equal(
+      await secrets.getSecret('ADDON_KEY'),
+      'value-of-PROD_ADDON_KEY'
+    )
+    await assert.rejects(() => secrets.getSecret('PROD_ADDON_KEY'), /denied/i)
+  })
+})
+
+describe('addon credentials are scoped to what the addon declared', () => {
+  beforeEach(() => {
+    resetPikkuState()
+  })
+
+  test('a declared credential is reachable', async () => {
+    registerAddon(['ADDON_KEY'], ['slack'])
+    wireAddon({ name: 'example', package: ADDON_PACKAGE })
+
+    const credentials = await credentialsHandedToAddon('example')
+    assert.equal(await credentials.get('slack'), 'credential-of-slack')
+  })
+
+  test('an undeclared credential is denied', async () => {
+    registerAddon(['ADDON_KEY'], ['slack'])
+    wireAddon({ name: 'example', package: ADDON_PACKAGE })
+
+    const credentials = await credentialsHandedToAddon('example')
+    await assert.rejects(() => credentials.get('stripe'), /denied/i)
+  })
+
+  test('a scoped addon cannot enumerate the app users', async () => {
+    registerAddon(['ADDON_KEY'], ['slack'])
+    wireAddon({ name: 'example', package: ADDON_PACKAGE })
+
+    const credentials = await credentialsHandedToAddon('example')
+    await assert.rejects(() => credentials.getAllUsers(), /denied/i)
+  })
+
+  test('an addon with no singleton factory is still scoped', async () => {
+    pikkuState(ADDON_PACKAGE, 'package', 'credentialsMeta', {
+      slack: { name: 'slack', displayName: 'slack', type: 'singleton' },
+    } as never)
+    wireAddon({ name: 'example', package: ADDON_PACKAGE })
+
+    const services = await getOrCreatePackageSingletonServices(
+      ADDON_PACKAGE,
+      createParentServices(),
+      pikkuState(null, 'addons', 'packages').get('example') as never
+    )
+    const credentials = services.credentialService as CredentialService
+
+    assert.equal(await credentials.get('slack'), 'credential-of-slack')
+    await assert.rejects(() => credentials.get('stripe'), /denied/i)
+    await assert.rejects(() => credentials.getAllUsers(), /denied/i)
+  })
+
+  test('globalCredentials, set by the host, hands over the whole service', async () => {
+    registerAddon(['ADDON_KEY'], ['slack'])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      globalCredentials: 'links credentials an operator names at runtime',
+    })
+
+    const credentials = await credentialsHandedToAddon('example')
+    assert.equal(await credentials.get('stripe'), 'credential-of-stripe')
+    assert.deepEqual(await credentials.getAllUsers(), ['user-1'])
+  })
+})
+
+/**
+ * An addon whose secret names come off its input rather than its own source
+ * declares nothing, so the host lends it names it could not have derived.
+ *
+ * knowledge: decisions/security/decision-secretless-functions.md
+ */
+describe('the host grants an addon secrets it could not declare', () => {
+  beforeEach(() => {
+    resetPikkuState()
+  })
+
+  test('a granted secret is readable', async () => {
+    registerAddon([])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretGrants: ['STRIPE_KEY'],
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    assert.equal(await secrets.getSecret('STRIPE_KEY'), 'value-of-STRIPE_KEY')
+  })
+
+  test('a secret the host did not grant is still denied', async () => {
+    registerAddon([])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretGrants: ['STRIPE_KEY'],
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    await assert.rejects(() => secrets.getSecret('DATABASE_URL'), /denied/i)
+  })
+
+  test('a grant adds to what the addon declared rather than replacing it', async () => {
+    registerAddon(['ADDON_KEY'])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretGrants: ['STRIPE_KEY'],
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    assert.equal(await secrets.getSecret('ADDON_KEY'), 'value-of-ADDON_KEY')
+    assert.equal(await secrets.getSecret('STRIPE_KEY'), 'value-of-STRIPE_KEY')
+  })
+
+  test('an overridden secret is granted by the override itself', async () => {
+    registerAddon([])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretOverrides: { MAILGUN_KEY: 'PROD_EMAIL_KEY' },
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    assert.equal(
+      await secrets.getSecret('MAILGUN_KEY'),
+      'value-of-PROD_EMAIL_KEY'
+    )
+  })
+
+  test('a grant is checked before the override renames it', async () => {
+    registerAddon([])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretGrants: ['MAILGUN_KEY'],
+      secretOverrides: { MAILGUN_KEY: 'PROD_EMAIL_KEY' },
+    })
+
+    const secrets = await secretsHandedToAddon('example')
+    assert.equal(
+      await secrets.getSecret('MAILGUN_KEY'),
+      'value-of-PROD_EMAIL_KEY'
+    )
+    await assert.rejects(() => secrets.getSecret('PROD_EMAIL_KEY'), /denied/i)
+  })
+
+  test('a granted credential is readable', async () => {
+    registerAddon([], [])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      credentialGrants: ['stripe'],
+    })
+
+    const credentials = await credentialsHandedToAddon('example')
+    assert.equal(await credentials.get('stripe'), 'credential-of-stripe')
+    await assert.rejects(() => credentials.get('slack'), /denied/i)
+  })
+
+  test('a granted credential does not widen the rest of the service', async () => {
+    registerAddon([], [])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      credentialGrants: ['stripe'],
+    })
+
+    const credentials = await credentialsHandedToAddon('example')
+    await assert.rejects(() => credentials.getAllUsers(), /denied/i)
+  })
+
+  test('an addon without a singleton factory is granted too', async () => {
+    pikkuState(ADDON_PACKAGE, 'package', 'declaredSecrets', [])
+    wireAddon({
+      name: 'example',
+      package: ADDON_PACKAGE,
+      secretGrants: ['STRIPE_KEY'],
+    })
+
+    const services = await getOrCreatePackageSingletonServices(
+      ADDON_PACKAGE,
+      createParentServices(),
+      pikkuState(null, 'addons', 'packages').get('example') as never
+    )
+
+    assert.equal(
+      await services.secrets.getSecret('STRIPE_KEY'),
+      'value-of-STRIPE_KEY'
+    )
+    await assert.rejects(
+      () => services.secrets.getSecret('DATABASE_URL'),
+      /denied/i
+    )
+  })
+})

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

@@ -708,6 +708,7 @@ describe('multi-instance addons', () => {
         return svc
       },
     } as never)
+    pikkuState('@addon/slack', 'package', 'declaredSecrets', ['slackToken'])
     registerFunction(
       'send',
       async (services: any) => ({ token: services.token }),
@@ -753,6 +754,7 @@ describe('multi-instance addons', () => {
         }
       },
     } as never)
+    pikkuState('@addon/slack', 'package', 'declaredSecrets', ['slackToken'])
 
     registerFunction(
       'leaf',

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

@@ -284,6 +284,10 @@ export class ContextAwareRPCService {
         secretOverrides: resolved.addonConfig?.secretOverrides,
         variableOverrides: resolved.addonConfig?.variableOverrides,
         credentialOverrides: resolved.addonConfig?.credentialOverrides,
+        secretGrants: resolved.addonConfig?.secretGrants,
+        credentialGrants: resolved.addonConfig?.credentialGrants,
+        globalSecrets: resolved.addonConfig?.globalSecrets,
+        globalCredentials: resolved.addonConfig?.globalCredentials,
       },
     }
   }

package/src/wirings/rpc/rpc-types.ts

@@ -67,6 +67,14 @@ export interface ResolvedFunction {
     secretOverrides?: Record<string, string>
     variableOverrides?: Record<string, string>
     credentialOverrides?: Record<string, string>
+    /** Set by the consuming app: secrets it lends this instance, as the addon names them */
+    secretGrants?: string[]
+    /** Set by the consuming app: credentials it lends this instance, as the addon names them */
+    credentialGrants?: string[]
+    /** Set by the consuming app: hand this instance the unscoped `SecretService` */
+    globalSecrets?: string
+    /** Set by the consuming app: hand this instance the unscoped `CredentialService` */
+    globalCredentials?: string
     /** Set by `wireRemoteAddon`: dispatch this namespace's RPCs over HTTP */
     remote?: boolean
     serverUrl?: string | ((services: any) => string | Promise<string>)

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

@@ -14,6 +14,31 @@ export type WireAddonConfig = {
   secretOverrides?: Record<string, string>
   variableOverrides?: Record<string, string>
   credentialOverrides?: Record<string, string>
+  /**
+   * Secrets this instance may read on top of the ones it declared, named as the
+   * addon reads them — the scope check runs before `secretOverrides` renames
+   * them, so an overridden secret is named here by its addon-side key. Listing
+   * one in `secretOverrides` grants it too.
+   *
+   * For an addon whose secret names come off its input rather than its own
+   * source, this is how the host lends names the addon could not declare.
+   */
+  secretGrants?: string[]
+  /** Credentials this instance may read on top of the ones it declared. */
+  credentialGrants?: string[]
+  /**
+   * Hands this instance the whole `SecretService` instead of one scoped to the
+   * secrets it declared. The value is the reason, recorded in the deploy
+   * manifest — an addon that names secrets at runtime cannot be scoped, and
+   * only the consuming app, never the addon, can grant it.
+   */
+  globalSecrets?: string
+  /**
+   * Hands this instance the whole `CredentialService` instead of one narrowed
+   * to the credentials it declared. The value is the reason, recorded in the
+   * deploy manifest, and only the consuming app can grant it.
+   */
+  globalCredentials?: string
 }
 
 export const wireAddon = (config: WireAddonConfig): void => {
@@ -32,6 +57,14 @@ export const wireAddon = (config: WireAddonConfig): void => {
     ...(config.credentialOverrides
       ? { credentialOverrides: config.credentialOverrides }
       : {}),
+    ...(config.secretGrants ? { secretGrants: config.secretGrants } : {}),
+    ...(config.credentialGrants
+      ? { credentialGrants: config.credentialGrants }
+      : {}),
+    ...(config.globalSecrets ? { globalSecrets: config.globalSecrets } : {}),
+    ...(config.globalCredentials
+      ? { globalCredentials: config.globalCredentials }
+      : {}),
   })
 }
 

package/src/wirings/scheduler/index.ts

@@ -7,5 +7,4 @@ export { logSchedulers } from './log-schedulers.js'
 export type {
   CoreScheduledTask,
   ScheduledTasksMeta,
-  PikkuScheduledTask,
 } from './scheduler.types.js'

package/src/wirings/trigger/index.ts

@@ -6,5 +6,4 @@ export type {
   CorePikkuTriggerFunction,
   CorePikkuTriggerFunctionConfig,
   CoreTrigger,
-  PikkuTrigger,
 } from './trigger.types.js'

package/src/wirings/virtual-user/index.ts

@@ -18,25 +18,16 @@
  */
 export type {
   ApiCatalogueEntry,
-  IntentRecord,
   IntentSource,
-  IntentStatus,
-  StepRecord,
-  VirtualUserAction,
-  VirtualUserBudget,
   VirtualUserDisposition,
   VirtualUserFinding,
-  VirtualUserFindingKind,
   VirtualUserRunResult,
-  VirtualUserTally,
   VirtualUserTarget,
 } from './virtual-user.types.js'
 export { PRODUCTION_DISPOSITION } from './virtual-user.types.js'
 export {
   runVirtualUser,
-  rememberIds,
   type RunVirtualUserParams,
-  type VirtualUserCallContext,
 } from './run-virtual-user.js'
 export {
   personaScopes,
@@ -57,26 +48,19 @@ export {
 } from './virtual-user-dispositions.js'
 export {
   catalogueClassification,
-  catalogueIndex,
   catalogueLookup,
-  describeEntry,
   isReadOnly,
   reachableCatalogue,
-  renderCatalogue,
   unreachableCatalogue,
 } from './virtual-user-catalogue.js'
 export {
-  reachableAgents,
   type AgentReachability,
   type ReachableAgent,
 } from './virtual-user-agents.js'
 export {
   IntentStack,
   intentsForPersona,
-  type IntentMove,
-  type ScheduledTick,
 } from './virtual-user-intents.js'
-export { createRng, type VirtualUserRng } from './virtual-user-rng.js'
 export {
   deriveCatalogue,
   deriveIntents,