@pikku/core 0.12.72 → 0.12.77

package/src/services/index.ts

@@ -1,7 +1,3 @@
-/**
- * @module @pikku/core
- */
-
 export { LogLevel } from './logger.js'
 export { ScopedSecretService } from './scoped-secret-service.js'
 export {
@@ -41,20 +37,19 @@ export type {
   CopyFileArgs,
 } from './content-service.js'
 export type {
-  ScenarioActor,
-  ScenarioActorConfig,
-  ScenarioActorOf,
-  ScenarioActors,
+  ScenarioPersona,
+  ResolvedPersona,
+  ScenarioPersonaOf,
+  ScenarioPersonas,
   ScenarioInvokeOptions,
   ScenarioRpcMap,
   ScenarioHttpResponse,
-} from './scenario-actors-service.js'
-export { readScenarioHttpResponse } from './scenario-actors-service.js'
-export {
-  HttpScenarioActor,
-  createHttpScenarioActors,
-  type HttpScenarioActorsConfig,
-} from './http-scenario-actors.js'
+} from './personas-service.js'
+// The persona runtime — `HttpPersona`, `createHttpPersonas`,
+// `readScenarioHttpResponse`, `postScenarioJson` — is exported from
+// `@pikku/core/persona`, not from here. Types are free; those are values, and
+// they reach the actor-flow and agent runners, which no production server runs.
+export type { HttpPersonasConfig } from './http-personas.js'
 export type { JWTService } from './jwt-service.js'
 export type {
   EmailService,
@@ -80,7 +75,7 @@ export {
   type WebhookServiceConfig,
 } from './webhook-service.js'
 export type { Logger } from './logger.js'
-export type { SecretService } from './secret-service.js'
+export type { SecretService, SecretValues } from './secret-service.js'
 export type { VariablesService } from './variables-service.js'
 export type { SchemaService } from './schema-service.js'
 export type { SessionService } from './user-session-service.js'
@@ -137,14 +132,19 @@ export type { VariableStatus, VariableMeta } from './typed-variables-service.js'
 export type { MetaService } from './meta-service.js'
 export type { SessionStore } from './session-store.js'
 export type { ScopeService, Role } from './scope-service.js'
+export {
+  assertRoleIsMutable,
+  assertRoleNameAvailable,
+  roleLockReason,
+} from './system-role-guard.js'
+export type { IsSystemRole } from './system-role-guard.js'
 export {
   NoopAuditService,
   createInvocationAudit,
-  resolveAuditActorFromWire,
   resolveAuditConfig,
+  resolveAuditUserIdentityFromWire,
 } from './audit-service.js'
 export type {
-  AuditActor,
   AuditConfig,
   AuditDurability,
   AuditEvent,
@@ -154,6 +154,7 @@ export type {
   AuditOutcome,
   AuditService,
   AuditSource,
+  AuditUserIdentity,
   ResolvedAuditConfig,
 } from './audit-service.js'
 export { InMemorySessionStore } from './in-memory-session-store.js'
@@ -200,3 +201,7 @@ export {
   spy,
   type StubCall,
 } from './stub-tracker.js'
+export {
+  SecretHostNotAllowedError,
+  assertSecretAllowedForHost,
+} from './secret-host-binding.js'

package/src/services/istanbul-coverage-service.ts

@@ -22,11 +22,7 @@ type IstanbulCoverageGlobal = Record<string, IstanbulFileCoverage>
 const getCoverageGlobal = (): IstanbulCoverageGlobal | undefined =>
   (globalThis as { __coverage__?: IstanbulCoverageGlobal }).__coverage__
 
-/**
- * Reads istanbul-instrumented counters from the `__coverage__` global —
- * the coverage backend for runtimes without V8 precise coverage (e.g. Bun,
- * where source files are instrumented at load time by a Bun loader plugin).
- */
+/** The coverage backend for runtimes without V8 precise coverage, e.g. Bun. */
 export class IstanbulCoverageService implements CoverageService {
   async start(): Promise<void> {}
 
@@ -39,9 +35,7 @@ export class IstanbulCoverageService implements CoverageService {
         hits = new Map()
         lineHits.set(file.path, hits)
       }
-      // istanbul line semantics: a statement's count belongs to its start
-      // line only, so an enclosing multi-line statement never masks an
-      // unexecuted inner statement (e.g. a throw inside a taken if).
+      // knowledge: decisions/internals/istanbul-statement-counts-attach-to-the-start-line-only.md
       for (const [id, location] of Object.entries(file.statementMap)) {
         const count = file.s[id] ?? 0
         const line = location.start.line

package/src/services/jwt-service.ts

@@ -1,27 +1,12 @@
 import type { RelativeTimeInput } from '../time-utils.js'
 
-/**
- * Interface for handling JSON Web Tokens (JWT).
- */
 export interface JWTService {
-  /**
-   * Encodes a payload into a JWT.
-   * @param expiresIn - The expiration time of the token.
-   * @param payload - The payload to encode.
-   * @returns A promise that resolves to the encoded JWT.
-   */
   encode: <T extends any>(
     expiresIn: RelativeTimeInput,
     payload: T
   ) => Promise<string>
 
-  /**
-   * Decodes a JWT into its payload.
-   * @param hash - The JWT to decode.
-   * @param invalidHashError - An optional error to throw if the hash is invalid.
-   * @param debug - An optional flag for debugging.
-   * @returns A promise that resolves to the decoded payload.
-   */
+  /** `invalidHashError` replaces the implementation's own error when the hash does not verify. */
   decode: <T>(
     hash: string,
     invalidHashError?: Error,

package/src/services/local-content-request-handler.test.ts

@@ -0,0 +1,202 @@
+import { describe, test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { JWTService, Logger } from './index.js'
+import { LocalContent } from './local-content.js'
+import { createLocalContentRequestHandler } from './local-content-request-handler.js'
+
+const noopLogger = {
+  info: () => {},
+  error: () => {},
+  warn: () => {},
+  debug: () => {},
+  trace: () => {},
+  setLevel: () => {},
+} as unknown as Logger
+
+const fakeJWT = {
+  encode: async (_expiry: string, payload: unknown) =>
+    Buffer.from(JSON.stringify(payload)).toString('base64url'),
+  decode: async (token: string) =>
+    JSON.parse(Buffer.from(token, 'base64url').toString()),
+} as unknown as JWTService
+
+describe('createLocalContentRequestHandler', () => {
+  let tmpDir: string
+  let handler: ReturnType<typeof createLocalContentRequestHandler>
+  let content: LocalContent
+
+  before(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'pikku-content-handler-'))
+    mkdirSync(join(tmpDir, 'bucket'), { recursive: true })
+    writeFileSync(join(tmpDir, 'bucket', 'existing.bin'), 'already here')
+
+    const config = {
+      localFileUploadPath: tmpDir,
+      uploadUrlPrefix: '/upload',
+      assetUrlPrefix: '/assets',
+      sizeLimit: '1mb',
+    }
+    content = new LocalContent(config, noopLogger, fakeJWT)
+    handler = createLocalContentRequestHandler({
+      content: config,
+      logger: noopLogger,
+      getJWT: () => fakeJWT,
+    })
+  })
+
+  after(() => {
+    rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  test('returns null for a path outside both prefixes', async () => {
+    const result = await handler(
+      new Request('http://localhost/uploadsomething')
+    )
+    assert.equal(result, null)
+  })
+
+  test('returns null for a method neither prefix handles', async () => {
+    const result = await handler(
+      new Request('http://localhost/upload/bucket/x.bin', { method: 'GET' })
+    )
+    assert.equal(result, null)
+  })
+
+  // Encoded SEPARATORS, not encoded dots. `%2e%2e` never reaches the handler:
+  // the URL parser treats it as a double-dot segment and resolves it away, so
+  // the path arrives already outside the prefix. `%2f` survives parsing intact
+  // and only becomes a separator when the handler decodes it — which is the one
+  // way a `..` can still be sitting in the key by the time it is resolved, and
+  // therefore the case the guard actually has to catch.
+  test('refuses an upload whose key escapes the content directory', async () => {
+    writeFileSync(join(tmpDir, '..', 'pikku-handler-secret.txt'), 'secret')
+    try {
+      const response = await handler(
+        new Request(
+          'http://localhost/upload/bucket/..%2f..%2fpikku-handler-secret.txt',
+          { method: 'PUT', body: 'overwritten' }
+        )
+      )
+      assert.equal(response?.status, 400)
+      assert.equal(
+        readFileSync(join(tmpDir, '..', 'pikku-handler-secret.txt'), 'utf8'),
+        'secret'
+      )
+    } finally {
+      rmSync(join(tmpDir, '..', 'pikku-handler-secret.txt'), { force: true })
+    }
+  })
+
+  test('refuses an asset read whose key escapes the content directory', async () => {
+    const response = await handler(
+      new Request('http://localhost/assets/bucket/..%2f..%2fanything.txt')
+    )
+    assert.equal(response?.status, 400)
+  })
+
+  test('round-trips an upload and a signed read', async () => {
+    const { uploadUrl } = await content.getUploadURL({
+      bucket: 'bucket',
+      fileKey: 'round/trip.bin',
+      contentType: 'application/octet-stream',
+    } as any)
+    const put = await handler(
+      new Request(`http://localhost${uploadUrl}`, {
+        method: 'PUT',
+        body: 'payload',
+      })
+    )
+    assert.equal(put?.status, 200)
+
+    const signed = await content.signContentKey({
+      bucket: 'bucket',
+      contentKey: 'round/trip.bin',
+      dateLessThan: new Date(Date.now() + 60_000),
+    } as any)
+    const get = await handler(new Request(`http://localhost${signed}`))
+    assert.equal(get?.status, 200)
+    assert.equal(await get!.text(), 'payload')
+  })
+
+  test('HEAD returns the length without the body', async () => {
+    const signed = await content.signContentKey({
+      bucket: 'bucket',
+      contentKey: 'existing.bin',
+      dateLessThan: new Date(Date.now() + 60_000),
+    } as any)
+    const response = await handler(
+      new Request(`http://localhost${signed}`, { method: 'HEAD' })
+    )
+    assert.equal(response?.status, 200)
+    assert.equal(
+      response?.headers.get('content-length'),
+      String('already here'.length)
+    )
+    assert.equal(await response!.text(), '')
+  })
+
+  test('refuses a read with no signature at all', async () => {
+    const response = await handler(
+      new Request('http://localhost/assets/bucket/existing.bin')
+    )
+    assert.equal(response?.status, 403)
+  })
+
+  test('refuses a signature that verifies but names another path', async () => {
+    const signed = await content.signContentKey({
+      bucket: 'bucket',
+      contentKey: 'existing.bin',
+      dateLessThan: new Date(Date.now() + 60_000),
+    } as any)
+    writeFileSync(join(tmpDir, 'bucket', 'sibling.bin'), 'sibling')
+    const query = signed.slice(signed.indexOf('?'))
+    const response = await handler(
+      new Request(`http://localhost/assets/bucket/sibling.bin${query}`)
+    )
+    assert.equal(response?.status, 403)
+  })
+
+  test('refuses signed reads when no JWT service is available', async () => {
+    const unverifiable = createLocalContentRequestHandler({
+      content: {
+        localFileUploadPath: tmpDir,
+        uploadUrlPrefix: '/upload',
+        assetUrlPrefix: '/assets',
+      },
+      logger: noopLogger,
+      getJWT: () => undefined,
+    })
+    const signed = await content.signContentKey({
+      bucket: 'bucket',
+      contentKey: 'existing.bin',
+      dateLessThan: new Date(Date.now() + 60_000),
+    } as any)
+    const response = await unverifiable(
+      new Request(`http://localhost${signed}`)
+    )
+    assert.equal(response?.status, 403)
+  })
+
+  test('rejects a body over the size limit without writing it', async () => {
+    const response = await handler(
+      new Request('http://localhost/upload/bucket/big.bin', {
+        method: 'PUT',
+        body: Buffer.alloc(1024 * 1024 + 1),
+      })
+    )
+    assert.equal(response?.status, 413)
+    // Abandoning the stream must leave nothing behind — a partial file here
+    // would be a truncated asset that later reads would serve as if whole.
+    assert.equal(existsSync(join(tmpDir, 'bucket', 'big.bin')), false)
+  })
+})

package/src/services/local-content-request-handler.ts

@@ -0,0 +1,267 @@
+import { createReadStream } from 'fs'
+import { mkdir, stat, writeFile } from 'fs/promises'
+import { normalize, resolve } from 'path'
+import { Readable } from 'stream'
+import type { JWTService, Logger } from '@pikku/core/services'
+import { signedContentPath, type LocalContentConfig } from './local-content.js'
+
+/**
+ * The server half of {@link LocalContent}.
+ *
+ * `LocalContent` hands out `PUT <uploadUrlPrefix>/<key>` upload URLs and signed
+ * `GET <assetUrlPrefix>/<key>` read URLs, but it cannot answer either: it is a
+ * `ContentService`, not a transport. Something in the serving path has to, and
+ * until now only `@pikku/node-http-server` did — so the very same project served
+ * under Bun handed the browser upload URLs that 404ed, with nothing naming the
+ * cause.
+ *
+ * Expressed in Web `Request`/`Response` so every runtime can share one
+ * implementation rather than each re-deriving the signature check. Returns
+ * `null` for anything that is not a content request, which is the caller's
+ * signal to carry on with its normal routing.
+ */
+export type LocalContentRequestHandler = (
+  request: Request
+) => Promise<Response | null>
+
+export type LocalContentRequestHandlerOptions = {
+  content: LocalContentConfig
+  logger: Logger
+  /**
+   * Resolved per request rather than passed by value: a runtime may only be
+   * able to reach the signing service through `singletonServices`, which is not
+   * populated until after the server is constructed.
+   */
+  getJWT: () => JWTService | undefined
+}
+
+const matchesPrefix = (pathname: string, prefix: string) =>
+  pathname === prefix || pathname.startsWith(`${prefix}/`)
+
+const contentKey = (pathname: string, prefix: string) =>
+  pathname.slice(prefix.length).replace(/^\/+/, '')
+
+/**
+ * Resolve a key against the content root, or `null` if it escapes. `normalize`
+ * first so `..` segments are collapsed before the prefix check, and the
+ * comparison carries a trailing separator so a sibling directory whose name
+ * merely starts with the root's cannot pass as being inside it.
+ */
+const toTargetPath = (basePath: string, key: string): string | null => {
+  const normalizedBasePath = resolve(basePath)
+  const targetPath = resolve(normalizedBasePath, normalize(key))
+  return targetPath.startsWith(`${normalizedBasePath}/`) ? targetPath : null
+}
+
+const parseSizeLimit = (sizeLimit: string): number => {
+  const match = /^(\d+(?:\.\d+)?)(b|kb|mb|gb)?$/i.exec(sizeLimit.trim())
+  if (!match) {
+    throw new Error(`Invalid size limit: ${sizeLimit}`)
+  }
+  const value = Number(match[1])
+  const unit = (match[2] ?? 'b').toLowerCase()
+  const multiplier =
+    unit === 'gb'
+      ? 1024 * 1024 * 1024
+      : unit === 'mb'
+        ? 1024 * 1024
+        : unit === 'kb'
+          ? 1024
+          : 1
+  return value * multiplier
+}
+
+const text = (status: number, body: string) =>
+  new Response(body, {
+    status,
+    headers: { 'content-type': 'text/plain; charset=utf-8' },
+  })
+
+export const createLocalContentRequestHandler = ({
+  content,
+  logger,
+  getJWT,
+}: LocalContentRequestHandlerOptions): LocalContentRequestHandler => {
+  // Logged at most once. An unverifiable request is attacker-triggerable, so
+  // this reports a startup misconfiguration rather than per-request news.
+  let loggedMissingJWT = false
+
+  const validateSignedAssetRequest = async (
+    requestUrl: URL
+  ): Promise<{ ok: true } | { ok: false; status: number; body: string }> => {
+    const signedAtValue = requestUrl.searchParams.get('signedAt')
+    const expiresAtValue = requestUrl.searchParams.get('expiresAt')
+    const notBeforeValue = requestUrl.searchParams.get('notBefore')
+    const signature = requestUrl.searchParams.get('signature')
+
+    if (!signedAtValue || !expiresAtValue) {
+      return { ok: false, status: 403, body: 'Signed URL required' }
+    }
+
+    const signedAt = Number(signedAtValue)
+    const expiresAt = Number(expiresAtValue)
+    const notBefore =
+      notBeforeValue == null ? undefined : Number(notBeforeValue)
+
+    if (
+      !Number.isFinite(signedAt) ||
+      !Number.isFinite(expiresAt) ||
+      (notBefore != null && !Number.isFinite(notBefore))
+    ) {
+      return { ok: false, status: 403, body: 'Invalid signed URL' }
+    }
+
+    const now = Date.now()
+    if (now > expiresAt || (notBefore != null && now < notBefore)) {
+      return { ok: false, status: 403, body: 'Signed URL expired' }
+    }
+
+    const jwt = getJWT()
+    if (!jwt) {
+      if (!loggedMissingJWT) {
+        loggedMissingJWT = true
+        logger.error(
+          'pikku: refusing signed asset reads — no JWTService is available to verify them. Pass `contentSigningJWT` (the same service LocalContent signs with) or expose it as `singletonServices.jwt`.'
+        )
+      }
+      return { ok: false, status: 403, body: 'Invalid signed URL' }
+    }
+
+    if (!signature) {
+      return { ok: false, status: 403, body: 'Signed URL signature required' }
+    }
+
+    try {
+      const payload = await jwt.decode<{
+        signedAt?: number
+        expiresAt?: number
+        notBefore?: number
+        path?: string
+      }>(signature)
+
+      // Every claim is compared, the path included: without it a signature
+      // minted for one asset would read any other.
+      if (
+        payload.signedAt !== signedAt ||
+        payload.expiresAt !== expiresAt ||
+        payload.notBefore !== notBefore ||
+        payload.path !== signedContentPath(requestUrl.pathname)
+      ) {
+        return { ok: false, status: 403, body: 'Invalid signed URL' }
+      }
+    } catch {
+      return { ok: false, status: 403, body: 'Invalid signed URL' }
+    }
+
+    return { ok: true }
+  }
+
+  const handleUpload = async (
+    request: Request,
+    pathname: string
+  ): Promise<Response> => {
+    const key = contentKey(pathname, content.uploadUrlPrefix)
+    const targetPath = toTargetPath(content.localFileUploadPath, key)
+    if (!targetPath) {
+      return text(400, 'Invalid path')
+    }
+
+    const maxBytes = parseSizeLimit(content.sizeLimit ?? '1mb')
+
+    // Counted as it arrives and abandoned the moment it goes over, so an
+    // oversized upload costs the limit rather than its own size — `arrayBuffer()`
+    // would have to hold all of it first, which hands an unauthenticated caller
+    // a way to spend the server's memory. Mirrors node-http-server's
+    // `readRequestBody`, which aborts the same way.
+    const chunks: Buffer[] = []
+    let bytesRead = 0
+    const reader = request.body?.getReader()
+    if (reader) {
+      try {
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done) break
+          bytesRead += value.byteLength
+          if (bytesRead > maxBytes) {
+            await reader.cancel()
+            return text(413, 'Content too large')
+          }
+          chunks.push(Buffer.from(value))
+        }
+      } finally {
+        reader.releaseLock()
+      }
+    }
+
+    await mkdir(resolve(targetPath, '..'), { recursive: true })
+    await writeFile(targetPath, Buffer.concat(chunks))
+    return new Response(null, { status: 200 })
+  }
+
+  const handleAsset = async (
+    request: Request,
+    requestUrl: URL,
+    pathname: string
+  ): Promise<Response> => {
+    const key = contentKey(pathname, content.assetUrlPrefix)
+    const targetPath = toTargetPath(content.localFileUploadPath, key)
+    if (!targetPath) {
+      return text(400, 'Invalid path')
+    }
+
+    const signed = await validateSignedAssetRequest(requestUrl)
+    if (!signed.ok) {
+      return text(signed.status, signed.body)
+    }
+
+    try {
+      const file = await stat(targetPath)
+      if (!file.isFile()) {
+        return new Response(null, { status: 404 })
+      }
+
+      const headers = {
+        'content-length': String(file.size),
+        'content-type': 'application/octet-stream',
+      }
+      if (request.method === 'HEAD') {
+        return new Response(null, { status: 200, headers })
+      }
+      // Streamed rather than buffered: assets are user uploads, and their size
+      // is bounded by `sizeLimit` at write time, not by anything here.
+      return new Response(
+        Readable.toWeb(createReadStream(targetPath)) as ReadableStream,
+        { status: 200, headers }
+      )
+    } catch {
+      return new Response(null, { status: 404 })
+    }
+  }
+
+  return async (request) => {
+    let requestUrl: URL
+    try {
+      requestUrl = new URL(request.url)
+    } catch {
+      return null
+    }
+
+    const pathname = decodeURIComponent(requestUrl.pathname)
+
+    if (
+      request.method === 'PUT' &&
+      matchesPrefix(pathname, content.uploadUrlPrefix)
+    ) {
+      return handleUpload(request, pathname)
+    }
+
+    if (
+      (request.method === 'GET' || request.method === 'HEAD') &&
+      matchesPrefix(pathname, content.assetUrlPrefix)
+    ) {
+      return handleAsset(request, requestUrl, pathname)
+    }
+
+    return null
+  }
+}