@pikku/core 0.12.82 → 0.12.83

package/src/types/state.types.ts

@@ -47,9 +47,9 @@ import type {
 } from '../wirings/scheduler/scheduler.types.js'
 import type {
   CoreWorkflow,
-  CoreFeature,
   WorkflowsRuntimeMeta,
 } from '../wirings/workflow/workflow.types.js'
+import type { CoreFeature } from '../wirings/workflow/scenario.types.js'
 import type {
   CoreTrigger,
   CoreTriggerSource,
@@ -102,6 +102,10 @@ export interface PikkuPackageState {
         variableOverrides?: Record<string, string>
         /** Per-instance name-aliases: logical name the addon reads -> actual project credential name */
         credentialOverrides?: Record<string, string>
+        /** Secrets the host lends this instance, named as the addon reads them */
+        secretGrants?: string[]
+        /** Credentials the host lends this instance, named as the addon reads them */
+        credentialGrants?: string[]
         /** Why this instance gets the whole `SecretService` rather than one scoped to its declared secrets */
         globalSecrets?: string
         /** Why this instance gets the whole `CredentialService` rather than one scoped to its declared credentials */

package/src/wirings/ai-agent/ai-agent-prepare.ts

@@ -565,6 +565,8 @@ export async function buildToolDefs(
                     variableOverrides: capturedAddonConfig?.variableOverrides,
                     credentialOverrides:
                       capturedAddonConfig?.credentialOverrides,
+                    secretGrants: capturedAddonConfig?.secretGrants,
+                    credentialGrants: capturedAddonConfig?.credentialGrants,
                     globalSecrets: capturedAddonConfig?.globalSecrets,
                     globalCredentials: capturedAddonConfig?.globalCredentials,
                   }

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

@@ -13,12 +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>
@@ -142,7 +162,11 @@ export const getOrCreatePackageSingletonServices = async (
       ...existingServices,
       secrets: new ScopedSecretService(
         existingServices.secrets,
-        new Set(pikkuState(packageName, 'package', 'declaredSecrets') ?? [])
+        allowedNames(
+          pikkuState(packageName, 'package', 'declaredSecrets'),
+          addonInstance?.secretGrants,
+          addonInstance?.secretOverrides
+        )
       ),
     }
   }
@@ -151,10 +175,12 @@ export const getOrCreatePackageSingletonServices = async (
       ...existingServices,
       credentialService: new ScopedCredentialService(
         existingServices.credentialService,
-        new Set(
+        allowedNames(
           Object.keys(
             pikkuState(packageName, 'package', 'credentialsMeta') ?? {}
-          )
+          ),
+          addonInstance?.credentialGrants,
+          addonInstance?.credentialOverrides
         )
       ),
     }
@@ -202,6 +228,8 @@ 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

@@ -259,3 +259,133 @@ describe('addon credentials are scoped to what the addon declared', () => {
     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.ts

@@ -284,6 +284,8 @@ 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,10 @@ 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` */

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

@@ -14,6 +14,18 @@ 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
@@ -45,6 +57,10 @@ 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/workflow/feature.ts

@@ -1,9 +1,6 @@
 import { pikkuState } from '../../pikku-state.js'
-import type {
-  CoreFeature,
-  CoreWorkflow,
-  FeaturePlanEntry,
-} from './workflow.types.js'
+import type { CoreWorkflow } from './workflow.types.js'
+import type { CoreFeature, FeaturePlanEntry } from './scenario.types.js'
 
 export const addFeature = (
   featureId: string,

package/src/wirings/workflow/index.ts

@@ -28,13 +28,9 @@ export {
   reconstructStateAt,
   reconstructFinalState,
 } from './run-timeline.js'
-export type {
-  RunTimeline,
-  ReconstructedRunState,
-} from './run-timeline.js'
+export type { RunTimeline, ReconstructedRunState } from './run-timeline.js'
 
 export { addWorkflow } from './dsl/workflow-runner.js'
-export { addFeature, resolveFeatureScenarios } from './feature.js'
 
 export { template, type TemplateString } from './graph/template.js'
 export {
@@ -63,10 +59,6 @@ export type {
   WorkflowRunService,
   WorkflowRunMirror,
   CoreWorkflow,
-  CoreFeature,
-  FeatureMeta,
-  FeaturesMeta,
-  FeaturePlanEntry,
   PikkuWorkflow,
   ContextVariable,
   WorkflowContext,
@@ -97,47 +89,7 @@ export type {
   SwitchStepMeta,
   FilterStepMeta,
   ArrayPredicateStepMeta,
-  ScenarioStepInvocation,
-  ScenarioStepMeta,
   WorkflowStepMeta,
   WorkflowStepWire,
   PikkuWorkflowWire,
-  PikkuScenarioWire,
 } from './workflow.types.js'
-
-export type {
-  ScenarioStepPhase,
-  ScenarioStepKind,
-  ScenarioStepOptions,
-  PikkuScenarioStepWire,
-  ScenarioEnvironment,
-  ScenarioSurface,
-  ScenarioSurfaceResolution,
-} from './scenario-step.types.js'
-export { SCENARIO_SURFACES } from './scenario-step.types.js'
-
-// Which of a step's bindings run: one for an action, every witness for a `then`
-export { resolveScenarioSurfaces } from './scenario-surface.js'
-
-export { requireActor, requireScenarioEnv } from './scenario-step-guards.js'
-
-export { pollUntil, type PollOptions } from './scenario-poll.js'
-
-export { createCookieJar } from './scenario-cookie-jar.js'
-export type { ScenarioCookieJar } from './scenario-cookie-jar.js'
-
-export type {
-  ScenarioHttpResponse,
-  ScenarioJsonRequest,
-} from '../../services/personas-service.js'
-// The readers themselves live on `@pikku/core/persona`; workflow is a production
-// wiring and must not pull scenario runtime in behind it.
-
-export type {
-  PikkuBrowserWire,
-  TestIdSelector,
-  ScenarioBrowserProvider,
-  ScenarioBrowserFailure,
-} from './scenario-step.types.js'
-
-export { composeStepProse, renderStepTemplate } from './scenario-prose.js'

package/src/wirings/workflow/pikku-scenario-service.ts

@@ -27,10 +27,10 @@ import type {
 } from './scenario-step.types.js'
 import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js'
 import type {
-  PikkuScenarioWire,
   PikkuWorkflowWire,
   WorkflowQueueOptions,
 } from './workflow.types.js'
+import type { PikkuScenarioWire } from './scenario.types.js'
 import type {
   WorkflowExpectEventuallyOptions,
   WorkflowExpectErrorOptions,
@@ -38,6 +38,26 @@ import type {
   WorkflowExpectServiceOptions,
 } from './dsl/workflow-dsl.types.js'
 
+export { addFeature, resolveFeatureScenarios } from './feature.js'
+export type * from './scenario.types.js'
+export { SCENARIO_SURFACES } from './scenario-step.types.js'
+
+// Which of a step's bindings run: one for an action, every witness for a `then`
+export { resolveScenarioSurfaces } from './scenario-surface.js'
+
+export { pollUntil, type PollOptions } from './scenario-poll.js'
+export { createCookieJar } from './scenario-cookie-jar.js'
+export type { ScenarioCookieJar } from './scenario-cookie-jar.js'
+export { composeStepProse, renderStepTemplate } from './scenario-prose.js'
+
+export { requireActor, requireScenarioEnv } from './scenario-step-guards.js'
+
+export type {
+  ScenarioHttpResponse,
+  ScenarioJsonRequest,
+} from '../../services/personas-service.js'
+// The readers themselves live on `@pikku/core/persona`
+
 /**
  * A workflow service with the scenario capability attached — the two lines
  * `pikku scenario run` needs, in one call so no caller has to remember that the

package/src/wirings/workflow/scenario.types.ts

@@ -0,0 +1,63 @@
+import type {
+  CorePikkuFunctionConfig,
+  CorePikkuFunctionHook,
+} from '../../function/functions.types.js'
+
+export type {
+  ScenarioStepInvocation,
+  ScenarioStepMeta,
+  PikkuScenarioWire,
+} from './dsl/workflow-dsl.types.js'
+
+export type {
+  ScenarioStepPhase,
+  ScenarioStepKind,
+  ScenarioStepOptions,
+  PikkuScenarioStepWire,
+  ScenarioEnvironment,
+  ScenarioSurface,
+  ScenarioSurfaceResolution,
+  PikkuBrowserWire,
+  TestIdSelector,
+  ScenarioBrowserProvider,
+  ScenarioBrowserFailure,
+} from './scenario-step.types.js'
+
+export type CoreFeatureScenario =
+  | CorePikkuFunctionConfig<any, any, any>
+  | { scenario: CorePikkuFunctionConfig<any, any, any>; data: unknown }
+
+export type CoreFeature = {
+  name: string
+  description?: string
+  tags?: string[]
+  scenarios: readonly CoreFeatureScenario[]
+  before?: CorePikkuFunctionHook
+  after?: CorePikkuFunctionHook
+}
+
+export type FeatureMetaEntry = {
+  scenario: string
+  data?: unknown
+}
+
+export type FeatureMeta = {
+  id: string
+  name: string
+  description?: string
+  tags: string[]
+  entries: FeatureMetaEntry[]
+  unresolvedEntries: number
+  hasBefore: boolean
+  hasAfter: boolean
+}
+
+export type FeaturesMeta = Record<string, FeatureMeta>
+
+export type FeaturePlanEntry = {
+  featureId: string
+  featureName: string
+  scenarioName: string
+  data?: unknown
+  tags: string[]
+}

package/src/wirings/workflow/workflow.types.ts

@@ -1,8 +1,5 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js'
-import type {
-  CorePikkuFunctionConfig,
-  CorePikkuFunctionHook,
-} from '../../function/functions.types.js'
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js'
 
 export type { WorkflowService } from '../../services/workflow-service.js'
@@ -30,22 +27,11 @@ export type {
   SwitchStepMeta,
   FilterStepMeta,
   ArrayPredicateStepMeta,
-  ScenarioStepInvocation,
-  ScenarioStepMeta,
   WorkflowStepMeta,
   WorkflowStepWire,
   PikkuWorkflowWire,
-  PikkuScenarioWire,
 } from './dsl/workflow-dsl.types.js'
 
-export type {
-  ScenarioStepPhase,
-  ScenarioStepOptions,
-  PikkuScenarioStepWire,
-  PikkuBrowserWire,
-  ScenarioBrowserProvider,
-} from './scenario-step.types.js'
-
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js'
 
 export interface WorkflowRunWire {
@@ -238,45 +224,6 @@ export type CoreWorkflow<
   tags?: string[]
 }
 
-export type CoreFeatureScenario =
-  | CorePikkuFunctionConfig<any, any, any>
-  | { scenario: CorePikkuFunctionConfig<any, any, any>; data: unknown }
-
-export type CoreFeature = {
-  name: string
-  description?: string
-  tags?: string[]
-  scenarios: readonly CoreFeatureScenario[]
-  before?: CorePikkuFunctionHook
-  after?: CorePikkuFunctionHook
-}
-
-export type FeatureMetaEntry = {
-  scenario: string
-  data?: unknown
-}
-
-export type FeatureMeta = {
-  id: string
-  name: string
-  description?: string
-  tags: string[]
-  entries: FeatureMetaEntry[]
-  unresolvedEntries: number
-  hasBefore: boolean
-  hasAfter: boolean
-}
-
-export type FeaturesMeta = Record<string, FeatureMeta>
-
-export type FeaturePlanEntry = {
-  featureId: string
-  featureName: string
-  scenarioName: string
-  data?: unknown
-  tags: string[]
-}
-
 export interface PikkuWorkflow {
   start: <I>(input: I) => Promise<{ runId: string }>
   getRun: (runId: string) => Promise<WorkflowRun>