@pikku/core 0.12.71 → 0.12.74

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

@@ -12,7 +12,7 @@ import type {
   CorePikkuFunctionSessionless,
 } from '../../function/functions.types.js'
 import { getErrorResponse } from '../../errors/error-handler.js'
-import { closeWireServices } from '../../utils.js'
+import { isProduction } from '../../env.js'
 import {
   pikkuState,
   getSingletonServices,
@@ -35,6 +35,8 @@ export class MCPError extends Error {
 
 export type RunMCPEndpointParams<Tools extends string = any> = {
   mcp?: PikkuMCP<Tools>
+  /** Defaults to enabled outside production. */
+  exposeErrors?: boolean
 }
 
 export type JsonRpcError = {
@@ -106,13 +108,11 @@ export async function runMCPResource(
     pikkuFuncId = metas[uri]?.pikkuFuncId
   } else {
     for (const [uriTemplate, value] of endpoints.entries()) {
-      // Extract parameter names from the template
       const paramNames = Array.from(
         uriTemplate.matchAll(/\{([^}]+)\}/g),
         (m) => m[1]
       )
 
-      // Create regex pattern to match and capture parameter values
       const regexPattern = uriTemplate.replace(/\{[^}]+\}/g, '([^/]+)')
       const regex = new RegExp(`^${regexPattern}$`)
       const match = uri.match(regex)
@@ -121,7 +121,6 @@ export async function runMCPResource(
         endpoint = value
         pikkuFuncId = metas[uriTemplate]?.pikkuFuncId
 
-        // Extract parameter values and create params object
         for (let i = 0; i < paramNames.length; i++) {
           extractedParams[paramNames[i]!] = match[i + 1]! // match[0] is the full match
         }
@@ -178,20 +177,16 @@ export async function runMCPPrompt(
   )
 }
 
-/**
- * JSON-RPC 2.0 compatible MCP endpoint runner
- */
 async function runMCPPikkuFunc(
   request: JsonRpcRequest,
   type: 'resource' | 'tool' | 'prompt',
   name: string,
   mcp: CoreMCPResource | CoreMCPPrompt | undefined,
   pikkuFuncId: string | undefined,
-  { mcp: mcpWire }: RunMCPEndpointParams
+  { mcp: mcpWire, exposeErrors = !isProduction() }: RunMCPEndpointParams
 ): Promise<JsonRpcResponse> {
   const singletonServices = getSingletonServices()
   const createWireServices = getCreateWireServices()
-  let wireServices: any
 
   try {
     if (request.jsonrpc !== '2.0') {
@@ -231,7 +226,6 @@ async function runMCPPikkuFunc(
       meta = pikkuState(null, 'mcp', 'promptsMeta')[name]
     }
 
-    // Resolve namespaced function IDs (e.g., 'swaggerPetstore:findPetsByStatus')
     let resolvedFuncName = pikkuFuncId
     let resolvedPackageName: string | null = meta?.packageName ?? null
     if (pikkuFuncId.includes(':')) {
@@ -289,13 +283,13 @@ async function runMCPPikkuFunc(
         id: request.id,
         code: -32603,
         message: 'Internal error',
-        data: { message: e.message, stack: e.stack },
+        // knowledge: decisions/security/mcp-internal-error-details-are-double-gated-on-production.md
+        data:
+          exposeErrors && !isProduction() && e instanceof Error
+            ? { message: e.message, stack: e.stack }
+            : undefined,
       })
     }
-  } finally {
-    if (wireServices) {
-      await closeWireServices(singletonServices.logger, wireServices)
-    }
   }
 }
 

package/src/wirings/mcp/mcp.types.ts

@@ -8,10 +8,7 @@ import type {
   MiddlewareMetadata,
 } from '../../types/core.types.js'
 
-/**
- * Extract URI parameters from MCP resource URI template.
- * E.g., "user/{userId}/post/{postId}" => "userId" | "postId"
- */
+/** "user/{userId}/post/{postId}" => "userId" | "postId" */
 type ExtractMCPURIParams<S extends string> =
   S extends `${string}{${infer Param}}/${infer Rest}`
     ? Param | ExtractMCPURIParams<Rest>
@@ -19,10 +16,7 @@ type ExtractMCPURIParams<S extends string> =
       ? Param
       : never
 
-/**
- * Type-level assertion that MCP resource URI parameters are present in the input type.
- * This ensures compile-time safety for URI parameter validation.
- */
+/** Resolves to a tuple of error strings, not `never`, so the mismatch surfaces in the type error. */
 export type AssertMCPResourceURIParams<In, URI extends string> =
   ExtractMCPURIParams<URI> extends keyof In
     ? unknown
@@ -34,7 +28,6 @@ export type AssertMCPResourceURIParams<In, URI extends string> =
       ]
 
 export type PikkuMCP<Tools extends string = any> = {
-  // elicitInput: <Input>(message: string) => Promise<{ action: string, content: Input }>
   uri?: string
   sendResourceUpdated: (uri: string) => void
   enableResources: (resources: Record<string, boolean>) => Promise<boolean>
@@ -42,35 +35,26 @@ export type PikkuMCP<Tools extends string = any> = {
   enableTools: (tools: Record<Tools, boolean>) => Promise<boolean>
 }
 
-/**
- * Represents metadata for MCP resources, including name, description, and documentation.
- */
 export type MCPResourceMeta = Record<
   string,
   Omit<CoreMCPResource, 'func' | 'middleware'> & {
     pikkuFuncId: string
     inputSchema: string | null
     outputSchema: string | null
-    middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
+    middleware?: MiddlewareMetadata[] // tag + explicit, already merged
   }
 >
 
-/**
- * Represents metadata for MCP tools, including name, description, and documentation.
- */
 export type MCPToolMeta = Record<
   string,
   Omit<CoreMCPTool, 'func' | 'middleware'> & {
     pikkuFuncId: string
     inputSchema: string | null
     outputSchema: string | null
-    middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
+    middleware?: MiddlewareMetadata[] // tag + explicit, already merged
   }
 >
 
-/**
- * Represents metadata for MCP prompts, including name, description, and arguments.
- */
 export type MCPPromptMeta = Record<
   string,
   Omit<CoreMCPPrompt, 'func' | 'middleware'> & {
@@ -82,13 +66,10 @@ export type MCPPromptMeta = Record<
       description: string
       required: boolean
     }>
-    middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
+    middleware?: MiddlewareMetadata[] // tag + explicit, already merged
   }
 >
 
-/**
- * Represents an MCP resource with specific properties.
- */
 export type CoreMCPResource<
   PikkuFunctionConfig = CorePikkuFunctionConfig<
     CorePikkuFunctionSessionless<any, any>
@@ -109,9 +90,6 @@ export type CoreMCPResource<
   middleware?: PikkuMiddleware[]
 }
 
-/**
- * Represents an MCP tool with specific properties.
- */
 export type CoreMCPTool<
   PikkuFunctionConfig = CorePikkuFunctionConfig<
     CorePikkuFunctionSessionless<any, any>
@@ -130,9 +108,6 @@ export type CoreMCPTool<
   middleware?: PikkuMiddleware[]
 }
 
-/**
- * Represents an MCP prompt with specific properties.
- */
 export type CoreMCPPrompt<
   PikkuFunctionConfig = CorePikkuFunctionConfig<
     CorePikkuFunctionSessionless<any, MCPPromptResponse>
@@ -167,21 +142,15 @@ export type JsonRpcErrorResponse = {
   data?: any
 }
 
-/**
- * Represents a message in an MCP prompt response
- */
 export type MCPPromptMessage = {
   role: 'user' | 'assistant' | 'system'
   content: {
     type: 'text' | 'image'
     text: string
-    data?: string // for image content
+    data?: string
   }
 }
 
-/**
- * Standard response type for MCP prompts - array of messages
- */
 export type MCPPromptResponse = MCPPromptMessage[]
 
 export type MCPResourceMessage = {
@@ -191,10 +160,6 @@ export type MCPResourceMessage = {
 
 export type MCPResourceResponse = MCPResourceMessage[]
 
-/**
- * Standard response type for MCP prompts - array of messages
- */
-
 export type MCPToolMessage =
   | {
       type: 'text'
@@ -202,7 +167,7 @@ export type MCPToolMessage =
     }
   | {
       type: 'image'
-      data: string // base64 encoded image data
+      data: string // base64
     }
 
 export type MCPToolResponse = MCPToolMessage[]

package/src/wirings/oauth2/oauth2.types.ts

@@ -1,19 +1,8 @@
-/**
- * OAuth2 credential and token types.
- */
-
-/**
- * App credentials for OAuth2 (client ID and secret).
- * These are typically set once and stored in the secret service.
- */
 export type OAuth2AppCredential = {
   clientId: string
   clientSecret?: string // Optional for PKCE flows
 }
 
-/**
- * OAuth2 token data returned from token endpoint.
- */
 export type OAuth2Token = {
   accessToken: string
   refreshToken?: string
@@ -21,22 +10,3 @@ export type OAuth2Token = {
   tokenType: string
   scope?: string
 }
-
-/**
- * OAuth2-specific configuration that extends a credential.
- * This is stored in SecretDefinitionMeta.oauth2 field.
- */
-export type OAuth2Config = {
-  /** Where access/refresh tokens are stored */
-  tokenSecretId: string
-  /** OAuth2 authorization URL */
-  authorizationUrl: string
-  /** OAuth2 token exchange URL */
-  tokenUrl: string
-  /** Required scopes */
-  scopes: string[]
-  /** Use PKCE flow */
-  pkce?: boolean
-  /** Additional query parameters for authorization URL */
-  additionalParams?: Record<string, string>
-}

package/src/wirings/persona/define-personas.ts

@@ -0,0 +1,29 @@
+import type { CorePersonas } from './persona.types.js'
+
+/**
+ * No-op function for declaring personas.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `PersonaId` union
+ * and a `personas.gen.json` the console and `pikku persona run` read off disk —
+ * describing, listing or running one never has to load the app.
+ *
+ * `definePersonas` rather than `defineVirtualUsers` because declaring is not
+ * running: a persona that exists only to be acted upon (the account an admin
+ * bans, the colleague a document is shared with) is seeded and never run.
+ *
+ * @example
+ * ```typescript
+ * definePersonas({
+ *   susan: {
+ *     name: 'Susan',
+ *     jobTitle: 'Buys for a small café',
+ *     roles: ['buyer'],
+ *     personality: 'Hunts cheap deals. Tries three coupon codes before giving up.',
+ *     goals: ['Get the weekly order in under five minutes'],
+ *     disposition: 'careless',
+ *     account: {},
+ *   },
+ * })
+ * ```
+ */
+export const definePersonas = (_config: CorePersonas): void => {}

package/src/wirings/persona/index.ts

@@ -0,0 +1,62 @@
+export { definePersonas } from './define-personas.js'
+export {
+  isRunnablePersona,
+  roleMismatchMessage,
+  runnablePersonas,
+  validateAndBuildPersonasMeta,
+  verifyPersonaRoles,
+} from './validate-personas.js'
+export type { RoleVerification } from './validate-personas.js'
+export {
+  personaEnvironmentErrors,
+  personaEnvironmentRefusal,
+  resolvePersonaEnvironments,
+} from './persona-environments.js'
+export type {
+  PersonaEnvironment,
+  PersonaEnvironmentSubject,
+} from './persona-environments.js'
+export {
+  personaEmail,
+  personaEmailLabel,
+  personaEmails,
+} from './persona-email.js'
+export {
+  allowedLinks,
+  applyMailboxAllowlist,
+  isAllowedSender,
+} from './persona-mailbox.js'
+export type {
+  MailboxAllowlist,
+  PersonaMailbox,
+  ReceivedEmail,
+} from './persona-mailbox.js'
+export type {
+  CorePersona,
+  CorePersonaAccount,
+  CorePersonas,
+  PersonaAccountMeta,
+  PersonaDefinitions,
+  PersonaMeta,
+  PersonasMeta,
+} from './persona.types.js'
+
+/**
+ * Signing in as a persona and talking to a stage over HTTP.
+ *
+ * Deliberately reached through this entry point rather than `@pikku/core/services`.
+ * `HttpPersona` pulls in the actor-flow conversation runner and, through it, the
+ * agent runner — none of which a production server has any use for. Exporting it
+ * from the services barrel put that chain in the module graph of every app that
+ * imports services, which only a bundler could remove and an unbundled Node or
+ * Lambda deploy would load outright.
+ */
+export {
+  HttpPersona,
+  createHttpPersonas,
+  type HttpPersonasConfig,
+} from '../../services/http-personas.js'
+export {
+  postScenarioJson,
+  readScenarioHttpResponse,
+} from '../../services/personas-service.js'

package/src/wirings/persona/persona-email.ts

@@ -0,0 +1,87 @@
+/**
+ * A persona's email address is computed, never declared.
+ *
+ * A persona that cannot read its own email cannot complete sign-up, magic
+ * links, invites or password resets — which are most of the flows worth
+ * exercising. So addresses are real and deliverable against a domain the stage
+ * actually receives mail on, rather than a synthetic `.local` dead end.
+ */
+
+const LABEL = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
+
+/**
+ * Lower-cases and strips a persona id down to something an address can carry.
+ *
+ * Personas are declared as object keys, so they are already identifier-shaped;
+ * this exists for the ones that are not (`'susan.buyer'`, `'Susan_2'`) rather
+ * than to permit arbitrary input.
+ */
+export const personaEmailLabel = (personaId: string): string => {
+  const label = personaId
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  if (!LABEL.test(label)) {
+    throw new Error(
+      `Persona '${personaId}' has no usable email label. A persona id must contain at least one letter or digit.`
+    )
+  }
+  return label
+}
+
+/**
+ * The address a persona reads mail at during a run.
+ *
+ * The `runId` suffix is not decoration. Without it two concurrent runs share an
+ * inbox *and* a user row, and run B reads run A's magic link. Sub-addressing
+ * also buys isolation for free: a different address is a different account in
+ * the app, so two runs cannot collide on sign-up either.
+ *
+ * Omitting `runId` gives the bare form, which is what a seeded fixture that has
+ * to stay stable across runs wants.
+ */
+export const personaEmail = (
+  personaId: string,
+  domain: string,
+  runId?: string
+): string => {
+  const label = personaEmailLabel(personaId)
+  const cleanDomain = domain.trim().toLowerCase().replace(/^@/, '')
+  if (!cleanDomain || cleanDomain.includes('@') || !cleanDomain.includes('.')) {
+    throw new Error(
+      `Persona email domain '${domain}' is not a domain. Set it to a domain the stage actually receives mail on.`
+    )
+  }
+  const suffix = runId ? `+${personaEmailLabel(runId)}` : ''
+  return `${label}${suffix}@${cleanDomain}`
+}
+
+/**
+ * Every address in a run, keyed by persona.
+ *
+ * All of a persona's logins share one address. That is not a simplification:
+ * better-auth keeps `email` on the `user` and defaults `allowDifferentEmails`
+ * to false, so giving a linked account its own address would have the library
+ * under test refuse to link the very thing the persona declared as linked.
+ */
+export const personaEmails = (
+  personaIds: readonly string[],
+  domain: string,
+  runId?: string
+): Record<string, string> => {
+  const emails: Record<string, string> = {}
+  const seen = new Map<string, string>()
+  for (const id of personaIds) {
+    const address = personaEmail(id, domain, runId)
+    const collidesWith = seen.get(address)
+    if (collidesWith !== undefined) {
+      throw new Error(
+        `Personas '${collidesWith}' and '${id}' both compute the address ${address}. ` +
+          `They would share a user row and read each other's email.`
+      )
+    }
+    seen.set(address, id)
+    emails[id] = address
+  }
+  return emails
+}

package/src/wirings/persona/persona-environments.test.ts

@@ -0,0 +1,183 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+import {
+  personaEnvironmentErrors,
+  personaEnvironmentRefusal,
+  resolvePersonaEnvironments,
+} from './persona-environments.js'
+
+const ENVIRONMENTS = {
+  local: {},
+  staging: {},
+  prod: { production: true },
+  'eu-prod': { production: true },
+}
+
+describe('resolvePersonaEnvironments', () => {
+  // The default that makes production opt-in: a persona nobody thought about
+  // runs everywhere it is harmless and nowhere it is not.
+  test('omitting environments means everywhere but production', () => {
+    assert.deepEqual(resolvePersonaEnvironments({}, ENVIRONMENTS), [
+      'local',
+      'staging',
+    ])
+  })
+
+  test('a declared list is taken verbatim, production included', () => {
+    assert.deepEqual(
+      resolvePersonaEnvironments(
+        { disposition: 'accountable', environments: ['staging', 'prod'] },
+        ENVIRONMENTS
+      ),
+      ['staging', 'prod']
+    )
+  })
+
+  test('more than one environment can be production', () => {
+    assert.deepEqual(
+      resolvePersonaEnvironments({}, { a: {}, b: { production: true } }),
+      ['a']
+    )
+  })
+})
+
+describe('personaEnvironmentErrors', () => {
+  test('a persona that declares nothing cannot be wrong', () => {
+    assert.deepEqual(
+      personaEnvironmentErrors('shopper', { disposition: 'careless' }, ENVIRONMENTS),
+      []
+    )
+  })
+
+  test('an accountable persona may name production', () => {
+    assert.deepEqual(
+      personaEnvironmentErrors(
+        'robin',
+        { disposition: 'accountable', environments: ['staging', 'prod'] },
+        ENVIRONMENTS
+      ),
+      []
+    )
+  })
+
+  test('a testing disposition naming production is an error', () => {
+    const [error, ...rest] = personaEnvironmentErrors(
+      'shopper',
+      { disposition: 'careless', environments: ['prod'] },
+      ENVIRONMENTS
+    )
+    assert.deepEqual(rest, [])
+    assert.match(error!, /names production environment 'prod'/)
+    assert.match(error!, /'careless'/)
+    assert.match(error!, /disposition 'accountable'/)
+  })
+
+  // The default disposition is `realistic`, which is still a testing one. A
+  // persona that declares no disposition at all must not slip into production
+  // on the strength of having said nothing.
+  test('no disposition at all is reported as realistic, and refused', () => {
+    const [error] = personaEnvironmentErrors(
+      'quiet',
+      { environments: ['prod'] },
+      ENVIRONMENTS
+    )
+    assert.match(error!, /'realistic'/)
+  })
+
+  test('every offending environment is reported, not just the first', () => {
+    const errors = personaEnvironmentErrors(
+      'shopper',
+      { disposition: 'careless', environments: ['prod', 'eu-prod'] },
+      ENVIRONMENTS
+    )
+    assert.equal(errors.length, 2)
+  })
+
+  // A typo silently narrows the persona to nothing, which is the same class of
+  // bug the rule exists to prevent — only quieter.
+  test('an unknown environment names the ones that exist', () => {
+    const [error] = personaEnvironmentErrors(
+      'shopper',
+      { environments: ['stagng'] },
+      ENVIRONMENTS
+    )
+    assert.match(error!, /'stagng', which is not configured/)
+    assert.match(error!, /local, staging, prod, eu-prod/)
+  })
+
+  test('with nothing configured it says where environments go', () => {
+    const [error] = personaEnvironmentErrors('shopper', { environments: ['x'] }, {})
+    assert.match(error!, /Declare it under 'environments' in pikku\.config\.json/)
+  })
+})
+
+describe('personaEnvironmentRefusal', () => {
+  const accountable = {
+    disposition: 'accountable' as const,
+    environments: ['staging', 'prod'],
+  }
+
+  test('lets a declared environment through', () => {
+    assert.equal(
+      personaEnvironmentRefusal('robin', accountable, 'prod', ENVIRONMENTS),
+      null
+    )
+  })
+
+  // Fail closed. An unresolved PIKKU_ENV is precisely the case where the build
+  // check was passed by a different artifact than the one now running, so
+  // "I don't know where I am" must not read as permission.
+  test('an unresolved environment refuses everybody', () => {
+    const refusal = personaEnvironmentRefusal(
+      'robin',
+      accountable,
+      undefined,
+      ENVIRONMENTS
+    )
+    assert.match(refusal!, /no environment is resolved/)
+    assert.match(refusal!, /PIKKU_ENV/)
+  })
+
+  test('an unrecognised environment refuses rather than assuming staging', () => {
+    const refusal = personaEnvironmentRefusal(
+      'robin',
+      accountable,
+      'somewhere-else',
+      ENVIRONMENTS
+    )
+    assert.match(refusal!, /is not configured/)
+  })
+
+  // The check the deployed artifact cannot have been trusted on: whatever the
+  // file said, this persona is not allowed to act on real data.
+  test('production refuses a testing disposition whatever it declared', () => {
+    const refusal = personaEnvironmentRefusal(
+      'shopper',
+      { disposition: 'adversarial', environments: ['prod'] },
+      'prod',
+      ENVIRONMENTS
+    )
+    assert.match(refusal!, /only 'accountable' may act on real data/)
+  })
+
+  test('an environment outside the declared list is refused', () => {
+    const refusal = personaEnvironmentRefusal(
+      'robin',
+      accountable,
+      'local',
+      ENVIRONMENTS
+    )
+    assert.match(refusal!, /it declares environments staging, prod/)
+  })
+
+  test('a persona declaring nothing still runs everywhere but production', () => {
+    assert.equal(
+      personaEnvironmentRefusal('shopper', {}, 'staging', ENVIRONMENTS),
+      null
+    )
+    assert.match(
+      personaEnvironmentRefusal('shopper', {}, 'prod', ENVIRONMENTS)!,
+      /only 'accountable' may act on real data/
+    )
+  })
+})