@ossy/platform 3.11.1 → 3.13.0

package/Dockerfile

@@ -1,16 +1,15 @@
 # Build context: ossy/packages/platform directory.
-# From repo root: docker build -f ossy/packages/platform/Dockerfile ossy/packages/platform
-# In CI, this image is built and pushed to ghcr.io/ossy-se/runtime:latest by the Publish workflow.
+# From repo root: docker build -f packages/platform/Dockerfile packages/platform
+# Pushed by the manual "Deploy platform runtime" workflow (not npm Publish).
 FROM node:24-bookworm-slim
 
 WORKDIR /app
 
 COPY package.json ./
 
-# Install production deps only.
-# @ossy/router and @ossy/sdk must be resolvable — in production these are
-# published npm packages; in monorepo CI use npm pack + install.
-RUN npm install --omit=dev --no-audit --no-fund --loglevel=error
+# Production deps from npm. --legacy-peer-deps: transitive peers on an older
+# lockstep patch must not fail the image when ranges are otherwise valid.
+RUN npm install --omit=dev --no-audit --no-fund --loglevel=error --legacy-peer-deps
 
 COPY src ./src
 COPY docker-healthcheck.js ./docker-healthcheck.js
@@ -29,7 +28,7 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
 
 # Required env vars at runtime:
 #   OSSY_API_KEY   — Ossy API JWT for CMS reads
-#   OSSY_API_URL   — (optional) override API base, default https://api.ossy.se/api/v0
+#   OSSY_API_URL   — (optional) override API base, default https://ossy.se/api/v0
 #   PORT           — (optional) override listen port, default 3000
 #   OSSY_SERVICE_NAME — (optional) `/health` service label, default runtime
 CMD ["node", "src/runtime.js"]

package/README.md

@@ -11,12 +11,13 @@ At startup `@ossy/platform`:
 3. Registers and runs all **startup hooks** (`*.startup.js`) in order.
 4. Connects all **integrations** (`*.integration.js`) by calling `connect({ env })`.
 5. Registers all **tasks** (`*.task.js`) with `TaskService` and starts the cron scheduler.
-6. Registers all **schemas** (`*.schema.js`) with `registerSchema`.
-7. Rebuilds all **aggregates** (`*.aggregate.js`) from the event store.
-8. Registers all **actions** (`*.action.js`) with `ActionService`.
-9. Mounts **MCP** at `POST /mcp` and serves `GET /capabilities.json`.
-10. Starts an Express server that routes requests to pages (`*.page.jsx`) and API handlers (`*.api.js`).
-11. Auto-mounts every action at `POST /actions` (`{ action, payload }`).
+6. When `MAXMIND_LICENSE_KEY` is set, downloads GeoLite2-Country to `GEOLITE2_COUNTRY_MMDB` (default `/tmp/GeoLite2-Country.mmdb`) so Host location projections can resolve country. Missing key or a failed download does not prevent startup (#804).
+7. Registers all **schemas** (`*.schema.js`) with `registerSchema`.
+8. Rebuilds all **aggregates** (`*.aggregate.js`) from the event store.
+9. Registers all **actions** (`*.action.js`) with `ActionService`.
+10. Mounts **MCP** at `POST /mcp` and serves `GET /capabilities.json`.
+11. Starts an Express server that routes requests to pages (`*.page.jsx`) and API handlers (`*.api.js`).
+12. Auto-mounts every action at `POST /actions` (`{ action, payload }`).
 
 Page SSR fills the `app:content` slot (see `PlatformShell` and `resolve-app-slots` in `@ossy/app`). App chrome uses namespaced keys such as `app:header` mapped from `export const slots` in `*.layout.jsx`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "3.11.1",
+  "version": "3.13.0",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -46,16 +46,16 @@
     "@aws-sdk/util-format-url": "^3.972.17",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@ossy/config": "^3.0.9",
-    "@ossy/event-store": "^3.11.1",
+    "@ossy/event-store": "^3.12.0",
     "@ossy/locale": "^3.4.0",
     "@ossy/manifest": "^3.9.0",
     "@ossy/observability": "^3.0.9",
     "@ossy/policies": "^3.0.9",
     "@ossy/schema": "^3.8.0",
-    "@ossy/sdk": "^3.11.1",
+    "@ossy/sdk": "^3.12.0",
     "@ossy/tokens": "^3.11.1",
-    "@ossy/users": "^3.11.1",
-    "@ossy/workspaces": "^3.11.1",
+    "@ossy/users": "^3.12.0",
+    "@ossy/workspaces": "^3.12.0",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
@@ -76,5 +76,5 @@
     "Dockerfile",
     "docker-healthcheck.js"
   ],
-  "gitHead": "f279de3535b6bc76631cbc6b943dae8f92a1565f"
+  "gitHead": "7a02d1e056b731aa36f72e3f8d6df941101dbd50"
 }

package/src/geoip/ensure-geolite2-country.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { createLogger } from '@ossy/observability'
+import { extractMmdbFromTarGz } from './extract-mmdb-from-tar-gz.js'
+import {
+  GEOLITE2_COUNTRY_DOWNLOAD_TIMEOUT_MS,
+  GEOLITE2_COUNTRY_MMDB_PATH,
+} from './geolite2-country-path.js'
+
+const log = createLogger('@ossy/platform/geoip')
+
+const LEGACY_DOWNLOAD_URL = 'https://download.maxmind.com/app/geoip_download'
+const PERMALINK_DOWNLOAD_URL = 'https://download.maxmind.com/geoip/databases/GeoLite2-Country/download?suffix=tar.gz'
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function resolveGeoLite2CountryPath (env = process.env) {
+  const raw = env.GEOLITE2_COUNTRY_MMDB ?? env.OSSY_GEOLITE2_COUNTRY_MMDB ?? ''
+  const trimmed = String(raw).trim()
+  return trimmed || GEOLITE2_COUNTRY_MMDB_PATH
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string | null}
+ */
+export function resolveMaxMindLicenseKey (env = process.env) {
+  const raw = env.MAXMIND_LICENSE_KEY ?? env.OSSY_MAXMIND_LICENSE_KEY ?? ''
+  const key = String(raw).trim()
+  return key || null
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string | null}
+ */
+export function resolveMaxMindAccountId (env = process.env) {
+  const raw = env.MAXMIND_ACCOUNT_ID ?? env.OSSY_MAXMIND_ACCOUNT_ID ?? ''
+  const id = String(raw).trim()
+  return id || null
+}
+
+/**
+ * @param {{ licenseKey: string, accountId?: string | null }} options
+ * @returns {{ url: string, headers: Record<string, string> }}
+ */
+export function maxMindDownloadRequest ({ licenseKey, accountId }) {
+  if (accountId) {
+    const basic = Buffer.from(`${accountId}:${licenseKey}`, 'utf8').toString('base64')
+    return {
+      url: PERMALINK_DOWNLOAD_URL,
+      headers: { Authorization: `Basic ${basic}` },
+    }
+  }
+  const url = `${LEGACY_DOWNLOAD_URL}?edition_id=GeoLite2-Country&license_key=${encodeURIComponent(licenseKey)}&suffix=tar.gz`
+  return { url, headers: {} }
+}
+
+/**
+ * Download GeoLite2-Country when `MAXMIND_LICENSE_KEY` is set.
+ *
+ * Shared by every `@ossy/platform` `startServer` image (ossy.se, plexus-sanitas,
+ * future `services[]` sites). Missing key / failed download is non-fatal:
+ * the process starts and location tiles omit `countryCode` (#804).
+ *
+ * @param {{
+ *   env?: NodeJS.ProcessEnv,
+ *   fetchImpl?: typeof fetch,
+ * }} [options]
+ * @returns {Promise<string | null>} destination path when a readable `.mmdb` is in place
+ */
+export async function ensureGeoLite2Country (options = {}) {
+  const env = options.env ?? process.env
+  const fetchImpl = options.fetchImpl ?? fetch
+  const dest = resolveGeoLite2CountryPath(env)
+
+  if (fs.existsSync(dest)) {
+    env.GEOLITE2_COUNTRY_MMDB = dest
+    log.info(`GeoLite2-Country already present at ${dest}`)
+    return dest
+  }
+
+  const licenseKey = resolveMaxMindLicenseKey(env)
+  if (!licenseKey) {
+    log.info('MAXMIND_LICENSE_KEY unset — skipping GeoLite2-Country download; location tiles will omit countryCode')
+    return null
+  }
+
+  const accountId = resolveMaxMindAccountId(env)
+  const { url, headers } = maxMindDownloadRequest({ licenseKey, accountId })
+
+  try {
+    log.info('Downloading GeoLite2-Country from MaxMind')
+    const response = await fetchImpl(url, {
+      headers,
+      signal: AbortSignal.timeout(GEOLITE2_COUNTRY_DOWNLOAD_TIMEOUT_MS),
+    })
+    if (!response.ok) {
+      throw new Error(`MaxMind download HTTP ${response.status}`)
+    }
+    const gzipped = Buffer.from(await response.arrayBuffer())
+    const mmdb = extractMmdbFromTarGz(gzipped)
+
+    fs.mkdirSync(path.dirname(dest), { recursive: true })
+    const staging = `${dest}.download`
+    fs.writeFileSync(staging, mmdb)
+    fs.renameSync(staging, dest)
+    env.GEOLITE2_COUNTRY_MMDB = dest
+    log.info(`Wrote GeoLite2-Country to ${dest}`)
+    return dest
+  } catch (err) {
+    log.warn('GeoLite2-Country download failed — location tiles will omit countryCode', {
+      error: err instanceof Error ? err.message : String(err),
+    })
+    return null
+  }
+}

package/src/geoip/ensure-geolite2-country.spec.js

@@ -0,0 +1,140 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from '@jest/globals'
+import {
+  ensureGeoLite2Country,
+  maxMindDownloadRequest,
+  resolveGeoLite2CountryPath,
+  resolveMaxMindLicenseKey,
+} from './ensure-geolite2-country.js'
+import { GEOLITE2_COUNTRY_MMDB_PATH } from './geolite2-country-path.js'
+import { makeUstarTarGz } from './tar-fixture.js'
+
+const originalGeo = process.env.GEOLITE2_COUNTRY_MMDB
+const originalOssyGeo = process.env.OSSY_GEOLITE2_COUNTRY_MMDB
+const originalKey = process.env.MAXMIND_LICENSE_KEY
+const originalOssyKey = process.env.OSSY_MAXMIND_LICENSE_KEY
+const originalAccount = process.env.MAXMIND_ACCOUNT_ID
+
+function restoreEnv () {
+  restore('GEOLITE2_COUNTRY_MMDB', originalGeo)
+  restore('OSSY_GEOLITE2_COUNTRY_MMDB', originalOssyGeo)
+  restore('MAXMIND_LICENSE_KEY', originalKey)
+  restore('OSSY_MAXMIND_LICENSE_KEY', originalOssyKey)
+  restore('MAXMIND_ACCOUNT_ID', originalAccount)
+}
+
+function restore (key, previous) {
+  if (previous == null) delete process.env[key]
+  else process.env[key] = previous
+}
+
+describe('resolveGeoLite2CountryPath', () => {
+  afterEach(restoreEnv)
+
+  it('defaults to the well-known container path', () => {
+    expect(resolveGeoLite2CountryPath({})).toBe(GEOLITE2_COUNTRY_MMDB_PATH)
+  })
+
+  it('prefers GEOLITE2_COUNTRY_MMDB', () => {
+    expect(resolveGeoLite2CountryPath({ GEOLITE2_COUNTRY_MMDB: '/var/lib/GeoLite2-Country.mmdb' }))
+      .toBe('/var/lib/GeoLite2-Country.mmdb')
+  })
+})
+
+describe('resolveMaxMindLicenseKey', () => {
+  it('returns null when unset', () => {
+    expect(resolveMaxMindLicenseKey({})).toBeNull()
+  })
+
+  it('trims OSSY_MAXMIND_LICENSE_KEY', () => {
+    expect(resolveMaxMindLicenseKey({ OSSY_MAXMIND_LICENSE_KEY: '  abc  ' })).toBe('abc')
+  })
+})
+
+describe('maxMindDownloadRequest', () => {
+  it('uses the legacy query URL without an account id', () => {
+    const request = maxMindDownloadRequest({ licenseKey: 'secret-key' })
+    expect(request.url).toContain('edition_id=GeoLite2-Country')
+    expect(request.url).toContain('license_key=secret-key')
+    expect(request.headers.Authorization).toBeUndefined()
+  })
+
+  it('uses basic auth permalink when account id is set', () => {
+    const request = maxMindDownloadRequest({ licenseKey: 'secret-key', accountId: '123456' })
+    expect(request.url).toBe('https://download.maxmind.com/geoip/databases/GeoLite2-Country/download?suffix=tar.gz')
+    expect(request.headers.Authorization).toBe(`Basic ${Buffer.from('123456:secret-key').toString('base64')}`)
+  })
+})
+
+describe('ensureGeoLite2Country', () => {
+  afterEach(restoreEnv)
+
+  it('skips download when the license key is missing', async () => {
+    const env = {}
+    let called = false
+    const dest = await ensureGeoLite2Country({
+      env,
+      fetchImpl: async () => {
+        called = true
+        return { ok: false, status: 500, arrayBuffer: async () => new ArrayBuffer(0) }
+      },
+    })
+    expect(dest).toBeNull()
+    expect(called).toBe(false)
+  })
+
+  it('returns the existing file without fetching', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'geolite2-'))
+    const dest = path.join(dir, 'GeoLite2-Country.mmdb')
+    fs.writeFileSync(dest, 'already-there')
+    const env = { GEOLITE2_COUNTRY_MMDB: dest, MAXMIND_LICENSE_KEY: 'secret-key' }
+    let called = false
+    const result = await ensureGeoLite2Country({
+      env,
+      fetchImpl: async () => {
+        called = true
+        return { ok: true, status: 200, arrayBuffer: async () => new ArrayBuffer(0) }
+      },
+    })
+    expect(result).toBe(dest)
+    expect(called).toBe(false)
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('writes the extracted mmdb and sets GEOLITE2_COUNTRY_MMDB', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'geolite2-'))
+    const dest = path.join(dir, 'GeoLite2-Country.mmdb')
+    const payload = Buffer.from('country-mmdb')
+    const archive = makeUstarTarGz('GeoLite2-Country_20240101/GeoLite2-Country.mmdb', payload)
+    const env = { GEOLITE2_COUNTRY_MMDB: dest, MAXMIND_LICENSE_KEY: 'secret-key' }
+
+    const result = await ensureGeoLite2Country({
+      env,
+      fetchImpl: async () => ({
+        ok: true,
+        status: 200,
+        arrayBuffer: async () => archive,
+      }),
+    })
+
+    expect(result).toBe(dest)
+    expect(env.GEOLITE2_COUNTRY_MMDB).toBe(dest)
+    expect(fs.readFileSync(dest).equals(payload)).toBe(true)
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('does not throw when MaxMind returns an error', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'geolite2-'))
+    const dest = path.join(dir, 'GeoLite2-Country.mmdb')
+    const env = { GEOLITE2_COUNTRY_MMDB: dest, MAXMIND_LICENSE_KEY: 'secret-key' }
+    const result = await ensureGeoLite2Country({
+      env,
+      fetchImpl: async () => ({ ok: false, status: 401, arrayBuffer: async () => new ArrayBuffer(0) }),
+    })
+    expect(result).toBeNull()
+    expect(fs.existsSync(dest)).toBe(false)
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+})

package/src/geoip/extract-mmdb-from-tar-gz.js

@@ -0,0 +1,68 @@
+import { gunzipSync } from 'node:zlib'
+
+const BLOCK = 512
+const MAX_ARCHIVE_BYTES = 50 * 1024 * 1024
+const MAX_MMDB_BYTES = 20 * 1024 * 1024
+
+/**
+ * @param {Buffer} header
+ * @param {number} start
+ * @param {number} len
+ * @returns {number}
+ */
+function readOctal (header, start, len) {
+  const raw = header.subarray(start, start + len).toString('utf8').replace(/\0/g, '').trim()
+  if (!raw) return 0
+  const parsed = Number.parseInt(raw, 8)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+/**
+ * @param {Buffer} header
+ * @returns {string}
+ */
+function headerName (header) {
+  const name = header.subarray(0, 100).toString('utf8').replace(/\0/g, '').trim()
+  const prefix = header.subarray(345, 345 + 155).toString('utf8').replace(/\0/g, '').trim()
+  return prefix ? `${prefix}/${name}` : name
+}
+
+/**
+ * Extract the first `.mmdb` member from a MaxMind GeoLite2 `.tar.gz`.
+ * Writes none of the tar paths — callers choose the destination (#804).
+ *
+ * @param {Buffer} gzipped
+ * @returns {Buffer}
+ */
+export function extractMmdbFromTarGz (gzipped) {
+  if (!Buffer.isBuffer(gzipped) || gzipped.length < 20) {
+    throw new Error('GeoLite2 archive is empty or invalid')
+  }
+  if (gzipped.length > MAX_ARCHIVE_BYTES) {
+    throw new Error('GeoLite2 archive is too large')
+  }
+
+  const tar = gunzipSync(gzipped)
+  let offset = 0
+  while (offset + BLOCK <= tar.length) {
+    const header = tar.subarray(offset, offset + BLOCK)
+    if (header.every((byte) => byte === 0)) break
+
+    const size = readOctal(header, 124, 12)
+    const typeflag = String.fromCharCode(header[156] || 0)
+    const name = headerName(header)
+    offset += BLOCK
+    const padded = Math.ceil(size / BLOCK) * BLOCK
+    const content = tar.subarray(offset, Math.min(offset + size, tar.length))
+    offset += padded
+
+    const isFile = typeflag === '0' || typeflag === '\0' || typeflag === ''
+    if (!isFile || !name.toLowerCase().endsWith('.mmdb')) continue
+    if (content.length > MAX_MMDB_BYTES) {
+      throw new Error('GeoLite2 mmdb member is too large')
+    }
+    return Buffer.from(content)
+  }
+
+  throw new Error('No .mmdb file in GeoLite2 archive')
+}

package/src/geoip/extract-mmdb-from-tar-gz.spec.js

@@ -0,0 +1,20 @@
+import { extractMmdbFromTarGz } from './extract-mmdb-from-tar-gz.js'
+import { makeUstarTarGz } from './tar-fixture.js'
+
+describe('extractMmdbFromTarGz', () => {
+  it('returns the first .mmdb member', () => {
+    const payload = Buffer.from('fake-mmdb-bytes')
+    const archive = makeUstarTarGz('GeoLite2-Country_20240101/GeoLite2-Country.mmdb', payload)
+    expect(extractMmdbFromTarGz(archive).equals(payload)).toBe(true)
+  })
+
+  it('skips non-mmdb members', () => {
+    const readme = Buffer.from('not the database')
+    const archive = makeUstarTarGz('GeoLite2-Country_20240101/COPYRIGHT.txt', readme)
+    expect(() => extractMmdbFromTarGz(archive)).toThrow(/No \.mmdb file/)
+  })
+
+  it('rejects empty input', () => {
+    expect(() => extractMmdbFromTarGz(Buffer.alloc(0))).toThrow(/empty or invalid/)
+  })
+})

package/src/geoip/geolite2-country-path.js

@@ -0,0 +1,10 @@
+/**
+ * Well-known GeoLite2-Country path on platform containers (#804).
+ *
+ * Keep in sync with `@ossy/deployment-tools` `GEOLITE2_COUNTRY_MMDB_PATH`
+ * (ECS task-definition env). Writable on Fargate ephemeral disk.
+ */
+export const GEOLITE2_COUNTRY_MMDB_PATH = '/tmp/GeoLite2-Country.mmdb'
+
+/** Abort hung MaxMind downloads before ECS health startPeriod (60s). */
+export const GEOLITE2_COUNTRY_DOWNLOAD_TIMEOUT_MS = 30_000

package/src/geoip/tar-fixture.js

@@ -0,0 +1,31 @@
+import { gzipSync } from 'node:zlib'
+
+const BLOCK = 512
+
+/**
+ * Build a gzipped ustar archive with a single file (test fixture).
+ *
+ * @param {string} name
+ * @param {Buffer | string} content
+ * @returns {Buffer}
+ */
+export function makeUstarTarGz (name, content) {
+  const data = Buffer.isBuffer(content) ? content : Buffer.from(content)
+  const header = Buffer.alloc(BLOCK)
+  header.write(name, 0, 100, 'utf8')
+  header.write('0000644\0', 100, 8, 'utf8')
+  header.write('0000000\0', 108, 8, 'utf8')
+  header.write('0000000\0', 116, 8, 'utf8')
+  header.write(`${data.length.toString(8).padStart(11, '0')}\0`, 124, 12, 'utf8')
+  header.write('00000000000\0', 136, 12, 'utf8')
+  header.write('        ', 148, 8, 'utf8')
+  header[156] = 0x30
+  header.write('ustar\0', 257, 6, 'utf8')
+  header.write('00', 263, 2, 'utf8')
+  let sum = 0
+  for (const byte of header) sum += byte
+  header.write(`${sum.toString(8).padStart(6, '0')}\0 `, 148, 8, 'utf8')
+  const padded = Buffer.alloc(Math.ceil(data.length / BLOCK) * BLOCK)
+  data.copy(padded)
+  return gzipSync(Buffer.concat([header, padded, Buffer.alloc(1024)]))
+}

package/src/proxy-internal.js

@@ -14,6 +14,25 @@ function normalizeWorkspaceIdHeader (value) {
   return first || undefined
 }
 
+/**
+ * Map `/@ossy…` to the same-process path (`/actions` or `/api/v0…`).
+ * @param {string} originalUrl
+ * @returns {string}
+ */
+export function ossyProxyLocalPath (originalUrl) {
+  const pathAfterOssy = String(originalUrl || '').replace(/^\/@ossy/, '') || '/'
+  const pathOnly = pathAfterOssy.split('?')[0]
+  if (pathOnly === '/actions' || pathOnly === '/events') {
+    return pathAfterOssy.startsWith('/') ? pathAfterOssy : `/${pathAfterOssy}`
+  }
+  return `/api/v0${pathAfterOssy.startsWith('/') ? pathAfterOssy : `/${pathAfterOssy}`}`
+}
+
+/** Absolute OSSY_API_URL → HTTP hop. Unset / relative → same Express app. */
+export function isRemoteOssyApiUrl (envUrl = process.env.OSSY_API_URL) {
+  return /^https?:\/\//i.test(String(envUrl || '').trim())
+}
+
 export function ProxyInternal () {
   return (req, res, next) => {
     if (!req.originalUrl.startsWith('/@ossy')) {
@@ -47,15 +66,20 @@ export function ProxyInternal () {
       return
     }
 
+    if (!isRemoteOssyApiUrl()) {
+      const dest = ossyProxyLocalPath(req.originalUrl)
+      log.info(`[@ossy/platform][proxy] ${req.method} ${req.originalUrl} → ${dest} (same origin)`)
+      req.url = dest
+      req.originalUrl = dest
+      return next()
+    }
+
     log.info(`[@ossy/platform][proxy] ${req.method} ${req.originalUrl}`)
 
-    const domain = (process.env.OSSY_API_URL || 'https://api.ossy.se')
+    const domain = String(process.env.OSSY_API_URL).trim()
       .replace(/\/api\/v0\/?$/, '')
       .replace(/\/$/, '')
-    const pathAfterOssy = req.originalUrl.replace(/^\/@ossy/, '') || '/'
-    // POST /actions lives on the app server root — not under /api/v0.
-    const upstreamPath = pathAfterOssy === '/actions' ? '/actions' : `/api/v0${pathAfterOssy}`
-    const url = `${domain}${upstreamPath}`
+    const url = `${domain}${ossyProxyLocalPath(req.originalUrl)}`
     const forwardedHeaders = JSON.parse(JSON.stringify(req.headers))
     const workspaceId = normalizeWorkspaceIdHeader(req.get('workspaceId'))
 

package/src/proxy-internal.spec.js

@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, it, jest } from '@jest/globals'
+import {
+  isRemoteOssyApiUrl,
+  ossyProxyLocalPath,
+  ProxyInternal,
+} from './proxy-internal.js'
+
+describe('ossyProxyLocalPath', () => {
+  it('maps REST under /@ossy onto /api/v0', () => {
+    expect(ossyProxyLocalPath('/@ossy/users/me')).toBe('/api/v0/users/me')
+    expect(ossyProxyLocalPath('/@ossy/apps/ask?domain=ossy.se'))
+      .toBe('/api/v0/apps/ask?domain=ossy.se')
+  })
+
+  it('keeps POST /actions and GET /events at the server root', () => {
+    expect(ossyProxyLocalPath('/@ossy/actions')).toBe('/actions')
+    expect(ossyProxyLocalPath('/@ossy/actions?x=1')).toBe('/actions?x=1')
+    expect(ossyProxyLocalPath('/@ossy/events')).toBe('/events')
+  })
+})
+
+describe('isRemoteOssyApiUrl', () => {
+  it('treats unset, empty, and relative values as same-origin', () => {
+    expect(isRemoteOssyApiUrl(undefined)).toBe(false)
+    expect(isRemoteOssyApiUrl('')).toBe(false)
+    expect(isRemoteOssyApiUrl('/api/v0')).toBe(false)
+  })
+
+  it('treats absolute http(s) as a remote hop', () => {
+    expect(isRemoteOssyApiUrl('https://ossy.se/api/v0')).toBe(true)
+    expect(isRemoteOssyApiUrl('http://localhost:3006')).toBe(true)
+  })
+})
+
+describe('ProxyInternal same-origin rewrite', () => {
+  const original = process.env.OSSY_API_URL
+
+  afterEach(() => {
+    if (original === undefined) delete process.env.OSSY_API_URL
+    else process.env.OSSY_API_URL = original
+  })
+
+  it('rewrites /@ossy onto this process when OSSY_API_URL is unset', () => {
+    delete process.env.OSSY_API_URL
+    const req = { originalUrl: '/@ossy/users/me', url: '/@ossy/users/me', method: 'GET' }
+    const next = jest.fn()
+    ProxyInternal()(req, {}, next)
+    expect(req.url).toBe('/api/v0/users/me')
+    expect(req.originalUrl).toBe('/api/v0/users/me')
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+
+  it('rewrites /@ossy/actions onto POST /actions', () => {
+    delete process.env.OSSY_API_URL
+    const req = { originalUrl: '/@ossy/actions', url: '/@ossy/actions', method: 'POST' }
+    const next = jest.fn()
+    ProxyInternal()(req, {}, next)
+    expect(req.url).toBe('/actions')
+    expect(req.originalUrl).toBe('/actions')
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+})

package/src/runtime.js

@@ -71,13 +71,24 @@ async function getSiteContext (domain) {
  *
  * Environment variables:
  *   OSSY_API_KEY  — API JWT for CMS reads (required)
- *   OSSY_API_URL  — Override API base URL (default: https://api.ossy.se/api/v0)
+ *   OSSY_API_URL  — Override API base URL (default: https://ossy.se/api/v0)
  *   PORT          — Override listen port (default: 3000)
  */
 export async function startRuntime ({ port } = {}) {
   const resolvedPort = port ?? resolvePort()
 
   const app = express()
+  // CloudFront → ALB → Node: hop count so `req.ip` is the viewer (#769).
+  // Default 2. Avoid `true` (leftmost XFF — spoofable). Override via OSSY_TRUST_PROXY_HOPS.
+  {
+    const raw = process.env.OSSY_TRUST_PROXY_HOPS
+    if (raw != null && String(raw).trim() !== '') {
+      const hops = Number(raw)
+      app.set('trust proxy', Number.isFinite(hops) && hops >= 0 ? hops : 2)
+    } else {
+      app.set('trust proxy', 2)
+    }
+  }
   // Liveness for ALB/ECS — before site loading so probes never depend on CMS/domain.
   // Prefer OSSY_SERVICE_NAME (ECS task env) when set.
   mountHealthEndpoint(app)
@@ -97,7 +108,7 @@ export async function startRuntime ({ port } = {}) {
     next()
   })
 
-  // Proxy /@ossy/* to the upstream Ossy API
+  // Proxy leftover /@ossy/* onto this process (/api/v0, /actions) unless OSSY_API_URL is absolute.
   app.use(ProxyInternal())
 
   // Force a fresh site download without waiting for the TTL to expire

package/src/server.js

@@ -28,6 +28,7 @@ import {
 } from './entitlements/action-entitlement.js'
 import { closePushSseConnections, mountPushSse } from './push/mount-push-sse.js'
 import { mountHealthEndpoint } from './health.js'
+import { ensureGeoLite2Country } from './geoip/ensure-geolite2-country.js'
 import {
   createSlowRequestLogger,
   createTimedOperation,
@@ -289,6 +290,10 @@ export async function startServer (options = {}) {
 
   TaskService.startScheduler()
 
+  // GeoLite2-Country for Host location projections (#804). Shared by every
+  // startServer image (ossy.se, plexus-sanitas, …). Missing key is non-fatal.
+  await ensureGeoLite2Country()
+
   if (process.env.DB_URL) {
     await ensureEventStoreIndexes().catch((err) => {
       log.error('Failed to ensure MongoDB indexes — aggregate reads may be very slow', undefined, err)
@@ -326,6 +331,17 @@ export async function startServer (options = {}) {
   }
 
   const app = express()
+  // CloudFront → ALB → Node: hop count so `req.ip` is the viewer (#769).
+  // Default 2. Avoid `true` (leftmost XFF — spoofable). Override via OSSY_TRUST_PROXY_HOPS.
+  {
+    const raw = process.env.OSSY_TRUST_PROXY_HOPS
+    if (raw != null && String(raw).trim() !== '') {
+      const hops = Number(raw)
+      app.set('trust proxy', Number.isFinite(hops) && hops >= 0 ? hops : 2)
+    } else {
+      app.set('trust proxy', 2)
+    }
+  }
   // Liveness for ALB/ECS — before auth so probes never depend on cookies/Mongo.
   // Prefer OSSY_SERVICE_NAME (ECS task env) when set.
   mountHealthEndpoint(app)

package/src/site-loader.js

@@ -10,7 +10,7 @@ const CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
 const DOWNLOAD_CONCURRENCY = 10
 const BASE_DIR = path.join(os.tmpdir(), 'ossy-rt')
 
-const API_URL = process.env.OSSY_API_URL || 'https://api.ossy.se/api/v0'
+const API_URL = process.env.OSSY_API_URL || 'https://ossy.se/api/v0'
 const API_KEY = process.env.OSSY_API_KEY
 
 /** @type {Map<string, { buildDir: string, workspaceId: string, loadedAt: number }>} */

package/src/tasks/task-service.js

@@ -4,6 +4,7 @@ import { IntegrationService } from '../integration.service.js'
 import { createLogger } from '@ossy/observability'
 import { isPrimaryTaskForAction, taskIdFromActionId } from '@ossy/schema'
 import { TaskRunService } from '../audit/task-run-service.js'
+import { resolveClientIp, runWithEventContext } from '@ossy/event-store'
 
 const SCHEDULER_INTERVAL_MS = 60_000
 const _serviceLog = createLogger('TaskService')
@@ -108,18 +109,20 @@ export class TaskService {
       log: context.log ?? createLogger(id),
     }
 
-    return TaskRunService.execute({
-      taskId: id,
-      handler: task.handler,
-      context: invokeContext,
-      trigger: 'invoke',
-      triggeredBy: {
-        channel: context.req ? undefined : 'api',
-        actionInvocationId: context.actionInvocationId ?? null,
-      },
-      executionEnv: 'ossy_server',
-      audit,
-    })
+    return runWithEventContext({ ip: resolveClientIp(context.req) }, () =>
+      TaskRunService.execute({
+        taskId: id,
+        handler: task.handler,
+        context: invokeContext,
+        trigger: 'invoke',
+        triggeredBy: {
+          channel: context.req ? undefined : 'api',
+          actionInvocationId: context.actionInvocationId ?? null,
+        },
+        executionEnv: 'ossy_server',
+        audit,
+      }),
+    )
   }
 
   /** @param {string} id */

package/src/test/flow-runner.js

@@ -26,6 +26,7 @@ import { assertDownloadFilenames, resolveDownloadTarget } from './flow-download.
 import { resolveFilesTarget } from './flow-files.js'
 import { resolvePressKey } from './flow-press.js'
 import { resolveViewportSize } from './flow-viewport.js'
+import { flowBelongsToShard, parseFlowShard, sortFlowsForShard } from './flow-shard.js'
 
 export {
   applyFormFieldOverrides,
@@ -39,6 +40,12 @@ export {
   resolveActionMatchers,
   resolveActionService,
 } from './flow-action.js'
+export {
+  flowBelongsToShard,
+  flowIdsForShard,
+  parseFlowShard,
+  sortFlowsForShard,
+} from './flow-shard.js'
 export { resolveClickTarget } from './flow-click.js'
 export {
   assertDownloadFilenames,
@@ -840,17 +847,32 @@ export function registerFlow (mod, options = {}) {
 /**
  * Register all flows listed in `manifest.flows[]`.
  * @param {string} manifestPath Absolute path to build/manifest.json
+ * @param {{ shard?: string }} [options] Optional shard override (`N/M`); defaults to `E2E_FLOW_SHARD`
  */
-export async function registerFlowsFromManifest (manifestPath) {
+export async function registerFlowsFromManifest (manifestPath, options = {}) {
   const manifest = loadManifest(manifestPath)
   const buildDir = path.dirname(manifestPath)
   const staticDir = path.join(buildDir, 'public', 'static')
-
-  for (const entry of manifest.flows ?? []) {
+  const shard = parseFlowShard(options.shard ?? process.env.E2E_FLOW_SHARD)
+  // Sort by stable flow id so independently built matrix jobs partition identically
+  // even when package discovery/`readdir` order differs (#768 / #770).
+  const flows = sortFlowsForShard(manifest.flows ?? [])
+  let registered = 0
+
+  for (let i = 0; i < flows.length; i++) {
+    if (!flowBelongsToShard(i, shard)) continue
+    const entry = flows[i]
     const chunkName = entry.entry.replace(/^\/static\//, '')
     const chunkPath = path.join(staticDir, chunkName)
     const mod = await import(pathToFileURL(chunkPath).href + `?ts=${Date.now()}`)
     registerFlow(mod, { manifestPath, locale: manifest.config?.defaultLanguage })
+    registered += 1
+  }
+
+  if (shard) {
+    console.log(
+      `[e2e] flow shard ${shard.index}/${shard.total}: registered ${registered}/${flows.length} flows`,
+    )
   }
 }
 

package/src/test/flow-shard.js

@@ -0,0 +1,66 @@
+/**
+ * CI flow partitioning helpers.
+ *
+ * All product flows register from one Playwright `runner.spec.js`, so Playwright's
+ * file-level `--shard` leaves shards 2..N empty. Matrix jobs set `E2E_FLOW_SHARD=N/M`
+ * and the flow runner registers only that slice.
+ *
+ * Membership is by **stable flow id order**, not discovery/`readdir` order — each
+ * matrix job builds independently (#768 / #770).
+ */
+
+/**
+ * Parse `E2E_FLOW_SHARD` / explicit shard string (`1/4`) into 1-based index + total.
+ *
+ * @param {string | undefined | null} value
+ * @returns {{ index: number, total: number } | null}
+ */
+export function parseFlowShard (value = process.env.E2E_FLOW_SHARD) {
+  if (value == null || value === '') return null
+  const match = String(value).trim().match(/^(\d+)\s*\/\s*(\d+)$/)
+  if (!match) {
+    throw new Error(`Invalid E2E_FLOW_SHARD "${value}" (expected N/M, e.g. 1/4)`)
+  }
+  const index = Number(match[1])
+  const total = Number(match[2])
+  if (!Number.isInteger(index) || !Number.isInteger(total) || total < 1 || index < 1 || index > total) {
+    throw new Error(`Invalid E2E_FLOW_SHARD "${value}" (index must be 1..total)`)
+  }
+  return { index, total }
+}
+
+/**
+ * Deterministic order for shard partitioning (localeCompare on flow id).
+ *
+ * @param {Array<{ id?: string }>} flows
+ * @returns {Array<{ id?: string }>}
+ */
+export function sortFlowsForShard (flows) {
+  return [...(flows ?? [])].sort((a, b) =>
+    String(a?.id ?? '').localeCompare(String(b?.id ?? '')),
+  )
+}
+
+/**
+ * Stable round-robin membership for CI flow matrix jobs.
+ * @param {number} flowIndex 0-based position in the **id-sorted** flow list
+ * @param {{ index: number, total: number } | null} shard
+ */
+export function flowBelongsToShard (flowIndex, shard) {
+  if (!shard) return true
+  return flowIndex % shard.total === shard.index - 1
+}
+
+/**
+ * Flow ids owned by a shard for a given (unordered) manifest list.
+ *
+ * @param {Array<{ id?: string }>} flows
+ * @param {{ index: number, total: number } | null} shard
+ * @returns {string[]}
+ */
+export function flowIdsForShard (flows, shard) {
+  const ordered = sortFlowsForShard(flows)
+  return ordered
+    .filter((_, i) => flowBelongsToShard(i, shard))
+    .map((flow) => String(flow.id ?? ''))
+}

package/src/test/flow-shard.spec.js

@@ -0,0 +1,73 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  flowBelongsToShard,
+  flowIdsForShard,
+  parseFlowShard,
+  sortFlowsForShard,
+} from './flow-shard.js'
+
+describe('parseFlowShard', () => {
+  it('returns null for empty values', () => {
+    expect(parseFlowShard(undefined)).toBeNull()
+    expect(parseFlowShard(null)).toBeNull()
+    expect(parseFlowShard('')).toBeNull()
+  })
+
+  it('parses N/M', () => {
+    expect(parseFlowShard('1/4')).toEqual({ index: 1, total: 4 })
+    expect(parseFlowShard(' 3 / 4 ')).toEqual({ index: 3, total: 4 })
+  })
+
+  it('rejects invalid shapes', () => {
+    expect(() => parseFlowShard('4')).toThrow(/Invalid E2E_FLOW_SHARD/)
+    expect(() => parseFlowShard('0/4')).toThrow(/Invalid E2E_FLOW_SHARD/)
+    expect(() => parseFlowShard('5/4')).toThrow(/Invalid E2E_FLOW_SHARD/)
+  })
+})
+
+describe('flowBelongsToShard', () => {
+  it('keeps every flow when shard is null', () => {
+    expect(flowBelongsToShard(0, null)).toBe(true)
+    expect(flowBelongsToShard(7, null)).toBe(true)
+  })
+
+  it('round-robins indices across shards', () => {
+    const shard1 = { index: 1, total: 4 }
+    const shard2 = { index: 2, total: 4 }
+    const owned = [...Array(8).keys()].filter(i => flowBelongsToShard(i, shard1))
+    const owned2 = [...Array(8).keys()].filter(i => flowBelongsToShard(i, shard2))
+    expect(owned).toEqual([0, 4])
+    expect(owned2).toEqual([1, 5])
+  })
+})
+
+describe('sortFlowsForShard / flowIdsForShard', () => {
+  it('sorts by stable id regardless of input order', () => {
+    const a = [{ id: 'zeta' }, { id: 'alpha' }, { id: 'mu' }]
+    const b = [{ id: 'mu' }, { id: 'zeta' }, { id: 'alpha' }]
+    expect(sortFlowsForShard(a).map(f => f.id)).toEqual(['alpha', 'mu', 'zeta'])
+    expect(sortFlowsForShard(b).map(f => f.id)).toEqual(['alpha', 'mu', 'zeta'])
+  })
+
+  it('assigns the same ids to shard 1/4 for two different input orders', () => {
+    const shard = { index: 1, total: 4 }
+    const orderA = [
+      { id: '@ossy/z/flows/c' },
+      { id: '@ossy/a/flows/x' },
+      { id: '@ossy/m/flows/y' },
+      { id: '@ossy/b/flows/w' },
+      { id: '@ossy/n/flows/v' },
+      { id: '@ossy/c/flows/u' },
+      { id: '@ossy/d/flows/t' },
+      { id: '@ossy/e/flows/s' },
+    ]
+    const orderB = [...orderA].reverse()
+
+    expect(flowIdsForShard(orderA, shard)).toEqual(flowIdsForShard(orderB, shard))
+    // id-sorted: a/x, b/w, c/u, d/t, e/s, m/y, n/v, z/c → shard 1 owns indices 0,4
+    expect(flowIdsForShard(orderA, shard)).toEqual([
+      '@ossy/a/flows/x',
+      '@ossy/e/flows/s',
+    ])
+  })
+})