heyquilt 0.0.1 → 0.3.90

package/src/api/routes/relay.js

@@ -0,0 +1,76 @@
+// The relay reports who is in which session and when (src/presence.js on the relay). It
+// signs in with RELAY_API_SECRET. Each event applies once: replays are ignored.
+import crypto from 'node:crypto'
+import { HttpError, UUID, stripInvisible } from '../http.js'
+import { DAY_MS } from '../activity.js'
+import { cleanSessionName } from '../../session-name.js'
+import { END_REASONS, ACTIONS } from '../../presence.js'
+
+export const MAX_EVENTS = 500
+// 500 events of a few hundred bytes each: more than the API's usual 16 KB.
+export const PRESENCE_BODY = 512 * 1024
+export const KEEP_MS = 365 * DAY_MS
+export const SEEN_MS = 7 * DAY_MS
+const ROOM = /^[A-Za-z0-9_-]{1,64}$/
+const ACCOUNT = /^(person|agent):[A-Za-z0-9_-]{1,64}$/
+
+const VIA = ['app', 'hosted']
+/** A short label: printable, at most `n` characters. */
+const label = (x, n) => stripInvisible(x).slice(0, n).join('').replace(/[\u0000-\u001f\u007f]/g, '').trim()
+
+const digest = (s) => crypto.createHash('sha256').update(String(s)).digest()
+
+/** An event as the store takes it, or null when it isn't one (it is skipped, not retried). */
+export function cleanEvent (e, now) {
+  if (!e || typeof e !== 'object' || !UUID.test(String(e.id)) || !ROOM.test(String(e.room)) || !Number.isFinite(e.at)) return null
+  // The relay's clock may run ahead; nothing is recorded in the future.
+  const at = Math.min(e.at, now)
+  if (at < now - KEEP_MS) return null
+  const base = { id: String(e.id).toLowerCase(), type: e.type, room: e.room, at }
+  if (e.type === 'start') {
+    if (!ACCOUNT.test(String(e.account))) return null
+    const name = stripInvisible(e.name).slice(0, 64).join('').trim() || 'Quilt user'
+    const how = { ...(VIA.includes(e.via) ? { via: e.via } : {}), ...(label(e.tool, 40) ? { tool: label(e.tool, 40) } : {}) }
+    return { ...base, account: e.account, name, owner: e.owner === true, ...how }
+  }
+  if (e.type === 'end') {
+    if (!ACCOUNT.test(String(e.account)) || !UUID.test(String(e.start))) return null
+    return { ...base, account: e.account, start: String(e.start).toLowerCase(), ...(END_REASONS.includes(e.reason) ? { reason: e.reason } : {}) }
+  }
+  if (e.type === 'act') {
+    if (!ACCOUNT.test(String(e.account)) || !UUID.test(String(e.start)) || !ACTIONS.includes(e.action)) return null
+    return { ...base, account: e.account, start: String(e.start).toLowerCase(), action: e.action, target: label(e.target, 300) }
+  }
+  if (e.type === 'name') {
+    const name = cleanSessionName(e.name)
+    return name ? { ...base, name } : null
+  }
+  return null
+}
+
+export function relayRoutes ({ store, now, log, bearer, relaySecret }) {
+  let prunedAt = 0
+  const fromRelay = (req) => {
+    if (!relaySecret) throw new HttpError(503, 'presence is not set up on this server')
+    // Hashed first so the comparison takes the same time whatever was sent.
+    if (!crypto.timingSafeEqual(digest(bearer(req)), digest(relaySecret))) throw new HttpError(401, 'only the relay may report presence')
+  }
+
+  return [
+    ['POST', /^\/v1\/relay\/presence$/, async (req, body) => {
+      fromRelay(req)
+      if (!Array.isArray(body.events)) throw new HttpError(400, 'events must be a list')
+      if (body.events.length > MAX_EVENTS) throw new HttpError(413, `at most ${MAX_EVENTS} events at a time`)
+      const t = now()
+      const events = body.events.map((e) => cleanEvent(e, t)).filter(Boolean)
+      const applied = events.length ? await store.ingestPresence(events, t) : 0
+      // Visits older than 12 months go once a day, when the relay next reports (the API has no timer).
+      if (t - prunedAt >= DAY_MS) {
+        prunedAt = t
+        await store.pruneActivity({ before: t - KEEP_MS, seenBefore: t - SEEN_MS })
+          .catch((err) => log(`could not prune session activity: ${err?.message || err}`))
+      }
+      return { ok: true, applied, skipped: body.events.length - events.length }
+    }, { maxBody: PRESENCE_BODY }]
+  ]
+}

package/src/api/routes/session-invites.js

@@ -0,0 +1,119 @@
+// Inviting people and agents to a session, as an access type: by email, or someone the
+// owner has worked with. The grant is made up front (keyed by the account, or by the
+// email until someone signs in with it), so they get straight in. The invite link holds
+// the room secret: it goes into the email, and is kept with the invite only so the person
+// it was sent to sees it in their Quilt (GET /v1/me/invites); the owner's views never show it.
+import { HttpError, UUID, stripInvisible } from '../http.js'
+import { emailDomain } from '../domains.js'
+import { sessionInviteEmail } from '../invite-email.js'
+import { parseInvite } from '../../ui/invite.js'
+import { ownType, typeOfGrant } from '../access.js'
+import { sessionOwner, ACCOUNT, letAgentBackIn } from './grants.js'
+import { collaboratorsOf } from './sessions.js'
+
+export const SESSION_INVITE_TTL_MS = 7 * 24 * 60 * 60 * 1000
+const FORBIDDEN = 'Only the session owner can invite people.'
+// One address, nothing a mail header could split (the same rule as org invites).
+const STRICT_EMAIL = /^[^\s@,;<>"()\\]+@[^\s@,;<>"()\\]+$/
+
+export function sessionInviteRoutes ({ store, person, now, site, mailer, log, limitSend, workspaces = false }) {
+  const statusOf = (i) => (i.usedAt ? 'used' : i.cancelledAt ? 'cancelled' : i.expiresAt <= now() ? 'expired' : 'waiting')
+  // The invite comes first, then its grant: one that loses a race to another open invite for
+  // the same address or account (the database's unique index) changes nothing.
+  async function createInvite (fields, duplicateMessage, grant) {
+    let invite
+    try {
+      invite = await store.createSessionInvite({ ...fields, at: now() })
+    } catch (err) {
+      if (err.code === '23505') throw new HttpError(409, duplicateMessage)
+      throw err
+    }
+    // No grant, no invite: an open one would block inviting them again.
+    try { await store.putGrant(grant) } catch (err) { await store.cancelSessionInvite(invite.id).catch(() => {}); throw err }
+    await letAgentBackIn(store, grant.room, grant.account, workspaces, log)
+    return invite
+  }
+  // An account invite shows the name the owner saw, never the person's email.
+  async function view (i) {
+    const type = await typeOfGrant(store, { typeId: i.typeId })
+    return { id: i.id, ...(i.email ? { email: i.email } : { account: i.account, name: i.accountName }), typeId: type.id, typeName: type.name, status: statusOf(i), createdAt: i.createdAt, expiresAt: i.expiresAt }
+  }
+
+  function cleanEmail (raw) {
+    const email = String(raw || '').trim().toLowerCase()
+    if (!email || email.length > 254 || !STRICT_EMAIL.test(email) || !emailDomain(email)) throw new HttpError(400, "That email doesn't look right.")
+    return email
+  }
+
+  async function send (to, { userId, session, link }) {
+    const inviter = await store.profile(userId)
+    const inviterName = stripInvisible(inviter?.name || '').join('').trim() || undefined
+    const msg = sessionInviteEmail({ inviterName, sessionName: session.name || 'Untitled session', link, site })
+    try {
+      await mailer.send({ to, ...msg })
+    } catch (err) {
+      log(`session invite email failed: ${err?.stack || err?.message || err}`)
+      throw new HttpError(502, "The invite was saved, but the email didn't send. Cancel it and invite them again.")
+    }
+  }
+
+  return [
+    ['GET', /^\/v1\/sessions\/([^/]+)\/invites$/, async (req, body, [room]) => {
+      await sessionOwner(store, person, req, room, FORBIDDEN)
+      return { invites: await Promise.all((await store.listSessionInvites(room)).map(view)) }
+    }],
+
+    ['POST', /^\/v1\/sessions\/([^/]+)\/invites$/, async (req, body, [room]) => {
+      const owner = await sessionOwner(store, person, req, room, FORBIDDEN)
+      limitSend(owner.userId)
+      const type = await ownType(store, owner.me, body.typeId)
+      if (!type) throw new HttpError(400, 'no such access type')
+      let inv = null
+      try { inv = parseInvite(body.link, { allowRelay: () => true }) } catch {}
+      if (!inv || inv.room !== room) throw new HttpError(400, "Send this session's invite link.")
+      const link = String(body.link).trim()
+      const to = body.to && typeof body.to === 'object' ? body.to : {}
+
+      if (to.email !== undefined) {
+        const email = cleanEmail(to.email)
+        const taken = 'That address already has an open invite. Cancel it first.'
+        if (await store.openSessionInvite(room, { email }, now())) throw new HttpError(409, taken)
+        const invite = await createInvite({ room, email, typeId: type.id, invitedBy: owner.me, expiresAt: now() + SESSION_INVITE_TTL_MS, link }, taken,
+          { room, account: `email:${email}`, typeId: type.id, grantedBy: owner.me })
+        await send(email, { ...owner, link })
+        return { invite: await view(invite) }
+      }
+
+      const account = String(to.account || '')
+      if (!ACCOUNT.test(account)) throw new HttpError(400, 'Invite someone by email, or someone you have worked with.')
+      if (account === owner.me) throw new HttpError(400, "That's you.")
+      const who = (await collaboratorsOf(store, owner.me, now())).find((c) => c.account === account)
+      if (!who) throw new HttpError(404, "You can invite people you've worked with, or anyone by email.")
+      const taken = 'They already have an open invite. Cancel it first.'
+      if (await store.openSessionInvite(room, { account }, now())) throw new HttpError(409, taken)
+      // Inviting them again would overwrite the access they have, and cancelling that invite
+      // would then take it all away.
+      if (await store.grantFor(room, account)) throw new HttpError(409, 'They already have access to this session. Change it in Session settings.')
+      const invite = await createInvite({ room, account, accountName: who.name, typeId: type.id, invitedBy: owner.me, expiresAt: now() + SESSION_INVITE_TTL_MS, link }, taken,
+        { room, account, typeId: type.id, grantedBy: owner.me })
+      // A person hears about it at their sign-in email (looked up here, never sent back). An
+      // agent has no email: its grant just lets it straight in.
+      if (who.kind === 'person') {
+        const mail = await store.userEmail(account.slice('person:'.length))
+        if (mail?.confirmed && mail.email) await send(mail.email, { ...owner, link })
+      }
+      return { invite: await view(invite) }
+    }],
+
+    // Cancelling also takes back the grant the invite made, unless someone already used it.
+    ['DELETE', /^\/v1\/sessions\/([^/]+)\/invites\/([^/]+)$/, async (req, body, [room, id]) => {
+      await sessionOwner(store, person, req, room, FORBIDDEN)
+      const invite = UUID.test(id) ? await store.sessionInviteById(room, id) : null
+      if (!invite) throw new HttpError(404, 'no such invite')
+      if (!await store.cancelSessionInvite(invite.id)) throw new HttpError(409, 'That invite was already used or cancelled.')
+      // Unless an open invite for the same address or account needs it, even one made just now.
+      await store.deleteUnusedGrant(room, invite.email ? `email:${invite.email}` : invite.account, now())
+      return { ok: true }
+    }]
+  ]
+}

package/src/api/routes/sessions.js

@@ -0,0 +1,92 @@
+// Your sessions on the dashboard: where you've been, your time there, and who you
+// worked with (activity.js does the sums). Only sessions you were in, and only people
+// who were there at the same time as you.
+import { HttpError, Raw } from '../http.js'
+import { auditTrail, auditCsv, MAX_ACTIONS } from '../audit.js'
+import { summarize, collaborators, myVisits, isTimeZone, weekStart, monthStart, MAX_SESSIONS } from '../activity.js'
+import { cleanSessionName, BAD_SESSION_NAME } from '../../session-name.js'
+
+const ROOM = /^[A-Za-z0-9_-]{1,64}$/
+const NO_SESSION = 'no such session'
+
+/** An account's dashboard: its sessions, with the people in each, and the totals. */
+export async function overviewOf (store, account, tz, t) {
+  // The latest sessions, plus every one active this week or month, for the totals.
+  const since = Math.min(weekStart(t, tz), monthStart(t, tz))
+  const sessions = await store.accountSessions(account, { since, limit: MAX_SESSIONS })
+  const visits = await store.visitsInRooms(sessions.map((s) => s.room))
+  return summarize({ me: account, sessions, visits, now: t, tz })
+}
+
+/** People and agents this account has worked with: [{ account, name, kind, lastTogetherAt }], most recent first. */
+export async function collaboratorsOf (store, account, t) {
+  return collaborators((await overviewOf(store, account, 'UTC', t)).sessions)
+}
+
+export function sessionRoutes ({ store, now, person }) {
+  const me = async (req) => `person:${(await person(req)).userId}`
+  const zoneOf = (req) => {
+    const tz = new URL(req.url, 'http://x').searchParams.get('tz') || 'UTC'
+    if (!isTimeZone(tz)) throw new HttpError(400, 'tz must be an IANA time zone, like Europe/London')
+    return tz
+  }
+  const overview = (account, tz) => overviewOf(store, account, tz, now())
+
+  /** A session I was in, with every visit to it; 404 otherwise, whether or not it exists. */
+  async function mine (account, room) {
+    if (!ROOM.test(room)) throw new HttpError(404, NO_SESSION)
+    const session = await store.sessionByRoom(room)
+    const visits = session ? await store.visitsInRooms([room]) : []
+    if (!visits.some((v) => v.account === account)) throw new HttpError(404, NO_SESSION)
+    return { session, visits }
+  }
+
+  return [
+    ['GET', /^\/v1\/me\/sessions$/, async (req) => overview(await me(req), zoneOf(req))],
+
+    ['GET', /^\/v1\/me\/sessions\/([^/]+)$/, async (req, body, [room]) => {
+      const account = await me(req)
+      const { session, visits } = await mine(account, room)
+      const [s] = summarize({ me: account, sessions: [session], visits, now: now() }).sessions
+      return { session: { ...s, visits: myVisits({ me: account, visits }) } }
+    }],
+
+    // The owner's rename shows for everyone, and the relay's name no longer replaces it.
+    ['PUT', /^\/v1\/me\/sessions\/([^/]+)$/, async (req, body, [room]) => {
+      const account = await me(req)
+      const name = cleanSessionName(body.name)
+      if (!name) throw new HttpError(400, BAD_SESSION_NAME)
+      const { session } = await mine(account, room)
+      if (session.ownerAccount !== account) throw new HttpError(403, 'Only the session owner can rename it.')
+      const renamed = await store.renameSession(room, name, now())
+      return { session: { room, name: renamed.name } }
+    }],
+
+    // The audit trail, for the owner only: every visit, how it came in, why it ended, and
+    // what it did. ?format=csv for a spreadsheet; ?from= and ?to= (epoch ms) narrow it.
+    ['GET', /^\/v1\/me\/sessions\/([^/]+)\/audit$/, async (req, body, [room]) => {
+      const account = await me(req)
+      const { session, visits } = await mine(account, room)
+      if (session.ownerAccount !== account) throw new HttpError(403, 'Only the session owner can see its audit trail.')
+      const q = new URL(req.url, 'http://x').searchParams
+      const t = now()
+      const num = (k, d) => { const n = Number(q.get(k)); return q.has(k) && Number.isFinite(n) ? n : d }
+      const from = num('from', 0)
+      const to = num('to', t + 1)
+      const inWindow = visits.filter((v) => v.startedAt < to && (v.endedAt == null || v.endedAt >= from))
+      const actions = await store.actionsInRoom(room, { from, to, limit: MAX_ACTIONS + 1 })
+      const truncated = actions.length > MAX_ACTIONS
+      const revoked = new Map()
+      for (const acc of new Set(inWindow.filter((v) => v.kind === 'agent').map((v) => v.account))) {
+        const agent = await store.agentById(acc.slice('agent:'.length)).catch(() => null)
+        if (agent && agent.revokedAt != null) revoked.set(acc, agent.revokedAt)
+      }
+      const trail = auditTrail({ visits: inWindow, actions: actions.slice(0, MAX_ACTIONS), revoked })
+      if (q.get('format') === 'csv') return new Raw(200, auditCsv(trail), 'text/csv; charset=utf-8')
+      return { session: { room, name: session.name }, from, to, truncated, visits: trail }
+    }],
+
+    // People and agents you've worked with, for invites (most recent first, at most 30).
+    ['GET', /^\/v1\/me\/collaborators$/, async (req) => ({ collaborators: await collaboratorsOf(store, await me(req), now()) })]
+  ]
+}

package/src/api/routes/teams.js

@@ -0,0 +1,132 @@
+// Flat teams inside an org, and who's in each: people and agents with editor or
+// viewer access, and for agents, optional folders.
+import { HttpError, needId, cleanName } from '../http.js'
+import { orgAccess } from '../org-access.js'
+import { accessOf, cleanScopes } from '../team-access.js'
+
+const kindOf = (m) => (m.agentId ? 'agent' : 'person')
+const memberView = (tm) => ({ memberId: tm.memberId, access: tm.access, scopes: tm.scopes || [] })
+
+export function teamRoutes ({ store, user, policyChanged = null }) {
+  const orgFor = async (req, slug) => { const u = await user(req); return { u, ...(await orgAccess(store, u.userId, slug)) } }
+
+  async function teamIn (a, id) {
+    const team = await store.teamById(a.org.id, needId(id, 'team'))
+    if (!team) throw new HttpError(404, 'no such team')
+    return team
+  }
+
+  // Folders only limit agents; a person in a team always reaches all of it.
+  // undefined means "leave the folders as they are".
+  function foldersFor (m, raw) {
+    if (raw === undefined) return undefined
+    const scopes = cleanScopes(raw)
+    if (scopes.length && !m.agentId) throw new HttpError(400, 'Folders are only for agents.')
+    return scopes
+  }
+
+  return [
+    ['GET', /^\/v1\/orgs\/([^/]+)\/teams$/, async (req, body, [slug]) => {
+      const a = await orgFor(req, slug)
+      const mine = new Map((await store.teamsOfMember(a.me.id)).map((x) => [x.teamId, x.access]))
+      // Teams: Read shows every team; everyone sees the teams they're in.
+      const teams = (await store.listTeams(a.org.id)).filter((t) => a.can('teams', 'r') || mine.has(t.id))
+      return {
+        teams: await Promise.all(teams.map(async (t) => ({
+          id: t.id,
+          name: t.name,
+          createdAt: t.createdAt,
+          access: mine.get(t.id) || null,
+          // The team's git rule (git for everyone: '' sets nothing, off, branches or any).
+          git: (await store.teamGithub(t.id)).agentCommits,
+          members: a.can('team_members', 'r') || mine.has(t.id)
+            ? (await store.listTeamMembers(t.id)).map((m) => ({ memberId: m.memberId, name: m.name, access: m.access, kind: m.kind, scopes: m.scopes || [] }))
+            : null
+        }))),
+        // The people and agents you could add, for those who add to teams.
+        people: a.can('team_members', 'c')
+          ? (await store.listMembers(a.org.id)).map((m) => ({ memberId: m.id, name: m.name, kind: kindOf(m) }))
+          : null
+      }
+    }],
+
+    ['POST', /^\/v1\/orgs\/([^/]+)\/teams$/, async (req, body, [slug]) => {
+      const a = await orgFor(req, slug)
+      a.need('teams', 'c')
+      return { team: await store.createTeam({ orgId: a.org.id, name: cleanName(body.name, 60, 'give the team a name') }) }
+    }],
+
+    ['PUT', /^\/v1\/orgs\/([^/]+)\/teams\/([^/]+)$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      a.need('teams', 'u')
+      const team = await teamIn(a, id)
+      return { team: await store.renameTeam(team.id, cleanName(body.name, 60, 'give the team a name')) }
+    }],
+
+    ['DELETE', /^\/v1\/orgs\/([^/]+)\/teams\/([^/]+)$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      a.need('teams', 'd')
+      await store.deleteTeam((await teamIn(a, id)).id)
+      if (policyChanged) policyChanged() // its git rule goes with it
+      return { ok: true }
+    }],
+
+    ['POST', /^\/v1\/orgs\/([^/]+)\/teams\/([^/]+)\/members$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      a.need('team_members', 'c')
+      const team = await teamIn(a, id)
+      const access = accessOf(body.access ?? 'viewer')
+      const m = await store.memberById(a.org.id, needId(body.memberId, 'member'))
+      if (!m) throw new HttpError(404, 'no such member')
+      const scopes = foldersFor(m, body.scopes) ?? []
+      // addTeamMember upserts; without this, Create alone could restyle someone's
+      // access by re-adding them, which is Team membership: Update's job.
+      if ((await store.listTeamMembers(team.id)).some((x) => x.memberId === m.id)) throw new HttpError(409, 'That person is already in this team.')
+      const added = memberView(await store.addTeamMember({ teamId: team.id, memberId: m.id, access, scopes }))
+      if (policyChanged) policyChanged() // the team's git rule now covers their sessions
+      return { member: added }
+    }],
+
+    ['PUT', /^\/v1\/orgs\/([^/]+)\/teams\/([^/]+)\/members\/([^/]+)$/, async (req, body, [slug, id, memberId]) => {
+      const a = await orgFor(req, slug)
+      a.need('team_members', 'u')
+      const team = await teamIn(a, id)
+      const m = await store.memberById(a.org.id, needId(memberId, 'member'))
+      if (!m) throw new HttpError(404, "that person isn't in this team")
+      const tm = await store.setTeamAccess(team.id, m.id, accessOf(body.access), foldersFor(m, body.scopes))
+      if (!tm) throw new HttpError(404, "that person isn't in this team")
+      return { member: memberView(tm) }
+    }],
+
+    // The team's git rule (docs/superpowers/specs/2026-10-17-git-for-everyone.md): whether git is on for
+    // everyone in the sessions its people own in the org's workspaces, and what agents may push there.
+    // '' sets nothing; off, branches or any is a ceiling for the workspaces' and sessions' own choices.
+    ['GET', /^\/v1\/orgs\/([^/]+)\/teams\/([^/]+)\/github$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      const team = await teamIn(a, id)
+      const mine = (await store.teamsOfMember(a.me.id)).some((x) => x.teamId === team.id)
+      if (!a.can('teams', 'r') && !mine) throw new HttpError(404, 'no such team')
+      return store.teamGithub(team.id)
+    }],
+    ['PUT', /^\/v1\/orgs\/([^/]+)\/teams\/([^/]+)\/github$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      a.need('teams', 'u')
+      const team = await teamIn(a, id)
+      if (!('agentCommits' in body)) throw new HttpError(400, 'Give agentCommits: "" (the team sets nothing), off, branches or any.')
+      const v = body.agentCommits === null ? '' : body.agentCommits
+      if (!['', 'off', 'branches', 'any'].includes(v)) throw new HttpError(400, 'agentCommits is "" (the team sets nothing), off, branches or any.')
+      await store.setTeamGithub(team.id, { agentCommits: v })
+      if (policyChanged) policyChanged()
+      return store.teamGithub(team.id)
+    }],
+
+    ['DELETE', /^\/v1\/orgs\/([^/]+)\/teams\/([^/]+)\/members\/([^/]+)$/, async (req, body, [slug, id, memberId]) => {
+      const a = await orgFor(req, slug)
+      a.need('team_members', 'd')
+      const team = await teamIn(a, id)
+      if (!await store.removeTeamMember(team.id, needId(memberId, 'member'))) throw new HttpError(404, "that person isn't in this team")
+      if (policyChanged) policyChanged()
+      return { ok: true }
+    }]
+  ]
+}