@sixb/core 0.1.20 → 0.1.22

package/src/activity/connection.ts

@@ -0,0 +1,217 @@
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { ActivityVisit, StoredActivityVisitPage } from "../storage/activity/types"
+import type { SessionRecord } from "../storage/auth"
+import type { ShareGrantRecord } from "../storage/share-grants"
+import { type ActivityDevice, describeUserAgent } from "./device"
+import type { ActivityService } from "./service"
+
+export type ActivityConnectionStatus = "active" | "expired" | "revoked"
+
+/** A signed-in session. No address or token is kept here. */
+export interface ActivitySessionConnection {
+  readonly type: "session"
+  readonly device: ActivityDevice
+  /** A native client's own label, such as a CLI's. */
+  readonly clientName?: string
+  readonly status: ActivityConnectionStatus
+  readonly createdAt: Date
+  readonly lastSeenAt?: Date
+  readonly revokedAt?: Date
+}
+
+/** The shared link a visitor opened, and the session it gave them. */
+export interface ActivityShareConnection {
+  readonly type: "share"
+  readonly grantId: string
+  /** Absent once the link's grant is gone. */
+  readonly definitionId?: string
+  readonly status: ActivityConnectionStatus
+  readonly createdAt: Date
+  readonly revokedAt?: Date
+}
+
+export type ActivityConnection = ActivitySessionConnection | ActivityShareConnection
+
+/** A user's sign-in, with the visits it opened. */
+export interface ActivityUserConnection extends ActivitySessionConnection {
+  /** Every visit the session opened. */
+  readonly visits: number
+  /** Its latest visits, newest first. */
+  readonly latestVisits: readonly ActivityVisit[]
+}
+
+export interface ActivityConnectionsPage {
+  readonly connections: readonly ActivityUserConnection[]
+  /** Pass it back as `cursor` for the next, older connections; absent on the last page. */
+  readonly nextCursor?: string
+}
+
+export interface ActivityConnectionsQuery {
+  readonly userId: string
+  /** 1 to 100. Default: 20. */
+  readonly limit?: number
+  /** The previous page's `nextCursor`. */
+  readonly cursor?: string
+}
+
+/** Where a list of sessions continues: a creation time, and how many created then it returned. */
+export interface ActivityConnectionsCursor {
+  readonly createdAt: Date
+  readonly skip: number
+}
+
+/** A user's sign-ins, newest first, revoked and expired ones too: one read per store. */
+export async function readActivityConnections(
+  runtime: SixbRuntimeContext,
+  service: ActivityService,
+  query: ActivityConnectionsQuery,
+  now: Date
+): Promise<ActivityConnectionsPage> {
+  const { userId, limit, before } = service.connectionsQuery(query)
+  const sessions = runtime.storage.auth?.sessions
+  if (!sessions) {
+    return { connections: [] }
+  }
+
+  const page = await sessions.listByUserId({
+    projectId: runtime.projectId,
+    userId,
+    limit,
+    ...(before === undefined ? {} : { before }),
+  })
+  const visits = await service.sessionVisits({
+    userId,
+    sessionIds: page.sessions.map((session) => session.id),
+  })
+  const bySession = new Map(visits.map((entry) => [entry.sessionId, entry]))
+
+  const connections = page.sessions.map((session) => ({
+    ...sessionConnection(session, now),
+    visits: bySession.get(session.id)?.visits ?? 0,
+    latestVisits: bySession.get(session.id)?.latest ?? [],
+  }))
+  const last = page.sessions.at(-1)
+
+  return {
+    connections,
+    ...(page.hasMore && last
+      ? { nextCursor: nextConnectionsCursor(page.sessions, last, before) }
+      : {}),
+  }
+}
+
+/**
+ * The cursor after a page: its last creation time, and how many sessions created then this page
+ * and the ones before it returned. It names no session, so the session id never leaves core.
+ */
+function nextConnectionsCursor(
+  sessions: readonly SessionRecord[],
+  last: SessionRecord,
+  before: ActivityConnectionsCursor | undefined
+): string {
+  const { createdAt } = last
+  const tied = sessions.filter((session) => session.createdAt.getTime() === createdAt.getTime())
+  const earlier = before && before.createdAt.getTime() === createdAt.getTime() ? before.skip : 0
+
+  return encodeActivityConnectionsCursor({ createdAt, skip: earlier + tied.length })
+}
+
+export function encodeActivityConnectionsCursor(cursor: ActivityConnectionsCursor): string {
+  return Buffer.from(JSON.stringify([cursor.createdAt.toISOString(), cursor.skip])).toString(
+    "base64url"
+  )
+}
+
+export function decodeActivityConnectionsCursor(value: string): ActivityConnectionsCursor {
+  try {
+    const parsed: unknown = JSON.parse(Buffer.from(value, "base64url").toString("utf8"))
+    if (Array.isArray(parsed) && parsed.length === 2) {
+      const [at, skip] = parsed
+      const createdAt = new Date(typeof at === "string" ? at : Number.NaN)
+      if (Number.isFinite(createdAt.getTime()) && Number.isSafeInteger(skip) && skip >= 0) {
+        return { createdAt, skip }
+      }
+    }
+  } catch {
+    // Reported below, like any other malformed cursor.
+  }
+  throw new Error("[Sixb] Invalid activity connections cursor.")
+}
+
+/**
+ * The session a visit came through: a sign-in, or a shared link, whose grant the caller read with
+ * the visit's share name.
+ */
+export async function readActivityConnection(
+  runtime: SixbRuntimeContext,
+  page: StoredActivityVisitPage,
+  grant: ShareGrantRecord | undefined,
+  now: Date
+): Promise<ActivityConnection | undefined> {
+  const { storage, projectId } = runtime
+  const { actor } = page.visit
+
+  if (actor.type === "user") {
+    const session = await storage.auth?.sessions.getById({ projectId, id: page.sessionId })
+    return session ? sessionConnection(session, now) : undefined
+  }
+
+  const session = await storage.shareSessions?.getById({ projectId, id: page.sessionId })
+  if (!session) {
+    return undefined
+  }
+
+  // A session lasts no longer than its link: revoking or expiring the grant ends it too.
+  const revokedAt = [session.revokedAt, grant?.revokedAt]
+    .flatMap((at) => (at === undefined ? [] : [at.getTime()]))
+    .sort((left, right) => left - right)[0]
+  const statuses = [
+    connectionStatus(session, now),
+    ...(grant ? [connectionStatus(grant, now)] : []),
+  ]
+  const status = statuses.includes("revoked")
+    ? "revoked"
+    : statuses.includes("expired")
+      ? "expired"
+      : "active"
+
+  return {
+    type: "share",
+    grantId: actor.grantId,
+    ...(grant ? { definitionId: grant.definitionId } : {}),
+    status,
+    createdAt: new Date(session.createdAt),
+    ...(revokedAt === undefined ? {} : { revokedAt: new Date(revokedAt) }),
+  }
+}
+
+function connectionStatus(
+  session: {
+    readonly expiresAt: Date
+    readonly absoluteExpiresAt?: Date
+    readonly revokedAt?: Date
+  },
+  now: Date
+): ActivityConnectionStatus {
+  if (session.revokedAt) {
+    return "revoked"
+  }
+
+  const expired =
+    session.expiresAt <= now ||
+    (session.absoluteExpiresAt !== undefined && session.absoluteExpiresAt <= now)
+  return expired ? "expired" : "active"
+}
+
+/** A signed-in session as a connection, from its record and the time it is read at. */
+function sessionConnection(session: SessionRecord, now: Date): ActivitySessionConnection {
+  return {
+    type: "session",
+    device: describeUserAgent(session.userAgent),
+    ...(session.bearer === undefined ? {} : { clientName: session.bearer.clientName }),
+    status: connectionStatus(session, now),
+    createdAt: new Date(session.createdAt),
+    ...(session.lastSeenAt === undefined ? {} : { lastSeenAt: new Date(session.lastSeenAt) }),
+    ...(session.revokedAt === undefined ? {} : { revokedAt: new Date(session.revokedAt) }),
+  }
+}

package/src/activity/device.ts

@@ -0,0 +1,41 @@
+/** What a user agent says about the device that signed in. Display only, never authorization. */
+export interface ActivityDevice {
+  readonly browser?: string
+  readonly os?: string
+}
+
+// First match wins: Edge and Opera also name Chrome, Chrome names Safari, iOS names Mac OS X, and
+// Android names Linux.
+const BROWSERS: readonly (readonly [RegExp, string])[] = [
+  [/\bEdg(?:e|A|iOS)?\//, "Edge"],
+  [/\b(?:OPR|Opera)\//, "Opera"],
+  [/\bSamsungBrowser\//, "Samsung Internet"],
+  [/\b(?:Firefox|FxiOS)\//, "Firefox"],
+  [/\b(?:Chrome|Chromium|CriOS|HeadlessChrome)\//, "Chrome"],
+  [/\bVersion\/[\d.]+.*\bSafari\//, "Safari"],
+]
+
+const SYSTEMS: readonly (readonly [RegExp, string])[] = [
+  [/\bWindows\b/, "Windows"],
+  [/\biPad\b/, "iPadOS"],
+  [/\b(?:iPhone|iPod)\b/, "iOS"],
+  [/\bAndroid\b/, "Android"],
+  [/\bCrOS\b/, "ChromeOS"],
+  [/\bMac OS X\b|\bMacintosh\b/, "macOS"],
+  [/\bLinux\b/, "Linux"],
+]
+
+/** The browser and operating system a user agent names, when it names a common one. */
+export function describeUserAgent(userAgent: string | undefined): ActivityDevice {
+  if (!userAgent) {
+    return {}
+  }
+
+  const browser = BROWSERS.find(([pattern]) => pattern.test(userAgent))?.[1]
+  const os = SYSTEMS.find(([pattern]) => pattern.test(userAgent))?.[1]
+
+  return {
+    ...(browser === undefined ? {} : { browser }),
+    ...(os === undefined ? {} : { os }),
+  }
+}

package/src/activity/execution.ts

@@ -0,0 +1,210 @@
+import { AuthorizationError, assertAuthorized } from "../authorization"
+import { getAuthorizationRef } from "../execution/authorization"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { ActivityEventInput, ActivitySummary, ActivityUser } from "../storage/activity/types"
+import {
+  type ActivityConnectionsPage,
+  type ActivityConnectionsQuery,
+  readActivityConnections,
+} from "./connection"
+import type {
+  ActivityCalendar,
+  ActivityCalendarQuery,
+  ActivityCaptureOptions,
+  ActivityCaptureResult,
+  ActivityPageQuery,
+  ActivityPeriodQuery,
+  ActivityService,
+  ActivitySource,
+} from "./service"
+import { type ActivityVisitView, nameSharedVisit, nameSharedVisits } from "./shares"
+import {
+  ACTIVITY_TIMELINE_LIMIT,
+  type ActivityVisitTimeline,
+  composeActivityTimeline,
+} from "./timeline"
+
+export interface ActivityVisitList {
+  readonly visits: readonly ActivityVisitView[]
+  readonly hasMore: boolean
+}
+
+export interface ActivityUsersResult {
+  /** `displayName` is the account's profile name; no other profile field is read. */
+  readonly users: readonly (ActivityUser & { readonly displayName?: string })[]
+  readonly hasMore: boolean
+}
+
+/** `sixb.activity`: the app's recorded visits. Every read needs `can.observe(project.activity)`. */
+export interface ActivityRuntime {
+  /** Shared visits name their link's share: see `ActivityVisitView`. */
+  list(query: ActivityPageQuery): Promise<ActivityVisitList>
+  users(query: ActivityPageQuery): Promise<ActivityUsersResult>
+  summarize(query: ActivityPeriodQuery): Promise<ActivitySummary>
+  calendar(query: ActivityCalendarQuery): Promise<ActivityCalendar>
+  /**
+   * The visit's page views and interactions with the actions, workflows and Agent runs its session
+   * started, and the connection it came through. Bounded: see `truncated`.
+   */
+  timeline(visitId: string): Promise<ActivityVisitTimeline | null>
+  /** A user's sign-ins, newest first, with the visits each opened. */
+  connections(query: ActivityConnectionsQuery): Promise<ActivityConnectionsPage>
+}
+
+/**
+ * Recording, for the server's capture route only: it is not on `sixb.activity`, so project code
+ * cannot record visits under whatever authority it runs with.
+ */
+export interface ActivityCaptureRuntime {
+  /** The settings a browser session reads before it sends anything. */
+  captureOptions(): ActivityCaptureOptions
+  /** Records a batch for the calling user or shared session. */
+  capture(events: readonly ActivityEventInput[]): Promise<ActivityCaptureResult>
+}
+
+// Display names are read one account at a time; a page of users reads a few at once.
+const PROFILE_READ_CONCURRENCY = 8
+
+export function createActivityRuntime(
+  runtime: SixbRuntimeContext,
+  service: ActivityService
+): ActivityRuntime {
+  const assertObservable = () => assertAuthorized(runtime, { kind: "activity.observe" })
+
+  return {
+    async list(query) {
+      assertObservable()
+      const page = await service.list(query)
+      return { ...page, visits: await nameSharedVisits(runtime, page.visits) }
+    },
+
+    async users(query) {
+      assertObservable()
+      const page = await service.users(query)
+
+      // Only accounts in this bounded page are looked up, and only their name is kept.
+      const users = await mapInChunks(page.users, PROFILE_READ_CONCURRENCY, async (user) => {
+        const profile = await runtime.storage.auth?.users.getById({
+          projectId: runtime.projectId,
+          id: user.userId,
+        })
+        return profile?.displayName ? { ...user, displayName: profile.displayName } : user
+      })
+
+      return { users, hasMore: page.hasMore }
+    },
+
+    async summarize(query) {
+      assertObservable()
+      return service.summarize(query)
+    },
+
+    async calendar(query) {
+      assertObservable()
+      return service.calendar(query)
+    },
+
+    async timeline(visitId) {
+      assertObservable()
+      const page = await service.readWithSession({ id: visitId, limit: ACTIVITY_TIMELINE_LIMIT })
+      if (!page) {
+        return null
+      }
+
+      const shared = await nameSharedVisit(runtime, page.visit)
+      return composeActivityTimeline(runtime, { ...shared, page }, new Date())
+    },
+
+    async connections(query) {
+      assertObservable()
+      return readActivityConnections(runtime, service, query, new Date())
+    },
+  }
+}
+
+export function createActivityCaptureRuntime(
+  runtime: SixbRuntimeContext,
+  service: ActivityService
+): ActivityCaptureRuntime {
+  return {
+    captureOptions() {
+      captureSource(runtime)
+      return service.captureOptions
+    },
+
+    async capture(events) {
+      return service.capture(captureSource(runtime), events)
+    },
+  }
+}
+
+const activityCaptureKey: unique symbol = Symbol("sixb.activityCapture")
+
+interface ActivityCaptureOwner {
+  readonly [activityCaptureKey]?: ActivityCaptureRuntime
+}
+
+export function registerActivityCaptureRuntime(
+  owner: object,
+  capture: ActivityCaptureRuntime
+): void {
+  Object.defineProperty(owner, activityCaptureKey, {
+    configurable: false,
+    enumerable: false,
+    value: capture,
+    writable: false,
+  })
+}
+
+/** The recording side of a bound SDK, such as a request's. */
+export function getActivityCaptureRuntime(owner: object): ActivityCaptureRuntime {
+  const capture = (owner as ActivityCaptureOwner)[activityCaptureKey]
+  if (!capture) {
+    throw new Error("[Sixb] Activity capture is not registered for this execution.")
+  }
+  return capture
+}
+
+/**
+ * The session the batch came through, from verified authorization only. A browser never names an
+ * actor, and an access token or a trusted primitive is not a visit.
+ */
+function captureSource(runtime: SixbRuntimeContext): ActivitySource {
+  const ref = getAuthorizationRef(runtime.runtimeAuthorization)
+
+  if (
+    ref.type === "principal" &&
+    ref.principal.type === "user" &&
+    ref.credential?.type === "session"
+  ) {
+    return {
+      actor: { type: "user", userId: ref.principal.id },
+      sessionId: ref.credential.id,
+    }
+  }
+
+  if (ref.type === "delegated") {
+    return {
+      actor: { type: "share", grantId: ref.delegation.grantId },
+      sessionId: ref.delegation.sessionId,
+    }
+  }
+
+  throw new AuthorizationError(
+    "activity.capture",
+    "[Sixb] Activity is recorded only for a signed-in user's session or a shared link's session."
+  )
+}
+
+async function mapInChunks<T, R>(
+  items: readonly T[],
+  size: number,
+  map: (item: T) => Promise<R>
+): Promise<R[]> {
+  const results: R[] = []
+  for (let start = 0; start < items.length; start += size) {
+    const chunk = await Promise.all(items.slice(start, start + size).map(map))
+    results.push(...chunk)
+  }
+  return results
+}