@pikku/core 0.12.72 → 0.12.77

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

@@ -1,36 +1,54 @@
 import assert from 'node:assert/strict'
 import { describe, test } from 'node:test'
 
-import { LocalContent } from './local-content.js'
+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 () => {
-    let capturedPayload:
-      | { signedAt: number; expiresAt: number; notBefore?: number }
-      | undefined
-
-    const content = new LocalContent(
-      {
-        localFileUploadPath: '/tmp/uploads',
-        uploadUrlPrefix: '/reaper',
-        assetUrlPrefix: '/assets',
-        server: 'http://localhost:3000',
-      },
-      {
-        info: () => {},
-        warn: () => {},
-        error: () => {},
-        debug: () => {},
-        setLevel: () => {},
-      } as any,
-      {
-        encode: async (_expiresIn: any, payload: any) => {
-          capturedPayload = payload
-          return 'signed-token'
-        },
-        decode: async () => ({}),
-      }
-    )
+    const { content, getPayload } = createContent()
 
     const dateGreaterThan = new Date(Date.now() + 60_000)
     const dateLessThan = new Date(Date.now() + 120_000)
@@ -43,6 +61,7 @@ describe('LocalContent signing', () => {
 
     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())
@@ -51,4 +70,117 @@ describe('LocalContent signing', () => {
       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')
+  })
 })

package/src/services/local-content.ts

@@ -24,12 +24,42 @@ export interface LocalContentConfig {
   sizeLimit?: string
 }
 
+/**
+ * The representation of an asset that gets bound into a signed URL's
+ * signature, and that a server can reconstruct from an incoming request:
+ * the decoded path, without origin or query string.
+ *
+ * Both sides must derive it the same way, so signer and verifier share this
+ * function. Percent escapes are decoded so that a client re-encoding an
+ * optional character still matches; a malformed escape is left verbatim
+ * rather than throwing, which keeps both sides in agreement.
+ */
+export const signedContentPath = (urlOrPath: string): string => {
+  let pathname: string
+  try {
+    pathname = new URL(urlOrPath, 'http://pikku.local').pathname
+  } catch {
+    pathname = urlOrPath
+  }
+  try {
+    return decodeURIComponent(pathname)
+  } catch {
+    return pathname
+  }
+}
+
 export class LocalContent implements ContentService {
   constructor(
     private config: LocalContentConfig,
     private logger: Logger,
-    private jwt?: JWTService
-  ) {}
+    private jwt: JWTService
+  ) {
+    if (!jwt) {
+      throw new Error(
+        'LocalContent requires a JWTService: without one it cannot sign asset URLs, and unsigned URLs cannot be verified.'
+      )
+    }
+  }
 
   private safePath(bucket: string, key: string): string {
     const base = resolve(this.config.localFileUploadPath)
@@ -48,6 +78,7 @@ export class LocalContent implements ContentService {
   public async init() {}
 
   private async signParams(
+    url: string,
     dateLessThan: Date,
     dateGreaterThan?: Date
   ): Promise<string> {
@@ -60,33 +91,34 @@ export class LocalContent implements ContentService {
     if (dateGreaterThan) {
       params.set('notBefore', String(dateGreaterThan.getTime()))
     }
-    if (this.jwt) {
-      const expiresInSeconds = Math.max(
-        1,
-        Math.floor((expiresAt - signedAt) / 1000)
-      )
-      const payload: {
-        signedAt: number
-        expiresAt: number
-        notBefore?: number
-      } = {
-        signedAt,
-        expiresAt,
-      }
-      if (dateGreaterThan) {
-        payload.notBefore = dateGreaterThan.getTime()
-      }
-      const signature = await this.jwt.encode(
-        { value: expiresInSeconds, unit: 'second' },
-        payload
-      )
-      params.set('signature', signature)
+    const expiresInSeconds = Math.max(
+      1,
+      Math.floor((expiresAt - signedAt) / 1000)
+    )
+    const payload: {
+      signedAt: number
+      expiresAt: number
+      notBefore?: number
+      path: string
+    } = {
+      signedAt,
+      expiresAt,
+      path: signedContentPath(url),
     }
+    if (dateGreaterThan) {
+      payload.notBefore = dateGreaterThan.getTime()
+    }
+    const signature = await this.jwt.encode(
+      { value: expiresInSeconds, unit: 'second' },
+      payload
+    )
+    params.set('signature', signature)
     return params.toString()
   }
 
   public async signURL(args: SignURLArgs): Promise<string> {
     const params = await this.signParams(
+      args.url,
       args.dateLessThan,
       args.dateGreaterThan
     )

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

@@ -6,22 +6,7 @@ import {
   resolveGatewayAdapter,
 } from '../wirings/gateway/gateway-runner.js'
 
-/**
- * Local GatewayService implementation.
- *
- * Starts all registered listener gateways unconditionally (single-process).
- * For distributed deployments, implement `GatewayService` with leader
- * election or similar coordination.
- *
- * @example
- * ```typescript
- * const gatewayService = new LocalGatewayService()
- * await gatewayService.start()
- *
- * // On shutdown
- * await gatewayService.stop()
- * ```
- */
+// knowledge: decisions/internals/local-trigger-and-gateway-services-assume-a-single-process.md
 export class LocalGatewayService implements GatewayService {
   private activeAdapters = new Map<string, GatewayAdapter>()
 
@@ -57,7 +42,7 @@ export class LocalGatewayService implements GatewayService {
             e
           )
         } catch {
-          // logger may not be available during shutdown
+          // The logger may already be gone during shutdown.
         }
       }
     }

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

@@ -7,14 +7,14 @@ describe('LocalSecretService', () => {
   test('should get secret from local storage', async () => {
     const service = new LocalSecretService()
     await service.setSecret('MY_KEY', { token: 'abc' })
-    const result = await service.getSecret('MY_KEY')
+    const result = (await service.getSecret('MY_KEY')).reveal()
     assert.deepStrictEqual(result, { token: 'abc' })
   })
 
   test('should get secret from environment variables', async () => {
     const vars = new LocalVariablesService({ MY_SECRET: 'secret-value' })
     const service = new LocalSecretService(vars)
-    const result = await service.getSecret('MY_SECRET')
+    const result = (await service.getSecret('MY_SECRET')).reveal()
     assert.strictEqual(result, 'secret-value')
   })
 
@@ -29,14 +29,14 @@ describe('LocalSecretService', () => {
   test('should get JSON secret from local storage', async () => {
     const service = new LocalSecretService()
     await service.setSecret('JSON_KEY', { data: 42 })
-    const result = await service.getSecret('JSON_KEY')
+    const result = (await service.getSecret('JSON_KEY')).reveal()
     assert.deepStrictEqual(result, { data: 42 })
   })
 
   test('should get JSON secret from environment variables', async () => {
     const vars = new LocalVariablesService({ CONFIG: '{"port":3000}' })
     const service = new LocalSecretService(vars)
-    const result = await service.getSecret('CONFIG')
+    const result = (await service.getSecret('CONFIG')).reveal()
     assert.deepStrictEqual(result, { port: 3000 })
   })
 
@@ -52,7 +52,7 @@ describe('LocalSecretService', () => {
     const vars = new LocalVariablesService({ KEY: 'env-value' })
     const service = new LocalSecretService(vars)
     await service.setSecret('KEY', 'local-value')
-    const result = await service.getSecret('KEY')
+    const result = (await service.getSecret('KEY')).reveal()
     assert.strictEqual(result, 'local-value')
   })
 
@@ -78,3 +78,18 @@ describe('LocalSecretService', () => {
     assert.strictEqual(await service.hasSecret('DEL_KEY'), false)
   })
 })
+
+describe('LocalSecretService round-trips a wrapped secret', () => {
+  test('setSecret unwraps rather than storing the redaction', async () => {
+    const service = new LocalSecretService()
+    await service.setSecret('SOURCE', 'sk-live-DEADBEEF')
+    const read = await service.getSecret('SOURCE')
+
+    await service.setSecret('COPY', read)
+
+    assert.strictEqual(
+      (await service.getSecret('COPY')).reveal(),
+      'sk-live-DEADBEEF'
+    )
+  })
+})

package/src/services/local-secrets.ts

@@ -1,11 +1,12 @@
+import {
+  createSecretValue,
+  isSecretValue,
+  type SecretValue,
+} from '../secret-value.js'
 import { LocalVariablesService } from './local-variables.js'
-import type { SecretService } from './secret-service.js'
+import type { SecretService, SecretValues } from './secret-service.js'
 import type { VariablesService } from './variables-service.js'
 
-/**
- * Service for retrieving secrets from environment variables.
- * Supports storing secrets locally in memory for CLI operations.
- */
 export class LocalSecretService implements SecretService {
   private localSecrets: Map<string, string> = new Map()
 
@@ -21,23 +22,26 @@ export class LocalSecretService implements SecretService {
     private variables: VariablesService = new LocalVariablesService()
   ) {}
 
-  public async getSecret<T = string>(key: string): Promise<T> {
+  public async getSecret<T = string>(key: string): Promise<SecretValue<T>> {
     const localValue = this.localSecrets.get(key)
     if (localValue) {
-      return this.parseSecret<T>(localValue)
+      return createSecretValue(this.parseSecret<T>(localValue))
     }
 
     const value = await this.variables.get(key)
     if (value) {
-      return this.parseSecret<T>(value)
+      return createSecretValue(this.parseSecret<T>(value))
     }
     throw new Error('Requested secret not found')
   }
 
   public async setSecret(key: string, value: unknown): Promise<void> {
+    // Storing the wrapper would serialize it to '[secret]', so unwrap first —
+    // writing a secret back to the vault is exactly what this method is for.
+    const raw = isSecretValue(value) ? value.reveal() : value
     this.localSecrets.set(
       key,
-      typeof value === 'string' ? value : JSON.stringify(value)
+      typeof raw === 'string' ? raw : JSON.stringify(raw)
     )
   }
 
@@ -55,13 +59,13 @@ export class LocalSecretService implements SecretService {
 
   public async getSecrets<
     T extends Record<string, unknown> = Record<string, unknown>,
-  >(keys: (keyof T & string)[]): Promise<Partial<T>> {
+  >(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>> {
     const results = await Promise.allSettled(keys.map((k) => this.getSecret(k)))
     const out: Record<string, unknown> = {}
     keys.forEach((key, i) => {
       if (results[i].status === 'fulfilled')
         out[key] = (results[i] as PromiseFulfilledResult<unknown>).value
     })
-    return out as Partial<T>
+    return out as Partial<SecretValues<T>>
   }
 }

package/src/services/logger-console.test.ts

@@ -27,7 +27,6 @@ describe('ConsoleLogger', () => {
     console.log = (...args: any[]) => captured.push({ method: 'log', args })
   })
 
-  // Restore console after each test
   test('should log info at default level', () => {
     logger.info('test message')
     assert.strictEqual(captured.length, 1)

package/src/services/logger-console.ts

@@ -1,10 +1,7 @@
 import type { Logger } from './logger.js'
 import { LogLevel } from './logger.js'
 
-/**
- * Text-mode console logger.
- * Output: `INFO: message` or `[traceId] INFO: message`
- */
+/** Emits `INFO: message`, or `[traceId] INFO: message` when scoped. */
 export class ConsoleLogger implements Logger {
   private level: LogLevel = LogLevel.info
   private prefix: string
@@ -85,9 +82,8 @@ export class ConsoleLogger implements Logger {
 }
 
 /**
- * JSON-mode console logger.
- * Output: `{"level":"info","message":"...","traceId":"..."}`
- * CF Workers Logs auto-indexes JSON keys for filtering.
+ * Emits `{"level":"info","message":"...","traceId":"..."}` — one JSON object per
+ * line, because Cloudflare Workers Logs auto-indexes JSON keys for filtering.
  */
 export class JsonConsoleLogger implements Logger {
   private level: LogLevel = LogLevel.info

package/src/services/logger.ts

@@ -1,5 +1,7 @@
+import type { Safe } from '../secret-value.js'
+
 export enum LogLevel {
-  'trace', // Add this level
+  'trace',
   'debug',
   'info',
   'warn',
@@ -8,56 +10,39 @@ export enum LogLevel {
 }
 
 /**
- * Interface for logging messages at various levels.
+ * A log line is the easiest place to leak a vault secret, so every parameter is
+ * `Safe<>`-guarded: a `SecretValue` anywhere in the message or the metadata,
+ * however deeply nested, collapses to `never` and fails the build. Reveal it
+ * first if you genuinely mean to log it.
  */
 export interface Logger {
-  /**
-   * Logs an informational message.
-   * @param messageOrObj - The message or object to log.
-   * @param meta - Additional metadata to log.
-   */
-  info(messageOrObj: string | Record<string, any>, ...meta: any[]): void
-
-  /**
-   * Logs a warning message.
-   * @param messageOrObj - The message or object to log.
-   * @param meta - Additional metadata to log.
-   */
-  warn(messageOrObj: string | Record<string, any>, ...meta: any[]): void
-
-  /**
-   * Logs an error message.
-   * @param messageOrObj - The message, object, or error to log.
-   * @param meta - Additional metadata to log.
-   */
-  error(
-    messageOrObj: string | Record<string, any> | Error,
-    ...meta: any[]
+  info<M extends string | Record<string, any>, A extends unknown[]>(
+    messageOrObj: Safe<M>,
+    ...meta: { [K in keyof A]: Safe<A[K]> }
+  ): void
+
+  warn<M extends string | Record<string, any>, A extends unknown[]>(
+    messageOrObj: Safe<M>,
+    ...meta: { [K in keyof A]: Safe<A[K]> }
+  ): void
+
+  error<M extends string | Record<string, any> | Error, A extends unknown[]>(
+    messageOrObj: Safe<M>,
+    ...meta: { [K in keyof A]: Safe<A[K]> }
+  ): void
+
+  debug<A extends unknown[]>(
+    message: string,
+    ...meta: { [K in keyof A]: Safe<A[K]> }
+  ): void
+
+  trace?<A extends unknown[]>(
+    message: string,
+    ...meta: { [K in keyof A]: Safe<A[K]> }
   ): void
 
-  /**
-   * Logs a debug message.
-   * @param message - The message to log.
-   * @param meta - Additional metadata to log.
-   */
-  debug(message: string, ...meta: any[]): void
-
-  /**
-   * Logs a trace message.
-   * @param message - The message to log.
-   * @param meta - Additional metadata to log.
-   */
-  trace?(message: string, ...meta: any[]): void
-
-  /**
-   * Sets the logging level.
-   * @param level - The logging level to set.
-   */
   setLevel(level: LogLevel): void
 
-  /**
-   * Creates a scoped logger with a traceId included in every log entry.
-   * Used per-request to correlate logs across function calls.
-   */
+  /** A logger carrying a traceId on every entry, taken per-request to correlate calls. */
   scope?(traceId: string): Logger
 }

package/src/services/meta-service.test.ts

@@ -6,11 +6,7 @@ import { join } from 'node:path'
 
 import { LocalMetaService } from './meta-service.js'
 
-/**
- * Scenarios and their steps are generated into `.pikku/scenarios/` so that no
- * app-facing module imports them. Everything that reads meta off disk — the
- * console's scenario list among them — must still see them.
- */
+// knowledge: decisions/internals/scenario-meta-lives-apart-from-app-meta-but-merges-when-read-off-disk.md
 describe('LocalMetaService reads the scenario meta alongside the app meta', () => {
   let pikkuDir: string