simplycms 0.4.0

package/src/auth/hooks.ts

@@ -0,0 +1,94 @@
+import type { AppRole } from './authz';
+
+/**
+ * Порт `handle_new_user` у TS (B3′, Task 7) — те, що робив SQL-тригер
+ * `on_auth_user_created` на схемі GoTrue.
+ *
+ * 🔴 Інваріант `first_user_no_auto_admin` (аудит 2026-08-04) переїхав сюди
+ * РАЗОМ із логікою і мусить лишитись: перший signup НЕ стає адміном. Стара
+ * діра звалась «хто перший встиг» — реєстрація на свіжому магазині давала
+ * повний доступ будь-кому, хто випередив власника. Роль `admin` тепер видає
+ * ЛИШЕ invite власника (`./invite`) або наявний адмін. Тут ролі не
+ * обчислюються взагалі — вона константа, і саме тому діру неможливо
+ * відтворити «випадковою умовою».
+ */
+
+/** Роль КОЖНОГО новоствореного користувача. Винятків немає — див. вище. */
+export const SIGNUP_ROLE: AppRole = 'user';
+
+/** Мінімум, який Better Auth знає про щойно створеного користувача. */
+export interface NewAuthUser {
+  readonly id: string;
+  readonly email: string;
+  readonly name?: string | null;
+}
+
+/** Що саме треба записати в доменні таблиці магазину. */
+export interface UserProvisionPlan {
+  readonly userId: string;
+  readonly email: string;
+  readonly firstName: string | null;
+  readonly lastName: string | null;
+  readonly role: AppRole;
+}
+
+/** Запис плану в БД. Порт — щоб хук тестувався без Postgres. */
+export type ProvisionUser = (plan: UserProvisionPlan) => Promise<void>;
+
+/**
+ * Розбиває єдине `name` Better Auth на пару, яку чекає `profiles`.
+ *
+ * 🔴 Розрив моделей реальний: GoTrue тримав `first_name`/`last_name` у
+ * `raw_user_meta_data`, а BA має одне поле `name`. Розбиття по ПЕРШОМУ
+ * пробілу (решта — у прізвище) — свідомий компроміс: воно не «правильне» для
+ * всіх культур, зате зворотне (склеювання) завжди дає вихідний рядок.
+ */
+export function splitName(name?: string | null): {
+  firstName: string | null;
+  lastName: string | null;
+} {
+  const trimmed = (name ?? '').trim();
+  if (!trimmed) return { firstName: null, lastName: null };
+
+  const space = trimmed.indexOf(' ');
+  if (space === -1) return { firstName: trimmed, lastName: null };
+  return {
+    firstName: trimmed.slice(0, space),
+    lastName: trimmed.slice(space + 1).trim() || null,
+  };
+}
+
+/**
+ * ЧИСТА побудова плану провізії — рівно те, що можна довести юнітом без БД.
+ *
+ * Категорія покупця тут не обчислюється: у `profiles.category_id` їде
+ * категорія за замовчуванням (`user_categories.is_default`, сід `0003_seed`),
+ * і вибирає її сам INSERT підзапитом — інакше довелось би тягнути зайве
+ * читання й вирішувати, що робити з гонкою.
+ */
+export function buildUserProvision(user: NewAuthUser): UserProvisionPlan {
+  const { firstName, lastName } = splitName(user.name);
+  return {
+    userId: user.id,
+    email: user.email,
+    firstName,
+    lastName,
+    role: SIGNUP_ROLE,
+  };
+}
+
+/**
+ * `databaseHooks.user.create.after` для інстансу Better Auth.
+ *
+ * 🔴 Хук виконується ПІСЛЯ коміту створення користувача й окремою
+ * транзакцією, тобто атомарності «user + profile» немає. Це властивість
+ * `databaseHooks`, а не недогляд: єдиний спосіб дістати атомарність — вести
+ * весь signUp однією транзакцією, чого адаптер BA не дає. Наслідок треба
+ * знати: користувач без профілю можливий, якщо провізія впала, — і саме тому
+ * помилка звідси НЕ ковтається, а летить наверх, роблячи signUp невдалим.
+ */
+export const createUserCreateHook =
+  (provisionUser: ProvisionUser) =>
+  async (user: NewAuthUser): Promise<void> => {
+    await provisionUser(buildUserProvision(user));
+  };

package/src/auth/index.ts

@@ -0,0 +1,75 @@
+/**
+ * `simplycms/auth` — серверний auth-контур v2 (B3′, Task 7, В2-К1а).
+ *
+ * 🔴 К1′б: контур ПІДКЛЮЧЕНО. GoTrue знесено — `src/start.ts` питає ролі
+ * звідси, роут `/api/auth/$` віддає запити хендлеру Better Auth, а клієнт
+ * вітрини живе на `better-auth/react`. Модулів `/auth/confirm` і
+ * `/auth/callback` більше немає.
+ *
+ * 🔴 `./drizzle-proxy` і `./provision` тут НЕ реекспортуються: перший —
+ * деталь того, як адаптер BA дістає транзакцію, другий уже прибінджений
+ * дефолтом усередині `createAuth`. Назовні виходить рівно те, що споживач
+ * мусить назвати сам: інстанс, порти, чисті функції — і `ownerInviteStore`,
+ * бо invite нікуди не прибінджений і без сховища не запускається.
+ */
+export { createAuth, getAuth, resetAuth } from './instance';
+export type { AuthDeps, SimplyAuth } from './instance';
+
+export { resolveAuthSecret, resolveAuthBaseUrl } from './env';
+export type { AuthEnv } from './env';
+
+export {
+  buildUserProvision,
+  createUserCreateHook,
+  splitName,
+  SIGNUP_ROLE,
+} from './hooks';
+export type { NewAuthUser, ProvisionUser, UserProvisionPlan } from './hooks';
+
+export { acceptOwnerInvite } from './accept-invite';
+export type {
+  AcceptInviteRejection,
+  AcceptOwnerInviteInput,
+  AcceptOwnerInviteResult,
+} from './accept-invite';
+
+export {
+  issueOwnerInvite,
+  verifyOwnerInvite,
+  inviteIdentifier,
+} from './invite';
+export type {
+  InviteRejection,
+  IssueOwnerInviteInput,
+  OwnerInviteResult,
+  OwnerInviteStore,
+  VerifyOwnerInviteResult,
+} from './invite';
+
+export { ownerInviteStore, hasAnyAdmin } from './invite-store';
+
+export { renderInviteEmail, renderResetPasswordEmail } from './invite-email';
+export type {
+  InviteEmail,
+  InviteEmailInput,
+  ResetPasswordEmailInput,
+  SendInviteEmail,
+} from './invite-email';
+
+export { stubSendAuthEmail } from './send-email';
+export type { SendAuthEmail } from './send-email';
+
+export { isAdminRequest, readSessionSubject, readUserRoles } from './session';
+export type { SessionSubject } from './session';
+
+export {
+  AUTHZ_MATRIX,
+  AuthzError,
+  can,
+  dbRoleFor,
+  dbRoleForSubject,
+  requireOperation,
+  requireRole,
+  resolveGrant,
+} from './authz';
+export type { AppRole, AuthScope, AuthzSubject, Operation } from './authz';

package/src/auth/instance.ts

@@ -0,0 +1,116 @@
+import { betterAuth } from 'better-auth';
+import { drizzleAdapter } from 'better-auth/adapters/drizzle';
+import { accounts, sessions, users, verifications } from 'simplycms/schema';
+import { createAuthDb } from './drizzle-proxy';
+import { resolveAuthBaseUrl, resolveAuthSecret } from './env';
+import { createUserCreateHook, type ProvisionUser } from './hooks';
+import { renderResetPasswordEmail } from './invite-email';
+import { provisionUserInDb } from './provision';
+import { stubSendAuthEmail, type SendAuthEmail } from './send-email';
+
+/**
+ * Інстанс Better Auth серверного контуру v2 (B3′, Task 7).
+ *
+ * 🔴 Контур ще НЕ підключений до `start.ts`, роутів і клієнта — це К1′б.
+ * Тут будується робочий серверний auth ПОРУЧ із чинним GoTrue-флоу, який
+ * лишається недоторканим.
+ *
+ * 🔴 Плагінів — нуль (B3: CVE-поверхня). Кожен плагін BA додає роути й
+ * таблиці; ставити їх «про запас» означає розширювати поверхню атаки на
+ * функціональність, якою ніхто не користується.
+ */
+
+/** Схема, яку бачить адаптер. Ключі — імена МОДЕЛЕЙ (див. `usePlural`). */
+const authSchema = { users, sessions, accounts, verifications };
+
+/** Що можна підмінити ззовні — рівно стільки, скільки треба тестам. */
+export interface AuthDeps {
+  /**
+   * DB-адаптер Better Auth. За замовчуванням — drizzle над pg-proxy через
+   * `withActor`. Юніт-тести підставляють `better-auth/adapters/memory` — саме
+   * цим DoD спеки «BA тестується без Docker» виконується фактом.
+   */
+  readonly database?: Parameters<typeof betterAuth>[0]['database'];
+  /** Провізія `profiles`+`user_roles`. За замовчуванням — запис у Postgres. */
+  readonly provisionUser?: ProvisionUser;
+  readonly secret?: string;
+  readonly baseURL?: string;
+  /**
+   * Канал доставки листів. За замовчуванням — заглушка з логом
+   * (`./send-email`): SMTP лишається справою магазину, ядро лише КЛИЧЕ канал.
+   */
+  readonly sendEmail?: SendAuthEmail;
+  /** Назва магазину в темі листа. */
+  readonly storeName?: string;
+}
+
+/**
+ * Створює інстанс. Env читається ТУТ, у рантаймі — не на модуль-рівні.
+ */
+export function createAuth(deps: AuthDeps = {}) {
+  const sendEmail = deps.sendEmail ?? stubSendAuthEmail;
+  const storeName = deps.storeName ?? 'SimplyCMS';
+
+  return betterAuth({
+    secret: deps.secret ?? resolveAuthSecret(process.env),
+    baseURL: deps.baseURL ?? resolveAuthBaseUrl(process.env),
+    database:
+      deps.database ??
+      drizzleAdapter(createAuthDb(), {
+        provider: 'pg',
+        schema: authSchema,
+        // 🔴 Обовʼязково: наші таблиці названі в МНОЖИНІ (узгоджено з доменною
+        // схемою), а BA за замовчуванням шукає `user`/`session` — без цього
+        // прапорця адаптер падає на першому ж запиті.
+        usePlural: true,
+      }),
+    emailAndPassword: {
+      enabled: true,
+      // 🔴 Колбек прибіндований ЗАВЖДИ, навіть коли транспорт — заглушка.
+      // Інакше `requestPasswordReset` мовчки повертав би 200 без жодного
+      // сліду, і «лист не прийшов» неможливо було б відрізнити від
+      // «магазин не налаштував пошту».
+      sendResetPassword: async ({ user, url }) => {
+        await sendEmail(
+          renderResetPasswordEmail({ to: user.email, url, storeName }),
+        );
+      },
+    },
+    advanced: {
+      database: {
+        // 🔴 `'uuid'` — єдине значення, коректне для ОБОХ адаптерів. Драйвер
+        // drizzle-pg оголошує `supportsUUIDs`, тож id генерує сама БД
+        // (`gen_random_uuid()` дефолтом колонки, як описано в `schema/auth`);
+        // memory-адаптер UUID не підтримує, і BA згенерує його в JS. Значення
+        // `false` зламало б саме memory-контур — користувач лишався б без id.
+        generateId: 'uuid',
+      },
+    },
+    databaseHooks: {
+      user: {
+        create: {
+          after: createUserCreateHook(deps.provisionUser ?? provisionUserInDb),
+        },
+      },
+    },
+  });
+}
+
+/** Тип готового інстансу — для сигнатур споживачів К1′б. */
+export type SimplyAuth = ReturnType<typeof createAuth>;
+
+let instance: SimplyAuth | undefined;
+
+/**
+ * Інстанс процесу (лінива синглтон-фабрика) — той самий контракт «рестарт
+ * замість гарячої ротації», що й у пулу `simplycms/db`.
+ */
+export function getAuth(): SimplyAuth {
+  instance ??= createAuth();
+  return instance;
+}
+
+/** Скидає синглтон (teardown тестів, перемикання env). */
+export function resetAuth(): void {
+  instance = undefined;
+}

package/src/auth/invite-email.ts

@@ -0,0 +1,84 @@
+/**
+ * Рендер листа-запрошення власника (Task 7, В2-К1а).
+ *
+ * 🔴 Виділено чистою функцією саме тому, що ДОСТАВКА недосяжна: SMTP у цьому
+ * оточенні немає, лист шле колбек магазину. Рендер же — єдина частина, яку
+ * можна довести машинно, і вона доводиться юнітом: посилання ціле, токен не
+ * загубився, HTML-версія не ламається на лапках в імені магазину.
+ */
+
+/** Готовий лист — те, що колбек магазину віддає своєму транспорту. */
+export interface InviteEmail {
+  readonly to: string;
+  readonly subject: string;
+  readonly text: string;
+  readonly html: string;
+}
+
+/** Колбек доставки. Реалізує магазин; ядро транспорту не знає. */
+export type SendInviteEmail = (message: InviteEmail) => Promise<void>;
+
+/** Мінімальне екранування — лист збирається конкатенацією, не шаблонізатором. */
+const escapeHtml = (value: string): string =>
+  value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+
+/** Скільки годин лишилось жити токену — для тексту листа. */
+const hours = (ttlMs: number): number =>
+  Math.max(1, Math.round(ttlMs / 3_600_000));
+
+export interface InviteEmailInput {
+  readonly to: string;
+  readonly url: string;
+  readonly storeName: string;
+  readonly ttlMs: number;
+}
+
+/** Збирає лист. Мова — українська: це лист власнику магазину, не UI-рядок. */
+export function renderInviteEmail(input: InviteEmailInput): InviteEmail {
+  const ttl = hours(input.ttlMs);
+  const subject = `Запрошення власника — ${input.storeName}`;
+  const text =
+    `Вас запрошено власником магазину «${input.storeName}».\n\n` +
+    `Щоб задати пароль і увійти, відкрийте посилання:\n${input.url}\n\n` +
+    `Посилання одноразове й дійсне ${ttl} год. Якщо ви не чекали цього ` +
+    `листа — просто проігноруйте його.`;
+  const html =
+    `<p>Вас запрошено власником магазину «${escapeHtml(input.storeName)}».</p>` +
+    `<p><a href="${escapeHtml(input.url)}">Задати пароль і увійти</a></p>` +
+    `<p>Посилання одноразове й дійсне ${ttl} год.</p>`;
+
+  return { to: input.to, subject, text, html };
+}
+
+export interface ResetPasswordEmailInput {
+  readonly to: string;
+  readonly url: string;
+  readonly storeName: string;
+}
+
+/**
+ * Лист скидання пароля (К1′б).
+ *
+ * Живе поруч із запрошенням навмисно: обидва — листи auth-контуру з ОДНИМ
+ * одноразовим посиланням, і спільне екранування тут дешевше за другий модуль
+ * із власною копією тих самих чотирьох `replace`.
+ */
+export function renderResetPasswordEmail(
+  input: ResetPasswordEmailInput,
+): InviteEmail {
+  const subject = `Скидання пароля — ${input.storeName}`;
+  const text =
+    `Ви (або хтось інший) попросили скинути пароль у магазині ` +
+    `«${input.storeName}».\n\nЩоб задати новий пароль, відкрийте ` +
+    `посилання:\n${input.url}\n\nЯкщо ви цього не робили — просто ` +
+    `проігноруйте лист, пароль лишиться попереднім.`;
+  const html =
+    `<p>Запит на скидання пароля в магазині «${escapeHtml(input.storeName)}».</p>` +
+    `<p><a href="${escapeHtml(input.url)}">Задати новий пароль</a></p>`;
+
+  return { to: input.to, subject, text, html };
+}

package/src/auth/invite-store.ts

@@ -0,0 +1,89 @@
+import { eq, sql } from 'drizzle-orm';
+import { withActor } from 'simplycms/db';
+import { userRoles, users, verifications } from 'simplycms/schema';
+import type { OwnerInviteStore } from './invite';
+
+/**
+ * Сховище invite власника на Postgres (Task 7, В2-К1а).
+ *
+ * Роль — `app_admin`: гранти на таблиці Better Auth і на `user_roles` видані
+ * саме їй (0002_grants.sql, §5-§6). Той самий вузький auth-шлях, що й у
+ * `./provision`.
+ */
+export const ownerInviteStore: OwnerInviteStore = {
+  async findUserIdByEmail(email) {
+    return withActor({ role: 'app_admin' }, async (db) => {
+      const rows = await db
+        .select({ id: users.id })
+        .from(users)
+        // Пошта в БД зберігається як введена, а порівнюємо ми регістро-
+        // незалежно — інакше `Owner@site` і `owner@site` дали б двох власників.
+        .where(eq(sql`lower(${users.email})`, email.trim().toLowerCase()))
+        .limit(1);
+      return rows[0]?.id ?? null;
+    });
+  },
+
+  async createUser({ email, name }) {
+    return withActor({ role: 'app_admin' }, async (db) => {
+      const rows = await db
+        .insert(users)
+        // `emailVerified: false` — власник підтвердить пошту самим фактом
+        // переходу за одноразовим посиланням із листа.
+        .values({ email, name, emailVerified: false })
+        .returning({ id: users.id });
+      return rows[0].id;
+    });
+  },
+
+  async storeToken({ identifier, valueHash, expiresAt }) {
+    await withActor({ role: 'app_admin' }, async (db) => {
+      // Старий токен тієї ж пошти знищується: «надішли ще раз» мусить робити
+      // попереднє посилання недійсним, інакше в обігу живуть два ключі.
+      await db
+        .delete(verifications)
+        .where(eq(verifications.identifier, identifier));
+      await db
+        .insert(verifications)
+        .values({ identifier, value: valueHash, expiresAt });
+    });
+  },
+
+  async consumeToken(identifier) {
+    return withActor({ role: 'app_admin' }, async (db) => {
+      // DELETE … RETURNING — атомарне «прочитати й погасити» в одному
+      // стейтменті: два паралельні переходи за посиланням не можуть обидва
+      // побачити токен дійсним.
+      const rows = await db
+        .delete(verifications)
+        .where(eq(verifications.identifier, identifier))
+        .returning({
+          valueHash: verifications.value,
+          expiresAt: verifications.expiresAt,
+        });
+      return rows[0] ?? null;
+    });
+  },
+
+  async grantAdminRole(userId) {
+    await withActor({ role: 'app_admin' }, async (db) => {
+      await db
+        .insert(userRoles)
+        .values({ userId, role: 'admin' })
+        .onConflictDoNothing({
+          target: [userRoles.userId, userRoles.role],
+        });
+    });
+  },
+};
+
+/** Чи є в магазині хоч один адмін — потрібно CLI, щоб не слати invite двічі. */
+export const hasAnyAdmin = async (): Promise<boolean> =>
+  withActor({ role: 'app_admin' }, async (db) => {
+    const rows = await db
+      .select({ id: userRoles.id })
+      .from(userRoles)
+      .where(eq(userRoles.role, 'admin'))
+      .limit(1);
+    return rows.length > 0;
+  });

package/src/auth/invite.ts

@@ -0,0 +1,144 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { renderInviteEmail, type SendInviteEmail } from './invite-email';
+
+/**
+ * Invite власника — заміна механіки `inviteUserByEmail` (Task 7, В2-К1а).
+ *
+ * 🔴 Що змінилось по суті. У GoTrue лист будував сам Supabase за шаблоном
+ * `supabase/templates/invite.html`, і перевірити рендер було нічим. Тепер
+ * токен випускаємо МИ, лист рендеримо МИ (`./invite-email`), а шле його
+ * колбек магазину — тож усе, крім SMTP-доставки, стає юніт-тестовним.
+ * SMTP лишається боргом оточення (доводиться в власника).
+ *
+ * 🔴 У БД лягає лише SHA-256 токена. Дамп таблиці `verifications` не має
+ * давати дійсного посилання: цим invite відрізняється від «просто рядка з
+ * секретом».
+ */
+
+/** Порт сховища. Реалізація на Postgres — `./invite-store`. */
+export interface OwnerInviteStore {
+  findUserIdByEmail(email: string): Promise<string | null>;
+  createUser(input: { email: string; name: string }): Promise<string>;
+  storeToken(input: {
+    identifier: string;
+    valueHash: string;
+    expiresAt: Date;
+  }): Promise<void>;
+  consumeToken(
+    identifier: string,
+  ): Promise<{ valueHash: string; expiresAt: Date } | null>;
+  grantAdminRole(userId: string): Promise<void>;
+}
+
+const DEFAULT_TTL_MS = 24 * 3_600_000;
+
+/** Ключ запису у `verifications`. Пошта — у нижньому регістрі: вона й є ключ. */
+export const inviteIdentifier = (email: string): string =>
+  `owner-invite:${email.trim().toLowerCase()}`;
+
+const hashToken = (token: string): string =>
+  createHash('sha256').update(token).digest('hex');
+
+export interface IssueOwnerInviteInput {
+  readonly store: OwnerInviteStore;
+  readonly sendEmail: SendInviteEmail;
+  readonly email: string;
+  readonly siteUrl: string;
+  readonly storeName?: string;
+  readonly ttlMs?: number;
+  readonly now?: Date;
+  /** Тільки для тестів: детермінований токен замість випадкового. */
+  readonly token?: string;
+}
+
+export interface OwnerInviteResult {
+  readonly userId: string;
+  /** `false` — користувач уже існував: повторний invite його не дублює. */
+  readonly created: boolean;
+  readonly url: string;
+}
+
+/**
+ * Випускає запрошення. Ідемпотентно щодо КОРИСТУВАЧА: повторний виклик на ту
+ * саму пошту не створює другого рядка `users` і не дублює роль — він лише
+ * перевипускає токен. Саме так поводився старий `owner:invite` (гілка
+ * `email_exists`), і саме цю поведінку власник очікує від «надішли ще раз».
+ */
+export async function issueOwnerInvite(
+  input: IssueOwnerInviteInput,
+): Promise<OwnerInviteResult> {
+  const email = input.email.trim().toLowerCase();
+  const ttlMs = input.ttlMs ?? DEFAULT_TTL_MS;
+  const now = input.now ?? new Date();
+
+  const existing = await input.store.findUserIdByEmail(email);
+  const userId =
+    existing ?? (await input.store.createUser({ email, name: email }));
+
+  const token = input.token ?? randomBytes(32).toString('base64url');
+  await input.store.storeToken({
+    identifier: inviteIdentifier(email),
+    valueHash: hashToken(token),
+    expiresAt: new Date(now.getTime() + ttlMs),
+  });
+
+  // Роль закріплюється НЕ хуком signUp (той дає рівно `user` — інваріант
+  // `first_user_no_auto_admin`), а саме тут: invite власника і є єдиний
+  // легальний шлях до `admin` на чистому магазині.
+  await input.store.grantAdminRole(userId);
+
+  const url =
+    `${input.siteUrl.replace(/\/$/, '')}/auth/invite` +
+    `?email=${encodeURIComponent(email)}&token=${encodeURIComponent(token)}`;
+
+  await input.sendEmail(
+    renderInviteEmail({
+      to: email,
+      url,
+      storeName: input.storeName ?? 'SimplyCMS',
+      ttlMs,
+    }),
+  );
+
+  return { userId, created: existing === null, url };
+}
+
+/** Чому запрошення не прийнято — рівно ті випадки, які має розрізняти UI. */
+export type InviteRejection = 'not-found' | 'expired' | 'mismatch';
+
+export type VerifyOwnerInviteResult =
+  | { readonly ok: true; readonly userId: string }
+  | { readonly ok: false; readonly reason: InviteRejection };
+
+/**
+ * Перевіряє токен і СПОЖИВАЄ його (одноразовість).
+ *
+ * 🔴 Порівняння хешів — `timingSafeEqual`, а не `===`: обидва рядки однакової
+ * довжини й повністю контрольовані зловмисником, тобто це класичний випадок,
+ * де побайтове раннє повернення тече в тайминг.
+ *
+ * Прив'язку пароля робить К1′б: тут доводиться лише «токен дійсний і це той
+ * самий користувач».
+ */
+export async function verifyOwnerInvite(input: {
+  store: OwnerInviteStore;
+  email: string;
+  token: string;
+  now?: Date;
+}): Promise<VerifyOwnerInviteResult> {
+  const email = input.email.trim().toLowerCase();
+  const now = input.now ?? new Date();
+
+  const record = await input.store.consumeToken(inviteIdentifier(email));
+  if (!record) return { ok: false, reason: 'not-found' };
+  if (record.expiresAt.getTime() <= now.getTime())
+    return { ok: false, reason: 'expired' };
+
+  const actual = Buffer.from(hashToken(input.token), 'hex');
+  const expected = Buffer.from(record.valueHash, 'hex');
+  if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+    return { ok: false, reason: 'mismatch' };
+
+  const userId = await input.store.findUserIdByEmail(email);
+  return userId ? { ok: true, userId } : { ok: false, reason: 'not-found' };
+}

package/src/auth/provision.ts

@@ -0,0 +1,34 @@
+import { sql } from 'drizzle-orm';
+import { withActor } from 'simplycms/db';
+import { profiles, userRoles } from 'simplycms/schema';
+import type { ProvisionUser } from './hooks';
+
+/**
+ * Реалізація порту провізії на Postgres (Task 7, В2-К1а).
+ *
+ * Роль — `app_admin`: політики `profiles_admin_all` і `user_roles_admin_all`
+ * дозволяють запис саме їй, а покупець свій профіль лише читає й редагує
+ * (0002_grants.sql, §4). Це той самий вузький auth-шлях, що й у
+ * `./drizzle-proxy`.
+ */
+export const provisionUserInDb: ProvisionUser = async (plan) => {
+  await withActor({ role: 'app_admin' }, async (db) => {
+    await db.insert(profiles).values({
+      userId: plan.userId,
+      email: plan.email,
+      firstName: plan.firstName,
+      lastName: plan.lastName,
+      // 🔴 Підзапитом, а не окремим SELECT: категорія за замовчуванням
+      // читається В ТІЙ САМІЙ транзакції, тож між читанням і записом ніхто
+      // не встигне перемкнути прапорець `is_default`.
+      categoryId: sql`(select id from public.user_categories where is_default limit 1)`,
+    });
+
+    // `onConflictDoNothing` — повторна провізія (ретрай хука після мережевого
+    // збою) не має падати на унікальності `(user_id, role)`.
+    await db
+      .insert(userRoles)
+      .values({ userId: plan.userId, role: plan.role })
+      .onConflictDoNothing();
+  });
+};

package/src/auth/send-email.ts

@@ -0,0 +1,26 @@
+import type { InviteEmail } from './invite-email';
+
+/**
+ * Канал доставки листів auth-контуру (К1′б).
+ *
+ * 🔴 SMTP тут НЕ реалізується — рішення власника: доставку він налаштовує й
+ * перевіряє локально. Ядро зобовʼязане лише КЛИКАТИ канал у всіх точках, де
+ * лист має піти, щоб магазину лишалося підставити одну функцію, а не шукати
+ * місця виклику.
+ */
+export type SendAuthEmail = (message: InviteEmail) => Promise<void>;
+
+/**
+ * Заглушка за замовчуванням: пише лист у лог замість відправки.
+ *
+ * 🔴 TODO(К6): підмінити реальним транспортом магазину. Мовчки ковтати лист
+ * не можна — посилання для скидання пароля й запрошення власника тоді
+ * зникали б безслідно, і діагноз виглядав би як «пошта не приходить».
+ * Лог лишає їх видимими в консолі сервера.
+ */
+export const stubSendAuthEmail: SendAuthEmail = async (message) => {
+  console.warn(
+    '[simplycms/auth] Лист НЕ надіслано (транспорт не налаштовано). ' +
+      `Кому: ${message.to}. Тема: ${message.subject}.\n${message.text}`,
+  );
+};