create-safest-tools 0.2.0

package/template/src/report-operator-accounts.ts

@@ -0,0 +1,810 @@
+import { canonicalJson } from "./audit";
+import { ApiError } from "./report-http";
+import type { OperatorRole, OperatorSession } from "./report-types";
+
+const encoder = new TextEncoder();
+const SESSION_HOURS = 12;
+const PROFILE_PICTURE_MAX_BYTES = 2 * 1024 * 1024;
+const assignableRoles = new Set<OperatorRole>(["administrator", "workflow_author", "reviewer", "appeal_reviewer", "quality_reviewer", "operations", "auditor"]);
+
+interface OperatorUserRow {
+  id: string;
+  email: string;
+  display_name: string;
+  avatar_url: string | null;
+  avatar_object_key: string | null;
+  avatar_uploaded_at: string | null;
+  roles_json: string;
+  status: "active" | "suspended";
+  accepted_at: string | null;
+  last_login_at: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+interface AccountSessionRow extends OperatorUserRow {
+  session_id: string;
+  csrf_hash: string;
+  expires_at: string;
+  last_seen_at: string;
+}
+
+interface InvitationRow {
+  id: string;
+  email: string;
+  role: OperatorRole;
+  status: "pending" | "accepted" | "revoked";
+  invited_by: string;
+  accepted_by: string | null;
+  expires_at: string;
+  accepted_at: string | null;
+  revoked_at: string | null;
+  created_at: string;
+}
+
+interface OperatorInvitationDelivery {
+  id: string;
+  email: string;
+  role: OperatorRole;
+  status: "pending";
+  expiresAt: string;
+  inviteUrl: string;
+}
+
+interface IssuedOperatorSession {
+  session: OperatorSession;
+  sessionToken: string;
+  csrfToken: string;
+  expiresAt: string;
+}
+
+function bytesToBase64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+
+function base64UrlToBytes(value: string): Uint8Array {
+  const normalized = value.replaceAll("-", "+").replaceAll("_", "/");
+  const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+  const binary = atob(padded);
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+function randomToken(byteLength = 32): string {
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+  return bytesToBase64Url(bytes);
+}
+
+async function sha256(value: string): Promise<string> {
+  return bytesToBase64Url(new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(value))));
+}
+
+function constantTimeEqual(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.byteLength !== right.byteLength) return false;
+  let difference = 0;
+  for (let index = 0; index < left.byteLength; index += 1) difference |= left[index]! ^ right[index]!;
+  return difference === 0;
+}
+
+function cleanEmail(value: unknown): string {
+  if (typeof value !== "string") throw new ApiError(400, "invalid_email", "Enter a valid email address.", { field: "email" });
+  const email = value.trim().toLowerCase();
+  if (email.length > 254 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(email)) {
+    throw new ApiError(400, "invalid_email", "Enter a valid email address.", { field: "email" });
+  }
+  return email;
+}
+
+function cleanDisplayName(value: unknown, fallback?: string): string {
+  const displayName = typeof value === "string" ? value.trim() : "";
+  const result = displayName || fallback || "";
+  if (!result || result.length > 100 || /[\u0000-\u001f\u007f]/u.test(result)) {
+    throw new ApiError(400, "invalid_display_name", "Display name must contain 1 to 100 characters.", { field: "display_name" });
+  }
+  return result;
+}
+
+function cleanAvatarUrl(value: unknown): string | null {
+  if (value === undefined || value === null || value === "") return null;
+  if (typeof value !== "string" || value.length > 2_048) throw new ApiError(400, "invalid_avatar_url", "Profile picture URL is invalid.");
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "https:" || url.username || url.password) throw new Error("invalid");
+    return url.href;
+  } catch {
+    throw new ApiError(400, "invalid_avatar_url", "Profile picture URL must be an HTTPS URL.");
+  }
+}
+
+function parseRoles(value: string): OperatorRole[] {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((role): role is OperatorRole => typeof role === "string"
+      && ["owner", "administrator", "workflow_author", "reviewer", "appeal_reviewer", "quality_reviewer", "operations", "auditor"].includes(role));
+  } catch {
+    return [];
+  }
+}
+
+export function permissionsForRoles(roles: OperatorRole[]): OperatorSession["permissions"] {
+  const owner = roles.includes("owner");
+  const administrator = roles.includes("administrator");
+  const reviewer = roles.includes("reviewer");
+  const appealReviewer = roles.includes("appeal_reviewer");
+  const workflowAuthor = roles.includes("workflow_author");
+  const qualityReviewer = roles.includes("quality_reviewer");
+  const operations = roles.includes("operations");
+  const auditor = roles.includes("auditor");
+  const configure = owner || administrator;
+  const read = configure || reviewer || appealReviewer || workflowAuthor || qualityReviewer || operations || auditor;
+  return {
+    readReports: read,
+    readEvidence: read,
+    readSensitiveEvidence: configure || reviewer || appealReviewer,
+    manageEvidence: configure,
+    claimReports: configure || reviewer,
+    reviewTasks: configure || reviewer || appealReviewer || qualityReviewer || operations,
+    assignTasks: configure,
+    messageReporters: configure || reviewer || appealReviewer,
+    messageParticipants: configure || reviewer || appealReviewer,
+    decideReports: configure || reviewer,
+    reassignReports: configure || reviewer,
+    approveActions: configure || reviewer,
+    operateActions: configure || operations,
+    reviewAppeals: configure || appealReviewer,
+    decideAppeals: configure || appealReviewer,
+    reviewQuality: configure || reviewer || qualityReviewer,
+    runShadow: configure || workflowAuthor || qualityReviewer,
+    runEnrichments: configure || workflowAuthor || reviewer || qualityReviewer,
+    manageForms: configure,
+    managePolicies: configure,
+    manageTemplates: configure,
+    manageQueues: configure,
+    manageRouting: configure,
+    manageWorkflowPins: configure,
+    manageConnections: configure,
+    publishConnections: configure,
+    manageComponents: configure || workflowAuthor,
+    publishComponents: configure,
+    manageWorkflows: configure || workflowAuthor,
+    publishWorkflows: configure,
+    manageAi: configure,
+    manageBudgets: configure,
+    useAssistant: read,
+    readRuns: read,
+    operateRuns: configure || operations,
+    searchWorkspace: read,
+    readAnalytics: read,
+    readAi: read,
+    readOperations: configure || operations || auditor,
+    operateSystem: configure || operations,
+    manageConfiguration: configure,
+    managePeople: configure,
+    manageInstallation: owner,
+    viewAudit: configure || auditor,
+    exportData: configure || auditor,
+    manageGovernance: configure,
+    manageIntegrations: configure,
+  };
+}
+
+function operatorAvatarUrl(user: OperatorUserRow): string | undefined {
+  if (user.avatar_object_key) {
+    const version = user.avatar_uploaded_at ?? user.updated_at;
+    return `/v1/profile-pictures/${encodeURIComponent(user.id)}?v=${encodeURIComponent(version)}`;
+  }
+  return user.avatar_url ?? undefined;
+}
+
+function operatorSession(
+  user: OperatorUserRow,
+  authorization?: { roles: OperatorRole[]; queueScope: string[] | null; fieldScope: Record<string, string[]> | null },
+  authMethod: OperatorSession["authMethod"] = "cloudflare_access",
+): OperatorSession {
+  const roles = authorization?.roles ?? parseRoles(user.roles_json);
+  const avatarUrl = operatorAvatarUrl(user);
+  return {
+    actor: { type: "operator_user", id: user.id },
+    authMethod,
+    verified: true,
+    displayName: user.display_name,
+    email: user.email,
+    ...(avatarUrl ? { avatarUrl } : {}),
+    roles,
+    permissions: permissionsForRoles(roles),
+    queueScope: authorization?.queueScope ?? null,
+    fieldScope: authorization?.fieldScope ?? null,
+  };
+}
+
+async function operatorAuthorization(db: D1Database, user: OperatorUserRow): Promise<{
+  roles: OperatorRole[];
+  queueScope: string[] | null;
+  fieldScope: Record<string, string[]> | null;
+}> {
+  const baseRoles = parseRoles(user.roles_json);
+  if (baseRoles.includes("owner")) return { roles: baseRoles, queueScope: null, fieldScope: null };
+  const bindings = await db.prepare(`
+    SELECT role, queue_scope_json AS queueScopeJson, field_scope_json AS fieldScopeJson
+    FROM role_bindings
+    WHERE installation_id = 'default' AND principal_type = 'operator_user'
+      AND principal_id = ?1 AND revoked_at IS NULL
+    ORDER BY created_at, id
+  `).bind(user.id).all<{ role: string; queueScopeJson: string; fieldScopeJson: string }>();
+  if (!bindings.results.length) return { roles: baseRoles, queueScope: null, fieldScope: null };
+  const roles = [...new Set(bindings.results.map((binding) => binding.role)
+    .filter((role): role is OperatorRole => ["administrator", "workflow_author", "reviewer", "appeal_reviewer", "quality_reviewer", "operations", "auditor"].includes(role)))];
+  const queueIds = new Set<string>();
+  let globalQueues = false;
+  const mergedFields: Record<string, string[]> = {};
+  let globalFields = false;
+  for (const binding of bindings.results) {
+    try {
+      const parsed = JSON.parse(binding.queueScopeJson) as unknown;
+      if (!Array.isArray(parsed) || parsed.length === 0) globalQueues = true;
+      else for (const queueId of parsed) if (typeof queueId === "string") queueIds.add(queueId);
+    } catch {
+      globalQueues = true;
+    }
+    try {
+      const parsed = JSON.parse(binding.fieldScopeJson) as unknown;
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || Object.keys(parsed).length === 0) globalFields = true;
+      else for (const [resource, fields] of Object.entries(parsed as Record<string, unknown>)) {
+        if (Array.isArray(fields)) mergedFields[resource] = [...new Set([...(mergedFields[resource] ?? []), ...fields.filter((field): field is string => typeof field === "string")])];
+      }
+    } catch {
+      globalFields = true;
+    }
+  }
+  return {
+    roles: roles.length ? roles : baseRoles,
+    queueScope: globalQueues ? null : [...queueIds].sort(),
+    fieldScope: globalFields ? null : mergedFields,
+  };
+}
+
+/**
+ * Resolves a Better Auth identity into Safest Resolve's product authorization model.
+ * A first sign-in may consume the signed invitation admitted by report-better-auth;
+ * returning users are resolved by their immutable, verified email address.
+ */
+export async function resolveBetterAuthOperator(
+  db: D1Database,
+  identity: { email: string; name: string; image?: string | null },
+  invitationId: string | null,
+): Promise<OperatorSession | null> {
+  const email = cleanEmail(identity.email);
+  let user = await db.prepare(`SELECT * FROM operator_users WHERE email = ?1 LIMIT 1`)
+    .bind(email).first<OperatorUserRow>();
+  if (user) {
+    if (user.status !== "active") return null;
+    return operatorSession(user, await operatorAuthorization(db, user), "better_auth");
+  }
+  if (!invitationId) return null;
+  const timestamp = new Date().toISOString();
+  const invitation = await db.prepare(`
+    SELECT id, email, role, status, invited_by, accepted_by, expires_at, accepted_at, revoked_at, created_at
+    FROM operator_invitations
+    WHERE id = ?1 AND status = 'pending' AND expires_at > ?2
+    LIMIT 1
+  `).bind(invitationId, timestamp).first<InvitationRow>();
+  if (!invitation || invitation.email.trim().toLowerCase() !== email) return null;
+  const displayName = cleanDisplayName(identity.name, email.split("@", 1)[0]);
+  const avatarUrl = cleanAvatarUrl(identity.image);
+  user = {
+    id: crypto.randomUUID(),
+    email,
+    display_name: displayName,
+    avatar_url: avatarUrl,
+    avatar_object_key: null,
+    avatar_uploaded_at: null,
+    roles_json: canonicalJson([invitation.role]),
+    status: "active",
+    accepted_at: timestamp,
+    last_login_at: timestamp,
+    created_at: timestamp,
+    updated_at: timestamp,
+  };
+  try {
+    await db.batch([
+      db.prepare(`
+        INSERT INTO operator_users (
+          id, email, display_name, avatar_url, roles_json, status,
+          invited_by, accepted_at, last_login_at, created_at, updated_at
+        ) VALUES (?1, ?2, ?3, ?4, ?5, 'active', ?6, ?7, ?7, ?7, ?7)
+      `).bind(
+        user.id, user.email, user.display_name, user.avatar_url, user.roles_json,
+        invitation.invited_by, timestamp,
+      ),
+      db.prepare(`
+        UPDATE operator_invitations
+        SET status = 'accepted', accepted_by = ?2, accepted_at = ?3
+        WHERE id = ?1 AND status = 'pending' AND expires_at > ?3
+      `).bind(invitation.id, user.id, timestamp),
+      db.prepare(`
+        INSERT INTO role_bindings (
+          id, installation_id, principal_type, principal_id, role,
+          queue_scope_json, field_scope_json, created_by, created_at
+        ) VALUES (?1, 'default', 'operator_user', ?2, ?3, '[]', '{}', ?4, ?5)
+      `).bind(crypto.randomUUID(), user.id, invitation.role, invitation.invited_by, timestamp),
+      auditEvent(db, "operator.invitation_accepted", user.id, "operator_user", user.id, {
+        invitation_id: invitation.id,
+        role: invitation.role,
+        auth_method: "better_auth",
+      }, timestamp),
+    ]);
+  } catch {
+    const raced = await db.prepare(`SELECT * FROM operator_users WHERE email = ?1 AND status = 'active' LIMIT 1`)
+      .bind(email).first<OperatorUserRow>();
+    if (!raced) return null;
+    user = raced;
+  }
+  return operatorSession(user, await operatorAuthorization(db, user), "better_auth");
+}
+
+function cookieMap(request: Request): Map<string, string> {
+  const result = new Map<string, string>();
+  for (const part of (request.headers.get("cookie") ?? "").split(";")) {
+    const separator = part.indexOf("=");
+    if (separator > 0) result.set(part.slice(0, separator).trim(), part.slice(separator + 1).trim());
+  }
+  return result;
+}
+
+function secureRequest(request: Request): boolean {
+  return new URL(request.url).protocol === "https:";
+}
+
+function sessionCookieName(request: Request): string {
+  return secureRequest(request) ? "__Host-safest_infrastructure_session" : "safest_infrastructure_session";
+}
+
+function csrfCookieName(request: Request): string {
+  return secureRequest(request) ? "__Host-safest_csrf" : "safest_csrf";
+}
+
+function cookie(name: string, value: string, request: Request, maxAge: number, httpOnly: boolean): string {
+  return `${name}=${value}; Path=/; Max-Age=${maxAge}; SameSite=Strict${httpOnly ? "; HttpOnly" : ""}${secureRequest(request) ? "; Secure" : ""}`;
+}
+
+export function appendOperatorSessionCookies(response: Response, issued: IssuedOperatorSession, request: Request): Response {
+  const headers = new Headers(response.headers);
+  const maxAge = Math.max(0, Math.floor((Date.parse(issued.expiresAt) - Date.now()) / 1_000));
+  headers.append("set-cookie", cookie(sessionCookieName(request), issued.sessionToken, request, maxAge, true));
+  headers.append("set-cookie", cookie(csrfCookieName(request), issued.csrfToken, request, maxAge, false));
+  return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}
+
+export function clearOperatorSessionCookies(response: Response, request: Request): Response {
+  const headers = new Headers(response.headers);
+  headers.append("set-cookie", cookie(sessionCookieName(request), "", request, 0, true));
+  headers.append("set-cookie", cookie(csrfCookieName(request), "", request, 0, false));
+  return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}
+
+async function issueSession(db: D1Database, user: OperatorUserRow): Promise<IssuedOperatorSession> {
+  const createdAt = new Date().toISOString();
+  const expiresAt = new Date(Date.parse(createdAt) + SESSION_HOURS * 3_600_000).toISOString();
+  const sessionToken = randomToken();
+  const csrfToken = randomToken();
+  await db.prepare(`
+    INSERT INTO infrastructure_owner_sessions (id, user_id, token_hash, csrf_hash, expires_at, last_seen_at, created_at)
+    VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?6)
+  `).bind(crypto.randomUUID(), user.id, await sha256(sessionToken), await sha256(csrfToken), expiresAt, createdAt).run();
+  return { session: operatorSession(user), sessionToken, csrfToken, expiresAt };
+}
+
+export async function resolveOperatorAccountSession(
+  request: Request,
+  db: D1Database,
+): Promise<{ session: OperatorSession; csrfHash: string; sessionId: string } | null> {
+  const rawToken = cookieMap(request).get(sessionCookieName(request));
+  if (!rawToken || rawToken.length > 200) return null;
+  const now = new Date().toISOString();
+  const row = await db.prepare(`
+    SELECT u.*, s.id AS session_id, s.csrf_hash, s.expires_at, s.last_seen_at
+    FROM infrastructure_owner_sessions s JOIN operator_users u ON u.id = s.user_id
+    WHERE s.token_hash = ?1 AND s.revoked_at IS NULL AND s.expires_at > ?2 AND u.status = 'active'
+  `).bind(await sha256(rawToken), now).first<AccountSessionRow>();
+  if (!row) return null;
+  if (Date.parse(row.last_seen_at) < Date.now() - 15 * 60_000) {
+    await db.prepare(`UPDATE infrastructure_owner_sessions SET last_seen_at = ?2 WHERE id = ?1 AND revoked_at IS NULL`).bind(row.session_id, now).run();
+  }
+  return { session: operatorSession(row, await operatorAuthorization(db, row)), csrfHash: row.csrf_hash, sessionId: row.session_id };
+}
+
+export async function verifyOperatorCsrf(request: Request, csrfHash: string): Promise<void> {
+  if (["GET", "HEAD", "OPTIONS"].includes(request.method)) return;
+  const cookies = cookieMap(request);
+  const cookieToken = cookies.get(csrfCookieName(request));
+  const headerToken = request.headers.get("x-csrf-token");
+  if (!cookieToken || !headerToken || cookieToken !== headerToken || !constantTimeEqual(
+    base64UrlToBytes(await sha256(headerToken)),
+    base64UrlToBytes(csrfHash),
+  )) throw new ApiError(403, "csrf_validation_failed", "Refresh the page and try again.");
+}
+
+export async function bootstrapOwner(
+  db: D1Database,
+  identity: { email: string; displayName: string; avatarUrl?: string },
+): Promise<IssuedOperatorSession> {
+  const email = cleanEmail(identity.email);
+  const displayName = cleanDisplayName(identity.displayName, email.split("@", 1)[0]);
+  const avatarUrl = cleanAvatarUrl(identity.avatarUrl);
+  const timestamp = new Date().toISOString();
+  let user = await db.prepare(`SELECT * FROM operator_users WHERE email = ?1`).bind(email).first<OperatorUserRow>();
+  if (user) {
+    await db.prepare(`
+      UPDATE operator_users SET display_name = ?2, avatar_url = ?3, roles_json = '["owner"]', status = 'active', updated_at = ?4
+      WHERE id = ?1
+    `).bind(user.id, displayName, avatarUrl, timestamp).run();
+    user = { ...user, display_name: displayName, avatar_url: avatarUrl, roles_json: '["owner"]', status: "active", updated_at: timestamp };
+  } else {
+    user = {
+      id: crypto.randomUUID(), email, display_name: displayName, avatar_url: avatarUrl,
+      avatar_object_key: null, avatar_uploaded_at: null,
+      roles_json: '["owner"]', status: "active", accepted_at: timestamp,
+      last_login_at: timestamp, created_at: timestamp, updated_at: timestamp,
+    };
+    await db.prepare(`
+      INSERT INTO operator_users (
+        id, email, display_name, avatar_url, roles_json, status, accepted_at, last_login_at, created_at, updated_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, 'active', ?6, ?6, ?6, ?6)
+    `).bind(user.id, user.email, user.display_name, user.avatar_url, user.roles_json, timestamp).run();
+  }
+  await db.prepare(`UPDATE operator_users SET last_login_at = ?2 WHERE id = ?1`).bind(user.id, timestamp).run();
+  await auditEvent(db, "operator.owner_bootstrap", user.id, "cloudflare_access", user.id, { email }, timestamp).run();
+  return issueSession(db, user);
+}
+
+function auditEvent(
+  db: D1Database,
+  action: string,
+  actorId: string,
+  actorType: OperatorSession["actor"]["type"] | "system",
+  targetId: string,
+  details: unknown,
+  createdAt: string,
+): D1PreparedStatement {
+  return db.prepare(`
+    INSERT INTO audit_events (
+      id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at
+    ) VALUES (?1, ?1, ?2, ?3, ?4, 'operator_user', ?5, ?6, ?7)
+  `).bind(crypto.randomUUID(), action, actorType, actorId, targetId, canonicalJson(details), createdAt);
+}
+
+function roleFromInput(value: unknown): OperatorRole {
+  if (typeof value !== "string" || !assignableRoles.has(value as OperatorRole)) {
+    throw new ApiError(400, "invalid_operator_role", "Choose a valid team role.", { field: "role" });
+  }
+  return value as OperatorRole;
+}
+
+export async function createOperatorInvitation(
+  db: D1Database,
+  actor: OperatorSession,
+  input: Record<string, unknown>,
+  publicBaseUrl: string,
+): Promise<OperatorInvitationDelivery> {
+  const email = cleanEmail(input.email);
+  const role = roleFromInput(input.role);
+  if (role === "administrator" && !actor.roles.includes("owner")) {
+    throw new ApiError(403, "owner_required", "Only the infrastructure owner can invite an administrator.");
+  }
+  if (!actor.roles.includes("owner") && !actor.roles.includes("administrator")) {
+    throw new ApiError(403, "operator_permission_denied", "Your role cannot invite team members.");
+  }
+  const existing = await db.prepare(`SELECT id, status FROM operator_users WHERE email = ?1`).bind(email)
+    .first<{ id: string; status: "active" | "suspended" }>();
+  if (existing) {
+    throw new ApiError(
+      409,
+      "operator_already_exists",
+      existing.status === "suspended"
+        ? "This person already has a suspended Safest account. Reactivate that account instead of inviting them again."
+        : "This person already has an active Safest account.",
+    );
+  }
+  const timestamp = new Date().toISOString();
+  const expiresAt = new Date(Date.parse(timestamp) + 7 * 86_400_000).toISOString();
+  const rawToken = randomToken();
+  const id = crypto.randomUUID();
+  await db.batch([
+    db.prepare(`UPDATE operator_invitations SET status = 'revoked', revoked_at = ?2 WHERE email = ?1 AND status = 'pending'`).bind(email, timestamp),
+    db.prepare(`
+      INSERT INTO operator_invitations (id, email, role, token_hash, invited_by, expires_at, created_at)
+      VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)
+    `).bind(id, email, role, await sha256(rawToken), actor.actor.id, expiresAt, timestamp),
+    auditEvent(db, "operator.invited", actor.actor.id, actor.actor.type, id, { email, role, expires_at: expiresAt }, timestamp),
+  ]);
+  return {
+    id, email, role, status: "pending", expiresAt,
+    inviteUrl: `${new URL(publicBaseUrl).origin}/#invite=${encodeURIComponent(rawToken)}`,
+  };
+}
+
+export async function listOperatorPeople(db: D1Database): Promise<Record<string, unknown>> {
+  const [users, invitations] = await Promise.all([
+    db.prepare(`
+      SELECT id, email, display_name, avatar_url, avatar_object_key, avatar_uploaded_at,
+        roles_json, status, accepted_at, last_login_at, created_at, updated_at
+      FROM operator_users ORDER BY CASE WHEN roles_json LIKE '%owner%' THEN 0 WHEN roles_json LIKE '%administrator%' THEN 1 ELSE 2 END, display_name, email
+    `).all<OperatorUserRow>(),
+    db.prepare(`
+      SELECT id, email, role, status, invited_by, accepted_by, expires_at, accepted_at, revoked_at, created_at
+      FROM operator_invitations ORDER BY created_at DESC, id DESC LIMIT 100
+    `).all<InvitationRow>(),
+  ]);
+  return {
+    users: users.results.map((user) => ({
+      id: user.id, email: user.email, displayName: user.display_name, avatarUrl: operatorAvatarUrl(user),
+      roles: parseRoles(user.roles_json), status: user.status, acceptedAt: user.accepted_at,
+      lastLoginAt: user.last_login_at, createdAt: user.created_at,
+    })),
+    invitations: invitations.results.map((invitation) => ({
+      id: invitation.id, email: invitation.email, role: invitation.role,
+      status: invitation.status === "pending" && invitation.expires_at <= new Date().toISOString() ? "expired" : invitation.status,
+      invitedBy: invitation.invited_by, expiresAt: invitation.expires_at, acceptedAt: invitation.accepted_at,
+      createdAt: invitation.created_at,
+    })),
+  };
+}
+
+export async function revokeOperatorInvitation(db: D1Database, actor: OperatorSession, invitationId: string): Promise<void> {
+  if (!/^[0-9a-f-]{36}$/iu.test(invitationId)) throw new ApiError(400, "invalid_invitation", "Invitation ID is invalid.");
+  const timestamp = new Date().toISOString();
+  const result = await db.prepare(`
+    UPDATE operator_invitations SET status = 'revoked', revoked_at = ?2
+    WHERE id = ?1 AND status = 'pending'
+  `).bind(invitationId, timestamp).run();
+  if (!result.meta.changes) throw new ApiError(404, "invitation_not_found", "The pending invitation was not found.");
+  await auditEvent(db, "operator.invitation_revoked", actor.actor.id, actor.actor.type, invitationId, {}, timestamp).run();
+}
+
+export async function updateOperatorUser(
+  db: D1Database,
+  actor: OperatorSession,
+  userId: string,
+  input: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const user = await db.prepare(`
+    SELECT id, roles_json AS rolesJson, status,
+      (SELECT queue_scope_json FROM role_bindings
+       WHERE principal_type = 'operator_user' AND principal_id = operator_users.id AND revoked_at IS NULL
+       ORDER BY created_at DESC, id DESC LIMIT 1) AS queueScopeJson
+    FROM operator_users WHERE id = ?1 LIMIT 1
+  `).bind(userId).first<{ id: string; rolesJson: string; status: "active" | "suspended"; queueScopeJson: string | null }>();
+  if (!user) throw new ApiError(404, "operator_not_found", "The operator does not exist.");
+  const existingRoles = parseRoles(user.rolesJson);
+  const rolesValue = input.roles ?? existingRoles;
+  if (!Array.isArray(rolesValue) || !rolesValue.length || rolesValue.length > 8) {
+    throw new ApiError(400, "operator_roles_invalid", "roles must contain one or more unique roles.");
+  }
+  const allRoles = new Set<OperatorRole>(["owner", ...assignableRoles]);
+  const roles = [...new Set(rolesValue.map((role) => {
+    if (typeof role !== "string" || !allRoles.has(role as OperatorRole)) throw new ApiError(400, "operator_roles_invalid", "roles contains an unsupported role.");
+    return role as OperatorRole;
+  }))];
+  const statusValue = input.status ?? user.status;
+  if (statusValue !== "active" && statusValue !== "suspended") throw new ApiError(400, "operator_status_invalid", "status must be active or suspended.");
+  let existingQueueScopes: unknown = [];
+  try { existingQueueScopes = JSON.parse(user.queueScopeJson ?? "[]") as unknown; } catch { existingQueueScopes = []; }
+  const queueScopeValue = input.queue_scopes ?? existingQueueScopes;
+  if (!Array.isArray(queueScopeValue) || queueScopeValue.length > 200 || queueScopeValue.some((value) => typeof value !== "string" || value.length < 1 || value.length > 100)) {
+    throw new ApiError(400, "operator_queue_scope_invalid", "queue_scopes must be a bounded array of queue IDs.");
+  }
+  const queueScopes = [...new Set(queueScopeValue as string[])];
+  const changingOwner = existingRoles.includes("owner") && (statusValue !== "active" || !roles.includes("owner"));
+  if ((roles.includes("owner") || changingOwner) && !actor.roles.includes("owner")) {
+    throw new ApiError(403, "owner_role_requires_owner", "Only an owner can grant or remove the owner role.");
+  }
+  if (changingOwner) {
+    const otherOwners = await db.prepare(`
+      SELECT COUNT(*) AS count FROM operator_users
+      WHERE id != ?1 AND status = 'active' AND roles_json LIKE '%"owner"%'
+    `).bind(userId).first<{ count: number }>();
+    if (Number(otherOwners?.count ?? 0) < 1) throw new ApiError(409, "last_owner_required", "The last active owner cannot be suspended or demoted.");
+  }
+  const timestamp = new Date().toISOString();
+  const statements: D1PreparedStatement[] = [
+    db.prepare(`UPDATE operator_users SET roles_json = ?2, status = ?3, updated_at = ?4 WHERE id = ?1`)
+      .bind(userId, canonicalJson(roles), statusValue, timestamp),
+    db.prepare(`UPDATE role_bindings SET revoked_at = ?2 WHERE principal_type = 'operator_user' AND principal_id = ?1 AND revoked_at IS NULL`)
+      .bind(userId, timestamp),
+  ];
+  for (const role of roles) {
+    statements.push(db.prepare(`
+      INSERT INTO role_bindings (
+        id, installation_id, principal_type, principal_id, role,
+        queue_scope_json, field_scope_json, created_by, created_at
+      ) VALUES (?1, 'default', 'operator_user', ?2, ?3, ?4, '{}', ?5, ?6)
+    `).bind(crypto.randomUUID(), userId, role, canonicalJson(queueScopes), actor.actor.id, timestamp));
+  }
+  if (statusValue === "suspended") {
+    statements.push(db.prepare(`UPDATE infrastructure_owner_sessions SET revoked_at = ?2 WHERE user_id = ?1 AND revoked_at IS NULL`).bind(userId, timestamp));
+  }
+  statements.push(auditEvent(db, "operator.access_updated", actor.actor.id, actor.actor.type, userId, {
+    roles, status: statusValue, queueScopes,
+  }, timestamp));
+  await db.batch(statements);
+  return { id: userId, roles, status: statusValue, queueScopes };
+}
+
+export async function revokeOperatorSessions(db: D1Database, actor: OperatorSession, userId: string): Promise<number> {
+  const user = await db.prepare(`SELECT id FROM operator_users WHERE id = ?1 LIMIT 1`).bind(userId).first();
+  if (!user) throw new ApiError(404, "operator_not_found", "The operator does not exist.");
+  const timestamp = new Date().toISOString();
+  const result = await db.prepare(`UPDATE infrastructure_owner_sessions SET revoked_at = ?2 WHERE user_id = ?1 AND revoked_at IS NULL`)
+    .bind(userId, timestamp).run();
+  await auditEvent(db, "operator.sessions_revoked", actor.actor.id, actor.actor.type, userId, { count: result.meta.changes }, timestamp).run();
+  return Number(result.meta.changes ?? 0);
+}
+
+function requireAccountActor(session: OperatorSession): string {
+  if (session.actor.type !== "operator_user") {
+    throw new ApiError(403, "account_session_required", "Sign in with your Safest account to manage your profile.");
+  }
+  return session.actor.id;
+}
+
+async function loadOperatorUser(db: D1Database, userId: string): Promise<OperatorUserRow> {
+  const user = await db.prepare(`SELECT * FROM operator_users WHERE id = ?1 AND status = 'active' LIMIT 1`)
+    .bind(userId).first<OperatorUserRow>();
+  if (!user) throw new ApiError(404, "operator_not_found", "The Safest account was not found.");
+  return user;
+}
+
+export async function updateOperatorProfile(
+  db: D1Database,
+  session: OperatorSession,
+  input: Record<string, unknown>,
+): Promise<OperatorSession> {
+  const userId = requireAccountActor(session);
+  const displayName = cleanDisplayName(input.display_name);
+  const timestamp = new Date().toISOString();
+  const results = await db.batch([
+    db.prepare(`UPDATE operator_users SET display_name = ?2, updated_at = ?3 WHERE id = ?1 AND status = 'active'`)
+      .bind(userId, displayName, timestamp),
+    auditEvent(db, "operator.profile_updated", userId, "operator_user", userId, { display_name: displayName }, timestamp),
+  ]);
+  if (!(results[0]?.meta.changes ?? 0)) throw new ApiError(404, "operator_not_found", "The Safest account was not found.");
+  return operatorSession(await loadOperatorUser(db, userId));
+}
+
+function profilePictureExtension(contentType: string): string | null {
+  return ({ "image/jpeg": "jpg", "image/png": "png", "image/webp": "webp" } as Record<string, string>)[contentType] ?? null;
+}
+
+export function detectProfilePictureContentType(bytes: Uint8Array): "image/jpeg" | "image/png" | "image/webp" | null {
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+  if (bytes.length >= 8 && [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+    .every((value, index) => bytes[index] === value)) return "image/png";
+  if (bytes.length >= 12 && new TextDecoder().decode(bytes.slice(0, 4)) === "RIFF"
+    && new TextDecoder().decode(bytes.slice(8, 12)) === "WEBP") return "image/webp";
+  return null;
+}
+
+async function boundedProfilePicture(request: Request): Promise<{ bytes: Uint8Array; contentType: string; extension: string }> {
+  const declaredLength = Number.parseInt(request.headers.get("content-length") ?? "0", 10);
+  if (Number.isFinite(declaredLength) && declaredLength > PROFILE_PICTURE_MAX_BYTES) {
+    throw new ApiError(413, "profile_picture_too_large", "Profile pictures must be 2 MB or smaller.");
+  }
+  const declaredType = request.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+  const extension = profilePictureExtension(declaredType);
+  if (!extension) throw new ApiError(415, "unsupported_profile_picture", "Use a JPEG, PNG, or WebP profile picture.");
+  const bytes = new Uint8Array(await request.arrayBuffer());
+  if (!bytes.length || bytes.length > PROFILE_PICTURE_MAX_BYTES) {
+    throw new ApiError(bytes.length ? 413 : 400, bytes.length ? "profile_picture_too_large" : "profile_picture_empty",
+      bytes.length ? "Profile pictures must be 2 MB or smaller." : "Choose a profile picture to upload.");
+  }
+  if (detectProfilePictureContentType(bytes) !== declaredType) {
+    throw new ApiError(400, "profile_picture_type_mismatch", "The selected file does not match its image type.");
+  }
+  return { bytes, contentType: declaredType, extension };
+}
+
+export async function uploadOperatorProfilePicture(
+  db: D1Database,
+  bucket: R2Bucket,
+  session: OperatorSession,
+  request: Request,
+): Promise<{ session: OperatorSession; oldObjectKey: string | null }> {
+  const userId = requireAccountActor(session);
+  const upload = await boundedProfilePicture(request);
+  const current = await loadOperatorUser(db, userId);
+  const objectKey = `operator-profile-pictures/${userId}/${crypto.randomUUID()}.${upload.extension}`;
+  const timestamp = new Date().toISOString();
+  await bucket.put(objectKey, upload.bytes, {
+    httpMetadata: { contentType: upload.contentType, cacheControl: "private, max-age=300" },
+    customMetadata: { operatorUserId: userId },
+  });
+  try {
+    await db.batch([
+      db.prepare(`
+        UPDATE operator_users
+        SET avatar_object_key = ?2, avatar_uploaded_at = ?3, avatar_url = NULL, updated_at = ?3
+        WHERE id = ?1 AND status = 'active'
+      `).bind(userId, objectKey, timestamp),
+      auditEvent(db, "operator.profile_picture_updated", userId, "operator_user", userId, {
+        content_type: upload.contentType,
+        size_bytes: upload.bytes.length,
+      }, timestamp),
+    ]);
+  } catch (error) {
+    await bucket.delete(objectKey);
+    throw error;
+  }
+  return {
+    session: operatorSession({
+      ...current,
+      avatar_url: null,
+      avatar_object_key: objectKey,
+      avatar_uploaded_at: timestamp,
+      updated_at: timestamp,
+    }),
+    oldObjectKey: current.avatar_object_key,
+  };
+}
+
+export async function deleteOperatorProfilePicture(
+  db: D1Database,
+  session: OperatorSession,
+): Promise<{ session: OperatorSession; oldObjectKey: string | null }> {
+  const userId = requireAccountActor(session);
+  const current = await loadOperatorUser(db, userId);
+  const timestamp = new Date().toISOString();
+  await db.batch([
+    db.prepare(`
+      UPDATE operator_users
+      SET avatar_object_key = NULL, avatar_uploaded_at = NULL, avatar_url = NULL, updated_at = ?2
+      WHERE id = ?1 AND status = 'active'
+    `).bind(userId, timestamp),
+    auditEvent(db, "operator.profile_picture_removed", userId, "operator_user", userId, {}, timestamp),
+  ]);
+  return {
+    session: operatorSession({
+      ...current,
+      avatar_url: null,
+      avatar_object_key: null,
+      avatar_uploaded_at: null,
+      updated_at: timestamp,
+    }),
+    oldObjectKey: current.avatar_object_key,
+  };
+}
+
+export async function operatorProfilePictureResponse(
+  db: D1Database,
+  bucket: R2Bucket,
+  userId: string,
+  headOnly = false,
+): Promise<Response> {
+  if (!/^[0-9a-f-]{36}$/iu.test(userId)) throw new ApiError(404, "profile_picture_not_found", "The profile picture was not found.");
+  const row = await db.prepare(`SELECT avatar_object_key FROM operator_users WHERE id = ?1 AND status = 'active' LIMIT 1`)
+    .bind(userId).first<{ avatar_object_key: string | null }>();
+  if (!row?.avatar_object_key) throw new ApiError(404, "profile_picture_not_found", "The profile picture was not found.");
+  const object = headOnly ? await bucket.head(row.avatar_object_key) : await bucket.get(row.avatar_object_key);
+  if (!object) throw new ApiError(404, "profile_picture_not_found", "The profile picture was not found.");
+  const headers = new Headers();
+  object.writeHttpMetadata(headers);
+  headers.set("etag", object.httpEtag);
+  headers.set("content-length", String(object.size));
+  headers.set("cache-control", "private, max-age=300");
+  headers.set("cross-origin-resource-policy", "same-origin");
+  headers.set("x-content-type-options", "nosniff");
+  return new Response(headOnly ? null : (object as R2ObjectBody).body, { headers });
+}
+
+export async function logoutOperator(request: Request, db: D1Database): Promise<void> {
+  const account = await resolveOperatorAccountSession(request, db);
+  if (!account) return;
+  await verifyOperatorCsrf(request, account.csrfHash);
+  const timestamp = new Date().toISOString();
+  await db.batch([
+    db.prepare(`UPDATE infrastructure_owner_sessions SET revoked_at = ?2 WHERE id = ?1 AND revoked_at IS NULL`).bind(account.sessionId, timestamp),
+    auditEvent(db, "operator.logout", account.session.actor.id, account.session.actor.type, account.session.actor.id, {}, timestamp),
+  ]);
+}