@huynle/hub 0.7.4 → 0.8.0

package/src/central/teams/policy.ts

@@ -0,0 +1,231 @@
+// Team communication policy in message delivery (HWA-34; contract docs/plans/2026-10-30-hub-workspaces-artifacts-
+// contracts.md, Teams + HWA-33 clarification; decisions zltiwb4s, 5etngvgm, r3vv4eon, qxzrdc6c).
+//
+// The delivery engine (../agent/delivery.ts) calls this module before it stores anything:
+// - prepare(userID, from, addr) once per send: resolves team addresses and returns admit(), which filters the
+//   resolved recipients through the normative rule `teamDeliveryVerdict` (packages/protocol/src/teams.ts; never
+//   re-derived here) and throws when none is left.
+// - answer(userID, from, original, to, kind) before a reply or decline is stored.
+//
+// Addressing (qxzrdc6c):
+// - `@@role#team` / `@@role.project#team` (parseTeamRoleAddress) name the sessions currently seated in that role of
+//   that active team (paused teams included), filtered by the session's project; never global role holders. The
+//   team becomes the explicit team context: only its policy decides, and a team sender must hold a seat in it
+//   (not_member). An unknown or archived team, or a role nobody holds, is not_found (like any address).
+// - A team-less `@@role[.project]` from a session with active seats: when the role is seated (by another session)
+//   in two or more of the sender's active teams, 409 ambiguous with `candidates: [{team, address}]` (only the
+//   sender's own teams); in exactly one, it resolves to that team's seats (implicit: every shared team counts);
+//   in none, it stays a global role address. Sessions in no team, the user and apps: global, unchanged (r3vv4eon).
+// - The SDK parseAddress never accepts `#`, so no other caller resolves a team address as a global role.
+//
+// Recipients: every candidate of a role (one or sendAll) is checked; send picks among the permitted ones, sendAll
+// reaches only those. When none is permitted the send is denied with the first candidate's reason.
+//
+// Denials: AgentError forbidden, extra `{policy: "policy" | "external" | "not_member"}` and a fixed message that
+// names no team, role or recipient. Before a denial is recorded the sender's message rate limit is charged (the
+// limiter passed in), so repeated denied attempts end in rate_limited and the audit stays bounded. The `denied`
+// hook gets IDs only (sender, recipient, team when known, kind, reason); the hub records it in the agent audit and
+// appends teamDeniedEvent (journal family `manage`) for the Watchtower's denied counts. Nothing is stored,
+// no hop counted, nothing sent.
+//
+// Replies and declines: always allowed when they answer an ask that was delivered to the replier (its recipient is
+// the replying party; Messages.answerable enforces the same on store, so a forged or foreign ID is not_found and
+// reaches nobody). Denied asks are never stored, so they cannot be answered. A reply to a msg is a msg under policy.
+//
+// Revisions and in-flight messages (decided for HWA-34): the policy is read fresh for each send (no cache across
+// sends), so a published revision, a pause/archive or a staffing change applies to the very next message. Messages
+// admitted earlier are not re-checked: an ask stays answerable after its edge, its team or the replier's seat goes
+// away, its re-wake reminders continue, and pending (offline) messages are still delivered on flush.
+//
+// Cost: one deliveryContext read (seats of the sender and all candidates, plus their teams) per send, plus, for
+// role addresses, one byName or one current-seat list per involved team (≤ TEAM_LIMITS.teamsPerUser). Lookups are
+// memoised within the send only.
+import { parseTeamRoleAddress, type TeamSeat, teamDeliveryVerdict, type DeliveryVerdict } from "../../protocol"
+import type { DirectoryEntry, Resolved } from "../agent/directory"
+import { type Party, partyKey } from "../agent/envelope"
+import { AgentError } from "../agent/errors"
+import type { EventInput } from "../agent/events"
+import type { Message } from "../agent/messages"
+import { parseAddress } from "../agent/names"
+import type { DeliveryContext, TeamSeatStore } from "./seats"
+import type { TeamStore } from "./store"
+
+export type TeamDenialReason = "policy" | "external" | "not_member"
+
+/** What the denied hook and the journal get: IDs and enums only. */
+export interface TeamDenial {
+  readonly senderID: string
+  readonly recipientID?: string
+  readonly kind: "msg" | "ask" | "reply" | "decline"
+  readonly reason: TeamDenialReason
+  readonly teamID?: string
+}
+
+/** Recipients named through a team: `explicit` for `#team` (the verdict's team context). */
+export interface TeamResolved extends Resolved {
+  readonly team: { readonly teamID: string; readonly explicit: boolean }
+}
+
+/** The message limiter (MessageLimiter.admit): charged before a denial is recorded. */
+export interface PolicyLimiter {
+  admit(userID: string, from: Party, to: Party): Promise<void>
+}
+
+/** One send under policy (see prepare). */
+export interface TeamSend {
+  /** Set when the address resolved through a team; otherwise the caller resolves it as before. */
+  readonly resolved?: TeamResolved
+  /** The recipients the sender may reach, in order; throws forbidden when none is left. */
+  admit(recipients: readonly DirectoryEntry[], kind: "msg" | "ask", limiter?: PolicyLimiter): Promise<DirectoryEntry[]>
+}
+
+export interface TeamPolicyDeps {
+  readonly teams: Pick<TeamStore, "byName" | "get">
+  readonly seats: Pick<TeamSeatStore, "deliveryContext" | "list">
+  /** Session lookups by ID (Directory.resolve). */
+  readonly directory: { resolve(userID: string, addr: string): Resolved }
+  /** A denial, after it was charged to the limiter: audit it and append teamDeniedEvent. Errors are logged. */
+  readonly denied?: (userID: string, denial: TeamDenial) => void | Promise<void>
+}
+
+/** The compact journal event of a denial (TEAM_EVENT_TYPES `team.denied`): IDs only, never text or role names. */
+export const teamDeniedEvent = (d: TeamDenial): EventInput => ({
+  type: "team.denied",
+  family: "manage",
+  subject: { senderID: d.senderID, ...(d.recipientID !== undefined ? { sessionID: d.recipientID } : {}), ...(d.teamID !== undefined ? { teamID: d.teamID } : {}) },
+  data: { kind: d.kind, reason: d.reason },
+})
+
+const DENIED: Record<TeamDenialReason, { message: string; hint: string }> = {
+  policy: { message: "Your team's communication paths do not allow this message", hint: "Message a role your team lets you reach, or escalate to @me" },
+  external: { message: "Team members can only contact sessions in their teams", hint: "Escalate to @me, or ask the user to allow external contact for your role" },
+  not_member: { message: "You hold no seat in that team", hint: "Address the role without #team, or through a team you are in" },
+}
+
+type Denied = Extract<DeliveryVerdict, { allow: false }>
+
+const sessionParty = (entry: DirectoryEntry): Party => ({ kind: "session", sessionID: entry.sessionID, ...(entry.name ? { name: entry.name } : {}) })
+
+export class TeamPolicy {
+  constructor(private readonly deps: TeamPolicyDeps) {}
+
+  /** Starts a send from `from` to `addr` (see the header). */
+  async prepare(userID: string, from: Party, addr: string): Promise<TeamSend> {
+    const resolved = await this.resolve(userID, from, addr)
+    const teamID = resolved?.team.explicit ? resolved.team.teamID : undefined
+    return {
+      ...(resolved ? { resolved } : {}),
+      admit: async (recipients, kind, limiter) => {
+        if (from.kind !== "session" || recipients.length === 0) return [...recipients]
+        const ctx = await this.context(userID, [from.sessionID, ...recipients.map((r) => r.sessionID)])
+        const allowed: DirectoryEntry[] = []
+        let first: { entry: DirectoryEntry; verdict: Denied } | undefined
+        for (const entry of recipients) {
+          const verdict = this.verdict(ctx, from.sessionID, entry.sessionID, kind, teamID)
+          if (verdict.allow) allowed.push(entry)
+          else first ??= { entry, verdict }
+        }
+        if (allowed.length || !first) return allowed
+        return this.deny(userID, from, sessionParty(first.entry), { senderID: from.sessionID, recipientID: first.entry.sessionID, kind, reason: first.verdict.reason, ...(teamID ? { teamID } : {}) }, limiter)
+      },
+    }
+  }
+
+  /** Checks a reply or decline from `from` (the original's recipient) to `to` (its sender) before it is stored. */
+  async answer(userID: string, from: Party, original: Message, to: Party, kind: "reply" | "decline", limiter?: PolicyLimiter): Promise<void> {
+    if (from.kind !== "session") return
+    // A decline of a msg is invalid (Messages.decline says so); policy does not mask that answer.
+    if (kind === "decline" && original.kind !== "ask") return
+    const replyToPermittedAsk = original.kind === "ask" && partyKey(original.recipient) === partyKey(from)
+    const ids = [from.sessionID, ...(to.kind === "session" ? [to.sessionID] : [])]
+    const base = { kind: "reply" as const, toUser: to.kind === "user", replyToPermittedAsk }
+    // @me and permitted-ask answers need no lookup (the verdict's first rules).
+    let verdict = teamDeliveryVerdict({ ...base, senderSeats: [], recipientSeats: [], teams: new Map() })
+    if (!verdict.allow || (verdict.via !== "user" && verdict.via !== "reply")) {
+      const ctx = await this.context(userID, ids)
+      verdict = teamDeliveryVerdict({ ...base, senderSeats: seatsIn(ctx, from.sessionID), recipientSeats: to.kind === "session" ? seatsIn(ctx, to.sessionID) : [], teams: ctx.teams })
+    }
+    if (verdict.allow) return
+    await this.deny(userID, from, to, { senderID: from.sessionID, ...(to.kind === "session" ? { recipientID: to.sessionID } : {}), kind, reason: verdict.reason }, limiter)
+  }
+
+  // ---------- internals ----------
+
+  private verdict(ctx: DeliveryContext, senderID: string, recipientID: string, kind: "msg" | "ask", teamID: string | undefined): DeliveryVerdict {
+    return teamDeliveryVerdict({
+      kind,
+      toUser: false,
+      replyToPermittedAsk: false,
+      senderSeats: seatsIn(ctx, senderID),
+      recipientSeats: seatsIn(ctx, recipientID),
+      ...(teamID !== undefined ? { teamID } : {}),
+      teams: ctx.teams,
+    })
+  }
+
+  private context(userID: string, sessionIDs: readonly string[]): Promise<DeliveryContext> {
+    return this.deps.seats.deliveryContext(userID, [...new Set(sessionIDs)])
+  }
+
+  /** Charges the limiter, records the denial (IDs only) and throws forbidden. */
+  private async deny(userID: string, from: Party, to: Party, denial: TeamDenial, limiter?: PolicyLimiter): Promise<never> {
+    await limiter?.admit(userID, from, to)
+    try {
+      await this.deps.denied?.(userID, denial)
+    } catch (cause) {
+      console.error(`[hub] team denial record failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+    }
+    const { message, hint } = DENIED[denial.reason]
+    throw new AgentError("forbidden", message, { hint, extra: { policy: denial.reason } })
+  }
+
+  /** Team resolution of `addr` (see the header); undefined: resolve it as a plain address. */
+  private async resolve(userID: string, from: Party, addr: string): Promise<TeamResolved | undefined> {
+    const team = parseTeamRoleAddress(addr)
+    if (team) {
+      const record = await this.deps.teams.byName(userID, team.team)
+      if (!record || record.state !== "active") throw new AgentError("not_found", `No session ${addr}`)
+      const sessions = await this.seated(userID, record.id, team.role, team.project)
+      if (!sessions.length) throw new AgentError("not_found", `No session ${addr}`)
+      return { address: { kind: "role", role: team.role, ...(team.project ? { project: team.project } : {}) }, sessions, team: { teamID: record.id, explicit: true } }
+    }
+    const address = parseAddress(addr)
+    if (address?.kind !== "role" || from.kind !== "session") return undefined
+    const ctx = await this.context(userID, [from.sessionID])
+    const mine = [...new Set(seatsIn(ctx, from.sessionID).filter((s) => ctx.teams.get(s.teamID)?.state === "active").map((s) => s.teamID))]
+    const matches: Array<{ teamID: string; sessions: DirectoryEntry[] }> = []
+    for (const teamID of mine) {
+      const sessions = (await this.seated(userID, teamID, address.role, address.project)).filter((e) => e.sessionID !== from.sessionID)
+      if (sessions.length) matches.push({ teamID, sessions })
+    }
+    if (matches.length > 1) {
+      const candidates: Array<{ team: string; address: string }> = []
+      for (const m of matches) {
+        const name = (await this.deps.teams.get(userID, m.teamID))?.name
+        if (name) candidates.push({ team: name, address: `@@${address.role}${address.project ? `.${address.project}` : ""}#${name}` })
+      }
+      candidates.sort((a, b) => (a.team < b.team ? -1 : 1))
+      throw new AgentError("ambiguous", `${addr} is a role in ${matches.length} of your teams`, { hint: "Name the team: @@role#team (quote # in a shell)", extra: { candidates } })
+    }
+    const only = matches[0]
+    return only ? { address, sessions: only.sessions, team: { teamID: only.teamID, explicit: false } } : undefined
+  }
+
+  /** Directory entries of the sessions currently seated in the role (and the project, when given). */
+  private async seated(userID: string, teamID: string, role: string, project: string | undefined): Promise<DirectoryEntry[]> {
+    const ids = [...new Set((await this.deps.seats.list(userID, teamID, { current: true })).filter((s) => s.role === role).map((s) => s.sessionID))]
+    const out: DirectoryEntry[] = []
+    for (const id of ids) {
+      let entry: DirectoryEntry | undefined
+      try {
+        entry = this.deps.directory.resolve(userID, id).sessions.find((e) => e.sessionID === id)
+      } catch {
+        entry = undefined // a seat of a session the directory no longer knows: nobody to deliver to
+      }
+      if (entry && (project === undefined || entry.project === project)) out.push(entry)
+    }
+    return out
+  }
+}
+
+const seatsIn = (ctx: DeliveryContext, sessionID: string): readonly TeamSeat[] => ctx.seats.get(sessionID) ?? []