@pikku/core 0.12.77 → 0.12.79

package/src/utils/safe-fetch.ts

@@ -32,6 +32,134 @@ function parseIPv4Octets(
   return octets as [number, number, number, number]
 }
 
+/**
+ * IPv4 blocks that must never be reachable from user-supplied URLs: private,
+ * loopback, link-local (cloud metadata), carrier-grade NAT (Alibaba's
+ * `100.100.100.200` metadata endpoint), IETF protocol assignments, benchmarking,
+ * 6to4 anycast, the documentation TEST-NETs, multicast and reserved space.
+ */
+const PRIVATE_IPV4_BLOCKS: ReadonlyArray<readonly [string, number]> = [
+  ['0.0.0.0', 8],
+  ['10.0.0.0', 8],
+  ['100.64.0.0', 10],
+  ['127.0.0.0', 8],
+  ['169.254.0.0', 16],
+  ['172.16.0.0', 12],
+  ['192.0.0.0', 24],
+  ['192.0.2.0', 24],
+  ['192.88.99.0', 24],
+  ['192.168.0.0', 16],
+  ['198.18.0.0', 15],
+  ['198.51.100.0', 24],
+  ['203.0.113.0', 24],
+  ['224.0.0.0', 4],
+  ['240.0.0.0', 4],
+]
+
+const toUint32 = (octets: [number, number, number, number]): number =>
+  ((octets[0] << 24) | (octets[1] << 16) | (octets[2] << 8) | octets[3]) >>> 0
+
+const PRIVATE_IPV4_RANGES = PRIVATE_IPV4_BLOCKS.map(([base, prefix]) => {
+  const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0
+  return [(toUint32(parseIPv4Octets(base)!) & mask) >>> 0, mask] as const
+})
+
+const isPrivateIPv4 = (octets: [number, number, number, number]): boolean => {
+  const addr = toUint32(octets)
+  return PRIVATE_IPV4_RANGES.some(
+    ([base, mask]) => (addr & mask) >>> 0 === base
+  )
+}
+
+/**
+ * Expands an IPv6 literal into its eight 16-bit groups, handling `::` elision
+ * and a trailing dotted-quad. `null` when not a well-formed IPv6 literal.
+ */
+function parseIPv6Groups(host: string): number[] | null {
+  const zoneless = host.split('%')[0]!
+  const halves = zoneless.split('::')
+  if (halves.length > 2) return null
+
+  const parseSide = (side: string): number[] | null => {
+    if (side === '') return []
+    const parts = side.split(':')
+    const groups: number[] = []
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i]!
+      if (i === parts.length - 1 && part.includes('.')) {
+        const v4 = parseIPv4Octets(part)
+        if (!v4) return null
+        groups.push((v4[0] << 8) | v4[1], (v4[2] << 8) | v4[3])
+        continue
+      }
+      if (!/^[0-9a-f]{1,4}$/.test(part)) return null
+      groups.push(parseInt(part, 16))
+    }
+    return groups
+  }
+
+  const head = parseSide(halves[0]!)
+  if (head === null) return null
+
+  if (halves.length === 1) {
+    return head.length === 8 ? head : null
+  }
+
+  const tail = parseSide(halves[1]!)
+  if (tail === null) return null
+  if (head.length + tail.length > 7) return null
+  return [...head, ...new Array(8 - head.length - tail.length).fill(0), ...tail]
+}
+
+const embeddedIPv4 = (
+  hi: number,
+  lo: number
+): [number, number, number, number] => [
+  (hi >> 8) & 0xff,
+  hi & 0xff,
+  (lo >> 8) & 0xff,
+  lo & 0xff,
+]
+
+function isPrivateIPv6(groups: number[]): boolean {
+  const [g0, g1, g2, g3, g4, g5, g6, g7] = groups as [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+  ]
+
+  if (groups.every((g) => g === 0)) return true // :: unspecified
+  if (groups.slice(0, 7).every((g) => g === 0) && g7 === 1) return true // ::1
+
+  // IPv4-mapped ::ffff:0:0/96 and IPv4-compatible ::/96
+  if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0) {
+    if (g5 === 0xffff || g5 === 0) return isPrivateIPv4(embeddedIPv4(g6, g7))
+  }
+  // NAT64 well-known prefix 64:ff9b::/96
+  if (
+    g0 === 0x64 &&
+    g1 === 0xff9b &&
+    g2 === 0 &&
+    g3 === 0 &&
+    g4 === 0 &&
+    g5 === 0
+  )
+    return isPrivateIPv4(embeddedIPv4(g6, g7))
+  // 6to4 2002::/16 carries the IPv4 address in the next 32 bits
+  if (g0 === 0x2002) return isPrivateIPv4(embeddedIPv4(g1, g2))
+  if (g0 === 0x100 && g1 === 0 && g2 === 0 && g3 === 0) return true // discard-only 100::/64
+  if ((g0 & 0xffc0) === 0xfe80) return true // link-local fe80::/10
+  if ((g0 & 0xfe00) === 0xfc00) return true // unique-local fc00::/7
+  if ((g0 & 0xffc0) === 0xfec0) return true // deprecated site-local fec0::/10
+  if ((g0 & 0xff00) === 0xff00) return true // multicast ff00::/8
+  return false
+}
+
 /**
  * Whether a hostname is an obvious internal target. Best-effort literal
  * matching only: it cannot catch a public hostname that *resolves* to a
@@ -46,31 +174,30 @@ export function isPrivateHost(hostname: string): boolean {
     return true
 
   if (host.includes(':')) {
-    if (host === '::' || host === '::1') return true
-    const mappedV4 = host.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/)
-    if (mappedV4) return isPrivateHost(mappedV4[1]!)
-    const mappedHex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/)
-    if (mappedHex) {
-      const hi = parseInt(mappedHex[1]!, 16)
-      const lo = parseInt(mappedHex[2]!, 16)
-      return isPrivateHost(
-        `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`
-      )
-    }
-    if (/^fe[89ab]/.test(host)) return true // link-local fe80::/10
-    if (host.startsWith('fc') || host.startsWith('fd')) return true // unique-local fc00::/7
-    return false
+    const groups = parseIPv6Groups(host)
+    return groups ? isPrivateIPv6(groups) : false
   }
 
   const v4 = parseIPv4Octets(host)
-  if (v4) {
-    const [a, b] = v4
-    if (a === 127 || a === 10 || a === 0) return true
-    if (a === 169 && b === 254) return true // link-local incl. cloud metadata
-    if (a === 172 && b >= 16 && b <= 31) return true
-    if (a === 192 && b === 168) return true
-  }
-  return false
+  return v4 ? isPrivateIPv4(v4) : false
+}
+
+/** Resolves a hostname to the IP addresses it points at. */
+export type HostResolver = (hostname: string) => Promise<string[]>
+
+let defaultHostResolver: HostResolver | undefined
+
+/**
+ * Installs the resolver {@link safeFetch} uses when a call passes no
+ * `resolveHost` of its own.
+ *
+ * Core cannot resolve DNS itself — Workers has no DNS API — so without a
+ * resolver the guard is literal-only and a public name pointing at
+ * `169.254.169.254` passes. Node runtimes install
+ * `nodeHostResolver` from `@pikku/core/node-host-resolver` at startup.
+ */
+export function setDefaultHostResolver(resolver: HostResolver | undefined) {
+  defaultHostResolver = resolver
 }
 
 export interface SafeFetchOptions {
@@ -81,6 +208,50 @@ export interface SafeFetchOptions {
   allowedHosts?: string[]
   /** Maximum redirect hops to follow (each re-validated). Defaults to 3. */
   maxRedirects?: number
+  /**
+   * Resolves a hostname so a *public* name pointing at a private address is
+   * refused. Defaults to whatever {@link setDefaultHostResolver} installed;
+   * pass `null` to opt a call out of resolution entirely.
+   */
+  resolveHost?: HostResolver | null
+}
+
+/** Whether a hostname is already an IP literal, which the sync check covers. */
+function isIpLiteral(hostname: string): boolean {
+  const host = hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '')
+  if (host.includes(':')) return parseIPv6Groups(host.toLowerCase()) !== null
+  return parseIPv4Octets(host) !== null
+}
+
+/**
+ * Rejects a hostname that resolves to an internal address.
+ *
+ * Resolution happens once per hop and the connection is not pinned to the
+ * address checked, so a rebind between this check and the socket connecting is
+ * still possible; catching that needs a runtime-level connect hook.
+ */
+async function assertResolvedHostAllowed(
+  hostname: string,
+  options: SafeFetchOptions
+): Promise<void> {
+  if (options.allowedHosts) return
+  const resolver =
+    options.resolveHost === null
+      ? undefined
+      : (options.resolveHost ?? defaultHostResolver)
+  if (!resolver || isIpLiteral(hostname)) return
+
+  const addresses = await resolver(hostname)
+  if (addresses.length === 0) {
+    throw new Error(`Refusing to fetch: '${hostname}' resolved to no addresses`)
+  }
+  for (const address of addresses) {
+    if (isPrivateHost(address)) {
+      throw new Error(
+        `Refusing to fetch from a private/internal host: '${hostname}' resolves to ${address}`
+      )
+    }
+  }
 }
 
 export function assertFetchableUrl(
@@ -142,7 +313,9 @@ export async function safeFetch(
   options: SafeFetchOptions = {}
 ): Promise<Response> {
   const maxRedirects = options.maxRedirects ?? 3
-  let currentUrl = assertFetchableUrl(url, options).toString()
+  const initial = assertFetchableUrl(url, options)
+  await assertResolvedHostAllowed(initial.hostname, options)
+  let currentUrl = initial.toString()
   let currentInit = init
 
   for (let hop = 0; ; hop++) {
@@ -157,10 +330,12 @@ export async function safeFetch(
     if (!location || hop >= maxRedirects) {
       return response
     }
-    const nextUrl = assertFetchableUrl(
+    const next = assertFetchableUrl(
       new URL(location, currentUrl).toString(),
       options
-    ).toString()
+    )
+    await assertResolvedHostAllowed(next.hostname, options)
+    const nextUrl = next.toString()
     await response.body?.cancel()
     let nextInit = redirectInit(response.status, currentInit)
     if (new URL(nextUrl).origin !== new URL(currentUrl).origin) {

package/src/wirings/gateway/gateway-authorization.test.ts

@@ -8,6 +8,7 @@ import {
   addGlobalPermission,
   clearPermissionsCache,
 } from '../../permissions.js'
+import { addTagMiddleware } from '../../middleware-runner.js'
 import type {
   GatewayAdapter,
   GatewayInboundMessage,
@@ -84,6 +85,31 @@ const seedCompiledMeta = () => {
   }
 }
 
+/**
+ * What the inspector records for a gateway and the function it was wired with.
+ * These tests wire gateways by hand, so nothing populates it otherwise — and it
+ * has to be in place before `wireGateway`, exactly as the generated bootstrap
+ * loads every meta file before any wiring file.
+ */
+const seedDeclaredHandler = (
+  gatewayName: string,
+  funcId: string,
+  funcMeta: Record<string, any>,
+  gatewayMeta: Record<string, any> = {}
+) => {
+  ;(pikkuState(null, 'function', 'meta') as any)[funcId] = {
+    pikkuFuncId: funcId,
+    inputSchemaName: null,
+    outputSchemaName: null,
+    ...funcMeta,
+  }
+  ;(pikkuState(null, 'gateway', 'meta') as any)[gatewayName] = {
+    pikkuFuncId: funcId,
+    name: gatewayName,
+    ...gatewayMeta,
+  }
+}
+
 const postMessage = async (route: string) => {
   const request = new Request(`http://localhost${route}`, {
     method: 'POST',
@@ -229,6 +255,68 @@ describe('gateway handler authorization', () => {
       assert.deepEqual(calls, ['ran'])
     })
 
+    test('a handler declared with pikkuFunc keeps its session requirement', async () => {
+      const calls: string[] = []
+
+      seedDeclaredHandler('declared-session', 'myHandler', {
+        sessionless: false,
+      })
+
+      wireGateway({
+        name: 'declared-session',
+        type: 'webhook',
+        route: '/webhooks/declared-session',
+        adapter: createMockAdapter(),
+        func: {
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/declared-session')
+
+      assert.equal(response.status, 403)
+      assert.deepEqual(
+        calls,
+        [],
+        'a session-required pikkuFunc must not be silently made sessionless'
+      )
+    })
+
+    test('a handler declared sessionless keeps running without a session', async () => {
+      const calls: string[] = []
+
+      seedDeclaredHandler('declared-sessionless', 'mySessionlessHandler', {
+        sessionless: true,
+      })
+
+      wireGateway({
+        name: 'declared-sessionless',
+        type: 'webhook',
+        route: '/webhooks/declared-sessionless',
+        adapter: createMockAdapter(),
+        func: {
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/declared-sessionless')
+
+      assert.equal(response.status, 200)
+      assert.deepEqual(calls, ['ran'])
+    })
+
     test('gateway-level auth: true requires a session', async () => {
       const calls: string[] = []
 
@@ -281,6 +369,49 @@ describe('gateway handler authorization', () => {
       assert.deepEqual(calls, [], 'auth: true must require a session')
     })
 
+    test('tag middleware declared for the gateway actually runs', async () => {
+      const order: string[] = []
+
+      addTagMiddleware('audited', [
+        async (_s: any, _wire: any, next: any) => {
+          order.push('middleware')
+          await next()
+        },
+      ] as any)
+
+      seedDeclaredHandler(
+        'tagged',
+        'myTaggedHandler',
+        { sessionless: true },
+        { tags: ['audited'], middleware: [{ type: 'tag', tag: 'audited' }] }
+      )
+
+      wireGateway({
+        name: 'tagged',
+        type: 'webhook',
+        route: '/webhooks/tagged',
+        adapter: createMockAdapter(),
+        func: {
+          func: async () => {
+            order.push('handler')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/tagged')
+
+      assert.equal(response.status, 200)
+      assert.deepEqual(
+        order,
+        ['middleware', 'handler'],
+        'addTagMiddleware must gate a gateway carrying the tag'
+      )
+    })
+
     test('the adapter still auto-sends the handler reply', async () => {
       const adapter = createMockAdapter()
 

package/src/wirings/gateway/gateway-runner.ts

@@ -23,20 +23,46 @@ const bridgeMiddlewareSession = async (wire: PikkuRawWire): Promise<void> => {
   }
 }
 
+/**
+ * Metadata the inspector recorded for the function the gateway was wired with.
+ * The bootstrap loads every meta file before any wiring file, so this is
+ * already populated by the time a gateway wires itself. A gateway wired by
+ * hand rather than through codegen has no entry, and falls back to the
+ * sessionless default below.
+ */
+const declaredHandlerMeta = (config: CoreGateway) => {
+  const declaredFuncId = pikkuState(null, 'gateway', 'meta')[config.name]
+    ?.pikkuFuncId
+  return declaredFuncId
+    ? pikkuState(null, 'function', 'meta')[declaredFuncId]
+    : undefined
+}
+
 // knowledge: decisions/security/gateway-handlers-run-through-the-function-runner-gate.md
 const registerGatewayHandler = (config: CoreGateway): string => {
   const funcId = gatewayHandlerFuncId(config.name)
   const funcMeta = pikkuState(null, 'function', 'meta')
+  const declared = declaredHandlerMeta(config)
   funcMeta[funcId] = {
+    ...declared,
     pikkuFuncId: funcId,
-    inputSchemaName: null,
-    outputSchemaName: null,
-    sessionless: true,
+    inputSchemaName: declared?.inputSchemaName ?? null,
+    outputSchemaName: declared?.outputSchemaName ?? null,
+    sessionless: declared?.sessionless ?? true,
   }
   addFunction(funcId, config.func as any)
   return funcId
 }
 
+/**
+ * Tag middleware the inspector resolved for this gateway. It is keyed by
+ * gateway name rather than reachable from `config`, because `tags` is a
+ * compile-time input everywhere — nothing at runtime maps a tag to its
+ * middleware group.
+ */
+const gatewayInheritedMiddleware = (config: CoreGateway) =>
+  pikkuState(null, 'gateway', 'meta')[config.name]?.middleware
+
 export const resolveGatewayAdapter = (
   config: CoreGateway,
   services: CoreSingletonServices
@@ -134,6 +160,7 @@ const wireWebhookGateway = (config: CoreGateway): void => {
 const createWebhookPostHandler = (config: CoreGateway) => {
   const { name, middleware: userMiddleware } = config
   const handlerFuncId = registerGatewayHandler(config)
+  const inheritedMiddleware = gatewayInheritedMiddleware(config)
 
   return async (
     services: CoreSingletonServices,
@@ -169,6 +196,7 @@ const createWebhookPostHandler = (config: CoreGateway) => {
         singletonServices: services,
         data: () => parsed,
         auth: config.auth,
+        inheritedMiddleware,
         wire: wire as any,
       })
     }
@@ -253,6 +281,7 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
 
   const userMiddleware = config.middleware as CorePikkuMiddleware[] | undefined
   const handlerFuncId = registerGatewayHandler(config)
+  const inheritedMiddleware = gatewayInheritedMiddleware(config)
 
   addFunction(connectFuncId, {
     auth: false,
@@ -292,6 +321,7 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
           singletonServices: services,
           data: () => parsed,
           auth: config.auth,
+          inheritedMiddleware,
           wire: wire as any,
         })
       }
@@ -333,6 +363,7 @@ export const createListenerMessageHandler = (
 ): ((rawData: unknown) => Promise<void>) => {
   const userMiddleware = config.middleware as CorePikkuMiddleware[] | undefined
   const handlerFuncId = registerGatewayHandler(config)
+  const inheritedMiddleware = gatewayInheritedMiddleware(config)
 
   return async (rawData: unknown): Promise<void> => {
     const adapter = await resolveGatewayAdapter(config, singletonServices)
@@ -354,6 +385,7 @@ export const createListenerMessageHandler = (
         singletonServices,
         data: () => parsed,
         auth: config.auth,
+        inheritedMiddleware,
         wire,
       })
     }

package/src/wirings/secret/validate-secret-definitions.test.ts

@@ -108,6 +108,53 @@ describe('validateAndBuildSecretDefinitionsMeta', () => {
     )
   })
 
+  test('should carry allowedHosts into the meta', () => {
+    const definitions = [
+      {
+        name: 'example-api',
+        displayName: 'Example API',
+        secretId: 'EXAMPLE_API_CREDENTIALS',
+        allowedHosts: ['api.example.com', '*.example.com'],
+        sourceFile: 'a.ts',
+      },
+    ]
+    const result = validateAndBuildSecretDefinitionsMeta(
+      definitions as any,
+      new Map()
+    )
+    assert.deepStrictEqual(result['example-api']!.allowedHosts, [
+      'api.example.com',
+      '*.example.com',
+    ])
+  })
+
+  test('should carry allowedHosts into the meta for a shared secretId', () => {
+    const definitions = [
+      {
+        name: 'cred1',
+        displayName: 'Cred 1',
+        secretId: 'SHARED',
+        allowedHosts: ['first.example.com'],
+        sourceFile: 'a.ts',
+      },
+      {
+        name: 'cred2',
+        displayName: 'Cred 2',
+        secretId: 'SHARED',
+        allowedHosts: ['second.example.com'],
+        sourceFile: 'b.ts',
+      },
+    ]
+    const result = validateAndBuildSecretDefinitionsMeta(
+      definitions as any,
+      new Map()
+    )
+    assert.deepStrictEqual(result['cred1']!.allowedHosts, ['first.example.com'])
+    assert.deepStrictEqual(result['cred2']!.allowedHosts, [
+      'second.example.com',
+    ])
+  })
+
   test('should handle empty definitions', () => {
     const result = validateAndBuildSecretDefinitionsMeta([], new Map())
     assert.deepStrictEqual(result, {})

package/src/wirings/secret/validate-secret-definitions.ts

@@ -57,6 +57,7 @@ export function validateAndBuildSecretDefinitionsMeta(
           oauth2: def.oauth2,
           rotationPeriod: def.rotationPeriod,
           docsUrl: def.docsUrl,
+          allowedHosts: def.allowedHosts,
           sourceFile: def.sourceFile,
         }
       }
@@ -75,6 +76,7 @@ export function validateAndBuildSecretDefinitionsMeta(
         oauth2: def.oauth2,
         rotationPeriod: def.rotationPeriod,
         docsUrl: def.docsUrl,
+        allowedHosts: def.allowedHosts,
         sourceFile: def.sourceFile,
       }
     }