@ossy/event-store 3.11.1 → 3.12.0

package/README.md

@@ -15,12 +15,13 @@ Event sourcing primitives for the Ossy platform. Provides `Aggregate` (ADR 0008
 | `getProjection` | `projection-queries.js` | Read a projection snapshot by scope |
 | `PushInvalidation` | `push-invalidation.js` | Workspace-scoped SSE fan-out |
 | `buildInvalidationKeys`, `buildPushMessage` | `push-invalidation.js` | Derive client cache keys from events |
+| `runWithEventContext`, `getEventContextIp`, `resolveClientIp`, `stampAppendedEvent` | `event-context.js` / `resolve-client-ip.js` / `stamp-resource-event.js` | Stamp trusted connection `ip` on appended events (ADR 0016) |
 
 ## Core concepts
 
 The event store keeps two MongoDB collections:
 
-- **`eventstore`** — every resource/entity event ever appended. Immutable. ADR 0008 documents use `type` (schema id), `resourceId`, `event` (lifecycle name), `version`, `payload`, `created`, and `createdBy`.
+- **`eventstore`** — every resource/entity event ever appended. Immutable. ADR 0008 documents use `type` (schema id), `resourceId`, `event` (lifecycle name), `version`, `payload`, `created`, `createdBy`, and optional `ip` (ADR 0016; omitted from folded snapshots).
 - **`aggregates`** — denormalized state snapshots: entity/resource folds keyed by `id`, and projection snapshots keyed by `{ id: scopeId, type: projectionId, kind: 'projection' }`. Rebuilt at startup and updated on the changestream.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/event-store",
-  "version": "3.11.1",
+  "version": "3.12.0",
   "description": "Ossy Event Store — Aggregate, EventStore, and MongoDB client",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
   "author": "Ossy <yourfriends@ossy.se> (https://ossy.se)",
   "license": "MIT",
   "dependencies": {
-    "@ossy/fold": "^3.4.0",
+    "@ossy/fold": "^3.12.0",
     "@ossy/observability": "^3.0.9",
     "mongodb": "^7.2.0",
     "nanoid": "^5.1.11"
@@ -37,5 +37,5 @@
   "files": [
     "src"
   ],
-  "gitHead": "f279de3535b6bc76631cbc6b943dae8f92a1565f"
+  "gitHead": "c2650803219ad1831559b512848358d9550ffad2"
 }

package/src/event-context.js

@@ -0,0 +1,27 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+/** @type {AsyncLocalStorage<{ ip?: string | null }>} */
+const storage = new AsyncLocalStorage()
+
+/**
+ * Run `fn` with an append-time event context (ADR 0016).
+ * `ip` is the trusted connection address for this request, or null to omit.
+ *
+ * @template T
+ * @param {{ ip?: string | null }} ctx
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function runWithEventContext (ctx, fn) {
+  const ip = typeof ctx?.ip === 'string' && ctx.ip.trim() ? ctx.ip.trim() : null
+  return storage.run({ ip }, fn)
+}
+
+/**
+ * Trusted IP for the current append, or null when no HTTP request context.
+ * @returns {string | null}
+ */
+export function getEventContextIp () {
+  const ip = storage.getStore()?.ip
+  return typeof ip === 'string' && ip.trim() ? ip.trim() : null
+}

package/src/index.js

@@ -7,3 +7,6 @@ export * from './projection-rebuild.js'
 export { getProjection } from './projection-queries.js'
 export { PushInvalidation, buildInvalidationKeys, buildPushMessage } from './push-invalidation.js'
 export { ensureEventStoreIndexes, resetEnsureIndexesForTests } from './ensure-indexes.js'
+export { runWithEventContext, getEventContextIp } from './event-context.js'
+export { resolveClientIp } from './resolve-client-ip.js'
+export { stampAppendedEvent } from './stamp-resource-event.js'

package/src/projection-rebuild.js

@@ -124,7 +124,8 @@ export class ProjectionRebuild {
       for (const [scopeId, scopeEvents] of byScope) {
         let state = ProjectionClass.initialState?.(scopeId) ?? {}
         for (const event of scopeEvents) {
-          state = ProjectionClass.Apply(event, state) ?? state
+          // Apply may be sync or async (e.g. MaxMind enrichment on page-view location).
+          state = (await Promise.resolve(ProjectionClass.Apply(event, state))) ?? state
         }
         const version = scopeEvents.length
         const last = scopeEvents[scopeEvents.length - 1]
@@ -161,7 +162,8 @@ export class ProjectionRebuild {
     )
 
     const state = snapshot?.state ?? ProjectionClass.initialState?.(scopeId) ?? {}
-    const next = ProjectionClass.Apply(event, state)
+    // Apply may be sync or async (e.g. MaxMind enrichment on page-view location).
+    const next = await Promise.resolve(ProjectionClass.Apply(event, state))
     if (!next) return
 
     const version = (snapshot?.version ?? 0) + 1

package/src/resolve-client-ip.js

@@ -0,0 +1,40 @@
+/**
+ * Best-effort client IP from an Express-like request.
+ *
+ * Prefer `req.ip` when Express `trust proxy` is enabled (platform defaults on —
+ * CloudFront → ALB). Then `socket.remoteAddress`. Leftmost `X-Forwarded-For`
+ * is **last resort only** (spoofable if the edge did not set `req.ip`).
+ * Never read `payload.ip` (ADR 0016).
+ *
+ * @param {unknown} req
+ * @returns {string | null}
+ */
+export function resolveClientIp (req) {
+  if (!req || typeof req !== 'object') return null
+  const request = /** @type {{ headers?: Record<string, unknown>, ip?: unknown, socket?: { remoteAddress?: string } }} */ (req)
+  if (typeof request.ip === 'string' && request.ip.trim()) {
+    return normalizeIp(request.ip.trim())
+  }
+  const remote = request.socket?.remoteAddress
+  if (typeof remote === 'string' && remote.trim()) {
+    return normalizeIp(remote.trim())
+  }
+  const xff = request.headers?.['x-forwarded-for']
+  if (typeof xff === 'string' && xff.trim()) {
+    return normalizeIp(xff.split(',')[0].trim()) || null
+  }
+  if (Array.isArray(xff) && typeof xff[0] === 'string') {
+    return normalizeIp(xff[0].split(',')[0].trim()) || null
+  }
+  return null
+}
+
+/**
+ * Strip IPv6-mapped IPv4 prefix (`::ffff:1.2.3.4` → `1.2.3.4`).
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeIp (value) {
+  if (value.startsWith('::ffff:')) return value.slice('::ffff:'.length)
+  return value
+}

package/src/resolve-client-ip.spec.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from '@jest/globals'
+import { resolveClientIp } from './resolve-client-ip.js'
+
+describe('resolveClientIp', () => {
+  it('prefers req.ip over socket and spoofable X-Forwarded-For', () => {
+    expect(resolveClientIp({
+      headers: { 'x-forwarded-for': '1.2.3.4, 5.6.7.8' },
+      socket: { remoteAddress: '10.0.0.1' },
+      ip: '9.9.9.9',
+    })).toBe('9.9.9.9')
+  })
+
+  it('prefers socket.remoteAddress over X-Forwarded-For', () => {
+    expect(resolveClientIp({
+      headers: { 'x-forwarded-for': '1.2.3.4' },
+      socket: { remoteAddress: '10.0.0.1' },
+    })).toBe('10.0.0.1')
+  })
+
+  it('uses leftmost XFF only as last resort', () => {
+    expect(resolveClientIp({
+      headers: { 'x-forwarded-for': '1.2.3.4, 5.6.7.8' },
+    })).toBe('1.2.3.4')
+    expect(resolveClientIp({
+      socket: { remoteAddress: '10.0.0.1' },
+    })).toBe('10.0.0.1')
+  })
+
+  it('normalizes IPv6-mapped IPv4 and returns null when empty', () => {
+    expect(resolveClientIp({ ip: '::ffff:8.8.8.8' })).toBe('8.8.8.8')
+    expect(resolveClientIp({ headers: {} })).toBeNull()
+    expect(resolveClientIp(null)).toBeNull()
+  })
+})

package/src/schema-stream.js

@@ -1,6 +1,7 @@
 import { nanoid } from 'nanoid'
 import { EventStore, getResourceStream } from './event-store.js'
 import { Mongo, withMongoReconnect } from './mongodb.js'
+import { stampAppendedEvent } from './stamp-resource-event.js'
 import { createLogger } from '@ossy/observability'
 
 const log = createLogger('event-store')
@@ -39,14 +40,11 @@ export class SchemaStream {
     return stream => {
       const version = stream.version + 1
       const schemaId = event.type ?? stream.events[0]?.type ?? stream.AggregateRoot?.SchemaId
-      const saved = {
-        ...event,
-        type: schemaId,
-        id: nanoid(),
-        created: Date.now(),
+      const saved = stampAppendedEvent(event, {
         resourceId: stream.id,
         version,
-      }
+        type: schemaId,
+      })
       return EventStore.AppendResourceEvent(saved)
         .then(() => {
           stream.version = version

package/src/stamp-resource-event.js

@@ -0,0 +1,35 @@
+import { nanoid } from 'nanoid'
+import { getEventContextIp } from './event-context.js'
+
+/**
+ * Platform fields on an appended eventstore row (ADR 0008 + 0016).
+ * Caller-supplied `ip` / `id` / `created` / `version` / `resourceId` are ignored.
+ *
+ * @param {object} event
+ * @param {{ resourceId: string, version: number, type?: string }} meta
+ * @returns {object}
+ */
+export function stampAppendedEvent (event, { resourceId, version, type }) {
+  const {
+    ip: _ignoredIp,
+    id: _ignoredId,
+    created: _ignoredCreated,
+    resourceId: _ignoredResourceId,
+    version: _ignoredVersion,
+    ...rest
+  } = event ?? {}
+
+  const saved = {
+    ...rest,
+    type: type ?? rest.type,
+    id: nanoid(),
+    created: Date.now(),
+    resourceId,
+    version,
+  }
+
+  const ip = getEventContextIp()
+  if (ip) saved.ip = ip
+
+  return saved
+}

package/src/stamp-resource-event.spec.js

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it, jest } from '@jest/globals'
+import { runWithEventContext } from './event-context.js'
+import { stampAppendedEvent } from './stamp-resource-event.js'
+
+describe('stampAppendedEvent', () => {
+  afterEach(() => {
+    jest.useRealTimers()
+  })
+
+  it('stamps platform fields and omits ip without request context', () => {
+    jest.useFakeTimers({ now: 1_700_000_000_000 })
+    const saved = stampAppendedEvent({
+      event: 'Created',
+      createdBy: 'user-1',
+      ip: '1.2.3.4',
+      payload: { name: 'Doc' },
+    }, { resourceId: 'res-1', version: 1, type: '@ossy/example/schema/doc' })
+
+    expect(saved).toMatchObject({
+      event: 'Created',
+      createdBy: 'user-1',
+      type: '@ossy/example/schema/doc',
+      resourceId: 'res-1',
+      version: 1,
+      created: 1_700_000_000_000,
+      payload: { name: 'Doc' },
+    })
+    expect(saved.id).toEqual(expect.any(String))
+    expect(saved).not.toHaveProperty('ip')
+  })
+
+  it('stamps trusted context ip and ignores caller ip', () => {
+    const saved = runWithEventContext({ ip: '203.0.113.10' }, () =>
+      stampAppendedEvent({
+        event: 'Patched',
+        createdBy: 'user-1',
+        ip: '1.2.3.4',
+        payload: { name: 'Doc' },
+      }, { resourceId: 'res-1', version: 2, type: '@ossy/example/schema/doc' }),
+    )
+
+    expect(saved.ip).toBe('203.0.113.10')
+    expect(saved.event).toBe('Patched')
+  })
+
+  it('stamps ip on Deleted', () => {
+    const saved = runWithEventContext({ ip: '198.51.100.9' }, () =>
+      stampAppendedEvent({
+        event: 'Deleted',
+        createdBy: 'user-1',
+        payload: {},
+      }, { resourceId: 'res-1', version: 3, type: '@ossy/example/schema/doc' }),
+    )
+
+    expect(saved.ip).toBe('198.51.100.9')
+    expect(saved.event).toBe('Deleted')
+  })
+})