@pikku/core 0.12.72 → 0.12.74

package/src/wirings/role/role.test.ts

@@ -0,0 +1,104 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  flattenSystemRoleDefinitions,
+  validateAndBuildSystemRoleDefinitionsMeta,
+} from './validate-role-definitions.js'
+import type { SystemRoleDefinitions } from './role.types.js'
+
+const defs = (...d: SystemRoleDefinitions): SystemRoleDefinitions => d
+
+describe('system role validation', () => {
+  test('keys definitions by name', () => {
+    const meta = validateAndBuildSystemRoleDefinitionsMeta(
+      defs(
+        { name: 'buyer', scopes: ['orders:create'], description: 'Buys' },
+        { name: 'admin', scopes: ['admin'] }
+      )
+    )
+    assert.deepEqual(Object.keys(meta), ['buyer', 'admin'])
+    assert.equal(meta.buyer?.description, 'Buys')
+  })
+
+  test('a name containing the scope separator is refused', () => {
+    assert.throws(
+      () =>
+        validateAndBuildSystemRoleDefinitionsMeta(
+          defs({ name: 'admin:billing', scopes: [] })
+        ),
+      /contains the ':' separator/
+    )
+  })
+
+  test('an empty name is refused', () => {
+    assert.throws(
+      () =>
+        validateAndBuildSystemRoleDefinitionsMeta(
+          defs({ name: '', scopes: [] })
+        ),
+      /empty name/
+    )
+  })
+
+  // An addon and its host both declaring `admin` is legitimate; the second is
+  // redundant rather than conflicting, so long as it says the same thing.
+  test('an identical redeclaration is allowed', () => {
+    const meta = validateAndBuildSystemRoleDefinitionsMeta(
+      defs(
+        { name: 'admin', scopes: ['admin'], sourceFile: 'a.ts' },
+        { name: 'admin', scopes: ['admin'], sourceFile: 'b.ts' }
+      )
+    )
+    assert.equal(Object.keys(meta).length, 1)
+    assert.equal(meta.admin?.sourceFile, 'a.ts')
+  })
+
+  test('scope order does not make two declarations different', () => {
+    assert.doesNotThrow(() =>
+      validateAndBuildSystemRoleDefinitionsMeta(
+        defs(
+          { name: 'buyer', scopes: ['a', 'b'], sourceFile: 'a.ts' },
+          { name: 'buyer', scopes: ['b', 'a'], sourceFile: 'b.ts' }
+        )
+      )
+    )
+  })
+
+  test('a conflicting redeclaration names both files', () => {
+    assert.throws(
+      () =>
+        validateAndBuildSystemRoleDefinitionsMeta(
+          defs(
+            { name: 'buyer', scopes: ['a'], sourceFile: 'a.ts' },
+            { name: 'buyer', scopes: ['a', 'b'], sourceFile: 'b.ts' }
+          )
+        ),
+      /a\.ts[\s\S]*b\.ts/
+    )
+  })
+})
+
+describe('flattening', () => {
+  test('deduplicates by name, keeping the first', () => {
+    const flat = flattenSystemRoleDefinitions(
+      defs(
+        { name: 'admin', scopes: ['admin'], description: 'first' },
+        { name: 'admin', scopes: ['admin'], description: 'second' },
+        { name: 'buyer', scopes: [] }
+      )
+    )
+    assert.deepEqual(
+      flat.map((r) => r.name),
+      ['admin', 'buyer']
+    )
+    assert.equal(flat[0]?.description, 'first')
+  })
+
+  test('copies the scope array rather than aliasing the declaration', () => {
+    const definition = { name: 'buyer', scopes: ['a'] }
+    const flat = flattenSystemRoleDefinitions(defs(definition))
+    flat[0]!.scopes.push('b')
+    assert.deepEqual(definition.scopes, ['a'])
+  })
+})

package/src/wirings/role/role.types.ts

@@ -0,0 +1,47 @@
+/**
+ * A system role: a named set of scopes that ships with the product.
+ *
+ * System roles are declared in code, which is what separates them from the
+ * roles an admin composes in the console. The distinction is the one AWS draws
+ * between managed and customer-managed policies — a system role is part of the
+ * application's surface, so the console may show and grant it but must not
+ * rename, re-scope or delete it.
+ */
+export type CoreSystemRole = {
+  /** Short human-readable name, e.g. "Buyer". */
+  displayName?: string
+  /** Longer-form description, surfaced in the console when granting. */
+  description?: string
+  /**
+   * The scopes this role grants. Every id must be declared with
+   * `defineScope` — the inspector fails the build otherwise, so a role cannot
+   * quietly grant a scope that no function checks.
+   */
+  scopes: string[]
+}
+
+/**
+ * System roles to declare, keyed by name. A key must be non-empty and must not
+ * contain `:` — that separator belongs to scopes, and a role that looks like a
+ * scope id is a role nobody reads correctly.
+ */
+export type CoreSystemRoles = Record<string, CoreSystemRole>
+
+export type SystemRoleDefinitionMeta = {
+  name: string
+  displayName?: string
+  description?: string
+  scopes: string[]
+  sourceFile?: string
+}
+
+export type SystemRoleDefinitions = SystemRoleDefinitionMeta[]
+export type SystemRoleDefinitionsMeta = Record<string, SystemRoleDefinitionMeta>
+
+/** A declared system role, ready to sync into a scope store. */
+export type SystemRole = {
+  name: string
+  displayName?: string
+  description?: string
+  scopes: string[]
+}

package/src/wirings/role/validate-role-definitions.ts

@@ -0,0 +1,93 @@
+import type {
+  SystemRole,
+  SystemRoleDefinitions,
+  SystemRoleDefinitionsMeta,
+} from './role.types.js'
+
+const SEPARATOR = ':'
+
+const assertRoleName = (name: string): void => {
+  if (name.length === 0) {
+    throw new Error('A system role is declared with an empty name.')
+  }
+  if (name.includes(SEPARATOR)) {
+    throw new Error(
+      `System role '${name}' contains the '${SEPARATOR}' separator. ` +
+        `'${SEPARATOR}' delimits scope ids; a role named like a scope reads as one.`
+    )
+  }
+}
+
+/**
+ * The declared roles as a flat list, deduplicated by name.
+ *
+ * A role may legitimately be declared more than once — an addon and its host
+ * app both contributing `admin`, say — and
+ * {@link validateAndBuildSystemRoleDefinitionsMeta} has already guaranteed
+ * those declarations are identical, so the second is redundant rather than
+ * conflicting. Collapsing here keeps codegen (which emits an object literal
+ * keyed by name) and a ScopeService (which syncs one row per role) honest.
+ */
+export const flattenSystemRoleDefinitions = (
+  definitions: SystemRoleDefinitions
+): SystemRole[] => {
+  const seen = new Set<string>()
+  const out: SystemRole[] = []
+  for (const def of definitions) {
+    if (seen.has(def.name)) {
+      continue
+    }
+    seen.add(def.name)
+    out.push({
+      name: def.name,
+      displayName: def.displayName,
+      description: def.description,
+      scopes: [...def.scopes],
+    })
+  }
+  return out
+}
+
+/**
+ * Validates declared system roles and keys them by name.
+ *
+ * Definitions sharing a name must grant the same scope set; a conflicting
+ * redeclaration is a hard error naming both source files. Order within
+ * `scopes` is not significant — two declarations listing the same scopes
+ * differently are the same role.
+ */
+export function validateAndBuildSystemRoleDefinitionsMeta(
+  definitions: SystemRoleDefinitions
+): SystemRoleDefinitionsMeta {
+  const meta: SystemRoleDefinitionsMeta = {}
+
+  for (const def of definitions) {
+    assertRoleName(def.name)
+
+    const existing = meta[def.name]
+    if (existing) {
+      const sameScopes =
+        JSON.stringify([...existing.scopes].sort()) ===
+        JSON.stringify([...def.scopes].sort())
+      if (!sameScopes) {
+        throw new Error(
+          `System role '${def.name}' is declared with different scopes.\n` +
+            `  First declaration: ${existing.sourceFile ?? 'unknown'}\n` +
+            `  Second declaration: ${def.sourceFile ?? 'unknown'}\n` +
+            `Roles sharing a name must grant the same scopes.`
+        )
+      }
+      continue
+    }
+
+    meta[def.name] = {
+      name: def.name,
+      displayName: def.displayName,
+      description: def.description,
+      scopes: [...def.scopes],
+      sourceFile: def.sourceFile,
+    }
+  }
+
+  return meta
+}

package/src/wirings/rpc/addon-auth-tags.test.ts

@@ -0,0 +1,223 @@
+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 {
+  addTagMiddleware,
+  clearMiddlewareCache,
+} from '../../middleware-runner.js'
+import { ForbiddenError } from '../../errors/errors.js'
+import {
+  resolveAddonAuth,
+  resolveAddonTags,
+  wireAddon,
+} from './wire-addon.js'
+
+const ADDON_PACKAGE = '@addon/console'
+
+const createServices = () =>
+  ({
+    logger: {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+    },
+  }) as never
+
+const registerAddonFunction = (funcName: string) => {
+  addFunction(funcName, { func: async () => 'ok' } as never, ADDON_PACKAGE)
+  pikkuState(ADDON_PACKAGE, 'function', 'meta')[funcName] = {
+    name: funcName,
+    sessionless: true,
+    permissions: [],
+  } as never
+}
+
+const session = () => ({ userId: 'u1' }) as never
+
+/**
+ * How an addon function is reached over a directly-wired route: the inspector
+ * records the addon package on the wiring meta and the runner hands it to
+ * `runPikkuFunc`, never passing through namespace resolution.
+ */
+const callOverDirectWiring = (
+  funcName: string,
+  {
+    wireType = 'http',
+    withSession = false,
+    auth,
+  }: {
+    wireType?: string
+    withSession?: boolean
+    auth?: boolean
+  } = {}
+) =>
+  runPikkuFunc(wireType as never, `${wireType}:/console/thing`, funcName, {
+    singletonServices: createServices(),
+    data: () => ({}),
+    auth,
+    packageName: ADDON_PACKAGE,
+    wire: (withSession ? { session: session() } : {}) as never,
+  })
+
+beforeEach(() => {
+  resetPikkuState()
+  // resetPikkuState deliberately leaves runtime caches alone; combineMiddleware
+  // keys its cache on wireType/wireId, which these tests reuse.
+  clearMiddlewareCache()
+  pikkuState(null, 'package', 'singletonServices', createServices())
+})
+
+describe('resolveAddonAuth', () => {
+  test('is false for a non-addon package', () => {
+    assert.equal(resolveAddonAuth(null), false)
+    assert.equal(resolveAddonAuth('@addon/other'), false)
+  })
+
+  test('reads the named instance when one is resolved', () => {
+    wireAddon({ name: 'live', package: ADDON_PACKAGE, auth: true })
+    wireAddon({ name: 'test', package: ADDON_PACKAGE, auth: false })
+
+    assert.equal(resolveAddonAuth(ADDON_PACKAGE, 'live'), true)
+    assert.equal(resolveAddonAuth(ADDON_PACKAGE, 'test'), false)
+  })
+
+  test('takes the stricter reading across namespaces on the unnamed path', () => {
+    wireAddon({ name: 'live', package: ADDON_PACKAGE, auth: true })
+    wireAddon({ name: 'test', package: ADDON_PACKAGE, auth: false })
+
+    assert.equal(resolveAddonAuth(ADDON_PACKAGE), true)
+  })
+})
+
+describe('resolveAddonTags', () => {
+  test('unions tags across every namespace the package is wired under', () => {
+    wireAddon({ name: 'live', package: ADDON_PACKAGE, tags: ['admin'] })
+    wireAddon({ name: 'test', package: ADDON_PACKAGE, tags: ['sandbox'] })
+
+    assert.deepEqual(resolveAddonTags(ADDON_PACKAGE).sort(), [
+      'admin',
+      'sandbox',
+    ])
+  })
+
+  test('reads the named instance exactly when one is resolved', () => {
+    wireAddon({ name: 'live', package: ADDON_PACKAGE, tags: ['admin'] })
+    wireAddon({ name: 'test', package: ADDON_PACKAGE, tags: ['sandbox'] })
+
+    assert.deepEqual(resolveAddonTags(ADDON_PACKAGE, 'live'), ['admin'])
+  })
+})
+
+describe('wireAddon auth on direct wirings', () => {
+  test('requires a session for a sessionless addon function', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, auth: true })
+    registerAddonFunction('credentialGet')
+
+    await assert.rejects(
+      () => callOverDirectWiring('credentialGet'),
+      ForbiddenError
+    )
+  })
+
+  test('allows the call once a session is present', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, auth: true })
+    registerAddonFunction('credentialGet')
+
+    assert.equal(
+      await callOverDirectWiring('credentialGet', { withSession: true }),
+      'ok'
+    )
+  })
+
+  test('leaves an addon wired without auth ungated', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE })
+    registerAddonFunction('credentialGet')
+
+    assert.equal(await callOverDirectWiring('credentialGet'), 'ok')
+  })
+
+  test('does not weaken a wiring that already requires auth', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, auth: false })
+    registerAddonFunction('credentialGet')
+
+    await assert.rejects(
+      () => callOverDirectWiring('credentialGet', { auth: true }),
+      ForbiddenError
+    )
+  })
+
+  test('gates every wiring kind, not just http', async () => {
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, auth: true })
+    registerAddonFunction('credentialGet')
+
+    for (const wireType of [
+      'http',
+      'channel',
+      'queue',
+      'scheduler',
+      'cli',
+      'mcp',
+      'trigger',
+      'gateway',
+    ]) {
+      await assert.rejects(
+        () => callOverDirectWiring('credentialGet', { wireType }),
+        ForbiddenError,
+        `${wireType} should have been gated`
+      )
+    }
+  })
+})
+
+describe('wireAddon tags on direct wirings', () => {
+  test('runs middleware the app registered for the addon tag', async () => {
+    const seen: string[] = []
+    addTagMiddleware('admin', [
+      (async (_services: never, _wire: never, next: () => Promise<void>) => {
+        seen.push('admin')
+        await next()
+      }) as never,
+    ])
+
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, tags: ['admin'] })
+    registerAddonFunction('credentialGet')
+
+    assert.equal(await callOverDirectWiring('credentialGet'), 'ok')
+    assert.deepEqual(seen, ['admin'])
+  })
+
+  test('lets that middleware reject the call', async () => {
+    addTagMiddleware('admin', [
+      (async () => {
+        throw new ForbiddenError('nope')
+      }) as never,
+    ])
+
+    wireAddon({ name: 'console', package: ADDON_PACKAGE, tags: ['admin'] })
+    registerAddonFunction('credentialGet')
+
+    await assert.rejects(
+      () => callOverDirectWiring('credentialGet'),
+      ForbiddenError
+    )
+  })
+
+  test('leaves an addon wired without tags alone', async () => {
+    const seen: string[] = []
+    addTagMiddleware('admin', [
+      (async (_services: never, _wire: never, next: () => Promise<void>) => {
+        seen.push('admin')
+        await next()
+      }) as never,
+    ])
+
+    wireAddon({ name: 'console', package: ADDON_PACKAGE })
+    registerAddonFunction('credentialGet')
+
+    assert.equal(await callOverDirectWiring('credentialGet'), 'ok')
+    assert.deepEqual(seen, [])
+  })
+})

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