@pikku/core 0.12.106 → 0.12.111

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

@@ -1,391 +0,0 @@
-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/addon/index.ts

@@ -1,12 +0,0 @@
-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'
-export {
-  resolveRemoteAddonToken,
-  RemoteAddonAuthError,
-} from './remote-addon-auth.js'
-export type { RemoteAddonAuthBinding } from './remote-addon-auth.js'

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

@@ -1,65 +0,0 @@
-import type { CoreServices, PikkuRawWire } from '../../types/core.types.js'
-import { PikkuError, addError } from '../../errors/error-handler.js'
-import {
-  isSecretValue,
-  type SecretValue,
-} from '../../classification/secret-value.js'
-
-export type RemoteAddonAuthBinding =
-  | { credentialId: string }
-  | { secretId: string }
-  | {
-      resolve: (
-        services: CoreServices,
-        wire: PikkuRawWire
-      ) => string | SecretValue<string> | Promise<string | SecretValue<string>>
-    }
-
-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.',
-})
-
-/** Returns `null` only when no auth is bound; an empty resolved token throws. */
-export async function resolveRemoteAddonToken(
-  auth: RemoteAddonAuthBinding | undefined,
-  services: CoreServices,
-  wire: PikkuRawWire,
-  namespace: string
-): Promise<string | null> {
-  if (!auth) {
-    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)
-  }
-
-  // The wire is where a secret is meant to end up, so unwrap it here rather
-  // than at each branch — `resolve` and `getCredential` may hand one back too.
-  const resolved = isSecretValue(token) ? token.reveal() : token
-
-  if (resolved === null || resolved === undefined || resolved === '') {
-    throw new RemoteAddonAuthError(namespace, 'resolved token was empty')
-  }
-
-  return String(resolved)
-}

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

@@ -1,102 +0,0 @@
-import { beforeEach, describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { resetPikkuState, pikkuState } from '../../pikku-state.js'
-import { resolveAddonScopes, wireAddon } from './wire-addon.js'
-
-beforeEach(() => {
-  resetPikkuState()
-})
-
-describe('wireAddon', () => {
-  test('registers addon package metadata for namespace resolution', () => {
-    wireAddon({
-      name: 'stripe',
-      package: '@addon/stripe',
-      rpcEndpoint: 'https://rpc.example.com',
-      auth: true,
-      mcp: true,
-      tags: ['payments', 'billing'],
-      scopes: ['admin'],
-      secretOverrides: { apiKey: 'STRIPE_API_KEY' },
-      variableOverrides: { region: 'AWS_REGION' },
-      credentialOverrides: { oauth: 'stripeOAuth' },
-    })
-
-    assert.deepEqual(pikkuState(null, 'addons', 'packages').get('stripe'), {
-      package: '@addon/stripe',
-      rpcEndpoint: 'https://rpc.example.com',
-      auth: true,
-      tags: ['payments', 'billing'],
-      scopes: ['admin'],
-      secretOverrides: { apiKey: 'STRIPE_API_KEY' },
-      variableOverrides: { region: 'AWS_REGION' },
-      credentialOverrides: { oauth: 'stripeOAuth' },
-    })
-  })
-
-  test('overwrites existing addon config for the same namespace', () => {
-    wireAddon({
-      name: 'stripe',
-      package: '@addon/stripe-v1',
-      rpcEndpoint: 'https://rpc-v1.example.com',
-      auth: false,
-      tags: ['old'],
-    })
-
-    wireAddon({
-      name: 'stripe',
-      package: '@addon/stripe-v2',
-      rpcEndpoint: 'https://rpc-v2.example.com',
-      auth: true,
-      tags: ['new'],
-    })
-
-    assert.deepEqual(pikkuState(null, 'addons', 'packages').get('stripe'), {
-      package: '@addon/stripe-v2',
-      rpcEndpoint: 'https://rpc-v2.example.com',
-      auth: true,
-      tags: ['new'],
-    })
-  })
-
-  test('omits scopes entirely when none are declared', () => {
-    wireAddon({ name: 'stripe', package: '@addon/stripe' })
-
-    assert.equal(
-      'scopes' in pikkuState(null, 'addons', 'packages').get('stripe')!,
-      false
-    )
-  })
-})
-
-describe('resolveAddonScopes', () => {
-  test('returns nothing for a package that is not a wired addon', () => {
-    wireAddon({ name: 'stripe', package: '@addon/stripe', scopes: ['admin'] })
-
-    assert.deepEqual(resolveAddonScopes('@addon/other'), [])
-    assert.deepEqual(resolveAddonScopes(null), [])
-  })
-
-  test('reads the scopes of the named namespace', () => {
-    wireAddon({ name: 'live', package: '@addon/stripe', scopes: ['admin'] })
-    wireAddon({ name: 'test', package: '@addon/stripe', scopes: ['sandbox'] })
-
-    assert.deepEqual(resolveAddonScopes('@addon/stripe', 'live'), ['admin'])
-    assert.deepEqual(resolveAddonScopes('@addon/stripe', 'test'), ['sandbox'])
-  })
-
-  test('unions every namespace when the caller has no namespace', () => {
-    wireAddon({ name: 'live', package: '@addon/stripe', scopes: ['admin'] })
-    wireAddon({ name: 'test', package: '@addon/stripe', scopes: ['sandbox'] })
-
-    assert.deepEqual(resolveAddonScopes('@addon/stripe'), ['admin', 'sandbox'])
-  })
-
-  test('falls back to the package union when the namespace names another package', () => {
-    wireAddon({ name: 'live', package: '@addon/stripe', scopes: ['admin'] })
-    wireAddon({ name: 'mail', package: '@addon/mail' })
-
-    assert.deepEqual(resolveAddonScopes('@addon/stripe', 'mail'), ['admin'])
-  })
-})