@open-mercato/core 0.7.1-develop.7178.1.ab93fbaf4e → 0.7.1-develop.7180.1.9717fbbb43

package/src/modules/staff/lib/time-tracking/featureAccess.ts

@@ -0,0 +1,115 @@
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('staff').child({ component: 'time-tracking/featureAccess' })
+
+type RbacServiceLike = {
+  getGrantedFeatures?: (
+    userId: string,
+    scope: { tenantId: string | null; organizationId: string | null },
+  ) => Promise<string[]>
+  userHasAllFeatures?: (
+    userId: string,
+    required: string[],
+    scope: { tenantId: string | null; organizationId: string | null },
+  ) => Promise<boolean>
+}
+
+type ContainerLike = { resolve: (name: string) => unknown }
+
+export type FeatureAccess = {
+  /** The decision. Fail-closed: `false` whenever it could not be established. */
+  allowed: boolean
+  /**
+   * The caller's grants, for the plumbing that genuinely needs a list (mutation
+   * guards, enrichers). Empty when unresolved — check `resolved` before reading
+   * anything into an empty array.
+   */
+  grantedFeatures: string[]
+  /**
+   * `false` when RBAC could not be consulted — the service was unresolvable, it
+   * exposes no way to answer, or the call threw. An unresolved lookup is not the
+   * same as "no permission", and a caller that treats it as one silently
+   * downgrades somebody's access.
+   *
+   * `true` therefore means the answer is definite: RBAC produced the grant list,
+   * or there was no one to ask about (no user). An empty `grantedFeatures` is
+   * only ever a real answer under `resolved`.
+   */
+  resolved: boolean
+}
+
+const DENIED: FeatureAccess = { allowed: false, grantedFeatures: [], resolved: false }
+
+/**
+ * One question, one authority, one failure direction.
+ *
+ * The module previously carried twelve hand-rolled copies of this lookup, each
+ * choosing its own semantics: nine returned `[]` on failure (fail-closed, but
+ * silently — a manager was demoted to their own project memberships and nothing
+ * said why), six returned `null` and were then read as `granted === null || …`
+ * (fail-open — which is how an RBAC outage handed hourly rates to plain report
+ * viewers), and the rest were somewhere in between. The same
+ * `staff.timesheets.rates.view` flag ended up failing closed on two surfaces and
+ * open on three.
+ *
+ * The decision comes from `userHasAllFeatures` rather than from matching the
+ * grant array locally. Both paths agree in a healthy runtime — `getGrantedFeatures`
+ * expands a super-admin's `'*'` into per-module wildcards that `authorizeFeatures`
+ * understands — but only the service call carries `isSuperAdmin` explicitly, and
+ * asking one question in one way is what stops two surfaces disagreeing about the
+ * same person.
+ *
+ * The array is returned alongside it because guards and enrichers legitimately
+ * need a list. It is deliberately *not* the thing to authorize on.
+ *
+ * A failed lookup logs. That is the point: the previous silence meant an RBAC
+ * outage presented to users as missing data and to operators as nothing at all.
+ */
+export async function resolveFeatureAccess(
+  container: ContainerLike,
+  userId: string | null,
+  required: readonly string[],
+  scope: { tenantId: string | null; organizationId: string | null },
+): Promise<FeatureAccess> {
+  if (!userId) return { ...DENIED, resolved: true }
+
+  let rbac: RbacServiceLike | undefined
+  try {
+    rbac = container.resolve('rbacService') as RbacServiceLike | undefined
+  } catch (err) {
+    logger.warn('rbacService could not be resolved; denying', { err, userId, required })
+    return { ...DENIED }
+  }
+  if (!rbac?.userHasAllFeatures) {
+    logger.warn('rbacService cannot answer feature checks; denying', { userId, required })
+    return { ...DENIED }
+  }
+
+  let allowed = false
+  try {
+    allowed = (await rbac.userHasAllFeatures(userId, [...required], scope)) === true
+  } catch (err) {
+    logger.warn('feature check failed; denying', { err, userId, required })
+    return { ...DENIED }
+  }
+
+  // The grant list is a convenience, not the decision, so a failure to read it
+  // downgrades the plumbing that wants a list without touching `allowed`.
+  // A service that cannot produce a list at all is the same kind of failure as
+  // one whose call throws: the empty array is a fallback, not RBAC's answer, and
+  // saying otherwise is how an empty list gets read as authoritative.
+  let grantedFeatures: string[] = []
+  let resolved = false
+  if (!rbac.getGrantedFeatures) {
+    logger.warn('rbacService cannot list grants; feature decision still stands', { userId, required })
+  } else {
+    try {
+      grantedFeatures = (await rbac.getGrantedFeatures(userId, scope)) ?? []
+      resolved = true
+    } catch (err) {
+      logger.warn('grant list could not be read; feature decision still stands', { err, userId })
+    }
+  }
+
+  return { allowed, grantedFeatures, resolved }
+}

package/src/modules/staff/lib/time-tracking/interval.ts

@@ -0,0 +1,90 @@
+export const MINUTES_PER_DAY = 1440
+
+export type IntervalInput = {
+  start?: string | null
+  end?: string | null
+  durationMinutes?: number | null
+}
+
+export type ComputedIntervalField = 'start' | 'end' | 'duration' | null
+
+export type DerivedInterval = {
+  start: string | null
+  end: string | null
+  durationMinutes: number | null
+  computed: ComputedIntervalField
+  crossesMidnight: boolean
+}
+
+const CLOCK_PATTERN = /^(\d{1,2}):(\d{2})$/
+
+export function parseClock(value: string | null | undefined): number | null {
+  if (typeof value !== 'string') return null
+  const match = CLOCK_PATTERN.exec(value.trim())
+  if (!match) return null
+  const hours = Number.parseInt(match[1], 10)
+  const minutes = Number.parseInt(match[2], 10)
+  if (hours > 23 || minutes > 59) return null
+  return hours * 60 + minutes
+}
+
+export function formatClock(minutesOfDay: number): string {
+  const normalized = ((Math.round(minutesOfDay) % MINUTES_PER_DAY) + MINUTES_PER_DAY) % MINUTES_PER_DAY
+  const hours = Math.floor(normalized / 60)
+  const minutes = normalized % 60
+  return `${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}`
+}
+
+function normalizeDuration(value: number | null | undefined): number | null {
+  if (value === null || value === undefined) return null
+  if (!Number.isFinite(value) || value < 0) return null
+  return Math.round(value)
+}
+
+export function deriveInterval(input: IntervalInput): DerivedInterval {
+  const start = parseClock(input.start)
+  const end = parseClock(input.end)
+  const duration = normalizeDuration(input.durationMinutes)
+
+  if (start !== null && end !== null) {
+    const crossesMidnight = end < start
+    const computedDuration = crossesMidnight ? MINUTES_PER_DAY - start + end : end - start
+    return {
+      start: formatClock(start),
+      end: formatClock(end),
+      durationMinutes: computedDuration,
+      computed: duration === computedDuration ? null : 'duration',
+      crossesMidnight,
+    }
+  }
+
+  if (start !== null && duration !== null) {
+    const absoluteEnd = start + duration
+    return {
+      start: formatClock(start),
+      end: formatClock(absoluteEnd),
+      durationMinutes: duration,
+      computed: 'end',
+      crossesMidnight: absoluteEnd >= MINUTES_PER_DAY,
+    }
+  }
+
+  if (end !== null && duration !== null) {
+    const absoluteStart = end - duration
+    return {
+      start: formatClock(absoluteStart),
+      end: formatClock(end),
+      durationMinutes: duration,
+      computed: 'start',
+      crossesMidnight: absoluteStart < 0,
+    }
+  }
+
+  return {
+    start: start === null ? null : formatClock(start),
+    end: end === null ? null : formatClock(end),
+    durationMinutes: duration,
+    computed: null,
+    crossesMidnight: false,
+  }
+}

package/src/modules/staff/lib/time-tracking/migrateProjectCodes.ts

@@ -0,0 +1,161 @@
+/**
+ * Rewrites existing project codes to the short form and re-derives every task
+ * reference to match.
+ *
+ * `staff_time_tasks.reference` is denormalised (`<project code>-<sequence>`) and
+ * frozen at creation, because it is quoted where the task row is no longer
+ * joined. That freeze is what makes this a migration rather than a settings
+ * change: shortening a project's code does not retro-number its tasks, so
+ * without this the tenant ends up with `EHK` projects whose tasks still say
+ * `ERGO-HESTIA-KORPO-4`.
+ *
+ * What this deliberately preserves:
+ *
+ *  * **Sequence numbers.** `APOLLO-14` becomes `APO-14`, never `APO-1`. The
+ *    number is the task's identity to the people who use it; only the prefix
+ *    changes.
+ *  * **Hand-picked codes.** A code that is already at or under the target length
+ *    was chosen, not derived, so it is left exactly as it is.
+ *
+ * What it cannot preserve: a reference somebody wrote down outside the system.
+ * Reports do not quote task references — report lines are labelled by task title
+ * and `staff_time_report_entries` freezes minutes and money, never the reference
+ * — so nothing already exported changes meaning. Anything a person memorised
+ * does.
+ */
+
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { StaffTimeProject, StaffTimeTask } from '../../data/entities'
+import { PROJECT_CODE_TARGET_LENGTH, deriveProjectCodeBase } from './projectCode'
+import { formatTaskReference } from '../timesheets-tasks/taskReference'
+
+export type MigrateProjectCodesScope = { tenantId: string; organizationId: string }
+
+export type ProjectCodeChange = {
+  projectId: string
+  projectName: string
+  fromCode: string
+  toCode: string
+  taskCount: number
+}
+
+export type MigrateProjectCodesResult = {
+  changes: ProjectCodeChange[]
+  /** Projects left alone because their code was already short. */
+  skipped: number
+  tasksRenumbered: number
+}
+
+/**
+ * Plans the rename without writing anything. Exported so the CLI can offer a dry
+ * run: a rewrite of every code in a tenant is not something to discover the
+ * shape of by executing it.
+ */
+export function planProjectCodeMigration(
+  projects: readonly Pick<StaffTimeProject, 'id' | 'name' | 'code'>[],
+  taskCountByProjectId: ReadonlyMap<string, number>,
+): { changes: ProjectCodeChange[]; skipped: number } {
+  // Codes that survive untouched are reserved first, so a project keeping `HBH`
+  // cannot have it taken from under it by a project being shortened to `HBH`.
+  const taken = new Set<string>()
+  const shortening: typeof projects[number][] = []
+  let skipped = 0
+
+  for (const project of projects) {
+    const code = (project.code ?? '').trim()
+    if (code.length > 0 && code.length <= PROJECT_CODE_TARGET_LENGTH) {
+      taken.add(code.toUpperCase())
+      skipped += 1
+      continue
+    }
+    shortening.push(project)
+  }
+
+  // Oldest first, so a re-run is stable and the same project keeps the same code
+  // rather than the order of a query deciding who gets the unsuffixed one.
+  const ordered = [...shortening].sort((left, right) => left.id.localeCompare(right.id))
+
+  const changes: ProjectCodeChange[] = []
+  for (const project of ordered) {
+    const base = deriveProjectCodeBase(project.name ?? '')
+    let candidate = base
+    for (let counter = 2; taken.has(candidate.toUpperCase()); counter += 1) {
+      candidate = `${base}${counter}`
+    }
+    taken.add(candidate.toUpperCase())
+    changes.push({
+      projectId: project.id,
+      projectName: project.name ?? '',
+      fromCode: project.code ?? '',
+      toCode: candidate,
+      taskCount: taskCountByProjectId.get(project.id) ?? 0,
+    })
+  }
+
+  return { changes, skipped }
+}
+
+export async function migrateProjectCodes(
+  em: EntityManager,
+  scope: MigrateProjectCodesScope,
+  options: { dryRun?: boolean } = {},
+): Promise<MigrateProjectCodesResult> {
+  const projects = await em.find(StaffTimeProject, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    deletedAt: null,
+  })
+
+  const tasks = await em.find(StaffTimeTask, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    deletedAt: null,
+  })
+
+  const tasksByProjectId = new Map<string, StaffTimeTask[]>()
+  for (const task of tasks) {
+    const bucket = tasksByProjectId.get(task.timeProjectId) ?? []
+    bucket.push(task)
+    tasksByProjectId.set(task.timeProjectId, bucket)
+  }
+  const counts = new Map([...tasksByProjectId].map(([id, list]) => [id, list.length]))
+
+  const { changes, skipped } = planProjectCodeMigration(projects, counts)
+  if (options.dryRun) {
+    return {
+      changes,
+      skipped,
+      tasksRenumbered: changes.reduce((total, change) => total + change.taskCount, 0),
+    }
+  }
+
+  const projectById = new Map(projects.map((project) => [project.id, project]))
+  const now = new Date()
+  let tasksRenumbered = 0
+
+  // One transaction: a half-applied rename leaves tasks quoting a prefix their
+  // project no longer carries, which is the exact inconsistency this exists to
+  // remove.
+  await em.transactional(async (tem) => {
+    for (const change of changes) {
+      const project = projectById.get(change.projectId)
+      if (!project) continue
+      const managed = tem.getReference(StaffTimeProject, project.id)
+      managed.code = change.toCode
+      managed.updatedAt = now
+      tem.persist(managed)
+
+      for (const task of tasksByProjectId.get(change.projectId) ?? []) {
+        const managedTask = tem.getReference(StaffTimeTask, task.id)
+        // The sequence number is the task's identity to the people who use it;
+        // only the prefix moves.
+        managedTask.reference = formatTaskReference(change.toCode, task.sequenceNumber)
+        managedTask.updatedAt = now
+        tem.persist(managedTask)
+        tasksRenumbered += 1
+      }
+    }
+  })
+
+  return { changes, skipped, tasksRenumbered }
+}

package/src/modules/staff/lib/time-tracking/moneyVisibility.ts

@@ -0,0 +1,37 @@
+import { resolveFeatureAccess } from './featureAccess'
+
+export const RATES_FEATURE = 'staff.timesheets.rates.view'
+
+type ContainerLike = { resolve: (name: string) => unknown }
+
+/**
+ * Whether the caller may see rates, costs and amounts.
+ *
+ * One decision, made once, in one direction — because the same feature was
+ * previously answered by five hand-rolled gates with two opposite failure
+ * defaults. Three report surfaces (preview, export, sheet) read
+ * `grantedFeatures === null || authorizeFeatures(...)`, so an unreadable grant
+ * set *opened* the money fields; `my-work` and the entries list returned `false`
+ * in the same situation. None of the three report routes declares
+ * `staff.timesheets.rates.view` in its metadata — they require only
+ * `reports.view` — so nothing else stood between a plain report viewer and the
+ * customer's hourly rate when RBAC was unavailable.
+ *
+ * Failing closed is the only defensible default here: hiding a rate from someone
+ * entitled to it is a support ticket, showing it to someone who is not is a
+ * disclosure.
+ *
+ * The lookup itself belongs to `resolveFeatureAccess`, the module's single RBAC
+ * authority: it asks `userHasAllFeatures` (the call that carries `isSuperAdmin`
+ * internally), denies on every failure path, and logs the failure rather than
+ * swallowing it. This function stays as the *name* of the question, so a route
+ * reads `canSeeMoney` instead of a bare feature string — but it re-derives
+ * nothing and cannot drift from the rest of the module.
+ */
+export async function resolveMoneyVisibility(
+  container: ContainerLike,
+  userId: string | null,
+  scope: { tenantId: string | null; organizationId: string | null },
+): Promise<boolean> {
+  return (await resolveFeatureAccess(container, userId, [RATES_FEATURE], scope)).allowed
+}

package/src/modules/staff/lib/time-tracking/overlap.ts

@@ -0,0 +1,159 @@
+/**
+ * EP-38 — the overlap policy provider.
+ *
+ * `findOverlaps` is unchanged: it still answers the arithmetic question "which
+ * of these spans intersect the candidate". What is new is the policy layer on
+ * top of it, which answers the product question "and what should happen".
+ *
+ * The built-in `staff.time_tracking.overlap.warn_when_enabled` reproduces
+ * today's behaviour exactly, including the setting's off state: overlapping time
+ * is legitimate in consulting work, so the answer is `warn` when the
+ * `warnings.overlap` tenant setting is on and at least one span intersects, and
+ * `allow` otherwise. It never returns `block`.
+ *
+ * Contributed policies can only ESCALATE — the combined answer is the most
+ * severe of every policy's, `block` > `warn` > `allow` — so a payroll-compliance
+ * module can harden the rule but nothing can silently suppress a warning the
+ * tenant asked for.
+ */
+
+import { MINUTES_PER_DAY, deriveInterval, parseClock } from './interval'
+import { extensionPoints } from '@open-mercato/core/modules/staff/extension-points'
+import { createStrategyRegistry, BUILT_IN_STRATEGY_PRIORITY } from './registries/registry'
+import { tryStrategy } from './registries/invoke'
+import { hasResolverScope, type ScopedResolverContext } from './registries/scope'
+
+export type OverlapSpan = {
+  id?: string | null
+  date: string
+  start?: string | null
+  end?: string | null
+  durationMinutes?: number | null
+}
+
+export type Overlap = {
+  id: string | null
+  entry: OverlapSpan
+  overlapMinutes: number
+}
+
+export type FindOverlapsOptions = {
+  excludeId?: string
+}
+
+const DATE_ONLY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/
+
+const MS_PER_DAY = 86400000
+
+function toEpochDay(date: string | null | undefined): number | null {
+  if (typeof date !== 'string') return null
+  const match = DATE_ONLY_PATTERN.exec(date.trim())
+  if (!match) return null
+  const utc = Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]))
+  if (!Number.isFinite(utc)) return null
+  return Math.round(utc / MS_PER_DAY)
+}
+
+function toAbsoluteSpan(span: OverlapSpan): { start: number; end: number } | null {
+  const epochDay = toEpochDay(span?.date)
+  if (epochDay === null) return null
+  const derived = deriveInterval({
+    start: span.start,
+    end: span.end,
+    durationMinutes: span.durationMinutes,
+  })
+  const startOfDay = parseClock(derived.start)
+  if (startOfDay === null) return null
+  const duration = derived.durationMinutes
+  if (duration === null || duration <= 0) return null
+  const start = epochDay * MINUTES_PER_DAY + startOfDay
+  return { start, end: start + duration }
+}
+
+export function findOverlaps(
+  candidate: OverlapSpan,
+  existing: readonly OverlapSpan[],
+  opts?: FindOverlapsOptions,
+): Overlap[] {
+  const candidateSpan = toAbsoluteSpan(candidate)
+  if (!candidateSpan) return []
+
+  const excludeId = opts?.excludeId
+  const overlaps: Overlap[] = []
+
+  for (const other of existing ?? []) {
+    if (!other) continue
+    if (excludeId !== undefined && other.id === excludeId) continue
+    const otherSpan = toAbsoluteSpan(other)
+    if (!otherSpan) continue
+    if (candidateSpan.start >= otherSpan.end || otherSpan.start >= candidateSpan.end) continue
+    overlaps.push({
+      id: other.id ?? null,
+      entry: other,
+      overlapMinutes:
+        Math.min(candidateSpan.end, otherSpan.end) - Math.max(candidateSpan.start, otherSpan.start),
+    })
+  }
+
+  return overlaps
+}
+
+export type OverlapDecision = 'allow' | 'warn' | 'block'
+
+export type OverlapPolicyContext = ScopedResolverContext & {
+  candidate: OverlapSpan
+  /** The tenant's `warnings.overlap` setting; the built-in reads only this. */
+  warningsEnabled: boolean
+  staffMemberId?: string | null
+  timeProjectId?: string | null
+  excludeId?: string | null
+}
+
+export type OverlapPolicy = {
+  id: string
+  priority?: number
+  evaluate(spans: readonly Overlap[], ctx: OverlapPolicyContext): OverlapDecision
+}
+
+export const OVERLAP_POLICY_REGISTRY_ID = extensionPoints.hosts.overlapPolicyRegistry.spotId
+
+export const BUILT_IN_OVERLAP_POLICY_ID = 'staff.time_tracking.overlap.warn_when_enabled'
+
+const overlapRegistry = createStrategyRegistry<OverlapPolicy>(OVERLAP_POLICY_REGISTRY_ID)
+
+export function registerOverlapPolicy(policy: OverlapPolicy): () => void {
+  return overlapRegistry.register(policy)
+}
+
+export function listOverlapPolicies(): OverlapPolicy[] {
+  return overlapRegistry.list()
+}
+
+export function getOverlapPolicy(id: string | null | undefined): OverlapPolicy | null {
+  return overlapRegistry.get(id)
+}
+
+overlapRegistry.registerBuiltIn({
+  id: BUILT_IN_OVERLAP_POLICY_ID,
+  priority: BUILT_IN_STRATEGY_PRIORITY,
+  evaluate: (spans, ctx) => (ctx.warningsEnabled && spans.length > 0 ? 'warn' : 'allow'),
+})
+
+const DECISION_SEVERITY: Record<OverlapDecision, number> = { allow: 0, warn: 1, block: 2 }
+
+export function evaluateOverlapPolicies(
+  spans: readonly Overlap[],
+  ctx: OverlapPolicyContext,
+): OverlapDecision {
+  const scoped = hasResolverScope(ctx)
+  let decision: OverlapDecision = 'allow'
+  for (const policy of overlapRegistry.list()) {
+    if (!scoped && policy.id !== BUILT_IN_OVERLAP_POLICY_ID) continue
+    // A policy can only ESCALATE, so a thrower is skipped: it cannot express a
+    // warning, and letting it abort the evaluation would suppress the warnings the
+    // remaining policies — including the built-in — do express.
+    const answer = tryStrategy(OVERLAP_POLICY_REGISTRY_ID, policy.id, () => policy.evaluate(spans, ctx))
+    if (answer && DECISION_SEVERITY[answer] > DECISION_SEVERITY[decision]) decision = answer
+  }
+  return decision
+}

package/src/modules/staff/lib/time-tracking/portalRecipients.ts

@@ -0,0 +1,76 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('staff').child({ component: 'time-tracking/portal-recipients' })
+
+/**
+ * EP-50. The customer-user side of the portal contract, expressed as table and
+ * column **names** rather than imports.
+ *
+ * Staff is slated for extraction into `@open-mercato/staff`, so it may not take a
+ * static dependency on `customer_accounts`; `requires` in `index.ts` stays
+ * `['planner', 'resources']`. A Kysely query against the string
+ * `'customer_users'` reads the mapping without an import edge, exactly the way
+ * `warranty_claims/commands/claims.ts` does — and if the table is absent because
+ * the module is not installed, the query throws and this returns an empty list,
+ * which every caller treats as "no portal audience".
+ *
+ * `customer_users.customer_entity_id` is the FK into `customers:customer_entity`,
+ * which is the same id `staff_time_reports.customer_id` holds (EP-44 declares that
+ * link). That equality is the whole ownership model: a portal user reaches a
+ * report when, and only when, their own `customer_entity_id` matches the report's
+ * `customer_id` inside the same tenant and organization.
+ */
+
+type CustomerUsersDb = {
+  customer_users: {
+    id: string
+    tenant_id: string | null
+    organization_id: string | null
+    customer_entity_id: string | null
+    is_active: boolean
+    deleted_at: Date | null
+  }
+}
+
+export type PortalRecipientScope = {
+  tenantId: string
+  organizationId: string
+  customerId: string
+}
+
+/** A broadcast fan-out, not a mailing list — a customer with more portal users than this gets a truncated audience rather than an unbounded query. */
+export const MAX_PORTAL_RECIPIENTS = 100
+
+function isNonEmpty(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+export async function resolvePortalRecipientUserIds(
+  em: EntityManager,
+  scope: PortalRecipientScope,
+): Promise<string[]> {
+  if (!isNonEmpty(scope.tenantId) || !isNonEmpty(scope.organizationId) || !isNonEmpty(scope.customerId)) {
+    return []
+  }
+  try {
+    const db = em.getKysely<CustomerUsersDb>()
+    const rows = await db
+      .selectFrom('customer_users')
+      .select('id')
+      .where('tenant_id', '=', scope.tenantId)
+      .where('organization_id', '=', scope.organizationId)
+      .where('customer_entity_id', '=', scope.customerId)
+      .where('is_active', '=', true)
+      .where('deleted_at', 'is', null)
+      .limit(MAX_PORTAL_RECIPIENTS)
+      .execute()
+    return rows.map((row) => row.id).filter(isNonEmpty)
+  } catch (err) {
+    logger.warn('Could not resolve portal recipients for a time-tracking customer', {
+      customerId: scope.customerId,
+      err,
+    })
+    return []
+  }
+}

package/src/modules/staff/lib/time-tracking/portalReports.ts

@@ -0,0 +1,31 @@
+/**
+ * EP-50. The customer-portal contract for time reports, in one place so the list
+ * route, the detail route and the tests cannot drift from each other.
+ *
+ * `portal.*` is the customer RBAC namespace (`CustomerRbacService`), disjoint from
+ * the staff `staff.timesheets.*` namespace. It is granted through
+ * `setup.defaultCustomerRoleFeatures`, not `acl.ts` — `acl.ts` declares staff
+ * features only.
+ */
+
+export const PORTAL_TIME_REPORTS_VIEW_FEATURE = 'portal.time_reports.view'
+
+/**
+ * The four predicates every portal read of `staff_time_reports` must carry, as a
+ * SQL fragment with its parameters in order. Written once because a portal report
+ * read that forgets one of them is a cross-customer disclosure, and three call
+ * sites re-typing the same WHERE clause is how one of them eventually forgets.
+ */
+export function portalOwnedReportClause(scope: {
+  tenantId: string
+  organizationId: string
+  customerId: string
+}): { sql: string; params: string[] } {
+  return {
+    sql: `tenant_id = ? AND organization_id = ? AND customer_id = ? AND status = 'closed' AND deleted_at IS NULL`,
+    params: [scope.tenantId, scope.organizationId, scope.customerId],
+  }
+}
+
+export const PORTAL_TIME_REPORT_BEFORE_SPOT_ID = 'portal:staff.time_report:before'
+export const PORTAL_TIME_REPORT_AFTER_SPOT_ID = 'portal:staff.time_report:after'