@pikku/core 0.12.74 → 0.12.77

package/src/services/audit-service.ts

@@ -4,6 +4,7 @@ import type {
   PikkuWiringTypes,
 } from '../types/core.types.js'
 import type { Logger } from './logger.js'
+import type { Safe } from '../secret-value.js'
 
 export type AuditDurability = 'best-effort' | 'transactional'
 export type AuditOutcome = 'success' | 'failed' | 'denied'
@@ -19,7 +20,19 @@ export type ResolvedAuditConfig = {
   durability: AuditDurability
 }
 
-export type AuditActor = {
+/**
+ * Who an event happened under.
+ *
+ * A user, not an "actor": in pikku an actor is a synthetic person a scenario
+ * drives, flagged `actor` on the user row, and the overwhelming majority of
+ * audited events are caused by ordinary customers. Naming this `actor` made the
+ * synthetic case unsayable — `actor.actor === true` — and implied every
+ * recorded action was a test.
+ *
+ * `pikkuUserId` is the identity pikku resolves for every wire, so it is the one
+ * field a signed-out caller still leaves behind.
+ */
+export type AuditUserIdentity = {
   userId?: string
   orgId?: string
   pikkuUserId?: string
@@ -37,16 +50,67 @@ export type AuditEvent = {
   traceId?: string
   transactionId?: string | null
   queryId?: string | null
-  actor?: AuditActor
+  userIdentity?: AuditUserIdentity
   input?: unknown
   metadata?: Record<string, unknown>
 }
 
 export type AuditEventBatch = AuditEvent[]
 
+/**
+ * A page of the trail, newest first, narrowed by the filters a reader picked.
+ *
+ * Every field is a conjunction, and an empty array is not a filter — it is
+ * "match nothing", which would otherwise read as "match everything" and quietly
+ * widen a scoped query.
+ */
+export type AuditQuery = {
+  /** Restrict to these users. */
+  userIds?: string[]
+  /** Restrict to these `AuditEvent['type']` values. */
+  types?: string[]
+  /** Restrict to one organisation. */
+  orgId?: string
+  /** Inclusive lower bound on `occurredAt` (ISO 8601). */
+  from?: string
+  /** Exclusive upper bound on `occurredAt` (ISO 8601). */
+  to?: string
+  limit?: number
+  offset?: number
+}
+
+/**
+ * The distinct values present in the trail, for populating filter controls.
+ *
+ * Computed over the whole trail rather than the current page — a filter list
+ * that only offered what the current page happens to show could never be used
+ * to reach anything else.
+ */
+export type AuditFacets = {
+  userIds: string[]
+  types: string[]
+}
+
+export type AuditQueryResult = {
+  events: AuditEvent[]
+  /** Offset of the next page, or `null` at the end. */
+  nextCursor: number | null
+  /** Present only when the caller asked for it — it costs two extra scans. */
+  facets?: AuditFacets
+}
+
 export interface AuditService {
   audit(event: AuditEvent): Promise<void>
   write?(batch: AuditEventBatch): Promise<void>
+  /**
+   * The read side. Optional because a sink can legitimately be write-only — a
+   * queue producer that hands events to another system has nothing to read
+   * back. A reader that finds this absent should say the trail is not readable
+   * here rather than that it is empty; the two are very different answers.
+   */
+  query?(query: AuditQuery): Promise<AuditQueryResult>
+  /** Distinct users and types across the whole trail. Paired with {@link query}. */
+  facets?(): Promise<AuditFacets>
 }
 
 export class NoopAuditService implements AuditService {
@@ -57,9 +121,18 @@ export class NoopAuditService implements AuditService {
 
 export type AuditLogWriteInput = Omit<AuditEvent, 'occurredAt'>
 
+/**
+ * The audit an invocation writes to. `write` is `Safe<>`-guarded like the
+ * logger: an audit event carries `input` and `metadata` as `unknown`, so
+ * nominality alone cannot stop a `SecretValue` landing in one. A secret
+ * anywhere in the event, however deeply nested, collapses to `never`.
+ *
+ * An unrevealed `SecretValue` would serialize as `[secret]` anyway; the guard
+ * is what makes that an explicit choice rather than a near miss.
+ */
 export interface AuditLog {
   readonly config: ResolvedAuditConfig | undefined
-  write(event: AuditLogWriteInput): Promise<void>
+  write<E extends AuditLogWriteInput>(event: Safe<E>): Promise<void>
   flush(): Promise<void>
   close(): Promise<void>
 }
@@ -149,7 +222,8 @@ class InvocationAuditLog implements AuditLog {
       wireType: this.wire.wireType,
       wireId: this.wire.wireId,
       traceId: this.wire.traceId,
-      actor: event.actor ?? resolveAuditActorFromWire(this.wire),
+      userIdentity:
+        event.userIdentity ?? resolveAuditUserIdentityFromWire(this.wire),
       ...event,
       occurredAt: new Date().toISOString(),
     }
@@ -184,19 +258,23 @@ export const createInvocationAudit = (
   return new InvocationAuditLog(wire.audit, service, wire, logger)
 }
 
-export const resolveAuditActorFromWire = (
+export const resolveAuditUserIdentityFromWire = (
   wire: PikkuWire<any, any, any, CoreUserSession>
-): AuditActor | undefined => {
+): AuditUserIdentity | undefined => {
   const session = wire.session as CoreUserSession | undefined
-  const actor: AuditActor = {
+  const userIdentity: AuditUserIdentity = {
     userId: session?.userId,
     orgId: session?.orgId,
     pikkuUserId: wire.pikkuUserId,
   }
 
-  if (!actor.userId && !actor.orgId && !actor.pikkuUserId) {
+  if (
+    !userIdentity.userId &&
+    !userIdentity.orgId &&
+    !userIdentity.pikkuUserId
+  ) {
     return undefined
   }
 
-  return actor
+  return userIdentity
 }

package/src/services/credential-wire-service.ts

@@ -1,3 +1,4 @@
+import { isSecretValue } from '../secret-value.js'
 import type { CredentialService } from './credential-service.js'
 import { defaultPikkuUserIdResolver } from './pikku-user-id.js'
 import type { PikkuRawWire } from '../types/core.types.js'
@@ -17,8 +18,15 @@ export class PikkuCredentialWireService {
     return this.aliases?.[name] ?? name
   }
 
+  /**
+   * A credential is one of the few places vault material is meant to end up, so
+   * a `SecretValue` is unwrapped here rather than rejected — `get` promises the
+   * raw material, and storing the wrapper would make that a lie.
+   */
   set(name: string, value: unknown): void {
-    this.credentials[this.resolveName(name)] = value
+    this.credentials[this.resolveName(name)] = isSecretValue(value)
+      ? value.reveal()
+      : value
   }
 
   get<T = unknown>(name: string): T | null | Promise<T | null> {

package/src/services/email-service.ts

@@ -1,3 +1,5 @@
+import type { Safe } from '../secret-value.js'
+
 export interface EmailTemplateReference {
   name: string
   locale?: string
@@ -42,5 +44,5 @@ export interface SendEmailResult {
 }
 
 export interface EmailService {
-  send(input: SendEmailInput): Promise<SendEmailResult>
+  send<T extends SendEmailInput>(input: Safe<T>): Promise<SendEmailResult>
 }

package/src/services/index.ts

@@ -75,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'
@@ -141,11 +141,10 @@ export type { IsSystemRole } from './system-role-guard.js'
 export {
   NoopAuditService,
   createInvocationAudit,
-  resolveAuditActorFromWire,
   resolveAuditConfig,
+  resolveAuditUserIdentityFromWire,
 } from './audit-service.js'
 export type {
-  AuditActor,
   AuditConfig,
   AuditDurability,
   AuditEvent,
@@ -155,6 +154,7 @@ export type {
   AuditOutcome,
   AuditService,
   AuditSource,
+  AuditUserIdentity,
   ResolvedAuditConfig,
 } from './audit-service.js'
 export { InMemorySessionStore } from './in-memory-session-store.js'

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
+  }
+}