@pikku/core 0.12.95 → 0.12.97

package/src/dev/module-runner.test.ts

@@ -8,7 +8,10 @@ import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { tmpdir } from 'node:os'
 
-import { createModuleRunner } from './module-runner.js'
+import {
+  createModuleRunner,
+  isTopLevelAwaitLimitation,
+} from './module-runner.js'
 
 // A forced-GC hook without launching the process with a flag: on Bun use the
 // native collector; on Node flip --expose-gc on just long enough to grab `gc`.
@@ -56,9 +59,10 @@ describe('createModuleRunner', { concurrency: false }, () => {
        export const createTodo = { func: async (_s: any, d: Todo) => ({ id: d.id }) }`
     )
 
-    const mod = await runner.run(file)
-    assert.ok(mod)
-    const createTodo = mod!.createTodo as {
+    const result = await runner.run(file)
+    assert.equal(result.ok, true)
+    const createTodo = (result as { exports: Record<string, unknown> }).exports
+      .createTodo as {
       func: (...a: any[]) => Promise<any>
     }
     assert.equal(typeof createTodo.func, 'function')
@@ -83,8 +87,9 @@ describe('createModuleRunner', { concurrency: false }, () => {
        wire('createTodo', createTodo)`
     )
 
-    const mod = await runner.run(userFile)
-    assert.ok(mod)
+    const result = await runner.run(userFile)
+    assert.equal(result.ok, true)
+    const mod = (result as { exports: Record<string, unknown> }).exports
 
     // Read the dependency through the same resolver the runner uses, so we
     // observe the exact instance the user module's `import` bound to (using a
@@ -103,26 +108,64 @@ describe('createModuleRunner', { concurrency: false }, () => {
 
     await writeFile(file, `export const value = { func: async () => 'v1' }`)
     const first = await runner.run(file)
-    assert.equal(await (first!.value as any).func(), 'v1')
+    assert.equal(first.ok, true)
+    assert.equal(await ((first as any).exports.value as any).func(), 'v1')
 
     await writeFile(file, `export const value = { func: async () => 'v2' }`)
     const second = await runner.run(file)
-    assert.equal(await (second!.value as any).func(), 'v2')
+    assert.equal(second.ok, true)
+    assert.equal(await ((second as any).exports.value as any).func(), 'v2')
 
     // Stable key: many reloads of one path never grow the registry.
     for (let i = 0; i < 20; i++) await runner.run(file)
     assert.equal(runner.size, 1)
   })
 
-  test('returns null on a bad edit so the caller keeps old code', async () => {
+  test('reports a bad edit with its reason so the caller can say why', async () => {
     const runner = createModuleRunner()
     const file = join(tmpDir, 'broken.ts')
     await writeFile(
       file,
       `export const oops = { func: async () => ( } ] syntax`
     )
-    const mod = await runner.run(file)
-    assert.equal(mod, null)
+    const result = await runner.run(file)
+    assert.equal(result.ok, false)
+    // The caller keeps serving the old code, so this error is the only thing
+    // standing between the developer and an unexplained stale response.
+    const { error } = result as { error: Error }
+    assert.ok(error instanceof Error)
+    assert.match(error.message, /broken\.ts/)
+    assert.equal(isTopLevelAwaitLimitation(error), false)
+  })
+
+  test('names the top-level await limitation as such', async () => {
+    const runner = createModuleRunner()
+    const file = join(tmpDir, 'tla.ts')
+    await writeFile(
+      file,
+      `const config = await Promise.resolve({ ok: true })
+       export const load = { func: async () => config }`
+    )
+    const result = await runner.run(file)
+    assert.equal(result.ok, false)
+    // Nothing is wrong with this file — the `cjs` emit is what cannot take it,
+    // and the caller has to be able to tell the developer that.
+    assert.equal(
+      isTopLevelAwaitLimitation((result as { error: Error }).error),
+      true
+    )
+  })
+
+  test('a thrown non-Error still arrives as an Error carrying its value', async () => {
+    const runner = createModuleRunner()
+    const file = join(tmpDir, 'throws-a-string.ts')
+    await writeFile(file, `throw 'boom'`)
+    const result = await runner.run(file)
+    assert.equal(result.ok, false)
+    const { error } = result as { error: Error }
+    assert.ok(error instanceof Error)
+    assert.equal(error.message, 'boom')
+    assert.equal((error as { cause?: unknown }).cause, 'boom')
   })
 
   test('editing and reimporting a module 200x does not leak memory', async () => {
@@ -153,8 +196,8 @@ describe('createModuleRunner', { concurrency: false }, () => {
 
     for (let i = 1; i <= 200; i++) {
       await write(i)
-      const mod = await runner.run(file)
-      assert.ok(mod)
+      const result = await runner.run(file)
+      assert.equal(result.ok, true)
     }
     gc()
     const growth = heapUsedMb() - baseline

package/src/dev/module-runner.ts

@@ -18,22 +18,35 @@ const loadTransform = async (): Promise<EsbuildTransform> => {
   return transformSync
 }
 
+/** The outcome of one run. A failure carries its error rather than collapsing
+ *  to `null`: the caller keeps serving the previously-loaded code, so unless the
+ *  reason travels with the failure the running process silently disagrees with
+ *  the file on disk and nothing anywhere says why. */
+export type PikkuModuleRunResult =
+  { ok: true; exports: Record<string, unknown> } | { ok: false; error: Error }
+
 export interface PikkuModuleRunner {
   /** Run a user module by absolute path. Repeated runs of one path overwrite a
-   *  single registry slot. Returns `null` on failure so the caller can keep the
-   *  previously-loaded code. */
-  run: (absPath: string) => Promise<Record<string, unknown> | null>
+   *  single registry slot. Failure is returned, not thrown, so the caller can
+   *  keep the previously-loaded code — and the discriminant makes that case
+   *  impossible to read past by accident. */
+  run: (absPath: string) => Promise<PikkuModuleRunResult>
   evict: (absPath: string) => void
   clear: () => void
   readonly size: number
 }
 
+/** esbuild states pikku's one documented reload limitation only in the text of
+ *  its transform error. Matching it is worth the fragility: the developer's file
+ *  is correct, and no amount of re-reading it will reveal that the reloader —
+ *  not the file — is what cannot cope. */
+export const isTopLevelAwaitLimitation = (error: Error): boolean =>
+  /top-level await/i.test(error.message)
+
 export const createModuleRunner = (): PikkuModuleRunner => {
   const registry = new Map<string, Record<string, unknown>>()
 
-  const run = async (
-    filePath: string
-  ): Promise<Record<string, unknown> | null> => {
+  const run = async (filePath: string): Promise<PikkuModuleRunResult> => {
     const absPath = resolve(filePath)
     try {
       const transform = await loadTransform()
@@ -55,11 +68,20 @@ export const createModuleRunner = (): PikkuModuleRunner => {
       fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath))
 
       registry.set(absPath, moduleObj.exports)
-      return moduleObj.exports
-    } catch {
+      return { ok: true, exports: moduleObj.exports }
+    } catch (thrown) {
       // A bad edit, or the one known limitation: a file using top-level
-      // `await`, which cannot be emitted in `cjs` form.
-      return null
+      // `await`, which cannot be emitted in `cjs` form. Normalised to an
+      // `Error` so the caller always has a message and a stack to print
+      // without re-deriving them; a non-`Error` throw keeps its original value
+      // as the `cause`.
+      return {
+        ok: false,
+        error:
+          thrown instanceof Error
+            ? thrown
+            : new Error(String(thrown), { cause: thrown }),
+      }
     }
   }
 

package/src/middleware/index.ts

@@ -3,6 +3,7 @@ export { authCookie } from './auth-cookie.js'
 export { authBearer } from './auth-bearer.js'
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js'
 export { cors } from './cors.js'
+export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js'
 export { telemetryOuter, telemetryInner } from './telemetry.js'
 export {
   addTagMiddleware,

package/src/middleware/require-origin.test.ts

@@ -0,0 +1,115 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js'
+import { InvalidOriginError } from '../errors/errors.js'
+import { resetPikkuState } from '../pikku-state.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+const headers = (values: Record<string, string | undefined>) => ({
+  method: () => 'post',
+  header: (name: string) => values[name],
+})
+
+const run = async (
+  config: Parameters<typeof requireOrigin>[0],
+  values: Record<string, string | undefined>
+) => {
+  let reached = false
+  const middleware = requireOrigin(config)
+  await middleware({} as any, { http: { request: headers(values) } } as any, async () => {
+    reached = true
+  })
+  return reached
+}
+
+describe('toOrigin', () => {
+  test('keeps scheme, host and port and drops the rest', () => {
+    assert.equal(toOrigin('https://app.com:8443/a/b?c=1'), 'https://app.com:8443')
+  })
+
+  test('rejects the sandboxed-iframe "null" origin and unparseable values', () => {
+    assert.equal(toOrigin('null'), null)
+    assert.equal(toOrigin(''), null)
+    assert.equal(toOrigin(undefined), null)
+  })
+})
+
+describe('isAllowedOrigin', () => {
+  test('matches the request host exactly', () => {
+    assert.equal(isAllowedOrigin('https://app.com', 'https://app.com', []), true)
+  })
+
+  test('does not suffix-match a lookalike domain', () => {
+    assert.equal(isAllowedOrigin('https://evil-app.com', null, ['https://app.com']), false)
+    assert.equal(isAllowedOrigin('https://app.com.evil.net', null, ['https://app.com']), false)
+  })
+
+  test('normalises a configured origin before comparing', () => {
+    assert.equal(isAllowedOrigin('https://app.com', null, ['https://app.com/path']), true)
+  })
+
+  test('rejects a missing origin', () => {
+    assert.equal(isAllowedOrigin(null, 'https://app.com', ['https://app.com']), false)
+  })
+})
+
+describe('requireOrigin', () => {
+  test('allows a beacon from the request own host', async () => {
+    assert.equal(
+      await run({}, { origin: 'https://app.com', host: 'app.com' }),
+      true
+    )
+  })
+
+  test('falls back to referer when only it is sent', async () => {
+    assert.equal(
+      await run({}, { referer: 'https://app.com/pricing', host: 'app.com' }),
+      true
+    )
+  })
+
+  test('honours x-forwarded-proto when deriving the host origin', async () => {
+    assert.equal(
+      await run(
+        {},
+        { origin: 'http://app.com', host: 'app.com', 'x-forwarded-proto': 'http' }
+      ),
+      true
+    )
+  })
+
+  test('rejects another site with a 403', async () => {
+    await assert.rejects(
+      () => run({}, { origin: 'https://evil.com', host: 'app.com' }),
+      InvalidOriginError
+    )
+  })
+
+  test('rejects a non-browser caller that sends no origin', async () => {
+    await assert.rejects(
+      () => run({}, { host: 'app.com' }),
+      InvalidOriginError
+    )
+  })
+
+  test('resolves configured origins from services when given a function', async () => {
+    assert.equal(
+      await run(
+        { origins: async () => ['https://other.com'] },
+        { origin: 'https://other.com', host: 'app.com' }
+      ),
+      true
+    )
+  })
+
+  test('passes through when there is no http wire at all', async () => {
+    let reached = false
+    await requireOrigin({})({} as any, {} as any, async () => {
+      reached = true
+    })
+    assert.equal(reached, true)
+  })
+})

package/src/middleware/require-origin.ts

@@ -0,0 +1,79 @@
+import type { CoreSingletonServices } from '../types/core.types.js'
+import { InvalidOriginError } from '../errors/errors.js'
+import {
+  pikkuMiddleware,
+  pikkuMiddlewareFactory,
+} from './middleware-factories.js'
+
+/** Scheme + host + port, or null for anything unparseable including the literal `"null"` origin. */
+export const toOrigin = (value: string | null | undefined): string | null => {
+  if (!value) return null
+  try {
+    const url = new URL(value)
+    return url.protocol && url.host ? url.origin : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Whether a request origin may post to an origin-locked route.
+ *
+ * The comparison is exact on the parsed origin, never a suffix match:
+ * `endsWith('myapp.com')` also accepts `https://evil-myapp.com`.
+ */
+export const isAllowedOrigin = (
+  requestOrigin: string | null,
+  hostOrigin: string | null,
+  configuredOrigins: string[]
+): boolean => {
+  if (!requestOrigin) return false
+  if (hostOrigin && requestOrigin === hostOrigin) return true
+  return configuredOrigins.some((allowed) => toOrigin(allowed) === requestOrigin)
+}
+
+/**
+ * Rejects a request with a 403 unless its `Origin` is this app's own or explicitly allowed.
+ *
+ * This is not what `cors()` does. CORS sets response headers and is enforced by the
+ * browser, so a non-browser client ignores them and the request still runs; this rejects
+ * before the function body. It stops another site's page from posting to an unauthed
+ * route — it is not flood control, because `Origin` is trusted from nobody but a browser.
+ * A missing `Origin` is rejected too: a real browser sets one on a cross-origin-capable POST.
+ */
+export const requireOrigin = pikkuMiddlewareFactory<{
+  /** Extra allowed origins beyond the request's own host, or a resolver for them. */
+  origins?:
+    | string[]
+    | ((services: CoreSingletonServices) => string[] | Promise<string[]>)
+}>(({ origins = [] } = {}) =>
+  pikkuMiddleware({
+    name: 'requireOrigin',
+    description: 'Rejects requests that did not come from this app.',
+    func: async (services, { http }, next) => {
+      const request = http?.request
+      if (!request) return next()
+
+      const requestOrigin =
+        toOrigin(request.header('origin')) ??
+        toOrigin(request.header('referer'))
+
+      const host = request.header('host')
+      const proto = request.header('x-forwarded-proto') ?? 'https'
+      const hostOrigin = host ? toOrigin(`${proto}://${host}`) : null
+
+      const configured =
+        typeof origins === 'function'
+          ? await origins(services as CoreSingletonServices)
+          : origins
+
+      if (!isAllowedOrigin(requestOrigin, hostOrigin, configured)) {
+        throw new InvalidOriginError(
+          `Rejected origin ${requestOrigin ?? '(none)'}`
+        )
+      }
+
+      return next()
+    },
+  })
+)

package/src/public-surface.json

@@ -10,15 +10,18 @@
     "authBearer",
     "authCookie",
     "cors",
+    "isAllowedOrigin",
     "pikkuAgentMiddleware",
     "pikkuChannelMiddleware",
     "pikkuChannelMiddlewareFactory",
     "pikkuMiddleware",
     "pikkuMiddlewareFactory",
     "pikkuRemoteAuthMiddleware",
+    "requireOrigin",
     "runMiddleware",
     "telemetryInner",
-    "telemetryOuter"
+    "telemetryOuter",
+    "toOrigin"
   ],
   "./function": [
     "AbandonedError",

package/src/services/secret-service.ts

@@ -4,6 +4,11 @@ import type { SecretValue } from '../classification/secret-value.js'
 export type SecretValues<T> = { [K in keyof T]: SecretValue<T[K]> }
 
 export interface SecretService {
+  /**
+   * Throws if the secret is not found, unless `defineSecret` declared it
+   * `optional` — then absence resolves `undefined`. Unwrap the result with
+   * `.reveal()`.
+   */
   getSecret<T = string>(key: string): Promise<SecretValue<T>>
   /** Answers for any key, including a disallowed one — it must not throw. */
   hasSecret(key: string): Promise<boolean>

package/src/services/typed-variables-service.test.ts

@@ -2,6 +2,7 @@ import { describe, test } from 'node:test'
 import assert from 'node:assert'
 import { TypedVariablesService } from './typed-variables-service.js'
 import { LocalVariablesService } from './local-variables.js'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 
 describe('TypedVariablesService', () => {
   const createService = (vars: Record<string, string | undefined> = {}) => {
@@ -71,3 +72,95 @@ describe('TypedVariablesService', () => {
     assert.strictEqual(missing.length, 0)
   })
 })
+
+/**
+ * Stands in for `z.enum([...]).default(...)`: a schema that answers `undefined`
+ * with a value rather than an issue. Core declares no schema library of its
+ * own, so the contract under test is Standard Schema's, not Zod's.
+ */
+const withDefault = <T>(value: T): StandardSchemaV1<unknown, T> => ({
+  '~standard': {
+    version: 1,
+    vendor: 'test',
+    validate: (input: unknown) =>
+      input === undefined ? { value } : { value: input as T },
+  },
+})
+
+const noDefault: StandardSchemaV1<unknown, string> = {
+  '~standard': {
+    version: 1,
+    vendor: 'test',
+    validate: (input: unknown) =>
+      typeof input === 'string'
+        ? { value: input }
+        : { issues: [{ message: 'expected a string' }] },
+  },
+}
+
+describe('TypedVariablesService schema defaults', () => {
+  const createService = (vars: Record<string, string | undefined> = {}) =>
+    new TypedVariablesService(new LocalVariablesService(vars), {
+      GITHUB_BASE_URL: {
+        name: 'GITHUB_BASE_URL',
+        displayName: 'GitHub Base URL',
+        schema: withDefault('https://api.github.com'),
+      },
+      API_KEY: {
+        name: 'API_KEY',
+        displayName: 'API Key',
+        schema: noDefault,
+      },
+      // The form code generation emits, deferred past the import cycle.
+      REGION: {
+        name: 'REGION',
+        displayName: 'Region',
+        schema: () => withDefault('eu-west-1'),
+      },
+    })
+
+  test('resolves a declared default when the host sets nothing', async () => {
+    const service = createService()
+    assert.strictEqual(
+      await service.get('GITHUB_BASE_URL'),
+      'https://api.github.com'
+    )
+  })
+
+  test('prefers the host value over the default', async () => {
+    const service = createService({ GITHUB_BASE_URL: 'https://ghe.internal' })
+    assert.strictEqual(
+      await service.get('GITHUB_BASE_URL'),
+      'https://ghe.internal'
+    )
+  })
+
+  test('stays undefined when the schema carries no default', async () => {
+    const service = createService()
+    assert.strictEqual(await service.get('API_KEY'), undefined)
+  })
+
+  test('resolves a default behind a thunk', async () => {
+    const service = createService()
+    assert.strictEqual(await service.get('REGION'), 'eu-west-1')
+  })
+
+  test('a defaulted variable is not missing', async () => {
+    const service = createService()
+    const missing = await service.getMissing()
+    assert.deepStrictEqual(
+      missing.map((v) => v.variableId),
+      ['API_KEY']
+    )
+  })
+
+  test('status separates having a default from being configured', async () => {
+    const service = createService()
+    const status = await service.getAllStatus()
+    const github = status.find((s) => s.variableId === 'GITHUB_BASE_URL')!
+    assert.strictEqual(github.isConfigured, false)
+    assert.strictEqual(github.hasDefault, true)
+    const apiKey = status.find((s) => s.variableId === 'API_KEY')!
+    assert.strictEqual(apiKey.hasDefault, false)
+  })
+})

package/src/services/typed-variables-service.ts

@@ -1,3 +1,4 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { VariablesService } from './variables-service.js'
 
 export interface VariableStatus {
@@ -5,13 +6,35 @@ export interface VariableStatus {
   name: string
   displayName: string
   isConfigured: boolean
+  /** Whether the declaration answers for itself when the host sets nothing. */
+  hasDefault: boolean
 }
 
 export type VariableMeta = {
   name: string
   displayName: string
+  /**
+   * The shape the variable was declared with. It is the schema itself rather
+   * than a description of it, because a default is only knowable by running it:
+   * `undefined` goes in and, if the declaration carries one, the default comes
+   * back out.
+   *
+   * A thunk is accepted, and is what code generation emits. The generated file
+   * and the file declaring the schema import each other, so reading the schema
+   * while the modules are still initializing throws — deferring the read until
+   * a variable is actually asked for is what keeps the cycle harmless.
+   */
+  schema?: StandardSchemaV1 | (() => StandardSchemaV1)
 }
 
+const isPromise = (value: unknown): value is Promise<unknown> =>
+  typeof (value as Promise<unknown> | undefined)?.then === 'function'
+
+/**
+ * A declared default is the answer to a variable nobody set, so it is resolved
+ * here rather than in `VariablesService`: the store knows what a host has put
+ * in it, and only this layer knows what was declared.
+ */
 export class TypedVariablesService<
   TMap = Record<string, unknown>,
 > implements VariablesService {
@@ -25,13 +48,23 @@ export class TypedVariablesService<
   ): Promise<TMap[K] | undefined> | TMap[K] | undefined
   get<T = string>(name: string): Promise<T | undefined> | T | undefined
   get(name: string): Promise<unknown> | unknown {
-    return this.variables.get(name)
+    const stored = this.variables.get(name)
+    if (isPromise(stored)) {
+      return stored.then((value) =>
+        value === undefined ? this.resolveDefault(name) : value
+      )
+    }
+    return stored === undefined ? this.resolveDefault(name) : stored
   }
 
   getVariables<T extends Record<string, unknown> = Record<string, unknown>>(
     names: (keyof T & string)[]
   ): Promise<Partial<T>> | Partial<T> {
-    return this.variables.getVariables<T>(names)
+    const stored = this.variables.getVariables<T>(names)
+    if (isPromise(stored)) {
+      return stored.then((values) => this.withDefaults(names, values))
+    }
+    return this.withDefaults(names, stored)
   }
 
   getAll():
@@ -62,14 +95,72 @@ export class TypedVariablesService<
         name: meta.name,
         displayName: meta.displayName,
         isConfigured: all[variableId] !== undefined,
+        hasDefault: (await this.resolveDefault(variableId)) !== undefined,
       })
     }
 
     return results
   }
 
+  /**
+   * What a deployment still has to be told. A variable that defaults is not on
+   * this list — it has a value, just not one anybody has to supply.
+   */
   async getMissing(): Promise<VariableStatus[]> {
     const all = await this.getAllStatus()
-    return all.filter((v) => !v.isConfigured)
+    return all.filter((v) => !v.isConfigured && !v.hasDefault)
+  }
+
+  /**
+   * The value the declaration answers with when the host set nothing, or
+   * `undefined` when it does not answer for itself.
+   */
+  private resolveDefault(name: string): Promise<unknown> | unknown {
+    const declared = this.variablesMeta[name]?.schema
+    if (!declared) {
+      return undefined
+    }
+    const schema = typeof declared === 'function' ? declared() : declared
+    const result = schema['~standard'].validate(undefined)
+    if (isPromise(result)) {
+      return result.then(unwrapDefault)
+    }
+    return unwrapDefault(result)
+  }
+
+  /**
+   * Kept synchronous when the defaults resolve synchronously, so a caller that
+   * did not await `getVariables` before does not have to start.
+   */
+  private withDefaults<T extends Record<string, unknown>>(
+    names: (keyof T & string)[],
+    values: Partial<T>
+  ): Promise<Partial<T>> | Partial<T> {
+    const out: Record<string, unknown> = { ...values }
+    const pending: Promise<void>[] = []
+    for (const name of names) {
+      if (out[name] !== undefined) continue
+      const fallback = this.resolveDefault(name)
+      if (isPromise(fallback)) {
+        pending.push(
+          fallback.then((value) => {
+            if (value !== undefined) out[name] = value
+          })
+        )
+      } else if (fallback !== undefined) {
+        out[name] = fallback
+      }
+    }
+    if (pending.length > 0) {
+      return Promise.all(pending).then(() => out as Partial<T>)
+    }
+    return out as Partial<T>
   }
 }
+
+/**
+ * A schema with no default rejects `undefined`, which is not a failure here —
+ * it is the answer that there is nothing to fall back to.
+ */
+const unwrapDefault = (result: StandardSchemaV1.Result<unknown>) =>
+  result.issues ? undefined : result.value