@ossy/platform 1.34.0 → 1.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -20,10 +20,12 @@
     "./tasks": "./src/index.js",
     "./resources": "./src/resources/index.js",
     "./definition": "./src/Definition.js",
-    "./integrations": "./src/integration.service.js"
+    "./integrations": "./src/integration.service.js",
+    "./test": "./src/test/index.js"
   },
   "scripts": {
-    "start": "PORT=3003 node -e \"import('./src/server.js').then(m => m.startServer())\""
+    "start": "PORT=3003 node -e \"import('./src/server.js').then(m => m.startServer())\"",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --verbose"
   },
   "keywords": [],
   "author": "Ossy <yourfriends@ossy.se> (https://ossy.se)",
@@ -34,19 +36,28 @@
     "@aws-sdk/s3-request-presigner": "^3.1057.0",
     "@aws-sdk/util-create-request": "^3.972.26",
     "@aws-sdk/util-format-url": "^3.972.17",
-    "@ossy/event-store": "^1.3.0",
-    "@ossy/observability": "^1.3.0",
-    "@ossy/router": "^1.35.0",
-    "@ossy/sdk": "^1.35.0",
+    "@ossy/event-store": "^1.4.0",
+    "@ossy/observability": "^1.4.0",
+    "@ossy/policies": "^1.9.0",
+    "@ossy/router": "^1.36.0",
+    "@ossy/sdk": "^1.36.0",
+    "@ossy/tokens": "^1.9.0",
+    "@ossy/users": "^1.9.0",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
+    "jsonwebtoken": "^9.0.0",
     "mongodb": "^7.2.0",
     "morgan": ">=1.10.1 <2.0.0"
   },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "casual": "^1.6.2",
+    "jest": "^30.2.0"
+  },
   "files": [
     "src",
     "Dockerfile"
   ],
-  "gitHead": "c6697078268867d88553ca0bac08faad5cea1546"
+  "gitHead": "24df2bde0d5d8794c5a82b9e802a2594ca73a5d9"
 }

package/src/index.js

@@ -7,3 +7,8 @@ export { Definition } from './Definition.js'
 export { IntegrationService } from './integration.service.js'
 export { ConfigService } from './config.service.js'
 export { ActionService } from './actions/action.service.js'
+export { TokenService } from './token.service.js'
+export { UsersMiddleware } from './users.middleware.js'
+export { WorkspacesMiddleware } from './workspaces.middleware.js'
+export { matchesCron } from './tasks/cron.js'
+export { matchesGlob, globToRegex, policyToQueryClause } from './tasks/glob.js'

package/src/server.js

@@ -14,6 +14,9 @@ import { registerResourceTemplate } from './resources/resource-template.registry
 import { IntegrationService } from './integration.service.js'
 import { ActionService } from './actions/action.service.js'
 import { createLogger } from '@ossy/observability'
+import { ConfigService } from './config.service.js'
+import { UsersMiddleware } from './users.middleware.js'
+import { WorkspacesMiddleware } from './workspaces.middleware.js'
 
 const log = createLogger('@ossy/platform')
 
@@ -204,12 +207,10 @@ export async function startServer (options = {}) {
     return promise
   }
 
-  const userMiddleware = await loadMiddleware(buildDir)
-
   const app = express()
   app.use(morgan('tiny'))
   app.use(express.json({ strict: false }))
-  app.use(cookieParser(process.env.OSSY_COOKIE_SECRET || 'default_secret'))
+  app.use(cookieParser(ConfigService.TokenSecret))
   app.use((req, _res, next) => {
     const userSettings = JSON.parse(req.signedCookies?.['x-ossy-user-settings'] || '{}')
     req.userAppSettings = userSettings
@@ -220,7 +221,8 @@ export async function startServer (options = {}) {
     req.isAuthenticated = cookieHeader ? cookieHeader.includes('auth=') : false
     next()
   })
-  for (const mw of userMiddleware) app.use(mw)
+  app.use(UsersMiddleware.AuthenticateUser)
+  app.use(WorkspacesMiddleware.ExtractWorkspaceId())
   if (fs.existsSync(publicDir)) app.use(express.static(publicDir))
   app.use(ProxyInternal())
 
@@ -342,21 +344,6 @@ export async function startServer (options = {}) {
   return { app, server, port, close: closeServer, lifetime }
 }
 
-async function loadMiddleware (buildDir) {
-  const candidates = [
-    path.resolve(buildDir, 'public', 'static', 'middleware.js'),
-    path.resolve(buildDir, 'middleware.js'),
-  ]
-  for (const candidate of candidates) {
-    if (!fs.existsSync(candidate)) continue
-    const mod = await import(pathToFileURL(candidate).href)
-    const value = mod.default
-    if (Array.isArray(value)) return value
-    if (typeof value === 'function') return [value]
-  }
-  return []
-}
-
 export default startServer
 export { ConfigService } from './config.service.js'
 export { ActionService } from './actions/action.service.js'

package/src/tasks/cron.spec.js

@@ -0,0 +1,154 @@
+import { matchesCron } from './cron.js'
+
+function makeDate({ minute = 0, hour = 0, dom = 1, month = 1, dow = 1 } = {}) {
+  // dow: 0=Sun, 1=Mon … 6=Sat
+  // Build a Date that has exactly the requested components in local time.
+  const d = new Date(2024, month - 1, dom, hour, minute, 0, 0)
+  // Verify the day-of-week matches what was requested (some combinations are impossible).
+  // For our tests we construct dates we know are valid, so this is just a safety check.
+  if (dow !== undefined && d.getDay() !== dow) {
+    // Shift to find a date in the same month with the desired dow (best-effort).
+    const offset = (dow - d.getDay() + 7) % 7
+    d.setDate(d.getDate() + offset)
+  }
+  return d
+}
+
+describe('matchesCron', () => {
+
+  // ---------------------------------------------------------------------------
+  // Guard rails
+  // ---------------------------------------------------------------------------
+
+  it('returns false for falsy expression', () => {
+    expect(matchesCron('')).toBe(false)
+    expect(matchesCron(null)).toBe(false)
+    expect(matchesCron(undefined)).toBe(false)
+  })
+
+  it('returns false for wrong field count', () => {
+    expect(matchesCron('* * * *')).toBe(false)        // 4 fields
+    expect(matchesCron('* * * * * *')).toBe(false)    // 6 fields
+  })
+
+  // ---------------------------------------------------------------------------
+  // Wildcard
+  // ---------------------------------------------------------------------------
+
+  it('"* * * * *" matches any date', () => {
+    expect(matchesCron('* * * * *', makeDate({ minute: 0,  hour: 0,  dom: 1,  month: 1,  dow: 1 }))).toBe(true)
+    expect(matchesCron('* * * * *', makeDate({ minute: 59, hour: 23, dom: 28, month: 12, dow: 5 }))).toBe(true)
+  })
+
+  // ---------------------------------------------------------------------------
+  // Exact minute
+  // ---------------------------------------------------------------------------
+
+  it('"0 * * * *" matches only when minute === 0', () => {
+    expect(matchesCron('0 * * * *', makeDate({ minute: 0  }))).toBe(true)
+    expect(matchesCron('0 * * * *', makeDate({ minute: 1  }))).toBe(false)
+    expect(matchesCron('0 * * * *', makeDate({ minute: 30 }))).toBe(false)
+  })
+
+  it('"30 * * * *" matches only when minute === 30', () => {
+    expect(matchesCron('30 * * * *', makeDate({ minute: 30 }))).toBe(true)
+    expect(matchesCron('30 * * * *', makeDate({ minute: 0  }))).toBe(false)
+    expect(matchesCron('30 * * * *', makeDate({ minute: 31 }))).toBe(false)
+  })
+
+  // ---------------------------------------------------------------------------
+  // Step (*/n)
+  // ---------------------------------------------------------------------------
+
+  it('"*/5 * * * *" matches minutes 0,5,10,…55', () => {
+    const matches   = [0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55]
+    const nonMatch  = [1, 2, 3, 4, 6, 7, 29, 31, 59]
+
+    for (const m of matches)  expect(matchesCron('*/5 * * * *',  makeDate({ minute: m }))).toBe(true)
+    for (const m of nonMatch) expect(matchesCron('*/5 * * * *',  makeDate({ minute: m }))).toBe(false)
+  })
+
+  it('"*/15 * * * *" matches minutes 0,15,30,45', () => {
+    expect(matchesCron('*/15 * * * *', makeDate({ minute: 0  }))).toBe(true)
+    expect(matchesCron('*/15 * * * *', makeDate({ minute: 15 }))).toBe(true)
+    expect(matchesCron('*/15 * * * *', makeDate({ minute: 30 }))).toBe(true)
+    expect(matchesCron('*/15 * * * *', makeDate({ minute: 45 }))).toBe(true)
+    expect(matchesCron('*/15 * * * *', makeDate({ minute: 1  }))).toBe(false)
+    expect(matchesCron('*/15 * * * *', makeDate({ minute: 16 }))).toBe(false)
+  })
+
+  // ---------------------------------------------------------------------------
+  // Exact hour
+  // ---------------------------------------------------------------------------
+
+  it('"0 9 * * *" matches 09:00 of any day', () => {
+    expect(matchesCron('0 9 * * *', makeDate({ minute: 0, hour: 9  }))).toBe(true)
+    expect(matchesCron('0 9 * * *', makeDate({ minute: 1, hour: 9  }))).toBe(false)
+    expect(matchesCron('0 9 * * *', makeDate({ minute: 0, hour: 10 }))).toBe(false)
+  })
+
+  // ---------------------------------------------------------------------------
+  // Day-of-week
+  // ---------------------------------------------------------------------------
+
+  it('"0 9 * * 1" matches 09:00 on Mondays only', () => {
+    // dow=1 → Monday
+    const monday    = makeDate({ minute: 0, hour: 9, dow: 1 })
+    const tuesday   = makeDate({ minute: 0, hour: 9, dow: 2 })
+    const sunday    = makeDate({ minute: 0, hour: 9, dow: 0 })
+
+    expect(matchesCron('0 9 * * 1', monday)).toBe(true)
+    expect(matchesCron('0 9 * * 1', tuesday)).toBe(false)
+    expect(matchesCron('0 9 * * 1', sunday)).toBe(false)
+  })
+
+  // ---------------------------------------------------------------------------
+  // Range (a-b)
+  // ---------------------------------------------------------------------------
+
+  it('"0 9-17 * * *" matches hours 9 through 17', () => {
+    for (const h of [9, 10, 11, 12, 17]) {
+      expect(matchesCron('0 9-17 * * *', makeDate({ minute: 0, hour: h }))).toBe(true)
+    }
+    expect(matchesCron('0 9-17 * * *', makeDate({ minute: 0, hour: 8  }))).toBe(false)
+    expect(matchesCron('0 9-17 * * *', makeDate({ minute: 0, hour: 18 }))).toBe(false)
+  })
+
+  // ---------------------------------------------------------------------------
+  // Comma-separated list
+  // ---------------------------------------------------------------------------
+
+  it('"0,30 * * * *" matches minutes 0 and 30', () => {
+    expect(matchesCron('0,30 * * * *', makeDate({ minute: 0  }))).toBe(true)
+    expect(matchesCron('0,30 * * * *', makeDate({ minute: 30 }))).toBe(true)
+    expect(matchesCron('0,30 * * * *', makeDate({ minute: 15 }))).toBe(false)
+    expect(matchesCron('0,30 * * * *', makeDate({ minute: 31 }))).toBe(false)
+  })
+
+  // ---------------------------------------------------------------------------
+  // Month
+  // ---------------------------------------------------------------------------
+
+  it('"0 0 1 1 *" matches only 00:00 on Jan 1', () => {
+    const jan1  = makeDate({ minute: 0, hour: 0, dom: 1,  month: 1  })
+    const jan2  = makeDate({ minute: 0, hour: 0, dom: 2,  month: 1  })
+    const feb1  = makeDate({ minute: 0, hour: 0, dom: 1,  month: 2  })
+
+    expect(matchesCron('0 0 1 1 *', jan1)).toBe(true)
+    expect(matchesCron('0 0 1 1 *', jan2)).toBe(false)
+    expect(matchesCron('0 0 1 1 *', feb1)).toBe(false)
+  })
+
+  // ---------------------------------------------------------------------------
+  // Range step (a-b/n)
+  // ---------------------------------------------------------------------------
+
+  it('"10-50/20 * * * *" matches minutes 10, 30, 50', () => {
+    expect(matchesCron('10-50/20 * * * *', makeDate({ minute: 10 }))).toBe(true)
+    expect(matchesCron('10-50/20 * * * *', makeDate({ minute: 30 }))).toBe(true)
+    expect(matchesCron('10-50/20 * * * *', makeDate({ minute: 50 }))).toBe(true)
+    expect(matchesCron('10-50/20 * * * *', makeDate({ minute: 0  }))).toBe(false)
+    expect(matchesCron('10-50/20 * * * *', makeDate({ minute: 20 }))).toBe(false)
+  })
+
+})

package/src/tasks/glob.js

@@ -10,3 +10,40 @@ export function matchesGlob(pattern, value) {
     .replace(/§§/g, '.*')
   return new RegExp(`^${escaped}$`).test(value)
 }
+
+/**
+ * Converts a glob pattern to a RegExp (anchored at both ends).
+ *   **  → .* (any characters including /)
+ *   *   → [^/]* (any characters except /)
+ */
+export function globToRegex(pattern) {
+  const escaped = pattern
+    .replace(/\./g, '\\.')
+    .replace(/\*\*/g, '§§')   // placeholder to protect ** before replacing *
+    .replace(/\*/g, '[^/]*')
+    .replace(/§§/g, '.*')
+  return new RegExp('^' + escaped + '$')
+}
+
+/**
+ * Converts a Policy aggregate document into a MongoDB query clause that matches
+ * restricted resources the policy grants read access to.
+ * Returns null if the policy does not grant resource:read.
+ */
+export function policyToQueryClause(policy) {
+  const { where, actions, effect } = policy.state
+  if (effect !== 'allow' || !actions.includes('resource:read')) return null
+
+  const clause = { 'state.access': 'restricted' }
+
+  if (where.workspace && where.workspace !== '*')
+    clause['state.belongsTo'] = where.workspace
+
+  if (where.location && where.location !== '*')
+    clause['state.location'] = { $regex: globToRegex(where.location).source }
+
+  if (where.type && where.type !== '*')
+    clause['state.type'] = { $regex: globToRegex(where.type).source }
+
+  return clause
+}

package/src/tasks/glob.spec.js

@@ -0,0 +1,194 @@
+import { matchesGlob, globToRegex, policyToQueryClause } from './glob.js'
+
+// ---------------------------------------------------------------------------
+// matchesGlob
+// ---------------------------------------------------------------------------
+
+describe('matchesGlob', () => {
+
+  describe('image/* pattern', () => {
+    it('matches image/jpeg', () => {
+      expect(matchesGlob('image/*', 'image/jpeg')).toBe(true)
+    })
+
+    it('matches image/png', () => {
+      expect(matchesGlob('image/*', 'image/png')).toBe(true)
+    })
+
+    it('does not match image/jpeg/extra (two levels deep)', () => {
+      expect(matchesGlob('image/*', 'image/jpeg/extra')).toBe(false)
+    })
+  })
+
+  describe('* wildcard', () => {
+    it('matches any single-segment value', () => {
+      expect(matchesGlob('*', 'hello')).toBe(true)
+      expect(matchesGlob('*', 'anything')).toBe(true)
+    })
+  })
+
+  describe('/uploads/** pattern', () => {
+    it('matches /uploads/foo/bar/baz.jpg (multi-level)', () => {
+      expect(matchesGlob('/uploads/**', '/uploads/foo/bar/baz.jpg')).toBe(true)
+    })
+  })
+
+  describe('/uploads/* pattern', () => {
+    it('does not match /uploads/foo/bar (two levels deep)', () => {
+      expect(matchesGlob('/uploads/*', '/uploads/foo/bar')).toBe(false)
+    })
+  })
+
+  describe('exact strings', () => {
+    it('matches itself', () => {
+      expect(matchesGlob('image/jpeg', 'image/jpeg')).toBe(true)
+    })
+
+    it('does not match a different exact string', () => {
+      expect(matchesGlob('image/jpeg', 'image/png')).toBe(false)
+    })
+  })
+
+  describe('edge cases', () => {
+    it('returns false when pattern is empty/falsy', () => {
+      expect(matchesGlob('', 'image/jpeg')).toBe(false)
+      expect(matchesGlob(null, 'image/jpeg')).toBe(false)
+    })
+
+    it('returns false when value is null or undefined', () => {
+      expect(matchesGlob('image/*', null)).toBe(false)
+      expect(matchesGlob('image/*', undefined)).toBe(false)
+    })
+  })
+
+})
+
+// ---------------------------------------------------------------------------
+// globToRegex
+// ---------------------------------------------------------------------------
+
+describe('globToRegex', () => {
+
+  it('returns a RegExp', () => {
+    expect(globToRegex('image/*')).toBeInstanceOf(RegExp)
+  })
+
+  describe('image/* pattern', () => {
+    it('matches image/jpeg', () => {
+      expect(globToRegex('image/*').test('image/jpeg')).toBe(true)
+    })
+
+    it('does not match video/mp4', () => {
+      expect(globToRegex('image/*').test('video/mp4')).toBe(false)
+    })
+  })
+
+  describe('/docs/** pattern', () => {
+    it('matches /docs/ (just the prefix)', () => {
+      expect(globToRegex('/docs/**').test('/docs/')).toBe(true)
+    })
+
+    it('matches /docs/foo (one level deep)', () => {
+      expect(globToRegex('/docs/**').test('/docs/foo')).toBe(true)
+    })
+
+    it('matches /docs/foo/bar (two levels deep)', () => {
+      expect(globToRegex('/docs/**').test('/docs/foo/bar')).toBe(true)
+    })
+  })
+
+  describe('/docs/* pattern', () => {
+    it('matches /docs/foo (one level deep)', () => {
+      expect(globToRegex('/docs/*').test('/docs/foo')).toBe(true)
+    })
+
+    it('does not match /docs/foo/bar (two levels deep)', () => {
+      expect(globToRegex('/docs/*').test('/docs/foo/bar')).toBe(false)
+    })
+  })
+
+})
+
+// ---------------------------------------------------------------------------
+// policyToQueryClause
+// ---------------------------------------------------------------------------
+
+describe('policyToQueryClause', () => {
+
+  function makePolicy({ effect = 'allow', actions = ['resource:read'], where = {} } = {}) {
+    return {
+      state: {
+        effect,
+        actions,
+        where: {
+          workspace: '*',
+          location: '*',
+          type: '*',
+          ...where,
+        },
+      },
+    }
+  }
+
+  it('returns null when effect is not allow', () => {
+    expect(policyToQueryClause(makePolicy({ effect: 'deny' }))).toBeNull()
+  })
+
+  it('returns null when actions do not include resource:read', () => {
+    expect(policyToQueryClause(makePolicy({ actions: ['resource:write'] }))).toBeNull()
+  })
+
+  it('always includes state.access: restricted', () => {
+    const clause = policyToQueryClause(makePolicy())
+    expect(clause['state.access']).toBe('restricted')
+  })
+
+  describe('workspace field', () => {
+    it('omits state.belongsTo when workspace is *', () => {
+      const clause = policyToQueryClause(makePolicy({ where: { workspace: '*' } }))
+      expect(clause['state.belongsTo']).toBeUndefined()
+    })
+
+    it('adds state.belongsTo when workspace is a specific id', () => {
+      const clause = policyToQueryClause(makePolicy({ where: { workspace: 'ws-abc' } }))
+      expect(clause['state.belongsTo']).toBe('ws-abc')
+    })
+  })
+
+  describe('location field', () => {
+    it('omits state.location when location is *', () => {
+      const clause = policyToQueryClause(makePolicy({ where: { location: '*' } }))
+      expect(clause['state.location']).toBeUndefined()
+    })
+
+    it('adds state.location.$regex when location is a glob', () => {
+      const clause = policyToQueryClause(makePolicy({ where: { location: '/uploads/**' } }))
+      expect(clause['state.location']).toEqual({ $regex: expect.any(String) })
+      expect(clause['state.location'].$regex).toBe(globToRegex('/uploads/**').source)
+    })
+  })
+
+  describe('type field', () => {
+    it('omits state.type when type is *', () => {
+      const clause = policyToQueryClause(makePolicy({ where: { type: '*' } }))
+      expect(clause['state.type']).toBeUndefined()
+    })
+
+    it('adds state.type.$regex when type is a glob', () => {
+      const clause = policyToQueryClause(makePolicy({ where: { type: 'image/*' } }))
+      expect(clause['state.type']).toEqual({ $regex: expect.any(String) })
+      expect(clause['state.type'].$regex).toBe(globToRegex('image/*').source)
+    })
+  })
+
+  it('combines workspace, location, and type filters in a single clause', () => {
+    const clause = policyToQueryClause(makePolicy({
+      where: { workspace: 'ws-xyz', location: '/assets/**', type: 'image/*' },
+    }))
+    expect(clause['state.access']).toBe('restricted')
+    expect(clause['state.belongsTo']).toBe('ws-xyz')
+    expect(clause['state.location'].$regex).toBe(globToRegex('/assets/**').source)
+    expect(clause['state.type'].$regex).toBe(globToRegex('image/*').source)
+  })
+
+})

package/src/test/index.js

@@ -0,0 +1 @@
+export * from './test.util.js'

package/src/test/jest.setup.js

@@ -0,0 +1,24 @@
+/**
+ * Integration tests run in Node on the host. Mongo in Docker is often a single-node replica set
+ * whose persisted config advertises a hostname that only resolves inside Docker (e.g.
+ * host.docker.internal). Without directConnection, the driver discovers that host and fails with
+ * ENOTFOUND on the host.
+ *
+ * We always normalize DB_URL for Jest (except mongodb+srv and except when directConnection is
+ * already set).
+ */
+function jestMongoUrl() {
+  const url = process.env.DB_URL
+  if (!url) {
+    return 'mongodb://127.0.0.1:27017/?directConnection=true'
+  }
+  if (/^mongodb\+srv:/i.test(url)) {
+    return url
+  }
+  if (/[?&]directConnection=/i.test(url)) {
+    return url
+  }
+  return url.includes('?') ? `${url}&directConnection=true` : `${url}?directConnection=true`
+}
+
+process.env.DB_URL = jestMongoUrl()

package/src/test/test.util.js

@@ -0,0 +1,185 @@
+import casual from 'casual'
+import { EventStore } from '@ossy/event-store'
+
+/** Requires Node 18+ (global `fetch`). */
+
+/**
+ * Native `fetch` often omits `Set-Cookie` from `headers.get()`; use `getSetCookie()` when present.
+ */
+export function getSetCookieHeader(response) {
+  const { headers } = response
+  if (typeof headers.getSetCookie === 'function') {
+    return headers.getSetCookie().join('; ')
+  }
+  return headers.get('set-cookie') ?? ''
+}
+
+/**
+ * Base URL for HTTP integration tests (no trailing slash).
+ * With Docker Compose, the API is usually published on host **3001** → set:
+ * `API_TEST_BASE_URL=http://localhost:3001/api/v0`
+ */
+export function getApiTestBaseUrl() {
+  return process.env.API_TEST_BASE_URL ?? 'http://localhost:3000/api/v0'
+}
+
+const baseUrl = /* lazy */ () => getApiTestBaseUrl()
+
+export class TestUtil {
+
+  /** JSON body for POST /users/sign-up (matches AuthService). */
+  static signUpBody({ email = casual.email, firstName = 'Test', lastName = 'User' } = {}) {
+    return JSON.stringify({ email, firstName, lastName })
+  }
+
+  static AssertResponse(test) {
+    return fetch(
+      `${baseUrl()}${test.endpoint}`,
+      {
+        method: test.method,
+        headers: test.headers,
+        body: test.body
+      }
+    ).then(response => {
+      expect(response.status).toBe(test.expectedResponseStatus)
+
+      return response.json()
+        .then(data => expect(data).toEqual(test.expectedResponseBody))
+    })
+  }
+
+  static AssertAuthenticationNeeded(request) {
+    describe('given no auth token is provided', () => {
+      it('must return 401 Unauthorized', async () => {
+        const response = await TestUtil.MakeRequest(request)
+        expect(response.status).toEqual(401)
+        await expect(response.json()).resolves.toMatch('');
+      })
+    })
+  }
+
+  static MakeRequest(request) {
+    return fetch(
+      `${baseUrl()}${request.endpoint}`,
+      {
+        method: request.method,
+        headers: request.headers,
+        body: request.body
+      }
+    )
+  }
+
+  static AssertEventExist(query) {
+    return EventStore.FindEvent(query)
+      .then(event => {
+        expect(!!event).toBe(true)
+      })
+  }
+
+  static GetEvent(query) {
+    return EventStore.FindEvent(query)
+  }
+
+  static GetEvents(query) {
+    return EventStore.FindEvents(query)
+  }
+
+  /** JWT from the latest Verification token aggregate for this user (sign-up or sign-in request). */
+  static countVerificationTokenEvents() {
+    return EventStore.Collection.countDocuments({
+      aggregateType: 'Token',
+      type: 'Created',
+      'payload.type': 'Verification',
+    })
+  }
+
+  static async getLatestApiTokenCreatedEventForSubject(subjectId) {
+    const ev = await EventStore.Collection.findOne(
+      {
+        aggregateType: 'Token',
+        type: 'Created',
+        'payload.type': 'Api',
+        'payload.subject': subjectId,
+      },
+      { sort: { created: -1 } }
+    )
+    if (!ev) {
+      throw new Error('No Api token Created event for subject')
+    }
+    return ev
+  }
+
+  static async getLatestVerificationJwtForSubject(subjectId) {
+    const ev = await EventStore.Collection.findOne(
+      {
+        aggregateType: 'Token',
+        type: 'Created',
+        'payload.type': 'Verification',
+        'payload.subject': subjectId,
+      },
+      { sort: { created: -1 } }
+    )
+    if (!ev?.payload?.token) {
+      return Promise.reject(new Error('No verification token found for subject'))
+    }
+    return ev.payload.token
+  }
+
+  static GetVerificationToken() {
+    const email = `${casual.email}`
+
+    return fetch(
+      `${baseUrl()}/users/sign-up`,
+      { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: TestUtil.signUpBody({ email }) }
+    )
+    .then(() => EventStore.FindEvent({
+      aggregateType: 'User',
+      type: { $in: [ 'SignedUp' ] },
+      'payload.email': email
+    }))
+    .then(event => event.payload.verificationToken)
+  }
+
+  static async GetAuthenticatedTestUser(email = casual.email) {
+
+    await TestUtil.AssertResponse({
+        endpoint: '/users/sign-up',
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json'},
+        body: TestUtil.signUpBody({ email }),
+        expectedResponseStatus: 200,
+        expectedResponseBody: ''
+    })
+
+    const signedUpEvent = await TestUtil.GetEvent({
+      aggregateType: 'User',
+      type: { $in: [ 'SignedUp' ] },
+      'payload.email': email
+    })
+
+    const verificationJwt = await TestUtil.getLatestVerificationJwtForSubject(signedUpEvent.aggregateId)
+
+    await fetch(
+      `${baseUrl()}/users/verify-sign-in?token=${verificationJwt}`,
+      { method: 'GET' }
+    )
+
+    const signInVerifiedEvent = await TestUtil.GetEvent({
+      aggregateType: 'User',
+      aggregateId: signedUpEvent.aggregateId,
+      type: { $in: [ 'SignInVerified' ] },
+    })
+
+    return {
+      id: signedUpEvent.aggregateId,
+      token: signInVerifiedEvent.payload.token,
+      email: email,
+    }
+
+  }
+
+  static CloseDbConnection() {
+    return EventStore.CloseDbConnection()
+  }
+
+}

package/src/token.service.js

@@ -0,0 +1,45 @@
+import { nanoid } from 'nanoid'
+import jwt from 'jsonwebtoken'
+import { ConfigService } from './config.service.js'
+import { createLogger } from '@ossy/observability'
+
+const log = createLogger('tokens')
+
+export class TokenService {
+
+  static new(payload = {}) {
+    const secret = ConfigService.TokenSecret
+    const expiresIn = payload?.expiresIn || ConfigService.TokenValidity
+    return jwt.sign({ ...payload }, secret, { expiresIn })
+  }
+
+  static newApiToken(workspaceId) {
+    const secret = ConfigService.TokenSecret
+    const expiresIn = ConfigService.TokenValidity
+    return jwt.sign({ workspaceId }, secret, { expiresIn })
+  }
+
+  static verify(token) {
+    return new Promise((resolve, reject) => {
+
+      if (!token) {
+        log.debug('[TokenService] No token to verify')
+        return reject(new Error('No token'))
+      }
+
+      jwt.verify(token, ConfigService.TokenSecret, { algorithms: ['HS256'] }, (error, payload) => {
+        const errorType = (error || {}).name
+
+        if (errorType) {
+          log.error('[TokenService]: Token invalid', undefined, error)
+          return reject()
+        }
+
+        log.info('[TokenService]: Token verified')
+        resolve(payload)
+      })
+
+    })
+  }
+
+}

package/src/users.middleware.js

@@ -0,0 +1,75 @@
+import { TokenService } from './token.service.js'
+import { createLogger } from '@ossy/observability'
+import { Aggregate } from '@ossy/event-store'
+import { User } from '@ossy/users'
+import { Token } from '@ossy/tokens'
+import { ConfigService } from './config.service.js'
+import { PoliciesQueries } from '@ossy/policies'
+
+const log = createLogger('users')
+
+/**
+ * Express middleware for user authentication and context resolution.
+ * @class
+ */
+export class UsersMiddleware {
+
+  /** Reject revoked API tokens (JWT alone stays valid until expiry). */
+  static assertApiTokenActive(payload) {
+    if (payload.type !== 'Api' || !payload.jti) {
+      return Promise.resolve(payload)
+    }
+    return Aggregate.Of(Token, payload.jti)
+      .then(aggregate => {
+        const view = Token.View(aggregate.events, aggregate.state)
+        if (view.status === 'Revoked') {
+          return Promise.reject(new Error('Api token revoked'))
+        }
+        return payload
+      })
+  }
+
+  /**
+   * Resolves the caller to a real user (with workspaces and policies attached)
+   * or to the anonymous principal. Authorization / role checks belong in a separate step.
+   */
+  static AuthenticateUser (req, res, next) {
+    const authToken = req.signedCookies.auth
+      || req.get('Authorization')
+
+    const asAnonymous = () => {
+      req.userId = ConfigService.AnonymousUserId
+      req.user = { id: 'anonymous', anonymous: true, workspaces: [], policies: [] }
+      next()
+    }
+
+    if (!authToken) {
+      log.debug('[UsersMiddleware] No auth token; anonymous')
+      return asAnonymous()
+    }
+
+    log.info('[UsersMiddleware] Authenticating')
+    log.debug('[UsersMiddleware] authToken', { authToken })
+
+    TokenService.verify(authToken)
+      .then(UsersMiddleware.assertApiTokenActive)
+      .then(({ sub }) => Aggregate.Of(User, sub))
+      .then(Aggregate.View())
+      .then(user => {
+        const workspaces = user.workspaces ?? []
+
+        return PoliciesQueries.GetPoliciesForUser(user.id)
+          .then(policies => {
+            log.info('[UsersMiddleware] Resolved user')
+            req.userId = user.id
+            req.user = { ...user, workspaces, policies }
+            next()
+          })
+      })
+      .catch(error => {
+        log.debug('[UsersMiddleware] Auth failed; anonymous', { error })
+        asAnonymous()
+      })
+  }
+
+}

package/src/workspaces.middleware.js

@@ -0,0 +1,19 @@
+export class WorkspacesMiddleware {
+
+  static ExtractWorkspaceId () {
+    return (req, res, next) => {
+      const raw = req.params.workspaceId || req.get('workspaceId')
+      // Duplicate headers are merged as `id, id` — take the first segment.
+      const workspaceId = raw ? String(raw).split(',')[0].trim() : null
+
+      // req.get('workspaceId') can return the string "undefined" when the header is absent
+      if (!workspaceId || workspaceId === 'undefined') {
+        return next()
+      }
+
+      req.workspaceId = workspaceId
+      return next()
+    }
+  }
+
+}