@pikku/core 0.12.72 → 0.12.77

package/src/function/list.types.ts

@@ -1,37 +1,10 @@
 /**
- * List-function primitives.
- *
- * A "list function" is any Pikku function that returns a paginated
- * collection. Adopting this shape unlocks a shared vocabulary across
- * MCP tools, AI agents, typed RPC clients, and widget libraries — they
- * all reason about cursor, filter, sort, and search uniformly.
- *
- * Under the hood, a list function is still a normal `pikkuFunc`. These
- * types are purely structural constraints; no runtime behaviour change.
- *
- * @example
- * ```ts
- * import { pikkuFunc } from '#pikku'
- * import type { ListInput, ListOutput } from '@pikku/core'
- *
- * export const listSessions = pikkuFunc<
- *   ListInput<{ status?: SessionStatus[] }, 'user' | 'status' | 'uploaded_at'>,
- *   ListOutput<Session>
- * >({
- *   func: async ({ kysely }, input) => {
- *     // input.sort / input.filter / input.cursor / input.search are typed
- *     return { rows, nextCursor, totalCount }
- *   },
- * })
- * ```
+ * A list function is an ordinary `pikkuFunc` whose input and output adopt
+ * these shapes. They are purely structural — no runtime behaviour attaches to
+ * them — and exist so MCP tools, agents, RPC clients and widget libraries all
+ * reason about cursor, filter, sort and search the same way.
  */
 
-/**
- * Shape every list function accepts as input.
- *
- * @template F - User-defined filter shape. Each key is a filterable field.
- * @template S - String union of sortable column names.
- */
 export interface ListInput<
   F extends Record<string, unknown> = Record<string, never>,
   S extends string = never,
@@ -42,15 +15,11 @@ export interface ListInput<
   limit?: number
   /** Ordered sort criteria — first entry is primary. */
   sort?: Array<{ column: S; direction: 'asc' | 'desc' }>
-  /** Structured filter tree. See {@link Filter}. */
   filter?: Filter<F>
   /** Unstructured text search across server-configured fields. */
   search?: string
 }
 
-/**
- * Shape every list function returns.
- */
 export interface ListOutput<Row> {
   rows: Row[]
   /** Null when no more pages. */
@@ -60,12 +29,9 @@ export interface ListOutput<Row> {
 }
 
 /**
- * Leaf predicate value on a single field.
- *
- * Operator keywords (`equals`, `not`, `in`, `notIn`, `gt`, `gte`, `lt`,
- * `lte`, `contains`, `startsWith`, `endsWith`, `mode`) mirror Prisma's
- * vocabulary for dev familiarity. These keys are reserved and cannot be
- * used as user field names in a Filter's `F` type.
+ * Leaf predicate on a single field. The operator keywords mirror Prisma's
+ * vocabulary; they are reserved and cannot be used as user field names in a
+ * Filter's `F` type.
  */
 export type LeafValue<T> =
   | T
@@ -87,33 +53,17 @@ export type LeafValue<T> =
     }
 
 /**
- * A single-key object keyed by a field name from F, value is a leaf
- * predicate. Single-key so the runtime discriminator is unambiguous:
- * multi-key objects are OR groups.
+ * A single-key object keyed by a field of F. Single-key so the runtime
+ * discriminator is unambiguous — multi-key objects are OR groups.
  */
 export type LeafFilter<F extends Record<string, unknown>> = {
   [K in keyof F]: { [Key in K]: LeafValue<F[K]> }
 }[keyof F]
 
 /**
- * Recursive filter tree.
- *
- * - `Array<Filter<F>>` — AND of children.
- * - `{ [label: string]: Filter<F> }` — OR of children. Keys are arbitrary
- *   labels (unique strings), ignored at evaluation time.
- * - `LeafFilter<F>` — single-key predicate on a declared field.
- *
- * @example "status = pending AND (therapist = kim OR therapist = park) AND uploaded_at > 2026-04-10"
- * ```ts
- * const filter: Filter<{ status: string; therapistId: string; uploadedAt: string }> = [
- *   { status: 'pending' },
- *   {
- *     kim:  { therapistId: 'kim' },
- *     park: { therapistId: 'park' },
- *   },
- *   { uploadedAt: { gt: '2026-04-10' } },
- * ]
- * ```
+ * Recursive filter tree: an array is an AND of its children; an object is an
+ * OR of its children, keyed by arbitrary unique labels that are ignored at
+ * evaluation time; a single-key object is a leaf predicate.
  */
 export type Filter<F extends Record<string, unknown>> =
   | LeafFilter<F>

package/src/handle-error.ts

@@ -4,19 +4,6 @@ import { NotFoundError } from './errors/errors.js'
 import type { Logger } from './services/logger.js'
 import type { PikkuHTTP } from './wirings/http/http.types.js'
 
-/**
- * Handle errors that occur during route processing
- *
- * @param {any} e - The error that occurred
- * @param {PikkuHTTP | undefined} http - HTTP wire object
- * @param {string} traceId - Unique ID for tracking this error
- * @param {Logger} logger - Logger service
- * @param {number[]} logWarningsForStatusCodes - HTTP status codes to log as warnings
- * @param {boolean} respondWith404 - Whether to respond with 404 for NotFoundError
- * @param {boolean} bubbleError - Whether to throw the error after handling
- * @param {boolean} exposeErrors - Whether to include internal error details (message, stack and
- * payload of 5xx errors) in the response body. Ignored in production.
- */
 export const handleHTTPError = (
   e: any,
   http: PikkuHTTP | undefined,
@@ -27,18 +14,15 @@ export const handleHTTPError = (
   bubbleError: boolean,
   exposeErrors: boolean = false
 ) => {
-  // Skip 404 handling if configured to do so
   if (e instanceof NotFoundError && !respondWith404) {
     return
   }
 
-  // Get appropriate error response
   const errorResponse = getErrorResponse(e)
   if (errorResponse != null) {
     const clientFacing =
       errorResponse.status < 500 || (exposeErrors && !isProduction())
 
-    // Set status and response body
     http?.response?.status(errorResponse.status)
     http?.response?.json({
       name: e instanceof Error ? e.name : undefined,
@@ -53,7 +37,6 @@ export const handleHTTPError = (
       errorId: traceId,
     })
 
-    // Log certain status codes as warnings
     if (logWarningsForStatusCodes.includes(errorResponse.status)) {
       if (traceId) {
         logger.warn(`Warning id: ${traceId}`)
@@ -61,7 +44,6 @@ export const handleHTTPError = (
       logger.warn(e instanceof Error ? e.message : e)
     }
   } else {
-    // Handle unexpected errors
     logger.error(e instanceof Error ? e.message : e)
     http?.response?.status(500)
 

package/src/index.ts

@@ -10,8 +10,10 @@ export type {
   CorePikkuMiddlewareFactory,
   CorePikkuMiddlewareGroup,
   CoreServices,
+  CoreSecretlessSingletonServices,
   CoreSingletonServices,
   CoreUserSession,
+  SecretlessServices,
   CreateConfig,
   ServerLifecycle,
   FunctionMeta,
@@ -89,6 +91,13 @@ export {
   parseVersionedId,
 } from './version.js'
 export { runPikkuFunc } from './function/function-runner.js'
+export {
+  AbandonedError,
+  beginChanges,
+  getAbortScope,
+  runInAbortScope,
+  type AbortScope,
+} from './function/abort-scope.js'
 export { runCLICommand, pikkuCLIRender } from './wirings/cli/cli-runner.js'
 export { fetch } from './wirings/http/http-runner.js'
 export {
@@ -103,7 +112,49 @@ export type {
 } from './wirings/mcp/mcp.types.js'
 export { runQueueJob } from './wirings/queue/queue-runner.js'
 export { runScheduledTask } from './wirings/scheduler/scheduler-runner.js'
-export { NotFoundError } from './errors/errors.js'
+export {
+  AIProviderAuthError,
+  AIProviderNotConfiguredError,
+  BadGatewayError,
+  BadRequestError,
+  ConflictError,
+  ExpectationFailedError,
+  ForbiddenError,
+  GatewayTimeoutError,
+  GoneError,
+  HTTPVersionNotSupportedError,
+  InternalServerError,
+  InvalidMiddlewareWireError,
+  InvalidOriginError,
+  InvalidSessionError,
+  LengthRequiredError,
+  LocalEnvironmentOnlyError,
+  LockedError,
+  MaxComputeTimeReachedError,
+  MethodNotAllowedError,
+  MissingCredentialError,
+  MissingSchemaError,
+  MissingScopeError,
+  MissingServiceError,
+  MissingSessionError,
+  NotAcceptableError,
+  NotFoundError,
+  NotImplementedError,
+  PayloadTooLargeError,
+  PaymentRequiredError,
+  PikkuMissingMetaError,
+  PreconditionFailedError,
+  ProxyAuthenticationRequiredError,
+  RangeNotSatisfiableError,
+  ReadonlySessionError,
+  RequestTimeoutError,
+  ServiceUnavailableError,
+  TooManyRequestsError,
+  URITooLongError,
+  UnauthorizedError,
+  UnprocessableContentError,
+  UnsupportedMediaTypeError,
+} from './errors/errors.js'
 export { PikkuError, isExpectedError } from './errors/error-handler.js'
 export type { EventHubService } from './wirings/channel/eventhub-service.js'
 export type { QueueService } from './wirings/queue/queue.types.js'
@@ -118,6 +169,14 @@ export type {
   SendTextEmailInput,
 } from './services/email-service.js'
 export type { SecretService } from './services/secret-service.js'
+export {
+  SecretAccessDeniedError,
+  withoutSecrets,
+} from './services/secretless.js'
+export {
+  SecretHostNotAllowedError,
+  assertSecretAllowedForHost,
+} from './services/secret-host-binding.js'
 export type { VariablesService } from './services/variables-service.js'
 export type {
   ContentService,
@@ -138,20 +197,23 @@ export type { SessionService } from './services/user-session-service.js'
 export {
   NoopAuditService,
   createInvocationAudit,
-  resolveAuditActorFromWire,
   resolveAuditConfig,
+  resolveAuditUserIdentityFromWire,
 } from './services/audit-service.js'
 export type {
-  AuditActor,
   AuditConfig,
   AuditDurability,
   AuditEvent,
   AuditEventBatch,
+  AuditFacets,
   AuditLog,
   AuditLogWriteInput,
   AuditOutcome,
+  AuditQuery,
+  AuditQueryResult,
   AuditService,
   AuditSource,
+  AuditUserIdentity,
   ResolvedAuditConfig,
 } from './services/audit-service.js'
 export type {
@@ -225,4 +287,23 @@ export type {
   AnonymizeStrategy,
   ColumnClassification,
   ClassificationManifest,
+  ColumnForm,
+  WrappedValue,
+  SealedValue,
+  HashedValue,
 } from './data-classification.js'
+
+export {
+  hashToken,
+  unsafeAsWrapped,
+  unsafeAsSealed,
+  unsafeAsHashed,
+} from './column-form.js'
+
+export type { SecretValue, Safe } from './secret-value.js'
+export {
+  createSecretValue,
+  isSecretValue,
+  SecretCoercionError,
+  REDACTED,
+} from './secret-value.js'

package/src/middleware/auth-apikey.test.ts

@@ -95,7 +95,6 @@ describe('authAPIKey middleware', () => {
     const jwtService = {
       encode: async () => 'token',
       decode: async (token: string) => {
-        // Should use header value, not query value
         assert.equal(token, 'header-key')
         return mockUserSession
       },

package/src/middleware/auth-apikey.ts

@@ -1,22 +1,5 @@
 import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 
-/**
- * API key middleware that retrieves a session from the 'x-api-key' header using JWT decoding.
- *
- * Extracts API key from either the 'x-api-key' header or 'apiKey' query parameter
- * and decodes it using the JWT service.
- *
- * @param options.source - Where to look for the API key: 'header', 'query', or 'all'
- *
- * @example
- * ```typescript
- * import { authAPIKey } from '@pikku/core/middleware'
- *
- * addHTTPMiddleware([
- *   authAPIKey({ source: 'header' })
- * ])
- * ```
- */
 export const authAPIKey = pikkuMiddlewareFactory<{
   source: 'header' | 'query' | 'all'
 }>(({ source }) =>

package/src/middleware/auth-bearer.test.ts

@@ -8,6 +8,7 @@ import {
   createMiddlewareSessionWireProps,
 } from '../services/user-session-service.js'
 import { InvalidSessionError } from '../errors/errors.js'
+import { createSecretValue } from '../secret-value.js'
 
 beforeEach(() => {
   resetPikkuState()
@@ -15,7 +16,6 @@ beforeEach(() => {
 
 const createMockHTTPRequest = (headers: Record<string, string> = {}) => ({
   header: (name: string) => {
-    // Check both lowercase and exact case
     return headers[name.toLowerCase()] || headers[name] || null
   },
 })
@@ -102,7 +102,6 @@ describe('authBearer middleware', () => {
     const jwtService = {
       encode: async () => 'token',
       decode: async () => {
-        // Should not be called in static token mode
         assert.fail('JWT decode should not be called in static token mode')
         return null
       },
@@ -268,7 +267,6 @@ describe('authBearer middleware', () => {
     const jwtService = {
       encode: async () => 'token',
       decode: async () => {
-        // Should not be called when static token is provided
         assert.fail('JWT decode should not be called in static token mode')
         return null
       },
@@ -432,7 +430,7 @@ describe('authBearer middleware', () => {
     const secrets = {
       getSecret: async (secretId: string) => {
         assert.equal(secretId, 'PIKKU_CONSOLE_TOKEN')
-        return 'secret-token-value'
+        return createSecretValue('secret-token-value')
       },
     }
 
@@ -503,7 +501,7 @@ describe('authBearer middleware', () => {
   test('should not set session when secret-resolved token does not match', async () => {
     const SessionService = new PikkuSessionService<CoreUserSession>()
     const secrets = {
-      getSecret: async () => 'expected-token',
+      getSecret: async () => createSecretValue('expected-token'),
     }
 
     const middleware = authBearer({

package/src/middleware/auth-bearer.ts

@@ -12,46 +12,9 @@ const constantTimeEqual = (a: string, b: string): boolean => {
 }
 
 /**
- * Bearer token middleware that extracts and validates tokens from the Authorization header.
- *
- * Supports three modes:
- * - JWT decoding (default): Decodes bearer tokens using the JWT service
- * - Static token: Provide a `token` object with a value and userSession for simple token validation
- * - Secret-resolved token: Provide a `token` object with a secretId — the expected
- *   value is resolved through the secrets service per request, so it works with any
- *   secret backend and the middleware is a no-op while the secret is unset
- *
- * @param options.token - Optional token configuration: { value, userSession } or { secretId, userSession }
- *
- * @example
- * ```typescript
- * import { authBearer } from '@pikku/core/middleware'
- *
- * // JWT mode (default)
- * addHTTPMiddleware('*', [
- *   authBearer()
- * ])
- *
- * // Static token mode
- * addHTTPMiddleware('*', [
- *   authBearer({
- *     token: {
- *       value: process.env.API_TOKEN,
- *       userSession: { userId: 'system', role: 'admin' }
- *     }
- *   })
- * ])
- *
- * // Secret-resolved token mode
- * addHTTPMiddleware('*', [
- *   authBearer({
- *     token: {
- *       secretId: 'PIKKU_CONSOLE_TOKEN',
- *       userSession: { userId: 'pikku-console-token' }
- *     }
- *   })
- * ])
- * ```
+ * Validates a bearer token: JWT-decoded by default, or compared in constant
+ * time against a static `value` or a `secretId` resolved through the secrets
+ * service per request.
  */
 export const authBearer = pikkuMiddlewareFactory<{
   token?:
@@ -92,9 +55,10 @@ export const authBearer = pikkuMiddlewareFactory<{
             expected = token.value
           } else {
             // An unset secret means the feature is off — never a request error.
-            expected = await secrets
+            const stored = await secrets
               ?.getSecret<string>(token.secretId)
               .catch(() => undefined)
+            expected = stored?.reveal()
           }
           if (expected && constantTimeEqual(bearerToken, expected)) {
             userSession = token.userSession

package/src/middleware/auth-cookie.test.ts

@@ -117,7 +117,6 @@ describe('authCookie middleware', () => {
         },
       } as any,
       async () => {
-        // Simulate session change
         SessionService.set(mockUserSession)
       }
     )
@@ -381,7 +380,6 @@ describe('authCookie middleware', () => {
         },
       } as any,
       async () => {
-        // Simulate session change
         SessionService.set(mockUserSession)
       }
     )
@@ -425,12 +423,10 @@ describe('authCookie middleware', () => {
         },
       } as any,
       async () => {
-        // Simulate session change
         SessionService.set(mockUserSession)
       }
     )
 
-    // Should complete without errors even though response is not available
     assert.equal(SessionService.get(), mockUserSession)
   })
 
@@ -468,7 +464,6 @@ describe('authCookie middleware', () => {
         },
       } as any,
       async () => {
-        // Modify session to trigger cookie setting
         SessionService.set({ ...mockUserSession, extra: 'data' })
       }
     )
@@ -519,7 +514,6 @@ describe('authCookie middleware', () => {
     const expiresDate = setCookies[0].options.expires
     assert(expiresDate instanceof Date)
 
-    // Expiration should be approximately 15 minutes from now
     const expectedExpiry = new Date(beforeTime.getTime() + 15 * 60 * 1000)
     const timeDiff = Math.abs(expiresDate.getTime() - expectedExpiry.getTime())
     // Allow 5 second tolerance for test execution time

package/src/middleware/auth-cookie.ts

@@ -4,32 +4,8 @@ import type { RelativeTimeInput } from '../time-utils.js'
 import { getRelativeTimeOffsetFromNow } from '../time-utils.js'
 
 /**
- * Cookie-based session middleware that uses JWT for encoding/decoding session data.
- *
- * Reads session from a cookie on incoming requests and automatically updates the cookie
- * when the session changes (e.g., after login).
- *
- * @param options.name - Cookie name
- * @param options.expiresIn - Cookie expiration time (e.g., { value: 30, unit: 'day' })
- * @param options.options - Cookie serialization options (httpOnly, secure, sameSite, etc.)
- *
- * @example
- * ```typescript
- * import { authCookie } from '@pikku/core/middleware'
- *
- * addHTTPMiddleware([
- *   authCookie({
- *     name: 'session',
- *     expiresIn: { value: 30, unit: 'day' },
- *     options: {
- *       httpOnly: true,
- *       secure: true,
- *       sameSite: 'strict',
- *       path: '/'
- *     }
- *   })
- * ])
- * ```
+ * Reads a JWT session from a cookie, and re-issues the cookie after the
+ * request whenever the session changed (e.g. after login).
  */
 export const authCookie = pikkuMiddlewareFactory<{
   name: string

package/src/middleware/cors.test.ts

@@ -243,6 +243,40 @@ describe('cors', () => {
       )
     })
 
+    test('should not expose any headers by default', async () => {
+      const middleware = cors()
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Expose-Headers'],
+        undefined
+      )
+    })
+
+    test('should set exposed headers', async () => {
+      const middleware = cors({ exposeHeaders: ['X-Custom', 'X-Other'] })
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Expose-Headers'],
+        'X-Custom, X-Other'
+      )
+    })
+
     test('should not set Vary when origin is string', async () => {
       const middleware = cors({ origin: 'https://example.com' })
       const request = createMockRequest()

package/src/middleware/cors.ts

@@ -1,44 +1,15 @@
 import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 
 /**
- * CORS middleware that handles cross-origin requests including OPTIONS preflight.
- *
- * Sets appropriate CORS headers on all responses and short-circuits OPTIONS
- * preflight requests with a 204 No Content response.
- *
- * @param options.origin - Allowed origin(s). Use `'*'` for any origin, `true` to reflect the request origin, a string for a single origin, or an array for multiple origins. Defaults to `'*'`.
- * @param options.methods - Allowed HTTP methods. Defaults to common methods.
- * @param options.headers - Allowed request headers. Defaults to common headers.
- * @param options.credentials - Whether to allow credentials. Defaults to `false`.
- * @param options.maxAge - Preflight cache duration in seconds. Defaults to `86400` (24 hours).
- *
- * @example
- * ```typescript
- * import { cors } from '@pikku/core/middleware'
- *
- * // Allow all origins
- * addHTTPMiddleware('*', [cors()])
- *
- * // Specific origin with credentials
- * addHTTPMiddleware('*', [
- *   cors({
- *     origin: 'https://app.example.com',
- *     credentials: true,
- *   })
- * ])
- *
- * // Multiple origins
- * addHTTPMiddleware('*', [
- *   cors({
- *     origin: ['https://app.example.com', 'https://admin.example.com'],
- *   })
- * ])
- * ```
+ * Sets CORS headers on every response and short-circuits OPTIONS preflight
+ * with a 204. `origin: true` reflects the request origin; an array reflects a
+ * matching origin and otherwise falls back to its first entry.
  */
 export const cors = pikkuMiddlewareFactory<{
   origin?: string | string[] | true
   methods?: string[]
   headers?: string[]
+  exposeHeaders?: string[]
   credentials?: boolean
   maxAge?: number
 }>(
@@ -46,6 +17,7 @@ export const cors = pikkuMiddlewareFactory<{
     origin = '*',
     methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
     headers = ['Content-Type', 'Authorization', 'x-api-key'],
+    exposeHeaders = [],
     credentials = false,
     maxAge = 86400,
   } = {}) => {
@@ -83,6 +55,13 @@ export const cors = pikkuMiddlewareFactory<{
         response.header('Access-Control-Allow-Methods', methods.join(', '))
         response.header('Access-Control-Allow-Headers', headers.join(', '))
 
+        if (exposeHeaders.length > 0) {
+          response.header(
+            'Access-Control-Expose-Headers',
+            exposeHeaders.join(', ')
+          )
+        }
+
         if (credentials) {
           response.header('Access-Control-Allow-Credentials', 'true')
         }