@pikku/core 0.12.71 → 0.12.74

package/src/wirings/queue/validate-worker-config.ts

@@ -3,63 +3,42 @@ import type {
   ConfigValidationResult,
 } from './queue.types.js'
 
-/**
- * Configuration mapping structure for queue implementations
- */
 export interface QueueConfigMapping {
-  /** Configurations that are directly supported */
   supported: Partial<
     Record<
       keyof PikkuWorkerConfig,
       {
-        /** The property name in the underlying queue system */
         queueProperty?: string
-        /** Optional transform function for the value */
         transform?: (value: any) => any
-        /** Description of what this configuration does */
         description: string
       }
     >
   >
 
-  /** Configurations that are not supported */
+  /** Rejected: the value is dropped and a warning raised. */
   unsupported: Partial<
     Record<
       keyof PikkuWorkerConfig,
       {
-        /** Why this configuration is not supported */
         reason: string
-        /** Detailed explanation of what the queue system does instead */
         explanation: string
       }
     >
   >
 
-  /** Configurations that have partial support or workarounds */
+  /** Applied anyway, but with a warning describing the substituted behaviour. */
   fallbacks: Partial<
     Record<
       keyof PikkuWorkerConfig,
       {
-        /** Why this configuration uses a fallback */
         reason: string
-        /** Detailed explanation of the fallback behavior */
         explanation: string
-        /** The fallback value or description */
         fallbackValue: string
       }
     >
   >
 }
 
-/**
- * Validates worker configuration using a mapping table
- * This provides a flexible, maintainable way to validate configurations
- * across different queue implementations
- *
- * @param config - The worker configuration to validate
- * @param configMapping - The mapping table defining supported/unsupported configurations
- * @returns Validation result with applied, ignored, warnings, and fallbacks
- */
 export function validateWorkerConfig(
   configMapping: QueueConfigMapping,
   config: PikkuWorkerConfig = {}
@@ -69,19 +48,16 @@ export function validateWorkerConfig(
   const warnings: string[] = []
   const fallbacks: { [key: string]: any } = {}
 
-  // Process each configuration property
   for (const [key, value] of Object.entries(config)) {
     if (value === undefined) continue
 
     const configKey = key as keyof PikkuWorkerConfig
 
-    // Check if it's a supported configuration
     if (configKey in configMapping.supported) {
       applied[configKey] = value
       continue
     }
 
-    // Check if it's a fallback configuration
     if (configKey in configMapping.fallbacks) {
       const fallbackMapping = configMapping.fallbacks[configKey]!
       applied[configKey] = value
@@ -92,7 +68,6 @@ export function validateWorkerConfig(
       continue
     }
 
-    // Check if it's an unsupported configuration
     if (configKey in configMapping.unsupported) {
       ignored[configKey] = value
       const mapping = configMapping.unsupported[configKey]!
@@ -100,7 +75,6 @@ export function validateWorkerConfig(
       continue
     }
 
-    // Unknown configuration
     ignored[configKey] = value
     warnings.push(
       `${key}: Unknown configuration option for this queue implementation`

package/src/wirings/role/define-system-role.ts

@@ -0,0 +1,33 @@
+import type { CoreSystemRoles } from './role.types.js'
+
+/**
+ * No-op function for declaring system roles.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `SystemRoleName`
+ * union, so a persona naming an undeclared role fails the build.
+ *
+ * A system role is a role that ships with the product: the console may grant
+ * it, but cannot rename, re-scope or delete it. Roles an admin composes in the
+ * console are unaffected and are not declared here.
+ *
+ * Removal is deliberately not destructive. Deleting a declaration leaves the
+ * row in the store, marked undeclared and inert, until `pikku roles prune` —
+ * the same additive contract `defineScope` has, and for the same reason: a
+ * mid-deploy revocation is not something a code edit should be able to cause.
+ *
+ * @example
+ * ```typescript
+ * defineSystemRole({
+ *   buyer: {
+ *     displayName: 'Buyer',
+ *     description: 'Can browse the catalogue and place orders',
+ *     scopes: ['catalogue:read', 'orders:create'],
+ *   },
+ *   admin: {
+ *     description: 'Everything',
+ *     scopes: ['admin'],
+ *   },
+ * })
+ * ```
+ */
+export const defineSystemRole = (_config: CoreSystemRoles): void => {}

package/src/wirings/role/index.ts

@@ -0,0 +1,13 @@
+export { defineSystemRole } from './define-system-role.js'
+export {
+  flattenSystemRoleDefinitions,
+  validateAndBuildSystemRoleDefinitionsMeta,
+} from './validate-role-definitions.js'
+export type {
+  CoreSystemRole,
+  CoreSystemRoles,
+  SystemRole,
+  SystemRoleDefinitionMeta,
+  SystemRoleDefinitions,
+  SystemRoleDefinitionsMeta,
+} from './role.types.js'

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, [])
+  })
+})