@ossy/platform 1.33.0 → 1.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "1.33.0",
+  "version": "1.35.0",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -20,29 +20,44 @@
     "./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)",
   "license": "MIT",
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1057.0",
     "@aws-sdk/client-ses": "^3.0.0",
-    "@ossy/event-store": "^1.2.0",
-    "@ossy/observability": "^1.2.0",
-    "@ossy/router": "^1.34.0",
-    "@ossy/sdk": "^1.34.0",
+    "@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.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": "46cdd391ec01ea9210543ee7b14661f77079a7e7"
+  "gitHead": "24df2bde0d5d8794c5a82b9e802a2594ca73a5d9"
 }

package/src/actions/action.service.js

@@ -0,0 +1,73 @@
+import { createLogger } from '@ossy/observability'
+
+const log = createLogger('platform/actions')
+
+/** @type {Map<string, { id: string, access: string, run: Function }>} */
+const _actions = new Map()
+
+/**
+ * Registry and invoker for `*.action.js` command handlers.
+ *
+ * Actions are named, discoverable functions exposed at `POST /actions/:id`.
+ * Each action exports:
+ *   - `id`     {string}   — unique slug, e.g. `'authentication/request-sign-in'`
+ *   - `access` {string}   — `'public'` | `'authenticated'` | `'workspace'` (default `'authenticated'`)
+ *   - `run`    {Function} — async handler receiving `{ payload, sdk, log, integrations, req }`
+ */
+export const ActionService = {
+  /**
+   * Register an action module (as imported from a bundled entry).
+   * Validates that `id` is a non-empty string and `run` is a function.
+   *
+   * @param {{ id: string, access?: string, run: Function }} mod
+   */
+  register (mod) {
+    const { id, run, access = 'authenticated' } = mod ?? {}
+
+    if (typeof id !== 'string' || id.trim() === '') {
+      throw new Error(`[ActionService] Action module must export a non-empty string "id" (got ${JSON.stringify(id)})`)
+    }
+    if (typeof run !== 'function') {
+      throw new Error(`[ActionService] Action "${id}" must export a "run" function`)
+    }
+
+    if (_actions.has(id)) {
+      log.warn(`[ActionService] Action "${id}" already registered — overwriting`)
+    }
+
+    _actions.set(id, { id, access, run })
+    log.info(`[ActionService] Registered action "${id}" (access: ${access})`)
+  },
+
+  /**
+   * Look up a registered action by id. Returns `null` when not found.
+   *
+   * @param {string} id
+   * @returns {{ id: string, access: string, run: Function } | null}
+   */
+  get (id) {
+    return _actions.get(id) ?? null
+  },
+
+  /**
+   * Returns all registered actions.
+   *
+   * @returns {{ id: string, access: string, run: Function }[]}
+   */
+  all () {
+    return [..._actions.values()]
+  },
+
+  /**
+   * Invoke an action by id, forwarding the provided context.
+   *
+   * @param {string} id
+   * @param {{ payload?: unknown, sdk?: unknown, log?: unknown, integrations?: unknown, req?: unknown }} context
+   * @returns {Promise<unknown>}
+   */
+  async invoke (id, context = {}) {
+    const action = _actions.get(id)
+    if (!action) throw new Error(`[ActionService] Action not found: "${id}"`)
+    return action.run(context)
+  },
+}

package/src/config.service.js

@@ -0,0 +1,48 @@
+/**
+ * API Configuration
+ * @class
+ */
+export class ConfigService {
+
+  static Port = process.env.BE_PORT || 3000
+  static Domain = process.env.DOMAIN || `localhost:${ConfigService.Port}`
+  static WebClientDomain = process.env.WEB_CLIENT_DOMAIN || `http://localhost:3000`
+  static MongoUrl = process.env.DB_URL || 'mongodb://mongodb:27017/'
+  static DbName = process.env.DB_NAME || 'test'
+  static TokenSecret = process.env.TOKEN_SECRET || 'testsecret2'
+  static TokenValidity = process.env.TOKEN_VALIDITY || 60 * 60 * 24 * 14
+  static LimitedAccessCode = process.env.LIMITED_ACCESS_CODE || 'test'
+  static BuildEnvironment = process.env.BUILD_ENVIRONMENT
+  static BotUserEmail = process.env.BOT_USER_EMAIL || 'ossybot@ossy.se'
+  static BotUserId = process.env.BOT_USER_ID || 'Mil5qAL7jDFCTyuKD_BKb'
+  /** Set on `req.userId` when there is no valid session; role checks can treat this as unauthenticated. */
+  static AnonymousUserId = process.env.ANONYMOUS_USER_ID || 'anonymous'
+  static MediaRepository = process.env.MEDIA_REPOSITORY
+  static MediaCdnDomainName = process.env.MEDIA_CDN_DOMAIN_NAME
+  static awsAccessKeyId = process.env.AWS_ACCESS_KEY_ID
+  static awsSecretAccessKey = process.env.AWS_SECRET_ACCESS_KEY
+  static SesRegion = process.env.SES_REGION || 'eu-north-1'
+  static Debug = process.env.DEBUG
+
+  /**
+   * Derives the web client base URL from the incoming request's Origin or Referer
+   * header so that email links point back to whichever domain the user came from
+   * (e.g. http://ossy.local, http://localhost:3002).  Falls back to the
+   * WEB_CLIENT_DOMAIN env var / default when no header is present.
+   */
+  static getWebClientBaseUrl(req) {
+    const origin = req?.headers?.origin
+    if (origin && origin !== 'null') return origin
+
+    const referer = req?.headers?.referer
+    if (referer) {
+      try {
+        const { origin: refOrigin } = new URL(referer)
+        if (refOrigin && refOrigin !== 'null') return refOrigin
+      } catch {}
+    }
+
+    return ConfigService.WebClientDomain
+  }
+
+}

package/src/index.js

@@ -5,3 +5,10 @@ export { registerResourceTemplate, getSystemResourceTemplates } from './resource
 export { normalizeAndValidateDocumentContent, validateResourceTemplatesForImport, ALLOWED_FIELD_TYPES } from './resources/resource-template.validation.js'
 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

@@ -12,7 +12,11 @@ import { TaskService } from './tasks/task-service.js'
 import { ChangeStream } from './tasks/change-stream.js'
 import { registerResourceTemplate } from './resources/resource-template.registry.js'
 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')
 
@@ -56,6 +60,7 @@ export function loadManifest (buildDir) {
   const aggregates = Array.isArray(manifest.aggregates) ? manifest.aggregates : []
   const integrations = Array.isArray(manifest.integrations) ? manifest.integrations : []
   const startups = Array.isArray(manifest.startups) ? manifest.startups : []
+  const actions = Array.isArray(manifest.actions) ? manifest.actions : []
   for (const e of entries) {
     if ((e.type === 'page' || e.type === 'api') && !validRoutable(e)) {
       log.warn(`Skipping ${e.type} "${e.id}" — manifest entry has no path.`)
@@ -71,6 +76,7 @@ export function loadManifest (buildDir) {
     aggregates,
     integrations,
     startups,
+    actions,
     config: manifest.config || {},
   }
 }
@@ -159,6 +165,17 @@ export async function startServer (options = {}) {
     }
   }
 
+  // Action registration — import each bundled action module and register it
+  // with ActionService so it can be looked up and invoked at runtime.
+  for (const actionEntry of manifest.actions ?? []) {
+    try {
+      const mod = await import(resolveEntryUrl(actionEntry.entry, buildDir))
+      ActionService.register(mod)
+    } catch (err) {
+      log.error(`Failed to load action "${actionEntry.id}"`, undefined, err)
+    }
+  }
+
   // Register the SDK so all tasks receive it as `sdk`.
   // Priority: explicit options.sdk → SDK.of() from env vars → null (direct-DB fallback in tasks).
   const botSdk = (process.env.API_URL && process.env.OSSY_API_KEY)
@@ -190,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
@@ -206,10 +221,41 @@ 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())
 
+  // Actions endpoint — auto-exposes every registered `*.action.js` handler.
+  // Access rules are enforced here; business logic lives in the action's `run`.
+  app.post('/actions/:id', async (req, res) => {
+    const actionId = req.params.id
+    const action = ActionService.get(actionId)
+    if (!action) return res.status(404).json({ error: 'Action not found' })
+
+    if (action.access === 'authenticated' && (!req.userId || req.userId === 'anonymous')) {
+      return res.status(401).json({ error: 'Unauthorized' })
+    }
+    if (action.access === 'workspace' && !req.workspaceId) {
+      return res.status(403).json({ error: 'Forbidden' })
+    }
+
+    const actionLog = createLogger(actionId)
+    try {
+      const result = await ActionService.invoke(actionId, {
+        payload: req.body,
+        sdk: req.sdk ?? null,
+        log: actionLog,
+        integrations: IntegrationService,
+        req,
+      })
+      res.json(result ?? { ok: true })
+    } catch (err) {
+      actionLog.error('Action failed', { id: actionId }, err)
+      res.status(500).json({ error: err && err.message ? err.message : 'Internal error' })
+    }
+  })
+
   app.all('*all', async (req, res) => {
     const requestUrl = req.originalUrl || '/'
     try {
@@ -298,19 +344,9 @@ 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'
+export { StorageClient } from './storage/storage.client.js'
+export { S3Client } from './storage/s3.client.js'
+export { LocalStorageClient } from './storage/local-storage.client.js'

package/src/storage/local-storage.client.js

@@ -0,0 +1,65 @@
+import path from 'path'
+import os from 'os'
+import { mkdir, writeFile, readFile, stat } from 'fs/promises'
+import { existsSync } from 'fs'
+
+const LOCAL_STORAGE_DIR = path.join(os.tmpdir(), 'ossy-local-media')
+
+function normalizeKey(keyOrShape) {
+  const Key = typeof keyOrShape === 'string' ? keyOrShape : keyOrShape?.Key
+  if (!Key || typeof Key !== 'string') {
+    throw new Error('[LocalStorageClient] missing Key')
+  }
+  return Key
+}
+
+function keyToLocalPath(key) {
+  const resolved = path.resolve(LOCAL_STORAGE_DIR, key)
+  if (!resolved.startsWith(LOCAL_STORAGE_DIR)) {
+    throw new Error('[LocalStorageClient] invalid key: path traversal detected')
+  }
+  return resolved
+}
+
+function buildUrl(key) {
+  const base = (process.env.LOCAL_API_URL || 'http://localhost:3001').replace(/\/$/, '')
+  return `${base}/local-storage?key=${encodeURIComponent(key)}`
+}
+
+export class LocalStorageClient {
+
+  static createUploadUrl({ Key }) {
+    return Promise.resolve(buildUrl(Key))
+  }
+
+  static createPresignedDownloadUrl(keyOrShape) {
+    const Key = normalizeKey(keyOrShape)
+    return Promise.resolve(buildUrl(Key))
+  }
+
+  static createDownloadUrl(keyOrShape) {
+    const Key = normalizeKey(keyOrShape)
+    return buildUrl(Key)
+  }
+
+  static async save(key, body) {
+    const localPath = keyToLocalPath(key)
+    await mkdir(path.dirname(localPath), { recursive: true })
+    await writeFile(localPath, body)
+  }
+
+  static async load(key) {
+    const localPath = keyToLocalPath(key)
+    if (!existsSync(localPath)) return { buffer: null, exists: false }
+    const buffer = await readFile(localPath)
+    return { buffer, exists: true }
+  }
+
+  static async headObject({ Key }) {
+    const localPath = keyToLocalPath(Key)
+    const s = await stat(localPath).catch(() => null)
+    if (!s) throw Object.assign(new Error('Not Found'), { $metadata: { httpStatusCode: 404 } })
+    return { ContentLength: s.size }
+  }
+
+}

package/src/storage/s3.client.js

@@ -0,0 +1,100 @@
+import { S3, PutObjectCommand, GetObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3'
+import { S3RequestPresigner } from '@aws-sdk/s3-request-presigner'
+import { createRequest } from '@aws-sdk/util-create-request'
+import { formatUrl } from '@aws-sdk/util-format-url'
+import { ConfigService } from '../config.service.js'
+import { createLogger } from '@ossy/observability'
+
+const log = createLogger('storage')
+
+const REGION = 'eu-north-1'
+
+function createS3Client() {
+  return new S3({
+    region: REGION,
+    credentials: {
+      accessKeyId: ConfigService.awsAccessKeyId,
+      secretAccessKey: ConfigService.awsSecretAccessKey
+    }
+  })
+}
+
+function normalizeKey(keyOrShape) {
+  const Key = typeof keyOrShape === 'string' ? keyOrShape : keyOrShape?.Key
+  if (!Key || typeof Key !== 'string') {
+    throw new Error('[S3Client] missing Key')
+  }
+  return Key
+}
+
+export class S3Client {
+
+  /**
+   * Public CDN URL (CloudFront) for objects under `media/` — use only when `access === 'public'`.
+   */
+  static createDownloadUrl(keyOrShape) {
+    const Key = normalizeKey(keyOrShape)
+    const pathAfterMedia = Key.includes('media/') ? Key.split('media/')[1] : Key
+    const base = ConfigService.MediaCdnDomainName || ''
+    return `${base.replace(/\/$/, '')}/${pathAfterMedia}`
+  }
+
+  /**
+   * Short-lived presigned GET for private bucket reads (restricted resources, workspace members).
+   */
+  static createPresignedDownloadUrl(keyOrShape, { expiresIn = 15 * 60 } = {}) {
+    const Key = normalizeKey(keyOrShape)
+    const Bucket = ConfigService.MediaRepository
+    if (!Bucket) {
+      return Promise.reject(new Error('[S3Client] MEDIA_REPOSITORY is not configured'))
+    }
+
+    const s3Client = createS3Client()
+    const signedRequest = new S3RequestPresigner(s3Client.config)
+
+    return createRequest(s3Client, new GetObjectCommand({ Bucket, Key }))
+      .then(request => signedRequest.presign(request, { expiresIn }))
+      .then(formatUrl)
+      .catch(error => {
+        log.error('S3Client.createPresignedDownloadUrl error', undefined, error)
+        return Promise.reject(error)
+      })
+  }
+
+  static createUploadUrl({ ContentType, ContentLength, Key, Bucket, expiresIn = 60 * 60 * 24 }) {
+    log.info('[S3Client][createUploadUrl()] Creating upload URL')
+
+    const bucket = Bucket ?? ConfigService.MediaRepository
+    if (!bucket) {
+      return Promise.reject(new Error('[S3Client] Bucket is not configured'))
+    }
+
+    const clientParams = {
+      Bucket: bucket,
+      Key,
+      ContentType,
+      ContentLength
+    }
+
+    const s3Client = createS3Client()
+    const signedRequest = new S3RequestPresigner(s3Client.config)
+
+    return createRequest(s3Client, new PutObjectCommand(clientParams))
+      .then(request => signedRequest.presign(request, { expiresIn }))
+      .then(formatUrl)
+      .catch(error => {
+        log.error('S3Client.createUploadUrl error', undefined, error)
+        return Promise.reject(error)
+      })
+  }
+
+  static headObject({ Key, Bucket }) {
+    const bucket = Bucket ?? ConfigService.MediaRepository
+    if (!bucket) {
+      return Promise.reject(new Error('[S3Client] Bucket is not configured'))
+    }
+    const s3Client = createS3Client()
+    return s3Client.send(new HeadObjectCommand({ Bucket: bucket, Key }))
+  }
+
+}

package/src/storage/storage.client.js

@@ -0,0 +1,12 @@
+import { S3Client } from './s3.client.js'
+import { LocalStorageClient } from './local-storage.client.js'
+import { ConfigService } from '../config.service.js'
+
+/**
+ * Active storage backend.
+ *
+ * - When `MEDIA_REPOSITORY` is set (production): delegates to S3.
+ * - When `MEDIA_REPOSITORY` is unset (local dev): delegates to LocalStorageClient,
+ *   which stores files in /tmp/ossy-local-media/ and serves them via GET /local-storage.
+ */
+export const StorageClient = ConfigService.MediaRepository ? S3Client : LocalStorageClient

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()
+    }
+  }
+
+}

package/src/email.integration.js

@@ -1,26 +0,0 @@
-import { SESClient } from '@aws-sdk/client-ses'
-
-export const id = 'email'
-
-export const credentials = [
-  'SES_REGION',
-  'SES_ACCESS_KEY_ID',
-  'SES_SECRET_ACCESS_KEY',
-]
-
-/**
- * Returns an AWS SES client configured from env vars.
- * Tasks receive this via `integrations.get('email')`.
- *
- * @param {{ env: NodeJS.ProcessEnv }} opts
- * @returns {SESClient}
- */
-export async function connect ({ env }) {
-  return new SESClient({
-    region: env.SES_REGION,
-    credentials: {
-      accessKeyId: env.SES_ACCESS_KEY_ID,
-      secretAccessKey: env.SES_SECRET_ACCESS_KEY,
-    },
-  })
-}