@pikku/core 0.12.78 → 0.12.80

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

@@ -77,89 +77,122 @@ const text = (status: number, body: string) =>
     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
+export type SignedContentVerification =
+  | { ok: true }
+  | { ok: false; status: number; body: string }
 
-  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' }
-    }
+/**
+ * Verifies a signed content URL — the one function that decides whether a
+ * signed read or a signed upload is genuine.
+ *
+ * Exported and shared so the runtimes that serve content (the core handler here,
+ * the node server, the express adapter) verify identically. They used to each
+ * carry their own copy, which is how the express upload path ended up with no
+ * check at all: one copy can rot or be forgotten in isolation.
+ *
+ * `onMissingJWT` is called at most where the caller wants to log the
+ * misconfiguration once; a signed request with no verifier is treated as
+ * invalid, never as trusted.
+ */
+export const verifySignedContentRequest = async (
+  requestUrl: URL,
+  jwt: JWTService | undefined,
+  onMissingJWT?: () => void
+): Promise<SignedContentVerification> => {
+  const signedAtValue = requestUrl.searchParams.get('signedAt')
+  const expiresAtValue = requestUrl.searchParams.get('expiresAt')
+  const notBeforeValue = requestUrl.searchParams.get('notBefore')
+  const signature = requestUrl.searchParams.get('signature')
 
-    const signedAt = Number(signedAtValue)
-    const expiresAt = Number(expiresAtValue)
-    const notBefore =
-      notBeforeValue == null ? undefined : Number(notBeforeValue)
+  if (!signedAtValue || !expiresAtValue) {
+    return { ok: false, status: 403, body: 'Signed URL required' }
+  }
 
-    if (
-      !Number.isFinite(signedAt) ||
-      !Number.isFinite(expiresAt) ||
-      (notBefore != null && !Number.isFinite(notBefore))
-    ) {
-      return { ok: false, status: 403, body: 'Invalid signed URL' }
-    }
+  const signedAt = Number(signedAtValue)
+  const expiresAt = Number(expiresAtValue)
+  const notBefore = notBeforeValue == null ? undefined : Number(notBeforeValue)
 
-    const now = Date.now()
-    if (now > expiresAt || (notBefore != null && now < notBefore)) {
-      return { ok: false, status: 403, body: 'Signed URL expired' }
-    }
+  if (
+    !Number.isFinite(signedAt) ||
+    !Number.isFinite(expiresAt) ||
+    (notBefore != null && !Number.isFinite(notBefore))
+  ) {
+    return { ok: false, status: 403, body: 'Invalid signed URL' }
+  }
 
-    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' }
-    }
+  const now = Date.now()
+  if (now > expiresAt || (notBefore != null && now < notBefore)) {
+    return { ok: false, status: 403, body: 'Signed URL expired' }
+  }
 
-    if (!signature) {
-      return { ok: false, status: 403, body: 'Signed URL signature required' }
-    }
+  if (!jwt) {
+    onMissingJWT?.()
+    return { ok: false, status: 403, body: 'Invalid signed URL' }
+  }
 
-    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 {
+  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' }
     }
-
-    return { ok: true }
+  } catch {
+    return { ok: false, status: 403, body: 'Invalid signed URL' }
   }
 
+  return { ok: true }
+}
+
+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 = (
+    requestUrl: URL
+  ): Promise<SignedContentVerification> =>
+    verifySignedContentRequest(requestUrl, getJWT(), () => {
+      if (loggedMissingJWT) return
+      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`.'
+      )
+    })
+
   const handleUpload = async (
     request: Request,
+    requestUrl: URL,
     pathname: string
   ): Promise<Response> => {
+    // Uploads are presigned exactly like reads: getUploadURL mints a signed URL
+    // and this verifies it before writing. Without this an unauthenticated PUT
+    // could write arbitrary bytes to any key under the content root — the write
+    // side had none of the signature checking the read side has always had.
+    const signed = await validateSignedAssetRequest(requestUrl)
+    if (!signed.ok) {
+      return text(signed.status, signed.body)
+    }
+
     const key = contentKey(pathname, content.uploadUrlPrefix)
     const targetPath = toTargetPath(content.localFileUploadPath, key)
     if (!targetPath) {
@@ -168,11 +201,7 @@ export const createLocalContentRequestHandler = ({
 
     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.
+    // knowledge: decisions/security/an-upload-is-counted-as-it-arrives-not-buffered-then-measured.md
     const chunks: Buffer[] = []
     let bytesRead = 0
     const reader = request.body?.getReader()
@@ -252,7 +281,7 @@ export const createLocalContentRequestHandler = ({
       request.method === 'PUT' &&
       matchesPrefix(pathname, content.uploadUrlPrefix)
     ) {
-      return handleUpload(request, pathname)
+      return handleUpload(request, requestUrl, pathname)
     }
 
     if (

package/src/services/local-content.ts

@@ -48,6 +48,9 @@ export const signedContentPath = (urlOrPath: string): string => {
   }
 }
 
+/** How long a presigned upload URL stays valid. Short, like an S3 PUT URL. */
+const UPLOAD_URL_TTL_MS = 15 * 60 * 1000
+
 export class LocalContent implements ContentService {
   constructor(
     private config: LocalContentConfig,
@@ -137,13 +140,24 @@ export class LocalContent implements ContentService {
     })
   }
 
+  /**
+   * Presigned upload, mirroring the read side: the URL carries a short-lived,
+   * path-bound signature that {@link createLocalContentRequestHandler} verifies
+   * before writing. An unsigned upload URL cannot be verified, and the handler
+   * now refuses one — so this must sign, or every upload 403s.
+   */
   public async getUploadURL(args: GetUploadURLArgs): Promise<UploadURLResult> {
     void args.visibility
     const fullKey = this.joinKey(args.bucket, args.fileKey)
     this.logger.debug(`Going to upload with key: ${fullKey}`)
+    const uploadUrl = await this.signURL({
+      url: `${this.config.uploadUrlPrefix}/${fullKey}`,
+      dateLessThan: new Date(Date.now() + UPLOAD_URL_TTL_MS),
+    })
     return {
-      uploadUrl: `${this.config.uploadUrlPrefix}/${fullKey}`,
+      uploadUrl,
       assetKey: fullKey,
+      uploadMethod: 'PUT',
     }
   }
 

package/src/services/local-email-service.ts

@@ -1,4 +1,8 @@
-import type { EmailService, SendEmailInput, SendEmailResult } from './email-service.js'
+import type {
+  EmailService,
+  SendEmailInput,
+  SendEmailResult,
+} from './email-service.js'
 
 export class LocalEmailService implements EmailService {
   async send(input: SendEmailInput): Promise<SendEmailResult> {

package/src/services/system-role-guard.test.ts

@@ -11,7 +11,10 @@ import {
   SystemRoleShadowedError,
 } from '../errors/errors.js'
 
-const system = (...names: string[]) => (name: string) => names.includes(name)
+const system =
+  (...names: string[]) =>
+  (name: string) =>
+    names.includes(name)
 
 describe('mutating a role', () => {
   test('a declared role refuses to be deleted or re-scoped', async () => {

package/src/services/workflow-service.ts

@@ -1,4 +1,4 @@
-import type { SerializedError } from '../types/core.types.js'
+import type { CoreUserSession, SerializedError } from '../types/core.types.js'
 import type {
   WorkflowRun,
   WorkflowPlannedStep,
@@ -47,8 +47,15 @@ export interface WorkflowService {
   /**
    * The payload is stored as given and validated on replay inside the workflow
    * body, so an invalid one re-closes the gate rather than failing the run.
+   *
+   * The session must belong to the run's owner — see `assertWorkflowRunOwner`.
    */
-  approveStep(runId: string, reason: string, decision: unknown): Promise<void>
+  approveStep(
+    runId: string,
+    reason: string,
+    decision: unknown,
+    session?: CoreUserSession
+  ): Promise<void>
   startWorkflow<I>(
     name: string,
     input: I,

package/src/side-effects-are-declared.test.ts

@@ -0,0 +1,84 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname, relative } from 'node:path'
+
+const srcRoot = dirname(fileURLToPath(import.meta.url))
+const packageRoot = join(srcRoot, '..')
+
+/**
+ * A statement that runs when the module is imported, rather than when
+ * something in it is called. Today every one is an `addError(...)` registering
+ * an error class in the runtime registry.
+ */
+const TOP_LEVEL_CALL = /^[a-zA-Z_$][\w.$]*\(/
+
+const collectSourceFiles = (directory: string): string[] =>
+  readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const entryPath = join(directory, entry.name)
+    if (entry.isDirectory()) {
+      return entry.name === 'dist' ? [] : collectSourceFiles(entryPath)
+    }
+    return entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')
+      ? [entryPath]
+      : []
+  })
+
+/** Source modules that do something merely by being imported. */
+const modulesWithSideEffects = (): string[] =>
+  collectSourceFiles(srcRoot)
+    .filter((file) =>
+      readFileSync(file, 'utf-8')
+        .split('\n')
+        .some((line) => TOP_LEVEL_CALL.test(line))
+    )
+    .map((file) => `./dist/${relative(srcRoot, file).replace(/\.ts$/, '.js')}`)
+    .sort()
+
+const declared = (): string[] => {
+  const pkg = JSON.parse(
+    readFileSync(join(packageRoot, 'package.json'), 'utf-8')
+  )
+  return [...(pkg.sideEffects ?? [])].sort()
+}
+
+/**
+ * `sideEffects` tells a bundler which modules it may not drop. Claiming
+ * `false` outright would be untrue — the error registry is built by
+ * `addError(...)` calls that run on import, and a bundler that dropped
+ * `errors/errors.js` would leave `getErrorResponse` unable to find any of
+ * them. Naming the modules exactly lets everything else be tree-shaken.
+ *
+ * knowledge: decisions/internals/side-effects-are-an-allowlist-not-a-boolean.md
+ */
+describe('every module with import-time side effects is declared', () => {
+  test('the allowlist matches the modules that actually have them', () => {
+    const actual = modulesWithSideEffects()
+    const listed = declared()
+
+    assert.deepEqual(
+      { missing: actual.filter((m) => !listed.includes(m)) },
+      { missing: [] },
+      'a module runs code on import but is not in package.json sideEffects. ' +
+        'A bundler may drop it, and whatever it registered will be absent at ' +
+        'runtime.'
+    )
+
+    assert.deepEqual(
+      { stale: listed.filter((m) => !actual.includes(m)) },
+      { stale: [] },
+      'package.json sideEffects names a module that no longer has any — ' +
+        'remove it so bundlers can tree-shake it.'
+    )
+  })
+
+  test('the detector finds a known side effect', () => {
+    // Guards the test above: a detector matching nothing would pass whatever
+    // package.json claimed.
+    assert.ok(
+      modulesWithSideEffects().includes('./dist/errors/errors.js'),
+      'errors/errors.js registers every error class at import and must match'
+    )
+  })
+})

package/src/source-files-stay-composable.test.ts

@@ -0,0 +1,41 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname, relative } from 'node:path'
+
+const srcRoot = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * The ceiling a single module may reach before it has to be composed out of
+ * smaller ones.
+ */
+const MAX_LINES = 2000
+
+const collectSourceFiles = (directory: string): string[] =>
+  readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const entryPath = join(directory, entry.name)
+    if (entry.isDirectory()) {
+      return entry.name === 'dist' ? [] : collectSourceFiles(entryPath)
+    }
+    return entry.name.endsWith('.ts') ? [entryPath] : []
+  })
+
+describe('source files stay composable', () => {
+  test(`no module in @pikku/core exceeds ${MAX_LINES} lines`, () => {
+    const offenders = collectSourceFiles(srcRoot)
+      .map((file) => ({
+        file: relative(srcRoot, file),
+        lines: readFileSync(file, 'utf-8').split('\n').length,
+      }))
+      .filter(({ lines }) => lines > MAX_LINES)
+      .sort((a, b) => b.lines - a.lines)
+
+    assert.deepEqual(
+      offenders,
+      [],
+      `modules over ${MAX_LINES} lines:\n` +
+        offenders.map(({ file, lines }) => `  ${lines}  ${file}`).join('\n')
+    )
+  })
+})

package/src/testing/service-tests/agent-run-service-tests.ts

@@ -0,0 +1,98 @@
+import { describe, test, before } from 'node:test'
+import assert from 'node:assert/strict'
+
+import type { AgentRunService } from '../../wirings/ai-agent/ai-agent.types.js'
+import type { ServiceTestConfig } from '../service-tests.js'
+
+/** Conformance suite for `agentRunService`. Runs only when a backend supplies one. */
+export const defineAgentRunServiceTests = (
+  name: string,
+  agentRunService: NonNullable<
+    ServiceTestConfig['services']['agentRunService']
+  >,
+  /**
+   * Thread-ownership is a property of the two services together — the run
+   * service lists what the storage service owns — so that half of the suite
+   * only runs when a backend supplies both. Passed explicitly rather than
+   * closed over, so the dependency is visible in the signature.
+   */
+  aiStorageService?: ServiceTestConfig['services']['aiStorageService']
+): void => {
+  const factory = agentRunService
+  describe(`AgentRunService [${name}]`, () => {
+    let agentService: AgentRunService
+
+    before(async () => {
+      agentService = await factory()
+    })
+
+    test('listThreads', async () => {
+      const threads = await agentService.listThreads()
+      assert.ok(Array.isArray(threads))
+    })
+
+    if (aiStorageService) {
+      const storageFactory = aiStorageService
+
+      // The `owners` constraint is what keeps the generated thread-management
+      // functions from leaking across tenants: a caller may only list threads
+      // owned by one of their session principals, matching the
+      // `principal:sub-partition` composition resolveOwnerResourceId writes.
+      test('listThreads scopes to the given owners, including sub-partitions', async () => {
+        const storage = await storageFactory()
+        await storage.createThread('owner-alice')
+        await storage.createThread('owner-alice:project-1')
+        await storage.createThread('owner-bob:secret')
+
+        const threads = await agentService.listThreads({
+          owners: ['owner-alice'],
+        })
+        const ids = threads.map((t) => t.resourceId)
+
+        assert.ok(ids.includes('owner-alice'))
+        assert.ok(ids.includes('owner-alice:project-1'))
+        assert.ok(
+          !ids.some((id) => id.startsWith('owner-bob')),
+          "another owner's threads must not be listed"
+        )
+      })
+
+      test('listThreads with an owner does not match a lookalike prefix', async () => {
+        const storage = await storageFactory()
+        await storage.createThread('owner-al')
+        await storage.createThread('owner-alice-evil:p')
+
+        const threads = await agentService.listThreads({
+          owners: ['owner-al'],
+        })
+        const ids = threads.map((t) => t.resourceId)
+
+        assert.ok(ids.includes('owner-al'))
+        assert.ok(!ids.includes('owner-alice-evil:p'))
+      })
+
+      test('listThreads with an empty owners list returns nothing', async () => {
+        const storage = await storageFactory()
+        await storage.createThread('owner-empty-check')
+
+        const threads = await agentService.listThreads({ owners: [] })
+        assert.deepEqual(threads, [])
+      })
+    }
+
+    test('getThread returns null for missing', async () => {
+      const thread = await agentService.getThread('missing-thread')
+      assert.equal(thread, null)
+    })
+
+    test('getDistinctAgentNames', async () => {
+      const names = await agentService.getDistinctAgentNames()
+      assert.ok(Array.isArray(names))
+    })
+
+    test('deleteThread returns false for missing', async () => {
+      const result = await agentService.deleteThread('missing-thread')
+      assert.equal(result, false)
+    })
+  })
+}