@valentinkolb/cloud 0.4.0 → 0.5.1

package/src/server/services/access.ts

@@ -1,5 +1,5 @@
-import { sql } from "bun";
 import { err, fail, ok, type Result } from "@valentinkolb/stdlib";
+import { sql } from "bun";
 
 // ==========================
 // Permission Levels
@@ -18,14 +18,19 @@ export const hasPermission = (userLevel: PermissionLevel, requiredLevel: Permiss
 // Principal Types
 // ==========================
 
-export type PrincipalType = "user" | "group" | "authenticated" | "public";
+export type PrincipalType = "user" | "group" | "service_account" | "authenticated" | "public";
 
 export type Principal =
   | { type: "user"; userId: string }
   | { type: "group"; groupId: string }
+  | { type: "service_account"; serviceAccountId: string }
   | { type: "authenticated" }
   | { type: "public" };
 
+export type AccessSubject =
+  | { type: "user"; userId: string; delegatedByServiceAccountId?: string | null }
+  | { type: "service_account"; serviceAccountId: string };
+
 // ==========================
 // Access Entry Types
 // ==========================
@@ -39,15 +44,43 @@ export type AccessEntry = {
   displayName?: string;
 };
 
+export type AccessUserSource =
+  | { type: "direct" }
+  | {
+      type: "group";
+      /** Top-level group from the access grant, not the nested membership group. */
+      groupId: string;
+      groupName: string;
+    };
+
+export type AccessUser = {
+  id: string;
+  uid: string;
+  displayName: string;
+  permission: Exclude<PermissionLevel, "none">;
+  source: AccessUserSource;
+};
+
 type DbAccess = {
   id: string;
   user_id: string | null;
   group_id: string | null;
+  service_account_id: string | null;
   authenticated_only: boolean;
   permission: PermissionLevel;
   created_at: Date;
 };
 
+type DbAccessUser = {
+  id: string;
+  uid: string;
+  display_name: string;
+  permission: Exclude<PermissionLevel, "none">;
+  direct: boolean;
+  source_group_id: string | null;
+  source_group_name: string | null;
+};
+
 // ==========================
 // Helper Functions
 // ==========================
@@ -60,12 +93,24 @@ const toPgUuidArray = (values: string[] | null | undefined): string => {
   return `{${values.join(",")}}`;
 };
 
+const uniqueIds = (values: string[] | null | undefined): string[] => [...new Set((values ?? []).filter(Boolean))];
+
+const escapeLikePattern = (value: string): string => value.replace(/[\\%_]/g, (match) => `\\${match}`);
+
+const PERMISSION_RANK: Record<PermissionLevel, number> = {
+  none: 1,
+  read: 2,
+  write: 3,
+  admin: 4,
+};
+
 /**
  * Builds a typed access principal from one database access row.
  */
 const principalFromDb = (row: DbAccess): Principal => {
   if (row.user_id) return { type: "user", userId: row.user_id };
   if (row.group_id) return { type: "group", groupId: row.group_id };
+  if (row.service_account_id) return { type: "service_account", serviceAccountId: row.service_account_id };
   if (row.authenticated_only) return { type: "authenticated" };
   return { type: "public" };
 };
@@ -93,6 +138,7 @@ export const createAccess = async (params: { principal: Principal; permission: P
 
   let userId: string | null = null;
   let groupId: string | null = null;
+  let serviceAccountId: string | null = null;
   let authenticatedOnly = false;
 
   if (principal.type === "user") {
@@ -113,14 +159,22 @@ export const createAccess = async (params: { principal: Principal; permission: P
     if (!group) {
       return fail(err.notFound("Group"));
     }
+  } else if (principal.type === "service_account") {
+    serviceAccountId = principal.serviceAccountId;
+    const [serviceAccount] = await sql<{ id: string }[]>`
+      SELECT id FROM auth.service_accounts WHERE id = ${serviceAccountId}::uuid AND status = 'active'
+    `;
+    if (!serviceAccount) {
+      return fail(err.notFound("Service account"));
+    }
   } else if (principal.type === "authenticated") {
     authenticatedOnly = true;
   }
   // public: user/group null, authenticated_only false
 
   const [row] = await sql<{ id: string }[]>`
-    INSERT INTO auth.access (user_id, group_id, authenticated_only, permission)
-    VALUES (${userId}::uuid, ${groupId}::uuid, ${authenticatedOnly}, ${permission}::auth.permission_level)
+    INSERT INTO auth.access (user_id, group_id, service_account_id, authenticated_only, permission)
+    VALUES (${userId}::uuid, ${groupId}::uuid, ${serviceAccountId}::uuid, ${authenticatedOnly}, ${permission}::auth.permission_level)
     RETURNING id
   `;
 
@@ -136,7 +190,7 @@ export const createAccess = async (params: { principal: Principal; permission: P
  */
 export const getAccess = async (params: { id: string }): Promise<AccessEntry | null> => {
   const [row] = await sql<DbAccess[]>`
-    SELECT id, user_id, group_id, authenticated_only, permission, created_at
+    SELECT id, user_id, group_id, service_account_id, authenticated_only, permission, created_at
     FROM auth.access
     WHERE id = ${params.id}::uuid
   `;
@@ -206,10 +260,12 @@ export const getEffectivePermission = async (params: {
   accessIds: string[];
   userId: string | null;
   userGroups: string[];
+  serviceAccountId?: string | null;
 }): Promise<PermissionLevel> => {
   const accessIds = params.accessIds ?? [];
   const userId = params.userId;
   const userGroups = params.userGroups ?? [];
+  const serviceAccountId = params.serviceAccountId ?? null;
 
   if (accessIds.length === 0) return "none";
 
@@ -221,8 +277,15 @@ export const getEffectivePermission = async (params: {
       AND (
         user_id = ${userId}::uuid
         OR group_id = ANY(${toPgUuidArray(userGroups)}::uuid[])
+        OR service_account_id = ${serviceAccountId}::uuid
         OR (${userId}::uuid IS NOT NULL AND authenticated_only = true)
-        OR (user_id IS NULL AND group_id IS NULL AND authenticated_only = false)
+        OR (
+          ${serviceAccountId}::uuid IS NULL
+          AND user_id IS NULL
+          AND group_id IS NULL
+          AND service_account_id IS NULL
+          AND authenticated_only = false
+        )
       )
     ORDER BY
       CASE permission
@@ -237,6 +300,172 @@ export const getEffectivePermission = async (params: {
   return rows[0]?.permission ?? "none";
 };
 
+/**
+ * Lists concrete users reachable from auth.access entries.
+ *
+ * Apps stay responsible for collecting the relevant access entry IDs from their
+ * own junction tables. This helper expands direct user grants and recursive
+ * group grants only. It intentionally does not expand public or
+ * authenticated-only grants into "all users", because those scopes are not
+ * bounded, predictable assignee/member lists.
+ */
+export const listUsersWithAccess = async (params: {
+  accessIds: string[];
+  search?: string;
+  userIds?: string[];
+  excludeUserIds?: string[];
+  minimumPermission?: Exclude<PermissionLevel, "none">;
+  limit?: number;
+}): Promise<AccessUser[]> => {
+  const accessIds = uniqueIds(params.accessIds);
+  if (accessIds.length === 0) return [];
+
+  const requestedUserIds = uniqueIds(params.userIds);
+  const excludeUserIds = uniqueIds(params.excludeUserIds);
+  const query = params.search?.trim().toLowerCase();
+  const pattern = query ? `%${escapeLikePattern(query)}%` : null;
+  const minimumRank = PERMISSION_RANK[params.minimumPermission ?? "read"];
+  const defaultLimit = requestedUserIds.length > 0 ? requestedUserIds.length : 20;
+  const limit = Math.min(Math.max(params.limit ?? defaultLimit, 1), 500);
+  const userFilter = requestedUserIds.length > 0 ? sql`AND id = ANY(${toPgUuidArray(requestedUserIds)}::uuid[])` : sql``;
+
+  const rows = await sql<DbAccessUser[]>`
+    WITH RECURSIVE
+      root_groups(root_group_id, root_group_name, group_id, group_ids, permission, permission_rank) AS (
+        SELECT
+          a.group_id,
+          COALESCE(NULLIF(g.name, ''), g.cn),
+          a.group_id,
+          ARRAY[a.group_id]::uuid[],
+          a.permission,
+          CASE a.permission
+            WHEN 'admin' THEN 4
+            WHEN 'write' THEN 3
+            WHEN 'read' THEN 2
+            ELSE 1
+          END
+        FROM auth.access a
+        JOIN auth.groups g ON g.id = a.group_id
+        WHERE a.id = ANY(${toPgUuidArray(accessIds)}::uuid[])
+          AND a.group_id IS NOT NULL
+          AND CASE a.permission
+            WHEN 'admin' THEN 4
+            WHEN 'write' THEN 3
+            WHEN 'read' THEN 2
+            ELSE 1
+          END >= ${minimumRank}
+
+        UNION ALL
+
+        SELECT
+          rg.root_group_id,
+          rg.root_group_name,
+          gg.child_group_id,
+          rg.group_ids || gg.child_group_id,
+          rg.permission,
+          rg.permission_rank
+        FROM auth.group_groups_v2 gg
+        JOIN root_groups rg ON rg.group_id = gg.parent_group_id
+        WHERE NOT gg.child_group_id = ANY(rg.group_ids)
+      ),
+      candidate_users AS (
+        SELECT
+          u.id,
+          u.uid,
+          COALESCE(NULLIF(u.display_name, ''), u.uid, u.id::text) AS display_name,
+          TRUE AS direct,
+          NULL::uuid AS source_group_id,
+          NULL::text AS source_group_name,
+          a.permission,
+          CASE a.permission
+            WHEN 'admin' THEN 4
+            WHEN 'write' THEN 3
+            WHEN 'read' THEN 2
+            ELSE 1
+          END AS permission_rank
+        FROM auth.access a
+        JOIN auth.users u ON u.id = a.user_id
+        WHERE a.id = ANY(${toPgUuidArray(accessIds)}::uuid[])
+          AND a.user_id IS NOT NULL
+          AND CASE a.permission
+            WHEN 'admin' THEN 4
+            WHEN 'write' THEN 3
+            WHEN 'read' THEN 2
+            ELSE 1
+          END >= ${minimumRank}
+
+        UNION ALL
+
+        SELECT
+          u.id,
+          u.uid,
+          COALESCE(NULLIF(u.display_name, ''), u.uid, u.id::text) AS display_name,
+          FALSE AS direct,
+          rg.root_group_id AS source_group_id,
+          rg.root_group_name AS source_group_name,
+          rg.permission,
+          rg.permission_rank
+        FROM root_groups rg
+        JOIN auth.user_groups_v2 ug ON ug.group_id = rg.group_id
+        JOIN auth.users u ON u.id = ug.user_id
+      ),
+      access_users AS (
+        SELECT
+          id,
+          uid,
+          display_name,
+          CASE MAX(permission_rank)
+            WHEN 4 THEN 'admin'
+            WHEN 3 THEN 'write'
+            ELSE 'read'
+          END AS permission,
+          BOOL_OR(direct) AS direct,
+          (
+            ARRAY_AGG(source_group_id ORDER BY permission_rank DESC, source_group_name)
+            FILTER (WHERE NOT direct AND source_group_id IS NOT NULL)
+          )[1] AS source_group_id,
+          (
+            ARRAY_AGG(source_group_name ORDER BY permission_rank DESC, source_group_name)
+            FILTER (WHERE NOT direct AND source_group_name IS NOT NULL)
+          )[1] AS source_group_name,
+          COALESCE(
+            STRING_AGG(source_group_name, ' ')
+            FILTER (WHERE NOT direct AND source_group_name IS NOT NULL),
+            ''
+          ) AS group_names
+        FROM candidate_users
+        GROUP BY id, uid, display_name
+      )
+    SELECT id, uid, display_name, permission, direct, source_group_id, source_group_name
+    FROM access_users
+    WHERE id <> ALL(${toPgUuidArray(excludeUserIds)}::uuid[])
+      AND (direct OR (source_group_id IS NOT NULL AND source_group_name IS NOT NULL))
+      ${userFilter}
+      AND (
+        ${pattern}::text IS NULL
+        OR LOWER(display_name) LIKE ${pattern} ESCAPE '\\'
+        OR LOWER(uid) LIKE ${pattern} ESCAPE '\\'
+        OR LOWER(group_names) LIKE ${pattern} ESCAPE '\\'
+      )
+    ORDER BY LOWER(display_name), id
+    LIMIT ${limit}
+  `;
+
+  return rows.map((row) => ({
+    id: row.id,
+    uid: row.uid,
+    displayName: row.display_name,
+    permission: row.permission,
+    source: row.direct
+      ? { type: "direct" }
+      : {
+          type: "group",
+          groupId: row.source_group_id as string,
+          groupName: row.source_group_name as string,
+        },
+  }));
+};
+
 /**
  * Resolve display names for access entries.
  * Populates the displayName field based on principal type.
@@ -248,6 +477,10 @@ export const resolveDisplayNames = async (entries: AccessEntry[]): Promise<Acces
     .filter((e) => e.principal.type === "group")
     .map((e) => (e.principal as { type: "group"; groupId: string }).groupId);
 
+  const serviceAccountIds = entries
+    .filter((e) => e.principal.type === "service_account")
+    .map((e) => (e.principal as { type: "service_account"; serviceAccountId: string }).serviceAccountId);
+
   // Fetch user display names
   const userNames = new Map<string, string>();
   if (userIds.length > 0) {
@@ -273,6 +506,18 @@ export const resolveDisplayNames = async (entries: AccessEntry[]): Promise<Acces
     }
   }
 
+  const serviceAccountNames = new Map<string, string>();
+  if (serviceAccountIds.length > 0) {
+    const serviceAccounts = await sql<{ id: string; name: string }[]>`
+      SELECT id, name
+      FROM auth.service_accounts
+      WHERE id = ANY(${toPgUuidArray(serviceAccountIds)}::uuid[])
+    `;
+    for (const serviceAccount of serviceAccounts) {
+      serviceAccountNames.set(serviceAccount.id, serviceAccount.name);
+    }
+  }
+
   return entries.map((entry) => {
     let displayName: string;
     switch (entry.principal.type) {
@@ -282,6 +527,9 @@ export const resolveDisplayNames = async (entries: AccessEntry[]): Promise<Acces
       case "group":
         displayName = groupNames.get(entry.principal.groupId) ?? "Unknown Group";
         break;
+      case "service_account":
+        displayName = serviceAccountNames.get(entry.principal.serviceAccountId) ?? "Unknown Service Account";
+        break;
       case "authenticated":
         displayName = "All users (incl. guests)";
         break;

package/src/server/services/index.ts

@@ -1,27 +1,30 @@
 // Cloud-specific server services
-export { services } from "./services";
-export { freeipa } from "./freeipa";
 
+export type { AccessEntry, AccessSubject, AccessUser, AccessUserSource, PermissionLevel, Principal, PrincipalType, ResourceAccessAdapter } from "./access";
 export {
-  PERMISSION_LEVELS,
-  hasPermission,
   createAccess,
-  getAccess,
-  updateAccess,
   deleteAccess,
+  getAccess,
   getEffectivePermission,
+  hasPermission,
+  listUsersWithAccess,
+  PERMISSION_LEVELS,
   resolveDisplayNames,
+  updateAccess,
 } from "./access";
-export type { AccessEntry, PermissionLevel, PrincipalType, Principal, ResourceAccessAdapter } from "./access";
+export { freeipa } from "./freeipa";
+export type { GeoPlace, GeoService } from "./geo";
 
 export { geo, geoService } from "./geo";
-export type { GeoService, GeoPlace } from "./geo";
+export { paginateItems } from "./pagination";
+export { services } from "./services";
 
 // Re-export from stdlib for backward compatibility
 // Prefer importing directly from @valentinkolb/stdlib
-import { svg as _svg, password as _password } from "@valentinkolb/stdlib";
-export { ok, okMany, fail, err, unwrap, paginate, tryCatch, isServiceError, crypto, svg, password } from "@valentinkolb/stdlib";
-export type { Result, Paginated, PageParams, ServiceError, ServiceErrorCode } from "@valentinkolb/stdlib";
+import { password as _password, svg as _svg } from "@valentinkolb/stdlib";
+
+export type { PageParams, Paginated, Result, ServiceError, ServiceErrorCode } from "@valentinkolb/stdlib";
+export { crypto, err, fail, isServiceError, ok, okMany, paginate, password, svg, tryCatch, unwrap } from "@valentinkolb/stdlib";
 
 // Compat aliases for old API names
 export const images = { generateFallback: _svg.generateAvatar, parseWebpDataUrl: _svg.parseWebpDataUrl };

package/src/server/services/pagination.ts

@@ -0,0 +1,22 @@
+import { type PageParams, type Paginated, paginate } from "@valentinkolb/stdlib";
+
+export const paginateItems = <T>(items: T[], pagination?: PageParams): Paginated<T> => {
+  if (!pagination) {
+    return {
+      items,
+      page: 1,
+      perPage: items.length,
+      total: items.length,
+      hasNext: false,
+    };
+  }
+
+  const { page, perPage, offset } = paginate(pagination);
+  return {
+    items: items.slice(offset, offset + perPage),
+    page,
+    perPage,
+    total: items.length,
+    hasNext: page * perPage < items.length,
+  };
+};

package/src/server/time.ts

@@ -0,0 +1,45 @@
+import type { DateContext } from "@valentinkolb/stdlib";
+import { normalizeTimeZone, TIMEZONE_COOKIE } from "../shared/time";
+
+export { TIMEZONE_COOKIE };
+
+type TimeContext = {
+  get(key: "settings"): Record<string, any> | undefined;
+  req: { raw: { headers: Headers } };
+};
+
+const readCookie = (headers: Headers, name: string): string | undefined => {
+  const cookie = headers.get("Cookie");
+  if (!cookie) return undefined;
+
+  for (const part of cookie.split(";")) {
+    const [rawName, ...rawValue] = part.trim().split("=");
+    if (rawName !== name) continue;
+    const value = rawValue.join("=");
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  }
+
+  return undefined;
+};
+
+export const getTimeZone = (c: TimeContext): string => {
+  const settingsTimeZone = c.get("settings")?.app?.timezone;
+  const fallback = normalizeTimeZone(typeof settingsTimeZone === "string" ? settingsTimeZone : undefined, "UTC");
+  return normalizeTimeZone(readCookie(c.req.raw.headers, TIMEZONE_COOKIE), fallback);
+};
+
+export const getDateConfig = (c: TimeContext): DateContext => ({
+  timeZone: getTimeZone(c),
+  locale: "en",
+  firstDayOfWeek: 1,
+});
+
+export const time = {
+  TIMEZONE_COOKIE,
+  getTimeZone,
+  getDateConfig,
+} as const;