@sixb/core 0.1.20 → 0.1.22

package/src/auth/member-events.ts

@@ -0,0 +1,114 @@
+import type { EventDraft, PropertyChange, UserProfileUpdatedEvent } from "../events/types"
+import type { CompleteSignInResult, InvitationRecord, UserRecord } from "../storage/auth"
+import { toUserProfile } from "../users/execution"
+import type { AuthenticatedUserRequestSession } from "./types"
+
+type ProfileChanges = UserProfileUpdatedEvent["payload"]["changes"]
+
+/**
+ * What a completed sign-in tells the project: a new member, or the profile their identity provider
+ * changed. A sign-in that changed nothing tells nothing.
+ */
+export function signInEvents(result: CompleteSignInResult): readonly EventDraft[] {
+  const user = toUserProfile(result.user)
+
+  if (result.previousUser === null) {
+    return [
+      {
+        type: "user.joined",
+        payload: {
+          user,
+          ...(result.invitation ? { invitationId: result.invitation.id } : {}),
+        },
+        idempotencyKey: `user.joined:${user.id}`,
+      },
+    ]
+  }
+
+  const changes = profileChanges(result.previousUser, result.user)
+  if (!hasChanges(changes)) return []
+
+  return [{ type: "user.profile.updated", payload: { user, changes } }]
+}
+
+/** A member edited their own profile. Saving the values it already had tells nothing. */
+export function profileUpdatedEvents(
+  caller: AuthenticatedUserRequestSession,
+  previousUser: UserRecord,
+  user: UserRecord
+): readonly EventDraft[] {
+  const changes = profileChanges(previousUser, user)
+  if (!hasChanges(changes)) return []
+
+  return [
+    {
+      type: "user.profile.updated",
+      payload: { user: toUserProfile(user), changes, requestedBy: requester(caller) },
+    },
+  ]
+}
+
+export function statusChangedEvents(
+  caller: AuthenticatedUserRequestSession,
+  previousUser: UserRecord,
+  user: UserRecord
+): readonly EventDraft[] {
+  if (previousUser.status === user.status) return []
+
+  return [
+    {
+      type: user.status === "suspended" ? "user.suspended" : "user.reactivated",
+      payload: { user: toUserProfile(user), requestedBy: requester(caller) },
+    },
+  ]
+}
+
+export function invitedEvents(
+  caller: AuthenticatedUserRequestSession,
+  invitation: InvitationRecord
+): readonly EventDraft[] {
+  return [
+    {
+      type: "user.invited",
+      payload: {
+        invitationId: invitation.id,
+        email: invitation.email,
+        expiresAt: invitation.expiresAt.toISOString(),
+        requestedBy: requester(caller),
+      },
+    },
+  ]
+}
+
+function profileChanges(before: UserRecord, after: UserRecord): ProfileChanges {
+  const displayName = fieldChange(before.displayName, after.displayName)
+  const avatarUrl = fieldChange(before.avatarUrl, after.avatarUrl)
+
+  return {
+    ...(displayName ? { displayName } : {}),
+    ...(avatarUrl ? { avatarUrl } : {}),
+  }
+}
+
+function fieldChange(
+  before: string | undefined,
+  after: string | undefined
+): PropertyChange<string> | undefined {
+  if (after === undefined) {
+    return before === undefined ? undefined : { operation: "cleared", before, after: null }
+  }
+
+  if (before === undefined) return { operation: "created", after }
+  if (before === after) return undefined
+
+  return { operation: "updated", before, after }
+}
+
+function hasChanges(changes: ProfileChanges): boolean {
+  return changes.displayName !== undefined || changes.avatarUrl !== undefined
+}
+
+// Only the principal: the session behind it is not part of the event.
+function requester(caller: AuthenticatedUserRequestSession) {
+  return { type: caller.principal.type, id: caller.principal.id }
+}

package/src/auth/profile.ts

@@ -0,0 +1,118 @@
+import { AuthRuntimeError } from "./errors"
+import type { UpdateOwnProfileInput } from "./types"
+
+const MAX_DISPLAY_NAME_LENGTH = 100
+const MAX_AVATAR_URL_LENGTH = 2048
+
+// What a name must not carry: control characters, unpaired surrogates, bidirectional overrides and
+// isolates, and line or paragraph separators. Other format characters stay, such as the zero-width
+// joiner emoji are built with.
+const FORBIDDEN_NAME_CHARACTERS = /[\p{Cc}\p{Cs}\u202A-\u202E\u2066-\u2069\u2028\u2029]/u
+const VISIBLE_CHARACTER = /[^\p{Z}\p{Cf}]/u
+
+// Plain http only reaches a picture served by the developer's own machine.
+const LOOPBACK_HOSTS: ReadonlySet<string> = new Set(["localhost", "127.0.0.1", "[::1]"])
+
+/** Validate the changes a person makes to their own profile. An empty value clears the field. */
+export function normalizeProfileChanges(input: UpdateOwnProfileInput): UpdateOwnProfileInput {
+  if (input.displayName === undefined && input.avatarUrl === undefined) {
+    throw new AuthRuntimeError(
+      "invalid_auth_input",
+      "[Sixb] A profile update needs displayName or avatarUrl."
+    )
+  }
+
+  const changes: { displayName?: string | null; avatarUrl?: string | null } = {}
+  if (input.displayName !== undefined) {
+    changes.displayName =
+      input.displayName === null ? null : normalizeDisplayName(input.displayName)
+  }
+  if (input.avatarUrl !== undefined) {
+    changes.avatarUrl = input.avatarUrl === null ? null : normalizeAvatarUrl(input.avatarUrl)
+  }
+
+  return changes
+}
+
+/**
+ * A name a sign-in supplies, such as one an identity provider sent, held to the rules a person's own
+ * name follows. A value that breaks them counts as not sent, so it never makes a sign-in fail.
+ */
+export function signInDisplayName(value: unknown): string | undefined {
+  const name = typeof value === "string" ? value.trim() : ""
+  return name && displayNameProblem(name) === null ? name : undefined
+}
+
+/** A picture a sign-in supplies, treated as {@link signInDisplayName} treats a name. */
+export function signInAvatarUrl(value: unknown): string | undefined {
+  return typeof value === "string" ? (canonicalAvatarUrl(value.trim()) ?? undefined) : undefined
+}
+
+function normalizeDisplayName(value: string): string | null {
+  const name = value.trim()
+  if (!name) {
+    return null
+  }
+
+  const problem = displayNameProblem(name)
+  if (problem) {
+    throw new AuthRuntimeError("invalid_auth_input", problem)
+  }
+
+  return name
+}
+
+function normalizeAvatarUrl(value: string): string | null {
+  const url = value.trim()
+  if (!url) {
+    return null
+  }
+
+  const canonical = canonicalAvatarUrl(url)
+  if (!canonical) {
+    throw new AuthRuntimeError(
+      "invalid_auth_input",
+      `[Sixb] An avatar URL must be an https URL of at most ${MAX_AVATAR_URL_LENGTH} characters, without a user name or password.`
+    )
+  }
+
+  return canonical
+}
+
+// Why a trimmed, non-empty name cannot be used, or null when it can. The limit counts code points,
+// so an emoji is one character. A code point is at most two UTF-16 units, so a string longer than
+// twice the limit is refused before it is split, which an unauthenticated sign-in could make costly.
+function displayNameProblem(name: string): string | null {
+  if (name.length > MAX_DISPLAY_NAME_LENGTH * 2 || [...name].length > MAX_DISPLAY_NAME_LENGTH) {
+    return `[Sixb] A display name can be at most ${MAX_DISPLAY_NAME_LENGTH} characters.`
+  }
+
+  if (FORBIDDEN_NAME_CHARACTERS.test(name)) {
+    return "[Sixb] A display name cannot contain control, bidirectional or line separator characters."
+  }
+
+  if (!VISIBLE_CHARACTER.test(name)) {
+    return "[Sixb] A display name needs at least one visible character."
+  }
+
+  return null
+}
+
+// The app loads pictures over https only, so that is all a profile keeps, written as the browser
+// would resolve it.
+function canonicalAvatarUrl(value: string): string | null {
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    return null
+  }
+
+  const secure =
+    url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname))
+  if (!secure || url.username || url.password || url.href.length > MAX_AVATAR_URL_LENGTH) {
+    return null
+  }
+
+  return url.href
+}

package/src/auth/runtime.ts

@@ -1,5 +1,7 @@
 import { randomUUID } from "node:crypto"
 import { type AuthorizationContext, resolveAuthorizationContext } from "../authorization"
+import type { DomainEventLog } from "../events/service"
+import type { EventDraft } from "../events/types"
 import {
   canPerformMembershipOperation,
   type GroupReference,
@@ -14,7 +16,7 @@ import {
   type AccessTokenRecord,
   type AuthStorage,
   AuthStorageError,
-  type CompleteDeviceAuthorizationInput,
+  type CreateAuthSessionInput,
   type GroupMembershipRecord,
   type InvitationRecord,
   type ServiceAccountGroupMembershipRecord,
@@ -23,6 +25,7 @@ import {
   type UserRecord,
 } from "../storage/auth"
 import { paginate } from "../storage/pagination"
+import { toUserProfile } from "../users/execution"
 import {
   createAccessTokenCredential,
   getBearerAccessTokenValue,
@@ -32,6 +35,13 @@ import {
 import { getRequestClientAddress } from "./client-address"
 import { getCookie, type ResolvedAuthCookieOptions } from "./cookies"
 import { AuthRuntimeError } from "./errors"
+import {
+  invitedEvents,
+  profileUpdatedEvents,
+  signInEvents,
+  statusChangedEvents,
+} from "./member-events"
+import { normalizeProfileChanges, signInDisplayName } from "./profile"
 import { SessionCache } from "./session-cache"
 import {
   type BearerSessionTokens,
@@ -76,8 +86,14 @@ import type {
   ListServiceAccountAccessTokensInput,
   ListServiceAccountAccessTokensResult,
   ListServiceAccountsResult,
+  MagicLinkCallbackInput,
+  MagicLinkCallbackResult,
   MemberSummary,
   MembershipCapabilities,
+  OidcCallbackInput,
+  OidcCallbackResult,
+  OwnProfile,
+  ProfileField,
   ReactivateMemberInput,
   ReactivateMemberResult,
   ResolvedAuthConfig,
@@ -93,10 +109,13 @@ import type {
   UnauthenticatedAuthSession,
   UpdateMemberGroupsInput,
   UpdateMemberGroupsResult,
+  UpdateOwnProfileInput,
 } from "./types"
 import {
   assertNonEmpty,
   isInvitationDeliveryAuthStrategy,
+  isMagicLinkAuthStrategy,
+  isOidcAuthStrategy,
   normalizePagination,
   resolveAuthConfig,
   resolveInvitationExpiresAt,
@@ -122,11 +141,15 @@ const BEARER_ACCESS_TOKEN_TTL_MS = 15 * 60_000
 // response was lost can retry. Later, it means a copy is in use and the session is revoked.
 const REFRESH_REUSE_GRACE_MS = 60_000
 
+const PROFILE_FIELDS: readonly ProfileField[] = ["displayName", "avatarUrl"]
+
 export interface AuthRuntimeOptions {
   readonly projectId: string
   readonly storage: Storage
   readonly security: SecurityDefinitionCatalog
   readonly config?: SixbAuthConfig
+  /** Where member events go: joined, suspended, reactivated, invited, profile updated. */
+  readonly events: DomainEventLog
 }
 
 export class AuthRuntime {
@@ -135,11 +158,13 @@ export class AuthRuntime {
   private readonly security: SecurityDefinitionCatalog
   private readonly config: ResolvedAuthConfig
   private readonly sessionCache: SessionCache | null
+  private readonly events: DomainEventLog
 
   constructor(options: AuthRuntimeOptions) {
     this.projectId = options.projectId
     this.storage = options.storage
     this.security = options.security
+    this.events = options.events
     this.config = resolveAuthConfig(options.config)
     this.sessionCache =
       this.config.session.cacheTtlMs > 0 ? new SessionCache(this.config.session.cacheTtlMs) : null
@@ -389,7 +414,9 @@ export class AuthRuntime {
     readonly clientName: string
     readonly now: Date
   }): {
-    readonly session: CompleteDeviceAuthorizationInput["session"]
+    readonly session: CreateAuthSessionInput & {
+      readonly bearer: NonNullable<CreateAuthSessionInput["bearer"]>
+    }
     readonly tokens: BearerSessionTokens
   } {
     const sessionId = `ses_${randomUUID()}`
@@ -603,6 +630,65 @@ export class AuthRuntime {
     }
   }
 
+  /**
+   * Finish a magic-link sign-in: consume the link and start the session the server minted. Every
+   * sign-in goes through the runtime, so what follows one is decided here and not in each route.
+   * A name that breaks the profile rules is dropped: it never makes the sign-in fail.
+   */
+  async completeMagicLinkSignIn(
+    input: Pick<MagicLinkCallbackInput, "magicLinkId" | "token" | "session" | "displayName">
+  ): Promise<MagicLinkCallbackResult> {
+    const strategy = this.getStrategy()
+    if (!isMagicLinkAuthStrategy(strategy)) {
+      throw new AuthRuntimeError(
+        "invalid_auth_config",
+        "[Sixb] The active auth strategy does not support magic-link sign-in."
+      )
+    }
+
+    const result = await strategy.completeMagicLinkSignIn({
+      projectId: this.projectId,
+      authStorage: this.requireAuthStorage(),
+      magicLinkId: input.magicLinkId,
+      token: input.token,
+      session: input.session,
+      displayName: signInDisplayName(input.displayName),
+    })
+
+    await this.emitMemberEvents(signInEvents(result))
+
+    return result
+  }
+
+  /** Finish an OIDC sign-in from the provider's callback and start the session the server minted. */
+  async completeOidcSignIn(
+    input: Pick<OidcCallbackInput, "requestUrl" | "requestOrigin" | "session">
+  ): Promise<OidcCallbackResult> {
+    const strategy = this.getStrategy()
+    if (!isOidcAuthStrategy(strategy)) {
+      throw new AuthRuntimeError(
+        "invalid_auth_config",
+        "[Sixb] The active auth strategy does not support OIDC sign-in."
+      )
+    }
+
+    const result = await strategy.completeOidcSignIn({
+      projectId: this.projectId,
+      authStorage: this.requireAuthStorage(),
+      requestUrl: input.requestUrl,
+      requestOrigin: input.requestOrigin,
+      session: input.session,
+    })
+
+    // The provider may have changed the person's name, picture or directory groups, which their
+    // other sessions hold in the cache.
+    this.sessionCache?.invalidateUser(result.user.id)
+
+    await this.emitMemberEvents(signInEvents(result))
+
+    return result
+  }
+
   /**
    * Resolve a caller's authorization context. Grants resolve eagerly
    * (`groups -> roles -> grants`, subtype-expanded), so checks against it are synchronous.
@@ -1114,7 +1200,7 @@ export class AuthRuntime {
       )
     }
 
-    const suspended = await storage.suspendUserAndRevokeSessions({
+    const { user: suspended, previousUser } = await storage.suspendUserAndRevokeSessions({
       projectId: this.projectId,
       userId: user.id,
       suspendedAt: new Date(),
@@ -1123,6 +1209,8 @@ export class AuthRuntime {
     // user stops authenticating immediately.
     this.sessionCache?.invalidateUser(user.id)
 
+    await this.emitMemberEvents(statusChangedEvents(caller, previousUser, suspended))
+
     return { user: suspended, groupIds, managedGroupIds }
   }
 
@@ -1141,16 +1229,100 @@ export class AuthRuntime {
     )
 
     // Reactivation restores access but not sessions; the user signs in again.
-    const reactivated = await storage.users.updateStatus({
+    const { user: reactivated, previousUser } = await storage.users.updateStatus({
       projectId: this.projectId,
       id: user.id,
       status: "active",
       updatedAt: new Date(),
     })
 
+    await this.emitMemberEvents(statusChangedEvents(caller, previousUser, reactivated))
+
     return { user: reactivated, groupIds, managedGroupIds }
   }
 
+  /** The caller's own profile, and which of its fields their identity provider manages. */
+  async getProfile(caller: AuthenticatedUserRequestSession): Promise<OwnProfile> {
+    const storage = this.requireAuthStorage()
+    const user = await storage.users.getById({ projectId: this.projectId, id: caller.user.id })
+    if (!user) {
+      throw new AuthStorageError(
+        "missing_user",
+        `[Sixb] User '${caller.user.id}' not found for project '${this.projectId}'.`
+      )
+    }
+
+    return {
+      profile: toUserProfile(user),
+      managedFields: await this.managedProfileFields(storage, user.id),
+    }
+  }
+
+  /**
+   * Change the caller's own name or picture. A field their identity provider manages is refused,
+   * because the next sign-in would overwrite it.
+   */
+  async updateProfile(
+    caller: AuthenticatedUserRequestSession,
+    input: UpdateOwnProfileInput
+  ): Promise<OwnProfile> {
+    const changes = normalizeProfileChanges(input)
+    const storage = this.requireAuthStorage()
+    const managedFields = await this.managedProfileFields(storage, caller.user.id)
+
+    const managedChanges = managedFields.filter((field) => changes[field] !== undefined)
+    if (managedChanges.length > 0) {
+      throw new AuthRuntimeError(
+        "authorization_denied",
+        `[Sixb] Your identity provider manages ${managedChanges.join(" and ")}. ` +
+          `Change ${managedChanges.length > 1 ? "them" : "it"} there.`
+      )
+    }
+
+    const { user, previousUser } = await storage.users.updateProfile({
+      projectId: this.projectId,
+      id: caller.user.id,
+      ...changes,
+      updatedAt: new Date(),
+    })
+
+    // Every session of this person caches their profile; drop them so all show the change.
+    const changed =
+      user.displayName !== previousUser.displayName || user.avatarUrl !== previousUser.avatarUrl
+    if (changed) {
+      this.sessionCache?.invalidateUser(user.id)
+    }
+
+    await this.emitMemberEvents(profileUpdatedEvents(caller, previousUser, user))
+
+    return { profile: toUserProfile(user), managedFields }
+  }
+
+  // The fields the active strategy's provider sets at sign-in, through any of the person's
+  // identities with it. Identities from a strategy the project no longer uses manage nothing.
+  private async managedProfileFields(
+    storage: AuthStorage,
+    userId: string
+  ): Promise<readonly ProfileField[]> {
+    const strategy = this.getStrategy()
+    if (!strategy?.providerProfileFields) {
+      return []
+    }
+
+    const identities = await storage.identities.listForUser({ projectId: this.projectId, userId })
+    const managed = new Set<ProfileField>()
+    for (const identity of identities) {
+      if (identity.strategyId !== strategy.id) {
+        continue
+      }
+      for (const field of strategy.providerProfileFields(identity)) {
+        managed.add(field)
+      }
+    }
+
+    return PROFILE_FIELDS.filter((field) => managed.has(field))
+  }
+
   /** The caller's active sessions, most recently active first. */
   async listSessions(caller: AuthenticatedUserRequestSession): Promise<readonly SessionRecord[]> {
     return this.requireAuthStorage().sessions.listActiveByUserId({
@@ -1308,15 +1480,13 @@ export class AuthRuntime {
       ...(input.revealLink && delivery.link ? { link: delivery.link } : {}),
     }
 
-    if (delivery.status === "not_supported") {
-      return { invitation, delivery }
-    }
-
-    if (delivery.status !== "sent") {
+    if (delivery.status !== "sent" && delivery.status !== "not_supported") {
       await this.revokeInvitationAfterDeliveryFailure(authStorage, invitation, now)
       throw this.createInvitationDeliveryError(delivery.status)
     }
 
+    await this.emitMemberEvents(invitedEvents(caller, invitation))
+
     return { invitation, delivery }
   }
 
@@ -1381,6 +1551,17 @@ export class AuthRuntime {
     }
   }
 
+  /**
+   * Member events follow the auth write that caused them, which has already committed. Auth
+   * storage keeps no outbox, so an event the broker refuses is reported through `onError` and lost:
+   * delivery is at most once.
+   */
+  private async emitMemberEvents(events: readonly EventDraft[]): Promise<void> {
+    if (events.length === 0) return
+
+    await this.events.emit({ events }, { source: "Sixb" })
+  }
+
   private requireAuthStorage() {
     if (!this.storage.auth) {
       throw new AuthRuntimeError(

package/src/auth/strategy.ts

@@ -7,8 +7,10 @@
  * entry plus the storage contracts from `@sixb/core/storage`.
  */
 
+export type { UserIdentityRecord } from "../storage/auth"
 export type { SignInRefusalReason } from "./errors"
 export { SignInRefusedError } from "./errors"
+export { signInAvatarUrl, signInDisplayName } from "./profile"
 export type {
   AuthEmailDeliveryStatus,
   AuthInvitationRecipientInput,
@@ -40,6 +42,7 @@ export type {
   OidcCallbackResult,
   OidcStartSignInInput,
   OidcStartSignInResult,
+  ProfileField,
   RevealedInvitationLink,
 } from "./types"
 export {

package/src/auth/types.ts

@@ -9,14 +9,19 @@ import type {
   ServiceAccountGroupMembershipRecord,
   ServiceAccountRecord,
   SessionRecord,
+  UserIdentityRecord,
   UserRecord,
 } from "../storage/auth"
+import type { UserProfile } from "../users"
 
 export type Principal =
   | { readonly type: "user"; readonly id: string }
   | { readonly type: "serviceAccount"; readonly id: string }
   | { readonly type: "system"; readonly id: string }
 
+/** A signed-in person: the only principal who talks to the Agent or takes part in a thread. */
+export type UserPrincipal = Extract<Principal, { readonly type: "user" }>
+
 /**
  * The canonical principal for system-originated writes (runs triggered without a caller,
  * worker fallbacks, decode-time defaults). Import this everywhere instead of inlining a
@@ -31,12 +36,20 @@ export function principalsEqual(left: Principal, right: Principal): boolean {
 
 export type AuthStrategyKind = "magicLink" | "oidc" | "dev" | "disabled"
 
+/** A profile field an identity provider can own. */
+export type ProfileField = "displayName" | "avatarUrl"
+
 export interface AuthStrategy {
   readonly id: string
   readonly kind: AuthStrategyKind
   readonly developmentOnly?: boolean
   readonly disabled?: boolean
   readonly allowDisabledInProduction?: boolean
+  /**
+   * The profile fields this strategy's provider sets at every sign-in of the person behind
+   * `identity`, so people cannot edit them in Sixb. Omitted, the strategy manages none.
+   */
+  providerProfileFields?(identity: UserIdentityRecord): readonly ProfileField[]
 }
 
 export interface InvitationRecipientInput {
@@ -133,6 +146,8 @@ export interface MagicLinkCallbackInput {
   readonly magicLinkId: string
   readonly token: string
   readonly session: CompleteAuthSessionInput
+  /** The name the person gave. Used only when this sign-in creates their account. */
+  readonly displayName?: string
   readonly now?: Date
 }
 
@@ -150,6 +165,8 @@ export interface MagicLinkPeekInput {
 
 export interface MagicLinkPeekResult {
   readonly email: string
+  /** The link will create an account, so the confirmation page may ask for a name. */
+  readonly firstSignIn?: true
 }
 
 export interface MagicLinkAuthStrategy extends InvitationDeliveryAuthStrategy {
@@ -211,6 +228,8 @@ export interface OidcAuthStrategy extends InvitationDeliveryAuthStrategy {
   readonly bootstrapGroupIds?: readonly string[]
   startOidcSignIn(input: OidcStartSignInInput): Promise<OidcStartSignInResult>
   completeOidcSignIn(input: OidcCallbackInput): Promise<OidcCallbackResult>
+  /** Every OIDC sign-in sets the name and picture the provider sends, so the strategy says which. */
+  providerProfileFields(identity: UserIdentityRecord): readonly ProfileField[]
 }
 
 export interface InviteUserInput {
@@ -371,6 +390,19 @@ export interface ReactivateMemberResult {
   readonly managedGroupIds: readonly string[]
 }
 
+/** The signed-in person's own profile. */
+export interface OwnProfile {
+  readonly profile: UserProfile
+  /** The fields their identity provider sets at sign-in, which they cannot edit here. */
+  readonly managedFields: readonly ProfileField[]
+}
+
+/** Omitted fields stay unchanged, and `null` clears one. */
+export interface UpdateOwnProfileInput {
+  readonly displayName?: string | null
+  readonly avatarUrl?: string | null
+}
+
 /** `"session"` reads only the cookie; `"any"` reads a bearer access token, else the cookie. */
 export type AuthCredentialSource = "session" | "any"