simplycms 0.4.0

package/src/admin/pages/Users.tsx

@@ -0,0 +1,322 @@
+import { useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { useNavigate, Link } from '@tanstack/react-router';
+import { adminPath } from '../lib/adminLinks';
+import { useSupabaseClient } from 'simplycms/supabase/SupabaseProvider';
+import { useFormatPrice } from 'simplycms/react-query';
+import { useT } from 'simplycms/i18n';
+import { Button } from 'simplycms/ui/button';
+import { Input } from 'simplycms/ui/input';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from 'simplycms/ui/table';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from 'simplycms/ui/select';
+import { Badge } from 'simplycms/ui/badge';
+import { Avatar, AvatarFallback, AvatarImage } from 'simplycms/ui/avatar';
+import { Search, Shield, ArrowLeft } from 'lucide-react';
+import { format } from 'date-fns';
+import { uk } from 'date-fns/locale';
+
+interface UserWithDetails {
+  user_id: string;
+  first_name: string | null;
+  last_name: string | null;
+  email: string | null;
+  phone: string | null;
+  avatar_url: string | null;
+  category_id: string | null;
+  auth_provider: string | null;
+  created_at: string;
+  category?: {
+    id: string;
+    name: string;
+  } | null;
+  is_admin: boolean;
+  total_orders: number;
+  total_spent: number;
+}
+
+export default function Users() {
+  const t = useT();
+  const supabase = useSupabaseClient();
+  const formatPrice = useFormatPrice();
+  const navigate = useNavigate();
+  const [search, setSearch] = useState('');
+  const [categoryFilter, setCategoryFilter] = useState<string>('all');
+  const [roleFilter, setRoleFilter] = useState<string>('all');
+
+  // Fetch categories for filter
+  const { data: categories } = useQuery({
+    queryKey: ['user-categories'],
+    queryFn: async () => {
+      const { data, error } = await supabase
+        .from('user_categories')
+        .select('*')
+        .order('name');
+      if (error) throw error;
+      return data;
+    },
+  });
+
+  // Fetch users with their details
+  const { data: users, isLoading } = useQuery({
+    queryKey: ['admin-users', search, categoryFilter, roleFilter],
+    queryFn: async () => {
+      // Get profiles with categories
+      let query = supabase
+        .from('profiles')
+        .select(
+          `
+          user_id,
+          first_name,
+          last_name,
+          email,
+          phone,
+          avatar_url,
+          category_id,
+          auth_provider,
+          created_at,
+          category:user_categories(id, name)
+        `,
+        )
+        .order('created_at', { ascending: false });
+
+      if (categoryFilter && categoryFilter !== 'all') {
+        query = query.eq('category_id', categoryFilter);
+      }
+
+      const { data: profiles, error: profilesError } = await query;
+      if (profilesError) throw profilesError;
+
+      // Get admin roles
+      const { data: adminRoles, error: rolesError } = await supabase
+        .from('user_roles')
+        .select('user_id')
+        .eq('role', 'admin');
+      if (rolesError) throw rolesError;
+
+      const adminUserIds = new Set(adminRoles?.map((r) => r.user_id) || []);
+
+      // Get order stats for each user
+      const { data: orderStats, error: statsError } = await supabase
+        .from('orders')
+        .select('user_id, total')
+        .not('user_id', 'is', null);
+      if (statsError) throw statsError;
+
+      // Calculate stats per user
+      const userStats = new Map<string, { orders: number; spent: number }>();
+      orderStats?.forEach((order) => {
+        if (!order.user_id) return;
+        const current = userStats.get(order.user_id) || { orders: 0, spent: 0 };
+        current.orders += 1;
+        current.spent += Number(order.total) || 0;
+        userStats.set(order.user_id, current);
+      });
+
+      // Combine all data
+      let result: UserWithDetails[] =
+        profiles?.map((profile) => ({
+          ...profile,
+          category: profile.category as { id: string; name: string } | null,
+          is_admin: adminUserIds.has(profile.user_id),
+          total_orders: userStats.get(profile.user_id)?.orders || 0,
+          total_spent: userStats.get(profile.user_id)?.spent || 0,
+        })) || [];
+
+      // Apply role filter
+      if (roleFilter === 'admin') {
+        result = result.filter((u) => u.is_admin);
+      } else if (roleFilter === 'user') {
+        result = result.filter((u) => !u.is_admin);
+      }
+
+      // Apply search filter
+      if (search) {
+        const searchLower = search.toLowerCase();
+        result = result.filter(
+          (u) =>
+            u.email?.toLowerCase().includes(searchLower) ||
+            u.first_name?.toLowerCase().includes(searchLower) ||
+            u.last_name?.toLowerCase().includes(searchLower) ||
+            u.phone?.includes(search),
+        );
+      }
+
+      return result;
+    },
+  });
+
+  const getInitials = (user: UserWithDetails) => {
+    const first = user.first_name?.[0] || '';
+    const last = user.last_name?.[0] || '';
+    return (
+      (first + last).toUpperCase() || user.email?.[0]?.toUpperCase() || '?'
+    );
+  };
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-center gap-4">
+        <Button variant="ghost" size="icon" asChild>
+          <Link to="/admin">
+            <ArrowLeft className="h-5 w-5" />
+          </Link>
+        </Button>
+        <div>
+          <h1 className="text-3xl font-bold">{t('admin.nav.users')}</h1>
+          <p className="text-muted-foreground">{t('admin.users.subtitle')}</p>
+        </div>
+      </div>
+
+      {/* Filters */}
+      <div className="flex flex-wrap gap-4">
+        <div className="relative flex-1 min-w-[250px]">
+          <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+          <Input
+            placeholder={t('admin.users.searchPlaceholder')}
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+            className="pl-10"
+          />
+        </div>
+        <Select value={categoryFilter} onValueChange={setCategoryFilter}>
+          <SelectTrigger className="w-[200px]">
+            <SelectValue placeholder={t('common.category')} />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="all">
+              {t('admin.users.allCategories')}
+            </SelectItem>
+            {categories?.map((cat) => (
+              <SelectItem key={cat.id} value={cat.id}>
+                {cat.name}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+        <Select value={roleFilter} onValueChange={setRoleFilter}>
+          <SelectTrigger className="w-[180px]">
+            <SelectValue placeholder={t('admin.users.role')} />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="all">{t('admin.users.allRoles')}</SelectItem>
+            <SelectItem value="admin">{t('admin.users.admins')}</SelectItem>
+            <SelectItem value="user">{t('admin.nav.users')}</SelectItem>
+          </SelectContent>
+        </Select>
+      </div>
+
+      {/* Users table */}
+      <div className="border rounded-lg">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead className="w-12"></TableHead>
+              <TableHead>{t('admin.users.user')}</TableHead>
+              <TableHead>{t('admin.users.contacts')}</TableHead>
+              <TableHead>{t('common.category')}</TableHead>
+              <TableHead className="text-center">
+                {t('admin.users.ordersCount')}
+              </TableHead>
+              <TableHead className="text-right">
+                {t('admin.users.totalSpent')}
+              </TableHead>
+              <TableHead>{t('admin.users.registered')}</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {isLoading ? (
+              <TableRow>
+                <TableCell colSpan={7} className="text-center py-8">
+                  {t('common.loading')}
+                </TableCell>
+              </TableRow>
+            ) : users?.length === 0 ? (
+              <TableRow>
+                <TableCell colSpan={7} className="text-center py-8">
+                  {t('admin.users.empty')}
+                </TableCell>
+              </TableRow>
+            ) : (
+              users?.map((user) => (
+                <TableRow
+                  key={user.user_id}
+                  className="cursor-pointer hover:bg-muted/50"
+                  onClick={() =>
+                    navigate({ to: adminPath(`users/${user.user_id}`) })
+                  }
+                >
+                  <TableCell>
+                    <Avatar className="h-10 w-10">
+                      <AvatarImage src={user.avatar_url || undefined} />
+                      <AvatarFallback>{getInitials(user)}</AvatarFallback>
+                    </Avatar>
+                  </TableCell>
+                  <TableCell>
+                    <div className="flex items-center gap-2">
+                      <div>
+                        <div className="font-medium flex items-center gap-2">
+                          {user.first_name || user.last_name
+                            ? `${user.first_name || ''} ${user.last_name || ''}`.trim()
+                            : t('admin.users.noName')}
+                          {user.is_admin && (
+                            <Shield className="h-4 w-4 text-primary" />
+                          )}
+                        </div>
+                        {user.auth_provider && (
+                          <span className="text-xs text-muted-foreground">
+                            via {user.auth_provider}
+                          </span>
+                        )}
+                      </div>
+                    </div>
+                  </TableCell>
+                  <TableCell>
+                    <div className="text-sm">
+                      {user.email && <div>{user.email}</div>}
+                      {user.phone && (
+                        <div className="text-muted-foreground">
+                          {user.phone}
+                        </div>
+                      )}
+                    </div>
+                  </TableCell>
+                  <TableCell>
+                    {user.category ? (
+                      <Badge variant="secondary">{user.category.name}</Badge>
+                    ) : (
+                      <span className="text-muted-foreground">—</span>
+                    )}
+                  </TableCell>
+                  <TableCell className="text-center">
+                    {user.total_orders > 0 ? user.total_orders : '—'}
+                  </TableCell>
+                  <TableCell className="text-right">
+                    {user.total_spent > 0 ? formatPrice(user.total_spent) : '—'}
+                  </TableCell>
+                  <TableCell className="text-muted-foreground">
+                    {format(new Date(user.created_at), 'dd MMM yyyy', {
+                      locale: uk,
+                    })}
+                  </TableCell>
+                </TableRow>
+              ))
+            )}
+          </TableBody>
+        </Table>
+      </div>
+    </div>
+  );
+}

package/src/auth/accept-invite.ts

@@ -0,0 +1,81 @@
+import { randomBytes } from 'node:crypto';
+import type { SimplyAuth } from './instance';
+import {
+  verifyOwnerInvite,
+  type InviteRejection,
+  type OwnerInviteStore,
+} from './invite';
+
+/**
+ * Прийняття запрошення власника: токен із листа → пароль → робочий вхід.
+ *
+ * 🔴 Ланка, якої бракувало. `issueOwnerInvite` випускав посилання, а
+ * `verifyOwnerInvite` умів лише сказати «токен дійсний»; пароля власник не
+ * отримував ніде, тож перший адмін на чистому магазині був недосяжний.
+ *
+ * 🔴 Пароль пишеться НЕ вручну в `accounts`, а штатним `POST /reset-password`
+ * самого Better Auth. Це свідомий обхід чужої внутрішньої кухні: саме той
+ * ендпойнт уміє і створити credential-акаунт, коли його ще немає (наш
+ * запрошений власник), і перезаписати наявний, і робить це тим самим
+ * хешуванням, що й реєстрація. Копія цієї логіки в нас застаріла б мовчки —
+ * і виявилось би це неможливістю ввійти.
+ *
+ * Ціна прийому — одноразовий внутрішній verification-рядок BA: наш токен уже
+ * доведено спожитий, і ми обмінюємо його на токен, який розуміє BA. Він живе
+ * хвилину й гаситься самим ендпойнтом.
+ */
+
+/** Чому прийняття не відбулось — рівно ті випадки, які розрізняє UI. */
+export type AcceptInviteRejection = InviteRejection | 'password-rejected';
+
+export type AcceptOwnerInviteResult =
+  | { readonly ok: true; readonly userId: string }
+  | { readonly ok: false; readonly reason: AcceptInviteRejection };
+
+export interface AcceptOwnerInviteInput {
+  readonly auth: SimplyAuth;
+  readonly store: OwnerInviteStore;
+  readonly email: string;
+  readonly token: string;
+  readonly password: string;
+  readonly now?: Date;
+}
+
+/** Скільки живе внутрішній обмінний токен BA. Хвилини вистачає з запасом. */
+const EXCHANGE_TTL_MS = 60_000;
+
+export async function acceptOwnerInvite(
+  input: AcceptOwnerInviteInput,
+): Promise<AcceptOwnerInviteResult> {
+  // 🔴 Спершу СПОЖИТИ наш токен і лише потім чіпати пароль: інакше невдала
+  // спроба пароля лишала б запрошення живим, а це вже підбір за посиланням.
+  const verified = await verifyOwnerInvite({
+    store: input.store,
+    email: input.email,
+    token: input.token,
+    now: input.now,
+  });
+  if (!verified.ok) return { ok: false, reason: verified.reason };
+
+  const context = await input.auth.$context;
+  const exchangeToken = randomBytes(32).toString('base64url');
+  await context.internalAdapter.createVerificationValue({
+    identifier: `reset-password:${exchangeToken}`,
+    value: verified.userId,
+    expiresAt: new Date((input.now ?? new Date()).getTime() + EXCHANGE_TTL_MS),
+  });
+
+  const response = await input.auth.api.resetPassword({
+    body: { newPassword: input.password, token: exchangeToken },
+    asResponse: true,
+  });
+  if (!response.ok) return { ok: false, reason: 'password-rejected' };
+
+  // Перехід за одноразовим посиланням і є доказом володіння поштою — саме
+  // тому `issueOwnerInvite` заводив користувача з `emailVerified: false`.
+  await context.internalAdapter.updateUser(verified.userId, {
+    emailVerified: true,
+  });
+
+  return { ok: true, userId: verified.userId };
+}

package/src/auth/authz.ts

@@ -0,0 +1,144 @@
+import type { ActorRole } from 'simplycms/db';
+
+/**
+ * Перший рубіж моделі безпеки B5″ — типізований authz у TS (Task 7, В2-К1а).
+ *
+ * 🔴 Рубежів два, і плутати їх не можна. ТУТ вирішується, чи операція взагалі
+ * дозволена цьому субʼєкту; РОЛЬ БД (`app_user`/`app_admin`, вмикається
+ * `SET LOCAL ROLE` у `withActor`) — другий рубіж, страхувальна сітка проти
+ * забутого `WHERE` у репозиторії. Другий рубіж не замінює першого: застосунок
+ * сам виставляє собі claims, тож проти скомпрометованого процесу RLS не
+ * захищає — це виміряно спайком B5.
+ */
+
+/** Доменна роль із `user_roles.role` (енам `app_role`). */
+export type AppRole = 'admin' | 'user';
+
+/**
+ * Вимір ДІЇ над рядками — дизайн-насіння зі спеки §8.
+ *
+ * 🔴 Тут навмисно ЛИШЕ місце, а не реалізація: `own` не фільтрує нічого сам —
+ * він каже викликачу, що запит зобовʼязаний звузитись до власних рядків
+ * (а RLS це продублює). Ролі персоналу (менеджер замовлень, контент-редактор)
+ * зʼявляться пізніше й розрізнятимуться саме цим виміром, а не набором
+ * операцій, — тому вимір заведено ЗАРАЗ, поки матриця мала.
+ */
+export type AuthScope = 'own' | 'any';
+
+/** Операції, які знає ядро. Список росте разом із serverFn-шаром К2/К3. */
+export type Operation =
+  | 'catalog.read'
+  | 'catalog.write'
+  | 'order.read'
+  | 'order.create'
+  | 'profile.read'
+  | 'profile.update'
+  | 'review.create'
+  | 'review.moderate'
+  | 'user.role.assign'
+  | 'admin.access';
+
+/** Хто робить операцію. `userId: null` — анонім (гість вітрини). */
+export interface AuthzSubject {
+  readonly userId: string | null;
+  readonly roles: readonly AppRole[];
+}
+
+type Grants = Readonly<Partial<Record<AppRole, AuthScope>>>;
+
+/**
+ * Матриця «роль × операція → scope». Відсутній ключ ролі = заборонено.
+ *
+ * 🔴 Анонім у матриці НЕ фігурує окремим рядком: він не має жодної ролі, тож
+ * усе, крім явно публічного, йому закрите за побудовою. Публічне читання
+ * каталогу дає не ця матриця, а ГРАНТ на `app_user` (0002_grants.sql) —
+ * тримати «дозволено всім» у двох місцях означало б колись розійтись.
+ */
+export const AUTHZ_MATRIX: Readonly<Record<Operation, Grants>> = {
+  'catalog.read': { user: 'any', admin: 'any' },
+  'catalog.write': { admin: 'any' },
+  'order.read': { user: 'own', admin: 'any' },
+  'order.create': { user: 'own', admin: 'any' },
+  'profile.read': { user: 'own', admin: 'any' },
+  'profile.update': { user: 'own', admin: 'any' },
+  'review.create': { user: 'own', admin: 'any' },
+  'review.moderate': { admin: 'any' },
+  'user.role.assign': { admin: 'any' },
+  'admin.access': { admin: 'any' },
+};
+
+/** Відмова authz. Окремий клас — щоб хендлер мапив її в 403, а не в 500. */
+export class AuthzError extends Error {
+  constructor(readonly operation: Operation | AppRole) {
+    super(`[simplycms/auth] Операція заборонена: ${operation}.`);
+    this.name = 'AuthzError';
+  }
+}
+
+/** `any` перекриває `own`; порядок потрібен для субʼєкта з кількома ролями. */
+const WIDER: Record<AuthScope, number> = { own: 0, any: 1 };
+
+/**
+ * Найширший scope, який дають субʼєкту його ролі, або `null` — заборонено.
+ */
+export function resolveGrant(
+  subject: AuthzSubject,
+  operation: Operation,
+): AuthScope | null {
+  const grants = AUTHZ_MATRIX[operation];
+  let best: AuthScope | null = null;
+  for (const role of subject.roles) {
+    const scope = grants[role];
+    if (scope && (best === null || WIDER[scope] > WIDER[best])) best = scope;
+  }
+  return best;
+}
+
+/** Чи дозволена операція (без деталей scope). */
+export const can = (subject: AuthzSubject, operation: Operation): boolean =>
+  resolveGrant(subject, operation) !== null;
+
+/**
+ * Вимагає роль. Використовується там, де перевірка — саме про роль
+ * (наприклад, вхід в адмінку), а не про конкретну операцію.
+ *
+ * @throws AuthzError
+ */
+export function requireRole(
+  subject: AuthzSubject,
+  role: AppRole,
+): asserts subject is AuthzSubject {
+  if (!subject.roles.includes(role)) throw new AuthzError(role);
+}
+
+/**
+ * Вимагає операцію й повертає scope, з яким її дозволено виконати.
+ *
+ * 🔴 Повертає саме scope, а не `void`: викликач мусить ПОБАЧИТИ, що йому
+ * дозволено лише `own`, і звузити запит. Функція, що повертала б `void`,
+ * зробила б різницю між `own` і `any` невидимою на місці виклику.
+ *
+ * @throws AuthzError
+ */
+export function requireOperation(
+  subject: AuthzSubject,
+  operation: Operation,
+): AuthScope {
+  const scope = resolveGrant(subject, operation);
+  if (!scope) throw new AuthzError(operation);
+  return scope;
+}
+
+/**
+ * Доменна роль → роль БД для `withActor` (другий рубіж).
+ *
+ * 🔴 Мапа однобічна й навмисно тупа: `app_admin` вмикається ЛИШЕ після того,
+ * як перший рубіж уже сказав «так». Викликати `withActor` з `app_admin`,
+ * оминувши `requireOperation`, — це і є той обхід, проти якого весь дизайн.
+ */
+export const dbRoleFor = (role: AppRole): ActorRole =>
+  role === 'admin' ? 'app_admin' : 'app_user';
+
+/** Роль БД для субʼєкта: адмін — якщо він адмін, інакше звичайний покупець. */
+export const dbRoleForSubject = (subject: AuthzSubject): ActorRole =>
+  subject.roles.includes('admin') ? 'app_admin' : 'app_user';

package/src/auth/drizzle-proxy.ts

@@ -0,0 +1,71 @@
+import { drizzle } from 'drizzle-orm/pg-proxy';
+import { withActor } from 'simplycms/db';
+
+/**
+ * Міст «Better Auth → Postgres» через `withActor` (Task 7, В2-К1а).
+ *
+ * 🔴 Чому proxy-драйвер, а не звичайний `drizzle(pool)`. Контракт B5″ каже:
+ * зʼєднання беруться ЛИШЕ через `withActor` (голий пул повертає обидва тихі
+ * режими відмови, тому імпорт `simplycms/db/client` — помилка лінту). Але
+ * `drizzleAdapter` хоче ОДИН довгоживучий db-обʼєкт, а `withActor` живе рівно
+ * одну транзакцію. `drizzle-orm/pg-proxy` знімає протиріччя: він не тримає
+ * зʼєднання взагалі, а віддає кожен згенерований SQL у колбек — тож кожен
+ * запит адаптера стає власною короткою транзакцією під `app_admin`.
+ *
+ * Ціна відома й прийнята: одна транзакція на запит замість однієї на
+ * операцію. Це auth-шлях (реєстрація, вхід, читання сесії), а не гаряча
+ * траєкторія каталогу; вимірювана ціна тут дешевша за четверту роль БД або
+ * за дірку в лінт-зоні.
+ *
+ * 🔴 Роль — `app_admin`, бо саме їй видані гранти на таблиці Better Auth
+ * (0002_grants.sql, §6): контракт v2 знає рівно дві акторські ролі. Шлях
+ * мусить лишатись ВУЗЬКИМ — це не привід відкривати `app_admin` запиту
+ * загалом, і поза цим модулем `app_admin` вмикається лише після
+ * `requireOperation` (див. `./authz`).
+ */
+
+/** Роль, під якою виконуються ВСІ запити auth-контуру. */
+const AUTH_ROLE = 'app_admin' as const;
+
+/**
+ * Драйвер pg-proxy кличе колбек із `method`, і форма відповіді від нього
+ * ЗАЛЕЖИТЬ: для `'execute'` рядки віддаються як обʼєкти, для решти (`'all'`,
+ * `'values'`, `'get'`) drizzle сам мапить їх за ПОЗИЦІЄЮ колонки, тобто чекає
+ * масиви. Помилка тут не падає — вона тихо дає `undefined` у кожному полі,
+ * тому режим вибирається явно, а не «як вийде».
+ */
+const arrayMode = (method: string): boolean => method !== 'execute';
+
+/** Транзакції proxy-драйвер не підтримує — див. докблок нижче. */
+export type AuthDb = ReturnType<typeof createAuthDb>;
+
+/**
+ * Drizzle-інстанс для `drizzleAdapter`.
+ *
+ * 🔴 `drizzle-orm/pg-proxy` кидає на `db.transaction()`. Для нас це безпечно й
+ * перевірено: у `@better-auth/drizzle-adapter@1.7.1` усі виклики
+ * `db.transaction` стоять під `config.provider === 'mysql'`, а сам адаптер
+ * конфігурується з `transaction: false` (дефолт). Якщо апстрім це змінить,
+ * ми дізнаємось падінням тесту, а не тихою втратою атомарності — і це
+ * рівно та поведінка, якої ми хочемо від піну версії (B3).
+ */
+export function createAuthDb() {
+  return drizzle(async (sql, params, method) => {
+    const rows = await withActor({ role: AUTH_ROLE }, async (_db, client) => {
+      // 🔴 Дві гілки, а не один обʼєкт із `rowMode: undefined`: у типах `pg`
+      // масивний режим — ОКРЕМИЙ перевантажений виклик (`QueryArrayConfig`),
+      // і опційне поле в спільному літералі не типізується взагалі.
+      if (arrayMode(method)) {
+        const result = await client.query<unknown[]>({
+          text: sql,
+          values: params,
+          rowMode: 'array',
+        });
+        return result.rows;
+      }
+      const result = await client.query({ text: sql, values: params });
+      return result.rows as unknown[];
+    });
+    return { rows };
+  });
+}

package/src/auth/env.ts

@@ -0,0 +1,48 @@
+/**
+ * Контракт серверного env для auth-контуру (спека CLI v1 §7, Task 7).
+ *
+ * 🔴 Ключі читаються ЛИШЕ з `process.env` і ЛИШЕ в рантаймі — усередині
+ * фабрики інстансу, не на модуль-рівні. `VITE_`-префікса тут немає й бути не
+ * може: секрет підпису сесій у клієнтському бандлі — це вже не секрет.
+ * Наслідок той самий, що й у Supabase-фабрик: ротація секрету = перезапуск
+ * процесу, без перезбірки.
+ *
+ * Функції винесено з `./instance` навмисно: так контракт env перевіряється
+ * юнітом без інстансу Better Auth і без БД.
+ */
+
+/** Джерело змінних оточення (та сама форма, що в `db/client` і `supabase/keys`). */
+export interface AuthEnv {
+  readonly BETTER_AUTH_SECRET?: string;
+  readonly BETTER_AUTH_URL?: string;
+}
+
+/**
+ * Секрет підпису сесій і токенів.
+ *
+ * @throws Error якщо ключ відсутній або порожній — тихий фолбек на
+ * згенерований секрет зробив би всі сесії недійсними після кожного
+ * перезапуску, і діагноз виглядав би як «випадкові розлогіни».
+ */
+export function resolveAuthSecret(env: AuthEnv): string {
+  // `||`, а не `??`: оголошена-але-порожня змінна — це відсутній ключ.
+  const secret = env.BETTER_AUTH_SECRET || undefined;
+
+  if (!secret) {
+    throw new Error(
+      '[simplycms/auth] Відсутня змінна оточення BETTER_AUTH_SECRET — ' +
+        'нема чим підписувати сесії. Контракт серверного env — спека CLI v1 ' +
+        '§7 (лише process.env, лише в рантаймі).',
+    );
+  }
+
+  return secret;
+}
+
+/**
+ * Публічна база URL застосунку (потрібна для колбеків OAuth і посилань у
+ * листах). Опційна: без неї Better Auth виводить базу з самого запиту, чого
+ * достатньо для email/password-флоу.
+ */
+export const resolveAuthBaseUrl = (env: AuthEnv): string | undefined =>
+  env.BETTER_AUTH_URL || undefined;