@meith/authorization 0.16.0

package/src/fixture.ts

@@ -0,0 +1,226 @@
+import { emptyPermissionSet, type PermissionSet } from '@meith/core'
+
+import { combinePermissionSets } from './combine'
+import type {
+  Actor,
+  AuthorizationSource,
+  ForumOverride,
+  GroupDefaults,
+  ModeratorAppointment,
+} from './types'
+
+export function makePermissionSet(overrides: Partial<PermissionSet>): PermissionSet {
+  return { ...emptyPermissionSet(), ...overrides }
+}
+
+export const GROUP = {
+  guest: 1,
+  registered: 2,
+  veterans: 3,
+  superMod: 5,
+  admin: 6,
+} as const
+
+const PARTICIPANT_FORUM_GRANTS: Partial<PermissionSet> = {
+  canView: true,
+  canViewThreads: true,
+  canViewOthersThreads: true,
+  canSearch: true,
+}
+
+const POSTER_FORUM_GRANTS: Partial<PermissionSet> = {
+  ...PARTICIPANT_FORUM_GRANTS,
+  canSubscribe: true,
+  canPostThreads: true,
+  canPostReplies: true,
+  canEditOwnPosts: true,
+  canDeleteOwnPosts: true,
+  canUploadAttachments: true,
+  canDownloadAttachments: true,
+  requiresThreadApproval: false,
+  requiresPostApproval: false,
+  requiresApprovalOnEdit: false,
+}
+
+export const GROUP_DEFAULTS: Record<number, PermissionSet> = {
+  [GROUP.guest]: makePermissionSet({
+    ...PARTICIPANT_FORUM_GRANTS,
+    canViewProfiles: true,
+  }),
+
+  [GROUP.registered]: makePermissionSet({
+    ...POSTER_FORUM_GRANTS,
+    canViewProfiles: true,
+    canViewMemberList: true,
+    canUsePrivateMessages: true,
+    canReportContent: true,
+    editTimeLimitMinutes: 30,
+    maxPostsPerDay: 50,
+  }),
+
+  [GROUP.veterans]: makePermissionSet({
+    canPostPolls: true,
+    canVotePolls: true,
+    maxPostsPerDay: 0,
+  }),
+
+  [GROUP.superMod]: makePermissionSet({
+    ...POSTER_FORUM_GRANTS,
+    canViewProfiles: true,
+    canViewMemberList: true,
+    canUsePrivateMessages: true,
+    canReportContent: true,
+    canAccessModCp: true,
+    isSuperModerator: true,
+  }),
+
+  [GROUP.admin]: makePermissionSet({
+    ...POSTER_FORUM_GRANTS,
+    canViewProfiles: true,
+    canViewMemberList: true,
+    canUsePrivateMessages: true,
+    canAccessModCp: true,
+    canAccessAdminCp: true,
+    isAdministrator: true,
+  }),
+}
+
+export const FORUM = {
+  public: 100,
+  publicSub: 101,
+  private: 200,
+  password: 300,
+} as const
+
+const CHAINS: Record<number, number[]> = {
+  [FORUM.public]: [FORUM.public],
+  [FORUM.publicSub]: [FORUM.publicSub, FORUM.public],
+  [FORUM.private]: [FORUM.private],
+  [FORUM.password]: [FORUM.password],
+}
+
+const OVERRIDES: ForumOverride[] = [
+  ...[GROUP.guest, GROUP.registered, GROUP.veterans].map((groupId) => ({
+    forumId: FORUM.private,
+    groupId,
+    overrides: {
+      canView: false,
+      canViewThreads: false,
+      canSearch: false,
+      canPostThreads: false,
+      canPostReplies: false,
+    },
+  })),
+
+  {
+    forumId: FORUM.publicSub,
+    groupId: GROUP.registered,
+    overrides: { canPostThreads: false, canPostReplies: false },
+  },
+  {
+    forumId: FORUM.publicSub,
+    groupId: GROUP.veterans,
+    overrides: { canPostThreads: false, canPostReplies: false },
+  },
+]
+
+export class MemoryAuthorizationSource implements AuthorizationSource {
+  async groupDefaults(groupIds: readonly number[]): Promise<GroupDefaults[]> {
+    return groupIds
+      .filter((id) => id in GROUP_DEFAULTS)
+      .map((groupId) => ({ groupId, permissions: GROUP_DEFAULTS[groupId]! }))
+  }
+
+  async ancestorChain(forumId: number): Promise<number[]> {
+    return CHAINS[forumId] ?? []
+  }
+
+  async forumOverrides(
+    forumIds: readonly number[],
+    groupIds: readonly number[],
+  ): Promise<ForumOverride[]> {
+    const fset = new Set(forumIds)
+    const gset = new Set(groupIds)
+    return OVERRIDES.filter((o) => fset.has(o.forumId) && gset.has(o.groupId))
+  }
+
+  async allForumIds(): Promise<number[]> {
+    return [FORUM.public, FORUM.publicSub, FORUM.private, FORUM.password]
+  }
+
+  async allAncestorChains(): Promise<ReadonlyMap<number, readonly number[]>> {
+    const ids = await this.allForumIds()
+    return new Map(ids.map((id) => [id, CHAINS[id] ?? []]))
+  }
+
+  async moderatorAppointments(userId: number | null): Promise<readonly ModeratorAppointment[]> {
+    if (userId !== ACTORS.forumModerator.userId) return []
+    return [
+      {
+        forumId: FORUM.public,
+        cascadeToSubforums: true,
+        canApproveContent: true,
+        canEditPosts: true,
+        canSoftDeletePosts: true,
+        canRestorePosts: true,
+        canOpenCloseThreads: true,
+        canStickThreads: true,
+        canMoveThreads: true,
+        canMergeThreads: true,
+        canSplitThreads: true,
+      },
+    ]
+  }
+}
+
+function actor(
+  partial: Pick<Actor, 'userId' | 'groupIds' | 'state'> & Partial<Pick<Actor, 'primaryGroupId'>>,
+): Actor {
+  return {
+    userId: partial.userId,
+    groupIds: partial.groupIds,
+    primaryGroupId: partial.primaryGroupId ?? partial.groupIds[0] ?? null,
+    state: partial.state,
+    global: combineForActor(partial.groupIds),
+    permissionVersion: 1,
+  }
+}
+
+function combineForActor(groupIds: readonly number[]): PermissionSet {
+  const sets = groupIds.filter((id) => id in GROUP_DEFAULTS).map((id) => GROUP_DEFAULTS[id]!)
+  return combinePermissionSets(sets)
+}
+
+export const ACTORS = {
+  guest: actor({ userId: null, groupIds: [GROUP.guest], state: 'guest' }),
+  registered: actor({ userId: 10, groupIds: [GROUP.registered], state: 'active' }),
+  secondary: actor({
+    userId: 11,
+    groupIds: [GROUP.registered, GROUP.veterans],
+    state: 'active',
+  }),
+  forumModerator: actor({
+    userId: 12,
+    groupIds: [GROUP.registered],
+    state: 'active',
+  }),
+  superModerator: actor({
+    userId: 13,
+    groupIds: [GROUP.registered, GROUP.superMod],
+    state: 'active',
+  }),
+  administrator: actor({
+    userId: 14,
+    groupIds: [GROUP.registered, GROUP.admin],
+    state: 'active',
+  }),
+  banned: actor({ userId: 15, groupIds: [GROUP.registered], state: 'banned' }),
+  awaiting: actor({
+    userId: 16,
+    groupIds: [GROUP.registered],
+    state: 'awaiting_activation',
+  }),
+} as const
+
+export type ActorName = keyof typeof ACTORS
+export type ForumName = keyof typeof FORUM

package/src/index.ts

@@ -0,0 +1,38 @@
+export { type ContentScope, PUBLIC_CONTENT } from '@meith/core'
+
+export type { AuthorizerOptions, BypassEvent } from './authorizer'
+export { Authorizer } from './authorizer'
+export { combineGroupValue, combinePermissionSets } from './combine'
+export {
+  buildPermissionMatrix,
+  type CopyChange,
+  type CopyPlan,
+  type MatrixCell,
+  type MatrixInput,
+  type MatrixRow,
+  planCopyToDescendants,
+  readMatrixCell,
+} from './matrix-editor'
+export type { MemoryAppointment, MemoryBoard } from './memory-source'
+export { InMemoryAuthorizationSource } from './memory-source'
+export { forumSubset, indexOverrides, resolveForumMatrix } from './resolve'
+export type {
+  Action,
+  Actor,
+  ActorSource,
+  ActorState,
+  AuthorizationSource,
+  ContentVisibility,
+  ForumOverride,
+  GroupDefaults,
+  ModeratedTarget,
+  NumericGlobalPermission,
+  Target,
+  Visible,
+} from './types'
+export {
+  hasAnyModeratorRight,
+  type ModeratorAppointment,
+  type ModeratorRights,
+  NO_MODERATOR_RIGHTS,
+} from './types'

package/src/matrix-editor.ts

@@ -0,0 +1,145 @@
+import { FORUM_PERMISSION_FIELDS, type ForumPermissions, type PermissionField } from '@meith/core'
+
+import { resolveForumMatrix } from './resolve'
+import type { ForumOverride, GroupDefaults } from './types'
+
+export interface MatrixCell {
+  readonly key: string
+  readonly description: string
+  readonly kind: PermissionField['kind']
+  readonly stored: boolean | number | null
+  readonly control: string
+  readonly effective: boolean | number
+  readonly inheritedFrom: number | null
+}
+
+export interface MatrixRow {
+  readonly groupId: number
+  readonly groupTitle: string
+  readonly cells: readonly MatrixCell[]
+}
+
+export interface MatrixInput {
+  readonly chain: readonly number[]
+  readonly groups: readonly (GroupDefaults & { readonly title: string })[]
+  readonly overrides: readonly ForumOverride[]
+}
+
+function index(overrides: readonly ForumOverride[]): Map<string, ForumOverride> {
+  const map = new Map<string, ForumOverride>()
+  for (const override of overrides) map.set(`${override.forumId}:${override.groupId}`, override)
+  return map
+}
+
+function sourceOf(
+  chain: readonly number[],
+  groupId: number,
+  key: string,
+  byForumGroup: ReadonlyMap<string, ForumOverride>,
+): number | null {
+  for (const forumId of chain) {
+    const value = byForumGroup.get(`${forumId}:${groupId}`)?.overrides[
+      key as keyof ForumPermissions
+    ]
+    if (value !== undefined && value !== null) return forumId
+  }
+  return null
+}
+
+export function buildPermissionMatrix(input: MatrixInput): readonly MatrixRow[] {
+  const byForumGroup = index(input.overrides)
+  const forumId = input.chain[0]
+
+  return input.groups.map((group) => {
+    const resolved = resolveForumMatrix(input.chain, [group], byForumGroup)
+    const own = forumId === undefined ? undefined : byForumGroup.get(`${forumId}:${group.groupId}`)
+
+    return {
+      groupId: group.groupId,
+      groupTitle: group.title,
+      cells: FORUM_PERMISSION_FIELDS.map((field) => {
+        const stored = own?.overrides[field.key as keyof ForumPermissions]
+        const source = sourceOf(input.chain, group.groupId, field.key, byForumGroup)
+        const storedOrNull = stored === undefined ? null : stored
+
+        return {
+          key: field.key,
+          description: field.description,
+          kind: field.kind,
+          stored: storedOrNull,
+          control: matrixCellValue({ kind: field.kind, stored: storedOrNull }),
+          effective: resolved[field.key as keyof ForumPermissions] as boolean | number,
+          inheritedFrom: source === null || source === forumId ? null : source,
+        }
+      }),
+    }
+  })
+}
+
+export interface CopyChange {
+  readonly forumId: number
+  readonly groupId: number
+  readonly key: string
+  readonly from: boolean | number | null
+  readonly to: boolean | number | null
+}
+
+export interface CopyPlan {
+  readonly changes: readonly CopyChange[]
+  readonly unchanged: readonly number[]
+}
+
+export function planCopyToDescendants(input: {
+  readonly sourceForumId: number
+  readonly descendantIds: readonly number[]
+  readonly groupIds: readonly number[]
+  readonly overrides: readonly ForumOverride[]
+}): CopyPlan {
+  const byForumGroup = index(input.overrides)
+  const changes: CopyChange[] = []
+  const touched = new Set<number>()
+
+  for (const forumId of input.descendantIds) {
+    for (const groupId of input.groupIds) {
+      const source = byForumGroup.get(`${input.sourceForumId}:${groupId}`)?.overrides ?? {}
+      const target = byForumGroup.get(`${forumId}:${groupId}`)?.overrides ?? {}
+
+      for (const field of FORUM_PERMISSION_FIELDS) {
+        const key = field.key as keyof ForumPermissions
+        const from = (target[key] ?? null) as boolean | number | null
+        const to = (source[key] ?? null) as boolean | number | null
+
+        if (Object.is(from, to)) continue
+        changes.push({ forumId, groupId, key: field.key, from, to })
+        touched.add(forumId)
+      }
+    }
+  }
+
+  return {
+    changes,
+    unchanged: input.descendantIds.filter((id) => !touched.has(id)),
+  }
+}
+
+export function readMatrixCell(
+  field: PermissionField,
+  raw: string | undefined,
+): boolean | number | null {
+  if (raw === undefined || raw === '' || raw === 'inherit') return null
+
+  if (field.kind === 'boolean' || field.kind === 'negative') {
+    if (raw === '1' || raw === 'grant') return true
+    if (raw === '0' || raw === 'deny') return false
+    return null
+  }
+
+  const value = Number(raw)
+  return Number.isSafeInteger(value) && value >= 0 ? value : null
+}
+
+export function matrixCellValue(cell: Pick<MatrixCell, 'kind' | 'stored'>): string {
+  if (cell.stored === null) return cell.kind === 'numeric' ? '' : 'inherit'
+  if (cell.kind === 'numeric') return String(cell.stored)
+  return cell.stored === true ? 'grant' : 'deny'
+}

package/src/matrix.fixture.ts

@@ -0,0 +1,131 @@
+export const PERMISSION_ACTIONS = [
+  'view',
+  'postThread',
+  'postReply',
+  'editOwn',
+  'editOthers',
+  'deleteOwn',
+  'softDelete',
+  'viewUnapproved',
+  'viewDeleted',
+  'approve',
+  'lock',
+  'stick',
+  'move',
+  'deleteThread',
+  'merge',
+  'split',
+  'upload',
+  'download',
+  'search',
+  'subscribe',
+] as const
+
+export type PermissionAction = (typeof PERMISSION_ACTIONS)[number]
+
+const ALL: readonly PermissionAction[] = PERMISSION_ACTIONS
+
+const MEMBER_PUBLIC: readonly PermissionAction[] = [
+  'view',
+  'postThread',
+  'postReply',
+  'editOwn',
+  'deleteOwn',
+  'upload',
+  'download',
+  'search',
+  'subscribe',
+]
+
+const MEMBER_READONLY: readonly PermissionAction[] = [
+  'view',
+  'editOwn',
+  'deleteOwn',
+  'upload',
+  'download',
+  'search',
+  'subscribe',
+]
+
+const MOD_PUBLIC: readonly PermissionAction[] = ALL
+
+const MOD_READONLY: readonly PermissionAction[] = [
+  'view',
+  'editOwn',
+  'editOthers',
+  'deleteOwn',
+  'softDelete',
+  'viewUnapproved',
+  'viewDeleted',
+  'approve',
+  'lock',
+  'stick',
+  'move',
+  'deleteThread',
+  'merge',
+  'split',
+  'upload',
+  'download',
+  'search',
+  'subscribe',
+]
+
+export type ExpectedMatrix = Record<string, Record<string, readonly PermissionAction[]>>
+
+export const EXPECTED: ExpectedMatrix = {
+  guest: {
+    public: ['view', 'search'],
+    publicSub: ['view', 'search'],
+    private: [],
+    password: [],
+  },
+
+  registered: {
+    public: MEMBER_PUBLIC,
+    publicSub: MEMBER_READONLY,
+    private: [],
+    password: [],
+  },
+
+  secondary: {
+    public: MEMBER_PUBLIC,
+    publicSub: MEMBER_READONLY,
+    private: [],
+    password: [],
+  },
+
+  forumModerator: {
+    public: MOD_PUBLIC,
+    publicSub: MOD_READONLY,
+    private: [],
+    password: [],
+  },
+
+  superModerator: {
+    public: ALL,
+    publicSub: ALL,
+    private: ALL,
+    password: ALL,
+  },
+
+  administrator: {
+    public: ALL,
+    publicSub: ALL,
+    private: ALL,
+    password: ALL,
+  },
+
+  banned: {
+    public: [],
+    publicSub: [],
+    private: [],
+    password: [],
+  },
+
+  awaiting: {
+    public: ['view', 'search'],
+    publicSub: ['view', 'search'],
+    private: [],
+    password: [],
+  },
+}

package/src/memory-source.ts

@@ -0,0 +1,68 @@
+import type {
+  AuthorizationSource,
+  ForumOverride,
+  GroupDefaults,
+  ModeratorAppointment,
+} from './types'
+
+export interface MemoryBoard {
+  readonly groups: readonly GroupDefaults[]
+  readonly chains: Readonly<Record<number, readonly number[]>>
+  readonly overrides: readonly ForumOverride[]
+  readonly moderators?: readonly MemoryAppointment[]
+}
+
+export type MemoryAppointment = ModeratorAppointment & {
+  readonly userId?: number | null
+  readonly groupId?: number | null
+}
+
+export class InMemoryAuthorizationSource implements AuthorizationSource {
+  private readonly groupsById: Map<number, GroupDefaults>
+
+  constructor(private readonly board: MemoryBoard) {
+    this.groupsById = new Map(board.groups.map((g) => [g.groupId, g]))
+  }
+
+  async groupDefaults(groupIds: readonly number[]): Promise<readonly GroupDefaults[]> {
+    const out: GroupDefaults[] = []
+    for (const id of groupIds) {
+      const g = this.groupsById.get(id)
+      if (g) out.push(g)
+    }
+    return out
+  }
+
+  async ancestorChain(forumId: number): Promise<readonly number[]> {
+    return this.board.chains[forumId] ?? []
+  }
+
+  async forumOverrides(
+    forumIds: readonly number[],
+    groupIds: readonly number[],
+  ): Promise<readonly ForumOverride[]> {
+    const fset = new Set(forumIds)
+    const gset = new Set(groupIds)
+    return this.board.overrides.filter((o) => fset.has(o.forumId) && gset.has(o.groupId))
+  }
+
+  async allForumIds(): Promise<readonly number[]> {
+    return Object.keys(this.board.chains).map((k) => Number(k))
+  }
+
+  async allAncestorChains(): Promise<ReadonlyMap<number, readonly number[]>> {
+    return new Map(Object.entries(this.board.chains).map(([id, chain]) => [Number(id), chain]))
+  }
+
+  async moderatorAppointments(
+    userId: number | null,
+    groupIds: readonly number[],
+  ): Promise<readonly ModeratorAppointment[]> {
+    const groups = new Set(groupIds)
+    return (this.board.moderators ?? []).filter(
+      (row) =>
+        (row.userId != null && row.userId === userId) ||
+        (row.groupId != null && groups.has(row.groupId)),
+    )
+  }
+}

package/src/resolve.ts

@@ -0,0 +1,45 @@
+import { FORUM_PERMISSION_FIELDS, type ForumPermissions, type PermissionSet } from '@meith/core'
+
+import { combineGroupValue } from './combine'
+import type { ForumOverride, GroupDefaults } from './types'
+
+export function resolveForumMatrix(
+  chain: readonly number[],
+  groups: readonly GroupDefaults[],
+  overridesByForumGroup: ReadonlyMap<string, ForumOverride>,
+): ForumPermissions {
+  const out: Record<string, boolean | number> = {}
+
+  for (const field of FORUM_PERMISSION_FIELDS) {
+    const key = field.key
+
+    const perGroup: (boolean | number)[] = groups.map((group) => {
+      for (const forumId of chain) {
+        const override = overridesByForumGroup.get(`${forumId}:${group.groupId}`)
+        const value = override?.overrides[key as keyof ForumPermissions]
+        if (value !== undefined && value !== null) {
+          return value as boolean | number
+        }
+      }
+      return (group.permissions as Record<string, boolean | number>)[key]!
+    })
+
+    out[key] = combineGroupValue(field.kind, perGroup)
+  }
+
+  return out as ForumPermissions
+}
+
+export function indexOverrides(overrides: readonly ForumOverride[]): Map<string, ForumOverride> {
+  const map = new Map<string, ForumOverride>()
+  for (const o of overrides) map.set(`${o.forumId}:${o.groupId}`, o)
+  return map
+}
+
+export function forumSubset(set: PermissionSet): ForumPermissions {
+  const out: Record<string, boolean | number> = {}
+  for (const field of FORUM_PERMISSION_FIELDS) {
+    out[field.key] = (set as Record<string, boolean | number>)[field.key]!
+  }
+  return out as ForumPermissions
+}