@pikku/core 0.12.72 → 0.12.77

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

@@ -12,18 +12,14 @@ import {
   pikkuState,
 } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-/**
- * Error class for queue processor not found
- */
+import { resolveQueueJobIdentity } from './queue-identity.js'
+
 class QueueWorkerNotFoundError extends PikkuError {
   constructor(name: string) {
     super(`Queue processor not found: ${name}`)
   }
 }
 
-/**
- * Error class for when a queue job is explicitly failed
- */
 export class QueueJobFailedError extends PikkuError {
   constructor(jobId: string, reason?: string) {
     super(`Queue job ${jobId} failed${reason ? `: ${reason}` : ''}`)
@@ -31,18 +27,13 @@ export class QueueJobFailedError extends PikkuError {
   }
 }
 
-/**
- * Error class for when a queue job is explicitly discarded
- */
 export class QueueJobDiscardedError extends PikkuError {
   constructor(jobId: string, reason?: string) {
     super(`Queue job ${jobId} discarded${reason ? `: ${reason}` : ''}`)
     this.name = 'QueueJobDiscardedError'
   }
 }
-/**
- * Add a queue processor to the system
- */
+
 export const wireQueueWorker = <
   InputData = any,
   OutputData = any,
@@ -54,7 +45,6 @@ export const wireQueueWorker = <
 >(
   queueWorker: CoreQueueWorker<PikkuFunctionConfig>
 ) => {
-  // Get processor metadata
   const meta = pikkuState(null, 'queue', 'meta')
   const processorMeta = meta[queueWorker.name]
   if (!processorMeta) {
@@ -64,7 +54,6 @@ export const wireQueueWorker = <
     return
   }
 
-  // Register the function with pikku
   addFunction(processorMeta.pikkuFuncId, {
     func: queueWorker.func.func,
     auth: queueWorker.func.auth,
@@ -73,21 +62,14 @@ export const wireQueueWorker = <
     tags: queueWorker.func.tags,
   })
 
-  // Store processor definition in state - runtime adapters will pick this up
   const registrations = pikkuState(null, 'queue', 'registrations')
   registrations.set(queueWorker.name, queueWorker)
 }
 
-/**
- * Get all registered queue processors
- */
 export function getQueueWorkers(): Map<string, CoreQueueWorker> {
   return pikkuState(null, 'queue', 'registrations')
 }
 
-/**
- * Stop and remove a queue processor
- */
 export async function removeQueueWorker(name: string): Promise<void> {
   const registrations = pikkuState(null, 'queue', 'registrations')
   const registration = registrations.get(name)
@@ -99,9 +81,6 @@ export async function removeQueueWorker(name: string): Promise<void> {
   registrations.delete(name)
 }
 
-/**
- * Process a single queue job - this function is called by queue consumers
- */
 export async function runQueueJob({
   job,
   updateProgress,
@@ -109,7 +88,6 @@ export async function runQueueJob({
 }: {
   job: QueueJob
   updateProgress?: (progress: number | string | object) => Promise<void>
-  /** Pre-resolved trace ID (e.g. from queue message metadata) */
   traceId?: string
 }): Promise<void> {
   const singletonServices = getSingletonServices()
@@ -127,23 +105,28 @@ export async function runQueueJob({
     )
   }
 
-  // Get the queue worker registration to access middleware
   const registrations = pikkuState(null, 'queue', 'registrations')
   const queueWorker = registrations.get(job.queueName)
   if (!queueWorker) {
     throw new Error(`Queue worker registration not found for: ${job.queueName}`)
   }
 
-  // Create the queue wire object
+  // knowledge: decisions/security/queue-job-identities-are-signed-at-enqueue.md
+  const pikkuUserId = await resolveQueueJobIdentity({
+    claimedIdentity: job.pikkuUserId,
+    binding: { queueName: job.queueName, jobId: job.id, data: job.data },
+    secrets: singletonServices.secrets,
+    logger,
+  })
+
   const queue: PikkuQueue = {
     queueName: job.queueName,
     jobId: job.id,
-    pikkuUserId: job.pikkuUserId,
+    pikkuUserId,
     updateProgress:
       updateProgress ||
       (async (progress: number | string | object) => {
         logger.info(`Job ${job.id} progress: ${progress}`)
-        // Default implementation - just log the progress
       }),
     fail: async (reason?: string) => {
       throw new QueueJobFailedError(job.id, reason)
@@ -161,7 +144,6 @@ export async function runQueueJob({
       queue,
     }
 
-    // Execute the pikku function with the job data
     const result = await runPikkuFunc(
       'queue',
       job.queueName,
@@ -194,7 +176,6 @@ export async function runQueueJob({
       logger.error('Processed error response:', errorResponse)
     }
 
-    // Re-throw the error so the queue service can handle retries/DLQ
     throw error
   }
 }

package/src/wirings/queue/queue.types.ts

@@ -1,95 +1,60 @@
 import type { CommonWireMeta } from '../../types/core.types.js'
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import type { QueueConfigMapping } from './validate-worker-config.js'
+import type { Safe } from '../../secret-value.js'
 
-/**
- * Configuration for queue workers - how jobs are processed
- */
-/**
- * Configuration for queue workers - how jobs are processed
- */
 export interface PikkuWorkerConfig {
-  /** Optional worker name for identification and monitoring */
   name?: string
-  /** Number of messages to process in batch / in parallel */
+  /** Total worker concurrency. */
   batchSize?: number
-  /** Number of messages to prefetch for efficiency */
   prefetch?: number
-  /** Polling interval for pull-based queues in ms */
+  /** Milliseconds. */
   pollInterval?: number
-  /** Message visibility timeout in seconds */
+  /** Seconds. */
   visibilityTimeout?: number
-  /** Duration of job lock in milliseconds */
+  /** Milliseconds. */
   lockDuration?: number
-  /** Number of seconds to wait when queue is empty before polling again */
+  /** Seconds. */
   drainDelay?: number
-  /** Keep N completed jobs for inspection */
+  /** Number of completed jobs to retain, not an age. */
   removeOnComplete?: number
-  /** Keep N failed jobs for inspection */
+  /** Number of failed jobs to retain, not an age. */
   removeOnFail?: number
-  /** Maximum number of times a job can be recovered from stalled state */
   maxStalledCount?: number
-  /** Condition to start processor at instance creation */
   autorun?: boolean
-  /**
-   * Cap how many jobs of any one group ({@link JobOptions.group}) may run at
-   * once, so a single group can't occupy the whole worker. Lets one shared
-   * queue stay fair across producers instead of splitting it into one queue
-   * per producer — which multiplies polling cost on pull-based backends.
-   * Must not exceed {@link batchSize}.
-   */
+  /** Must not exceed {@link batchSize}. */
   groupConcurrency?: number | GroupConcurrencyConfig
 }
 
-/**
- * Per-group concurrency limits, optionally varied by tier so slow groups can
- * be allowed more (or fewer) slots than the default.
- */
 export interface GroupConcurrencyConfig {
-  /** Limit applied to any group without a matching tier */
+  /** Limit applied to any group without a matching tier. */
   default: number
-  /** Per-tier overrides, keyed by {@link JobGroup.tier} */
+  /** Keyed by {@link JobGroup.tier}. */
   tiers?: Record<string, number>
 }
 
-/**
- * Fairness key for a job. Jobs sharing an `id` count against the same
- * {@link PikkuWorkerConfig.groupConcurrency} limit.
- */
 export interface JobGroup {
-  /** Group this job belongs to (e.g. a workflow name) */
   id: string
-  /** Optional tier selecting a per-tier limit */
   tier?: string
 }
 
-/**
- * Configuration for individual jobs - how jobs behave
- */
 export interface PikkuJobConfig {
-  /** Maximum retry attempts for failed jobs */
   retryAttempts?: number
-  /** Initial retry delay in milliseconds */
+  /** Milliseconds. */
   retryDelay?: number
-  /** Retry backoff strategy */
   retryBackoff?: 'linear' | 'exponential' | 'fixed'
-  /** Queue for failed messages after max retries */
   deadLetterQueue?: string
-  /** How long to retain completed jobs in seconds */
+  /** Seconds. */
   messageRetention?: number
-  /** Job priority (higher numbers = higher priority) */
+  /** Higher numbers run first. */
   priority?: number
-  /** Enable FIFO ordering where supported */
   fifo?: boolean
-  /** Job timeout in milliseconds */
+  /** Milliseconds. */
   timeout?: number
-  /** Delay before job execution in milliseconds */
+  /** Milliseconds. */
   delay?: number
 }
 
-/**
- * Configuration validation result with warnings and fallbacks
- */
 export interface ConfigValidationResult {
   applied: Partial<PikkuWorkerConfig>
   ignored: Partial<PikkuWorkerConfig>
@@ -97,9 +62,6 @@ export interface ConfigValidationResult {
   fallbacks: { [key: string]: any }
 }
 
-/**
- * Queue job representation
- */
 export type QueueJobStatus =
   | 'waiting'
   | 'active'
@@ -126,13 +88,9 @@ export interface QueueJob<T = any, R = any> {
   result?: R
   waitForCompletion?: (ttl?: number) => Promise<R>
   metadata?: () => Promise<QueueJobMetadata> | QueueJobMetadata
-  /** Pikku user ID propagated from the job producer */
   pikkuUserId?: string
 }
 
-/**
- * Job options for queue operations
- */
 export interface JobOptions {
   priority?: number
   delay?: number
@@ -141,46 +99,34 @@ export interface JobOptions {
   removeOnComplete?: number
   removeOnFail?: number
   jobId?: string
-  /** Pikku user ID to propagate to the queue worker for credential resolution */
+  // knowledge: decisions/security/queue-jobs-carry-the-producers-pikku-user-id.md
   pikkuUserId?: string
-  /** Fairness key — counts against the worker's {@link PikkuWorkerConfig.groupConcurrency} */
+  /** Counts against the worker's {@link PikkuWorkerConfig.groupConcurrency}. */
   group?: JobGroup
 }
 
-/**
- * Queue provider interface for job publishing operations
- */
 export interface QueueService {
-  /** Whether this queue provider supports job results */
   readonly supportsResults: boolean
 
-  /** Add a job to the queue with type safety */
-  add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>
+  add<T>(
+    queueName: string,
+    data: Safe<T>,
+    options?: JobOptions
+  ): Promise<string>
 
-  /** Get job status and result */
   getJob<T, R>(queueName: string, jobId: string): Promise<QueueJob<T, R> | null>
 }
 
-/**
- * Queue service interface that queue adapters implement
- */
 export interface QueueWorkers {
-  /** Service name identifier */
   name: string
 
-  /** Whether this queue service supports job results */
   supportsResults: boolean
 
-  /** Configuration mapping for validation */
   configMappings: QueueConfigMapping
 
-  /** Scan state and register all compatible processors */
   registerQueues(): Promise<Record<string, ConfigValidationResult[]>>
 }
 
-/**
- * Queue processor metadata
- */
 export type QueueWorkersMeta = Record<
   string,
   CommonWireMeta & {
@@ -189,9 +135,6 @@ export type QueueWorkersMeta = Record<
   }
 >
 
-/**
- * Core queue processor definition
- */
 export type CoreQueueWorker<
   PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> =
     CorePikkuFunctionConfig<any, any, any>,
@@ -204,21 +147,13 @@ export type CoreQueueWorker<
   middleware?: PikkuFunctionConfig['middleware']
 }
 
-/**
- * Represents a queue wire object for middleware
- * Provides information and actions for the current queue job execution
- */
 export interface PikkuQueue {
-  /** The name of the queue being processed */
   queueName: string
-  /** The current job ID */
   jobId: string
-  /** Pikku user ID propagated from the job producer for credential resolution */
   pikkuUserId?: string
-  /** Update job progress (0-100 or custom value) */
   updateProgress: (progress: number | string | object) => Promise<void>
-  /** Fail the current job with optional reason */
+  /** Never returns — throws QueueJobFailedError. */
   fail: (reason?: string) => Promise<void>
-  /** Discard/delete the job without retrying */
+  /** Never returns — throws QueueJobDiscardedError. */
   discard: (reason?: string) => Promise<void>
 }

package/src/wirings/queue/register-queue-helper.ts

@@ -4,23 +4,11 @@ import type { QueueConfigMapping } from './validate-worker-config.js'
 import { validateWorkerConfig } from './validate-worker-config.js'
 import type { Logger } from '../../services/logger.js'
 
-/**
- * Queue processor registration callback
- */
 export type QueueRegistrationCallback<T = any> = (
   queueName: string,
   processor: CoreQueueWorker
 ) => Promise<T>
 
-/**
- * Helper function to register queue processors with validation
- * This centralizes the common logic for looping over processors and validating configs
- *
- * @param configMappings - Configuration mapping for the queue implementation
- * @param registerCallback - Callback to register each individual queue processor
- * @param logger - Optional logger for info/error messages
- * @returns Record of validation results by queue name
- */
 export async function registerQueueWorkers<T = any>(
   configMappings: QueueConfigMapping,
   logger: Logger,
@@ -31,13 +19,11 @@ export async function registerQueueWorkers<T = any>(
 
   for (const [queueName, processor] of queueWorkers) {
     logger?.info(`Registering queue processor: ${queueName}`)
-    // Validate the processor configuration
     const validationResult = validateWorkerConfig(
       configMappings,
       processor.config
     )
 
-    // Store validation results
     configValidation[queueName] = configValidation[queueName] || []
     configValidation[queueName].push(validationResult)
 

package/src/wirings/queue/signed-queue-service.ts

@@ -0,0 +1,60 @@
+import type { Safe } from '../../secret-value.js'
+import type { Logger } from '../../services/logger.js'
+import type { SecretService } from '../../services/secret-service.js'
+import {
+  getQueueIdentitySecret,
+  signQueueIdentity,
+  warnQueueIdentitySecretMissing,
+} from './queue-identity.js'
+import type { JobOptions, QueueJob, QueueService } from './queue.types.js'
+
+/**
+ * Wraps any {@link QueueService} so `JobOptions.pikkuUserId` leaves the process
+ * as a signed claim that `runQueueJob` can verify.
+ */
+export class SignedQueueService implements QueueService {
+  constructor(
+    private readonly queueService: QueueService,
+    private readonly secrets: SecretService,
+    private readonly logger: Logger
+  ) {}
+
+  get supportsResults(): boolean {
+    return this.queueService.supportsResults
+  }
+
+  public async add<T>(
+    queueName: string,
+    data: Safe<T>,
+    options?: JobOptions
+  ): Promise<string> {
+    const pikkuUserId = options?.pikkuUserId
+    if (!pikkuUserId) {
+      return this.queueService.add(queueName, data, options)
+    }
+
+    const secret = await getQueueIdentitySecret(this.secrets)
+    if (!secret) {
+      warnQueueIdentitySecretMissing(this.logger)
+      const { pikkuUserId: _unsigned, ...rest } = options as JobOptions
+      return this.queueService.add(queueName, data, rest)
+    }
+
+    const signed = await signQueueIdentity(secret, pikkuUserId, {
+      queueName,
+      jobId: undefined,
+      data,
+    })
+    return this.queueService.add(queueName, data, {
+      ...options,
+      pikkuUserId: signed,
+    })
+  }
+
+  public async getJob<T, R>(
+    queueName: string,
+    jobId: string
+  ): Promise<QueueJob<T, R> | null> {
+    return this.queueService.getJob<T, R>(queueName, jobId)
+  }
+}

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'