@pikku/core 0.12.107 → 0.12.111

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

@@ -1,295 +0,0 @@
-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 type SignedContentVerification =
-  { ok: true } | { ok: false; status: number; body: string }
-
-/**
- * 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')
-
-  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' }
-  }
-
-  if (!jwt) {
-    onMissingJWT?.()
-    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 }
-}
-
-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) {
-      return text(400, 'Invalid path')
-    }
-
-    const maxBytes = parseSizeLimit(content.sizeLimit ?? '1mb')
-
-    // 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()
-    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, requestUrl, pathname)
-    }
-
-    if (
-      (request.method === 'GET' || request.method === 'HEAD') &&
-      matchesPrefix(pathname, content.assetUrlPrefix)
-    ) {
-      return handleAsset(request, requestUrl, pathname)
-    }
-
-    return null
-  }
-}

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

@@ -1,186 +0,0 @@
-import assert from 'node:assert/strict'
-import { describe, test } from 'node:test'
-
-import { LocalContent, signedContentPath } from './local-content.js'
-
-const createLogger = () =>
-  ({
-    info: () => {},
-    warn: () => {},
-    error: () => {},
-    debug: () => {},
-    setLevel: () => {},
-  }) as any
-
-type CapturedPayload = {
-  signedAt: number
-  expiresAt: number
-  notBefore?: number
-  path?: string
-}
-
-const createContent = (
-  overrides: Partial<{ server?: string; assetUrlPrefix: string }> = {}
-) => {
-  let capturedPayload: CapturedPayload | undefined
-  const content = new LocalContent(
-    {
-      localFileUploadPath: '/tmp/uploads',
-      uploadUrlPrefix: '/reaper',
-      assetUrlPrefix: overrides.assetUrlPrefix ?? '/assets',
-      server:
-        'server' in overrides ? overrides.server : 'http://localhost:3000',
-    },
-    createLogger(),
-    {
-      encode: async (_expiresIn: any, payload: any) => {
-        capturedPayload = payload
-        return 'signed-token'
-      },
-      decode: async () => ({}) as any,
-    }
-  )
-  return {
-    content,
-    getPayload: () => capturedPayload,
-  }
-}
-
-describe('LocalContent signing', () => {
-  test('binds notBefore into the signature payload', async () => {
-    const { content, getPayload } = createContent()
-
-    const dateGreaterThan = new Date(Date.now() + 60_000)
-    const dateLessThan = new Date(Date.now() + 120_000)
-    const signedUrl = await content.signContentKey({
-      bucket: 'avatars',
-      contentKey: 'user-1.png',
-      dateLessThan,
-      dateGreaterThan,
-    })
-
-    const url = new URL(signedUrl)
-    assert.equal(url.searchParams.get('signature'), 'signed-token')
-    const capturedPayload = getPayload()
-    assert.ok(capturedPayload)
-    assert.equal(capturedPayload?.expiresAt, dateLessThan.getTime())
-    assert.equal(capturedPayload?.notBefore, dateGreaterThan.getTime())
-    assert.equal(
-      url.searchParams.get('notBefore'),
-      String(dateGreaterThan.getTime())
-    )
-  })
-
-  test('binds the asset path into the signature payload', async () => {
-    const { content, getPayload } = createContent()
-
-    const signedUrl = await content.signContentKey({
-      bucket: 'avatars',
-      contentKey: 'user-1.png',
-      dateLessThan: new Date(Date.now() + 60_000),
-    })
-
-    assert.equal(getPayload()?.path, '/assets/avatars/user-1.png')
-    assert.equal(
-      new URL(signedUrl).pathname,
-      '/assets/avatars/user-1.png',
-      'the bound path must be the path the server will receive'
-    )
-  })
-
-  test('two different content keys never share a bound path', async () => {
-    const { content, getPayload } = createContent()
-
-    await content.signContentKey({
-      bucket: 'avatars',
-      contentKey: 'user-1.png',
-      dateLessThan: new Date(Date.now() + 60_000),
-    })
-    const first = getPayload()?.path
-
-    await content.signContentKey({
-      bucket: 'private',
-      contentKey: 'passport-scan.png',
-      dateLessThan: new Date(Date.now() + 60_000),
-    })
-    const second = getPayload()?.path
-
-    assert.ok(first)
-    assert.notEqual(first, second)
-  })
-
-  test('binds nested and space-containing keys to their decoded path', async () => {
-    const { content, getPayload } = createContent()
-
-    const signedUrl = await content.signContentKey({
-      bucket: 'avatars',
-      contentKey: 'nested/deep/my file (1).png',
-      dateLessThan: new Date(Date.now() + 60_000),
-    })
-
-    const url = new URL(signedUrl)
-    assert.equal(
-      getPayload()?.path,
-      '/assets/avatars/nested/deep/my file (1).png'
-    )
-    assert.equal(
-      decodeURIComponent(url.pathname),
-      getPayload()?.path,
-      'the signed path must match the decoded pathname the server receives'
-    )
-  })
-
-  test('binds the path when no server origin is configured', async () => {
-    const { content, getPayload } = createContent({ server: undefined })
-
-    const signedUrl = await content.signContentKey({
-      bucket: 'avatars',
-      contentKey: 'user-1.png',
-      dateLessThan: new Date(Date.now() + 60_000),
-    })
-
-    assert.equal(getPayload()?.path, '/assets/avatars/user-1.png')
-    assert.ok(signedUrl.startsWith('/assets/avatars/user-1.png?'))
-  })
-
-  test('signURL binds the path of the url it signs', async () => {
-    const { content, getPayload } = createContent()
-
-    await content.signURL({
-      url: 'http://localhost:3000/assets/avatars/user-1.png',
-      dateLessThan: new Date(Date.now() + 60_000),
-    })
-
-    assert.equal(getPayload()?.path, '/assets/avatars/user-1.png')
-  })
-
-  test('refuses to construct without a JWT service', () => {
-    assert.throws(
-      () =>
-        new LocalContent(
-          {
-            localFileUploadPath: '/tmp/uploads',
-            uploadUrlPrefix: '/reaper',
-            assetUrlPrefix: '/assets',
-          },
-          createLogger(),
-          undefined as any
-        ),
-      /JWTService/
-    )
-  })
-})
-
-describe('signedContentPath', () => {
-  test('strips the origin and query, and decodes the path', () => {
-    assert.equal(
-      signedContentPath('http://localhost:3000/assets/a/b%20c.png?x=1'),
-      '/assets/a/b c.png'
-    )
-    assert.equal(signedContentPath('/assets/a/b%20c.png'), '/assets/a/b c.png')
-  })
-
-  test('is stable for a malformed percent escape', () => {
-    assert.equal(signedContentPath('/assets/100%.png'), '/assets/100%.png')
-  })
-})