test: синхронизировать electron-smoke с smoke.test.ts (login реализован)

electron-smoke ассертил login/getAccessToken → NotImplemented (старый скелет Story 1.2), но login реализован (flow-executor Story 11.2): в stub-окружении даёт AuthV2Error(network_error)/(wallet_locked). Node/browser smoke уже обновлены — ждут любой валидный код AuthV2ErrorCode. Привёл electron к тому же; конкретный код не пиннингуем. Это была единственная упавшая из 6 проверок electron.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.env.example

@@ -39,3 +39,14 @@ MINIO_ROOT_PASSWORD=minioadmin
 CHAIN_URL=http://127.0.0.1:8888
 API_URL=http://127.0.0.1:2998/v1/graphql
 MONGODB_URL=mongodb://127.0.0.1:27017
+
+# --- CoopID (overlays docker-compose.authentik.yml + docker-compose.edge.yml) ---
+# Поднимаются только явной цепочкой -f (см. infra/coopid/README.md);
+# перед первым запуском: bash scripts/coopid-gen-secrets.sh
+# К портам применяется то же правило offset = (INSTANCE_INDEX - 1) * 10.
+COOP_PG_HOST_PORT=5632
+AUTHENTIK_HOST_PORT=9008
+CADDY_HTTP_PORT=8088
+CADDY_HTTPS_PORT=8443
+# Домен кооператива для caddy: localhost = dev self-signed; реальный домен = Let's Encrypt.
+COOPID_DOMAIN=localhost

.github/workflows/release.yaml

@@ -1,49 +1,45 @@
 name: Release
 
-# Единый релизный workflow по push'у тэга `v*`.
+# Релизный workflow по push'у в testnet/main (FF-промоушн-модель, см.
+# scripts/RELEASE.md).
 #
 # Порядок (через jobs.needs):
 #   1) release             — контракты + контейнеры + webhook деплоя (атомарно)
-#   2) publish-packages    — npm publish через lerna (если не -alpha)
-#   3) publish-docs        — mkdocs + standards-site → gh-pages (если не -alpha + ветка main)
-#   4) trigger-coopenomics — repository_dispatch в coopenomics/coopenomics (тот же гейт, что docs)
+#   2) publish-packages    — npm publish через lerna (только ветка main)
+#   3) trigger-coopenomics — workflow_dispatch сборки сайта C9S/coopenomics на
+#                            Gitea (только ветка main); он сам тянет mono и
+#                            пересобирает доки.
+#
+# publish-docs (gh-pages на github.com) удалён 2026-05-25 — после переезда на
+# Gitea Pages-публикация невалидна; доки деплоятся через C9S/coopenomics.
 #
 # Зачем последовательно: пакеты/доки/внешний триггер не должны уезжать,
-# если релиз контрактов или контейнеров провалился. Раньше четыре workflow'а
-# стартовали параллельно по одному тэгу — отсюда гонка из инцидента 2026-05-13
-# с ledger2 walletop sweep'ом (см. историю release.yaml до объединения).
+# если релиз контрактов или контейнеров провалился.
 #
-# Гейт `-alpha` унифицирован: пакеты + доки + триггер docs пропускают только
-# не-alpha тэги. -beta/-rc/-test в проекте не используются (см. CLAUDE.md),
-# поэтому проще иметь один паттерн `!contains(github.ref, '-alpha')`.
-# IS_PROD в release-job остаётся на `(alpha|beta|rc|test)` — он определяет
-# деплой-webhook (testnet vs production) и тэг `:latest` у образов;
-# намеренно строже, чтобы случайный -rc-тэг не уехал на прод.
+# Триггер — push в testnet/main с изменением lerna.json. Версию бампает
+# `lerna version` ОДИН раз на dev (scripts/cut-release.sh); тот же коммит едет
+# вверх по fast-forward (scripts/promote.sh). lerna.json меняется только на
+# релизном бампе, поэтому обычные feature-пуши деплой не триггерят. dev в
+# триггере НЕТ: cut на dev только бампает версию, деплой начинается с testnet
+# (staging) и завершается main (production).
 #
-# Резолв ветки. Тэг семантики окружения не несёт (например `v2026.5.13-alpha-2`
-# может лежать на testnet или dev — определяет именно ветка, на которую сделан
-# merge перед тэгом). Поэтому ищем первое совпадение SHA с remote-ветками
-# main/testnet/dev. branch экспортируется как outputs.branch для downstream jobs.
+# Окружение определяет ВЕТКА (main → production, testnet → staging), а не
+# суффикс версии: единая версия едет во все среды, поэтому source of truth —
+# ветка, на которую сделан промоушн. Версия читается из закоммиченного
+# lerna.json. Гейты npm-publish/доки — `branch == main`.
 
 on:
   push:
-    tags:
-      - 'v*'
+    branches: [testnet, main]
+    paths:
+      - 'lerna.json'
+  workflow_dispatch:
 
 permissions:
   contents: write
 
 jobs:
-  # Гейт TS-типов перед сборкой образов. Reusable workflow `typecheck.yaml`
-  # запускает vue-tsc на desktop и tsc --noEmit на controller. Нужно потому,
-  # что `lerna run build` в корневом Dockerfile НЕ ловит TS-ошибки:
-  # quasar build идёт через esbuild с выключенным vueTsc, а у controller'а
-  # build-скрипта вообще нет (ts-node в рантайме).
-  typecheck:
-    uses: ./.github/workflows/typecheck.yaml
-
   release:
-    needs: typecheck
     runs-on: ubuntu-latest
     outputs:
       tag_name: ${{ steps.resolve.outputs.tag_name }}
@@ -55,22 +51,22 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Resolve branch, build mode and tags
+      - name: Resolve branch, build mode and version
         id: resolve
         run: |
-          TAG_NAME="${{ github.ref_name }}"
+          # Ветка — это ветка push'а (или выбранная в workflow_dispatch).
+          BRANCH="${{ github.ref_name }}"
           SHA="${{ github.sha }}"
-          BRANCH=""
-          for candidate in main testnet dev; do
-            if git branch -r --contains "$SHA" 2>/dev/null | grep -qE "^[[:space:]]*origin/${candidate}$"; then
-              BRANCH="$candidate"
-              break
-            fi
-          done
-          if [ -z "$BRANCH" ]; then
-            echo "::error::Тэг $TAG_NAME ($SHA) не лежит ни на одной из dev/testnet/main"
+
+          # Версия — из закоммиченного lerna.json. Её бампит lerna version ОДИН
+          # раз на dev (scripts/cut-release.sh), и тот же коммит едет по FF в
+          # testnet/main. Тэг как триггер больше не используется.
+          RAW_VERSION="$(sed -nE 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p' lerna.json | head -1)"
+          if [ -z "$RAW_VERSION" ]; then
+            echo "::error::Не удалось прочитать version из lerna.json"
             exit 1
           fi
+          TAG_NAME="v${RAW_VERSION}"
 
           case "$BRANCH" in
             main)
@@ -88,17 +84,22 @@ jobs:
               CONTRACTS_TAG=dev
               CONTRACTS_EXTRA=
               ;;
+            *)
+              echo "::error::Неподдерживаемая ветка $BRANCH (ожидались testnet/main/dev)"
+              exit 1
+              ;;
           esac
 
-          # IS_PROD определяет webhook деплоя (PRODUCTION vs TESTNET) и тэг :latest.
-          # Сознательно строже гейта publish-* — случайный -rc/-beta тэг не должен
-          # уехать на прод-вебхук, даже если в npm/docs его опубликовали.
-          if [[ "$TAG_NAME" =~ -(alpha|beta|rc|test) ]]; then
-            IS_PROD=false
-            WEBHOOK_URL='${{ vars.TESTNET_WEBHOOK_URL }}'
-          else
+          # Окружение деплоя определяет ВЕТКА: main → production, иначе → testnet.
+          # IS_PROD управляет деплой-webhook (PRODUCTION vs TESTNET) и тэгом :latest
+          # у образов. Раньше критерием был суффикс -alpha у тэга; теперь единая
+          # версия едет во все среды, поэтому источник истины — ветка промоушна.
+          if [ "$BRANCH" = "main" ]; then
             IS_PROD=true
             WEBHOOK_URL='${{ vars.PRODUCTION_WEBHOOK_URL }}'
+          else
+            IS_PROD=false
+            WEBHOOK_URL='${{ vars.TESTNET_WEBHOOK_URL }}'
           fi
 
           {
@@ -127,14 +128,41 @@ jobs:
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       # === Этап 1: контракты ===
+      # CDT ставим из .deb (C9S/cdt v4.2.0) прямо в окружение job'а и
+      # компилируем напрямую — БЕЗ вложенного docker. Почему не build-all.sh:
+      # тот монтирует $(pwd):/project в sibling-контейнер, а под Gitea
+      # act_runner сам job исполняется в контейнере → хостовый демон не видит
+      # этот путь, /project пуст, cmake падает "no CMakeLists.txt".
+      # build-all.sh остаётся для локальной сборки (оборачивает тот же
+      # build_contracts_cdt.sh в docker).
+      # CMakeLists хардкодит toolchain /cdt/build/...; .deb кладёт CDT в
+      # /usr/opt/cdt/4.2.0, а сам CDTWasmToolchain.cmake указывает на /usr
+      # абсолютно — поэтому симлинк /cdt/build → /usr/opt/cdt/4.2.0 сводит пути
+      # без правки CMakeLists.
 
-      - name: Pull CDT toolchain image
-        run: docker pull dicoop/blockchain_v5.1.1:dev
+      - name: Install CDT 4.2.0 toolchain (.deb)
+        run: |
+          SUDO=""; [ "$(id -u)" -ne 0 ] && SUDO="sudo"
+          $SUDO apt-get update
+          # build-essential — для host-компилятора (project() в CMakeLists);
+          # libz3-4/libtinfo6/libxml2/zlib1g — рантайм бинарей CDT (clang-9,
+          # ld.lld и т.д.). Пакет cdt объявляет только libcurl4-gnutls-dev,
+          # поэтому остальные .so ставим явно — в образе dicoop/blockchain они
+          # были из сборки исходников, из .deb не тянутся.
+          $SUDO apt-get install -y --no-install-recommends \
+            curl ca-certificates cmake make build-essential \
+            libz3-4 libtinfo6 libxml2 zlib1g
+          curl -fsSL -o /tmp/cdt.deb \
+            https://git.coopenomics.world/C9S/cdt/releases/download/v4.2.0/cdt_4.2.0-1_amd64.deb
+          $SUDO apt-get install -y /tmp/cdt.deb
+          $SUDO mkdir -p /cdt
+          $SUDO ln -sfn /usr/opt/cdt/4.2.0 /cdt/build
+          cdt-cpp --version || true
 
       - name: Compile contracts
         working-directory: components/contracts
         run: |
-          ./build-all.sh "$BUILD_MODE"
+          ./build_contracts_cdt.sh "$BUILD_MODE"
           echo "--- build/contracts ---"
           ls -la build/contracts/
 
@@ -215,6 +243,17 @@ jobs:
       - name: Build and push contracts image
         working-directory: components/contracts
         run: |
+          # Ретрай push'а: резолвинг registry-1.docker.io на runner'е изредка
+          # моргает (DNS-таймаут к 127.0.0.53) — 3 попытки с паузой.
+          dpush() {
+            local ref="$1" n=1
+            until docker push "$ref"; do
+              [ "$n" -ge 3 ] && { echo "::error::docker push $ref не удался после $n попыток"; return 1; }
+              echo "::warning::docker push $ref упал (попытка $n/3) — повтор через 10с"
+              n=$((n+1)); sleep 10
+            done
+          }
+
           IMAGE="dicoop/contracts"
           SHORT_SHA="${SHA::7}"
           docker build \
@@ -223,14 +262,14 @@ jobs:
             --label "build.mode=$BUILD_MODE" \
             -t "$IMAGE:$CONTRACTS_TAG" \
             ./docker/.context
-          docker push "$IMAGE:$CONTRACTS_TAG"
+          dpush "$IMAGE:$CONTRACTS_TAG"
 
           docker tag "$IMAGE:$CONTRACTS_TAG" "$IMAGE:$CONTRACTS_TAG-$SHORT_SHA"
-          docker push "$IMAGE:$CONTRACTS_TAG-$SHORT_SHA"
+          dpush "$IMAGE:$CONTRACTS_TAG-$SHORT_SHA"
 
           if [ -n "$CONTRACTS_EXTRA" ]; then
             docker tag "$IMAGE:$CONTRACTS_TAG" "$IMAGE:$CONTRACTS_EXTRA"
-            docker push "$IMAGE:$CONTRACTS_EXTRA"
+            dpush "$IMAGE:$CONTRACTS_EXTRA"
           fi
 
       - name: Verify pushed contracts image
@@ -243,15 +282,31 @@ jobs:
 
       - name: Build and push base image
         run: |
+          dpush() {
+            local ref="$1" n=1
+            until docker push "$ref"; do
+              [ "$n" -ge 3 ] && { echo "::error::docker push $ref не удался после $n попыток"; return 1; }
+              echo "::warning::docker push $ref упал (попытка $n/3) — повтор через 10с"
+              n=$((n+1)); sleep 10
+            done
+          }
           docker build --target runtime -t "dicoop/mono-base:$TAG_NAME" .
-          docker push "dicoop/mono-base:$TAG_NAME"
+          dpush "dicoop/mono-base:$TAG_NAME"
           if [ "$IS_PROD" = "true" ]; then
             docker tag "dicoop/mono-base:$TAG_NAME" dicoop/mono-base:latest
-            docker push dicoop/mono-base:latest
+            dpush dicoop/mono-base:latest
           fi
 
       - name: Build and push service images
         run: |
+          dpush() {
+            local ref="$1" n=1
+            until docker push "$ref"; do
+              [ "$n" -ge 3 ] && { echo "::error::docker push $ref не удался после $n попыток"; return 1; }
+              echo "::warning::docker push $ref упал (попытка $n/3) — повтор через 10с"
+              n=$((n+1)); sleep 10
+            done
+          }
           build_service() {
             local SVC="$1" PKG="$2" CMD="$3"
             local DOCKERFILE="Dockerfile.$SVC"
@@ -260,10 +315,10 @@ jobs:
               echo "CMD [\"pnpm\", \"-F\", \"$PKG\", \"run\", \"$CMD\"]"
             } > "$DOCKERFILE"
             docker build -t "dicoop/$SVC:$TAG_NAME" -f "$DOCKERFILE" .
-            docker push "dicoop/$SVC:$TAG_NAME"
+            dpush "dicoop/$SVC:$TAG_NAME"
             if [ "$IS_PROD" = "true" ]; then
               docker tag "dicoop/$SVC:$TAG_NAME" "dicoop/$SVC:latest"
-              docker push "dicoop/$SVC:latest"
+              dpush "dicoop/$SVC:latest"
             fi
           }
 
@@ -285,14 +340,16 @@ jobs:
 
   # ============================================================================
   # publish-packages — npm publish (бывший publish-packages.yaml).
-  # Гейт: не-alpha. Не зависит от ветки.
+  # Гейт: ветка main. Версия для publish — из закоммиченного package.json
+  # (lerna publish from-package); её бампит cut-release.sh на dev, тот же коммит
+  # доезжает до main по FF.
   # Жёстко прибиваем версию pnpm, которой сгенерён lockfile (lockfileVersion 9.0
   # = pnpm 9/10). Иначе action-setup может подтянуть другую версию и переписать
   # pnpm-lock.yaml → Lerna EUNCOMMIT.
   # ============================================================================
   publish-packages:
     needs: release
-    if: ${{ !contains(github.ref, '-alpha') }}
+    if: ${{ needs.release.outputs.branch == 'main' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -314,149 +371,44 @@ jobs:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
   # ============================================================================
-  # publish-docs — mkdocs + standards-site → gh-pages (бывший publish-docs.yaml).
-  # Гейт: не-alpha + ветка main.
-  # ВНИМАНИЕ: gh-pages step пушит на github.com/coopenomics/mono — это GitHub
-  # Pages. При переезде на Gitea Actions нужно будет либо подложить PAT для
-  # внешнего push'а в GitHub, либо переключить публикацию на Gitea Pages.
-  # ============================================================================
-  publish-docs:
-    needs: release
-    if: ${{ !contains(github.ref, '-alpha') && needs.release.outputs.branch == 'main' }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      # Версия pnpm берётся из `packageManager` корневого package.json,
-      # синхронно с publish-packages job'ом и Dockerfile'ами.
-      - name: Set up pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: pnpm
-
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.10'
-
-      - name: Install Python requirements
-        run: |
-          python -m venv venv
-          source venv/bin/activate
-          pip install mkdocs-material mkdocs-macros-plugin mkdocs-section-index pymdown-extensions
-        working-directory: ./components/docs
-
-      - name: Install Node.js dependencies
-        run: pnpm install
-        working-directory: ./components/docs
-
-      - name: Patch spectaql-config.yml for CI
-        run: |
-          sed -i.bak "0,/url:.*/s|url:.*|url: 'https://testnet.coopenomics.world/backend/v1/graphql'|" spectaql-config.yml
-        working-directory: ./components/controller
-
-      - name: Show patched spectaql-config.yml
-        run: cat spectaql-config.yml
-        working-directory: ./components/controller
-
-      - name: Build cooptypes
-        run: pnpm run build
-        working-directory: ./components/cooptypes
-
-      - name: Generate controller docs
-        run: pnpm run docs
-        working-directory: ./components/controller
-
-      - name: Copy controller docs
-        run: |
-          mkdir -p ./components/docs/docs/graphql
-          cp -r ./components/controller/docs/* ./components/docs/docs/graphql/
-
-      - name: Generate sdk docs
-        run: pnpm run docs
-        working-directory: ./components/sdk
-
-      - name: Copy sdk docs
-        run: |
-          mkdir -p ./components/docs/docs/sdk
-          cp -r ./components/sdk/docs/* ./components/docs/docs/sdk/
-
-      - name: Generate cooptypes docs
-        run: pnpm run docs
-        working-directory: ./components/cooptypes
-
-      - name: Copy cooptypes docs
-        run: |
-          mkdir -p ./components/docs/docs/cooptypes
-          cp -r ./components/cooptypes/docs/* ./components/docs/docs/cooptypes/
-
-      # ── standards-site → /standards/ на docs.цифровой-кооператив.рф ──
-      # Отдельный Vue-сайт с BPMN-графом кооперативных стандартов,
-      # публикуется как поддиректория на том же домене. Vite собирает
-      # с base='/standards/' (см. vite.config.ts), относительные пути
-      # внутри dist/ и hash-router работают корректно.
-      # dist кладём в docs/standards/ ДО mkdocs build — так же, как
-      # graphql/sdk/cooptypes; mkdocs сам включит его в итоговый site/.
-      - name: Build standards-site
-        run: pnpm run build
-        working-directory: ./components/contracts/standards-site
-
-      - name: Copy standards-site into docs/standards
-        run: |
-          mkdir -p ./components/docs/docs/standards
-          cp -r ./components/contracts/standards-site/dist/* ./components/docs/docs/standards/
-
-      - name: Build docs (mkdocs)
-        run: |
-          source venv/bin/activate
-          mkdocs build
-        working-directory: ./components/docs
-
-      - name: Remove specific large file before publishing
-        run: |
-          rm -f ./components/docs/site/sdk/typedoc.json
-          if [ -f "./components/docs/site/sdk/typedoc.json" ]; then
-            echo "ERROR: typedoc.json still exists!"
-            exit 1
-          else
-            echo "SUCCESS: typedoc.json removed successfully"
-          fi
-
-      - name: Publish to GitHub Pages
-        run: npx gh-pages --nojekyll -d site --repo https://x-access-token:${GITHUB_TOKEN}@github.com/coopenomics/mono.git
-        working-directory: ./components/docs
-        env:
-          GIT_AUTHOR_NAME: github-actions
-          GIT_AUTHOR_EMAIL: github-actions@github.com
-          GIT_COMMITTER_NAME: github-actions
-          GIT_COMMITTER_EMAIL: github-actions@github.com
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Trigger docs deployment webhook
-        if: ${{ success() }}
-        run: |
-          curl -X POST "${{ vars.DOCS_DEPLOY_WEBHOOK_URL }}" \
-            -H 'Content-Type: application/json' \
-            -d '{"ref":"${{ github.ref }}","sha":"${{ github.sha }}","branch":"${{ github.ref_name }}"}'
-
-  # ============================================================================
-  # trigger-coopenomics-docs — repository_dispatch в coopenomics/coopenomics
-  # (бывший build-contracts-docs.yaml). Гейт идентичен publish-docs.
+  # trigger-coopenomics-docs — пересборка сайта C9S/coopenomics.
+  # Гейт: ветка main.
+  #
+  # coopenomics переехал на Gitea (C9S/coopenomics); его publish-docs.yaml
+  # клонирует mono и пересобирает сайт. Gitea НЕ имеет API для
+  # repository_dispatch — только workflow_dispatch, поэтому дёргаем целевой
+  # workflow через Gitea API с PAT (secret DOCS_DISPATCH_TOKEN — префикс GITEA_
+  # у секретов зарезервирован Gitea, нельзя; права write на C9S/coopenomics).
+  # Целевой workflow слушает workflow_dispatch с входами
+  # mono_sha/mono_ref.
   # ============================================================================
   trigger-coopenomics-docs:
     needs: release
-    if: ${{ !contains(github.ref, '-alpha') && needs.release.outputs.branch == 'main' }}
+    if: ${{ needs.release.outputs.branch == 'main' }}
     runs-on: ubuntu-latest
     steps:
-      - name: Trigger Coopenomics deployment
-        uses: peter-evans/repository-dispatch@v2
-        with:
-          token: ${{ secrets.COOPENOMICS_PAT }}
-          repository: coopenomics/coopenomics
-          event-type: deploy_from_mono
-          client-payload: '{"repository": "${{ github.repository }}", "sha": "${{ github.sha }}", "ref": "${{ github.ref }}", "actor": "${{ github.actor }}"}'
+      - name: Trigger coopenomics website rebuild (Gitea workflow_dispatch)
+        run: |
+          curl -fsSL -X POST \
+            -H "Authorization: token ${{ secrets.DOCS_DISPATCH_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            -d '{"ref":"master","inputs":{"mono_sha":"${{ github.sha }}","mono_ref":"${{ github.ref }}"}}' \
+            "${{ github.server_url }}/api/v1/repos/C9S/coopenomics/actions/workflows/publish-docs.yaml/dispatches"
+
+  # ============================================================================
+  # trigger-mono-docs — деплой ВТОРОЙ документации (сайт доков mono) через
+  # webhook DOCS_DEPLOY_WEBHOOK_URL. Отдельная от coopenomics публикация —
+  # обе доки уезжают синхронно по релизу. Извлечён из бывшего publish-docs:
+  # gh-pages на github.com выпилен как мёртвый, остался реальный deploy-webhook
+  # (приёмник деплоит доки на своей стороне). Гейт: ветка main.
+  # ============================================================================
+  trigger-mono-docs:
+    needs: release
+    if: ${{ needs.release.outputs.branch == 'main' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger docs deployment webhook
+        run: |
+          curl -fsSL -X POST "${{ vars.DOCS_DEPLOY_WEBHOOK_URL }}" \
+            -H 'Content-Type: application/json' \
+            -d '{"ref":"${{ github.ref }}","sha":"${{ github.sha }}","branch":"${{ github.ref_name }}"}'

.github/workflows/sdk-cross-runtime.yaml

@@ -0,0 +1,59 @@
+name: SDK cross-runtime
+
+# Story 9.13 (CoopID, Эпик 9): smoke-тесты @coopenomics/auth на трёх рантаймах —
+# Node (vitest), браузер (vitest browser mode + chromium), desktop-runtime
+# (electron, main-process против собранного dist). SDK уходит клиентам в три
+# разных рантайма, и регрессия вида «crypto.subtle недоступен / bundle не
+# грузится в браузере» не ловится Node-юнитами вовсе.
+#
+# Триггер — только изменения самого пакета: прогон тяжёлый (браузер + electron
+# + xvfb), на каждый PR в dev его гонять незачем.
+
+on:
+  pull_request:
+    branches: [dev]
+    paths:
+      - 'components/auth/**'
+      - '.github/workflows/sdk-cross-runtime.yaml'
+  workflow_call:
+
+concurrency:
+  group: sdk-cross-runtime-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  cross-runtime:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.33.0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install workspace deps
+        run: pnpm install --frozen-lockfile --filter @coopenomics/auth...
+
+      # xvfb — electron на Linux требует X-сервер; браузеры playwright ставим
+      # вместе с системными библиотеками chromium (--with-deps).
+      - name: Install runtime prerequisites
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y xvfb
+          # test:electron поднимает реальный electron — ему нужны GTK/ATK/ALSA-библиотеки,
+          # которых нет в наборе `playwright --with-deps chromium` (chromium на другом тулките).
+          # Симптом без них: electron «error while loading shared libraries: libgtk-3.so.0».
+          # Ubuntu 24.04 (noble) — пакеты с суффиксом t64; ставим по одному, чтобы расхождение
+          # имени пакета не валило весь шаг.
+          for pkg in libgtk-3-0t64 libnotify4 libnss3 libxss1 libxtst6 libatspi2.0-0t64 libasound2t64; do
+            sudo apt-get install -y "$pkg" || true
+          done
+          cd components/auth && pnpm exec playwright install --with-deps chromium
+
+      - name: Run cross-runtime smoke
+        run: pnpm test:cross-runtime

.github/workflows/typecheck.yaml

@@ -13,17 +13,25 @@ name: Typecheck
 #
 # Триггеры:
 #  - pull_request на dev — гейт перед мерджем в основную ветку;
-#  - workflow_call — переиспользуется из release.yaml как `needs:` у release-job,
-#    чтобы битый тэг не уехал в DockerHub.
+#  - workflow_call — оставлен для переиспользования, но release.yaml его
+#    больше НЕ вызывает (гейт из релиза убран как избыточный — типы
+#    проверяются на PR в dev до того, как код доедет до тэга).
 #
-# Push в dev/testnet/main НЕ триггерит — намеренно (PR-гейт достаточен,
-# а тэги покрывает workflow_call из release.yaml).
+# Push в dev/testnet/main НЕ триггерит — намеренно (PR-гейт на dev достаточен).
 
 on:
   pull_request:
     branches: [dev]
   workflow_call:
 
+# Новый push в PR-ветку отменяет ещё бегущий typecheck по той же ветке —
+# иначе 30-минутные прогоны копятся очередью. Группа по head_ref (исходная
+# ветка PR), для workflow_call fallback на ref. Отмена только своих же
+# прежних прогонов, разные PR друг друга не трогают.
+concurrency:
+  group: typecheck-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   desktop:
     runs-on: ubuntu-latest

.gitignore

@@ -1,4 +1,5 @@
 node_modules/
+node_modules
 lerna-debug.log
 components/controller/graph.png
 blockchain-data/
@@ -22,3 +23,8 @@ components/contracts/cpp/ledger2/scripts/out/
 
 .env.testnet
 .pnpm-store
+schema.gql
+.claude
+
+# CoopID: file-based Docker Secrets (генерируются scripts/coopid-gen-secrets.sh)
+infra/coopid/secrets/

CLAUDE.md

@@ -38,6 +38,8 @@ ln -s /home/admin/mono-ai-4/components/controller/.env $WT/components/controller
 
 **Базовая ветка mono-ai-1 — `dev`.** Прямые коммиты в `dev` для мелких фиксов разрешены и не требуют feature-ветки/PR (отменено 2026-05-22 пользователем). Для крупных задач — feature-ветка (`feat/...` или `fix/...`) от dev и PR в dev; merge делает пользователь на GitHub. Push в `main` / `mvp` — по-прежнему только через PR.
 
+**Релиз/деплой — FF-промоушн `dev → testnet → main`** (см. `scripts/RELEASE.md`). Версию бампает `lerna` ОДИН раз на dev (`scripts/cut-release.sh`), тот же коммит едет вверх по fast-forward (`scripts/promote.sh testnet|main`). `testnet`/`main` не несут своих коммитов — только FF-указатели, поэтому merge-конфликтов нет. **В `testnet`/`main` прямых коммитов и повторных бампов версии быть не должно** — это ломает FF. Деплой триггерит push в testnet/main с изменением `lerna.json`; окружение определяет ветка (main → prod). Старые `publish-alpha.sh`/`publish-prod.sh` (merge `-X theirs` + per-branch бамп + back-merge) удалены — они и плодили 20-package.json конфликты.
+
 **Не stash'ить `-u` при unstaged WIP пользователя.** Это создаёт окно для потери при drop/конфликте. Если нужно временно убрать unstaged — `git stash push -- <конкретные-paths>` либо коммит-в-feature, и только свои файлы. Кейс 2026-05-18: после `git stash -u`+`drop` при конфликте потерял WIP пользователя (infra.ts/config.ts/quasar.config.cjs и др.).
 
 ### Story-by-story для проекта «Стол заказов» (mono-ai-4 на marketplace2)
@@ -184,6 +186,35 @@ await sendPOST('/v1/graphql', { query: QUERY, variables });
 
 Канон — `features/Branch/CreateBranch/{api,model}/index.ts`: тип в model `export type IXxxInput = Mutations.X.Y.IInput['data']`; функция в api `function (data: IXxxInput) { ... variables: { data } }`. Не делать `as` cast'ов.
 
+## ⚠️ ДИЗАЙН-КАНОН desktop — ОБЯЗАТЕЛЕН К ИСПОЛЬЗОВАНИЮ
+
+**ПРИ ЛЮБОЙ ВЁРСТКЕ В `components/desktop/` НЕ ВЫДУМЫВАТЬ СТИЛИ.** Всегда сначала свериться с каноном. Не строй гипотез о цветах/радиусах/типографике/паттернах из памяти — иди и читай.
+
+**Полная спецификация канона — в skill `/mono-desktop-canon`** (правила обёрток, цвета/токены, иконки, структура страницы, stop-signals). Здесь — короткая выжимка; при расхождении побеждает skill.
+
+**Источник истины — в самом репозитории** (НЕ внешние HTML/прототипы):
+
+| Что | Путь |
+|---|---|
+| Токены палитры/типографики/spacing/radii (`--p-*`) | `components/desktop/src/css/mono-platform/tokens.css` |
+| Прототип-классы компонентов + typography-утилиты `.t-*` | `components/desktop/src/css/mono-platform/components.css` |
+| Оверрайды Quasar под канон | `components/desktop/src/css/mono-platform/quasar-canon.css` |
+| Минимальная SCSS-палитра Quasar (`$primary`/`$dark`) | `components/desktop/src/css/quasar.variables.scss` |
+| Обёртки / доменные блоки / layout | `components/desktop/src/shared/ui/{base,domain,layout}/` |
+| **Живой эталон** (`/_dev/ui` в dev-сборке) | `components/desktop/src/pages/_dev/ui/index.vue` |
+
+**При сомнении — открыть `tokens.css` и `_dev/ui/index.vue`, смотреть как сделано там.** Внешний `shared/MONO Design System.html` и `auth-prototype/` каноном НЕ являются — это устаревшие прототипы.
+
+**Запреты:**
+- Экран собирается из готовых компонентов: `shared/ui/base` (вместо сырых `q-input`/`q-btn`/`q-card`/`q-table`/`q-chip`/`q-dialog`/`q-select`), `shared/ui/domain` (WalletCard, DataRow, DocumentRow, IdentityPanel…), `shared/ui/layout` (PageHead, PageTabs, AppHeader/AppDrawer). Голый Quasar — только где обёртки нет (`q-icon`, `q-toggle`, `q-list`, `q-menu`, `q-tooltip`, `q-tabs`, `q-separator`, `q-spinner`, `q-inner-loading`…). Props обёрток не угадывать — читать `*.types.ts` рядом.
+- Цвет — только токены `var(--p-*)` (поверхности `--p-surface*`, текст `--p-ink*`, линии `--p-line*`, акцент `--p-primary`, статусы `--p-pos/neg/warn/info`) либо utility-классы/color-props. Никаких сырых hex/rgb. Темы light/dark переключаются через `[data-theme]` на `<html>` — токены следуют сами.
+- Spacing/радиусы/типографика — токены `--p-1..--p-10` (4px…72px), `--p-r-sm/md/lg/xl`, `--p-fs-*`/`--p-lh-*` либо классы `.t-*`. Без хардкод-px.
+- Иконки — `q-icon(name='…')` именами Material Icons. **FontAwesome (`fa-*`) запрещён** — заменять на Material-эквивалент попутно.
+- Запрещённые/удаляемые токены: `--mp-*` (старый `marketplace-tokens.scss`), `--tr-*`, `--ds-*`. Легитимны только `--p-*`, `--q-*` (Quasar автоген), `--prog-*`.
+- Никаких локальных переопределений `.q-btn`/`.q-card`/`.q-notification` в feature-файлах — Quasar-overrides централизованы в `quasar-canon.css`.
+
+**Кейс 2026-05-28:** при сомнении в каноне пошёл искать его во внешнем HTML/auth-prototype вместо репозитория — перевёрстал не туда, переделывал. SoT — репо (`tokens.css` + `_dev/ui`) и skill `/mono-desktop-canon`, не внешние файлы.
+
 ## Frontend desktop — English имена
 
 В `components/desktop/` и любом Vue/TS frontend коде **все имена идентификаторов — английские**:

components/auth/build.config.ts

@@ -0,0 +1,12 @@
+import { defineBuildConfig } from 'unbuild'
+
+// Один dual-выход (ESM .mjs + CJS .cjs + .d.ts) обслуживает все три target'а:
+// браузер и desktop-runtime берут import→.mjs, Node — require→.cjs (exports-map).
+export default defineBuildConfig({
+  entries: ['src/index'],
+  declaration: true,
+  clean: true,
+  rollup: {
+    emitCJS: true,
+  },
+})

components/auth/eslint.config.js

@@ -0,0 +1,13 @@
+// @ts-check
+import antfu from '@antfu/eslint-config'
+
+export default antfu(
+  {
+    type: 'lib',
+    rules: {
+      'eslint-comments/no-unlimited-disable': 'off',
+      'no-console': 'off',
+      'ts/explicit-function-return-type': 'off',
+    },
+  },
+)

components/auth/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@coopenomics/auth",
+  "type": "module",
+  "version": "2026.6.9-18",
+  "private": false,
+  "packageManager": "pnpm@9.9.0",
+  "description": "SDK аутентификации CoopID: OIDC, vault, кошелёк и подпись для браузера, Node и desktop",
+  "author": "Alex Ant <dacom.dark.sun@gmail.com>",
+  "license": "MIT",
+  "keywords": [],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/*",
+        "./dist/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prebuild": "pnpm run typecheck",
+    "build": "unbuild",
+    "dev": "unbuild --stub",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:node": "vitest run test/cross-runtime",
+    "test:browser": "vitest run --config vitest.config.browser.ts",
+    "test:electron": "node test/cross-runtime/run-electron.mjs",
+    "test:cross-runtime": "pnpm run build && pnpm run test:node && pnpm run test:browser && pnpm run test:electron",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.8.0",
+    "@wharfkit/antelope": "^1.1.1",
+    "@wharfkit/session": "^1.4.0",
+    "cooptypes": "workspace:*",
+    "jose": "^6.2.2",
+    "oidc-client-ts": "^3.1.0"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^3.3.2",
+    "@types/node": "^22.5.4",
+    "@vitest/browser": "2.1.9",
+    "electron": "36.9.5",
+    "eslint": "^9.9.1",
+    "playwright": "1.59.1",
+    "typescript": "^5.5.4",
+    "unbuild": "^2.0.0",
+    "vite": "^5.4.3",
+    "vitest": "^2.0.5"
+  }
+}

components/auth/src/certificate/index.ts

@@ -0,0 +1,194 @@
+/**
+ * participant_certificate: чтение claims на клиенте (ЛК, Story 1.9) и offline-
+ * верификация (Story 4.4). Здесь — только ДЕКОДИРОВАНИЕ payload и производные
+ * (статус, человекочитаемые типы верификации). Проверка подписи против trust
+ * anchor — отдельно (verifyOffline, chain/), для отображения в ЛК не требуется.
+ */
+import { decodeJwt } from 'jose'
+import { AuthV2Error, AuthV2ErrorCode } from '../errors'
+
+export * from './schema-policy'
+
+export interface CoopChainLink {
+  account: string
+  public_key: string
+}
+
+/**
+ * Подтверждённый тип верификации в удостоверении (Story 4.3). Структурная форма
+ * для RP: что подтверждено (`type`), когда (`verified_at`, ISO-8601 UTC) и на каком
+ * основании (`source`).
+ */
+export interface VerificationTypeClaim {
+  type: string
+  verified_at: string
+  source: string
+}
+
+/** Claims participant_certificate (зеркало payload контроллера, Story 1.8). */
+export interface ParticipantCertificateClaims {
+  iss: string
+  /** UUID пайщика */
+  sub: string
+  /** серийный номер удостоверения */
+  jti: string
+  iat: number
+  exp: number
+  coopname: string
+  coop_chain: CoopChainLink[]
+  verification_types: VerificationTypeClaim[]
+  identification: Record<string, unknown> | null
+  claim_schema_version: string
+  /** 152-ФЗ-обязательство RP удалить данные пайщика (Story 4.8), напр. `erase_on_exclusion`. */
+  data_retention_contract: string
+  /** Дедлайн удаления данных RP, unix-секунды (`iat + 30 дней`, Story 4.8). */
+  retention_deadline_ts: number
+}
+
+/** Нормализовать сырой claim verification_types в структурную форму (Story 4.3). */
+function normalizeVerificationTypes(raw: unknown): VerificationTypeClaim[] {
+  if (!Array.isArray(raw))
+    return []
+  return raw
+    .filter((e): e is Record<string, unknown> => typeof e === 'object' && e !== null && typeof (e as Record<string, unknown>).type === 'string')
+    .map(e => ({
+      type: String(e.type),
+      verified_at: String(e.verified_at ?? ''),
+      source: String(e.source ?? ''),
+    }))
+}
+
+export type CertificateStatus = 'active' | 'expiring' | 'expired'
+
+/** Окно «истекает» до exp (24ч по умолчанию у сертификата; здесь — последний час). */
+export const CERTIFICATE_EXPIRING_WINDOW_MS = 60 * 60 * 1000
+
+/** Человекочитаемые описания типов верификации (claim `verification_types`). */
+export const VERIFICATION_TYPE_LABELS: Record<string, string> = {
+  coop_baseline: 'Базовое подтверждение кооперативом',
+}
+
+/** Описание типа верификации; неизвестный — отдаём как есть (forward-compat). */
+export function verificationTypeLabel(type: string): string {
+  return VERIFICATION_TYPE_LABELS[type] ?? type
+}
+
+/**
+ * Декодировать compact JWS в claims БЕЗ проверки подписи (для отображения в ЛК).
+ * Бросает AuthV2Error при структурно некорректном сертификате.
+ */
+export function decodeParticipantCertificate(jws: string): ParticipantCertificateClaims {
+  let raw: Record<string, unknown>
+  try {
+    raw = decodeJwt(jws) as Record<string, unknown>
+  }
+  catch {
+    throw new AuthV2Error(AuthV2ErrorCode.ChainVerificationFailed, 'Некорректный participant_certificate: не удалось прочитать claims')
+  }
+  if (typeof raw.jti !== 'string' || typeof raw.exp !== 'number' || typeof raw.sub !== 'string')
+    throw new AuthV2Error(AuthV2ErrorCode.ChainVerificationFailed, 'participant_certificate без обязательных claims (jti/exp/sub)')
+
+  return {
+    iss: String(raw.iss ?? ''),
+    sub: raw.sub,
+    jti: raw.jti,
+    iat: Number(raw.iat ?? 0),
+    exp: raw.exp,
+    coopname: String(raw.coopname ?? ''),
+    coop_chain: Array.isArray(raw.coop_chain) ? (raw.coop_chain as CoopChainLink[]) : [],
+    verification_types: normalizeVerificationTypes(raw.verification_types),
+    identification: (raw.identification as Record<string, unknown> | null) ?? null,
+    claim_schema_version: String(raw.claim_schema_version ?? ''),
+    data_retention_contract: String(raw.data_retention_contract ?? ''),
+    retention_deadline_ts: Number(raw.retention_deadline_ts ?? 0),
+  }
+}
+
+/** Статус по сроку действия: expired / expiring (близко к exp) / active. */
+export function certificateStatus(claims: Pick<ParticipantCertificateClaims, 'exp'>, nowMs: number = Date.now()): CertificateStatus {
+  const expMs = claims.exp * 1000
+  if (nowMs >= expMs)
+    return 'expired'
+  if (expMs - nowMs <= CERTIFICATE_EXPIRING_WINDOW_MS)
+    return 'expiring'
+  return 'active'
+}
+
+/**
+ * Окно упреждающего перезапроса сертификата (Story 4.6): за 5 минут до `exp` SDK
+ * молча обновляет удостоверение, чтобы у короткоживущего cert (дефолт 1ч) не было
+ * разрыва доступа на стыке.
+ */
+export const CERTIFICATE_RENEWAL_LEAD_MS = 5 * 60 * 1000
+
+/**
+ * Сколько миллисекунд ждать до момента перезапроса (`exp − lead`). Никогда не
+ * отрицательно: если до `exp` осталось ≤ lead (или cert уже истёк) — 0 (перезапрос сразу).
+ */
+export function computeRenewalDelayMs(claims: Pick<ParticipantCertificateClaims, 'exp'>, nowMs: number = Date.now()): number {
+  const renewAtMs = claims.exp * 1000 - CERTIFICATE_RENEWAL_LEAD_MS
+  return Math.max(0, renewAtMs - nowMs)
+}
+
+/** Управление запланированным авто-обновлением сертификата. */
+export interface CertificateRenewalHandle {
+  /** Отменить запланированный перезапрос (например, при logout). */
+  cancel: () => void
+}
+
+/** Параметры планировщика — для подмены времени/таймеров в тестах. */
+export interface ScheduleCertificateRenewalOptions {
+  now?: () => number
+  setTimer?: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>
+  clearTimer?: (handle: ReturnType<typeof setTimeout>) => void
+}
+
+/**
+ * Запланировать silent renewal сертификата за 5 минут до `exp` (Story 4.6). По
+ * срабатыванию таймера вызывает `renew()` — хост-колбэк, который обновляет access
+ * через `refresh_token` и тянет свежий cert (`getParticipantCertificate`), — затем
+ * перепланирует от `exp` нового удостоверения. Кросс-рантайм: SDK владеет ЛОГИКОЙ
+ * планирования, а транспорт/refresh — на стороне приложения (как и весь fetch в SDK).
+ * Бесконечный цикл сам себя продлевает, пока не вызван `cancel()`. Ошибка `renew`
+ * не роняет процесс (логируется), но и НЕ перепланирует — повторную попытку инициирует хост.
+ */
+export function scheduleCertificateRenewal(
+  initialJws: string,
+  renew: () => Promise<string>,
+  options: ScheduleCertificateRenewalOptions = {},
+): CertificateRenewalHandle {
+  const now = options.now ?? (() => Date.now())
+  const setTimer = options.setTimer ?? ((cb, ms) => setTimeout(cb, ms))
+  const clearTimer = options.clearTimer ?? (h => clearTimeout(h))
+
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let cancelled = false
+
+  const scheduleFrom = (jws: string): void => {
+    if (cancelled)
+      return
+    const claims = decodeParticipantCertificate(jws)
+    const delay = computeRenewalDelayMs(claims, now())
+    timer = setTimer(() => {
+      void renew()
+        .then((nextJws) => {
+          if (!cancelled)
+            scheduleFrom(nextJws)
+        })
+        .catch(() => {
+          // best-effort: сбой обновления (нет сети/refresh истёк) не роняет цикл;
+          // повторную попытку инициирует приложение (например, при следующем действии).
+        })
+    }, delay)
+  }
+
+  scheduleFrom(initialJws)
+
+  return {
+    cancel: () => {
+      cancelled = true
+      if (timer !== null)
+        clearTimer(timer)
+    },
+  }
+}

components/auth/src/certificate/schema-policy.ts

@@ -0,0 +1,90 @@
+/**
+ * Политика версий схемы claims удостоверения на стороне SDK (Story 4.10).
+ * Зеркало публичной `/.well-known/coopid-schema-policy.json` контроллера: типы,
+ * сравнение версий и кэш с TTL 24ч. `verifyOffline` сверяет `claim_schema_version`
+ * проверяемого сертификата с минимально поддерживаемой версией из этого кэша.
+ *
+ * Кросс-рантайм: SDK владеет ЛОГИКОЙ кеша/сравнения; сам HTTP-fetch политики
+ * инжектируется хостом (как и весь fetch в SDK — chain/ остаётся чисто офлайновым).
+ */
+
+/** Путь публичной политики версий схемы у контроллера кооператива. */
+export const SCHEMA_POLICY_WELL_KNOWN_PATH = '/.well-known/coopid-schema-policy.json'
+
+/** TTL кэша политики: офлайн принимает закэшированную min-версию до 24 часов (FR72). */
+export const SCHEMA_POLICY_CACHE_TTL_MS = 24 * 60 * 60 * 1000
+
+export interface CoopIdSchemaPolicy {
+  current_version: string
+  min_supported_version: string
+  deprecation: Record<string, string>
+}
+
+/**
+ * Сравнить две версии схемы. Версии — целочисленные строки (`'0'`, `'1'`, …):
+ * сравниваем численно, при нечисловой версии — лексикографический фолбэк.
+ * `< 0` если a старее b, `0` если равны, `> 0` если a новее.
+ */
+export function compareSchemaVersions(a: string, b: string): number {
+  const na = Number(a)
+  const nb = Number(b)
+  if (Number.isFinite(na) && Number.isFinite(nb))
+    return na - nb
+  if (a === b)
+    return 0
+  return a < b ? -1 : 1
+}
+
+/** Поддерживается ли версия схемы (не старее минимально поддерживаемой). */
+export function isSchemaVersionSupported(version: string, minSupported: string): boolean {
+  return compareSchemaVersions(version, minSupported) >= 0
+}
+
+export interface SchemaPolicyCacheOptions {
+  /** Хост-колбэк, тянущий политику с `SCHEMA_POLICY_WELL_KNOWN_PATH` (fetch — у приложения). */
+  fetchPolicy: () => Promise<CoopIdSchemaPolicy>
+  /** «Сейчас» в мс (инъекция для детерминизма/тестов). */
+  now?: () => number
+  /** TTL кэша в мс (по умолчанию 24ч). */
+  ttlMs?: number
+}
+
+export interface SchemaPolicyCache {
+  /** Политика из кэша (свежий fetch при истёкшем TTL; stale-кэш при офлайне). */
+  getPolicy: () => Promise<CoopIdSchemaPolicy>
+  /** Минимально поддерживаемая версия — для передачи в `verifyOffline`. */
+  getMinSupportedVersion: () => Promise<string>
+}
+
+/**
+ * Кэш политики версий схемы с TTL 24ч (Story 4.10, FR72). В пределах TTL отдаёт
+ * закэшированную политику без сети. По истечении TTL пробует обновить; если fetch
+ * упал (офлайн/недоступность) — отдаёт последнюю валидную политику (недоступность
+ * сети НЕ роняет офлайн-проверку; короткий cert TTL ограничивает риск устаревания).
+ * Нет кэша и fetch упал → пробрасывает ошибку (политику взять неоткуда).
+ */
+export function createSchemaPolicyCache(options: SchemaPolicyCacheOptions): SchemaPolicyCache {
+  const now = options.now ?? (() => Date.now())
+  const ttlMs = options.ttlMs ?? SCHEMA_POLICY_CACHE_TTL_MS
+  let cached: { policy: CoopIdSchemaPolicy, fetchedAt: number } | null = null
+
+  const getPolicy = async (): Promise<CoopIdSchemaPolicy> => {
+    if (cached && now() - cached.fetchedAt < ttlMs)
+      return cached.policy
+    try {
+      const policy = await options.fetchPolicy()
+      cached = { policy, fetchedAt: now() }
+      return policy
+    }
+    catch (error) {
+      if (cached)
+        return cached.policy
+      throw error
+    }
+  }
+
+  return {
+    getPolicy,
+    getMinSupportedVersion: async () => (await getPolicy()).min_supported_version,
+  }
+}

components/auth/src/chain/index.ts

@@ -0,0 +1,315 @@
+import type { CoopChainLink } from '../certificate'
+/**
+ * Цепочка доверия: офлайн-проверка participant_certificate walk'ом
+ * `ano → voskhod → vostok → participant` от embedded trust anchor.
+ * Реализация verify — Story 4.4; чтение ключей `cert` из COOPOS — здесь.
+ */
+import { APIClient } from '@wharfkit/antelope'
+import { base64url } from 'jose'
+import { compareSchemaVersions } from '../certificate/schema-policy'
+import { TRUST_ANCHOR_ANO_CERT_PUBKEY } from '../config/trust-anchor'
+import { AuthV2Error, AuthV2ErrorCode } from '../errors'
+
+/**
+ * Публичный ключ permission `cert` аккаунта в COOPOS (Story 1.3).
+ * Возвращает строку в формате Antelope (`PUB_K1_...`).
+ */
+export async function readCertPublicKey(rpcUrl: string, account: string): Promise<string> {
+  const client = new APIClient({ url: rpcUrl })
+  const acc = await client.v1.chain.get_account(account).catch((e: unknown) => {
+    throw new AuthV2Error(
+      AuthV2ErrorCode.NetworkError,
+      `COOPOS недоступен или аккаунт ${account} не найден: ${e instanceof Error ? e.message : String(e)}`,
+    )
+  })
+  const cert = acc.permissions.find(p => String(p.perm_name) === 'cert')
+  const key = cert?.required_auth.keys[0]?.key
+  if (!cert || !key) {
+    throw new AuthV2Error(
+      AuthV2ErrorCode.ChainVerificationFailed,
+      `На аккаунте ${account} нет permission cert с ключом — цепочка доверия не настроена (Story 1.3).`,
+    )
+  }
+  // MVP-инвариант: cert — строго single-key (multi-sig для ano — Growth).
+  // Молча взять keys[0] у multi-sig значило бы проверять подпись против
+  // одного из N ключей — это дыра в цепочке доверия.
+  const auth = cert.required_auth
+  if (Number(auth.threshold) !== 1 || auth.keys.length !== 1 || auth.accounts.length > 0 || auth.waits.length > 0) {
+    throw new AuthV2Error(
+      AuthV2ErrorCode.ChainVerificationFailed,
+      `Permission cert на ${account} не является single-key (threshold=${auth.threshold}, keys=${auth.keys.length}) — не поддерживается MVP-верификацией.`,
+    )
+  }
+  return key.toString()
+}
+
+export type VerifyOfflineReason =
+  | 'malformed_certificate' // не compact JWS / нет обязательных claims (coop_chain, exp)
+  | 'unsupported_alg' // alg ≠ ES256K
+  | 'expired' // exp в прошлом относительно now
+  | 'untrusted_anchor' // coop_chain не укоренён в известном trust-anchor `ano`
+  | 'untrusted_issuer' // звено цепи (в т.ч. издатель) не совпало с доверенным кэшем ключей
+  | 'signature_mismatch' // подпись не сходится с ключом издателя
+  | 'unsupported_schema_version' // claim_schema_version старее min_supported_version политики
+
+export interface VerifyOfflineResult {
+  valid: boolean
+  /** Причина отказа, если valid=false. Офлайн-отзыв (revoked) — вне MVP (Story 4.7). */
+  reason?: VerifyOfflineReason
+  /** Аккаунт-издатель (последнее звено coop_chain), под чьим ключом сошлась подпись. */
+  issuer?: string
+}
+
+export interface VerifyOfflineOptions {
+  /**
+   * Офлайн-снимок доверенных cert-ключей известных кооперативов
+   * (`chain_manifests_cache`): `account → Antelope public_key`. Источник доверия —
+   * каждое звено `coop_chain` сертификата сверяется с этим набором (закрывает
+   * подделку «свой leaf-ключ + настоящий ano в root»). Без него издатель не
+   * подтверждается → `untrusted_issuer` (fail-closed). Наполнение кэша
+   * (manifest-sync) — отдельная задача.
+   */
+  trustedKeys?: Record<string, string>
+  /**
+   * Доверенный якорь `ano.cert` (Antelope `PUB_K1_…`). По умолчанию —
+   * `trustedKeys['ano']`, затем вшитый release-pinned `TRUST_ANCHOR_ANO_CERT_PUBKEY`.
+   */
+  trustAnchor?: string
+  /** «Сейчас» в мс для проверки exp (инъекция для детерминизма/тестов). */
+  now?: number
+  /**
+   * Минимально поддерживаемая версия схемы claims (Story 4.10). Резолвится хостом
+   * из кэша политики (`createSchemaPolicyCache().getMinSupportedVersion`, TTL 24ч).
+   * Если задана и `cert.claim_schema_version` старее неё → `unsupported_schema_version`.
+   * Не задана → ось версии схемы не гейтит (крипто/exp/цепь остаются fail-closed).
+   */
+  minSchemaVersion?: string
+}
+
+/** Порядок группы secp256k1 (n) и его половина — для low-S нормализации подписи. */
+const SECP256K1_N = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141n
+const SECP256K1_HALF_N = SECP256K1_N >> 1n
+
+/**
+ * Нормализовать S подписи R||S (64 байта) к нижней половине порядка кривой.
+ * cert подписывает controller через jose+Node KeyObject, а Node-ECDSA может выдать
+ * high-S; wharfkit/noble verify по умолчанию отвергает high-S (`lowS:true`).
+ * Верификация secp256k1 инвариантна к `S ↔ n−S`, поэтому приведение к low-S делает
+ * подпись принимаемой независимо от каноничности подписанта.
+ */
+function normalizeLowS(rs: Uint8Array): Uint8Array {
+  let s = 0n
+  for (const byte of rs.slice(32, 64))
+    s = (s << 8n) | BigInt(byte)
+  if (s <= SECP256K1_HALF_N)
+    return rs
+  let low = SECP256K1_N - s
+  const out = new Uint8Array(rs) // копия R||S
+  for (let i = 63; i >= 32; i--) {
+    out[i] = Number(low & 0xFFn)
+    low >>= 8n
+  }
+  return out
+}
+
+interface CertHead { alg?: string }
+interface CertPayload { coop_chain?: CoopChainLink[], exp?: number, claim_schema_version?: string }
+
+/**
+ * Офлайн-валидация удостоверения `participant_certificate` без обращения к сети
+ * (Story 4.4; Vision: NFC-карты, бумажный QR). Проверяет структуру/alg/exp,
+ * укоренение `coop_chain` в trust-anchor `ano`, принадлежность звеньев доверенному
+ * кэшу ключей и подпись против ключа издателя (последнее звено `coop_chain`).
+ *
+ * Полностью офлайн и fail-closed: без доверенного якоря/кэша вердикт всегда
+ * `valid:false`. Отзыв ключа офлайн не проверяется (вне MVP — Story 4.7, Growth
+ * FR65); компенсируется коротким TTL (Story 4.6).
+ */
+export async function verifyOffline(certificate: string, options: VerifyOfflineOptions = {}): Promise<VerifyOfflineResult> {
+  const parts = certificate.split('.')
+  if (parts.length !== 3)
+    return { valid: false, reason: 'malformed_certificate' }
+  const [h, p, s] = parts
+
+  let head: CertHead
+  let payload: CertPayload
+  try {
+    head = JSON.parse(new TextDecoder().decode(base64url.decode(h)))
+    payload = JSON.parse(new TextDecoder().decode(base64url.decode(p)))
+  }
+  catch {
+    return { valid: false, reason: 'malformed_certificate' }
+  }
+  if (head.alg !== 'ES256K')
+    return { valid: false, reason: 'unsupported_alg' }
+
+  const chain = payload.coop_chain
+  if (!Array.isArray(chain) || chain.length === 0 || typeof payload.exp !== 'number')
+    return { valid: false, reason: 'malformed_certificate' }
+
+  const now = options.now ?? Date.now()
+  if (now >= payload.exp * 1000)
+    return { valid: false, reason: 'expired' }
+
+  // Версия схемы (Story 4.10): если хост передал минимально поддерживаемую версию
+  // (из кэша политики, TTL 24ч), отвергаем сертификаты старее неё — устаревшая схема
+  // claims не должна проходить как валидная. Без minSchemaVersion ось не гейтит.
+  if (options.minSchemaVersion !== undefined
+    && compareSchemaVersions(payload.claim_schema_version ?? '0', options.minSchemaVersion) < 0) {
+    return { valid: false, reason: 'unsupported_schema_version' }
+  }
+
+  // Якорь: цепь обязана начинаться с известного `ano`.
+  const root = chain[0]
+  const anchor = options.trustAnchor ?? options.trustedKeys?.ano ?? TRUST_ANCHOR_ANO_CERT_PUBKEY
+  if (!anchor || root.account !== 'ano' || root.public_key !== anchor)
+    return { valid: false, reason: 'untrusted_anchor' }
+
+  // Звенья: при наличии кэша каждое звено должно совпасть с доверенным ключом.
+  if (options.trustedKeys) {
+    for (const link of chain) {
+      if (options.trustedKeys[link.account] !== link.public_key)
+        return { valid: false, reason: 'untrusted_issuer' }
+    }
+  }
+  else {
+    // Без кэша подтверждён только якорь; издателя доверять нельзя — fail-closed.
+    return { valid: false, reason: 'untrusted_issuer' }
+  }
+
+  // Подпись: против ключа издателя (последнее звено coop_chain, оно же `kid`).
+  const issuer = chain[chain.length - 1]
+  let rs: Uint8Array
+  try {
+    rs = base64url.decode(s)
+  }
+  catch {
+    return { valid: false, reason: 'malformed_certificate' }
+  }
+  if (rs.length !== 64)
+    return { valid: false, reason: 'malformed_certificate' }
+
+  const { PublicKey, Signature } = await import('@wharfkit/antelope')
+  const normalized = normalizeLowS(rs)
+  const signingInput = new TextEncoder().encode(`${h}.${p}`)
+  let ok = false
+  try {
+    const sig = Signature.from({ type: 'K1', r: normalized.slice(0, 32), s: normalized.slice(32, 64), recid: 0 })
+    ok = sig.verifyMessage(signingInput, PublicKey.from(issuer.public_key))
+  }
+  catch {
+    ok = false // некорректный ключ/подпись в сертификате — не валим исключением
+  }
+  if (!ok)
+    return { valid: false, reason: 'signature_mismatch' }
+
+  return { valid: true, issuer: issuer.account }
+}
+
+/**
+ * Окно активности одного публичного ключа подписанта в истории его аккаунта.
+ * Блоки, не время: смена authority в COOPOS привязана к блоку.
+ */
+export interface KeyValidityWindow {
+  /** публичный ключ в формате Antelope (`PUB_K1_...`) */
+  public_key: string
+  /** блок, с которого ключ стал активным (включительно) */
+  valid_from_block: number
+  /** блок, по который ключ был активным (включительно); null = активен сейчас */
+  valid_to_block: number | null
+}
+
+export type VerifyDocumentReason =
+  | 'malformed_jws'
+  | 'unsupported_alg'
+  | 'signature_mismatch' // ни один исторический ключ не даёт валидную подпись (подделка/чужой)
+  | 'key_not_active_at_signing' // подпись валидна под ключом, но он НЕ был активен на signedAtBlock
+
+export interface VerifyDocumentParams {
+  /** compact JWS из `signDocument` (Story 2.3) */
+  jws: string
+  /**
+   * Блок, на который проверяется активность ключа — `last_irreversible_block_num`
+   * на момент `iat` подписи. Известен держателю документа (метаданные подписи).
+   */
+  signedAtBlock: number
+  /**
+   * Историческая хронология ключей подписанта (offline-снимок из
+   * `chain_manifests_cache`). Наполнение кэша (ротация ключей / manifest-sync) —
+   * отдельная задача; здесь — чистая проверка по уже полученной хронологии.
+   */
+  authority: KeyValidityWindow[]
+}
+
+export interface VerifyDocumentResult {
+  valid: boolean
+  reason?: VerifyDocumentReason
+  /** ключ, под которым подпись подтвердилась (если valid) */
+  matched_key?: string
+}
+
+/**
+ * Backward-валидность подписи документа через chain-walk (Story 2.5). Подпись,
+ * сделанная ключом пайщика ДО ротации, остаётся валидной: проверяем, что ключ был
+ * активен в момент подписи (`signedAtBlock` ∈ окно ключа), а не «активен сейчас».
+ * Так ротация ключа не аннулирует юридически значимые документы.
+ *
+ * Полностью офлайн: работает по переданной хронологии `authority` (кэш манифеста),
+ * без сети. Верификация — `verifyMessage` против ключей-кандидатов (а НЕ recover:
+ * `signDocument` отбрасывает recovery-байт, оставляя JWS-формат R||S).
+ */
+export async function verifyDocumentOffline(params: VerifyDocumentParams): Promise<VerifyDocumentResult> {
+  const parts = params.jws.split('.')
+  if (parts.length !== 3)
+    return { valid: false, reason: 'malformed_jws' }
+  const [h, p, s] = parts
+
+  let header: { alg?: string }
+  try {
+    header = JSON.parse(new TextDecoder().decode(base64url.decode(h)))
+  }
+  catch {
+    return { valid: false, reason: 'malformed_jws' }
+  }
+  if (header.alg !== 'ES256K')
+    return { valid: false, reason: 'unsupported_alg' }
+
+  let rs: Uint8Array
+  try {
+    rs = base64url.decode(s)
+  }
+  catch {
+    return { valid: false, reason: 'malformed_jws' }
+  }
+  if (rs.length !== 64)
+    return { valid: false, reason: 'malformed_jws' }
+
+  const { PublicKey, Signature } = await import('@wharfkit/antelope')
+  const signingInput = new TextEncoder().encode(`${h}.${p}`)
+  const sig = Signature.from({ type: 'K1', r: rs.slice(0, 32), s: rs.slice(32, 64), recid: 0 })
+
+  let signedUnderRotatedKey = false
+  for (const w of params.authority) {
+    let ok = false
+    try {
+      ok = sig.verifyMessage(signingInput, PublicKey.from(w.public_key))
+    }
+    catch {
+      ok = false // некорректный ключ в хронологии — пропускаем, не валим всю проверку
+    }
+    if (!ok)
+      continue
+    const active = params.signedAtBlock >= w.valid_from_block
+      && (w.valid_to_block === null || params.signedAtBlock <= w.valid_to_block)
+    if (active)
+      return { valid: true, matched_key: w.public_key }
+    // подпись валидна, но этот ключ не был активен в момент подписи — продолжаем
+    // искать (вдруг другой ключ окна подходит); запоминаем для точной причины.
+    signedUnderRotatedKey = true
+  }
+
+  return {
+    valid: false,
+    reason: signedUnderRotatedKey ? 'key_not_active_at_signing' : 'signature_mismatch',
+  }
+}

components/auth/src/config/coopos-public-nodes.ts

@@ -0,0 +1,7 @@
+/**
+ * Публичные RPC-ноды COOPOS — fallback для чтения ключей/manifest'ов,
+ * когда нода кооператива недоступна (используется начиная со Story 9.5).
+ *
+ * TODO(Story 9.5): наполнить актуальным списком публичных нод сети.
+ */
+export const COOPOS_PUBLIC_NODES: readonly string[] = []

components/auth/src/config/trust-anchor.ts

@@ -0,0 +1,13 @@
+/**
+ * Embedded trust anchor цепочки доверия: публичный ключ `ano.cert` в
+ * Antelope-формате (`PUB_K1_…`, кривая secp256k1). Якорь вшивается в пакет
+ * (release-pinned), чтобы `verifyOffline()` укоренял `coop_chain` без сети.
+ *
+ * Формат — Antelope-строка, а не JWK: вся цепь (`coop_chain`, `readCertPublicKey`,
+ * wharfkit-верификация) оперирует `PUB_K1_…`; JWK был несравним со звеньями
+ * (реконсиляция скелета 1.2 ↔ реальности, Story 4.4).
+ *
+ * TODO(release): подставить реальный ключ после создания permission `cert` на
+ * аккаунте `ano` в COOPOS (hash-pinned bundle в consuming-приложениях, NFR).
+ */
+export const TRUST_ANCHOR_ANO_CERT_PUBKEY: string | null = null

components/auth/src/errors.ts

@@ -0,0 +1,223 @@
+/**
+ * Зеркало enum'а ошибок auth-v2 контроллера (источник истины — controller,
+ * появится в Story 1.11). Расширяется синхронно с серверной стороной.
+ */
+export enum AuthV2ErrorCode {
+  NotImplemented = 'not_implemented',
+  InvalidCredentials = 'invalid_credentials',
+  WeakPassword = 'weak_password',
+  SessionBindingReused = 'session_binding_reused',
+  SessionBindingExpired = 'session_binding_expired',
+  TimestampTooOld = 'timestamp_too_old',
+  VaultDecryptionFailed = 'vault_decryption_failed',
+  CertificateExpired = 'certificate_expired',
+  CertificateRevoked = 'certificate_revoked',
+  ChainVerificationFailed = 'chain_verification_failed',
+  CooposDegraded = 'coopos_degraded',
+  TooManyAttempts = 'too_many_attempts',
+  TooManyRecoveryAttempts = 'too_many_recovery_attempts',
+  InvalidTwoFactorCode = 'invalid_2fa_code',
+  TwoFactorNotEnrolled = 'two_factor_not_enrolled',
+  InvalidRecoveryToken = 'invalid_recovery_token',
+  InvalidOfflineCode = 'invalid_offline_code',
+  InsufficientVerification = 'insufficient_verification',
+  NetworkError = 'network_error',
+  WalletLocked = 'wallet_locked',
+  ClientWalletMismatch = 'client_wallet_mismatch',
+  /** Клиентский код: high-stakes-действие (экспорт удостоверения с PII) не подтверждено. */
+  ConsentRequired = 'consent_required',
+}
+
+/**
+ * Ошибки SDK в формате OAuth 2.0 ({ error, error_description }): код — машинный,
+ * description — человеко-читаемое сообщение для UI.
+ */
+export class AuthV2Error extends Error {
+  readonly code: AuthV2ErrorCode
+
+  constructor(code: AuthV2ErrorCode, description: string) {
+    super(description)
+    this.name = 'AuthV2Error'
+    this.code = code
+  }
+
+  toJSON(): { error: AuthV2ErrorCode, error_description: string } {
+    return { error: this.code, error_description: this.message }
+  }
+}
+
+/** Внутренний помощник для каркаса: единообразный отказ нереализованных методов. */
+export function notImplemented(method: string): never {
+  throw new AuthV2Error(
+    AuthV2ErrorCode.NotImplemented,
+    `Метод ${method}() ещё не реализован: скелет SDK (Story 1.2), реализация приходит историями Эпиков 1–2.`,
+  )
+}
+
+/**
+ * Рекомендованное действие для UI при ошибке — определяет, какую кнопку/подсказку
+ * показать пайщику (Story 1.11).
+ */
+export type AuthV2ErrorAction =
+  | 'retry' // повторить ввод/вход
+  | 'recover' // предложить восстановление доступа («Восстановить доступ»)
+  | 'check_connection' // проверить интернет
+  | 'contact_support' // обратиться в кооператив
+  | 'none'
+
+/** Описание ошибки для отображения: сообщение + действие + судьба сессии. */
+export interface AuthV2ErrorView {
+  /** машинный код (null — неожиданная, не-типизированная ошибка) */
+  code: AuthV2ErrorCode | null
+  /** человеко-читаемое сообщение для UI */
+  message: string
+  /** что предложить пайщику */
+  action: AuthV2ErrorAction
+  /**
+   * Сохранять ли текущую сессию. `true` — НЕ разлогинивать (сбой временный/внешний:
+   * нет связи, кооператив недоступен, кошелёк заперт) — NFR20/FR50: оффлайн не
+   * выкидывает пайщика. `false` — сбой требует повторного входа.
+   */
+  keepSession: boolean
+}
+
+type AuthV2ErrorViewBody = Omit<AuthV2ErrorView, 'code'>
+
+/**
+ * Каталог человеко-читаемых сообщений по кодам ошибок (Story 1.11). Источник
+ * UI-текстов — здесь; контроллер отдаёт только машинный `error`, клиент по нему
+ * выбирает сообщение и actionable-подсказку. Тексты — по-русски, без раскрытия
+ * технических деталей (например, какое именно поле логина неверно — security).
+ */
+export const AUTH_V2_ERROR_VIEWS: Record<AuthV2ErrorCode, AuthV2ErrorViewBody> = {
+  [AuthV2ErrorCode.NotImplemented]: {
+    message: 'Функция пока недоступна.',
+    action: 'none',
+    keepSession: true,
+  },
+  [AuthV2ErrorCode.InvalidCredentials]: {
+    message: 'Неверный email или пароль.',
+    action: 'retry',
+    keepSession: false,
+  },
+  [AuthV2ErrorCode.WeakPassword]: {
+    message: 'Пароль слишком простой. Используйте не менее 12 символов и не повторяйте типичные сочетания.',
+    action: 'retry',
+    keepSession: false,
+  },
+  [AuthV2ErrorCode.SessionBindingReused]: {
+    message: 'Сессия входа уже использована. Войдите заново.',
+    action: 'retry',
+    keepSession: false,
+  },
+  [AuthV2ErrorCode.SessionBindingExpired]: {
+    message: 'Время на подтверждение входа истекло. Войдите заново.',
+    action: 'retry',
+    keepSession: false,
+  },
+  [AuthV2ErrorCode.TimestampTooOld]: {
+    message: 'Истекло время на подтверждение входа. Повторите попытку.',
+    action: 'retry',
+    keepSession: false,
+  },
+  [AuthV2ErrorCode.VaultDecryptionFailed]: {
+    message: 'Не удалось расшифровать кошелёк. Попробуйте восстановить доступ.',
+    action: 'recover',
+    keepSession: false,
+  },
+  [AuthV2ErrorCode.CertificateExpired]: {
+    message: 'Срок действия удостоверения истёк. Войдите заново, чтобы обновить его.',
+    action: 'retry',
+    keepSession: false,
+  },
+  [AuthV2ErrorCode.CertificateRevoked]: {
+    message: 'Удостоверение отозвано. Обратитесь в кооператив.',
+    action: 'contact_support',
+    keepSession: false,
+  },
+  [AuthV2ErrorCode.ChainVerificationFailed]: {
+    message: 'Не удалось подтвердить подпись. Обратитесь в поддержку кооператива.',
+    action: 'contact_support',
+    keepSession: false,
+  },
+  [AuthV2ErrorCode.CooposDegraded]: {
+    message: 'Кооператив временно недоступен. Повторите попытку позже.',
+    action: 'retry',
+    keepSession: true,
+  },
+  [AuthV2ErrorCode.TooManyAttempts]: {
+    message: 'Слишком много попыток. Подождите немного и попробуйте снова.',
+    action: 'retry',
+    // временный троттлинг — не разлогиниваем пайщика, просто просим подождать.
+    keepSession: true,
+  },
+  [AuthV2ErrorCode.TooManyRecoveryAttempts]: {
+    message: 'Слишком много запросов на восстановление. Подождите и попробуйте позже.',
+    action: 'retry',
+    keepSession: true,
+  },
+  [AuthV2ErrorCode.InvalidTwoFactorCode]: {
+    message: 'Неверный код из приложения-аутентификатора. Проверьте код и попробуйте снова.',
+    action: 'retry',
+    keepSession: true,
+  },
+  [AuthV2ErrorCode.TwoFactorNotEnrolled]: {
+    message: 'Второй фактор не подключён.',
+    action: 'retry',
+    keepSession: true,
+  },
+  [AuthV2ErrorCode.InvalidRecoveryToken]: {
+    message: 'Ссылка восстановления недействительна или истекла. Запросите восстановление заново.',
+    action: 'recover',
+    keepSession: false,
+  },
+  [AuthV2ErrorCode.InvalidOfflineCode]: {
+    message: 'Код восстановления неверен или уже использован.',
+    action: 'retry',
+    keepSession: false,
+  },
+  [AuthV2ErrorCode.InsufficientVerification]: {
+    message: 'Недостаточный уровень верификации для этого действия. Обратитесь в кооператив.',
+    action: 'contact_support',
+    // авторизационное ограничение по уровню доверия — сессия валидна, не разлогиниваем.
+    keepSession: true,
+  },
+  [AuthV2ErrorCode.NetworkError]: {
+    message: 'Нет связи с кооперативом. Проверьте интернет.',
+    action: 'check_connection',
+    keepSession: true,
+  },
+  [AuthV2ErrorCode.WalletLocked]: {
+    message: 'Кошелёк заблокирован. Введите пароль для доступа к ключу.',
+    action: 'retry',
+    keepSession: true,
+  },
+  [AuthV2ErrorCode.ClientWalletMismatch]: {
+    message: 'Ключ в этом браузере не соответствует аккаунту. Войдите заново.',
+    action: 'retry',
+    keepSession: false,
+  },
+  [AuthV2ErrorCode.ConsentRequired]: {
+    message: 'Для экспорта удостоверения нужно подтверждение.',
+    action: 'retry',
+    keepSession: true,
+  },
+}
+
+/** Безопасный фолбэк для неожиданной (не-AuthV2) ошибки — без утечки технических деталей. */
+const GENERIC_ERROR_VIEW: AuthV2ErrorViewBody = {
+  message: 'Не удалось выполнить операцию. Попробуйте ещё раз.',
+  action: 'retry',
+  keepSession: true,
+}
+
+/**
+ * Превратить любую брошенную SDK ошибку в готовое к показу описание (Story 1.11):
+ * человеко-читаемое сообщение, рекомендованное действие и флаг сохранения сессии.
+ * Не-типизированные ошибки сводятся к безопасному фолбэку (не показываем `e.message`).
+ */
+export function describeAuthV2Error(error: unknown): AuthV2ErrorView {
+  if (error instanceof AuthV2Error)
+    return { code: error.code, ...AUTH_V2_ERROR_VIEWS[error.code] }
+  return { code: null, ...GENERIC_ERROR_VIEW }
+}

components/auth/src/export/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Экспорт удостоверения наружу (QR для Vision/предъявления). В MVP существует
+ * только ПОЛНАЯ форма (`full_certificate`) — она несёт PII пайщика, поэтому
+ * огорожена двумя барьерами (разблокированный vault + явное согласие).
+ *
+ * ROADMAP (Growth): анонимная форма `proof_of_membership` — доказательство членства
+ * БЕЗ PII, с коротким сроком (`exp ≤ 24ч`). Она появится отдельным методом
+ * `exportProofQR()`. В MVP его НЕТ намеренно: пока anonymous-формат не существует,
+ * вызвать `exportProofQR()` нельзя (ошибка компиляции) — чтобы по ошибке не выпустить
+ * PII-полный сертификат под видом anonymous.
+ */
+import { AuthV2Error, AuthV2ErrorCode } from '../errors'
+import { isWalletUnlocked } from '../wallet'
+
+export interface ExportFullQROptions {
+  /**
+   * Колбэк high-stakes-consent диалога: хост показывает пайщику явное подтверждение
+   * («вы экспортируете удостоверение с персональными данными») и резолвит `true`,
+   * только если пайщик согласился. `false`/reject → экспорт отклоняется.
+   */
+  confirm: () => Promise<boolean>
+}
+
+/**
+ * Экспорт ПОЛНОГО participant_certificate (с PII) для предъявления/QR. Доступен
+ * только когда (1) vault разблокирован — экспортирует владелец активной сессии, не
+ * случайный держатель запертого устройства; (2) пайщик явно подтвердил high-stakes
+ * consent. Возвращает payload-байты удостоверения; кодирование в визуальный QR —
+ * на стороне хоста/Vision (SDK кросс-рантайм, QR-рендерер не тянет).
+ */
+export async function exportFullQR(certificate: string, options: ExportFullQROptions): Promise<Uint8Array> {
+  if (!isWalletUnlocked())
+    throw new AuthV2Error(AuthV2ErrorCode.WalletLocked, 'Экспорт удостоверения возможен только при разблокированном кошельке')
+
+  const consented = await options.confirm().catch(() => false)
+  if (!consented)
+    throw new AuthV2Error(AuthV2ErrorCode.ConsentRequired, 'Экспорт удостоверения с персональными данными требует явного подтверждения')
+
+  return new TextEncoder().encode(certificate)
+}

components/auth/src/index.ts

@@ -0,0 +1,49 @@
+export type { CertificateRenewalHandle, CertificateStatus, CoopChainLink, CoopIdSchemaPolicy, ParticipantCertificateClaims, ScheduleCertificateRenewalOptions, SchemaPolicyCache, SchemaPolicyCacheOptions, VerificationTypeClaim } from './certificate'
+export {
+  CERTIFICATE_EXPIRING_WINDOW_MS,
+  CERTIFICATE_RENEWAL_LEAD_MS,
+  certificateStatus,
+  compareSchemaVersions,
+  computeRenewalDelayMs,
+  createSchemaPolicyCache,
+  decodeParticipantCertificate,
+  isSchemaVersionSupported,
+  scheduleCertificateRenewal,
+  SCHEMA_POLICY_CACHE_TTL_MS,
+  SCHEMA_POLICY_WELL_KNOWN_PATH,
+  VERIFICATION_TYPE_LABELS,
+  verificationTypeLabel,
+} from './certificate'
+
+export type { KeyValidityWindow, VerifyDocumentParams, VerifyDocumentReason, VerifyDocumentResult, VerifyOfflineOptions, VerifyOfflineReason, VerifyOfflineResult } from './chain'
+
+export { readCertPublicKey, verifyDocumentOffline, verifyOffline } from './chain'
+/**
+ * @coopenomics/auth — SDK аутентификации CoopID.
+ *
+ * Публичная поверхность зафиксирована скелетом (Story 1.2): все методы
+ * типизированы и бросают AuthV2Error(not_implemented) до своей реализации.
+ */
+export { COOPOS_PUBLIC_NODES } from './config/coopos-public-nodes'
+
+export { TRUST_ANCHOR_ANO_CERT_PUBKEY } from './config/trust-anchor'
+export { AUTH_V2_ERROR_VIEWS, AuthV2Error, AuthV2ErrorCode, describeAuthV2Error } from './errors'
+export type { AuthV2ErrorAction, AuthV2ErrorView } from './errors'
+
+export type { ExportFullQROptions } from './export'
+export { exportFullQR } from './export'
+export type { MigrateParams } from './migration'
+
+export { canonicalMigrationMessage, migrate } from './migration'
+export type { FlowExecutorParams, HandshakeResult, LoginParams, LoginResult, LogoutParams, SessionTokens } from './oidc'
+
+export { authenticateWithFlowExecutor, configureCoopId, configureOidc, configureTokenStorage, currentTokens, DEFAULT_AUTHENTICATION_FLOW, getAccessToken, getParticipantCertificate, login, loginWithMagicLink, logout, performTimestampHandshake, recover, restoreSession } from './oidc'
+export type { SignDocumentParams, TimestampSignature } from './signing'
+
+export { canonicalTimestampMessage, signChainDigest, signDocument, signTimestamp } from './signing'
+export type { EncryptedVaultBlob, VaultSubject } from './vault'
+
+export { ARGON2ID_PARAMS, decryptPrivateKey, deriveKey, encryptPrivateKey } from './vault'
+export type { StorageAdapter } from './wallet'
+
+export { clearLocalVault, clearPinCache, DEFAULT_PIN, fetchVaultBlob, getWallet, hasPinCache, isWalletUnlocked, loadLocalVault, lockWallet, persistPinCache, rotateKey, saveLocalVault, saveToVault, storeVaultBlob, unlockWallet, unlockWithPin, Wallet } from './wallet'

components/auth/src/migration/index.ts

@@ -0,0 +1,90 @@
+/**
+ * Миграция действующего пайщика «ключ → пароль» (Story 11.4), клиентская сторона.
+ *
+ * Пайщик сейчас владеет только WIF (легаси, без пароля). `migrate` доказывает
+ * владение ключом подписью метки времени (как легаси `login`), сервер проверяет
+ * её против он-чейн active-permission и ставит пароль в authentik (Story 11.1).
+ * Затем клиент шифрует ТОТ ЖЕ WIF новым паролём в vault (Story 11.3) — приватный
+ * ключ на сервер не уходит. Идемпотентно (повтор с тем же ключом/паролём безопасен).
+ *
+ * Подпись биндится к новому паролю через `pw_hash` в каноническом сообщении:
+ * перехваченный proof нельзя переиспользовать с другим паролём.
+ */
+import { AuthV2Error, AuthV2ErrorCode } from '../errors'
+import { coopIdApiUrl } from '../oidc/client'
+import { saveToVault, type StorageAdapter } from '../wallet'
+
+export interface MigrateParams {
+  email: string
+  /** WIF, которым пайщик владеет сейчас (легаси-ключ из поля входа). */
+  privateKey: string
+  newPassword: string
+  /** Если задано — сохранить локальную копию зашифрованного vault'а на устройстве. */
+  storage?: StorageAdapter
+}
+
+/**
+ * Каноническое сообщение proof'а миграции — **зеркало** серверного
+ * `canonicalMigrationMessage` (controller). Ключи в фиксированном алфавитном
+ * порядке: клиент и сервер собирают строку байт-в-байт, иначе `recoverPublicKey`
+ * на сервере восстановит чужой ключ. `pw_hash` — sha256-hex нового пароля.
+ */
+export function canonicalMigrationMessage(payload: { ts: string, pw_hash: string }): string {
+  return JSON.stringify({ pw_hash: payload.pw_hash, purpose: 'coopid-key-migration', ts: payload.ts })
+}
+
+/** sha256-hex (lowercase) — байт-в-байт совпадает с серверным createHash('sha256').digest('hex'). */
+async function sha256Hex(input: string): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input))
+  return Array.from(new Uint8Array(digest), b => b.toString(16).padStart(2, '0')).join('')
+}
+
+/** Разобрать OAuth2-ошибку контроллера ({ error, error_description }) в AuthV2Error. */
+async function authErrorFromResponse(res: Response, fallback: AuthV2ErrorCode, fallbackMsg: string): Promise<AuthV2Error> {
+  const body = (await res.json().catch(() => null)) as { error?: string, error_description?: string } | null
+  return new AuthV2Error((body?.error as AuthV2ErrorCode) ?? fallback, body?.error_description ?? fallbackMsg)
+}
+
+/**
+ * Выполнить миграцию «ключ → пароль». Возвращает `{ username }` (резолвится
+ * сервером по email; нужен как subject vault'а). Бросает `AuthV2Error`:
+ * InvalidCredentials (неверный ключ/email/подпись), WeakPassword, TimestampTooOld,
+ * CooposDegraded, NetworkError.
+ */
+export async function migrate(params: MigrateParams): Promise<{ username: string }> {
+  const apiUrl = coopIdApiUrl()
+  const ts = new Date().toISOString()
+  const message = canonicalMigrationMessage({ ts, pw_hash: await sha256Hex(params.newPassword) })
+
+  // Подпись текущим ключом (recoverable SIG_K1_). Невалидный WIF → понятная ошибка.
+  const { PrivateKey } = await import('@wharfkit/antelope')
+  let signature: string
+  try {
+    signature = PrivateKey.from(params.privateKey).signMessage(new TextEncoder().encode(message)).toString()
+  }
+  catch {
+    throw new AuthV2Error(AuthV2ErrorCode.InvalidCredentials, 'Некорректный приватный ключ')
+  }
+
+  let res: Response
+  try {
+    res = await fetch(`${apiUrl}/coop/migration`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ email: params.email, timestamp: ts, signature, new_password: params.newPassword }),
+    })
+  }
+  catch (e) {
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Сеть недоступна при миграции: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (!res.ok)
+    throw await authErrorFromResponse(res, AuthV2ErrorCode.InvalidCredentials, `Миграция отклонена (HTTP ${res.status})`)
+
+  const body = (await res.json()) as { username?: string }
+  if (!body?.username)
+    throw new AuthV2Error(AuthV2ErrorCode.ChainVerificationFailed, 'Миграция не вернула username')
+
+  // Зашифровать текущий WIF новым паролём → server vault (обязательно) + локальная копия.
+  await saveToVault({ apiUrl, account: body.username, privateKey: params.privateKey, password: params.newPassword, storage: params.storage })
+  return { username: body.username }
+}

components/auth/src/oidc/client.ts

@@ -0,0 +1,91 @@
+/**
+ * Первый этап входа CoopID (Story 11.2) — password через authentik:
+ * (1) встроенная форма гонит email+password в flow-executor authentik и
+ * устанавливает сессию (`flow-executor.ts`); (2) `oidc-client-ts` выполняет
+ * `authorization_code`+PKCE МОЛЧА (`signinSilent`, prompt=none) — сессия уже есть,
+ * второго ввода пароля нет. Так клиент видит пароль (нужно для vault, Story 11.3),
+ * не нарушая FR29: запрещённый `grant_type=password` не используется, грант —
+ * стандартный authorization_code+PKCE (Implicit и ROPC запрещены, RFC 9700).
+ *
+ * Конфигурация (client_id/redirect_uri/scope, база controller'а) задаётся
+ * приложением на старте через `configureOidc`/`configureCoopId` — это среда-зависимые
+ * параметры (frontend кооператива), не зашитые в SDK.
+ */
+import { type User, UserManager, type UserManagerSettings } from 'oidc-client-ts'
+import { AuthV2Error, AuthV2ErrorCode } from '../errors'
+import { authenticateWithFlowExecutor } from './flow-executor'
+
+interface OidcClientConfig {
+  clientId: string
+  redirectUri: string
+  scope: string
+  postLogoutRedirectUri?: string
+  /** redirect_uri скрытого silent-iframe для prompt=none authorize (Story 11.2). */
+  silentRedirectUri?: string
+}
+
+let oidcConfig: OidcClientConfig | null = null
+let coopApiUrl: string | null = null
+
+/** Конфигурация OIDC-клиента authentik (вызывается приложением на старте). */
+export function configureOidc(config: { clientId: string, redirectUri: string, scope?: string, postLogoutRedirectUri?: string, silentRedirectUri?: string }): void {
+  oidcConfig = {
+    clientId: config.clientId,
+    redirectUri: config.redirectUri,
+    scope: config.scope ?? 'openid profile',
+    postLogoutRedirectUri: config.postLogoutRedirectUri,
+    silentRedirectUri: config.silentRedirectUri,
+  }
+}
+
+/** База URL controller'а кооператива (для второго этапа: bind/verify/refresh). */
+export function configureCoopId(config: { apiUrl: string }): void {
+  coopApiUrl = config.apiUrl.replace(/\/$/, '')
+}
+
+/** База controller'а или явная ошибка конфигурации. */
+export function coopIdApiUrl(): string {
+  if (!coopApiUrl)
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, 'CoopID не сконфигурирован: вызовите configureCoopId({ apiUrl }) на старте приложения')
+  return coopApiUrl
+}
+
+function userManager(issuer: string): UserManager {
+  if (!oidcConfig)
+    throw new AuthV2Error(AuthV2ErrorCode.InvalidCredentials, 'OIDC не сконфигурирован: вызовите configureOidc({ clientId, redirectUri }) на старте приложения')
+  const settings: UserManagerSettings = {
+    authority: issuer.replace(/\/$/, ''),
+    client_id: oidcConfig.clientId,
+    redirect_uri: oidcConfig.redirectUri,
+    silent_redirect_uri: oidcConfig.silentRedirectUri ?? oidcConfig.redirectUri,
+    scope: oidcConfig.scope,
+    post_logout_redirect_uri: oidcConfig.postLogoutRedirectUri,
+    response_type: 'code', // Authorization Code + PKCE; oidc-client-ts включает PKCE по умолчанию.
+  }
+  return new UserManager(settings)
+}
+
+/**
+ * Проводит первый этап входа и возвращает OIDC-User (id_token/access_token +
+ * установленная сессионная cookie authentik, нужная для bind). Story 11.2:
+ * (1) встроенная форма → flow-executor authentik устанавливает сессию (фактор 1);
+ * (2) `signinSilent` выполняет authorization_code+PKCE молча (сессия уже есть,
+ * prompt=none через скрытый iframe `silent_redirect_uri`) — без попапа и без
+ * повторного ввода пароля.
+ */
+export async function authenticateWithAuthentik(params: { issuer: string, email: string, password: string, flowSlug?: string }): Promise<User> {
+  // Фактор-1: учётные данные уходят в authentik (а не в наш backend) — ROPC не используется.
+  await authenticateWithFlowExecutor({ issuer: params.issuer, email: params.email, password: params.password, flowSlug: params.flowSlug })
+  // Грант FR29: code+PKCE поверх уже установленной сессии, без интерактивного UI.
+  const um = userManager(params.issuer)
+  let user: User | null
+  try {
+    user = await um.signinSilent()
+  }
+  catch (e) {
+    throw new AuthV2Error(AuthV2ErrorCode.InvalidCredentials, `Не удалось завершить вход через authentik: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (!user)
+    throw new AuthV2Error(AuthV2ErrorCode.InvalidCredentials, 'authentik не вернул сессию после ввода пароля')
+  return user
+}

components/auth/src/oidc/flow-executor.ts

@@ -0,0 +1,160 @@
+/**
+ * Story 11.2 — встроенный фактор-1 входа CoopID через flow-executor authentik.
+ *
+ * Зачем НЕ popup/redirect: desktop рисует СВОЮ форму email+password и гонит
+ * учётные данные в интерактивный flow-API authentik. Так клиент пайщика ВИДИТ
+ * пароль — это нужно, чтобы шифровать им password-vault (Story 11.3); требование
+ * вынуждено zero-knowledge-инвариантом vault'а (сервер хранит шифр и расшифровать
+ * не может → ключ шифрования обязан быть клиентским секретом, единственный такой
+ * секрет — пароль). FR29 при этом соблюдается: запрещённый `grant_type=password`
+ * НЕ используется — грант остаётся `authorization_code`+PKCE и выполняется в
+ * `client.ts` уже ПОСЛЕ установки сессии (см. `authenticateWithAuthentik`).
+ *
+ * Топология (Эпик 5, Caddyfile): flow-API доступен same-origin по
+ * `{issuer.origin}/api/v3/flows/executor/<slug>/` — Caddy catch-all проксирует всё
+ * на authentik под доменом кооператива. `credentials:'include'` доставляет и
+ * устанавливает сессионную cookie authentik; CSRF-cookie (`authentik_csrf`) эхо-
+ * отправляется в заголовке `X-authentik-CSRF` (authentik требует его на unsafe-
+ * методах API). Same-origin критичен: кросс-домен CSRF-cookie не прочитать, а
+ * сессионная cookie не доедет до последующего authorize.
+ */
+import { AuthV2Error, AuthV2ErrorCode } from '../errors'
+
+/** Slug стандартного flow аутентификации authentik (identification → password). */
+export const DEFAULT_AUTHENTICATION_FLOW = 'default-authentication-flow'
+
+/** Предохранитель от зацикливания на неожиданной последовательности стадий. */
+const MAX_FLOW_STEPS = 8
+
+export interface FlowExecutorParams {
+  /** Issuer кооператива (`https://coop.example/application/o/coopid/`); origin — база flow-API. */
+  issuer: string
+  email: string
+  password: string
+  /** Slug flow аутентификации authentik (по умолчанию `default-authentication-flow`). */
+  flowSlug?: string
+}
+
+/** Снимок challenge'а flow-executor (берём только нужные поля; authentik отдаёт больше). */
+interface FlowChallenge {
+  /** `native` | `redirect` | `shell` — `redirect` означает завершение flow (сессия установлена). */
+  type?: string
+  /** Web-компонент текущей стадии: `ak-stage-identification`, `ak-stage-password`, … */
+  component?: string
+  /** Пер-полевые ошибки валидации (неверный пароль → перерисованная стадия с этим полем). */
+  response_errors?: Record<string, Array<{ string?: string, code?: string }>>
+}
+
+/** Текущий CSRF-токен authentik из cookie (same-origin). В Node/тестах — пусто. */
+function csrfHeader(): Record<string, string> {
+  if (typeof document === 'undefined' || !document.cookie)
+    return {}
+  const match = document.cookie.match(/(?:^|;\s*)authentik_csrf=([^;]+)/)
+  return match ? { 'X-authentik-CSRF': decodeURIComponent(match[1]) } : {}
+}
+
+/** URL шага flow-executor. `query` пуст: flow запускается напрямую (authorize делает client.ts). */
+function flowUrl(base: string, slug: string): string {
+  return `${base}/api/v3/flows/executor/${encodeURIComponent(slug)}/?query=${encodeURIComponent('')}`
+}
+
+/** Завершение flow: сессия authentik установлена (redirect-терминал или стадия user-login). */
+function isSuccess(c: FlowChallenge): boolean {
+  return c.type === 'redirect' || c.component === 'xak-flow-redirect' || c.component === 'ak-stage-user-login'
+}
+
+/** Доступ отклонён политикой flow (например, аккаунт неактивен). */
+function isAccessDenied(c: FlowChallenge): boolean {
+  return c.component === 'ak-stage-access-denied'
+}
+
+/** Первое человеко-читаемое сообщение об ошибке валидации из challenge'а (если есть). */
+function firstResponseError(c: FlowChallenge): string | null {
+  const groups = c.response_errors
+  if (!groups)
+    return null
+  for (const key of Object.keys(groups)) {
+    const msg = groups[key]?.find(e => e.string)?.string
+    if (msg)
+      return msg
+  }
+  return Object.keys(groups).length > 0 ? '' : null
+}
+
+async function getChallenge(url: string): Promise<FlowChallenge> {
+  let res: Response
+  try {
+    res = await fetch(url, { method: 'GET', credentials: 'include', headers: { accept: 'application/json', ...csrfHeader() } })
+  }
+  catch (e) {
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Сеть недоступна на старте входа: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (!res.ok)
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `flow-executor (старт) вернул HTTP ${res.status}`)
+  return (await res.json()) as FlowChallenge
+}
+
+async function postChallenge(url: string, body: Record<string, unknown>): Promise<FlowChallenge> {
+  let res: Response
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      credentials: 'include',
+      headers: { 'content-type': 'application/json', 'accept': 'application/json', ...csrfHeader() },
+      body: JSON.stringify(body),
+    })
+  }
+  catch (e) {
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Сеть недоступна при отправке формы входа: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  // 400 — authentik перерисовывает ту же стадию с `response_errors` (неверный пароль);
+  // это валидное тело challenge'а, читаем его. Остальные не-ok — сетевая/конфиг ошибка.
+  if (!res.ok && res.status !== 400)
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `flow-executor вернул HTTP ${res.status}`)
+  return (await res.json()) as FlowChallenge
+}
+
+/**
+ * Проводит фактор-1 (email+password) через flow-executor authentik и устанавливает
+ * сессионную cookie. Возвращает `void` при успехе (сессия — побочный эффект cookie),
+ * бросает `AuthV2Error(InvalidCredentials)` при неверных учётных данных / отказе и
+ * `AuthV2Error(NetworkError)` при сетевом сбое.
+ *
+ * Поддерживаются стандартные стадии `ak-stage-identification` и `ak-stage-password`
+ * (в т.ч. совмещённая identification с `password_fields`). Интерактивные стадии
+ * вне scope встроенной формы (MFA-валидация, consent) → InvalidCredentials с
+ * пояснением: их обрабатывает отдельный эпик динамического 2FA.
+ */
+export async function authenticateWithFlowExecutor(params: FlowExecutorParams): Promise<void> {
+  const base = new URL(params.issuer).origin
+  const url = flowUrl(base, params.flowSlug ?? DEFAULT_AUTHENTICATION_FLOW)
+
+  let challenge = await getChallenge(url)
+  for (let step = 0; step < MAX_FLOW_STEPS; step++) {
+    if (isSuccess(challenge))
+      return
+
+    if (isAccessDenied(challenge))
+      throw new AuthV2Error(AuthV2ErrorCode.InvalidCredentials, 'Доступ запрещён: проверьте email и пароль')
+
+    const err = firstResponseError(challenge)
+    if (err !== null)
+      throw new AuthV2Error(AuthV2ErrorCode.InvalidCredentials, err || 'Неверный email или пароль')
+
+    switch (challenge.component) {
+      case 'ak-stage-identification':
+        // Совмещённая identification может ждать и пароль (`password_fields`) — отдаём оба.
+        challenge = await postChallenge(url, { uid_field: params.email, password: params.password })
+        break
+      case 'ak-stage-password':
+        challenge = await postChallenge(url, { password: params.password })
+        break
+      default:
+        throw new AuthV2Error(
+          AuthV2ErrorCode.InvalidCredentials,
+          `Стадия входа «${challenge.component ?? challenge.type ?? 'неизвестно'}» не поддерживается встроенной формой`,
+        )
+    }
+  }
+  throw new AuthV2Error(AuthV2ErrorCode.InvalidCredentials, 'Вход не завершён: превышено число шагов flow authentik')
+}

components/auth/src/oidc/handshake.ts

@@ -0,0 +1,99 @@
+/**
+ * Второй этап входа CoopID — timestamp-signature handshake (Story 1.7), браузер-
+ * агностичная часть фасада логина. Предполагает уже установленную сессию authentik
+ * (cookie доезжает на bind через `credentials: 'include'`); первый этап (password,
+ * Authorization Code + PKCE через oidc-client-ts, FR29) делает `client.ts`.
+ *
+ * Поток: `/coop/session/bind` → `signTimestamp` (ключ берётся из keystore, наружу
+ * не выходит) → `/coop/verify/timestamp`. Полученные токены кладутся в сессию
+ * (`tokens.ts`) и возвращаются вызывающему.
+ */
+import { AuthV2Error, AuthV2ErrorCode } from '../errors'
+import { signTimestamp } from '../signing'
+import { setSession } from './tokens'
+
+export interface HandshakeResult {
+  accessToken: string
+  refreshToken: string
+  /** compact JWS ES256K, выпускается controller'ом (Story 1.8); может отсутствовать. */
+  participantCertificate?: string
+  /** true → вход выдан в degraded-режиме (узел недоступен / ключ не финализирован, Story 9.6). */
+  degraded: boolean
+  degradedReason?: string
+}
+
+interface BindResponse {
+  binding_token: string
+  expires_in: number
+}
+
+interface VerifyResponse {
+  access_token: string
+  refresh_token: string
+  participant_certificate?: string
+  degraded?: boolean
+  degraded_reason?: string
+}
+
+/** Извлечь AuthV2Error из тела ответа контроллера (OAuth2-формат { error, error_description }). */
+async function authErrorFromResponse(res: Response, fallback: AuthV2ErrorCode, fallbackMsg: string): Promise<AuthV2Error> {
+  const body = (await res.json().catch(() => null)) as { error?: string, error_description?: string } | null
+  const code = (body?.error as AuthV2ErrorCode) ?? fallback
+  return new AuthV2Error(code, body?.error_description ?? fallbackMsg)
+}
+
+/**
+ * Выполняет handshake второго этапа и сохраняет сессию. `apiUrl` — база controller'а
+ * кооператива (например `https://coop.example`).
+ */
+export async function performTimestampHandshake(apiUrl: string): Promise<HandshakeResult> {
+  const base = apiUrl.replace(/\/$/, '')
+
+  // 1. bind: session_binding_token из тела (Эпик 7, D2). credentials:'include' —
+  //    чтобы сессионная cookie authentik доехала до controller'а для резолва username.
+  let bindRes: Response
+  try {
+    bindRes = await fetch(`${base}/coop/session/bind`, { method: 'POST', credentials: 'include' })
+  }
+  catch (e) {
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Сеть недоступна на этапе bind: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (bindRes.status === 401 || bindRes.status === 403)
+    throw new AuthV2Error(AuthV2ErrorCode.InvalidCredentials, 'Сессия authentik не подтверждена: пройдите первый этап входа (password)')
+  if (!bindRes.ok)
+    throw await authErrorFromResponse(bindRes, AuthV2ErrorCode.NetworkError, `bind вернул HTTP ${bindRes.status}`)
+  const bind = (await bindRes.json()) as BindResponse
+  if (!bind?.binding_token)
+    throw new AuthV2Error(AuthV2ErrorCode.SessionBindingExpired, 'bind не вернул session_binding_token')
+
+  // 2. подпись канонической метки (jti/sub — из binding_token; ключ — из keystore,
+  //    бросит WalletLocked, если кошелёк заперт).
+  const sig = await signTimestamp({ sessionBindingToken: bind.binding_token })
+
+  // 3. verify: доказательство владения ключом → платформенные токены + сертификат.
+  let verifyRes: Response
+  try {
+    verifyRes = await fetch(`${base}/coop/verify/timestamp`, {
+      method: 'POST',
+      credentials: 'include',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ signature: sig.signature, timestamp: sig.ts, binding_token: bind.binding_token }),
+    })
+  }
+  catch (e) {
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Сеть недоступна на этапе verify: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (!verifyRes.ok)
+    throw await authErrorFromResponse(verifyRes, AuthV2ErrorCode.ChainVerificationFailed, `verify вернул HTTP ${verifyRes.status}`)
+
+  const v = (await verifyRes.json()) as VerifyResponse
+  setSession(base, { accessToken: v.access_token, refreshToken: v.refresh_token })
+
+  return {
+    accessToken: v.access_token,
+    refreshToken: v.refresh_token,
+    participantCertificate: v.participant_certificate,
+    degraded: Boolean(v.degraded),
+    degradedReason: v.degraded_reason,
+  }
+}

components/auth/src/oidc/index.ts

@@ -0,0 +1,248 @@
+import type { VaultSubject } from '../vault/types'
+import type { StorageAdapter } from '../wallet'
+/**
+ * OIDC-слой: вход через authentik (password + timestamp-signature),
+ * magic-link, recovery и работа с токенами (oidc-client-ts).
+ */
+import { AuthV2Error, AuthV2ErrorCode } from '../errors'
+import { encryptPrivateKey } from '../vault/encrypt'
+import { lockWallet, saveLocalVault, unlockWallet } from '../wallet'
+import { authenticateWithAuthentik, coopIdApiUrl } from './client'
+import { performTimestampHandshake } from './handshake'
+import { clearSession, getAccessToken as getStoredAccessToken } from './tokens'
+
+export { authenticateWithAuthentik, configureCoopId, configureOidc } from './client'
+export { authenticateWithFlowExecutor, DEFAULT_AUTHENTICATION_FLOW } from './flow-executor'
+export type { FlowExecutorParams } from './flow-executor'
+export type { HandshakeResult } from './handshake'
+export { performTimestampHandshake } from './handshake'
+export type { SessionTokens } from './tokens'
+export { configureTokenStorage, currentTokens, restoreSession } from './tokens'
+
+export interface LoginParams {
+  /** Issuer кооператива, например `https://coop.example/application/o/coopid/` */
+  issuer: string
+  email: string
+  /**
+   * Пароль пайщика (Story 11.2). Уходит во встроенную форму → flow-executor
+   * authentik (фактор 1), а не в наш backend — запрещённый FR29 `grant_type=password`
+   * не используется. Тем же паролем клиент шифрует password-vault (Story 11.3).
+   */
+  password: string
+  /** Slug flow аутентификации authentik (по умолчанию `default-authentication-flow`). */
+  flowSlug?: string
+}
+
+export interface LoginResult {
+  accessToken: string
+  idToken: string
+  /** compact JWS ES256K, выпускается controller'ом */
+  participantCertificate: string
+}
+
+/**
+ * Двухэтапный вход (Story 1.7, обновлён Story 11.2): (1) password через authentik —
+ * встроенная форма гонит email+password в flow-executor (сессия), затем
+ * `authorization_code`+PKCE молча (`signinSilent`); (2) timestamp-signature handshake
+ * против controller'а (bind → подпись ключом из keystore → verify). Перед вызовом
+ * кошелёк должен быть разблокирован (`unlockWallet`), иначе handshake бросит WalletLocked.
+ *
+ * База controller'а берётся из `configureCoopId({ apiUrl })`, OIDC-клиент — из
+ * `configureOidc({ clientId, redirectUri })` (вызываются приложением на старте).
+ */
+export async function login(params: LoginParams): Promise<LoginResult> {
+  const apiUrl = coopIdApiUrl()
+  // 1. password-этап: устанавливает сессию authentik (cookie) + отдаёт id_token.
+  const user = await authenticateWithAuthentik({ issuer: params.issuer, email: params.email, password: params.password, flowSlug: params.flowSlug })
+  // 2. timestamp-signature handshake: платформенные токены + удостоверение.
+  const handshake = await performTimestampHandshake(apiUrl)
+  return {
+    accessToken: handshake.accessToken,
+    idToken: user.id_token ?? '',
+    participantCertificate: handshake.participantCertificate ?? '',
+  }
+}
+
+/** Разобрать OAuth2-ошибку контроллера ({ error, error_description }) в AuthV2Error. */
+async function authErrorFromResponse(res: Response, fallback: AuthV2ErrorCode, fallbackMsg: string): Promise<AuthV2Error> {
+  const body = (await res.json().catch(() => null)) as { error?: string, error_description?: string } | null
+  return new AuthV2Error((body?.error as AuthV2ErrorCode) ?? fallback, body?.error_description ?? fallbackMsg)
+}
+
+export interface LoginWithMagicLinkParams {
+  /** Issuer кооператива — для повторного входа через authentik уже новым паролём. */
+  issuer: string
+  /** Email пайщика — фактор-1 повторной аутентификации в authentik после смены ключа. */
+  email: string
+  /** Magic-link токен из ссылки восстановления (или `recovery_token` offline-канала, Story 3.4). */
+  token: string
+  /** TOTP-код из приложения-аутентификатора — второй фактор подтверждения (Story 3.2/3.6). */
+  totp: string
+  /** Новый пароль: им шифруется новый vault и он же ставится в authentik (Story 12.1). */
+  newPassword: string
+  /** Slug flow аутентификации authentik (по умолчанию `default-authentication-flow`). */
+  flowSlug?: string
+  /** Если задано — сохранить локальную копию нового зашифрованного vault'а на устройстве. */
+  storage?: StorageAdapter
+}
+
+/**
+ * Вход по magic-link (восстановление доступа) — полный confirm-флоу + повторный вход
+ * (Эпик 12, Story 12.2). Старый ключ пайщиком утрачен (на то и восстановление),
+ * поэтому клиент генерит НОВУЮ пару: приватный шифруется новым паролём в vault и
+ * наружу/на сервер не уходит, on-chain едет только публичный.
+ *
+ * Account на старте неизвестен — magic-link несёт только непрозрачный `token`. Но он и
+ * не нужен заранее: AAD vault'а больше не зависит от account (см. `vault/encrypt.ts`),
+ * а username для повторного входа отдаёт сам `confirm`, резолвнув его из токена. Так
+ * обходимся без отдельного whoami-by-token эндпоинта.
+ *
+ * Шаги: (1) сгенерировать пару; (2) зашифровать новый ключ новым паролём (AAD=тип
+ * субъекта, без account); (3) `POST /coop/recovery/confirm` {token, TOTP, public_key,
+ * vault, password} — сервер (12.1) ставит пароль в authentik, сохраняет vault под нужным
+ * account, ротирует active-ключ (`registrator::changekey`), отзывает старые сессии и
+ * возвращает `{ username }`; (4) повторный вход новым контуром: authentik-сессия новым
+ * паролём → `unlockWallet` по этому username (скачать только что записанный блоб →
+ * расшифровать → keystore) → timestamp-handshake. Ключ к этому моменту уже ротирован
+ * on-chain, поэтому verify увидит новый pubkey (при лаге узла handshake вернёт degraded,
+ * Story 9.6).
+ */
+export async function loginWithMagicLink(params: LoginWithMagicLinkParams): Promise<LoginResult> {
+  const apiUrl = coopIdApiUrl()
+
+  // 1. Новая пара ключей (старый утрачен). WIF в формате `5J…`/`5K…` — как везде в системе.
+  const { PrivateKey } = await import('@wharfkit/antelope')
+  const newKey = PrivateKey.generate('K1')
+  const newPrivateKey = newKey.toWif()
+  const newPublicKey = newKey.toPublic().toString()
+
+  // 2. Зашифровать новый ключ новым паролём. AAD = тип субъекта (`participant`), а не
+  //    account: id в AAD не участвует (см. vault/encrypt.ts), поэтому шифруем, не зная
+  //    username. Сервер сохранит блоб под нужным account сам (по recovery-токену).
+  const subject: VaultSubject = { subject_type: 'participant', subject_id: '' }
+  const vaultBlob = await encryptPrivateKey(newPrivateKey, params.newPassword, subject)
+
+  // 3. confirm: токен magic-link + TOTP + новый материал. Тело — контракт RecoveryConfirmBody.
+  let res: Response
+  try {
+    res = await fetch(`${apiUrl}/coop/recovery/confirm`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ token: params.token, code: params.totp, public_key: newPublicKey, vault: vaultBlob, password: params.newPassword }),
+    })
+  }
+  catch (e) {
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Сеть недоступна при подтверждении восстановления: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (res.status === 429)
+    throw new AuthV2Error(AuthV2ErrorCode.TooManyRecoveryAttempts, 'Слишком много попыток подтверждения, попробуйте позже')
+  if (!res.ok)
+    throw await authErrorFromResponse(res, AuthV2ErrorCode.InvalidRecoveryToken, `Подтверждение восстановления отклонено (HTTP ${res.status})`)
+
+  // confirm вернул account пайщика (резолвнут из токена) — по нему скачаем и
+  // расшифруем только что сохранённый сервером блоб при повторном входе.
+  const confirmed = (await res.json().catch(() => null)) as { username?: string } | null
+  if (!confirmed?.username)
+    throw new AuthV2Error(AuthV2ErrorCode.InvalidRecoveryToken, 'Подтверждение восстановления не вернуло аккаунт')
+  const account = confirmed.username
+
+  // 4. Локальная копия нового блоба (best-effort на устройстве восстановления).
+  if (params.storage)
+    await saveLocalVault(params.storage, account, vaultBlob)
+
+  // 5. Повторный вход новым контуром. unlockWallet забирает только что сохранённый
+  //    серверный блоб и расшифровывает новым паролём — заодно round-trip-проверка vault'а.
+  const user = await authenticateWithAuthentik({ issuer: params.issuer, email: params.email, password: params.newPassword, flowSlug: params.flowSlug })
+  await unlockWallet({ apiUrl, account, password: params.newPassword })
+  const handshake = await performTimestampHandshake(apiUrl)
+  return {
+    accessToken: handshake.accessToken,
+    idToken: user.id_token ?? '',
+    participantCertificate: handshake.participantCertificate ?? '',
+  }
+}
+
+/**
+ * Запросить восстановление доступа (magic-link на email; по стратегии кооператива
+ * — также offline-код). Эпик 3, `POST /coop/recovery/request`. Анти-enumeration:
+ * сервер всегда отвечает 202 вне зависимости от существования аккаунта.
+ */
+export async function recover(email: string): Promise<void> {
+  const base = coopIdApiUrl()
+  let res: Response
+  try {
+    res = await fetch(`${base}/coop/recovery/request`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ email }),
+    })
+  }
+  catch (e) {
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Сеть недоступна при запросе восстановления: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  // 202 — нормальный путь; иные коды (кроме rate-limit) — ошибка конфигурации/сети.
+  if (res.status === 429)
+    throw new AuthV2Error(AuthV2ErrorCode.TooManyRecoveryAttempts, 'Слишком много попыток восстановления, попробуйте позже')
+  if (!res.ok && res.status !== 202)
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Запрос восстановления отклонён (HTTP ${res.status})`)
+}
+
+/** Текущий access_token (с автообновлением через refresh). Story 1.7. */
+export async function getAccessToken(): Promise<string> {
+  return getStoredAccessToken()
+}
+
+/**
+ * Актуальное participant_certificate текущей сессии — compact JWS из
+ * `GET /coop/certificate` (Story 1.8). `accessToken` — платформенный токен входа
+ * (Bearer). Декодирование claims — `decodeParticipantCertificate` (certificate/).
+ */
+export async function getParticipantCertificate(apiUrl: string, accessToken: string): Promise<string> {
+  let res: Response
+  try {
+    res = await fetch(`${apiUrl.replace(/\/$/, '')}/coop/certificate`, {
+      headers: { authorization: `Bearer ${accessToken}` },
+    })
+  }
+  catch (e) {
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Сеть недоступна при запросе удостоверения: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (!res.ok)
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Не удалось получить удостоверение (HTTP ${res.status})`)
+  const body = (await res.json()) as { participant_certificate: string }
+  return body.participant_certificate
+}
+
+export interface LogoutParams {
+  /** Базовый URL controller'а кооператива (например `https://coop.example`). */
+  apiUrl: string
+  /** refresh_token текущей сессии — отзывается на сервере. */
+  refreshToken: string
+  /** access_token (опционально) — тоже отзывается. */
+  accessToken?: string
+}
+
+/**
+ * RP-initiated logout (Story 1.10): отзыв токенов на сервере + затирание локального
+ * keystore. Серверный вызов — best-effort; локальное затирание ключа и сессии
+ * выполняется ВСЕГДА (в `finally`), даже если сервер недоступен — безопасность важнее
+ * «чистого» logout: расшифрованный ключ не должен остаться в памяти браузера при
+ * сетевом сбое. Редирект на login — на стороне вызывающего. Стандартный OIDC
+ * end-session — Story 5.1.
+ */
+export async function logout(params: LogoutParams): Promise<void> {
+  try {
+    await fetch(`${params.apiUrl.replace(/\/$/, '')}/coop/logout`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ refresh_token: params.refreshToken, access_token: params.accessToken }),
+    })
+  }
+  catch {
+    // best-effort: недоступность сервера не должна блокировать локальное затирание ключа
+  }
+  finally {
+    lockWallet()
+    clearSession()
+  }
+}

components/auth/src/oidc/tokens.ts

@@ -0,0 +1,147 @@
+import type { StorageAdapter } from '../wallet/storage-adapter'
+/**
+ * Lifecycle платформенных токенов сессии CoopID (Эпик 7). Источник истины токена —
+ * этот модуль `@coopenomics/auth`; `@coopenomics/sdk` копирует access в свои
+ * GraphQL-заголовки (D1: bearer не покидает слой SDK, приложение его не трогает).
+ *
+ * Хранение — in-memory (как keystore ключа): по умолчанию живёт только в RAM
+ * вкладки. Персистентность между перезагрузками подключается приложением через
+ * `StorageAdapter` (frontend — IndexedDB), чтобы крипто-/токен-логика не зависела
+ * от среды и тестировалась без браузера.
+ */
+import { decodeJwt } from 'jose'
+import { AuthV2Error, AuthV2ErrorCode } from '../errors'
+
+export interface SessionTokens {
+  accessToken: string
+  refreshToken: string
+}
+
+/** Запас до фактического exp, при котором access считаем «пора обновлять». */
+const REFRESH_SKEW_SEC = 30
+
+let tokens: SessionTokens | null = null
+let apiBase: string | null = null
+
+/**
+ * Опциональная персистентность токенов между перезагрузками (паритет с легаси,
+ * у которого токены лежат в IndexedDB). По умолчанию контур RAM-only; приложение
+ * подключает `StorageAdapter` (frontend — IndexedDB) через `configureTokenStorage`.
+ * Без этого CoopID-сессия не переживала бы F5 (ключ поднимается из PIN-кэша, а
+ * токен терялся бы), т.е. была бы СЛАБЕЕ легаси.
+ */
+const TOKEN_STORAGE_KEY = 'coopid.session.tokens'
+let storage: StorageAdapter | null = null
+
+interface PersistedSession {
+  apiBase: string
+  tokens: SessionTokens
+}
+
+/** Подключает (или снимает — `null`) персистентность токенов сессии. */
+export function configureTokenStorage(adapter: StorageAdapter | null): void {
+  storage = adapter
+}
+
+/** Кладёт токены текущей сессии (вызывается из handshake/login/refresh). `apiUrl` — база controller'а для refresh. */
+export function setSession(apiUrl: string, next: SessionTokens): void {
+  apiBase = apiUrl.replace(/\/$/, '')
+  tokens = next
+  // best-effort персист: сбой записи не должен ронять вход (токены уже в RAM).
+  if (storage)
+    void storage.set(TOKEN_STORAGE_KEY, JSON.stringify({ apiBase, tokens: next } satisfies PersistedSession)).catch(() => undefined)
+}
+
+/**
+ * Восстанавливает токены сессии из персистентного хранилища на старте приложения
+ * (после reload). `true` — сессия поднята в RAM. Уже активная RAM-сессия не
+ * перетирается. Без подключённого storage или записи — `false`.
+ */
+export async function restoreSession(): Promise<boolean> {
+  if (tokens && apiBase)
+    return true
+  if (!storage)
+    return false
+  const raw = await storage.get(TOKEN_STORAGE_KEY)
+  if (!raw)
+    return false
+  try {
+    const parsed = JSON.parse(raw) as PersistedSession
+    if (!parsed?.apiBase || !parsed?.tokens?.accessToken || !parsed?.tokens?.refreshToken)
+      return false
+    apiBase = parsed.apiBase
+    tokens = parsed.tokens
+    return true
+  }
+  catch {
+    return false
+  }
+}
+
+/** Затирает токены сессии (logout). Идемпотентно. Стирает и персистентную копию. */
+export function clearSession(): void {
+  tokens = null
+  apiBase = null
+  if (storage)
+    void storage.remove(TOKEN_STORAGE_KEY).catch(() => undefined)
+}
+
+/** Снимок текущих токенов (или null, если сессии нет). */
+export function currentTokens(): SessionTokens | null {
+  return tokens ? { ...tokens } : null
+}
+
+/** Истёк ли (или вот-вот истечёт) access-токен. Невалидный/без exp → считаем истёкшим. */
+function accessExpired(token: string): boolean {
+  try {
+    const { exp } = decodeJwt(token)
+    if (typeof exp !== 'number')
+      return true
+    return exp - REFRESH_SKEW_SEC <= Math.floor(Date.now() / 1000)
+  }
+  catch {
+    return true
+  }
+}
+
+/**
+ * Обновляет пару токенов через REST `/coop/refresh` (то же зеркало платформенной
+ * токен-машинерии, что и legacy GraphQL-refresh). 401 → сессия истекла/отозвана.
+ */
+export async function refreshSession(base: string, refreshToken: string): Promise<SessionTokens> {
+  let res: Response
+  try {
+    res = await fetch(`${base}/coop/refresh`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ refresh_token: refreshToken }),
+    })
+  }
+  catch (e) {
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Сеть недоступна при обновлении токена: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (res.status === 401 || res.status === 403)
+    throw new AuthV2Error(AuthV2ErrorCode.SessionBindingExpired, 'Сессия истекла: требуется повторный вход')
+  if (!res.ok)
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Не удалось обновить токен (HTTP ${res.status})`)
+
+  const body = (await res.json()) as { access_token: string, refresh_token: string }
+  return { accessToken: body.access_token, refreshToken: body.refresh_token }
+}
+
+/**
+ * Текущий access_token с авто-обновлением через refresh (Story 1.7). Бросает, если
+ * активной сессии нет (нужно войти). Обновлённую пару кладёт обратно в сессию.
+ */
+export async function getAccessToken(): Promise<string> {
+  if (!tokens || !apiBase)
+    throw new AuthV2Error(AuthV2ErrorCode.WalletLocked, 'Нет активной сессии: сначала выполните вход')
+  if (!accessExpired(tokens.accessToken))
+    return tokens.accessToken
+
+  const refreshed = await refreshSession(apiBase, tokens.refreshToken)
+  // setSession обновляет RAM И персистентную копию — иначе на диске остался бы
+  // устаревший refresh-токен и следующий reload поднял бы протухшую сессию.
+  setSession(apiBase, refreshed)
+  return refreshed.accessToken
+}

components/auth/src/signing/index.ts

@@ -0,0 +1,132 @@
+/**
+ * Подпись: документы (Story 2.3) и timestamp-метка второго этапа аутентификации
+ * (Story 2.4). Полностью локальные операции (без сети); подпись timestamp НЕ
+ * создаёт audit_events.
+ */
+import { base64url, decodeJwt } from 'jose'
+import { AuthV2Error, AuthV2ErrorCode } from '../errors'
+import { currentView, readUnlockedKey } from '../wallet/storage'
+
+export interface SignDocumentParams {
+  /** Содержимое документа: байты или строка (кодируется UTF-8). */
+  payload: Uint8Array | string
+  /** Алгоритм подписи; поддерживается ES256K (COOPOS-кривая secp256k1). */
+  alg?: 'ES256K'
+}
+
+/**
+ * Подпись дайджеста транзакции COOPOS ключом пайщика из keystore (мост подписи
+ * CoopID, Эпик 7). Приватный ключ НЕ покидает keystore — наружу уходит только
+ * готовая подпись `SIG_K1_…`. Это та же операция, что внутри
+ * `@wharfkit/wallet-plugin-privatekey`, но ключ берётся из RAM-keystore (2.2), а
+ * не из аргумента: десктопный `WalletPluginCoopId` делегирует сюда `sign()`, и
+ * wharfkit `Session.transact()` подписывает чужими руками, не зная ключа.
+ *
+ * Вход — hex-строка signing-дайджеста (`transaction.signingDigest(chainId)`),
+ * чтобы не тащить wharfkit-типы через границу пакета (иначе ловушка двойного
+ * `Checksum256` из разных копий antelope). Бросает `WalletLocked`, если заперт.
+ */
+export async function signChainDigest(digestHex: string): Promise<string> {
+  currentView() // бросает WalletLocked, если keystore заперт
+  const { PrivateKey, Checksum256 } = await import('@wharfkit/antelope')
+  const signature = PrivateKey.from(readUnlockedKey()).signDigest(Checksum256.from(digestHex))
+  return signature.toString()
+}
+
+export interface TimestampSignature {
+  ts: string
+  binding_token_jti: string
+  sub: string
+  signature: string
+  public_key: string
+}
+
+/**
+ * Каноническое сообщение, которое подписывается и которое сервер обязан собрать
+ * байт-в-байт для `recoverMessage` (`/coop/verify/timestamp`, Story 1.7). Ключи в
+ * фиксированном алфавитном порядке — детерминизм между клиентом и сервером.
+ * Экспортируется, чтобы controller переиспользовал ту же канонизацию.
+ */
+export function canonicalTimestampMessage(payload: { ts: string, binding_token_jti: string, sub: string }): string {
+  return JSON.stringify({ binding_token_jti: payload.binding_token_jti, sub: payload.sub, ts: payload.ts })
+}
+
+/**
+ * Локальная подпись документа ключом пайщика (Story 2.3). Возвращает compact JWS
+ * `<header>.<payload>.<signature>` (alg=ES256K). Полностью офлайн: без сети и без
+ * `audit_events` — сервер о подписи не знает (AC: подпись неоспорима и не зависит
+ * от состояния сервера).
+ *
+ * Подпись делается тем же кросс-рантайм secp256k1-примитивом, что и `signTimestamp`
+ * (`@wharfkit/antelope`): jose в браузере ES256K не умеет (WebCrypto без secp256k1),
+ * поэтому compact JWS собирается вручную, а K1-подпись сериализуется в JWS-формат
+ * R||S (recovery-байт отбрасывается — верификация по pubkey, не recover). `kid` в
+ * заголовке = COOPOS-аккаунт подписанта (разрешение ключа при верификации, Story 2.5).
+ */
+export async function signDocument(params: SignDocumentParams): Promise<string> {
+  const alg = params.alg ?? 'ES256K'
+  if (alg !== 'ES256K')
+    throw new AuthV2Error(AuthV2ErrorCode.ChainVerificationFailed, `Неподдерживаемый алгоритм подписи: ${alg}`)
+
+  const { account } = currentView() // бросает WalletLocked, если заперт
+  const wif = readUnlockedKey()
+
+  const payloadBytes = typeof params.payload === 'string'
+    ? new TextEncoder().encode(params.payload)
+    : params.payload
+
+  const header = base64url.encode(JSON.stringify({ alg, kid: account }))
+  const payloadB64 = base64url.encode(payloadBytes)
+  const signingInput = `${header}.${payloadB64}`
+
+  const { PrivateKey } = await import('@wharfkit/antelope')
+  const sig = PrivateKey.from(wif).signMessage(new TextEncoder().encode(signingInput))
+  // K1-подпись сериализуется как [recovery(1), r(32), s(32)] = 65б; JWS ES256K = R||S
+  // (64б) — recovery-байт не нужен (верификация по pubkey, не recover).
+  const rs = sig.data.array.slice(1)
+  return `${signingInput}.${base64url.encode(rs)}`
+}
+
+/**
+ * Подпись метки времени для второго этапа auth (Story 2.4). Берёт `sub`/`jti` из
+ * активного `session_binding_token` (Эпик 1: читаем claims без верификации —
+ * подпись делает локальный ключ, доверие даёт сервер при verify), подписывает
+ * каноническое `{ ts, binding_token_jti, sub }` COOPOS-native recoverable
+ * подписью (SIG_K1_..., секрет — из keystore 2.2). Схема самоописана префиксом
+ * SIG_K1_ — alg не хардкодим. Результат уходит в `/coop/verify/timestamp`, где
+ * сервер `recoverMessage` → сверяет pubkey с COOPOS `get_account`.
+ */
+export async function signTimestamp(params: { sessionBindingToken: string }): Promise<TimestampSignature> {
+  let claims: { sub?: string, jti?: string }
+  try {
+    claims = decodeJwt(params.sessionBindingToken)
+  }
+  catch {
+    throw new AuthV2Error(AuthV2ErrorCode.SessionBindingExpired, 'Некорректный session_binding_token: не удалось прочитать claims')
+  }
+  const sub = claims.sub
+  const jti = claims.jti
+  if (!sub || !jti)
+    throw new AuthV2Error(AuthV2ErrorCode.SessionBindingExpired, 'session_binding_token без обязательных claims sub/jti')
+
+  // Кошелёк должен принадлежать тому же субъекту, что и токен (иначе подпишем
+  // метку чужим ключом — сервер всё равно отвергнет, но ловим раньше и понятнее).
+  const wallet = currentView() // бросает WalletLocked, если заперт
+  if (wallet.account !== sub)
+    throw new AuthV2Error(AuthV2ErrorCode.ClientWalletMismatch, `Разблокированный кошелёк (${wallet.account}) не совпадает с субъектом токена (${sub})`)
+
+  const ts = new Date().toISOString()
+  const message = canonicalTimestampMessage({ ts, binding_token_jti: jti, sub })
+
+  const { PrivateKey } = await import('@wharfkit/antelope')
+  const pk = PrivateKey.from(readUnlockedKey())
+  const signature = pk.signMessage(new TextEncoder().encode(message))
+
+  return {
+    ts,
+    binding_token_jti: jti,
+    sub,
+    signature: signature.toString(),
+    public_key: pk.toPublic().toString(),
+  }
+}

components/auth/src/vault/encrypt.ts

@@ -0,0 +1,124 @@
+import { AuthV2Error, AuthV2ErrorCode } from '../errors'
+import { deriveKey } from './kdf'
+import type { EncryptedVaultBlob, VaultSubject } from './types'
+
+const CIPHER_VERSION = 'aes-256-gcm-v1'
+const KDF_VERSION = 'argon2id-v1'
+const SALT_LEN = 16
+const NONCE_LEN = 12
+
+function toB64Url(bytes: Uint8Array): string {
+  let bin = ''
+  for (const b of bytes) bin += String.fromCharCode(b)
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+export function fromB64Url(s: string): Uint8Array {
+  const bin = atob(s.replace(/-/g, '+').replace(/_/g, '/'))
+  const out = new Uint8Array(bin.length)
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+  return out
+}
+
+/**
+ * AAD GCM привязывает шифртекст к ТИПУ субъекта (`participant`/`coop`/…), но НЕ к
+ * конкретному account-id. Раньше было `${type}|${id}` — это требовало знать
+ * username ещё до confirm при восстановлении (Эпик 12), хотя сервер и так
+ * резолвит account из recovery-токена; так родился лишний whoami-by-token.
+ *
+ * Account-id убран из AAD намеренно (решение владельца 2026-06-15): пер-юзер
+ * привязку даёт пароль + случайная соль, лежащая в самом блобе; контролем доступа
+ * AAD здесь не был (блоб и так публично читается по account через `GET /coop/vault`).
+ * Поэтому теперь клиент шифрует новый ключ просто паролём, а account для
+ * последующей выборки/расшифровки блоба берёт из ответа confirm.
+ */
+function aad(subject: VaultSubject): string {
+  return subject.subject_type
+}
+
+/** WebCrypto в strict-TS требует ArrayBuffer-backed view; нормализуем Uint8Array. */
+function buf(u: Uint8Array): ArrayBuffer {
+  return u.buffer.slice(u.byteOffset, u.byteOffset + u.byteLength) as ArrayBuffer
+}
+
+/**
+ * Subject-агностичное ядро (Story 2.2): Argon2id(пароль, salt) → AES-256-GCM с
+ * произвольной AAD-строкой. Поверх него работает vault приватного ключа
+ * (AAD=субъект). PIN-слой (AAD=`pin|<account>`) снят в 11.8 (модель «без PIN»).
+ */
+export async function encryptWithPassword(
+  plaintext: string,
+  password: string,
+  additionalData: string,
+): Promise<EncryptedVaultBlob> {
+  const salt = crypto.getRandomValues(new Uint8Array(SALT_LEN))
+  const nonce = crypto.getRandomValues(new Uint8Array(NONCE_LEN))
+  const keyBytes = deriveKey(password, salt)
+
+  const key = await crypto.subtle.importKey('raw', buf(keyBytes), { name: 'AES-GCM' }, false, ['encrypt'])
+  const sealed = new Uint8Array(
+    await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv: buf(nonce), additionalData: buf(new TextEncoder().encode(additionalData)) },
+      key,
+      buf(new TextEncoder().encode(plaintext)),
+    ),
+  )
+  // WebCrypto склеивает ciphertext+tag; tag GCM — последние 16 байт.
+  const tagLen = 16
+  const ciphertext = sealed.slice(0, sealed.length - tagLen)
+  const authTag = sealed.slice(sealed.length - tagLen)
+
+  return {
+    cipher_version: CIPHER_VERSION,
+    kdf_version: KDF_VERSION,
+    salt: toB64Url(salt),
+    nonce: toB64Url(nonce),
+    ciphertext: toB64Url(ciphertext),
+    auth_tag: toB64Url(authTag),
+  }
+}
+
+/** Парная расшифровка ядра; неверный пароль/AAD → `VaultDecryptionFailed`. */
+export async function decryptWithPassword(
+  blob: EncryptedVaultBlob,
+  password: string,
+  additionalData: string,
+): Promise<string> {
+  const keyBytes = deriveKey(password, fromB64Url(blob.salt))
+  const key = await crypto.subtle.importKey('raw', buf(keyBytes), { name: 'AES-GCM' }, false, ['decrypt'])
+  const sealed = new Uint8Array([...fromB64Url(blob.ciphertext), ...fromB64Url(blob.auth_tag)])
+  try {
+    const plain = await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv: buf(fromB64Url(blob.nonce)), additionalData: buf(new TextEncoder().encode(additionalData)) },
+      key,
+      buf(sealed),
+    )
+    return new TextDecoder().decode(plain)
+  } catch {
+    throw new AuthV2Error(AuthV2ErrorCode.VaultDecryptionFailed, 'Не удалось расшифровать: неверный пароль или повреждённые данные')
+  }
+}
+
+/**
+ * Клиентское шифрование приватного ключа пайщика (Story 2.1). Сервер получает
+ * только результат — расшифровать может лишь владелец пароля (AAD=субъект).
+ */
+export async function encryptPrivateKey(
+  privateKey: string,
+  password: string,
+  subject: VaultSubject,
+): Promise<EncryptedVaultBlob> {
+  return encryptWithPassword(privateKey, password, aad(subject))
+}
+
+/**
+ * Локальная расшифровка (round-trip тесты и keystore 2.2). Серверу недоступна —
+ * type-driven ban (см. controller VaultService).
+ */
+export async function decryptPrivateKey(
+  blob: EncryptedVaultBlob,
+  password: string,
+  subject: VaultSubject,
+): Promise<string> {
+  return decryptWithPassword(blob, password, aad(subject))
+}

components/auth/src/vault/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Vault-слой: client-side шифрование/расшифровка приватного ключа
+ * (Argon2id + AES-256-GCM). Сервер хранит только зашифрованный блоб и не
+ * может его расшифровать (type-driven ban в controller VaultService).
+ */
+export type { EncryptedVaultBlob, VaultSubject } from './types'
+export { ARGON2ID_PARAMS, deriveKey } from './kdf'
+export { decryptPrivateKey, encryptPrivateKey, fromB64Url } from './encrypt'

components/auth/src/vault/kdf.ts

@@ -0,0 +1,17 @@
+import { argon2id } from '@noble/hashes/argon2'
+
+/** Параметры Argon2id KDF (CoopID): зафиксированы версией `argon2id-v1`. */
+export const ARGON2ID_PARAMS = {
+  m: 65536, // 64 MiB
+  t: 3,
+  p: 4,
+  dkLen: 32, // ключ AES-256
+} as const
+
+/**
+ * Деривация 32-байтного ключа из пароля и соли (Argon2id).
+ * Изоморфно: @noble/hashes работает в браузере, Node и desktop-runtime.
+ */
+export function deriveKey(password: string, salt: Uint8Array): Uint8Array {
+  return argon2id(new TextEncoder().encode(password), salt, ARGON2ID_PARAMS)
+}

components/auth/src/vault/types.ts

@@ -0,0 +1,15 @@
+/** Субъект, к которому привязан зашифрованный блоб (AAD). */
+export interface VaultSubject {
+  subject_type: 'participant' | 'coop' | 'council_action'
+  subject_id: string
+}
+
+/** Зашифрованный блоб vault'а: всё, что хранит и отдаёт сервер. base64url-поля. */
+export interface EncryptedVaultBlob {
+  cipher_version: string
+  kdf_version: string
+  salt: string
+  nonce: string
+  ciphertext: string
+  auth_tag: string
+}

components/auth/src/wallet/index.ts

@@ -0,0 +1,197 @@
+import type { EncryptedVaultBlob, VaultSubject } from '../vault/types'
+import type { StorageAdapter } from './storage-adapter'
+/**
+ * Кошелёк (Story 2.2): разблокировка после логина, доступ к публичному «виду»
+ * ключа в памяти, запирание на logout. Приватный ключ живёт ТОЛЬКО в keystore
+ * (storage.ts) и наружу не выходит — `Wallet` его не содержит и не сериализует.
+ * Desktop-кошелёк переезжает на этот модуль (миграция — Эпик 7).
+ */
+import { AuthV2Error, AuthV2ErrorCode, notImplemented } from '../errors'
+import { decryptPrivateKey, encryptPrivateKey } from '../vault/encrypt'
+import { saveLocalVault } from './local-vault'
+import { clearPinProtected, DEFAULT_PIN, hasPinProtected, loadPinProtected, savePinProtected } from './pin'
+import { currentView, isUnlocked, readUnlockedKey, storeUnlocked, wipeKeystore } from './storage'
+
+/**
+ * Несериализуемая обёртка кошелька: отдаёт только аккаунт и публичный ключ.
+ * Приватного ключа в объекте НЕТ — `JSON.stringify(wallet)` физически не может
+ * его раскрыть. Подпись (Stories 2.3/2.4) берёт ключ из keystore, не из Wallet.
+ */
+export class Wallet {
+  readonly account: string
+  readonly publicKey: string
+
+  constructor(view: { account: string, publicKey: string }) {
+    this.account = view.account
+    this.publicKey = view.publicKey
+  }
+
+  toJSON(): { account: string, publicKey: string } {
+    return { account: this.account, publicKey: this.publicKey }
+  }
+}
+
+/** Деривует публичный ключ из приватного (WIF K1) через WharfKit antelope. */
+async function derivePublicKey(privateKey: string): Promise<string> {
+  // Ленивый импорт: тяжёлый antelope не тянем в bundle, пока кошелёк не разблокируют.
+  const { PrivateKey } = await import('@wharfkit/antelope')
+  try {
+    return PrivateKey.from(privateKey).toPublic().toString()
+  }
+  catch {
+    throw new AuthV2Error(AuthV2ErrorCode.VaultDecryptionFailed, 'Расшифрованное значение не является валидным приватным ключом')
+  }
+}
+
+/** GET зашифрованного blob'а пайщика с контроллера (blob-only, см. 2.2). */
+export async function fetchVaultBlob(apiUrl: string, subjectId: string): Promise<EncryptedVaultBlob> {
+  let res: Response
+  try {
+    res = await fetch(`${apiUrl.replace(/\/$/, '')}/coop/vault/participant/${encodeURIComponent(subjectId)}`)
+  }
+  catch (e) {
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Сеть недоступна при запросе vault: ${e instanceof Error ? e.message : e}`)
+  }
+  if (!res.ok)
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Не удалось получить vault (HTTP ${res.status})`)
+  return res.json() as Promise<EncryptedVaultBlob>
+}
+
+/**
+ * POST зашифрованного blob'а на контроллер (Story 11.3, `POST /coop/vault`, 201).
+ * Тело — blob + плоские `subject_type`/`subject_id` (контракт `StoreVaultDto`).
+ * Сервер только сохраняет шифр и расшифровать его не может (type-ban в 2.1).
+ */
+export async function storeVaultBlob(apiUrl: string, subject: VaultSubject, blob: EncryptedVaultBlob): Promise<void> {
+  let res: Response
+  try {
+    res = await fetch(`${apiUrl.replace(/\/$/, '')}/coop/vault`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ ...blob, subject_type: subject.subject_type, subject_id: subject.subject_id }),
+    })
+  }
+  catch (e) {
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Сеть недоступна при сохранении vault: ${e instanceof Error ? e.message : e}`)
+  }
+  if (!res.ok)
+    throw new AuthV2Error(AuthV2ErrorCode.NetworkError, `Не удалось сохранить vault (HTTP ${res.status})`)
+}
+
+interface SaveToVaultParams {
+  apiUrl: string
+  account: string
+  privateKey: string
+  password: string
+  /** Если задано — дополнительно сохранить локальную копию зашифрованного blob'а. */
+  storage?: StorageAdapter
+}
+
+/**
+ * Шифрует приватный ключ паролём (Argon2id+AES-256-GCM, AAD=субъект) и сохраняет
+ * vault: на сервере (обязательно) и локально (если передан `storage`). Возвращает
+ * зашифрованный blob. Приватный ключ наружу/на сервер не уходит — только шифр.
+ * Используется миграцией «ключ→пароль» (Story 11.4) и сменой пароля.
+ */
+export async function saveToVault(params: SaveToVaultParams): Promise<EncryptedVaultBlob> {
+  const subject: VaultSubject = { subject_type: 'participant', subject_id: params.account }
+  const blob = await encryptPrivateKey(params.privateKey, params.password, subject)
+  await storeVaultBlob(params.apiUrl, subject, blob)
+  if (params.storage)
+    await saveLocalVault(params.storage, params.account, blob)
+  return blob
+}
+
+interface UnlockParams {
+  apiUrl: string
+  account: string
+  password: string
+}
+
+/**
+ * Полная разблокировка: забрать blob → расшифровать паролём на клиенте →
+ * положить ключ в keystore. При неверном пароле keystore остаётся пуст.
+ */
+export async function unlockWallet(params: UnlockParams): Promise<Wallet> {
+  const blob = await fetchVaultBlob(params.apiUrl, params.account)
+  const privateKey = await decryptPrivateKey(blob, params.password, {
+    subject_type: 'participant',
+    subject_id: params.account,
+  })
+  const publicKey = await derivePublicKey(privateKey)
+  storeUnlocked({ account: params.account, publicKey, privateKey })
+  return new Wallet({ account: params.account, publicKey })
+}
+
+/** Текущий разблокированный кошелёк. Бросает `WalletLocked`, если заперт. */
+export async function getWallet(): Promise<Wallet> {
+  return new Wallet(currentView())
+}
+
+/** Заперт ли кошелёк (нет ключа в памяти). */
+export function isWalletUnlocked(): boolean {
+  return isUnlocked()
+}
+
+/** Затирает ключ из памяти (logout). Идемпотентно. */
+export function lockWallet(): void {
+  wipeKeystore()
+}
+
+/** Ротация ключа пайщика (updateauth + перешифровка vault). Story 3.3. */
+export async function rotateKey(): Promise<void> {
+  notImplemented('rotateKey')
+}
+
+interface PersistPinParams {
+  /** ПИН для шифрования локального кэша; по умолчанию — `DEFAULT_PIN` ('000000', прозрачный). */
+  pin?: string
+  storage: StorageAdapter
+}
+
+/**
+ * Перешифровывает текущий разблокированный ключ ПИНом и кладёт в локальный кэш
+ * (уточнённая at-rest модель, см. `pin.ts`). Вызывается сразу после успешного
+ * `unlockWallet`/`migrate`, чтобы последующие входы шли по ПИН, а не по паролю.
+ * Бросает `WalletLocked`, если кошелёк заперт (нечего кэшировать). Ключ читается
+ * пакет-внутренней `readUnlockedKey()` и наружу не выходит — в кэш ложится шифр.
+ */
+export async function persistPinCache(params: PersistPinParams): Promise<void> {
+  const { account } = currentView() // бросает WalletLocked, если заперт
+  await savePinProtected(readUnlockedKey(), params.pin ?? DEFAULT_PIN, account, params.storage)
+}
+
+interface UnlockWithPinParams {
+  /** ПИН; по умолчанию — `DEFAULT_PIN` ('000000', прозрачная авто-разблокировка). */
+  pin?: string
+  storage: StorageAdapter
+}
+
+/**
+ * Разблокировка из локального PIN-кэша без round-trip к серверу и без пароля
+ * (reload устройства, авто-лок по простою). `null` — кэша нет (нужен полный вход
+ * `unlockWallet` паролём). Неверный ПИН → `VaultDecryptionFailed`. При успехе
+ * кладёт ключ в keystore и возвращает `Wallet`.
+ */
+export async function unlockWithPin(params: UnlockWithPinParams): Promise<Wallet | null> {
+  const loaded = await loadPinProtected(params.pin ?? DEFAULT_PIN, params.storage)
+  if (!loaded)
+    return null
+  const publicKey = await derivePublicKey(loaded.privateKey)
+  storeUnlocked({ account: loaded.account, publicKey, privateKey: loaded.privateKey })
+  return new Wallet({ account: loaded.account, publicKey })
+}
+
+/** Есть ли локальный PIN-кэш (выбор сценария разблокировки на загрузке). */
+export async function hasPinCache(storage: StorageAdapter): Promise<boolean> {
+  return hasPinProtected(storage)
+}
+
+/** Удаляет локальный PIN-кэш («забыть устройство» / смена аккаунта). */
+export async function clearPinCache(storage: StorageAdapter): Promise<void> {
+  await clearPinProtected(storage)
+}
+
+export { clearLocalVault, loadLocalVault, saveLocalVault } from './local-vault'
+export { DEFAULT_PIN } from './pin'
+export type { StorageAdapter } from './storage-adapter'

components/auth/src/wallet/local-vault.ts

@@ -0,0 +1,46 @@
+/**
+ * Локальная копия зашифрованного vault-блоба (Story 11.3). Хранит то же, что и
+ * сервер — Argon2id+AES-256-GCM ciphertext, бесполезный без пароля; расшифровать
+ * нельзя без знания пароля пайщика (zero-knowledge инвариант сохраняется и локально).
+ *
+ * Зачем дублировать серверную копию на устройстве: вход и подпись возможны без
+ * round-trip к контроллеру (офлайн/деградация узла), а также чтобы сразу после
+ * миграции (Story 11.4) ключ был доступен локально. Сервер остаётся источником
+ * истины и обязателен для входа с НОВОГО устройства (там локальной копии нет).
+ *
+ * Это НЕ расшифрованный ключ: расшифрованный WIF живёт только в RAM-keystore
+ * (`storage.ts`) и стирается на логауте (Story 11.8). Локально лежит лишь шифр.
+ */
+import type { EncryptedVaultBlob } from '../vault/types'
+import type { StorageAdapter } from './storage-adapter'
+
+const LOCAL_VAULT_KEY = 'coopid.wallet.vault'
+
+interface LocalVaultRecord {
+  account: string
+  blob: EncryptedVaultBlob
+}
+
+/** Сохраняет (перезаписывает) локальную копию зашифрованного blob'а пайщика. */
+export async function saveLocalVault(storage: StorageAdapter, account: string, blob: EncryptedVaultBlob): Promise<void> {
+  const record: LocalVaultRecord = { account, blob }
+  await storage.set(LOCAL_VAULT_KEY, JSON.stringify(record))
+}
+
+/**
+ * Возвращает локальную копию blob'а для `account` (или `null`, если записи нет /
+ * она от другого аккаунта). Подмена account → `null`: чужой blob не отдаём, даже
+ * расшифровать его без чужого пароля всё равно нельзя.
+ */
+export async function loadLocalVault(storage: StorageAdapter, account: string): Promise<EncryptedVaultBlob | null> {
+  const raw = await storage.get(LOCAL_VAULT_KEY)
+  if (!raw)
+    return null
+  const record = JSON.parse(raw) as LocalVaultRecord
+  return record.account === account ? record.blob : null
+}
+
+/** Удаляет локальную копию vault'а (смена аккаунта / «забыть устройство»). */
+export async function clearLocalVault(storage: StorageAdapter): Promise<void> {
+  await storage.remove(LOCAL_VAULT_KEY)
+}

components/auth/src/wallet/pin.ts

@@ -0,0 +1,77 @@
+import type { EncryptedVaultBlob } from '../vault/types'
+import type { StorageAdapter } from './storage-adapter'
+/**
+ * Локальный PIN-кэш приватного ключа (уточнённая модель CoopID, 2026-06-15 —
+ * СУПЕРДИТ «без PIN» из Story 11.8). Двухуровневая защита ключа:
+ *
+ *  1) Серверный vault ← ПАРОЛЬ (сложный, записан отдельно). Расшифровывается
+ *     только при входе; повторно пароль не спрашиваем. Защита от кражи блоба.
+ *  2) Локальный кэш ← ПИН (этот модуль). После входа расшифрованный WIF
+ *     перешифровывается ПИНом тем же Argon2id+AES-256-GCM и кладётся в
+ *     `StorageAdapter`. Дальнейшие разблокировки (reload, авто-лок по простою) —
+ *     ПИНом, НЕ паролём.
+ *
+ * Модель угроз: ПИН защищает не от похищения блоба (от него защищает пароль), а
+ * «от дурака» — постороннего/ребёнка за разблокированным устройством. ПИН по
+ * умолчанию `DEFAULT_PIN` ('000000') делает разблокировку прозрачной (ключ де-факто
+ * лежит локально с тривиальной защитой — осознанная плата за «не вводить пароль
+ * повторно»); кастомный ПИН поднимает планку до анти-«дурак» (6 цифр). AAD
+ * `pin|<account>` привязывает обёртку к аккаунту; account лежит в самой записи,
+ * поэтому знать его заранее не нужно (в отличие от серверного blob'а).
+ */
+import { decryptWithPassword, encryptWithPassword } from '../vault/encrypt'
+
+export type { StorageAdapter } from './storage-adapter'
+
+const STORAGE_KEY = 'coopid.wallet.pin-vault'
+
+/** Стандартный «прозрачный» ПИН: разблокировка происходит автоматически и незаметно. */
+export const DEFAULT_PIN = '000000'
+
+function aad(account: string): string {
+  return `pin|${account}`
+}
+
+interface PinRecord {
+  account: string
+  blob: EncryptedVaultBlob
+}
+
+/** Сохраняет ключ под ПИН в storage (перезаписывает предыдущую запись). */
+export async function savePinProtected(
+  privateKey: string,
+  pin: string,
+  account: string,
+  storage: StorageAdapter,
+): Promise<void> {
+  const blob = await encryptWithPassword(privateKey, pin, aad(account))
+  const record: PinRecord = { account, blob }
+  await storage.set(STORAGE_KEY, JSON.stringify(record))
+}
+
+/**
+ * Восстанавливает ключ из storage по ПИН. `null` — записи нет. Неверный ПИН →
+ * `VaultDecryptionFailed` (из ядра). Возвращает `{account, privateKey}` — account
+ * берётся из самой записи, знать его до разблокировки не требуется.
+ */
+export async function loadPinProtected(
+  pin: string,
+  storage: StorageAdapter,
+): Promise<{ account: string, privateKey: string } | null> {
+  const raw = await storage.get(STORAGE_KEY)
+  if (!raw)
+    return null
+  const record = JSON.parse(raw) as PinRecord
+  const privateKey = await decryptWithPassword(record.blob, pin, aad(record.account))
+  return { account: record.account, privateKey }
+}
+
+/** Есть ли локальный PIN-кэш (без расшифровки — для выбора сценария разблокировки). */
+export async function hasPinProtected(storage: StorageAdapter): Promise<boolean> {
+  return (await storage.get(STORAGE_KEY)) !== null
+}
+
+/** Удаляет PIN-запись (logout с «забыть устройство» / смена аккаунта). */
+export async function clearPinProtected(storage: StorageAdapter): Promise<void> {
+  await storage.remove(STORAGE_KEY)
+}

components/auth/src/wallet/storage-adapter.ts

@@ -0,0 +1,13 @@
+/**
+ * Подключаемый async key-value стор для персистентных артефактов кошелька
+ * (локальная копия vault'а — Story 11.3). PIN-слой снят в 11.8 (модель «без PIN»).
+ *
+ * Абстракция нужна для кросс-рантайма (NFR26): в браузере — обёртка над
+ * localStorage/IndexedDB, в desktop-runtime — своя реализация, в Node/тестах —
+ * память. Крипто и логика хранения от среды не зависят.
+ */
+export interface StorageAdapter {
+  get: (key: string) => Promise<string | null>
+  set: (key: string, value: string) => Promise<void>
+  remove: (key: string) => Promise<void>
+}

components/auth/src/wallet/storage.ts

@@ -0,0 +1,55 @@
+/**
+ * In-memory keystore (Story 2.2). ЕДИНСТВЕННОЕ место, где живёт расшифрованный
+ * приватный ключ пайщика — module-private переменная, только в RAM процесса/вкладки.
+ *
+ * Публичная поверхность SDK (`getWallet()`) приватный ключ НЕ отдаёт: signing-модули
+ * (Stories 2.3/2.4) берут его через пакет-внутреннюю `readUnlockedKey()`. На logout —
+ * `wipeKeystore()` затирает ключ (перезапись + сброс ссылки).
+ */
+import { AuthV2Error, AuthV2ErrorCode } from '../errors'
+
+interface UnlockedEntry {
+  account: string
+  publicKey: string
+  privateKey: string
+}
+
+/** Открытое состояние сессии. null = заперто. */
+let unlocked: UnlockedEntry | null = null
+
+/** Кладёт расшифрованный ключ в keystore (вызывается из unlockWallet). */
+export function storeUnlocked(entry: UnlockedEntry): void {
+  unlocked = entry
+}
+
+/** Заперт ли кошелёк (нет расшифрованного ключа в памяти). */
+export function isUnlocked(): boolean {
+  return unlocked !== null
+}
+
+/** Публичный «вид» кошелька без приватного ключа. Бросает, если заперто. */
+export function currentView(): { account: string, publicKey: string } {
+  if (!unlocked)
+    throw new AuthV2Error(AuthV2ErrorCode.WalletLocked, 'Кошелёк заперт: сначала вызовите unlockWallet()')
+  return { account: unlocked.account, publicKey: unlocked.publicKey }
+}
+
+/**
+ * Пакет-внутренний доступ к приватному ключу для signing-модулей (2.3/2.4).
+ * НЕ реэкспортируется из index.ts — наружу ключ не выходит.
+ */
+export function readUnlockedKey(): string {
+  if (!unlocked)
+    throw new AuthV2Error(AuthV2ErrorCode.WalletLocked, 'Кошелёк заперт: подпись невозможна без unlockWallet()')
+  return unlocked.privateKey
+}
+
+/** Затирает ключ из памяти (logout / lockWallet). Идемпотентно. */
+export function wipeKeystore(): void {
+  if (unlocked) {
+    // Перезаписываем строку-ключ перед сбросом ссылки, чтобы уменьшить окно жизни
+    // в куче (JS-строки иммутабельны — гарантий нет, но снимаем прямую ссылку).
+    unlocked.privateKey = '\0'.repeat(unlocked.privateKey.length)
+    unlocked = null
+  }
+}

components/auth/test/certificate-renewal.test.ts

@@ -0,0 +1,89 @@
+import { Buffer } from 'node:buffer'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  CERTIFICATE_RENEWAL_LEAD_MS,
+  computeRenewalDelayMs,
+  scheduleCertificateRenewal,
+} from '../src/certificate'
+
+/** Собрать декодируемый compact-JWS с нужными claims (подпись не проверяется при decode). */
+function fakeCert(claims: Record<string, unknown>): string {
+  const header = Buffer.from(JSON.stringify({ alg: 'ES256K', typ: 'JWT' })).toString('base64url')
+  const payload = Buffer.from(JSON.stringify({ jti: 'serial-1', sub: 'uuid-1', ...claims })).toString('base64url')
+  return `${header}.${payload}.sig`
+}
+
+describe('computeRenewalDelayMs', () => {
+  it('обычный кейс: задержка до exp − lead', () => {
+    const nowMs = 1_000_000
+    const exp = Math.floor(nowMs / 1000) + 3600 // +1ч
+    const delay = computeRenewalDelayMs({ exp }, nowMs)
+    expect(delay).toBe(3600 * 1000 - CERTIFICATE_RENEWAL_LEAD_MS)
+  })
+
+  it('до exp осталось ≤ lead → 0 (перезапрос немедленно)', () => {
+    const nowMs = 1_000_000
+    const exp = Math.floor(nowMs / 1000) + 120 // 2 мин < lead (5 мин)
+    expect(computeRenewalDelayMs({ exp }, nowMs)).toBe(0)
+  })
+
+  it('cert уже истёк → 0', () => {
+    const nowMs = 1_000_000
+    const exp = Math.floor(nowMs / 1000) - 10
+    expect(computeRenewalDelayMs({ exp }, nowMs)).toBe(0)
+  })
+})
+
+describe('scheduleCertificateRenewal', () => {
+  it('срабатывает в exp − lead, зовёт renew и перепланирует от нового cert', async () => {
+    let currentNow = 0
+    const timers: Array<{ cb: () => void, delay: number }> = []
+    const setTimer = vi.fn((cb: () => void, delay: number) => {
+      timers.push({ cb, delay })
+      return timers.length as any
+    })
+    const clearTimer = vi.fn()
+
+    const firstExp = 3600 // сек
+    const secondExp = 7200
+    const first = fakeCert({ exp: firstExp })
+    const second = fakeCert({ exp: secondExp })
+    const renew = vi.fn().mockResolvedValue(second)
+
+    scheduleCertificateRenewal(first, renew, { now: () => currentNow, setTimer, clearTimer })
+
+    // первый таймер запланирован на exp − lead
+    expect(setTimer).toHaveBeenCalledTimes(1)
+    expect(timers[0].delay).toBe(firstExp * 1000 - CERTIFICATE_RENEWAL_LEAD_MS)
+
+    // время дошло до срабатывания → дёргаем callback
+    currentNow = firstExp * 1000 - CERTIFICATE_RENEWAL_LEAD_MS
+    timers[0].cb()
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(renew).toHaveBeenCalledTimes(1)
+    // перепланирование от exp нового сертификата
+    expect(setTimer).toHaveBeenCalledTimes(2)
+    expect(timers[1].delay).toBe(secondExp * 1000 - CERTIFICATE_RENEWAL_LEAD_MS - currentNow)
+  })
+
+  it('cancel() отменяет запланированный таймер и не перепланирует', async () => {
+    const timers: Array<{ cb: () => void, delay: number }> = []
+    const setTimer = vi.fn((cb: () => void, delay: number) => {
+      timers.push({ cb, delay })
+      return timers.length as any
+    })
+    const clearTimer = vi.fn()
+    const renew = vi.fn().mockResolvedValue(fakeCert({ exp: 7200 }))
+
+    const handle = scheduleCertificateRenewal(fakeCert({ exp: 3600 }), renew, { now: () => 0, setTimer, clearTimer })
+    handle.cancel()
+    expect(clearTimer).toHaveBeenCalledTimes(1)
+
+    // даже если таймер «выстрелит» после cancel — renew не перепланирует
+    timers[0].cb()
+    await Promise.resolve()
+    expect(setTimer).toHaveBeenCalledTimes(1)
+  })
+})

components/auth/test/certificate.test.ts

@@ -0,0 +1,127 @@
+import { SignJWT } from 'jose'
+import { describe, expect, it } from 'vitest'
+import {
+  CERTIFICATE_EXPIRING_WINDOW_MS,
+  certificateStatus,
+  decodeParticipantCertificate,
+  verificationTypeLabel,
+} from '../src/certificate'
+import { AuthV2Error, AuthV2ErrorCode } from '../src/errors'
+
+async function makeCert(overrides: Record<string, unknown> = {}, opts: { jti?: string, exp?: string } = {}): Promise<string> {
+  let b = new SignJWT({
+    coopname: 'voskhod',
+    coop_chain: [
+      { account: 'ano', public_key: 'PUB_K1_ano' },
+      { account: 'voskhod', public_key: 'PUB_K1_vos' },
+      { account: 'vostok', public_key: 'PUB_K1_vostok' },
+    ],
+    verification_types: [{ type: 'coop_baseline', verified_at: '2026-01-02T03:04:05.000Z', source: 'cooperative_decision' }],
+    identification: { type: 'individual', username: 'ant', first_name: 'Иван' },
+    claim_schema_version: '1',
+    ...overrides,
+  })
+    .setProtectedHeader({ alg: 'HS256' })
+    .setIssuer('https://voskhod.coop')
+    .setSubject('uuid-1')
+    .setIssuedAt()
+    .setExpirationTime(opts.exp ?? '24h')
+  if (opts.jti !== undefined || overrides.jti === undefined)
+    b = b.setJti(opts.jti ?? 'serial-123')
+  return b.sign(new TextEncoder().encode('test-secret-padding-000000000000000000'))
+}
+
+describe('decodeParticipantCertificate', () => {
+  it('декодирует все claims в типизированный объект', async () => {
+    const claims = decodeParticipantCertificate(await makeCert())
+    expect(claims.sub).toBe('uuid-1')
+    expect(claims.jti).toBe('serial-123')
+    expect(claims.coopname).toBe('voskhod')
+    expect(claims.claim_schema_version).toBe('1')
+    expect(claims.verification_types).toEqual([
+      { type: 'coop_baseline', verified_at: '2026-01-02T03:04:05.000Z', source: 'cooperative_decision' },
+    ])
+    expect(claims.coop_chain.map(l => l.account)).toEqual(['ano', 'voskhod', 'vostok'])
+    expect(claims.identification).toMatchObject({ type: 'individual', username: 'ant' })
+    expect(claims.exp).toBeGreaterThan(claims.iat)
+  })
+
+  it('identification может быть null', async () => {
+    const claims = decodeParticipantCertificate(await makeCert({ identification: null }))
+    expect(claims.identification).toBeNull()
+  })
+
+  it('retention-claims читаются (Story 4.8)', async () => {
+    const claims = decodeParticipantCertificate(await makeCert({
+      data_retention_contract: 'erase_on_exclusion',
+      retention_deadline_ts: 1800000000,
+    }))
+    expect(claims.data_retention_contract).toBe('erase_on_exclusion')
+    expect(claims.retention_deadline_ts).toBe(1800000000)
+  })
+
+  it('retention-claims отсутствуют → безопасные дефолты (Story 4.8)', async () => {
+    const claims = decodeParticipantCertificate(await makeCert())
+    expect(claims.data_retention_contract).toBe('')
+    expect(claims.retention_deadline_ts).toBe(0)
+  })
+
+  it('verification_types: структурные записи сохраняются, мусор отбрасывается (Story 4.3)', async () => {
+    const claims = decodeParticipantCertificate(await makeCert({
+      verification_types: [
+        { type: 'coop_baseline', verified_at: '2026-01-02T03:04:05.000Z', source: 'cooperative_decision' },
+        'legacy_string',
+        { source: 'no_type' },
+      ],
+    }))
+    expect(claims.verification_types).toEqual([
+      { type: 'coop_baseline', verified_at: '2026-01-02T03:04:05.000Z', source: 'cooperative_decision' },
+    ])
+  })
+
+  it('не-JWT строка → AuthV2Error(chain_verification_failed)', () => {
+    let err: unknown
+    try {
+      decodeParticipantCertificate('garbage')
+    }
+    catch (e) {
+      err = e
+    }
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.ChainVerificationFailed)
+  })
+
+  it('без обязательных claims (нет jti) → AuthV2Error', async () => {
+    // токен без jti
+    const noJti = await new SignJWT({ coopname: 'voskhod' })
+      .setProtectedHeader({ alg: 'HS256' })
+      .setSubject('uuid-1')
+      .setExpirationTime('24h')
+      .sign(new TextEncoder().encode('test-secret-padding-000000000000000000'))
+    expect(() => decodeParticipantCertificate(noJti)).toThrow(AuthV2Error)
+  })
+})
+
+describe('certificateStatus', () => {
+  const now = 1_900_000_000_000 // фиксированный «сейчас» (мс)
+  it('exp в прошлом → expired', () => {
+    expect(certificateStatus({ exp: now / 1000 - 10 }, now)).toBe('expired')
+  })
+  it('exp в окне «истекает» → expiring', () => {
+    const exp = (now + CERTIFICATE_EXPIRING_WINDOW_MS - 1000) / 1000
+    expect(certificateStatus({ exp }, now)).toBe('expiring')
+  })
+  it('exp далеко → active', () => {
+    const exp = (now + CERTIFICATE_EXPIRING_WINDOW_MS + 10 * 60 * 1000) / 1000
+    expect(certificateStatus({ exp }, now)).toBe('active')
+  })
+})
+
+describe('verificationTypeLabel', () => {
+  it('известный тип → человекочитаемое описание', () => {
+    expect(verificationTypeLabel('coop_baseline')).toBe('Базовое подтверждение кооперативом')
+  })
+  it('неизвестный тип → возвращается как есть', () => {
+    expect(verificationTypeLabel('future_kyc_x')).toBe('future_kyc_x')
+  })
+})

components/auth/test/chain.int.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Интеграционный тест Story 1.3: SDK читает publickey permission `cert` из COOPOS.
+ * Требует живую дев-ноду: COOPID_TEST_RPC=http://127.0.0.1:8908 pnpm test
+ * Без env — скипается (юнит-прогоны CI не зависят от цепи).
+ */
+import { describe, expect, it } from 'vitest'
+import { AuthV2Error, AuthV2ErrorCode } from '../src/errors'
+import { readCertPublicKey } from '../src/index'
+
+const RPC = process.env.COOPID_TEST_RPC
+
+describe.skipIf(!RPC)('readCertPublicKey — против дев-сети COOPOS', () => {
+  it.each(['vostok', 'voskhod', 'ano'])('читает ключ cert у %s', async (account) => {
+    const key = await readCertPublicKey(RPC!, account)
+    expect(key).toMatch(/^(PUB_K1_|EOS)/)
+  })
+
+  it('аккаунт без cert → ChainVerificationFailed', async () => {
+    const err = await readCertPublicKey(RPC!, 'eosio').then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.ChainVerificationFailed)
+  })
+
+  it('несуществующий аккаунт → NetworkError', async () => {
+    const err = await readCertPublicKey(RPC!, 'nonexistacct').then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.NetworkError)
+  })
+})

components/auth/test/cross-runtime/electron-main.cjs

@@ -0,0 +1,71 @@
+/**
+ * Electron-таргет cross-runtime smoke (Story 9.13): те же проверки, что в
+ * smoke.test.ts, но против СОБРАННОГО артефакта (dist/index.cjs — то, что
+ * реально получают клиенты) в main-process electron. Запуск — через
+ * run-electron.mjs (`pnpm test:electron`), не напрямую.
+ *
+ * Без vitest: минимальный assert + exit-код, чтобы не тащить тест-раннер в
+ * electron. Сценарии держать синхронными со smoke.test.ts.
+ */
+const { app } = require('electron')
+
+const KEY = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'
+const PW = 'correct-horse-battery-staple-12'
+const ACCOUNT = 'ant'
+
+function assert(cond, name) {
+  if (!cond)
+    throw new Error(`smoke-проверка провалена: ${name}`)
+  console.log(`[electron-smoke] OK ${name}`)
+}
+
+async function run() {
+  const sdk = require('../../dist/index.cjs')
+
+  // vault round-trip + unlockWallet (WebCrypto AES-GCM + Argon2id в main-process)
+  const blob = await sdk.encryptPrivateKey(KEY, PW, { subject_type: 'participant', subject_id: ACCOUNT })
+  globalThis.fetch = async () =>
+    new Response(JSON.stringify(blob), { status: 200, headers: { 'content-type': 'application/json' } })
+  const wallet = await sdk.unlockWallet({ apiUrl: 'https://coop.stub', account: ACCOUNT, password: PW })
+  assert(wallet.account === ACCOUNT && wallet.publicKey.startsWith('PUB_K1_'), 'vault round-trip + unlockWallet')
+  assert(sdk.isWalletUnlocked() === true, 'isWalletUnlocked после unlock')
+
+  // signDocument → verifyDocumentOffline
+  const jws = await sdk.signDocument({ payload: 'кросс-рантайм smoke-документ' })
+  assert(jws.split('.').length === 3, 'signDocument: compact JWS')
+  const verdict = await sdk.verifyDocumentOffline({
+    jws,
+    signedAtBlock: 100,
+    authority: [{ public_key: wallet.publicKey, valid_from_block: 1, valid_to_block: null }],
+  })
+  assert(verdict.valid === true, 'verifyDocumentOffline подтверждает подпись')
+
+  // запертый кошелёк → типизированная WalletLocked
+  sdk.lockWallet()
+  const lockedErr = await sdk.signDocument({ payload: 'x' }).then(() => null, e => e)
+  assert(lockedErr instanceof sdk.AuthV2Error && lockedErr.code === sdk.AuthV2ErrorCode.WalletLocked, 'WalletLocked при запертом кошельке')
+
+  // login/getAccessToken реализованы (вход 1.7 + flow-executor Story 11.2): в stub-окружении
+  // без живого authentik/controller дают типизированную AuthV2Error (login→network_error,
+  // getAccessToken→wallet_locked). Конкретный код не пиннингуем — важно, что ошибка
+  // типизированная и код валиден для enum'а. Синхронно со smoke.test.ts.
+  const errorCodes = Object.values(sdk.AuthV2ErrorCode)
+  for (const [name, call] of [
+    ['login', () => sdk.login({ issuer: 'https://coop.stub/application/o/coopid/', email: 'a@b.c', password: 'p' })],
+    ['getAccessToken', () => sdk.getAccessToken()],
+  ]) {
+    const err = await call().then(() => null, e => e)
+    assert(err instanceof sdk.AuthV2Error && errorCodes.includes(err.code), `${name}: типизированная AuthV2Error`)
+  }
+}
+
+app.whenReady().then(run).then(
+  () => {
+    console.log('[electron-smoke] все проверки пройдены')
+    app.exit(0)
+  },
+  (e) => {
+    console.error('[electron-smoke] FAIL:', e)
+    app.exit(1)
+  },
+)

components/auth/test/cross-runtime/run-electron.mjs

@@ -0,0 +1,35 @@
+/**
+ * Лаунчер electron-таргета (Story 9.13): резолвит бинарь electron, проверяет
+ * наличие dist (smoke идёт против собранного артефакта), на безголовом хосте
+ * заворачивает запуск в `xvfb-run -a` (electron на Linux требует X-сервер).
+ * `--no-sandbox` — для контейнерных/CI-окружений без user namespaces.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import electronPath from 'electron'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const pkgRoot = join(here, '..', '..')
+
+if (!existsSync(join(pkgRoot, 'dist', 'index.cjs'))) {
+  console.error('[electron-smoke] dist/index.cjs не найден — сначала `pnpm build` (test:cross-runtime делает это сам)')
+  process.exit(1)
+}
+
+const electronArgs = ['--no-sandbox', join(here, 'electron-main.cjs')]
+const needXvfb = process.platform === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY
+
+const [cmd, args] = needXvfb
+  ? ['xvfb-run', ['-a', electronPath, ...electronArgs]]
+  : [electronPath, electronArgs]
+
+const res = spawnSync(cmd, args, { stdio: 'inherit', cwd: pkgRoot })
+
+if (res.error) {
+  console.error(`[electron-smoke] не удалось запустить ${cmd}: ${res.error.message}`)
+  process.exit(1)
+}
+process.exit(res.status ?? 1)

components/auth/test/cross-runtime/smoke.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Cross-runtime smoke (Story 9.13): один и тот же сценарий гоняется в Node
+ * (`pnpm test:node`) и в браузере (`pnpm test:browser`, chromium headless);
+ * electron-таргет (`pnpm test:electron`) выполняет те же проверки против
+ * собранного dist (см. electron-main.cjs).
+ *
+ * Правила файла:
+ * - только ПУБЛИЧНЫЙ API пакета (как у клиентов) и никаких Node-специфичных
+ *   глобалов (Buffer, process, fs) — иначе браузерный таргет перестаёт быть
+ *   честным; сеть стабится через globalThis.fetch;
+ * - дорогой Argon2id (KDF vault'а) выполняется ОДИН раз в beforeAll: в
+ *   chromium pure-JS KDF в разы медленнее Node (минуты), per-test KDF
+ *   упирается в таймауты. Тесты зависят от порядка: lockWallet — последний.
+ */
+import type { Wallet } from '../../src'
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
+import {
+  AuthV2Error,
+  AuthV2ErrorCode,
+  encryptPrivateKey,
+  getAccessToken,
+  isWalletUnlocked,
+  lockWallet,
+  login,
+  signDocument,
+  unlockWallet,
+  verifyDocumentOffline,
+} from '../../src'
+
+const KEY = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'
+const PW = 'correct-horse-battery-staple-12'
+const ACCOUNT = 'ant'
+
+describe('cross-runtime smoke: vault → wallet → подпись → верификация', () => {
+  let wallet: Wallet
+
+  beforeAll(async () => {
+    // Стаб контроллера: GET /coop/vault/... отдаёт заранее зашифрованный blob.
+    const blob = await encryptPrivateKey(KEY, PW, { subject_type: 'participant', subject_id: ACCOUNT })
+    vi.stubGlobal('fetch', async () =>
+      new Response(JSON.stringify(blob), { status: 200, headers: { 'content-type': 'application/json' } }))
+    wallet = await unlockWallet({ apiUrl: 'https://coop.stub', account: ACCOUNT, password: PW })
+    // 10 мин: два прогона Argon2id (encrypt + unlock) — в браузере это минуты
+  }, 600_000)
+
+  afterAll(() => {
+    lockWallet()
+    vi.unstubAllGlobals()
+  })
+
+  it('vault round-trip + unlockWallet: WebCrypto AES-GCM и Argon2id работают в этом рантайме', () => {
+    expect(wallet.account).toBe(ACCOUNT)
+    expect(wallet.publicKey).toMatch(/^PUB_K1_/)
+    expect(isWalletUnlocked()).toBe(true)
+  })
+
+  it('signDocument → compact JWS, verifyDocumentOffline подтверждает подпись', async () => {
+    const jws = await signDocument({ payload: 'кросс-рантайм smoke-документ' })
+    expect(jws.split('.')).toHaveLength(3)
+
+    const verdict = await verifyDocumentOffline({
+      jws,
+      signedAtBlock: 100,
+      authority: [{ public_key: wallet.publicKey, valid_from_block: 1, valid_to_block: null }],
+    })
+    expect(verdict.valid).toBe(true)
+  })
+
+  // SDK-сторона login/getAccessToken реализована (вход 1.7 + flow-executor Story 11.2).
+  // Smoke фиксирует кросс-рантайм: модуль грузится, функции вызываемы, канал
+  // типизированных ошибок работает в каждом рантайме. В stub-окружении без живого
+  // authentik/controller: login → AuthV2Error(network_error) (flow-executor не достучался),
+  // getAccessToken → AuthV2Error(wallet_locked) (нет активной сессии). Конкретный код
+  // не пиннингуем жёстко — важно, что ошибка типизированная (AuthV2Error) в любом рантайме.
+  it('login()/getAccessToken(): вызываемы и дают типизированную AuthV2Error в каждом рантайме', async () => {
+    for (const call of [
+      () => login({ issuer: 'https://coop.stub/application/o/coopid/', email: 'a@b.c', password: 'p' }),
+      () => getAccessToken(),
+    ]) {
+      const err = await call().then(() => null, e => e)
+      expect(err).toBeInstanceOf(AuthV2Error)
+      // код — валидное значение enum'а (канал типизированных ошибок целостен)
+      expect(Object.values(AuthV2ErrorCode)).toContain((err as AuthV2Error).code)
+    }
+  })
+
+  // Последний по порядку: запирает общий кошелёк из beforeAll
+  it('запертый кошелёк: signDocument даёт типизированную WalletLocked, не runtime-краш', async () => {
+    lockWallet()
+    const err = await signDocument({ payload: 'x' }).then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.WalletLocked)
+  })
+})

components/auth/test/errors.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+import { AUTH_V2_ERROR_VIEWS, AuthV2Error, AuthV2ErrorCode, describeAuthV2Error } from '../src/index'
+
+describe('describeAuthV2Error (Story 1.11)', () => {
+  it('каталог покрывает каждый код ошибки', () => {
+    for (const code of Object.values(AuthV2ErrorCode))
+      expect(AUTH_V2_ERROR_VIEWS[code], code).toBeDefined()
+  })
+
+  it('по AC: неверные учётные данные — общее сообщение без раскрытия поля', () => {
+    const view = describeAuthV2Error(new AuthV2Error(AuthV2ErrorCode.InvalidCredentials, 'whatever'))
+    expect(view.code).toBe(AuthV2ErrorCode.InvalidCredentials)
+    expect(view.message).toBe('Неверный email или пароль.')
+    // перечисляет оба поля через «или» — не раскрывает, какое именно неверно (security)
+    expect(view.message).toMatch(/email или пароль/i)
+    expect(view.message).not.toMatch(/не найден|не существует|нет такого|такой email/i)
+    expect(view.keepSession).toBe(false)
+  })
+
+  it('по AC: vault не расшифровывается — предлагает восстановление доступа', () => {
+    const view = describeAuthV2Error(new AuthV2Error(AuthV2ErrorCode.VaultDecryptionFailed, 'bad key'))
+    expect(view.action).toBe('recover')
+    expect(view.message).toMatch(/восстановить доступ/i)
+  })
+
+  it('по AC: сетевая ошибка — «проверьте интернет» и НЕ разлогинивает (NFR20/FR50)', () => {
+    const view = describeAuthV2Error(new AuthV2Error(AuthV2ErrorCode.NetworkError, 'fetch failed'))
+    expect(view.action).toBe('check_connection')
+    expect(view.message).toMatch(/проверьте интернет/i)
+    expect(view.keepSession).toBe(true)
+  })
+
+  it('внешний сбой (кооператив недоступен) — сессия сохраняется', () => {
+    expect(describeAuthV2Error(new AuthV2Error(AuthV2ErrorCode.CooposDegraded, 'down')).keepSession).toBe(true)
+  })
+
+  it('неожиданная (не-AuthV2) ошибка — безопасный фолбэк без утечки technical message', () => {
+    const view = describeAuthV2Error(new Error('TypeError: cannot read property x of undefined'))
+    expect(view.code).toBeNull()
+    expect(view.message).not.toMatch(/TypeError|undefined/)
+    expect(view.keepSession).toBe(true)
+  })
+
+  it('сообщение берётся из каталога, а не из e.message сервера', () => {
+    const view = describeAuthV2Error(new AuthV2Error(AuthV2ErrorCode.TimestampTooOld, 'raw server text'))
+    expect(view.message).not.toBe('raw server text')
+    expect(view.message).toBe(AUTH_V2_ERROR_VIEWS[AuthV2ErrorCode.TimestampTooOld].message)
+  })
+})

components/auth/test/export.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { AuthV2Error, AuthV2ErrorCode } from '../src/errors'
+import { exportFullQR } from '../src/export'
+import { lockWallet } from '../src/wallet'
+import { storeUnlocked } from '../src/wallet/storage'
+
+const CERT = 'header.payload.sig'
+
+afterEach(() => lockWallet())
+
+function unlock(): void {
+  storeUnlocked({ account: 'ant', publicKey: 'PUB_K1_ant', privateKey: '5KdummyWIF' })
+}
+
+describe('exportFullQR (Story 4.9)', () => {
+  it('заперт vault → WalletLocked, consent даже не запрашивается', async () => {
+    lockWallet()
+    const confirm = vi.fn().mockResolvedValue(true)
+    await expect(exportFullQR(CERT, { confirm })).rejects.toMatchObject({ code: AuthV2ErrorCode.WalletLocked })
+    expect(confirm).not.toHaveBeenCalled()
+  })
+
+  it('consent отклонён → ConsentRequired', async () => {
+    unlock()
+    await expect(exportFullQR(CERT, { confirm: async () => false })).rejects.toMatchObject({ code: AuthV2ErrorCode.ConsentRequired })
+  })
+
+  it('reject в confirm трактуется как отказ → ConsentRequired', async () => {
+    unlock()
+    const confirm = async (): Promise<boolean> => {
+      throw new Error('dialog closed')
+    }
+    await expect(exportFullQR(CERT, { confirm })).rejects.toMatchObject({ code: AuthV2ErrorCode.ConsentRequired })
+  })
+
+  it('разблокирован + consent дан → payload-байты с данными сертификата', async () => {
+    unlock()
+    const bytes = await exportFullQR(CERT, { confirm: async () => true })
+    expect(bytes).toBeInstanceOf(Uint8Array)
+    expect(new TextDecoder().decode(bytes)).toBe(CERT)
+  })
+
+  it('ошибки — типизированная AuthV2Error', async () => {
+    lockWallet()
+    const err = await exportFullQR(CERT, { confirm: async () => true }).catch(e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+  })
+})

components/auth/test/index.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+import * as api from '../src/index'
+import { AuthV2Error, AuthV2ErrorCode } from '../src/index'
+
+const PUBLIC_API = [
+  'login',
+  'loginWithMagicLink',
+  'recover',
+  'getAccessToken',
+  'getParticipantCertificate',
+  'logout',
+  'verifyOffline',
+  'signDocument',
+  'signTimestamp',
+  'getWallet',
+  'rotateKey',
+  'exportFullQR',
+] as const
+
+// Методы, ещё не реализованные (бросают not_implemented). По мере реализации
+// историй метод уходит отсюда: getWallet — 2.2, signTimestamp — 2.4, verifyOffline — 4.4,
+// exportFullQR — 4.9 (гейтится unlocked vault + consent, не not_implemented), login —
+// 1.7/11.2 (flow-executor → network_error без живого authentik), recover — Эпик 3,
+// getAccessToken — 1.7 (wallet_locked без сессии), loginWithMagicLink — 12.2 (confirm-флоу
+// + повторный handshake). Реальный stub остался один: rotateKey (3.3).
+const IMPLEMENTED = new Set(['getWallet', 'signTimestamp', 'getParticipantCertificate', 'logout', 'signDocument', 'verifyOffline', 'exportFullQR', 'login', 'recover', 'getAccessToken', 'loginWithMagicLink'])
+const STILL_STUBBED = PUBLIC_API.filter(m => !IMPLEMENTED.has(m))
+
+describe('@coopenomics/auth — скелет SDK', () => {
+  it('экспортирует всю публичную поверхность', () => {
+    for (const method of PUBLIC_API)
+      expect(api[method], method).toBeTypeOf('function')
+  })
+
+  it('stub\'ы отказывают типизированной AuthV2Error(not_implemented), а не молчат', async () => {
+    for (const method of STILL_STUBBED) {
+      const err = await (api[method] as () => Promise<unknown>)().then(
+        () => null,
+        e => e,
+      )
+      expect(err, method).toBeInstanceOf(AuthV2Error)
+      expect((err as AuthV2Error).code, method).toBe(AuthV2ErrorCode.NotImplemented)
+    }
+  })
+
+  it('ошибка сериализуется в формат OAuth 2.0', () => {
+    const err = new AuthV2Error(AuthV2ErrorCode.InvalidCredentials, 'Неверный email или пароль')
+    expect(err.toJSON()).toEqual({
+      error: 'invalid_credentials',
+      error_description: 'Неверный email или пароль',
+    })
+  })
+
+  it('exportProofQR НЕ экспортируется в MVP (anonymous-форма — Growth, Story 4.9)', () => {
+    expect((api as Record<string, unknown>).exportProofQR).toBeUndefined()
+  })
+
+  it('trust anchor и список нод доступны (placeholder до release-pin/9.5)', () => {
+    expect(api.TRUST_ANCHOR_ANO_CERT_PUBKEY).toBeNull()
+    expect(api.COOPOS_PUBLIC_NODES).toEqual([])
+  })
+})

components/auth/test/logout.test.ts

@@ -0,0 +1,43 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const lockWallet = vi.fn()
+
+// keystore-затирание мокаем на уровне модуля wallet — logout обязан вызвать его
+// независимо от исхода сетевого запроса.
+vi.mock('../src/wallet', () => ({
+  lockWallet,
+}))
+
+const { logout } = await import('../src/oidc')
+
+describe('logout (Story 1.10)', () => {
+  beforeEach(() => {
+    lockWallet.mockClear()
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('шлёт POST /coop/logout с refresh/access и затирает keystore', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await logout({ apiUrl: 'https://coop.example/', refreshToken: 'r1', accessToken: 'a1' })
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [url, opts] = fetchMock.mock.calls[0]
+    expect(url).toBe('https://coop.example/coop/logout')
+    expect(opts.method).toBe('POST')
+    expect(JSON.parse(opts.body)).toEqual({ refresh_token: 'r1', access_token: 'a1' })
+    expect(lockWallet).toHaveBeenCalledTimes(1)
+  })
+
+  it('затирает keystore ДАЖЕ при недоступности сервера (finally)', async () => {
+    const fetchMock = vi.fn().mockRejectedValue(new Error('network down'))
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(logout({ apiUrl: 'https://coop.example', refreshToken: 'r1' })).resolves.toBeUndefined()
+    expect(lockWallet).toHaveBeenCalledTimes(1)
+  })
+})

components/auth/test/migration.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { canonicalMigrationMessage, migrate } from '../src/migration'
+import { configureCoopId } from '../src/oidc/client'
+
+const WIF = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'
+
+beforeEach(() => configureCoopId({ apiUrl: 'https://coop.example' }))
+afterEach(() => vi.unstubAllGlobals())
+
+describe('canonicalMigrationMessage (Story 11.4)', () => {
+  it('фиксированный алфавитный порядок ключей: pw_hash, purpose, ts', () => {
+    expect(canonicalMigrationMessage({ ts: 'T', pw_hash: 'H' }))
+      .toBe('{"pw_hash":"H","purpose":"coopid-key-migration","ts":"T"}')
+  })
+})
+
+describe('migrate (Story 11.4) — «ключ → пароль»', () => {
+  it('невалидный WIF → InvalidCredentials, без сетевого запроса', async () => {
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+    await expect(migrate({ email: 'a@e.com', privateKey: 'not-a-key', newPassword: 'Strong#Pass1' }))
+      .rejects
+      .toMatchObject({ code: 'invalid_credentials' })
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('ошибка сервера (400 weak_password) пробрасывается; vault не сохраняется', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 400,
+      json: async () => ({ error: 'weak_password', error_description: 'Пароль слишком короткий' }),
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    await expect(migrate({ email: 'a@e.com', privateKey: WIF, newPassword: 'weakweak' }))
+      .rejects
+      .toMatchObject({ code: 'weak_password' })
+    // только POST /coop/migration, без POST /coop/vault
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(fetchMock.mock.calls[0][0]).toBe('https://coop.example/coop/migration')
+  })
+
+  it('happy path: POST /coop/migration → username, затем saveToVault (POST /coop/vault)', async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => ({ username: 'ant' }) }) // migration
+      .mockResolvedValueOnce({ ok: true, status: 201, json: async () => ({}) }) // vault store
+    vi.stubGlobal('fetch', fetchMock)
+
+    const result = await migrate({ email: 'a@e.com', privateKey: WIF, newPassword: 'Strong#Pass1' })
+
+    expect(result).toEqual({ username: 'ant' })
+    // 1) запрос миграции
+    expect(fetchMock.mock.calls[0][0]).toBe('https://coop.example/coop/migration')
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body)
+    expect(body.email).toBe('a@e.com')
+    expect(body.new_password).toBe('Strong#Pass1')
+    expect(typeof body.timestamp).toBe('string')
+    expect(body.signature).toMatch(/^SIG_/)
+    // 2) сохранение vault новым паролём (subject = возвращённый username)
+    expect(fetchMock.mock.calls[1][0]).toBe('https://coop.example/coop/vault')
+    expect(JSON.parse(fetchMock.mock.calls[1][1].body)).toMatchObject({ subject_type: 'participant', subject_id: 'ant' })
+  }, 60000)
+})

components/auth/test/oidc-flow-executor.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { authenticateWithFlowExecutor } from '../src/oidc/flow-executor'
+
+const ISSUER = 'https://coop.example/application/o/coopid/'
+const FLOW_URL = 'https://coop.example/api/v3/flows/executor/default-authentication-flow/?query='
+
+afterEach(() => vi.unstubAllGlobals())
+
+/** Ответ flow-executor: 200 + тело challenge'а. */
+function challenge(body: unknown, status = 200) {
+  return { ok: status < 400, status, json: async () => body }
+}
+
+describe('authenticateWithFlowExecutor (Story 11.2) — встроенный фактор-1 authentik', () => {
+  it('раздельные стадии identification → password → redirect: успех, верные URL/тела/credentials', async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(challenge({ component: 'ak-stage-identification' })) // GET
+      .mockResolvedValueOnce(challenge({ component: 'ak-stage-password' })) // POST email
+      .mockResolvedValueOnce(challenge({ type: 'redirect' })) // POST password → завершение
+    vi.stubGlobal('fetch', fetchMock)
+
+    await authenticateWithFlowExecutor({ issuer: ISSUER, email: 'user@e.com', password: 'S3cret!' })
+
+    // GET старта flow
+    expect(fetchMock.mock.calls[0][0]).toBe(FLOW_URL)
+    expect(fetchMock.mock.calls[0][1].method).toBe('GET')
+    expect(fetchMock.mock.calls[0][1].credentials).toBe('include')
+    // POST identification — uid_field + password (совмещённая форма безопасна и для раздельной)
+    expect(fetchMock.mock.calls[1][1].method).toBe('POST')
+    expect(JSON.parse(fetchMock.mock.calls[1][1].body)).toEqual({ uid_field: 'user@e.com', password: 'S3cret!' })
+    // POST password
+    expect(JSON.parse(fetchMock.mock.calls[2][1].body)).toEqual({ password: 'S3cret!' })
+    expect(fetchMock.mock.calls[2][1].credentials).toBe('include')
+  })
+
+  it('совмещённая identification сразу завершает flow (redirect)', async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(challenge({ component: 'ak-stage-identification' }))
+      .mockResolvedValueOnce(challenge({ type: 'redirect' }))
+    vi.stubGlobal('fetch', fetchMock)
+    await authenticateWithFlowExecutor({ issuer: ISSUER, email: 'u@e.com', password: 'p' })
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('завершение по стадии ak-stage-user-login (сессия установлена)', async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(challenge({ component: 'ak-stage-password' }))
+      .mockResolvedValueOnce(challenge({ component: 'ak-stage-user-login' }))
+    vi.stubGlobal('fetch', fetchMock)
+    await expect(authenticateWithFlowExecutor({ issuer: ISSUER, email: 'u@e.com', password: 'p' })).resolves.toBeUndefined()
+  })
+
+  it('неверный пароль (response_errors, HTTP 400) → InvalidCredentials с сообщением authentik', async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(challenge({ component: 'ak-stage-password' }))
+      .mockResolvedValueOnce(challenge({ component: 'ak-stage-password', response_errors: { password: [{ string: 'Неверный пароль', code: 'invalid' }] } }, 400))
+    vi.stubGlobal('fetch', fetchMock)
+    await expect(authenticateWithFlowExecutor({ issuer: ISSUER, email: 'u@e.com', password: 'bad' }))
+      .rejects
+      .toMatchObject({ code: 'invalid_credentials', message: 'Неверный пароль' })
+  })
+
+  it('ak-stage-access-denied → InvalidCredentials', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValueOnce(challenge({ component: 'ak-stage-access-denied' })))
+    await expect(authenticateWithFlowExecutor({ issuer: ISSUER, email: 'u@e.com', password: 'p' }))
+      .rejects
+      .toMatchObject({ code: 'invalid_credentials' })
+  })
+
+  it('неподдерживаемая интерактивная стадия (MFA) → InvalidCredentials с её именем', async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(challenge({ component: 'ak-stage-password' }))
+      .mockResolvedValueOnce(challenge({ component: 'ak-stage-authenticator-validate' }))
+    vi.stubGlobal('fetch', fetchMock)
+    await expect(authenticateWithFlowExecutor({ issuer: ISSUER, email: 'u@e.com', password: 'p' }))
+      .rejects
+      .toMatchObject({ code: 'invalid_credentials', message: expect.stringContaining('ak-stage-authenticator-validate') })
+  })
+
+  it('сеть упала на старте → NetworkError', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('down')))
+    await expect(authenticateWithFlowExecutor({ issuer: ISSUER, email: 'u@e.com', password: 'p' }))
+      .rejects
+      .toMatchObject({ code: 'network_error' })
+  })
+
+  it('эхо CSRF-cookie уходит в заголовке X-authentik-CSRF (same-origin)', async () => {
+    vi.stubGlobal('document', { cookie: 'foo=1; authentik_csrf=tok123; bar=2' })
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(challenge({ component: 'ak-stage-password' }))
+      .mockResolvedValueOnce(challenge({ type: 'redirect' }))
+    vi.stubGlobal('fetch', fetchMock)
+    await authenticateWithFlowExecutor({ issuer: ISSUER, email: 'u@e.com', password: 'p' })
+    expect(fetchMock.mock.calls[0][1].headers['X-authentik-CSRF']).toBe('tok123')
+    expect(fetchMock.mock.calls[1][1].headers['X-authentik-CSRF']).toBe('tok123')
+  })
+})

components/auth/test/oidc-handshake.test.ts

@@ -0,0 +1,94 @@
+import { PrivateKey } from '@wharfkit/antelope'
+import { SignJWT } from 'jose'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { AuthV2Error } from '../src/errors'
+import { performTimestampHandshake } from '../src/oidc/handshake'
+import { clearSession, currentTokens } from '../src/oidc/tokens'
+import { storeUnlocked, wipeKeystore } from '../src/wallet/storage'
+
+const KEY = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'
+const PUB = PrivateKey.from(KEY).toPublic().toString()
+const ACCOUNT = 'ant'
+
+async function bindingTokenFor(sub: string, jti = 'jti-1'): Promise<string> {
+  return new SignJWT({ stage_completed: 'password' })
+    .setProtectedHeader({ alg: 'HS256' })
+    .setSubject(sub)
+    .setJti(jti)
+    .setIssuedAt()
+    .setExpirationTime('120s')
+    .sign(new TextEncoder().encode('test-binding-secret'))
+}
+
+function okJson(body: unknown) {
+  return { ok: true, status: 200, json: async () => body }
+}
+
+beforeEach(() => {
+  clearSession()
+  storeUnlocked({ account: ACCOUNT, publicKey: PUB, privateKey: KEY })
+})
+
+afterEach(() => {
+  wipeKeystore()
+  vi.unstubAllGlobals()
+})
+
+describe('performTimestampHandshake (Story 1.7) — handshake внутрь SDK', () => {
+  it('bind → sign → verify: токены/сертификат + сессия сохранена; credentials:include на обоих', async () => {
+    const binding = await bindingTokenFor(ACCOUNT)
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(okJson({ binding_token: binding, expires_in: 120 }))
+      .mockResolvedValueOnce(okJson({ access_token: 'acc', refresh_token: 'ref', participant_certificate: 'cert', degraded: false }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const r = await performTimestampHandshake('https://coop.example/')
+
+    expect(r).toMatchObject({ accessToken: 'acc', refreshToken: 'ref', participantCertificate: 'cert', degraded: false })
+    expect(fetchMock.mock.calls[0][0]).toBe('https://coop.example/coop/session/bind')
+    expect(fetchMock.mock.calls[0][1].credentials).toBe('include')
+    expect(fetchMock.mock.calls[1][0]).toBe('https://coop.example/coop/verify/timestamp')
+    expect(fetchMock.mock.calls[1][1].credentials).toBe('include')
+    const verifyBody = JSON.parse(fetchMock.mock.calls[1][1].body)
+    expect(verifyBody.binding_token).toBe(binding)
+    expect(typeof verifyBody.signature).toBe('string')
+    expect(typeof verifyBody.timestamp).toBe('string')
+    expect(currentTokens()).toEqual({ accessToken: 'acc', refreshToken: 'ref' })
+  })
+
+  it('degraded-вход (узел недоступен/ключ не финализирован) прокидывается', async () => {
+    const binding = await bindingTokenFor(ACCOUNT)
+    vi.stubGlobal('fetch', vi.fn()
+      .mockResolvedValueOnce(okJson({ binding_token: binding, expires_in: 120 }))
+      .mockResolvedValueOnce(okJson({ access_token: 'a', refresh_token: 'r', degraded: true, degraded_reason: 'rpc_unavailable' })))
+
+    const r = await performTimestampHandshake('https://coop.example')
+    expect(r.degraded).toBe(true)
+    expect(r.degradedReason).toBe('rpc_unavailable')
+  })
+
+  it('bind 401 → InvalidCredentials (сессия authentik не подтверждена), сессия не сохраняется', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValueOnce({ ok: false, status: 401, json: async () => ({}) }))
+    await expect(performTimestampHandshake('https://coop.example')).rejects.toBeInstanceOf(AuthV2Error)
+    expect(currentTokens()).toBeNull()
+  })
+
+  it('verify !ok → AuthV2Error с кодом из тела (OAuth2 error)', async () => {
+    const binding = await bindingTokenFor(ACCOUNT)
+    vi.stubGlobal('fetch', vi.fn()
+      .mockResolvedValueOnce(okJson({ binding_token: binding, expires_in: 120 }))
+      .mockResolvedValueOnce({ ok: false, status: 401, json: async () => ({ error: 'chain_verification_failed', error_description: 'Подпись не соответствует ключу' }) }))
+
+    await expect(performTimestampHandshake('https://coop.example')).rejects.toMatchObject({ code: 'chain_verification_failed' })
+  })
+
+  it('кошелёк заперт → WalletLocked (подпись невозможна, verify не вызывается)', async () => {
+    wipeKeystore()
+    const binding = await bindingTokenFor(ACCOUNT)
+    const fetchMock = vi.fn().mockResolvedValueOnce(okJson({ binding_token: binding, expires_in: 120 }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(performTimestampHandshake('https://coop.example')).rejects.toMatchObject({ code: 'wallet_locked' })
+    expect(fetchMock).toHaveBeenCalledTimes(1) // только bind, до verify не дошли
+  })
+})

components/auth/test/oidc-login-magic-link.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Граница повторного входа (authentik-сессия + on-chain timestamp-handshake) — сетевые
+// интеграции; мокаем их, чтобы юнит-тест проверял детерминированный confirm-флоу:
+// генерацию пары, AAD vault'а, тело запроса confirm и маппинг ошибок. Крипто vault'а
+// и antelope здесь настоящие — round-trip ключа проверяется по-настоящему.
+vi.mock('../src/oidc/client', async importActual => ({
+  ...(await importActual<typeof import('../src/oidc/client')>()),
+  authenticateWithAuthentik: vi.fn().mockResolvedValue({ id_token: 'ID_TOK' }),
+}))
+vi.mock('../src/oidc/handshake', async importActual => ({
+  ...(await importActual<typeof import('../src/oidc/handshake')>()),
+  performTimestampHandshake: vi.fn().mockResolvedValue({ accessToken: 'AT', refreshToken: 'RT', participantCertificate: 'CERT', degraded: false }),
+}))
+vi.mock('../src/wallet', async importActual => ({
+  ...(await importActual<typeof import('../src/wallet')>()),
+  unlockWallet: vi.fn().mockResolvedValue(undefined),
+}))
+
+const { PrivateKey } = await import('@wharfkit/antelope')
+const { loginWithMagicLink } = await import('../src/oidc')
+const { authenticateWithAuthentik, configureCoopId } = await import('../src/oidc/client')
+const { performTimestampHandshake } = await import('../src/oidc/handshake')
+const { decryptPrivateKey } = await import('../src/vault/encrypt')
+const { unlockWallet } = await import('../src/wallet')
+
+const BASE = 'https://coop.example'
+// account больше НЕ параметр — сервер возвращает его в ответе confirm (резолвит из токена).
+const ACCOUNT = 'ant'
+const PARAMS = {
+  issuer: 'https://coop.example/application/o/coopid/',
+  email: 'ant@example.com',
+  token: 'magic-token-xyz',
+  totp: '123456',
+  newPassword: 'Strong#NewPass1',
+}
+
+beforeEach(() => configureCoopId({ apiUrl: BASE }))
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.clearAllMocks()
+})
+
+describe('loginWithMagicLink (Story 12.2) — восстановление доступа', () => {
+  it('happy: новая пара → корректное тело confirm → vault round-trip → повторный вход', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200, json: async () => ({ username: ACCOUNT }) })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const result = await loginWithMagicLink(PARAMS)
+
+    // единственный сетевой вызов — confirm (unlock/handshake/authentik замоканы).
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(fetchMock.mock.calls[0][0]).toBe(`${BASE}/coop/recovery/confirm`)
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body)
+    expect(body.token).toBe(PARAMS.token)
+    expect(body.code).toBe(PARAMS.totp)
+    expect(body.password).toBe(PARAMS.newPassword)
+    expect(body.public_key).toMatch(/^PUB_K1_/)
+    expect(body.vault).toMatchObject({ cipher_version: expect.any(String), salt: expect.any(String), ciphertext: expect.any(String) })
+
+    // AAD больше НЕ зависит от account: тот же блоб расшифровывается под ЛЮБЫМ
+    // subject_id (важен только тип субъекта) — регресс-гард решения 2026-06-15.
+    // И приватный ключ соответствует отправленному public_key — целостность пары.
+    const wif = await decryptPrivateKey(body.vault, PARAMS.newPassword, { subject_type: 'participant', subject_id: 'any-other-account' })
+    expect(PrivateKey.from(wif).toPublic().toString()).toBe(body.public_key)
+
+    // повторный вход новым контуром выполнен; account взят из ответа confirm.
+    expect(authenticateWithAuthentik).toHaveBeenCalledWith(expect.objectContaining({ email: PARAMS.email, password: PARAMS.newPassword, issuer: PARAMS.issuer }))
+    expect(unlockWallet).toHaveBeenCalledWith({ apiUrl: BASE, account: ACCOUNT, password: PARAMS.newPassword })
+    expect(performTimestampHandshake).toHaveBeenCalledWith(BASE)
+    expect(result).toEqual({ accessToken: 'AT', idToken: 'ID_TOK', participantCertificate: 'CERT' })
+  }, 60000)
+
+  it('confirm вернул 200 без username → InvalidRecoveryToken; повторный вход не запускается', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true, status: 200, json: async () => ({}) }))
+    await expect(loginWithMagicLink(PARAMS)).rejects.toMatchObject({ code: 'invalid_recovery_token' })
+    expect(authenticateWithAuthentik).not.toHaveBeenCalled()
+    expect(performTimestampHandshake).not.toHaveBeenCalled()
+  }, 60000)
+
+  it('неверный TOTP (400 invalid_2fa_code) → проброс; повторный вход не запускается', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 400, json: async () => ({ error: 'invalid_2fa_code', error_description: 'Неверный код' }) }))
+
+    await expect(loginWithMagicLink(PARAMS)).rejects.toMatchObject({ code: 'invalid_2fa_code' })
+    expect(authenticateWithAuthentik).not.toHaveBeenCalled()
+    expect(performTimestampHandshake).not.toHaveBeenCalled()
+  }, 60000)
+
+  it('недействительный токен (400 invalid_recovery_token) → проброс', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 400, json: async () => ({ error: 'invalid_recovery_token', error_description: 'Ссылка недействительна' }) }))
+    await expect(loginWithMagicLink(PARAMS)).rejects.toMatchObject({ code: 'invalid_recovery_token' })
+  }, 60000)
+
+  it('429 → TooManyRecoveryAttempts', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 429, json: async () => ({}) }))
+    await expect(loginWithMagicLink(PARAMS)).rejects.toMatchObject({ code: 'too_many_recovery_attempts' })
+  }, 60000)
+
+  it('сеть упала на confirm → NetworkError; повторный вход не запускается', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('down')))
+    await expect(loginWithMagicLink(PARAMS)).rejects.toMatchObject({ code: 'network_error' })
+    expect(authenticateWithAuthentik).not.toHaveBeenCalled()
+  }, 60000)
+
+  it('storage задан → локальная копия нового блоба сохранена под account', async () => {
+    const store = new Map<string, string>()
+    const storage = {
+      get: vi.fn(async (k: string) => store.get(k) ?? null),
+      set: vi.fn(async (k: string, v: string) => { store.set(k, v) }),
+      remove: vi.fn(async (k: string) => { store.delete(k) }),
+    }
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true, status: 200, json: async () => ({ username: ACCOUNT }) }))
+
+    await loginWithMagicLink({ ...PARAMS, storage })
+
+    expect(storage.set).toHaveBeenCalledTimes(1)
+    const saved = JSON.parse(storage.set.mock.calls[0][1] as string)
+    expect(saved.account).toBe(ACCOUNT)
+    expect(saved.blob).toMatchObject({ cipher_version: expect.any(String) })
+  }, 60000)
+})

components/auth/test/oidc-recover.test.ts

@@ -0,0 +1,29 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { recover } from '../src/oidc'
+import { configureCoopId } from '../src/oidc/client'
+
+beforeEach(() => configureCoopId({ apiUrl: 'https://coop.example' }))
+afterEach(() => vi.unstubAllGlobals())
+
+describe('recover (Эпик 3) — запрос восстановления доступа', () => {
+  it('шлёт POST /coop/recovery/request с email (202 — нормальный путь, анти-enumeration)', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 202, json: async () => ({}) })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await recover('user@example.com')
+
+    expect(fetchMock.mock.calls[0][0]).toBe('https://coop.example/coop/recovery/request')
+    expect(fetchMock.mock.calls[0][1].method).toBe('POST')
+    expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toEqual({ email: 'user@example.com' })
+  })
+
+  it('429 → TooManyRecoveryAttempts', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 429, json: async () => ({}) }))
+    await expect(recover('u@e.com')).rejects.toMatchObject({ code: 'too_many_recovery_attempts' })
+  })
+
+  it('сеть упала → NetworkError', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('down')))
+    await expect(recover('u@e.com')).rejects.toMatchObject({ code: 'network_error' })
+  })
+})

components/auth/test/oidc-tokens.test.ts

@@ -0,0 +1,134 @@
+import type { StorageAdapter } from '../src/wallet'
+import { SignJWT } from 'jose'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { AuthV2Error } from '../src/errors'
+import { clearSession, configureTokenStorage, currentTokens, getAccessToken, restoreSession, setSession } from '../src/oidc/tokens'
+
+/** JWT с заданным exp (сек от now); содержимое не важно — getAccessToken читает только exp. */
+async function jwtExpIn(seconds: number): Promise<string> {
+  return new SignJWT({})
+    .setProtectedHeader({ alg: 'HS256' })
+    .setIssuedAt()
+    .setExpirationTime(`${seconds}s`)
+    .sign(new TextEncoder().encode('t'))
+}
+
+function okJson(body: unknown) {
+  return { ok: true, status: 200, json: async () => body }
+}
+
+/** In-memory StorageAdapter для тестов персистентности токенов. */
+function memoryStorage(): StorageAdapter & { dump: () => Record<string, string> } {
+  const m = new Map<string, string>()
+  return {
+    get: async k => m.get(k) ?? null,
+    set: async (k, v) => void m.set(k, v),
+    remove: async k => void m.delete(k),
+    dump: () => Object.fromEntries(m),
+  }
+}
+
+beforeEach(() => clearSession())
+afterEach(() => {
+  vi.unstubAllGlobals()
+  configureTokenStorage(null)
+  clearSession()
+})
+
+describe('getAccessToken lifecycle (Story 1.7) — токен внутри SDK, авто-refresh', () => {
+  it('нет активной сессии → бросает', async () => {
+    await expect(getAccessToken()).rejects.toBeInstanceOf(AuthV2Error)
+  })
+
+  it('свежий access → возвращается без обращения к сети', async () => {
+    const access = await jwtExpIn(3600)
+    setSession('https://coop.example', { accessToken: access, refreshToken: 'r' })
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+
+    expect(await getAccessToken()).toBe(access)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('истёкший access → refresh через /coop/refresh, новая пара сохраняется', async () => {
+    const expired = await jwtExpIn(-10)
+    const fresh = await jwtExpIn(3600)
+    setSession('https://coop.example/', { accessToken: expired, refreshToken: 'r-old' })
+    const fetchMock = vi.fn().mockResolvedValue(okJson({ access_token: fresh, refresh_token: 'r-new' }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    expect(await getAccessToken()).toBe(fresh)
+    expect(fetchMock.mock.calls[0][0]).toBe('https://coop.example/coop/refresh')
+    expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toEqual({ refresh_token: 'r-old' })
+    expect(currentTokens()).toEqual({ accessToken: fresh, refreshToken: 'r-new' })
+  })
+
+  it('refresh 401 → SessionBindingExpired (нужен повторный вход)', async () => {
+    const expired = await jwtExpIn(-10)
+    setSession('https://coop.example', { accessToken: expired, refreshToken: 'r' })
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 401, json: async () => ({}) }))
+
+    await expect(getAccessToken()).rejects.toMatchObject({ code: 'session_binding_expired' })
+  })
+})
+
+describe('персистентность токенов (паритет с легаси — переживание reload)', () => {
+  it('setSession персистит пару токенов в storage', async () => {
+    const storage = memoryStorage()
+    const access = await jwtExpIn(3600)
+    configureTokenStorage(storage)
+    setSession('https://coop.example', { accessToken: access, refreshToken: 'r' })
+    expect(JSON.stringify(storage.dump())).toContain(access)
+  })
+
+  it('restoreSession поднимает пару после «reload» (RAM пуста, storage цел) — сессия переживает F5', async () => {
+    const access = await jwtExpIn(3600)
+    // «До reload»: storage с записью, как её оставил setSession в прошлой сессии.
+    const storage = memoryStorage()
+    await storage.set('coopid.session.tokens', JSON.stringify({ apiBase: 'https://coop.example', tokens: { accessToken: access, refreshToken: 'r' } }))
+    // «После reload»: RAM пуста (beforeEach), подключаем storage и восстанавливаем.
+    configureTokenStorage(storage)
+
+    expect(await restoreSession()).toBe(true)
+    expect(currentTokens()).toEqual({ accessToken: access, refreshToken: 'r' })
+    expect(await getAccessToken()).toBe(access) // токен жив без сети
+  })
+
+  it('нет персистентной записи → restoreSession=false (нужен вход)', async () => {
+    configureTokenStorage(memoryStorage())
+    expect(await restoreSession()).toBe(false)
+    await expect(getAccessToken()).rejects.toBeInstanceOf(AuthV2Error)
+  })
+
+  it('активная RAM-сессия не перетирается restoreSession', async () => {
+    const access = await jwtExpIn(3600)
+    setSession('https://coop.example', { accessToken: access, refreshToken: 'r' })
+    configureTokenStorage(memoryStorage()) // пустой storage
+    expect(await restoreSession()).toBe(true) // уже в RAM
+    expect(currentTokens()).toEqual({ accessToken: access, refreshToken: 'r' })
+  })
+
+  it('refresh обновляет персистентную копию (на диске свежий refresh-токен)', async () => {
+    const storage = memoryStorage()
+    const expired = await jwtExpIn(-10)
+    const fresh = await jwtExpIn(3600)
+    configureTokenStorage(storage)
+    setSession('https://coop.example', { accessToken: expired, refreshToken: 'r-old' })
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(okJson({ access_token: fresh, refresh_token: 'r-new' })))
+
+    expect(await getAccessToken()).toBe(fresh)
+    const dump = JSON.stringify(storage.dump())
+    expect(dump).toContain('r-new')
+    expect(dump).not.toContain('r-old')
+  })
+
+  it('clearSession стирает персистентную копию (logout)', async () => {
+    const storage = memoryStorage()
+    const access = await jwtExpIn(3600)
+    configureTokenStorage(storage)
+    setSession('https://coop.example', { accessToken: access, refreshToken: 'r' })
+    expect(Object.keys(storage.dump())).toHaveLength(1)
+    clearSession()
+    expect(Object.keys(storage.dump())).toHaveLength(0)
+  })
+})

components/auth/test/pin.test.ts

@@ -0,0 +1,123 @@
+import type { StorageAdapter } from '../src/wallet'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { AuthV2Error, AuthV2ErrorCode } from '../src/errors'
+import {
+  clearPinCache,
+  DEFAULT_PIN,
+  getWallet,
+  hasPinCache,
+  isWalletUnlocked,
+  lockWallet,
+  persistPinCache,
+  unlockWithPin,
+} from '../src/wallet'
+import { storeUnlocked } from '../src/wallet/storage'
+
+const KEY = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'
+const ACCOUNT = 'ant'
+const PUB = 'PUB_K1_'
+
+/** In-memory StorageAdapter (в браузере — localStorage/IndexedDB, тут — Map). */
+function memoryStorage(): StorageAdapter & { dump: () => Record<string, string> } {
+  const m = new Map<string, string>()
+  return {
+    get: async k => m.get(k) ?? null,
+    set: async (k, v) => void m.set(k, v),
+    remove: async k => void m.delete(k),
+    dump: () => Object.fromEntries(m),
+  }
+}
+
+/** Кладёт ключ в RAM-keystore, как это делает unlockWallet после входа паролём. */
+function putUnlocked(): void {
+  // publicKey деривуется внутри unlockWallet/unlockWithPin; здесь для setup
+  // достаточно любого валидного вида — реальный pub проверяем после unlockWithPin.
+  storeUnlocked({ account: ACCOUNT, publicKey: 'PUB_K1_setup', privateKey: KEY })
+}
+
+beforeEach(() => {
+  lockWallet()
+})
+
+afterEach(() => {
+  lockWallet()
+})
+
+describe('pin-кэш: persist → unlock без пароля и round-trip к серверу', () => {
+  it('кастомный ПИН: persist под ПИН, lock, unlock тем же ПИН → тот же account и валидный publicKey', async () => {
+    const storage = memoryStorage()
+    putUnlocked()
+    await persistPinCache({ pin: '135790', storage })
+    lockWallet()
+    expect(isWalletUnlocked()).toBe(false)
+
+    const wallet = await unlockWithPin({ pin: '135790', storage })
+    expect(wallet).not.toBeNull()
+    expect(wallet!.account).toBe(ACCOUNT)
+    expect(wallet!.publicKey).toMatch(new RegExp(`^${PUB}`))
+    expect(isWalletUnlocked()).toBe(true)
+    // keystore реально наполнен правильным ключом — getWallet отдаёт тот же pub
+    expect((await getWallet()).publicKey).toBe(wallet!.publicKey)
+  }, 30000)
+
+  it('дефолтный ПИН (000000): persist и unlock без аргумента pin — прозрачно', async () => {
+    const storage = memoryStorage()
+    putUnlocked()
+    await persistPinCache({ storage }) // pin не задан → DEFAULT_PIN
+    lockWallet()
+
+    const wallet = await unlockWithPin({ storage }) // pin не задан → DEFAULT_PIN
+    expect(wallet).not.toBeNull()
+    expect(wallet!.account).toBe(ACCOUNT)
+    // тем же значением расшифровывается и явный DEFAULT_PIN
+    lockWallet()
+    expect(await unlockWithPin({ pin: DEFAULT_PIN, storage })).not.toBeNull()
+  }, 30000)
+
+  it('неверный ПИН → VaultDecryptionFailed, keystore остаётся пуст', async () => {
+    const storage = memoryStorage()
+    putUnlocked()
+    await persistPinCache({ pin: '111111', storage })
+    lockWallet()
+
+    const err = await unlockWithPin({ pin: '999999', storage }).then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.VaultDecryptionFailed)
+    expect(isWalletUnlocked()).toBe(false)
+  }, 30000)
+})
+
+describe('pin-кэш: отсутствие кэша и жизненный цикл', () => {
+  it('нет кэша → unlockWithPin возвращает null (нужен полный вход паролём)', async () => {
+    const storage = memoryStorage()
+    expect(await unlockWithPin({ storage })).toBeNull()
+    expect(isWalletUnlocked()).toBe(false)
+  })
+
+  it('hasPinCache: false → persist → true → clear → false', async () => {
+    const storage = memoryStorage()
+    expect(await hasPinCache(storage)).toBe(false)
+    putUnlocked()
+    await persistPinCache({ storage })
+    expect(await hasPinCache(storage)).toBe(true)
+    await clearPinCache(storage)
+    expect(await hasPinCache(storage)).toBe(false)
+  }, 30000)
+
+  it('persistPinCache при запертом кошельке → WalletLocked (нечего кэшировать)', async () => {
+    const storage = memoryStorage()
+    lockWallet()
+    const err = await persistPinCache({ storage }).then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.WalletLocked)
+  })
+})
+
+describe('pin-кэш: at-rest — на диске только шифр', () => {
+  it('сохранённая запись не содержит WIF в открытом виде', async () => {
+    const storage = memoryStorage()
+    putUnlocked()
+    await persistPinCache({ pin: '424242', storage })
+    expect(JSON.stringify(storage.dump())).not.toContain(KEY)
+  }, 30000)
+})

components/auth/test/schema-policy.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  compareSchemaVersions,
+  type CoopIdSchemaPolicy,
+  createSchemaPolicyCache,
+  isSchemaVersionSupported,
+  SCHEMA_POLICY_CACHE_TTL_MS,
+} from '../src/index'
+
+const POLICY: CoopIdSchemaPolicy = { current_version: '1', min_supported_version: '1', deprecation: { 0: '2026-01-01' } }
+
+describe('compareSchemaVersions (Story 4.10)', () => {
+  it('числовое сравнение версий', () => {
+    expect(compareSchemaVersions('0', '1')).toBeLessThan(0)
+    expect(compareSchemaVersions('2', '1')).toBeGreaterThan(0)
+    expect(compareSchemaVersions('1', '1')).toBe(0)
+  })
+
+  it('нечисловая версия → лексикографический фолбэк', () => {
+    expect(compareSchemaVersions('a', 'b')).toBeLessThan(0)
+    expect(compareSchemaVersions('v2', 'v2')).toBe(0)
+  })
+
+  it('isSchemaVersionSupported: не старее минимума', () => {
+    expect(isSchemaVersionSupported('1', '1')).toBe(true)
+    expect(isSchemaVersionSupported('2', '1')).toBe(true)
+    expect(isSchemaVersionSupported('0', '1')).toBe(false)
+  })
+})
+
+describe('createSchemaPolicyCache (Story 4.10, FR72)', () => {
+  it('в пределах TTL отдаёт кэш без повторного fetch', async () => {
+    let t = 1000
+    const fetchPolicy = vi.fn().mockResolvedValue(POLICY)
+    const cache = createSchemaPolicyCache({ fetchPolicy, now: () => t })
+    expect(await cache.getMinSupportedVersion()).toBe('1')
+    t += SCHEMA_POLICY_CACHE_TTL_MS - 1
+    await cache.getPolicy()
+    expect(fetchPolicy).toHaveBeenCalledTimes(1)
+  })
+
+  it('после истечения TTL рефетчит политику', async () => {
+    let t = 1000
+    const fetchPolicy = vi.fn().mockResolvedValue(POLICY)
+    const cache = createSchemaPolicyCache({ fetchPolicy, now: () => t })
+    await cache.getPolicy()
+    t += SCHEMA_POLICY_CACHE_TTL_MS + 1
+    await cache.getPolicy()
+    expect(fetchPolicy).toHaveBeenCalledTimes(2)
+  })
+
+  it('офлайн (fetch упал) после истечения TTL → отдаёт stale-кэш', async () => {
+    let t = 1000
+    const fetchPolicy = vi.fn()
+      .mockResolvedValueOnce(POLICY)
+      .mockRejectedValueOnce(new Error('offline'))
+    const cache = createSchemaPolicyCache({ fetchPolicy, now: () => t })
+    await cache.getPolicy()
+    t += SCHEMA_POLICY_CACHE_TTL_MS + 1
+    expect(await cache.getMinSupportedVersion()).toBe('1')
+  })
+
+  it('нет кэша и fetch упал → пробрасывает ошибку', async () => {
+    const fetchPolicy = vi.fn().mockRejectedValue(new Error('offline'))
+    const cache = createSchemaPolicyCache({ fetchPolicy })
+    await expect(cache.getPolicy()).rejects.toThrow('offline')
+  })
+})

components/auth/test/signing.test.ts

@@ -0,0 +1,178 @@
+import { Checksum256, PrivateKey, PublicKey, Signature } from '@wharfkit/antelope'
+import { base64url, SignJWT } from 'jose'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { AuthV2Error, AuthV2ErrorCode } from '../src/errors'
+import { canonicalTimestampMessage, signChainDigest, signDocument, signTimestamp } from '../src/signing'
+import { storeUnlocked, wipeKeystore } from '../src/wallet/storage'
+
+const KEY = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'
+const ACCOUNT = 'ant'
+const PUB = PrivateKey.from(KEY).toPublic().toString()
+
+/** Поддельный, но корректно сформированный session_binding_token (signTimestamp его только декодирует). */
+async function makeToken(sub = ACCOUNT, jti = 'jti-abc-123'): Promise<string> {
+  return new SignJWT({})
+    .setProtectedHeader({ alg: 'HS256' })
+    .setSubject(sub)
+    .setJti(jti)
+    .setExpirationTime('2m')
+    .sign(new TextEncoder().encode('test-secret-padding-0000000000000000'))
+}
+
+beforeEach(() => {
+  storeUnlocked({ account: ACCOUNT, publicKey: PUB, privateKey: KEY })
+})
+
+afterEach(() => {
+  wipeKeystore()
+})
+
+describe('signTimestamp: COOPOS-native recoverable подпись', () => {
+  it('подписывает {ts,jti,sub}; recoverMessage канонического сообщения даёт тот же pubkey', async () => {
+    const token = await makeToken(ACCOUNT, 'jti-abc-123')
+    const res = await signTimestamp({ sessionBindingToken: token })
+
+    expect(res.sub).toBe(ACCOUNT)
+    expect(res.binding_token_jti).toBe('jti-abc-123')
+    expect(res.public_key).toBe(PUB)
+    expect(res.signature).toMatch(/^SIG_K1_/)
+
+    const msg = new TextEncoder().encode(canonicalTimestampMessage({
+      ts: res.ts,
+      binding_token_jti: res.binding_token_jti,
+      sub: res.sub,
+    }))
+    const recovered = Signature.from(res.signature).recoverMessage(msg).toString()
+    expect(recovered).toBe(PUB)
+  })
+
+  it('подмена сообщения ломает восстановление pubkey (integrity)', async () => {
+    const res = await signTimestamp({ sessionBindingToken: await makeToken() })
+    const tampered = new TextEncoder().encode(canonicalTimestampMessage({
+      ts: res.ts,
+      binding_token_jti: res.binding_token_jti,
+      sub: 'someone-else',
+    }))
+    const recovered = Signature.from(res.signature).recoverMessage(tampered).toString()
+    expect(recovered).not.toBe(PUB)
+  })
+
+  it('запертый кошелёк → WalletLocked', async () => {
+    wipeKeystore()
+    const err = await signTimestamp({ sessionBindingToken: await makeToken() }).then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.WalletLocked)
+  })
+
+  it('кошелёк не совпадает с субъектом токена → ClientWalletMismatch', async () => {
+    const err = await signTimestamp({ sessionBindingToken: await makeToken('petrov') }).then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.ClientWalletMismatch)
+  })
+
+  it('битый токен → SessionBindingExpired', async () => {
+    const err = await signTimestamp({ sessionBindingToken: 'not-a-jwt' }).then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.SessionBindingExpired)
+  })
+
+  it('токен без sub/jti → SessionBindingExpired', async () => {
+    const noClaims = await new SignJWT({})
+      .setProtectedHeader({ alg: 'HS256' })
+      .sign(new TextEncoder().encode('test-secret-padding-0000000000000000'))
+    const err = await signTimestamp({ sessionBindingToken: noClaims }).then(() => null, e => e)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.SessionBindingExpired)
+  })
+})
+
+describe('signChainDigest: подпись tx-дайджеста ключом из keystore (мост подписи CoopID)', () => {
+  it('подписывает дайджест; recoverDigest даёт pubkey подписанта (ключ наружу не выходит — только подпись)', async () => {
+    const digestHex = 'ab'.repeat(32) // 32 байта signing-дайджеста
+    const sig = await signChainDigest(digestHex)
+    expect(sig).toMatch(/^SIG_K1_/)
+    const recovered = Signature.from(sig).recoverDigest(Checksum256.from(digestHex)).toString()
+    expect(recovered).toBe(PUB)
+  })
+
+  it('подмена дайджеста ломает восстановление pubkey (integrity)', async () => {
+    const sig = await signChainDigest('ab'.repeat(32))
+    const recovered = Signature.from(sig).recoverDigest(Checksum256.from('cd'.repeat(32))).toString()
+    expect(recovered).not.toBe(PUB)
+  })
+
+  it('запертый кошелёк → WalletLocked (подпись транзакции невозможна без unlock)', async () => {
+    wipeKeystore()
+    const err = await signChainDigest('ab'.repeat(32)).then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.WalletLocked)
+  })
+})
+
+describe('canonicalTimestampMessage: детерминизм', () => {
+  it('фиксированный алфавитный порядок ключей', () => {
+    expect(canonicalTimestampMessage({ ts: 't', binding_token_jti: 'j', sub: 's' }))
+      .toBe('{"binding_token_jti":"j","sub":"s","ts":"t"}')
+  })
+})
+
+/** Верифицирует compact JWS ES256K: разбирает подпись R||S и проверяет её ключом. */
+function verifyJws(jws: string, pub: string): boolean {
+  const [h, p, s] = jws.split('.')
+  const rs = base64url.decode(s)
+  const sig = Signature.from({ type: 'K1', r: rs.slice(0, 32), s: rs.slice(32, 64), recid: 0 })
+  return sig.verifyMessage(new TextEncoder().encode(`${h}.${p}`), PublicKey.from(pub))
+}
+
+describe('signDocument: локальная подпись compact JWS (Story 2.3)', () => {
+  it('возвращает JWS <header>.<payload>.<signature>; header alg/kid, payload round-trip, подпись валидна', async () => {
+    const doc = new TextEncoder().encode('Протокол собрания №1')
+    const jws = await signDocument({ payload: doc, alg: 'ES256K' })
+
+    const parts = jws.split('.')
+    expect(parts).toHaveLength(3)
+
+    const header = JSON.parse(new TextDecoder().decode(base64url.decode(parts[0])))
+    expect(header).toEqual({ alg: 'ES256K', kid: ACCOUNT })
+
+    // payload декодируется обратно в исходные байты
+    expect(base64url.decode(parts[1])).toEqual(doc)
+
+    // подпись — ровно 64 байта (R||S, без recovery) и валидна для pubkey подписанта
+    expect(base64url.decode(parts[2]).length).toBe(64)
+    expect(verifyJws(jws, PUB)).toBe(true)
+  })
+
+  it('строковый payload эквивалентен его UTF-8 байтам', async () => {
+    const text = 'привет, кооператив'
+    const fromString = await signDocument({ payload: text })
+    const fromBytes = await signDocument({ payload: new TextEncoder().encode(text) })
+    // RFC6979-детерминизм K1: одинаковый вход → одинаковый JWS
+    expect(fromString).toBe(fromBytes)
+    expect(verifyJws(fromString, PUB)).toBe(true)
+  })
+
+  it('integrity: подделка payload в JWS ломает проверку подписи', async () => {
+    const jws = await signDocument({ payload: 'исходный документ' })
+    const [h, , s] = jws.split('.')
+    const tampered = `${h}.${base64url.encode(new TextEncoder().encode('подменённый документ'))}.${s}`
+    expect(verifyJws(tampered, PUB)).toBe(false)
+  })
+
+  it('alg по умолчанию — ES256K', async () => {
+    const jws = await signDocument({ payload: 'x' })
+    const header = JSON.parse(new TextDecoder().decode(base64url.decode(jws.split('.')[0])))
+    expect(header.alg).toBe('ES256K')
+  })
+
+  it('неподдерживаемый alg → AuthV2Error', async () => {
+    const err = await signDocument({ payload: 'x', alg: 'RS256' as 'ES256K' }).then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+  })
+
+  it('запертый кошелёк → WalletLocked', async () => {
+    wipeKeystore()
+    const err = await signDocument({ payload: 'x' }).then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.WalletLocked)
+  })
+})

components/auth/test/vault-store.test.ts

@@ -0,0 +1,94 @@
+import type { StorageAdapter } from '../src/wallet'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { decryptPrivateKey } from '../src/vault'
+import { clearLocalVault, loadLocalVault, saveLocalVault, saveToVault, storeVaultBlob } from '../src/wallet'
+
+const BLOB = {
+  cipher_version: 'aes-256-gcm-v1',
+  kdf_version: 'argon2id-v1',
+  salt: 'c2FsdA',
+  nonce: 'bm9uY2U',
+  ciphertext: 'Y2lwaGVy',
+  auth_tag: 'dGFn',
+}
+
+/** In-memory StorageAdapter для теста локальной копии. */
+function memStorage(): StorageAdapter & { map: Map<string, string> } {
+  const map = new Map<string, string>()
+  return {
+    map,
+    get: async k => map.get(k) ?? null,
+    set: async (k, v) => void map.set(k, v),
+    remove: async k => void map.delete(k),
+  }
+}
+
+afterEach(() => vi.unstubAllGlobals())
+
+describe('storeVaultBlob (Story 11.3) — POST /coop/vault', () => {
+  it('шлёт POST с плоскими subject_type/subject_id + полями blob; 201 ok', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 201, json: async () => ({}) })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await storeVaultBlob('https://coop.example', { subject_type: 'participant', subject_id: 'ant' }, BLOB)
+
+    expect(fetchMock.mock.calls[0][0]).toBe('https://coop.example/coop/vault')
+    expect(fetchMock.mock.calls[0][1].method).toBe('POST')
+    expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toEqual({ ...BLOB, subject_type: 'participant', subject_id: 'ant' })
+  })
+
+  it('не-ok ответ → NetworkError', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status: 500, json: async () => ({}) }))
+    await expect(storeVaultBlob('https://coop.example', { subject_type: 'participant', subject_id: 'ant' }, BLOB))
+      .rejects
+      .toMatchObject({ code: 'network_error' })
+  })
+
+  it('сеть упала → NetworkError', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('down')))
+    await expect(storeVaultBlob('https://coop.example', { subject_type: 'participant', subject_id: 'ant' }, BLOB))
+      .rejects
+      .toMatchObject({ code: 'network_error' })
+  })
+})
+
+describe('локальная копия vault (Story 11.3)', () => {
+  it('save → load возвращает blob того же аккаунта', async () => {
+    const storage = memStorage()
+    await saveLocalVault(storage, 'ant', BLOB)
+    expect(await loadLocalVault(storage, 'ant')).toEqual(BLOB)
+  })
+
+  it('load для другого аккаунта → null (чужой blob не отдаём)', async () => {
+    const storage = memStorage()
+    await saveLocalVault(storage, 'ant', BLOB)
+    expect(await loadLocalVault(storage, 'someone-else')).toBeNull()
+  })
+
+  it('нет записи → null; clear удаляет', async () => {
+    const storage = memStorage()
+    expect(await loadLocalVault(storage, 'ant')).toBeNull()
+    await saveLocalVault(storage, 'ant', BLOB)
+    await clearLocalVault(storage)
+    expect(await loadLocalVault(storage, 'ant')).toBeNull()
+  })
+})
+
+describe('saveToVault (Story 11.3) — encrypt → POST → локальная копия', () => {
+  it('шифрует ключ паролём, шлёт на сервер и кладёт локально; blob расшифровывается обратно', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 201, json: async () => ({}) })
+    vi.stubGlobal('fetch', fetchMock)
+    const storage = memStorage()
+    const wif = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'
+
+    const blob = await saveToVault({ apiUrl: 'https://coop.example', account: 'ant', privateKey: wif, password: 'P@ss', storage })
+
+    // сервер получил blob с субъектом ant
+    expect(fetchMock.mock.calls[0][0]).toBe('https://coop.example/coop/vault')
+    expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toMatchObject({ subject_type: 'participant', subject_id: 'ant', cipher_version: 'aes-256-gcm-v1' })
+    // локальная копия сохранена
+    expect(await loadLocalVault(storage, 'ant')).toEqual(blob)
+    // round-trip: тем же паролём ключ восстанавливается (неверный пароль покрыт wallet.test.ts)
+    expect(await decryptPrivateKey(blob, 'P@ss', { subject_type: 'participant', subject_id: 'ant' })).toBe(wif)
+  }, 60000)
+})

components/auth/test/vault.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import { AuthV2Error, AuthV2ErrorCode } from '../src/errors'
+import { decryptPrivateKey, encryptPrivateKey } from '../src/vault'
+import type { VaultSubject } from '../src/vault'
+
+const KEY = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'
+const PW = 'correct-horse-battery-staple-12'
+const SUBJECT: VaultSubject = { subject_type: 'participant', subject_id: 'ant' }
+
+describe('vault: Argon2id + AES-256-GCM', () => {
+  it('round-trip: encrypt → decrypt тем же паролем даёт исходный ключ', async () => {
+    const blob = await encryptPrivateKey(KEY, PW, SUBJECT)
+    expect(blob.cipher_version).toBe('aes-256-gcm-v1')
+    expect(blob.kdf_version).toBe('argon2id-v1')
+    const restored = await decryptPrivateKey(blob, PW, SUBJECT)
+    expect(restored).toBe(KEY)
+  })
+
+  it('каждое шифрование — новые salt и nonce', async () => {
+    const a = await encryptPrivateKey(KEY, PW, SUBJECT)
+    const b = await encryptPrivateKey(KEY, PW, SUBJECT)
+    expect(a.salt).not.toBe(b.salt)
+    expect(a.nonce).not.toBe(b.nonce)
+    expect(a.ciphertext).not.toBe(b.ciphertext)
+  })
+
+  it('неверный пароль → VaultDecryptionFailed', async () => {
+    const blob = await encryptPrivateKey(KEY, PW, SUBJECT)
+    const err = await decryptPrivateKey(blob, 'wrong-password-000000000000', SUBJECT).then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.VaultDecryptionFailed)
+  })
+
+  it('подмена subject_id НЕ ломает расшифровку: AAD не зависит от account (решение 2026-06-15)', async () => {
+    const blob = await encryptPrivateKey(KEY, PW, SUBJECT)
+    // другой subject_id, тот же тип и пароль → расшифровка проходит (id не в AAD).
+    const restored = await decryptPrivateKey(blob, PW, { subject_type: 'participant', subject_id: 'petrov' })
+    expect(restored).toBe(KEY)
+  })
+
+  it('подмена типа субъекта (AAD) ломает расшифровку', async () => {
+    const blob = await encryptPrivateKey(KEY, PW, SUBJECT)
+    const err = await decryptPrivateKey(blob, PW, { subject_type: 'coop', subject_id: 'ant' }).then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.VaultDecryptionFailed)
+  })
+}, 30000)

components/auth/test/verify-document.test.ts

@@ -0,0 +1,82 @@
+import { PrivateKey } from '@wharfkit/antelope'
+import { base64url } from 'jose'
+import { afterEach, describe, expect, it } from 'vitest'
+import { type KeyValidityWindow, verifyDocumentOffline } from '../src/index'
+import { signDocument } from '../src/signing'
+import { storeUnlocked, wipeKeystore } from '../src/wallet/storage'
+
+const KEY1 = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'
+const PUB1 = PrivateKey.from(KEY1).toPublic().toString()
+const ACCOUNT = 'ant'
+
+// Второй ключ — результат ротации (Story 3.3). Генерим, чтобы не хардкодить.
+const key2 = PrivateKey.generate('K1')
+const KEY2 = key2.toString()
+const PUB2 = key2.toPublic().toString()
+
+// key1 активен в блоках [100,200], затем ротация на key2 [201, сейчас].
+const authority: KeyValidityWindow[] = [
+  { public_key: PUB1, valid_from_block: 100, valid_to_block: 200 },
+  { public_key: PUB2, valid_from_block: 201, valid_to_block: null },
+]
+
+async function signWith(wif: string, payload: string): Promise<string> {
+  storeUnlocked({ account: ACCOUNT, publicKey: PrivateKey.from(wif).toPublic().toString(), privateKey: wif })
+  const jws = await signDocument({ payload })
+  wipeKeystore()
+  return jws
+}
+
+afterEach(() => wipeKeystore())
+
+describe('verifyDocumentOffline: backward-валидность (Story 2.5)', () => {
+  it('подпись старым ключом валидна, если ключ был активен на момент подписи (хотя сейчас ротирован)', async () => {
+    const jws = await signWith(KEY1, 'протокол собрания №7')
+    const res = await verifyDocumentOffline({ jws, signedAtBlock: 150, authority })
+    expect(res.valid).toBe(true)
+    expect(res.matched_key).toBe(PUB1)
+  })
+
+  it('та же подпись на блоке ПОСЛЕ ротации → невалидна (key_not_active_at_signing)', async () => {
+    const jws = await signWith(KEY1, 'протокол собрания №7')
+    const res = await verifyDocumentOffline({ jws, signedAtBlock: 250, authority })
+    expect(res.valid).toBe(false)
+    expect(res.reason).toBe('key_not_active_at_signing')
+  })
+
+  it('подпись текущим ключом в его окне → валидна', async () => {
+    const jws = await signWith(KEY2, 'протокол собрания №8')
+    const res = await verifyDocumentOffline({ jws, signedAtBlock: 300, authority })
+    expect(res.valid).toBe(true)
+    expect(res.matched_key).toBe(PUB2)
+  })
+
+  it('подделка payload → signature_mismatch', async () => {
+    const jws = await signWith(KEY1, 'оригинальный документ')
+    const [h, , s] = jws.split('.')
+    const tampered = `${h}.${base64url.encode(new TextEncoder().encode('подменённый документ'))}.${s}`
+    const res = await verifyDocumentOffline({ jws: tampered, signedAtBlock: 150, authority })
+    expect(res.valid).toBe(false)
+    expect(res.reason).toBe('signature_mismatch')
+  })
+
+  it('чужой ключ (нет в хронологии подписанта) → signature_mismatch', async () => {
+    const jws = await signWith(KEY2, 'документ')
+    const onlyKey1: KeyValidityWindow[] = [{ public_key: PUB1, valid_from_block: 100, valid_to_block: 200 }]
+    const res = await verifyDocumentOffline({ jws, signedAtBlock: 150, authority: onlyKey1 })
+    expect(res.valid).toBe(false)
+    expect(res.reason).toBe('signature_mismatch')
+  })
+
+  it('некорректный JWS → malformed_jws', async () => {
+    expect((await verifyDocumentOffline({ jws: 'a.b', signedAtBlock: 1, authority })).reason).toBe('malformed_jws')
+  })
+
+  it('неподдерживаемый alg → unsupported_alg', async () => {
+    const h = base64url.encode(new TextEncoder().encode(JSON.stringify({ alg: 'RS256' })))
+    const p = base64url.encode(new TextEncoder().encode('x'))
+    const sig = base64url.encode(new Uint8Array(64))
+    const res = await verifyDocumentOffline({ jws: `${h}.${p}.${sig}`, signedAtBlock: 1, authority })
+    expect(res.reason).toBe('unsupported_alg')
+  })
+})

components/auth/test/verify-offline.test.ts

@@ -0,0 +1,167 @@
+import type { PrivateKey as PrivateKeyType } from '@wharfkit/antelope'
+import { PrivateKey } from '@wharfkit/antelope'
+import { base64url } from 'jose'
+import { describe, expect, it } from 'vitest'
+import { type CoopChainLink, verifyOffline } from '../src/index'
+
+// Цепь доверия ano → voskhod → vostok(issuer). Ключи генерим, чтобы не хардкодить.
+const anoKey = PrivateKey.generate('K1')
+const voskhodKey = PrivateKey.generate('K1')
+const issuerKey = PrivateKey.generate('K1') // vostok — издатель, его ключом подписан cert
+
+const PUB_ANO = anoKey.toPublic().toString()
+const PUB_VOSKHOD = voskhodKey.toPublic().toString()
+const PUB_ISSUER = issuerKey.toPublic().toString()
+
+const CHAIN: CoopChainLink[] = [
+  { account: 'ano', public_key: PUB_ANO },
+  { account: 'voskhod', public_key: PUB_VOSKHOD },
+  { account: 'vostok', public_key: PUB_ISSUER },
+]
+
+// Полный доверенный кэш (chain_manifests_cache) — все звенья известны.
+const TRUSTED: Record<string, string> = { ano: PUB_ANO, voskhod: PUB_VOSKHOD, vostok: PUB_ISSUER }
+
+const NOW = 1_900_000_000_000 // фиксированный «сейчас» (мс)
+const FUTURE_EXP = Math.floor(NOW / 1000) + 3600 // +1ч
+const PAST_EXP = Math.floor(NOW / 1000) - 10
+
+interface CertOpts {
+  chain?: CoopChainLink[]
+  exp?: number
+  alg?: string
+  signWith?: PrivateKeyType
+  schemaVersion?: string
+}
+
+/** Собрать compact JWS-сертификат (формат CertificateService, Story 1.8). */
+function makeCert(opts: CertOpts = {}): string {
+  const signer = opts.signWith ?? issuerKey
+  const header = base64url.encode(JSON.stringify({ alg: opts.alg ?? 'ES256K', typ: 'JWT', kid: signer.toPublic().toString() }))
+  const payload = base64url.encode(JSON.stringify({
+    coopname: 'vostok',
+    coop_chain: opts.chain ?? CHAIN,
+    exp: opts.exp ?? FUTURE_EXP,
+    sub: 'uuid-1',
+    jti: 'serial-123',
+    claim_schema_version: opts.schemaVersion ?? '1',
+  }))
+  const signingInput = `${header}.${payload}`
+  const sig = signer.signMessage(new TextEncoder().encode(signingInput))
+  const rs = sig.data.array.slice(1) // [recovery(1), r(32), s(32)] → R||S
+  return `${signingInput}.${base64url.encode(rs)}`
+}
+
+describe('verifyOffline: офлайн-проверка удостоверения (Story 4.4)', () => {
+  it('валидный сертификат с доверенной цепью и якорем → valid, issuer', async () => {
+    const res = await verifyOffline(makeCert(), { trustedKeys: TRUSTED, now: NOW })
+    expect(res.valid).toBe(true)
+    expect(res.issuer).toBe('vostok')
+    expect(res.reason).toBeUndefined()
+  })
+
+  it('exp в прошлом → expired', async () => {
+    const res = await verifyOffline(makeCert({ exp: PAST_EXP }), { trustedKeys: TRUSTED, now: NOW })
+    expect(res.valid).toBe(false)
+    expect(res.reason).toBe('expired')
+  })
+
+  it('цепь не укоренена в известном ano (чужой якорь) → untrusted_anchor', async () => {
+    const other = PrivateKey.generate('K1').toPublic().toString()
+    const res = await verifyOffline(makeCert(), { trustedKeys: TRUSTED, trustAnchor: other, now: NOW })
+    expect(res.valid).toBe(false)
+    expect(res.reason).toBe('untrusted_anchor')
+  })
+
+  it('звено издателя не совпадает с доверенным кэшем → untrusted_issuer', async () => {
+    const foreign = PrivateKey.generate('K1').toPublic().toString()
+    const res = await verifyOffline(makeCert(), {
+      trustedKeys: { ano: PUB_ANO, voskhod: PUB_VOSKHOD, vostok: foreign },
+      now: NOW,
+    })
+    expect(res.valid).toBe(false)
+    expect(res.reason).toBe('untrusted_issuer')
+  })
+
+  it('без доверенного кэша ключей → fail-closed (untrusted_issuer)', async () => {
+    const res = await verifyOffline(makeCert(), { trustAnchor: PUB_ANO, now: NOW })
+    expect(res.valid).toBe(false)
+    expect(res.reason).toBe('untrusted_issuer')
+  })
+
+  it('подпись чужим ключом при валидной цепи → signature_mismatch', async () => {
+    // cert подписан foreignKey, но coop_chain заявляет издателя PUB_ISSUER;
+    // verifyOffline сверяет подпись с ключом издателя из цепи (не с kid) → провал.
+    const cert = makeCert({ signWith: PrivateKey.generate('K1') })
+    const res = await verifyOffline(cert, { trustedKeys: TRUSTED, now: NOW })
+    expect(res.valid).toBe(false)
+    expect(res.reason).toBe('signature_mismatch')
+  })
+
+  it('high-S подпись (не каноническая, как у jose/Node) → принимается через low-S нормализацию', async () => {
+    const cert = makeCert()
+    const [h, p, s] = cert.split('.')
+    const rs = base64url.decode(s)
+    // S → n − S (переводим каноническую low-S подпись wharfkit в high-S вариант).
+    const n = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141n
+    let sVal = 0n
+    for (const b of rs.slice(32, 64))
+      sVal = (sVal << 8n) | BigInt(b)
+    let high = n - sVal
+    const highRs = new Uint8Array(rs)
+    for (let i = 63; i >= 32; i--) {
+      highRs[i] = Number(high & 0xFFn)
+      high >>= 8n
+    }
+    const highCert = `${h}.${p}.${base64url.encode(highRs)}`
+    const res = await verifyOffline(highCert, { trustedKeys: TRUSTED, now: NOW })
+    expect(res.valid).toBe(true)
+    expect(res.issuer).toBe('vostok')
+  })
+
+  it('некорректный JWS (две части) → malformed_certificate', async () => {
+    const res = await verifyOffline('a.b', { trustedKeys: TRUSTED, now: NOW })
+    expect(res.reason).toBe('malformed_certificate')
+  })
+
+  it('неподдерживаемый alg → unsupported_alg', async () => {
+    const res = await verifyOffline(makeCert({ alg: 'RS256' }), { trustedKeys: TRUSTED, now: NOW })
+    expect(res.reason).toBe('unsupported_alg')
+  })
+
+  it('пустой coop_chain → malformed_certificate', async () => {
+    const res = await verifyOffline(makeCert({ chain: [] }), { trustedKeys: TRUSTED, now: NOW })
+    expect(res.reason).toBe('malformed_certificate')
+  })
+
+  it('версия схемы старее min_supported_version → unsupported_schema_version (Story 4.10)', async () => {
+    const res = await verifyOffline(makeCert({ schemaVersion: '0' }), { trustedKeys: TRUSTED, now: NOW, minSchemaVersion: '1' })
+    expect(res.valid).toBe(false)
+    expect(res.reason).toBe('unsupported_schema_version')
+  })
+
+  it('версия схемы = min_supported_version → ось схемы пройдена, cert валиден (Story 4.10)', async () => {
+    const res = await verifyOffline(makeCert({ schemaVersion: '1' }), { trustedKeys: TRUSTED, now: NOW, minSchemaVersion: '1' })
+    expect(res.valid).toBe(true)
+    expect(res.issuer).toBe('vostok')
+  })
+
+  it('без minSchemaVersion ось схемы не гейтит — даже старая версия проходит (Story 4.10)', async () => {
+    const res = await verifyOffline(makeCert({ schemaVersion: '0' }), { trustedKeys: TRUSTED, now: NOW })
+    expect(res.valid).toBe(true)
+  })
+
+  it('не делает сетевых запросов (fetch недоступен) → всё равно verdict', async () => {
+    const orig = globalThis.fetch
+    globalThis.fetch = (() => {
+      throw new Error('сеть запрещена в офлайн-проверке')
+    }) as typeof fetch
+    try {
+      const res = await verifyOffline(makeCert(), { trustedKeys: TRUSTED, now: NOW })
+      expect(res.valid).toBe(true)
+    }
+    finally {
+      globalThis.fetch = orig
+    }
+  })
+})

components/auth/test/wallet.test.ts

@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { AuthV2Error, AuthV2ErrorCode } from '../src/errors'
+import { encryptPrivateKey } from '../src/vault'
+import {
+  getWallet,
+  isWalletUnlocked,
+  lockWallet,
+  unlockWallet,
+  Wallet,
+} from '../src/wallet'
+
+const KEY = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'
+const PW = 'correct-horse-battery-staple-12'
+const ACCOUNT = 'ant'
+const API = 'http://stub'
+
+/** Подменяет fetch так, чтобы GET vault отдавал заранее зашифрованный blob. */
+async function stubVaultFetch(password = PW): Promise<void> {
+  const blob = await encryptPrivateKey(KEY, password, { subject_type: 'participant', subject_id: ACCOUNT })
+  vi.stubGlobal('fetch', vi.fn(async () => ({ ok: true, status: 200, json: async () => blob }) as any))
+}
+
+beforeEach(() => {
+  lockWallet()
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  lockWallet()
+})
+
+describe('wallet: unlock + in-memory keystore + getWallet', () => {
+  it('unlock → getWallet отдаёт account и деривованный publicKey', async () => {
+    await stubVaultFetch()
+    const wallet = await unlockWallet({ apiUrl: API, account: ACCOUNT, password: PW })
+    expect(wallet.account).toBe(ACCOUNT)
+    expect(wallet.publicKey).toMatch(/^PUB_K1_/)
+    expect(isWalletUnlocked()).toBe(true)
+
+    const again = await getWallet()
+    expect(again.publicKey).toBe(wallet.publicKey)
+  }, 30000)
+
+  it('неверный пароль → VaultDecryptionFailed, keystore остаётся пуст', async () => {
+    await stubVaultFetch(PW)
+    const err = await unlockWallet({ apiUrl: API, account: ACCOUNT, password: 'wrong-password-000000000000' })
+      .then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.VaultDecryptionFailed)
+    expect(isWalletUnlocked()).toBe(false)
+  }, 30000)
+
+  it('getWallet при запертом кошельке → WalletLocked', async () => {
+    const err = await getWallet().then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.WalletLocked)
+  })
+
+  it('сеть недоступна → NetworkError', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => ({ ok: false, status: 503, json: async () => ({}) }) as any))
+    const err = await unlockWallet({ apiUrl: API, account: ACCOUNT, password: PW }).then(() => null, e => e)
+    expect(err).toBeInstanceOf(AuthV2Error)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.NetworkError)
+  })
+})
+
+describe('wallet: несериализуемость приватного ключа', () => {
+  it('JSON.stringify(wallet) не раскрывает приватный ключ', async () => {
+    await stubVaultFetch()
+    const wallet = await unlockWallet({ apiUrl: API, account: ACCOUNT, password: PW })
+    const serialized = JSON.stringify(wallet)
+    expect(serialized).not.toContain(KEY)
+    expect(JSON.parse(serialized)).toEqual({ account: ACCOUNT, publicKey: wallet.publicKey })
+    // приватного ключа нет ни в одном перечислимом свойстве обёртки
+    expect(Object.values(wallet as unknown as Record<string, unknown>)).not.toContain(KEY)
+    expect(wallet).toBeInstanceOf(Wallet)
+  }, 30000)
+})
+
+describe('wallet: lock/wipe', () => {
+  it('lockWallet затирает keystore → getWallet бросает; идемпотентно', async () => {
+    await stubVaultFetch()
+    await unlockWallet({ apiUrl: API, account: ACCOUNT, password: PW })
+    expect(isWalletUnlocked()).toBe(true)
+    lockWallet()
+    expect(isWalletUnlocked()).toBe(false)
+    lockWallet() // повторно — без ошибки
+    const err = await getWallet().then(() => null, e => e)
+    expect((err as AuthV2Error).code).toBe(AuthV2ErrorCode.WalletLocked)
+  }, 30000)
+})

components/auth/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipDefaultLibCheck": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*", "test/**/*"]
+}

components/auth/vitest.config.browser.ts

@@ -0,0 +1,19 @@
+/**
+ * Браузерный таргет cross-runtime smoke (Story 9.13): vitest browser mode,
+ * playwright + chromium headless. Гоняет ТОЛЬКО test/cross-runtime/** —
+ * остальные юнит-тесты пакета остаются Node-таргетом (`pnpm test`).
+ */
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['test/cross-runtime/**/*.test.ts'],
+    browser: {
+      enabled: true,
+      provider: 'playwright',
+      name: 'chromium',
+      headless: true,
+      screenshotFailures: false,
+    },
+  },
+})

components/blago-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coopenomics/blago-cli",
-  "version": "2026.5.23-4",
+  "version": "2026.6.9-18",
   "description": "CLI синхронизации артефактов Благорост с бэкендом через @coopenomics/sdk",
   "type": "module",
   "private": true,

components/blago-cli/src/cmd/run-cli.ts

@@ -362,9 +362,9 @@ export async function runCli(argv: string[]): Promise<void> {
     )
     .action(async (paths: string[]) => {
       const root = requireRoot()
-      const { stagedPaths, skippedUnchanged, skippedIgnored, skippedPullOnlyArtifacts } = await runAdd(root, paths)
+      const { stagedPaths, skippedUnchanged, skippedIgnored, skippedPullOnlyArtifacts, skippedNonEntity } = await runAdd(root, paths)
       success(
-        `Staging обновлён: в списке ${stagedPaths.length} путь(ей). Пропущено без изменений относительно индекса: ${skippedUnchanged}; по .blagoignore: ${skippedIgnored}; артефакты только pull (messages/ и meetings/): ${skippedPullOnlyArtifacts}.`,
+        `Staging обновлён: в списке ${stagedPaths.length} путь(ей). Пропущено без изменений относительно индекса: ${skippedUnchanged}; по .blagoignore: ${skippedIgnored}; артефакты только pull (messages/ и meetings/): ${skippedPullOnlyArtifacts}; не blago-сущности (нет type=project/issue/story во frontmatter): ${skippedNonEntity}.`,
       )
     })
 

components/blago-cli/src/format/index.ts

@@ -38,6 +38,22 @@ export function parseBlagoMarkdown(raw: string): ParsedBlagoFile {
   }
 }
 
+/** Не бросает: возвращает тип сущности blago, если файл — корректный project/issue/story; иначе undefined. */
+export function peekBlagoEntityType(raw: string): EntityFrontmatterType | undefined {
+  let file: ReturnType<typeof matter>
+  try {
+    file = matter(raw)
+  }
+  catch {
+    return undefined
+  }
+  const t = file.data?.type
+  if (t === 'project' || t === 'issue' || t === 'story') {
+    return t
+  }
+  return undefined
+}
+
 export function serializeBlagoMarkdown(data: Record<string, unknown>, body: string): string {
   const trimmed = body.endsWith('\n') ? body : `${body}\n`
   // matter.stringify(string, data) сначала парсит string как frontmatter — body, начинающийся

components/blago-cli/src/sync/add.ts

@@ -3,6 +3,7 @@
 import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
 
+import { peekBlagoEntityType } from '../format/index.js'
 import { sha256Hex } from '../lib/hash.js'
 import { expandBlagoUserTargetsToRelativePaths } from './capital-target-expand.js'
 import { isBlagoSyncExcludedDirName, isIgnoredRelativePath, loadBlagoIgnoreRules } from './ignore.js'
@@ -28,19 +29,39 @@ async function collectMarkdownFiles(absDir: string): Promise<string[]> {
   return out
 }
 
-/** true — файл стоит поставить в staging: нет в индексе или SHA256 на диске ≠ content_etag_local. */
-async function isDirtyVsIndex(root: string, rel: string, index: Awaited<ReturnType<typeof loadIndex>>): Promise<boolean> {
-  const entry = findByRelativePath(index, rel)
-  if (!entry) {
-    return true
-  }
+type FileCheck =
+  | { kind: 'unreadable' }
+  | { kind: 'non-entity' }
+  | { kind: 'clean' }
+  | { kind: 'dirty' }
+
+/**
+ * Решение по одному файлу для staging:
+ * — нечитаемый → dirty (push сам сообщит вменяемую ошибку),
+ * — без корректного frontmatter type → non-entity (README/notes/CLAUDE/AGENTS и пр. не отправляем),
+ * — есть в индексе и sha256 совпал → clean,
+ * — иначе dirty.
+ */
+async function classifyFileForAdd(
+  root: string,
+  rel: string,
+  index: Awaited<ReturnType<typeof loadIndex>>,
+): Promise<FileCheck> {
+  let raw: string
   try {
-    const raw = await fs.readFile(path.join(root, rel), 'utf8')
-    return sha256Hex(raw) !== entry.content_etag_local
+    raw = await fs.readFile(path.join(root, rel), 'utf8')
   }
   catch {
-    return true
+    return { kind: 'unreadable' }
   }
+  if (peekBlagoEntityType(raw) === undefined) {
+    return { kind: 'non-entity' }
+  }
+  const entry = findByRelativePath(index, rel)
+  if (!entry) {
+    return { kind: 'dirty' }
+  }
+  return sha256Hex(raw) === entry.content_etag_local ? { kind: 'clean' } : { kind: 'dirty' }
 }
 
 export interface RunAddResult {
@@ -50,6 +71,8 @@ export interface RunAddResult {
   skippedIgnored: number
   /** messages/ и meetings/ — только синхронизация с сервера, в push не идут */
   skippedPullOnlyArtifacts: number
+  /** Файлы без корректного blago-frontmatter (README, notes, CLAUDE/AGENTS и пр.) — в staging не попадают */
+  skippedNonEntity: number
 }
 
 export async function runAdd(root: string, targets: string[]): Promise<RunAddResult> {
@@ -65,6 +88,7 @@ export async function runAdd(root: string, targets: string[]): Promise<RunAddRes
   let skippedUnchanged = 0
   let skippedIgnored = 0
   let skippedPullOnlyArtifacts = 0
+  let skippedNonEntity = 0
 
   for (const t of expanded) {
     const abs = path.resolve(root, t)
@@ -86,7 +110,12 @@ export async function runAdd(root: string, targets: string[]): Promise<RunAddRes
         skippedPullOnlyArtifacts += 1
         continue
       }
-      if (!(await isDirtyVsIndex(root, rel, index))) {
+      const check = await classifyFileForAdd(root, rel, index)
+      if (check.kind === 'non-entity') {
+        skippedNonEntity += 1
+        continue
+      }
+      if (check.kind === 'clean') {
         skippedUnchanged += 1
         continue
       }
@@ -96,5 +125,5 @@ export async function runAdd(root: string, targets: string[]): Promise<RunAddRes
 
   const stagedPaths = [...set].sort()
   await saveStaging(root, { paths: stagedPaths })
-  return { stagedPaths, skippedUnchanged, skippedIgnored, skippedPullOnlyArtifacts }
+  return { stagedPaths, skippedUnchanged, skippedIgnored, skippedPullOnlyArtifacts, skippedNonEntity }
 }

components/blago-cli/src/sync/communication-cursors.ts

@@ -9,12 +9,15 @@ export interface CommunicationCursorsFile {
   messageLastTsByRoom: Record<string, number>
   /** project_hash → ISO instant: транскрипции с endedAt ≤ этого момента уже выгружены */
   transcriptionLastEndedExclusiveByProject: Record<string, string>
+  /** matrixRoomId → ISO instant: транскрипции непроектной комнаты с endedAt ≤ этого момента уже выгружены */
+  transcriptionLastEndedExclusiveByRoom: Record<string, string>
 }
 
 function empty(): CommunicationCursorsFile {
   return {
     messageLastTsByRoom: {},
     transcriptionLastEndedExclusiveByProject: {},
+    transcriptionLastEndedExclusiveByRoom: {},
   }
 }
 
@@ -32,6 +35,11 @@ export async function loadCommunicationCursors(root: string): Promise<Communicat
         && typeof parsed.transcriptionLastEndedExclusiveByProject === 'object'
           ? { ...parsed.transcriptionLastEndedExclusiveByProject }
           : {},
+      transcriptionLastEndedExclusiveByRoom:
+        parsed.transcriptionLastEndedExclusiveByRoom !== undefined
+        && typeof parsed.transcriptionLastEndedExclusiveByRoom === 'object'
+          ? { ...parsed.transcriptionLastEndedExclusiveByRoom }
+          : {},
     }
   }
   catch {

components/blago-cli/src/sync/communication-markdown.ts

@@ -43,7 +43,6 @@ export function projectCommunicationDayToMarkdown(
 }
 
 export interface TranscriptionHeaderModel {
-  matrixRoomId: string
   roomId: string
   startedAt: Date | string
   endedAt: Date | string | null | undefined
@@ -71,7 +70,6 @@ export function renderCallTranscriptionMarkdown(
   const header = [
     `# Транскрипция звонка`,
     ``,
-    `- Matrix room: \`${transcription.matrixRoomId}\``,
     `- LiveKit room: \`${transcription.roomId}\``,
     `- Начало: ${start.toISOString()}`,
     `- Окончание: ${end ? end.toISOString() : '—'}`,

components/blago-cli/src/sync/pull-communication.ts

@@ -25,7 +25,7 @@ import {
   transcriptionMeetingFileStemUtc,
   type CommunicationDayLine,
 } from './communication-markdown.js'
-import { workspaceBasePath, type ProjectPathModel } from './layout.js'
+import { generateSlug, workspaceBasePath, type ProjectPathModel } from './layout.js'
 import { syncEntityFile } from './sync-entity-file.js'
 
 interface ProjectRowLite {
@@ -183,6 +183,19 @@ async function listRooms(ctx: AuthenticatedContext, projectHash: string) {
   return q[Queries.ChatCoop.ListProjectCommunicationRooms.name] ?? []
 }
 
+/** Стабильная папка непроектной комнаты в `rooms/`. Системные — фиксированные, комнаты секретаря — slug + хвост id (уникальность). */
+function nonProjectRoomFolder(kind: string, matrixRoomId: string, displayLabel: string): string {
+  if (kind === 'MEMBERS') {
+    return 'komnata-paishchikov'
+  }
+  if (kind === 'COUNCIL') {
+    return 'komnata-soveta'
+  }
+  const slug = generateSlug(displayLabel) || 'komnata'
+  const shortId = createHash('sha256').update(matrixRoomId, 'utf8').digest('hex').slice(0, 6)
+  return `${slug}-${shortId}`
+}
+
 export async function pullProjectCommunicationArtifacts(
   ctx: AuthenticatedContext,
   index: IndexFile,
@@ -198,6 +211,7 @@ export async function pullProjectCommunicationArtifacts(
     cursors = {
       messageLastTsByRoom: {},
       transcriptionLastEndedExclusiveByProject: {},
+      transcriptionLastEndedExclusiveByRoom: {},
     }
   }
 
@@ -356,7 +370,6 @@ export async function pullProjectCommunicationArtifacts(
           = dateFromUnknown(tr.endedAt) ?? (tr.endedAt as Date | string | null | undefined)
         const md = renderCallTranscriptionMarkdown(
           {
-            matrixRoomId: String(tr.matrixRoomId),
             roomId: String(tr.roomId),
             startedAt,
             endedAt: endedAtTr,
@@ -422,3 +435,207 @@ export async function pullProjectCommunicationArtifacts(
     warn(`Не удалось сохранить курсоры переписки: ${formatThrownValue(e)}`)
   }
 }
+
+/**
+ * Pull переписки и транскрипций из комнат ВНЕ проектов Capital (пайщики, совет, комнаты секретаря).
+ * Раскладка — отдельная верхняя папка `rooms/<folder>/{messages,meetings}/`, чтобы не смешивать с
+ * проектными `meetings/`. Логика идентична проектной, но bucket = одна комната, курсор транскрипций — по matrixRoomId.
+ */
+export async function pullNonProjectCommunicationArtifacts(
+  ctx: AuthenticatedContext,
+  index: IndexFile,
+): Promise<void> {
+  let rooms: { matrixRoomId: string, displayLabel: string, kind: string }[]
+  try {
+    const q = await ctx.client.Query(Queries.ChatCoop.ListNonProjectCommunicationRooms.query, {})
+    rooms = (q[Queries.ChatCoop.ListNonProjectCommunicationRooms.name] ?? []) as typeof rooms
+  }
+  catch (e) {
+    warn(`Список непроектных комнат (chatcoopListNonProjectCommunicationRooms): ${formatThrownValue(e)}`)
+    return
+  }
+  if (rooms.length === 0) {
+    return
+  }
+
+  let cursors: CommunicationCursorsFile
+  try {
+    cursors = await loadCommunicationCursors(ctx.root)
+  }
+  catch (e) {
+    warn(`Курсоры переписки (комнаты): не удалось прочитать, начинаем с пустых: ${formatThrownValue(e)}`)
+    cursors = {
+      messageLastTsByRoom: {},
+      transcriptionLastEndedExclusiveByProject: {},
+      transcriptionLastEndedExclusiveByRoom: {},
+    }
+  }
+
+  for (const room of rooms) {
+    const folder = nonProjectRoomFolder(room.kind, room.matrixRoomId, room.displayLabel)
+    const basePath = `rooms/${folder}`
+    const roomTitle = room.displayLabel || room.matrixRoomId
+
+    // Сообщения комнаты — по календарным суткам UTC новее курсора.
+    try {
+      const last = cursors.messageLastTsByRoom[room.matrixRoomId]
+      const afterTs = last ?? 0
+      const datesQ = await ctx.client.Query(Queries.ChatCoop.ListUtcDatesWithNewRoomMessages.query, {
+        variables: { data: { matrixRoomId: room.matrixRoomId, afterOriginServerTsExclusive: afterTs } },
+      })
+      const dates = (datesQ[Queries.ChatCoop.ListUtcDatesWithNewRoomMessages.name] ?? []).sort()
+      for (const utcDate of dates) {
+        const mq = await ctx.client.Query(Queries.ChatCoop.GetRoomMessagesForUtcDate.query, {
+          variables: { data: { matrixRoomId: room.matrixRoomId, utcDate } },
+        })
+        const linesRaw = mq[Queries.ChatCoop.GetRoomMessagesForUtcDate.name] ?? []
+        const lines: CommunicationDayLine[] = linesRaw.map(m => ({
+          originServerTs: m.originServerTs,
+          authorLabel: m.authorLabel,
+          coopUsername: m.coopUsername,
+          kind: String(m.kind),
+          bodyText: m.bodyText,
+        }))
+        if (lines.length === 0) {
+          continue
+        }
+        const content = projectCommunicationDayToMarkdown(roomTitle, room.matrixRoomId, utcDate, [
+          { displayLabel: room.displayLabel, matrixRoomId: room.matrixRoomId, lines },
+        ])
+        const rel = `${basePath}/messages/${utcDate}.md`
+        const entityHash = messageDayEntityHash(room.matrixRoomId, utcDate)
+        await syncEntityFile({
+          root: ctx.root,
+          index,
+          entityType: 'room_message_day',
+          entityHash,
+          relativePath: rel,
+          content,
+          remoteUpdatedAt: `${utcDate}T23:59:59.999Z`,
+          label: `переписка ${utcDate} (${room.matrixRoomId})`,
+        })
+      }
+
+      const maxQ = await ctx.client.Query(Queries.ChatCoop.GetMaxOriginServerTsForRoom.query, {
+        variables: { data: { matrixRoomId: room.matrixRoomId } },
+      })
+      const maxTs = maxQ[Queries.ChatCoop.GetMaxOriginServerTsForRoom.name] as number | null | undefined
+      if (maxTs !== undefined && maxTs !== null && Number.isFinite(maxTs)) {
+        cursors.messageLastTsByRoom[room.matrixRoomId] = maxTs
+      }
+    }
+    catch (e) {
+      warn(`Переписка Matrix, комната ${room.matrixRoomId} (${roomTitle}): ${formatThrownValue(e)}`)
+    }
+
+    // Транскрипции звонков комнаты + sibling memo.
+    try {
+      const tExIso = cursors.transcriptionLastEndedExclusiveByRoom[room.matrixRoomId]
+      const lowerBoundExclusive = tExIso === undefined ? new Date(0) : new Date(tExIso)
+
+      interface TranscriptionCandidate {
+        id: string
+        endedAt: Date
+        memo: string
+        updatedAt: Date | undefined
+      }
+      const byId = new Map<string, TranscriptionCandidate>()
+      const tq = await ctx.client.Query(Queries.ChatCoop.GetTranscriptions.query, {
+        variables: { data: { matrixRoomId: room.matrixRoomId, limit: CHATCOOP_TRANSCRIPTIONS_QUERY_LIMIT, offset: 0 } },
+      })
+      const list = tq[Queries.ChatCoop.GetTranscriptions.name] ?? []
+      for (const t of list) {
+        const end = dateFromUnknown(t.endedAt)
+        if (t.status !== Zeus.TranscriptionStatus.COMPLETED || !end) {
+          continue
+        }
+        const prev = byId.get(t.id)
+        if (!prev || end > prev.endedAt) {
+          byId.set(t.id, {
+            id: t.id,
+            endedAt: end,
+            memo: typeof t.memo === 'string' ? t.memo : '',
+            updatedAt: dateFromUnknown(t.updatedAt),
+          })
+        }
+      }
+      const allCompleted = [...byId.values()].sort((a, b) => a.endedAt.getTime() - b.endedAt.getTime())
+
+      const newMeetings = allCompleted.filter(c => c.endedAt.getTime() > lowerBoundExclusive.getTime())
+      let maxEnded: Date | null = null
+      for (const c of newMeetings) {
+        const packQ = await ctx.client.Query(Queries.ChatCoop.GetTranscription.query, {
+          variables: { data: { id: c.id } },
+        })
+        const pack = packQ[Queries.ChatCoop.GetTranscription.name]
+        if (!pack?.transcription || pack.transcription.status !== Zeus.TranscriptionStatus.COMPLETED) {
+          continue
+        }
+        const tr = pack.transcription
+        const startedAt: Date | string = dateFromUnknown(tr.startedAt) ?? (tr.startedAt as Date | string)
+        const endedAtTr: Date | string | null | undefined
+          = dateFromUnknown(tr.endedAt) ?? (tr.endedAt as Date | string | null | undefined)
+        const md = renderCallTranscriptionMarkdown(
+          {
+            roomId: String(tr.roomId),
+            startedAt,
+            endedAt: endedAtTr,
+          },
+          pack.segments.map(s => ({
+            speakerName: s.speakerName,
+            text: s.text,
+            startOffset: s.startOffset,
+            endOffset: s.endOffset,
+          })),
+        )
+        const stem = transcriptionMeetingFileStemUtc(c.endedAt)
+        const rel = `${basePath}/meetings/${stem}.md`
+        const entityHash = c.id.toLowerCase()
+        await syncEntityFile({
+          root: ctx.root,
+          index,
+          entityType: 'call_transcription',
+          entityHash,
+          relativePath: rel,
+          content: md,
+          remoteUpdatedAt: toUpdatedIso(c.endedAt),
+          label: `транскрипция ${c.id}`,
+        })
+        if (!maxEnded || c.endedAt > maxEnded) {
+          maxEnded = c.endedAt
+        }
+      }
+
+      for (const c of allCompleted) {
+        const stem = transcriptionMeetingFileStemUtc(c.endedAt)
+        const memoRel = `${basePath}/meetings/${stem}.memo.md`
+        const memoRemoteUpdatedAt = toUpdatedIso(c.updatedAt ?? c.endedAt)
+        await syncTranscriptionMemoFile({
+          root: ctx.root,
+          index,
+          transcriptionId: c.id,
+          relativePath: memoRel,
+          serverMemo: c.memo,
+          remoteUpdatedAtIso: memoRemoteUpdatedAt,
+        })
+      }
+
+      if (maxEnded) {
+        cursors.transcriptionLastEndedExclusiveByRoom[room.matrixRoomId] = maxEnded.toISOString()
+      }
+      else if (tExIso === undefined) {
+        cursors.transcriptionLastEndedExclusiveByRoom[room.matrixRoomId] = new Date().toISOString()
+      }
+    }
+    catch (e) {
+      warn(`Транскрипции звонков, комната ${room.matrixRoomId}: ${formatThrownValue(e)}`)
+    }
+  }
+
+  try {
+    await saveCommunicationCursors(ctx.root, cursors)
+  }
+  catch (e) {
+    warn(`Не удалось сохранить курсоры переписки (комнаты): ${formatThrownValue(e)}`)
+  }
+}

components/blago-cli/src/sync/pull.ts

@@ -28,7 +28,7 @@ import {
   storyFileRelativePath,
   workspaceBasePath,
 } from './layout.js'
-import { pullProjectCommunicationArtifacts } from './pull-communication.js'
+import { pullNonProjectCommunicationArtifacts, pullProjectCommunicationArtifacts } from './pull-communication.js'
 import { scaffoldBmadWorkspacesAfterPull } from './scaffold-bmad-workspace.js'
 import { syncEntityFile } from './sync-entity-file.js'
 import { writeWorkspaceIndexMarkdown } from './workspace-index.js'
@@ -329,6 +329,8 @@ export async function runPull(ctx: AuthenticatedContext, options: RunPullOptions
 
   await pullProjectCommunicationArtifacts(ctx, index, allProjects, projectByHash)
 
+  await pullNonProjectCommunicationArtifacts(ctx, index)
+
   await scaffoldBmadWorkspacesAfterPull(ctx, allProjects, projectByHash)
 
   await saveIndex(ctx.root, index)

components/blago-cli/src/sync/push.ts

@@ -6,7 +6,7 @@ import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
 
 import { Mutations, Queries } from '@coopenomics/sdk'
-import { parseBlagoMarkdown } from '../format/index.js'
+import { parseBlagoMarkdown, peekBlagoEntityType } from '../format/index.js'
 import { sha256Hex } from '../lib/hash.js'
 import { effectiveParentHash } from '../lib/parent-hash.js'
 import { warn } from '../ui/output.js'
@@ -58,6 +58,30 @@ export async function runPush(ctx: AuthenticatedContext): Promise<void> {
     }
     staging = await loadStaging(ctx.root)
   }
+  // Не-сущности (README/notes/CLAUDE/AGENTS и пр., в .md без type=project|issue|story) тоже не должны валить весь push.
+  // Чистим их автоматически — иначе одна забытая заметка блокирует отправку реальных правок.
+  const stagingAbs = (p: string): string => path.join(ctx.root, normalizeRelativePath(p))
+  const nonEntityInStaging: string[] = []
+  for (const p of staging.paths) {
+    try {
+      const raw = await fs.readFile(stagingAbs(p), 'utf8')
+      if (peekBlagoEntityType(raw) === undefined) {
+        nonEntityInStaging.push(normalizeRelativePath(p))
+      }
+    }
+    catch {
+      // нечитаемый файл — пусть основной цикл бросит понятную ошибку с путём
+    }
+  }
+  if (nonEntityInStaging.length > 0) {
+    const drop = new Set(nonEntityInStaging)
+    const kept = staging.paths.filter(p => !drop.has(normalizeRelativePath(p)))
+    await saveStaging(ctx.root, { paths: [...new Set(kept.map(p => normalizeRelativePath(p)))].sort() })
+    for (const p of nonEntityInStaging) {
+      warn(`Убрано из staging (нет blago-frontmatter type=project|issue|story): ${p}`)
+    }
+    staging = await loadStaging(ctx.root)
+  }
   if (staging.paths.length === 0) {
     throw new Error('Нечего отправлять. Добавьте файлы: blago add <путь | id проекта | projectId-issueId>')
   }
@@ -75,8 +99,24 @@ export async function runPush(ctx: AuthenticatedContext): Promise<void> {
     }
     const abs = path.join(ctx.root, n)
     const raw = await fs.readFile(abs, 'utf8')
-    const parsed = parseBlagoMarkdown(raw)
-    const { type, hash } = validateParsedForPush(parsed)
+    let parsed: ReturnType<typeof parseBlagoMarkdown>
+    try {
+      parsed = parseBlagoMarkdown(raw)
+    }
+    catch (err) {
+      // Без префикса путём из staging вылезает «type: undefined» без указания файла.
+      const msg = err instanceof Error ? err.message : String(err)
+      throw new Error(`Файл «${n}»: ${msg}`)
+    }
+    let type: ReturnType<typeof validateParsedForPush>['type']
+    let hash: string
+    try {
+      ({ type, hash } = validateParsedForPush(parsed))
+    }
+    catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      throw new Error(`Файл «${n}»: ${msg}`)
+    }
     const entry = findByHash(index, type, hash)
     const pKind = pendingKindForEntityType(type)
     const pending = pKind ? await findPendingForParsed(ctx.root, pKind, hash) : undefined

components/blago-cli/src/sync/restore.ts

@@ -367,7 +367,6 @@ export async function runRestore(ctx: AuthenticatedContext, userPath: string): P
   if (entry.entity_type === 'call_transcription') {
     interface TranscriptionRestorePack {
       transcription: {
-        matrixRoomId: string
         roomId: string
         startedAt: Date | string
         endedAt: Date | string | null | undefined
@@ -394,7 +393,6 @@ export async function runRestore(ctx: AuthenticatedContext, userPath: string): P
     }
     const content = renderCallTranscriptionMarkdown(
       {
-        matrixRoomId: tr.matrixRoomId,
         roomId: tr.roomId,
         startedAt: tr.startedAt,
         endedAt: tr.endedAt,

components/boot/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coopenomics/boot",
   "type": "module",
-  "version": "2026.5.23-4",
+  "version": "2026.6.9-18",
   "private": true,
   "packageManager": "pnpm@9.0.6",
   "description": "CLI-утилита инициализации блокчейна и кооператива",
@@ -26,6 +26,7 @@
     "boot:remote": "esno src/index.ts boot:remote",
     "reboot:clean": "cd components/boot/scripts && bash clean_reboot.sh",
     "reboot:extra": "cd components/boot/scripts && bash extra_reboot.sh",
+    "reboot:blago": "cd components/boot/scripts && bash blago_reboot.sh",
     "create-coop": "esno src/index.ts create-coop",
     "clear": "./scripts/clear.sh",
     "start": "./scripts/restart.sh",

components/boot/scripts/blago_reboot.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+
+# Полный перезапуск dev-среды для теста Благороста одной командой:
+#   1) extra_reboot.sh — чистая цепь + кооператив + совет 5 человек +
+#      dev-shortcut онбординга capital (extensions.capital: все *_done=true);
+#   2) ожидание готовности controller (GraphQL отвечает);
+#   3) seed-capital до фазы $SEED_UP_TO (default 04-contributor): программы
+#      УХД/Благорост + setconfig, проекты, регистрация ant как участника.
+#
+# Глубину сида можно менять: SEED_UP_TO=08-investments pnpm run reboot:blago
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+if [ -f "$ROOT_DIR/.env" ]; then
+  set -a
+  # shellcheck disable=SC1091
+  source "$ROOT_DIR/.env"
+  set +a
+fi
+
+bash "$SCRIPT_DIR/extra_reboot.sh"
+
+# Per-instance адрес controller'а — из корневого .env (API_URL); coopback после
+# force-recreate поднимается десятки секунд, seed-фазы без него падают.
+GRAPHQL_URL="${API_URL:-http://127.0.0.1:2998/v1/graphql}"
+echo "Ждём готовности controller ($GRAPHQL_URL)..."
+until curl -s --max-time 3 -o /dev/null -X POST -H 'Content-Type: application/json' \
+  --data '{"query":"{__typename}"}' "$GRAPHQL_URL"; do
+  sleep 3
+done
+echo "Controller готов."
+
+UP_TO="${SEED_UP_TO:-04-contributor}"
+echo "Сидируем capital до фазы $UP_TO..."
+cd "$SCRIPT_DIR/.."
+CONTROLLER_GRAPHQL_URL="$GRAPHQL_URL" pnpm exec esno src/scripts/seed-capital/index.ts --up-to="$UP_TO"
+
+echo "Готово: среда Благорост поднята (seed до $UP_TO)."

components/boot/scripts/clean_reboot.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Загружаем per-instance конфиг из корня репо.
+# Загружаем per-instance конфиг из корня репо (для CHAIN_URL/MONGODB_URL/API_URL,
+# которые читают TS-код boot и шелл-скрипты networks.sh/preactivate.sh).
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
 if [ -f "$ROOT_DIR/.env" ]; then
   set -a
@@ -9,26 +10,34 @@ if [ -f "$ROOT_DIR/.env" ]; then
   set +a
 fi
 
-# Останавливаем и удаляем контейнеры вместе с volumes
-echo "Останавливаем и удаляем контейнеры с volumes..."
-docker compose down -v mongo postgres cooparser || true
+# Останавливаем и удаляем контейнеры (сеть НЕ трогаем — к ней может быть
+# подключён внешний контейнер вроде provider-backend; down её снёс бы с ошибкой).
+echo "Останавливаем и удаляем контейнеры..."
+docker compose rm -fsv mongo postgres monoredis cooparser coopback || true
 
 # Останавливаем blockchain контейнер перед удалением данных
 echo "Останавливаем blockchain контейнер..."
 docker compose stop node || true
 
-# Удаляем blockchain data
+# Удаляем тома баз данных для чистого старта (named volumes rm -v не чистит)
+echo "Удаляем тома баз данных..."
+PROJECT="${COMPOSE_PROJECT_NAME:-$(basename "$ROOT_DIR")}"
+docker volume rm "${PROJECT}_postgres_data" "${PROJECT}_mongo_data" 2>/dev/null || true
+
+# Удаляем blockchain data через контейнер (alpine под root стирает данные
+# независимо от владельца — без sudo на любой ноде; на проде nodeos пишет под root).
 echo "Удаляем blockchain data..."
-# sudo chmod -R 755 ../blockchain-data/ 2>/dev/null || true
-sudo rm -rf ../blockchain-data/
+docker run --rm -v "$(cd .. && pwd)/blockchain-data:/d" alpine sh -c 'rm -rf /d/* /d/.[!.]* 2>/dev/null || true'
 
-# Пересоздаем и запускаем базы данных
+# Пересоздаем и запускаем базы данных + Redis (monoredis).
+# monoredis ОБЯЗАТЕЛЕН: без него coopback падает на старте с
+# `getaddrinfo EAI_AGAIN monoredis` → MaxRetriesPerRequestError → nodemon crash.
 echo "Пересоздаем и запускаем базы данных..."
-docker compose up -d mongo postgres
+docker compose up -d mongo postgres monoredis
 
-# Ждем готовности MongoDB
+# Ждем готовности MongoDB (standalone, ping вместо ожидания PRIMARY).
 echo "Ждем готовности MongoDB..."
-until docker compose exec -T mongo mongosh --eval "db.adminCommand('ping')" --quiet > /dev/null 2>&1; do
+until docker compose exec -T mongo mongosh --quiet --eval "db.adminCommand({ping:1}).ok" > /dev/null 2>&1; do
   echo "MongoDB еще не готов, ждем..."
   sleep 2
 done
@@ -42,7 +51,7 @@ until docker compose exec -T postgres pg_isready -U postgres -d voskhod > /dev/n
 done
 echo "PostgreSQL готов!"
 
-# Запускаем boot процесс
+# Запускаем boot процесс (clean: только программы Благорост/маркетплейс)
 echo "Запускаем boot процесс..."
 pnpm run boot:clean
 
@@ -51,6 +60,6 @@ echo "Запускаем parser..."
 docker compose up -d cooparser
 
 echo "Запускаем контроллер..."
-docker compose restart coopback || true
+docker compose up -d --force-recreate coopback || true
 
 echo "Перезапуск завершен!"

components/boot/scripts/extra_reboot.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Загружаем per-instance конфиг из корня репо.
+# Загружаем per-instance конфиг из корня репо (для CHAIN_URL/MONGODB_URL/API_URL,
+# которые читают TS-код boot и шелл-скрипты networks.sh/preactivate.sh).
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
 if [ -f "$ROOT_DIR/.env" ]; then
   set -a
@@ -9,30 +10,32 @@ if [ -f "$ROOT_DIR/.env" ]; then
   set +a
 fi
 
-# Останавливаем контроллер перед очисткой данных
-echo "Останавливаем контроллер..."
-docker compose down coopback || true
-
 # Останавливаем и удаляем контейнеры вместе с volumes
 echo "Останавливаем и удаляем контейнеры с volumes..."
-docker compose down -v mongo postgres cooparser || true
+docker compose down -v mongo postgres monoredis cooparser coopback || true
 
 # Останавливаем blockchain контейнер перед удалением данных
 echo "Останавливаем blockchain контейнер..."
 docker compose stop node || true
 
-# Удаляем blockchain data
+# Удаляем blockchain data.
+# Контейнерный wipe (alpine под root) стирает данные независимо от их владельца —
+# без sudo на любой ноде (на Pi нет passwordless sudo; на проде nodeos пишет
+# данные под root). Единый способ с reboot.sh / clean_reboot.sh.
 echo "Удаляем blockchain data..."
 # sudo chmod -R 755 ../blockchain-data/ 2>/dev/null || true
-sudo rm -rf ../blockchain-data/
+docker run --rm -v "$(cd .. && pwd)/blockchain-data:/d" alpine sh -c 'rm -rf /d/* /d/.[!.]* 2>/dev/null || true'
 
-# Пересоздаем и запускаем базы данных
+# Пересоздаем и запускаем базы данных + Redis (monoredis).
+# monoredis ОБЯЗАТЕЛЕН: без него coopback падает на старте с
+# `getaddrinfo EAI_AGAIN monoredis` → MaxRetriesPerRequestError → nodemon crash,
+# и провайдер не может взять org-данные partner1 (PROVIDER_URL=coopback:2998).
 echo "Пересоздаем и запускаем базы данных..."
-docker compose up -d mongo postgres
+docker compose up -d mongo postgres monoredis
 
-# Ждем готовности MongoDB
+# Ждем готовности MongoDB (standalone, ping вместо ожидания PRIMARY).
 echo "Ждем готовности MongoDB..."
-until docker compose exec -T mongo mongosh --eval "db.adminCommand('ping')" --quiet > /dev/null 2>&1; do
+until docker compose exec -T mongo mongosh --quiet --eval "db.adminCommand({ping:1}).ok" > /dev/null 2>&1; do
   echo "MongoDB еще не готов, ждем..."
   sleep 2
 done
@@ -46,7 +49,7 @@ until docker compose exec -T postgres pg_isready -U postgres -d voskhod > /dev/n
 done
 echo "PostgreSQL готов!"
 
-# Запускаем boot процесс
+# Запускаем boot процесс (расширенный: совет + пайщики; partner1 — при EXTRA_RENT=1)
 echo "Запускаем boot процесс..."
 pnpm run boot:extra
 
@@ -55,6 +58,6 @@ echo "Запускаем parser..."
 docker compose up -d cooparser
 
 echo "Запускаем контроллер..."
-docker compose up -d coopback
+docker compose up -d --force-recreate coopback || true
 
 echo "Перезапуск завершен!"

components/boot/src/blockchain/index.ts

@@ -291,31 +291,46 @@ export default class Blockchain {
   async activateFeature(feature: Feature) {
     await this.update_pass_instance()
 
-    await this.api.transact(
-      {
-        actions: [
-          {
-            account: 'eosio',
-            name: 'activate',
-            authorization: [
-              {
-                actor: 'eosio',
-                permission: 'active',
+    try {
+      await this.api.transact(
+        {
+          actions: [
+            {
+              account: 'eosio',
+              name: 'activate',
+              authorization: [
+                {
+                  actor: 'eosio',
+                  permission: 'active',
+                },
+              ],
+              data: {
+                feature_digest: feature.hash,
               },
-            ],
-            data: {
-              feature_digest: feature.hash,
             },
-          },
-        ],
-      },
-      {
-        blocksBehind: 3,
-        expireSeconds: 30,
-      },
-    )
+          ],
+        },
+        {
+          blocksBehind: 3,
+          expireSeconds: 30,
+        },
+      )
 
-    console.log('Фича активирована: ', feature.name)
+      console.log('Фича активирована: ', feature.name)
+    }
+    catch (e: any) {
+      // На уже забутстрапленном (не обнулённом) чейне протокол-фича уже активна —
+      // nodeos отдаёт protocol_feature_exception (code 3250000). Это не повод
+      // ронять весь boot: фича на месте, нужный результат достигнут, продолжаем.
+      const errName = e?.json?.error?.name
+      const errCode = e?.json?.error?.code
+      const msg = e instanceof Error ? e.message : String(e)
+      if (errName === 'protocol_feature_exception' || errCode === 3250000 || /already activated/i.test(msg)) {
+        console.warn(`Фича уже активирована, пропускаю: ${feature.name}`)
+        return
+      }
+      throw e
+    }
   }
 
   async createToken(params: TokenContract.Interfaces.ICreate) {

components/boot/src/configs/contracts.ts

@@ -128,4 +128,9 @@ export default [
     path: path.join(userBase, 'apps'),
     target: 'apps',
   },
+  {
+    name: 'expense',
+    path: path.join(userBase, 'expense'),
+    target: 'expense',
+  },
 ]

components/boot/src/configs/index.ts

@@ -154,6 +154,10 @@ export default {
       name: 'apps',
       code_permissions_to: ['apps'],
     },
+    {
+      name: 'expense',
+      code_permissions_to: ['expense'],
+    },
     // {
     //   name: provider_chairman,
     // },

components/boot/src/configs/protocol_features/BUILTIN-ASSERT_RECOVER_KEY_ACCOUNT.json

@@ -0,0 +1,11 @@
+{
+  "protocol_feature_type": "builtin",
+  "dependencies": [],
+  "description_digest": "2ad6b7aabba8edbc87b46f3340df4d0db0e4b65474db3e1cd5db33fb685a506b",
+  "subjective_restrictions": {
+    "earliest_allowed_activation_time": "1970-01-01T00:00:00.000",
+    "preactivation_required": true,
+    "enabled": true
+  },
+  "builtin_feature_codename": "ASSERT_RECOVER_KEY_ACCOUNT"
+}

components/boot/src/configs/protocol_features/BUILTIN-SAVANNA.json

@@ -0,0 +1,33 @@
+{
+  "protocol_feature_type": "builtin",
+  "dependencies": [
+    "09e86cb0accf8d81c9e85d34bea4b925ae936626d00c984e4691186891f5bc16",
+    "1a99a59d87e06e09ec5b028a9cbb7749b4a5ad8819004365d02dc4379a8b7241",
+    "2652f5f96006294109b3dd0bbde63693f55324af452b799ee137a81a905eed25",
+    "299dcb6af692324b899b39f16d5a530a33062804e41f09dc97e9f156b4476707",
+    "35c2186cc36f7bb4aeaf4487b36e57039ccf45a9136aa856a5d569ecca55ef2b",
+    "4a90c00d55454dc5b059055ca213579c6ea856967712a56017487886a4d4cc0f",
+    "4e7bf348da00a945489b2a681749eb56f5de00b900014e137ddae39f48f69d67",
+    "4fca8bd82bbd181e714e283f83e1b45d95ca5af40fb89ad3977b653c448f78c2",
+    "5443fcf88330c586bc0e5f3dee10e7f63c76c00249c87fe4fbf7f38c082006b4",
+    "63320dd4a58212e4d32d1f58926b73ca33a247326c2a5e9fd39268d2384e011a",
+    "68dcaa34c0517d19666e6b33add67351d8c5f69e999ca1e37931bc410a297428",
+    "6bcb40a24e49c26d0a60513b6aeb8551d264e4717f306b81a37a5afb3b47cedc",
+    "8ba52fe7a3956c5cd3a656a3174b931d3bb2abb45578befc59f283ecd816a405",
+    "ad9e3d8f650687709fd68f4b90b41f7d825a365b02c23a636cef88ac2ac00c43",
+    "bcd2a26394b36614fd4894241d3c451ab0f6fd110958c3423073621a70826e99",
+    "c3a6138c5061cf291310887c0b5c71fcaffeab90d5deb50d3b9e687cead45071",
+    "d528b9f6e9693f45ed277af93474fd473ce7d831dae2180cca35d907bd10cb40",
+    "e0fb64b1085cc5538970158d05a009c24e276fb94e1a0bf6a528b48fbc4ff526",
+    "ef43112c6543b88db2283a2e077278c315ae2c84719a8b25f25cc88565fbea99",
+    "f0af56d2c5a48d60a4a5b5c903edfb7db3a736a94ed589d0b797df33ff9d3e1d",
+    "fce57d2331667353a0eac6b4209b67b843a7262a848af0a49a6e2fa9f6584eb4"
+  ],
+  "description_digest": "01a8bebb4922c38293a8909668f7d00ba4a21a455c69719ad7dcc33ea1e631c0",
+  "subjective_restrictions": {
+    "earliest_allowed_activation_time": "1970-01-01T00:00:00.000",
+    "preactivation_required": true,
+    "enabled": true
+  },
+  "builtin_feature_codename": "SAVANNA"
+}

components/boot/src/init/booter.ts

@@ -1,7 +1,6 @@
-import config from '../configs'
 import { initExtensionsInPostgres, initSystemStatus } from '../postgres-init'
 import { installExtraData, installInitialData, startInfra } from './infra'
-import { CooperativeClass, startCoop } from './cooperative'
+import { startCoop } from './cooperative'
 
 export async function boot() {
   const blockchain = await startInfra()
@@ -14,18 +13,29 @@ export async function boot() {
 }
 
 export async function bootClean() {
-  const blockchain = await startInfra()
-
-  console.log('Создаём программы (Благорост и маркетплейс)')
-
-  const cooperative = new CooperativeClass(blockchain)
-  await cooperative.createPrograms(config.provider)
+  // Только инфраструктура: контракты, фичи, токен, системные параметры.
+  // Ни совета, ни программ — программы (createPrograms) требуют существующий
+  // совет и создаются в boot/bootExtra внутри installInitialData. В clean их
+  // не делаем (иначе soviet::createprog падает с «Совет не найден»).
+  await startInfra()
 }
 
 export async function bootExtra() {
   const blockchain = await startInfra()
   await installInitialData(blockchain, true) // Создать расширенный совет (устанавливает статус 'active' в MongoDB)
-  await installExtraData(blockchain) // Добавить дополнительных пайщиков
+
+  // installExtraData регистрирует partner1 как coop с auto-approve от провайдера —
+  // это и есть программная on-chain активация, которая триггерит аренду VM в
+  // провайдере (PENDING→RENT). boot:extra используется НЕ только для аренды
+  // сервера (например, просто пересев совета/чейна для других задач), поэтому
+  // провижининг partner1 включается ТОЛЬКО под флагом EXTRA_RENT=1.
+  if (process.env.EXTRA_RENT === '1') {
+    console.log('EXTRA_RENT=1 → installExtraData: провижининг partner1 (триггер аренды)')
+    await installExtraData(blockchain) // Регистрируем partner1 как coop (active)
+  }
+  else {
+    console.log('EXTRA_RENT не задан → пропускаем провижининг partner1 (аренда не запускается)')
+  }
 
   console.log('Инициализируем статус системы в PostgreSQL')
   await initSystemStatus() // Устанавливает статус 'active' в PostgreSQL

components/boot/src/init/infra.ts

@@ -15,6 +15,9 @@ import { sleep } from '../utils'
 import { generateRandomSHA256 } from '../utils/randomHash'
 import { initUsersInPostgres, initVaultInPostgres } from '../postgres-init'
 import { CooperativeClass } from './cooperative'
+import { signProgramAgreement } from './sign-program-agreement'
+import { fakeDocument } from '../tests/shared/fakeDocument'
+import { walletDraftId, walletProgramId } from '../tests/capital/consts'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -674,10 +677,17 @@ export async function installExtraData(blockchain: Blockchain) {
     status: 'active',
   })
 
-  // Ресурсы для партнёра: powerup CPU/NET. transfer токенов пропускаем —
-  // eosio.token::transfer падает на проверке membership в wallet program,
-  // которая для partner1 не настроена. Для provider sync + Hostkey-flow
-  // токены не нужны: tx от имени partner1 пойдут от soviet/admin.
+  // Записываем partner1 в ЦПП Кошелька оператора (voskhod, program_id=1).
+  // БЕЗ этого провайдерский performInitialTransfers (150 AXON на partner1 ДО
+  // перехода в ACTIVE, см. provider CLAUDE.md §13) падает ассертом
+  // eosio.token::is_can_transfer «Получатель не является участником целевой
+  // потребительской программы кошелька» — и инстанс навсегда застревает в
+  // INSTALL. wallet::signagree (auth voskhod@active) делает partner1 членом
+  // ЦПП Кошелька. Та же механика, что для обычных пайщиков в participant.ts.
+  console.log('Подписываем wallet-соглашение за partner1 (членство в ЦПП Кошелька)')
+  await signProgramAgreement(blockchain, config.provider, account.username, walletProgramId, walletDraftId, fakeDocument)
+
+  // Ресурсы для партнёра: powerup CPU/NET.
   await blockchain.powerup({
     payer: 'eosio',
     receiver: account.username,

components/cleos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coopenomics/cleos",
-  "version": "2026.5.23-4",
+  "version": "2026.6.9-18",
   "private": true,
   "description": "Обёртка над кошельком cleos для EOSIO блокчейна",
   "scripts": {

components/contracts/CMakeLists.txt

@@ -58,6 +58,7 @@ add_contract_build(registrator)
 add_contract_build(gateway)
 add_contract_build(marketplace)
 add_contract_build(apps)
+add_contract_build(expense)
 add_contract_build(system)
 
 # Опции для тестов

components/contracts/build-all.sh

@@ -1,15 +1,13 @@
 #!/usr/bin/env bash
+# Локальная сборка всех контрактов: оборачивает build_contracts_cdt.sh в
+# CDT-образ. Сам cmake/make живёт в build_contracts_cdt.sh — он же
+# используется в CI (там CDT ставится из .deb, без docker), поэтому
+# флаги сборки в одном месте и не разъезжаются.
 
 mode="${1:-prod}"
 
-if [ "$mode" = "test" ]; then
-  is_testnet="ON"
-else
-  is_testnet="OFF"
-fi
-
 docker run --rm --name cdt \
   --volume "$(pwd):/project" \
   -w /project \
   dicoop/blockchain:latest \
-  /bin/bash -c "mkdir -p build && cd build && cmake -DBUILD_TARGET= -DTEST_TARGET= -DVERBOSE=ON -DBUILD_TESTS=OFF -DIS_TESTNET=$is_testnet .. && make"
+  /bin/bash -c "./build_contracts_cdt.sh $mode"

components/contracts/build_contracts_cdt.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Компиляция всех контрактов кооперативной экономики через CDT.
+#
+# ВАЖНО: скрипт запускается УЖЕ внутри окружения с установленным CDT —
+# тулчейн ожидается по пути /cdt/build/lib/cmake/cdt/CDTWasmToolchain.cmake
+# (он захардкожен в CMakeLists.txt). Здесь НЕТ docker — только cmake/make.
+#
+# Два способа подготовить это окружение:
+#   - локально:  build-all.sh оборачивает скрипт в `docker run dicoop/blockchain:latest`
+#                (в образе CDT уже лежит в /cdt/build);
+#   - в CI:      CDT ставится из .deb (C9S/cdt), а /cdt/build симлинкуется на
+#                /usr/opt/cdt/<ver> (см. .github/workflows/release.yaml).
+#
+# Один источник cmake-флагов для обоих путей — чтобы локальная и CI-сборка
+# не разъезжались.
+set -euo pipefail
+
+mode="${1:-prod}"
+if [ "$mode" = "test" ]; then
+  is_testnet="ON"
+else
+  is_testnet="OFF"
+fi
+
+mkdir -p build
+cd build
+cmake -DBUILD_TARGET= -DTEST_TARGET= -DVERBOSE=ON -DBUILD_TESTS=OFF -DIS_TESTNET="$is_testnet" ..
+make

components/contracts/cpp/capital/app/expense_managment/program_expenses/createpgexp.cpp

@@ -0,0 +1,65 @@
+/**
+ * @brief Инициировать программный расход через шасси expense.
+ *
+ * capital — только инициатор. Резервирует средства в @c program_expense_pool,
+ * создаёт скелет записи progexpense (status=CREATED, как маркер pending), затем
+ * шлёт inline action `expense::createexp(...)` с callback handler `{capital, onpgexpdone}`.
+ * Шасси expense обслуживает весь дальнейший flow (авторизация совета, выдача аванса,
+ * отчёт, закрытие либо отклонение) и на терминальном переходе шлёт inline `onpgexpdone`.
+ *
+ * @param coopname        Кооператив
+ * @param expense_hash    Хеш расхода (= proposal_hash в шасси)
+ * @param creator         Инициатор расхода
+ * @param items           Позиции СЗ (см. ExpenseDomain::item); механика оплаты per-item
+ * @param description     Описание для отчётности
+ * @param statement       Документ-заявление (ProgramExpenseStatement)
+ *
+ * @ingroup public_actions
+ * @ingroup public_capital_actions
+ *
+ * @note Авторизация требуется от @p coopname.
+ */
+void capital::createpgexp(name coopname, checksum256 expense_hash, name creator,
+                          std::vector<ExpenseDomain::item> items,
+                          std::string description, document2 statement) {
+  require_auth(coopname);
+
+  verify_document_or_fail(statement, {creator});
+  eosio::check(!items.empty(), "Программный расход должен содержать хотя бы один item");
+
+  // Сумма расхода — сумма planned_amount всех items.
+  asset amount = items.front().planned_amount;
+  amount.amount = 0;
+  for (const auto &it : items) {
+    amount += it.planned_amount;
+  }
+  Wallet::validate_asset(amount);
+  eosio::check(amount.amount > 0, "Сумма программного расхода должна быть положительной");
+
+  auto exist = Capital::get_program_expense(coopname, expense_hash);
+  eosio::check(!exist.has_value(), "Программный расход с указанным хэшем уже существует");
+
+  // Резерв в пуле до отправки в шасси — две параллельные заявки не превысят пул.
+  Capital::State::reserve_program_expense(coopname, amount);
+
+  Capital::Expenses::create_program_expense(coopname, expense_hash, creator,
+                                            amount, description, statement);
+
+  // Inline action в шасси expense с callback handler на capital::onpgexpdone.
+  // data пустой — capital резолвит запись по expense_hash, дополнительный payload не нужен.
+  ExpenseDomain::callback_handler callback{
+    .contract = _capital,
+    .action   = Names::Capital::ON_PROGRAM_EXPENSE_DONE,
+    .data     = std::vector<char>{}
+  };
+
+  // Authority — _capital: у capital@eosio.code нет coopname@active, а
+  // expense::createexp принимает контракты-инициаторы по contracts_whitelist.
+  eosio::action(
+    eosio::permission_level{_capital, "active"_n},
+    _expense,
+    Names::External::CREATE_EXPENSE_PROPOSAL,
+    std::make_tuple(coopname, creator, expense_hash,
+                    ledger2_wallets::PROGRAM_EXPENSE_POOL, items, callback, statement)
+  ).send();
+}

components/contracts/cpp/capital/app/expense_managment/program_expenses/onpgexpdone.cpp

@@ -0,0 +1,65 @@
+/**
+ * @brief Callback от шасси expense на финализацию program-расхода.
+ *
+ * Шасси expense шлёт его inline (authority — _expense@active) когда закончило
+ * flow (closeexp или declexp). capital не делает ledger2-проводок —
+ * они уже сделаны шасси на payexp/reportexp/returnexp/overspendexp. capital
+ * только обновляет @c program_expense_pool и удаляет запись из @c progexpenses.
+ *
+ *   status == ExpenseDomain::ProposalStatus::CLOSED (4):
+ *     total_actual <= reserved → consume(total_actual) + release(остаток);
+ *     total_actual >  reserved (был overspendexp) → consume(reserved) +
+ *       прямое списание превышения из program_expense_pool.
+ *   status == ExpenseDomain::ProposalStatus::DECLINED (5):
+ *     release(reserved); decline возможен только до оплат (total_actual == 0).
+ *
+ * @param coopname     Кооператив
+ * @param expense_hash Хеш расхода (ключ в progexpenses)
+ * @param status       ExpenseDomain::ProposalStatus
+ * @param total_actual Фактически потраченная сумма
+ * @param data         Произвольный payload от инициатора (не используется на MVP)
+ *
+ * @ingroup public_actions
+ * @ingroup public_capital_actions
+ *
+ * @note Авторизация требуется от @p _expense — inline-callback шасси.
+ */
+void capital::onpgexpdone(name coopname, checksum256 expense_hash, uint8_t status,
+                          eosio::asset total_actual, std::vector<char> data) {
+  require_auth(_expense);
+
+  auto pgexp = Capital::Expenses::get_program_expense_or_fail(coopname, expense_hash);
+  const auto reserved = pgexp.amount;
+
+  if (status == static_cast<uint8_t>(ExpenseDomain::ProposalStatus::CLOSED)) {
+    eosio::check(total_actual.symbol == reserved.symbol,
+                 "Символ total_actual не совпадает с зарезервированной суммой");
+    eosio::check(total_actual.amount >= 0,
+                 "total_actual не может быть отрицательным");
+
+    if (total_actual.amount <= reserved.amount) {
+      if (total_actual.amount > 0) {
+        Capital::State::consume_program_expense(coopname, total_actual);
+      }
+      const asset leftover = reserved - total_actual;
+      if (leftover.amount > 0) {
+        Capital::State::release_program_expense(coopname, leftover);
+      }
+    } else {
+      // Перерасход (overspendexp в шасси): резерв списываем полностью,
+      // превышение — напрямую из свободного пула программных расходов.
+      Capital::State::consume_program_expense(coopname, reserved);
+      const asset excess = total_actual - reserved;
+      Capital::State::spend_program_expense_pool(coopname, excess);
+    }
+  } else if (status == static_cast<uint8_t>(ExpenseDomain::ProposalStatus::DECLINED)) {
+    // Шасси отклоняет СЗ только до первой оплаты — резерв возвращается целиком.
+    eosio::check(total_actual.amount == 0,
+                 "DECLINED с ненулевым total_actual — нарушение инварианта шасси");
+    Capital::State::release_program_expense(coopname, reserved);
+  } else {
+    eosio::check(false, "onpgexpdone принимает только статусы CLOSED либо DECLINED");
+  }
+
+  Capital::Expenses::delete_program_expense(coopname, pgexp.id);
+}

components/contracts/cpp/capital/app/expense_managment/program_expenses/topupprogexp.cpp

@@ -0,0 +1,33 @@
+/**
+ * @brief Пополняет пул программных расходов из общего инвестиционного пула программы.
+ *
+ * Программные расходы — это целевые списания «Благорост», не аллоцированные ни в один проект
+ * (хозяйственные расходы программы, оплата инфраструктуры программы и т.п.). Прежде чем
+ * создавать запрос на программный расход, председатель пополняет дедикейтнутый пул
+ * @c program_expense_pool из общего @c global_available_invest_pool. Помимо счётчиков
+ * state наполняется КООПЕРАТИВНЫЙ ledger2-кошелёк @c PROGRAM_EXPENSE_POOL (w.cap.pgexp) —
+ * именно из него шасси expense оплачивает СЗ; личные L3-кошельки пайщиков (w.cap.blago)
+ * при расходах не изменяются.
+ *
+ * @param coopname Кооператив (scope state)
+ * @param amount   Сумма пополнения (символ строго совпадает с программой)
+ * @ingroup public_actions
+ * @ingroup public_capital_actions
+ *
+ * @note Авторизация требуется от аккаунта: @p coopname (председатель).
+ */
+void capital::topupprogexp(name coopname, eosio::asset amount) {
+  require_auth(coopname);
+
+  Capital::State::topup_program_expense_pool(coopname, amount);
+
+  // Кошелёк-резерв пула: ISSUE w.cap.pgexp без бухпроводки (деньги физически
+  // на 51 с момента взносов — выделяется только назначение под расходы).
+  // Синтетический process_hash — у пополнения нет естественного анкера.
+  const uint64_t now_us = eosio::current_time_point().time_since_epoch().count();
+  const std::string anchor = coopname.to_string() + ":pgtopup:" + std::to_string(now_us);
+  const checksum256 process_hash = eosio::sha256(anchor.c_str(), anchor.size());
+
+  Ledger2::apply(_capital, coopname, operations::capital::PROGRAM_EXPENSE_TOPUP, amount,
+                 name{}, process_hash, "capital:topupprogexp");
+}

components/contracts/cpp/capital/app/participation_management/import_contributor/importcontr.cpp

@@ -72,8 +72,8 @@ void capital::importcontrib(eosio::name coopname, eosio::name username, checksum
     auto idx = user_wallets.get_index<"byuserwallet"_n>();
     auto preimp_it = idx.find(combine_ids(ledger2_wallets::PREIMP_FUND.value, username.value));
     if (preimp_it != idx.end() && preimp_it->available.amount > 0) {
-      eosio::check(preimp_it->blocked.amount == 0,
-                   "preimp.blocked > 0 не поддерживается при импорте — обратиться в поддержку");
+      // Поле blocked упразднено (2026-05-24): резерв/блокировка на кошельках
+      // больше не используется, проверка preimp.blocked == 0 излишня.
       Ledger2::apply(
         _capital, coopname, operations::capital::DROP_PREIMP,
         preimp_it->available, username, contributor_hash,

components/contracts/cpp/capital/capital.cpp

@@ -95,6 +95,12 @@
 #include "app/debt_managment/create_debt/declinedebt.cpp"
 #include "app/debt_managment/settle_debt/settledebt.cpp"
 
+// Управление программными расходами через шасси expense.
+// capital — инициатор + получатель callback, шасси обслуживает весь flow.
+#include "app/expense_managment/program_expenses/topupprogexp.cpp"
+#include "app/expense_managment/program_expenses/createpgexp.cpp"
+#include "app/expense_managment/program_expenses/onpgexpdone.cpp"
+
 // Управление расходами
 #include "app/expense_managment/create_expense/approveexpns.cpp"
 #include "app/expense_managment/create_expense/capauthexpns.cpp"

components/contracts/cpp/capital/capital.hpp

@@ -48,6 +48,7 @@ constexpr uint128_t CRPS_PRECISION_FACTOR = 100000000000000ULL; ///< Масшт
 #include <eosio/asset.hpp>
 #include "../lib/index.hpp"
 #include "domain/index.hpp"
+#include "../expense/expense.hpp"   // ExpenseDomain::item / callback_handler — для inline-action в шасси
 
 
 using namespace eosio;
@@ -322,4 +323,38 @@ public:
     [[eosio::action]]
     void settledebt(name coopname, name username, eosio::asset amount, document2 statement);
 
+    // Программные расходы через шасси expense.
+    // capital — инициатор + получатель callback, шасси держит весь flow расхода.
+
+    [[eosio::action]]
+    void topupprogexp(name coopname, eosio::asset amount);
+
+    /**
+     * @brief Инициировать программный расход через шасси expense.
+     * Резервирует amount в program_expense_pool, создаёт запись progexpense,
+     * шлёт inline action expense::createexp с callback={capital, onpgexpdone}.
+     * Шасси обслуживает весь flow (auth/pay/report/close|decline) и шлёт callback.
+     *
+     * items[] — позиции СЗ (см. ExpenseDomain::item); механика оплаты per-item
+     * (item.mechanics: ADVANCE — аванс, DIRECT — прямая оплата).
+     */
+    [[eosio::action]]
+    void createpgexp(name coopname, checksum256 expense_hash, name creator,
+                     std::vector<ExpenseDomain::item> items,
+                     std::string description, document2 statement);
+
+    /**
+     * @brief Callback от шасси expense на финализацию program-расхода.
+     * Шасси шлёт его inline (authority — _expense@active, require_auth(_expense))
+     * после терминального перехода flow (CLOSED либо DECLINED).
+     *
+     *   status == CLOSED   → consume(total_actual) + release(остаток резерва);
+     *                         при total_actual > reserved (перерасход) превышение
+     *                         списывается напрямую из program_expense_pool.
+     *   status == DECLINED → release(reserved); decline возможен только до оплат.
+     */
+    [[eosio::action]]
+    void onpgexpdone(name coopname, checksum256 expense_hash, uint8_t status,
+                     eosio::asset total_actual, std::vector<char> data);
+
 };

components/contracts/cpp/capital/domain/core/balances/balances.cpp

@@ -9,23 +9,26 @@ namespace Capital::Core {
    * @brief Совокупный баланс программы Благорост на уровне кооператива.
    *
    * Источник — ledger2 L2 (`wallets[BLAGOROST_FUND]`), агрегированный по всем
-   * пайщикам. Σ L3.{available, blocked}[w.cap.blago] == L2.{available, blocked}
-   * (Эпик 3 invariant), поэтому L2 — авторитетная сумма для CRPS-знаменателя.
-   * Если кошелёк ещё не создан (никто не инвестировал) — нулевой баланс.
+   * пайщикам. Σ L3.available[w.cap.blago] == L2.available (Эпик 3 invariant),
+   * поэтому L2 — авторитетная сумма для CRPS-знаменателя. Если кошелёк ещё не
+   * создан (никто не инвестировал) — нулевой баланс.
+   *
+   * Поле blocked упразднено (2026-05-24): субсчёт «заблокировано» больше не
+   * используется, баланс кошелька = available.
    */
   eosio::asset get_capital_program_share_balance(eosio::name coopname) {
     wallets2_index wallets(_ledger2, coopname.value);
     auto it = wallets.find(ledger2_wallets::BLAGOROST_FUND.value);
     if (it == wallets.end()) return eosio::asset(0, _root_govern_symbol);
-    return it->available + it->blocked;
+    return it->available;
   }
 
   /**
-   * @brief Доля пайщика в Благоросте (available + blocked) из ledger2 L3.
+   * @brief Доля пайщика в Благоросте (available) из ledger2 L3.
    *
    * Источник — `userwallets[(w.cap.blago, username)]`. Запись существует
-   * только пока available + blocked > 0 (Эпик 3 §6: auto-delete на нуле),
-   * поэтому отсутствие = нулевой баланс.
+   * только пока available > 0 (Эпик 3 §6: auto-delete на нуле), поэтому
+   * отсутствие = нулевой баланс. Поле blocked упразднено (2026-05-24).
    */
   eosio::asset get_capital_program_user_share_balance(eosio::name coopname, eosio::name username) {
     userwallets_index user_wallets(_ledger2, coopname.value);
@@ -33,6 +36,6 @@ namespace Capital::Core {
     auto key = combine_ids(ledger2_wallets::BLAGOROST_FUND.value, username.value);
     auto it = idx.find(key);
     if (it == idx.end()) return eosio::asset(0, _root_govern_symbol);
-    return it->available + it->blocked;
+    return it->available;
   }
 }

components/contracts/cpp/capital/domain/entities/expenses.hpp

@@ -178,8 +178,96 @@ namespace Capital::Expenses {
     Capital::expense_index expenses(_capital, coopname.value);
     auto expense = expenses.find(expense_id);
     eosio::check(expense != expenses.end(), "Расход не найден");
-    
+
     expenses.erase(expense);
   }
 
+} // namespace Capital::Expenses
+
+namespace Capital {
+
+  /**
+   * @brief Таблица программных расходов — целевые списания «Благорост»,
+   *        не привязанные к конкретному проекту.
+   * @par Область памяти (scope): coopname
+   * @par Имя таблицы (table): progexpenses
+   */
+  struct [[eosio::table, eosio::contract(CAPITAL)]] program_expense {
+    uint64_t id;                                    ///< Внутренний ключ
+    name coopname;                                  ///< Имя кооператива
+    name username;                                  ///< Инициатор расхода (председатель / казначей)
+
+    name status = Expenses::Status::CREATED;        ///< Статус (CREATED/APPROVED/AUTHORIZED/PAID/DECLINED — общий enum)
+    checksum256 expense_hash;                       ///< Хеш расхода — анкер процесса p.cap.expns
+    uint64_t fund_id;                               ///< Идентификатор фонда списания
+    eosio::asset amount;                            ///< Сумма расхода
+    std::string description;                        ///< Описание (для отчётности)
+
+    document2 expense_statement;                    ///< Служебная записка (ProgramExpenseStatement)
+    document2 approved_statement;                   ///< Записка, принятая председателем
+    document2 authorization;                        ///< Решение совета
+
+    time_point_sec spended_at = current_time_point();
+
+    uint64_t primary_key() const { return id; }
+    uint64_t by_username() const { return username.value; }
+    checksum256 by_expense_hash() const { return expense_hash; }
+  };
+
+  typedef eosio::multi_index<
+    "progexpenses"_n, program_expense,
+    indexed_by<"byusername"_n, const_mem_fun<program_expense, uint64_t, &program_expense::by_username>>,
+    indexed_by<"byhash"_n, const_mem_fun<program_expense, checksum256, &program_expense::by_expense_hash>>
+  > program_expense_index;
+
+  inline std::optional<program_expense> get_program_expense(eosio::name coopname, const checksum256 &hash) {
+    program_expense_index t(_capital, coopname.value);
+    auto idx = t.get_index<"byhash"_n>();
+    auto itr = idx.find(hash);
+    if (itr == idx.end()) return std::nullopt;
+    return program_expense(*itr);
+  }
+
+} // namespace Capital
+
+namespace Capital::Expenses {
+
+  inline program_expense get_program_expense_or_fail(eosio::name coopname, const checksum256 &expense_hash) {
+    auto v = Capital::get_program_expense(coopname, expense_hash);
+    eosio::check(v.has_value(), "Программный расход с указанным хэшем не найден");
+    return v.value();
+  }
+
+  inline void create_program_expense(
+    eosio::name coopname,
+    const checksum256 &expense_hash,
+    eosio::name username,
+    const eosio::asset &amount,
+    const std::string &description,
+    const document2 &statement
+  ) {
+    Capital::program_expense_index t(_capital, coopname.value);
+    uint64_t id = get_global_id_in_scope(_capital, coopname, "progexpenses"_n);
+
+    t.emplace(coopname, [&](auto &e) {
+      e.id = id;
+      e.coopname = coopname;
+      e.username = username;
+      e.expense_hash = expense_hash;
+      e.fund_id = Ledger::accounts::GENERAL_EXPENSES;
+      e.status = Status::CREATED;
+      e.spended_at = current_time_point();
+      e.expense_statement = statement;
+      e.amount = amount;
+      e.description = description;
+    });
+  }
+
+  inline void delete_program_expense(eosio::name coopname, uint64_t id) {
+    Capital::program_expense_index t(_capital, coopname.value);
+    auto itr = t.find(id);
+    eosio::check(itr != t.end(), "Программный расход не найден");
+    t.erase(itr);
+  }
+
 } // namespace Capital::Expenses

components/contracts/cpp/capital/domain/entities/global_state.hpp

@@ -39,8 +39,11 @@ namespace Capital {
     asset program_membership_distributed = asset(0, _root_govern_symbol); ///< Распределенная сумма членских взносов по программе
     double program_membership_cumulative_reward_per_share;               ///< Накопительное вознаграждение на долю в членских взносах
 
+    asset program_expense_pool = asset(0, _root_govern_symbol);     ///< Доступная сумма программы под целевые расходы (без аллокации в проекты)
+    asset program_expense_reserved = asset(0, _root_govern_symbol); ///< Сумма, зарезервированная под approved/authorized программные расходы
+
     config config;                                           ///< Управляемая конфигурация контракта
-    
+
     uint64_t primary_key() const { return coopname.value; }     ///< Первичный ключ (1)
   };
 
@@ -78,7 +81,7 @@ inline global_state get_global_state(name coopname) {
 
 /**
  * @brief Проверяет что контракт инициализирован.
- * 
+ *
  * @param coopname Имя кооператива.
  */
 inline void is_initialized(name coopname) {
@@ -86,6 +89,96 @@ inline void is_initialized(name coopname) {
   auto itr = global_state_inst.find(coopname.value);
   eosio::check(itr != global_state_inst.end(), "Контракт не инициализирован");
 }
+
+/**
+ * @brief Пополняет пул программных расходов на @p amount из общего пула инвестиций программы.
+ *        Вызывается из action topupprogexp (председатель).
+ */
+inline void topup_program_expense_pool(eosio::name coopname, const asset &amount) {
+  global_state_table global_state_inst(_capital, _capital.value);
+  auto itr = global_state_inst.find(coopname.value);
+  eosio::check(itr != global_state_inst.end(), "Контракт не инициализирован");
+  eosio::check(amount.is_valid() && amount.amount > 0, "Сумма пополнения должна быть положительной");
+  eosio::check(itr->global_available_invest_pool >= amount,
+               "Недостаточно свободных инвестиций программы для пополнения пула расходов");
+
+  global_state_inst.modify(itr, _capital, [&](auto &s) {
+    s.global_available_invest_pool -= amount;
+    s.program_expense_pool += amount;
+  });
+}
+
+/**
+ * @brief Резервирует средства под approved/authorized программный расход:
+ *        program_expense_pool -= amount, program_expense_reserved += amount.
+ */
+inline void reserve_program_expense(eosio::name coopname, const asset &amount) {
+  global_state_table global_state_inst(_capital, _capital.value);
+  auto itr = global_state_inst.find(coopname.value);
+  eosio::check(itr != global_state_inst.end(), "Контракт не инициализирован");
+  eosio::check(amount.is_valid() && amount.amount > 0, "Сумма резерва должна быть положительной");
+  eosio::check(itr->program_expense_pool >= amount,
+               "Недостаточно средств в пуле программных расходов");
+
+  global_state_inst.modify(itr, _capital, [&](auto &s) {
+    s.program_expense_pool -= amount;
+    s.program_expense_reserved += amount;
+  });
+}
+
+/**
+ * @brief Освобождает зарезервированное при отклонении программного расхода:
+ *        program_expense_reserved -= amount, program_expense_pool += amount.
+ */
+inline void release_program_expense(eosio::name coopname, const asset &amount) {
+  global_state_table global_state_inst(_capital, _capital.value);
+  auto itr = global_state_inst.find(coopname.value);
+  eosio::check(itr != global_state_inst.end(), "Контракт не инициализирован");
+  eosio::check(amount.is_valid() && amount.amount > 0, "Сумма освобождения должна быть положительной");
+  eosio::check(itr->program_expense_reserved >= amount,
+               "Зарезервированных программных расходов меньше указанной суммы");
+
+  global_state_inst.modify(itr, _capital, [&](auto &s) {
+    s.program_expense_reserved -= amount;
+    s.program_expense_pool += amount;
+  });
+}
+
+/**
+ * @brief Окончательное списание программного расхода (callback onpgexpdone, CLOSED):
+ *        program_expense_reserved -= amount. Деньги уже ушли через шасси expense,
+ *        ledger2-проводки сделаны на payexp/reportexp/returnexp.
+ */
+inline void consume_program_expense(eosio::name coopname, const asset &amount) {
+  global_state_table global_state_inst(_capital, _capital.value);
+  auto itr = global_state_inst.find(coopname.value);
+  eosio::check(itr != global_state_inst.end(), "Контракт не инициализирован");
+  eosio::check(amount.is_valid() && amount.amount > 0, "Сумма списания должна быть положительной");
+  eosio::check(itr->program_expense_reserved >= amount,
+               "Зарезервированных программных расходов меньше указанной суммы");
+
+  global_state_inst.modify(itr, _capital, [&](auto &s) {
+    s.program_expense_reserved -= amount;
+  });
+}
+
+/**
+ * @brief Прямое списание из свободного пула программных расходов — превышение
+ *        факта над резервом при закрытии расхода с перерасходом (overspendexp
+ *        в шасси выдал доплату из BLAGOROST_FUND сверх зарезервированного).
+ */
+inline void spend_program_expense_pool(eosio::name coopname, const asset &amount) {
+  global_state_table global_state_inst(_capital, _capital.value);
+  auto itr = global_state_inst.find(coopname.value);
+  eosio::check(itr != global_state_inst.end(), "Контракт не инициализирован");
+  eosio::check(amount.is_valid() && amount.amount > 0, "Сумма списания должна быть положительной");
+  eosio::check(itr->program_expense_pool >= amount,
+               "Недостаточно средств в пуле программных расходов для покрытия перерасхода — пополните пул (topupprogexp)");
+
+  global_state_inst.modify(itr, _capital, [&](auto &s) {
+    s.program_expense_pool -= amount;
+  });
+}
 }// namespace State
 
 }// namespace Capital

components/contracts/cpp/expense/CMakeLists.txt

@@ -0,0 +1,10 @@
+cmake_minimum_required(VERSION 3.5)
+
+project(expense)
+
+find_package(cdt)
+
+add_contract(expense expense expense.cpp)
+if(IS_TESTNET)
+    target_compile_definitions(expense PUBLIC IS_TESTNET=1)
+endif()

components/contracts/cpp/expense/expense.cpp

@@ -0,0 +1,425 @@
+// expense.cpp — шасси расходов (первый потребитель: Благорост).
+//
+// Принцип: контракт-владелец расходных операций, агностичен к программе-источнику.
+// Кошелёк-пул приходит в createexp параметром source_wallet; ledger2-коды всех
+// операций жизненного цикла выводятся из него через EXPENSE_OPERATION_SETS
+// (фабричная настройка — подключение нового пула не меняет этот контракт).
+// Механика оплаты per-item (ADVANCE | DIRECT) выбирает код внутри набора;
+// callback-handler сохраняется как переменная.
+
+#include "expense.hpp"
+
+namespace D = ExpenseDomain;
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+namespace {
+
+asset zero_like(const asset& a) { return asset{0, a.symbol}; }
+
+asset sum_planned(const std::vector<D::item>& items) {
+  if (items.empty()) return asset{0, eosio::symbol{"RUB", 4}};
+  asset total = zero_like(items.front().planned_amount);
+  for (const auto& it : items) total += it.planned_amount;
+  return total;
+}
+
+// Набор ledger2-кодов операций шасси по кошельку-источнику СЗ. Один источник =
+// один набор (EXPENSE_OPERATION_SETS в ledger2) — в коде expense нет
+// захардкоженных operation_code, контракт настраивается на любой пул.
+const ExpenseOperationSet& expense_ops_for(eosio::name source_wallet) {
+  const auto* set = find_expense_operation_set(source_wallet);
+  eosio::check(set != nullptr,
+               "Для кошелька-источника не настроен набор операций шасси расходов (EXPENSE_OPERATION_SETS)");
+  return *set;
+}
+
+D::proposals_index get_proposals(eosio::name self, eosio::name coopname) {
+  return D::proposals_index(self, coopname.value);
+}
+
+auto find_proposal(D::proposals_index& tbl, const eosio::checksum256& proposal_hash) {
+  auto idx = tbl.get_index<"byhash"_n>();
+  return idx.find(proposal_hash);
+}
+
+void send_callback_if_any(const D::callback_handler& cb,
+                          eosio::name coopname,
+                          const eosio::checksum256& proposal_hash,
+                          uint8_t status,
+                          const eosio::asset& amount,
+                          eosio::name self) {
+  if (cb.contract.value == 0) return;
+  // Payload: (coopname, proposal_hash, status, total_actual, data).
+  // status = ExpenseDomain::ProposalStatus — инициатор различает CLOSED vs DECLINED.
+  // coopname нужен инициатору для скоупа таблиц (capital::progexpenses scope=coopname).
+  eosio::action(
+    eosio::permission_level{self, "active"_n},
+    cb.contract,
+    cb.action,
+    std::make_tuple(coopname, proposal_hash, status, amount, cb.data)
+  ).send();
+}
+
+} // namespace
+
+// ── actions ──────────────────────────────────────────────────────────────────
+
+void expense::createexp(name coopname, name username,
+                        checksum256 proposal_hash,
+                        name source_wallet,
+                        std::vector<D::item> items,
+                        D::callback_handler callback,
+                        document2 statement) {
+  // Прямой вызов backend'а — авторизация кооператива; inline от контракта-инициатора
+  // (capital::createpgexp и т.п.) — авторизация по whitelist, как в ledger2::apply.
+  if (!has_auth(coopname)) {
+    check_auth_and_get_payer_or_fail(contracts_whitelist);
+  }
+
+  verify_document_or_fail(statement, {username});
+  eosio::check(!items.empty(), "СЗ должен содержать хотя бы один item");
+  eosio::check(ledger2_is_known_wallet(source_wallet),
+               "source_wallet не найден в LEDGER2_WALLET_REGISTRY");
+  // Источник определяет ledger2-коды всех операций жизненного цикла —
+  // отказываем сразу при создании, а не в момент оплаты.
+  expense_ops_for(source_wallet);
+
+  auto tbl = get_proposals(get_self(), coopname);
+  eosio::check(find_proposal(tbl, proposal_hash) == tbl.get_index<"byhash"_n>().end(),
+               "СЗ с таким proposal_hash уже существует");
+
+  // Механика оплаты задаётся на каждом item отдельно (ADVANCE | DIRECT) —
+  // в одном СЗ допустимо смешение: ledger2-проводка payexp идёт по-позиционно
+  // с кодом, выведенным из механики конкретного item'а.
+  for (auto& it : items) {
+    eosio::check(it.planned_amount.is_valid() && it.planned_amount.amount > 0,
+                 "planned_amount каждого item должен быть положительным");
+    eosio::check(it.mechanics <= static_cast<uint8_t>(D::Mechanics::DIRECT),
+                 "Неизвестная mechanics item (0 = ADVANCE, 1 = DIRECT)");
+    eosio::check(it.recipient_type <= static_cast<uint8_t>(D::RecipientType::ORG),
+                 "Неизвестный recipient_type item");
+
+    // Инвариант: пайщик (SELF/MEMBER) получает только аванс под отчёт на личные
+    // реквизиты (расходом станет после его отчёта чеком); организация — только
+    // прямую оплату по выставленным реквизитам, аванс ей не выдаётся.
+    if (it.recipient_type == static_cast<uint8_t>(D::RecipientType::ORG)) {
+      eosio::check(it.mechanics == static_cast<uint8_t>(D::Mechanics::DIRECT),
+                   "Организации/ИП доступна только оплата по счёту (DIRECT)");
+    } else {
+      eosio::check(it.mechanics == static_cast<uint8_t>(D::Mechanics::ADVANCE),
+                   "Пайщику средства выдаются только авансом под отчёт (ADVANCE)");
+      eosio::check(it.recipient != name(),
+                   "recipient обязателен для получателя-пайщика");
+      eosio::check(is_account(it.recipient),
+                   "Аккаунт получателя-пайщика не существует");
+    }
+
+    it.status        = static_cast<uint8_t>(D::ItemStatus::APPROVED);
+    it.actual_amount = zero_like(it.planned_amount);
+  }
+
+  const auto total = sum_planned(items);
+
+  tbl.emplace(get_self(), [&](auto& row) {
+    row.id              = tbl.available_primary_key();
+    row.coopname        = coopname;
+    row.proposal_hash   = proposal_hash;
+    row.username        = username;
+    row.source_wallet   = source_wallet;
+    row.status          = static_cast<uint8_t>(D::ProposalStatus::CREATED);
+    row.items           = items;
+    row.total_planned   = total;
+    row.total_actual    = zero_like(total);
+    row.callback        = callback;
+    row.statement_doc   = statement;
+    row.decision_doc    = document2{};
+    row.created_at      = eosio::current_time_point();
+    row.updated_at      = row.created_at;
+  });
+
+  // СЗ утверждает совет (как возвраты паевых взносов): ставим вопрос в повестку.
+  // Утверждение председателем после голосования → callback authexp от _soviet;
+  // отклонение (отрицательный консенсус / просрочка) → declexp с причиной.
+  ::Soviet::create_agenda(
+    _expense,
+    coopname,
+    username,
+    get_valid_soviet_action("createexp"_n),
+    proposal_hash,
+    _expense,
+    "authexp"_n,
+    "declexp"_n,
+    statement,
+    std::string("")
+  );
+}
+
+void expense::authexp(name coopname, checksum256 proposal_hash, document2 decision) {
+  require_auth(_soviet);
+
+  auto tbl = get_proposals(get_self(), coopname);
+  auto idx = tbl.get_index<"byhash"_n>();
+  auto it  = idx.find(proposal_hash);
+  eosio::check(it != idx.end(), "СЗ не найден");
+  eosio::check(it->status == static_cast<uint8_t>(D::ProposalStatus::CREATED),
+               "Авторизовать можно только СЗ в статусе CREATED");
+
+  verify_document_or_fail(decision);
+
+  idx.modify(it, get_self(), [&](auto& row) {
+    row.decision_doc = decision;
+    row.status       = static_cast<uint8_t>(D::ProposalStatus::AUTHORIZED);
+    row.updated_at   = eosio::current_time_point();
+  });
+}
+
+void expense::declexp(name coopname, checksum256 proposal_hash, std::string reason) {
+  require_auth(_soviet);
+
+  auto tbl = get_proposals(get_self(), coopname);
+  auto idx = tbl.get_index<"byhash"_n>();
+  auto it  = idx.find(proposal_hash);
+  eosio::check(it != idx.end(), "СЗ не найден");
+  // Отклонение возможно только пока ни один item не оплачен: после payexp деньги
+  // уже ушли через ledger2, и decline разъехался бы с учётом инициатора
+  // (callback DECLINED возвращает инициатору весь резерв). Частично исполненный
+  // СЗ завершается обычным путём: reportexp / returnexp → closeexp.
+  eosio::check(it->status == static_cast<uint8_t>(D::ProposalStatus::CREATED) ||
+               it->status == static_cast<uint8_t>(D::ProposalStatus::AUTHORIZED),
+               "Отклонить можно только СЗ без оплат (статусы CREATED / AUTHORIZED)");
+
+  idx.modify(it, get_self(), [&](auto& row) {
+    row.status     = static_cast<uint8_t>(D::ProposalStatus::DECLINED);
+    row.updated_at = eosio::current_time_point();
+  });
+
+  // Callback инициатору (capital::onpgexpdone и т.п.); total_actual здесь всегда 0 —
+  // оплат до decline не было (см. проверку статусов выше).
+  send_callback_if_any(it->callback, coopname, proposal_hash,
+                       static_cast<uint8_t>(D::ProposalStatus::DECLINED),
+                       it->total_actual, get_self());
+}
+
+void expense::payexp(name coopname, checksum256 proposal_hash, checksum256 item_hash,
+                     asset actual_amount) {
+  require_auth(coopname);
+
+  auto tbl = get_proposals(get_self(), coopname);
+  auto idx = tbl.get_index<"byhash"_n>();
+  auto it  = idx.find(proposal_hash);
+  eosio::check(it != idx.end(), "СЗ не найден");
+  eosio::check(it->status == static_cast<uint8_t>(D::ProposalStatus::AUTHORIZED) ||
+               it->status == static_cast<uint8_t>(D::ProposalStatus::PARTIALLY_PAID),
+               "Оплата возможна только из статусов AUTHORIZED / PARTIALLY_PAID");
+  eosio::check(actual_amount.is_valid() && actual_amount.amount > 0,
+               "actual_amount должен быть положительным");
+
+  bool item_found = false;
+  uint8_t paid_mechanics = 0;
+  name paid_recipient{};
+
+  idx.modify(it, get_self(), [&](auto& row) {
+    bool all_reported = true;
+    for (auto& i : row.items) {
+      if (i.item_hash == item_hash) {
+        eosio::check(i.status == static_cast<uint8_t>(D::ItemStatus::APPROVED),
+                     "Item уже оплачен или закрыт");
+        eosio::check(actual_amount.symbol == i.planned_amount.symbol,
+                     "Символ actual_amount не совпадает с планом item");
+        eosio::check(actual_amount.amount <= i.planned_amount.amount,
+                     "Сумма оплаты не может превышать план item; доплата сверх плана — через overspendexp");
+        i.actual_amount = actual_amount;
+        // DIRECT не имеет фазы подотчёта (нет ADVANCE_HOLD): закрывающие документы
+        // прикладывает сам кассир, item считается отчитанным сразу после оплаты.
+        i.status = static_cast<D::Mechanics>(i.mechanics) == D::Mechanics::DIRECT
+          ? static_cast<uint8_t>(D::ItemStatus::REPORTED)
+          : static_cast<uint8_t>(D::ItemStatus::PAID);
+        paid_mechanics = i.mechanics;
+        paid_recipient = i.recipient;
+        item_found = true;
+      }
+      if (i.status != static_cast<uint8_t>(D::ItemStatus::REPORTED)) {
+        all_reported = false;
+      }
+    }
+    eosio::check(item_found, "item с заданным hash не найден в СЗ");
+    row.total_actual += actual_amount;
+    // DIRECT-only СЗ становится готов к закрытию сразу после последней оплаты.
+    row.status = all_reported
+      ? static_cast<uint8_t>(D::ProposalStatus::REPORT_SUBMITTED)
+      : static_cast<uint8_t>(D::ProposalStatus::PARTIALLY_PAID);
+    row.updated_at = eosio::current_time_point();
+  });
+
+  // ledger2-проводка по механике оплаченного item'а — выдача аванса или прямая
+  // оплата; коды выводятся из кошелька-источника СЗ. СЗ может смешивать механики.
+  // username нужен ledger2 только для USER_SHARED-стороны (кошелёк-подотчёт) —
+  // это ПОЛУЧАТЕЛЬ аванса, не автор СЗ.
+  const auto& ops = expense_ops_for(it->source_wallet);
+  const auto code = static_cast<D::Mechanics>(paid_mechanics) == D::Mechanics::ADVANCE
+    ? ops.advance
+    : ops.direct;
+  Ledger2::apply(get_self(), coopname, code, actual_amount,
+                 paid_recipient, proposal_hash, "expense:payexp");
+}
+
+void expense::reportexp(name coopname, checksum256 proposal_hash, checksum256 item_hash) {
+  require_auth(coopname);
+
+  auto tbl = get_proposals(get_self(), coopname);
+  auto idx = tbl.get_index<"byhash"_n>();
+  auto it  = idx.find(proposal_hash);
+  eosio::check(it != idx.end(), "СЗ не найден");
+  eosio::check(it->status == static_cast<uint8_t>(D::ProposalStatus::PARTIALLY_PAID),
+               "Отчёт возможен только по СЗ в статусе PARTIALLY_PAID");
+
+  asset item_amount = asset{0, it->total_actual.symbol};
+  bool item_found = false;
+  name item_recipient{};
+
+  idx.modify(it, get_self(), [&](auto& row) {
+    bool all_reported = true;
+    for (auto& i : row.items) {
+      if (i.item_hash == item_hash) {
+        eosio::check(i.status == static_cast<uint8_t>(D::ItemStatus::PAID),
+                     "Отчёт возможен только для оплаченных items");
+        eosio::check(static_cast<D::Mechanics>(i.mechanics) == D::Mechanics::ADVANCE,
+                     "reportexp применим только к ADVANCE-механике");
+        i.status   = static_cast<uint8_t>(D::ItemStatus::REPORTED);
+        item_amount = i.actual_amount;
+        item_recipient = i.recipient;
+        item_found  = true;
+      }
+      if (i.status != static_cast<uint8_t>(D::ItemStatus::REPORTED)) {
+        all_reported = false;
+      }
+    }
+    eosio::check(item_found, "item с заданным hash не найден в СЗ");
+    if (all_reported) {
+      row.status = static_cast<uint8_t>(D::ProposalStatus::REPORT_SUBMITTED);
+    }
+    row.updated_at = eosio::current_time_point();
+  });
+
+  // ledger2: BURN кошелька-подотчёта на остаточный actual item'а (выдано −
+  // возвращено + доплачено), без бухпроводки — проводка уже сделана при выдаче.
+  // Подотчёт числится на получателе аванса — его username и закрывает burn.
+  // Полный возврат аванса (actual == 0) — burn не нужен, подотчёт уже пуст.
+  if (item_amount.amount > 0) {
+    Ledger2::apply(get_self(), coopname, expense_ops_for(it->source_wallet).report, item_amount,
+                   item_recipient, proposal_hash, "expense:reportexp");
+  }
+}
+
+void expense::closeexp(name coopname, checksum256 proposal_hash) {
+  require_auth(coopname);
+
+  auto tbl = get_proposals(get_self(), coopname);
+  auto idx = tbl.get_index<"byhash"_n>();
+  auto it  = idx.find(proposal_hash);
+  eosio::check(it != idx.end(), "СЗ не найден");
+  eosio::check(it->status == static_cast<uint8_t>(D::ProposalStatus::REPORT_SUBMITTED),
+               "Закрыть можно только СЗ в статусе REPORT_SUBMITTED");
+
+  idx.modify(it, get_self(), [&](auto& row) {
+    row.status     = static_cast<uint8_t>(D::ProposalStatus::CLOSED);
+    row.updated_at = eosio::current_time_point();
+  });
+
+  // Callback на финализацию (capital::onpgexpdone и т.п.) — если был установлен при createexp.
+  send_callback_if_any(it->callback, coopname, proposal_hash,
+                       static_cast<uint8_t>(D::ProposalStatus::CLOSED),
+                       it->total_actual, get_self());
+}
+
+void expense::returnexp(name coopname, checksum256 proposal_hash, checksum256 item_hash,
+                        asset return_amount) {
+  require_auth(coopname);
+
+  auto tbl = get_proposals(get_self(), coopname);
+  auto idx = tbl.get_index<"byhash"_n>();
+  auto it  = idx.find(proposal_hash);
+  eosio::check(it != idx.end(), "СЗ не найден");
+  eosio::check(it->status == static_cast<uint8_t>(D::ProposalStatus::PARTIALLY_PAID),
+               "Возврат возможен только по СЗ в статусе PARTIALLY_PAID");
+
+  bool item_found = false;
+  name item_recipient{};
+
+  idx.modify(it, get_self(), [&](auto& row) {
+    for (auto& i : row.items) {
+      if (i.item_hash == item_hash) {
+        eosio::check(i.status == static_cast<uint8_t>(D::ItemStatus::PAID),
+                     "Возврат возможен только из статуса PAID");
+        eosio::check(static_cast<D::Mechanics>(i.mechanics) == D::Mechanics::ADVANCE,
+                     "returnexp применим только к ADVANCE-механике");
+        eosio::check(return_amount.is_valid() &&
+                     return_amount.symbol == i.actual_amount.symbol,
+                     "Символ return_amount не совпадает с item");
+        eosio::check(return_amount.amount > 0 && return_amount.amount <= i.actual_amount.amount,
+                     "return_amount должен быть положительным и не превышать actual_amount");
+        // Settlement-запись: статус item НЕ меняется (остаётся PAID) — после
+        // возврата остатка получатель штатно отчитывается reportexp по
+        // фактически потраченной части (при полном возврате — actual == 0).
+        i.actual_amount -= return_amount;
+        item_recipient = i.recipient;
+        item_found = true;
+        break;
+      }
+    }
+    eosio::check(item_found, "item с заданным hash не найден в СЗ");
+    row.total_actual -= return_amount;
+    row.updated_at   = eosio::current_time_point();
+  });
+
+  // ledger2: TRANSFER подотчёт → пул-источник (зеркало выдачи аванса).
+  // Подотчёт снимается с получателя аванса.
+  Ledger2::apply(get_self(), coopname, expense_ops_for(it->source_wallet).refund, return_amount,
+                 item_recipient, proposal_hash, "expense:returnexp");
+}
+
+void expense::overspendexp(name coopname, checksum256 proposal_hash, checksum256 item_hash,
+                           asset overspend_amount) {
+  require_auth(coopname);
+  eosio::check(overspend_amount.amount > 0, "overspend_amount должен быть положительным");
+
+  auto tbl = get_proposals(get_self(), coopname);
+  auto idx = tbl.get_index<"byhash"_n>();
+  auto it  = idx.find(proposal_hash);
+  eosio::check(it != idx.end(), "СЗ не найден");
+  eosio::check(it->status == static_cast<uint8_t>(D::ProposalStatus::PARTIALLY_PAID),
+               "Перерасход возможен только по СЗ в статусе PARTIALLY_PAID");
+
+  bool item_found = false;
+  name item_recipient{};
+
+  idx.modify(it, get_self(), [&](auto& row) {
+    for (auto& i : row.items) {
+      if (i.item_hash == item_hash) {
+        eosio::check(i.status == static_cast<uint8_t>(D::ItemStatus::PAID),
+                     "Перерасход регистрируется только из статуса PAID");
+        eosio::check(static_cast<D::Mechanics>(i.mechanics) == D::Mechanics::ADVANCE,
+                     "overspendexp применим только к ADVANCE-механике");
+        eosio::check(overspend_amount.is_valid() &&
+                     overspend_amount.symbol == i.actual_amount.symbol,
+                     "Символ overspend_amount не совпадает с item");
+        // Settlement-запись: статус item НЕ меняется (остаётся PAID) — подотчёт
+        // (теперь на полную сумму выдано + доплата) закрывается штатным reportexp,
+        // который сделает burn ADVANCE_HOLD на итоговый actual.
+        i.actual_amount += overspend_amount;
+        item_recipient = i.recipient;
+        item_found = true;
+        break;
+      }
+    }
+    eosio::check(item_found, "item с заданным hash не найден в СЗ");
+    row.total_actual += overspend_amount;
+    row.updated_at   = eosio::current_time_point();
+  });
+
+  // ledger2: доплата перерасхода — TRANSFER пул-источник → подотчёт получателя
+  // (зеркало выдачи аванса на сумму доплаты). Закрытие на полную сумму — в reportexp.
+  Ledger2::apply(get_self(), coopname, expense_ops_for(it->source_wallet).overspend, overspend_amount,
+                 item_recipient, proposal_hash, "expense:overspend");
+}

components/contracts/cpp/expense/expense.hpp

@@ -0,0 +1,233 @@
+#pragma once
+
+#include <eosio/eosio.hpp>
+#include <eosio/asset.hpp>
+#include <eosio/crypto.hpp>
+#include "../lib/index.hpp"
+
+using namespace eosio;
+using std::string;
+
+/**
+ *  @defgroup public_expense Контракт EXPENSE
+ *  @brief Шасси расходов цифрового кооператива (MVP — Благорост).
+ *
+ *  Универсальный контракт: principal storage = СЗ-расход с массивом items;
+ *  кошелёк-источник (пул) приходит параметром source_wallet, ledger2-коды всех
+ *  операций жизненного цикла выводятся из него через EXPENSE_OPERATION_SETS
+ *  (ledger2/operations.hpp) — подключение нового пула не меняет контракт;
+ *  механика оплаты per-item (ADVANCE | DIRECT) выбирает код внутри набора;
+ *  callback на финализацию (контракт+action+data) сохраняется при createexp
+ *  как переменная — `expense` агностичен к программе-получателю.
+ *
+ *  See: components/desktop/extensions/expenses/NAMING-C28-28.md (v3).
+ */
+
+namespace ExpenseDomain {
+
+  /**
+   * @brief Способ оплаты item-а в СЗ.
+   *   ADVANCE — пайщик-получатель оплачивает, затем приносит чек.
+   *   DIRECT  — кассир/председатель платит организации напрямую.
+   */
+  enum class Mechanics : uint8_t {
+    ADVANCE = 0,
+    DIRECT  = 1,
+  };
+
+  /**
+   * @brief Получатель платежа в item-е.
+   *   SELF    — сам создатель СЗ.
+   *   MEMBER  — другой пайщик.
+   *   ORG     — внешняя организация.
+   */
+  enum class RecipientType : uint8_t {
+    SELF   = 0,
+    MEMBER = 1,
+    ORG    = 2,
+  };
+
+  enum class ProposalStatus : uint8_t {
+    CREATED          = 0,  ///< СЗ создан, ждёт подписи signact1 создателя.
+    AUTHORIZED       = 1,  ///< СЗ подписан signact2 (совет), готов к оплате.
+    PARTIALLY_PAID   = 2,  ///< Часть item-ов оплачена.
+    REPORT_SUBMITTED = 3,  ///< Отчёт о расходе подан, ждёт авторизации совета.
+    CLOSED           = 4,  ///< СЗ-отчёт авторизован — расход закрыт.
+    DECLINED         = 5,  ///< СЗ отклонён до или после авторизации.
+  };
+
+  enum class ItemStatus : uint8_t {
+    APPROVED  = 0,  ///< Запланирован, ждёт оплаты.
+    PAID      = 1,  ///< Оплачен (ADVANCE — выдан пайщику; DIRECT — оплачен организации).
+    REPORTED  = 2,  ///< Закрыт отчётом (чек приложен). DIRECT-item получает его сразу при payexp.
+    RETURNED  = 3,  ///< Зарезервировано, не используется: returnexp уменьшает actual_amount, статус остаётся PAID до отчёта.
+    OVERSPENT = 4,  ///< Зарезервировано, не используется: overspendexp увеличивает actual_amount, статус остаётся PAID до отчёта.
+  };
+
+  /**
+   * @brief Callback на финализацию — устанавливается при createexp как переменная.
+   *
+   * Контракт expense не знает про capital/blagorost — он просто вызывает inline
+   * action на (contract, action) и прокидывает data наружу. Пустой contract = нет callback.
+   *
+   * Пример: для расхода в РИД-проект Благороста UI/backend заполняет
+   * { "capital"_n, "onexpreport"_n, packed(wip_project_hash) }.
+   */
+  struct callback_handler {
+    eosio::name        contract;
+    eosio::name        action;
+    std::vector<char>  data;
+    EOSLIB_SERIALIZE(callback_handler, (contract)(action)(data))
+  };
+
+  /**
+   * @brief Item — одна строка СЗ-расхода.
+   */
+  struct item {
+    eosio::checksum256 item_hash;
+    uint8_t            mechanics;         ///< Mechanics
+    uint8_t            recipient_type;    ///< RecipientType
+    eosio::name        recipient;         ///< username (для SELF/MEMBER), либо name-идентификатор (для ORG)
+    std::string        description;
+    eosio::asset       planned_amount;
+    eosio::asset       actual_amount;     ///< 0 пока не оплачено / не отчиталось
+    uint8_t            status;            ///< ItemStatus
+
+    EOSLIB_SERIALIZE(item, (item_hash)(mechanics)(recipient_type)(recipient)(description)(planned_amount)(actual_amount)(status))
+  };
+
+  /**
+   * @brief Таблица СЗ-расходов. Scope = coopname.
+   */
+  struct [[eosio::table, eosio::contract("expense")]] proposal {
+    uint64_t              id;
+    eosio::name           coopname;       ///< кооператив (= scope таблицы; дублируем полем по канону)
+    eosio::checksum256    proposal_hash;
+    eosio::name           username;       ///< создатель
+    eosio::name           source_wallet;  ///< семантически — из какого ЦПП/фонда (w.cap.blago, w.sov.expns, …)
+    uint8_t               status;         ///< ProposalStatus
+    std::vector<item>     items;
+    eosio::asset          total_planned;
+    eosio::asset          total_actual;
+    callback_handler      callback;       ///< опционально; contract.value == 0 = нет callback
+    document2             statement_doc;  ///< type=2010, signact1 создателя
+    document2             decision_doc;   ///< type=2011, signact2 совета
+    eosio::time_point_sec created_at;
+    eosio::time_point_sec updated_at;
+
+    uint64_t primary_key()      const { return id; }
+    eosio::checksum256 by_hash() const { return proposal_hash; }
+    uint64_t by_username()      const { return username.value; }
+    uint64_t by_status()        const { return static_cast<uint64_t>(status); }
+
+    EOSLIB_SERIALIZE(proposal,
+      (id)(coopname)(proposal_hash)(username)(source_wallet)(status)
+      (items)(total_planned)(total_actual)(callback)(statement_doc)(decision_doc)
+      (created_at)(updated_at))
+  };
+
+  using proposals_index = eosio::multi_index<"proposals"_n, proposal,
+    eosio::indexed_by<"byhash"_n,     eosio::const_mem_fun<proposal, eosio::checksum256, &proposal::by_hash>>,
+    eosio::indexed_by<"byusername"_n, eosio::const_mem_fun<proposal, uint64_t, &proposal::by_username>>,
+    eosio::indexed_by<"bystatus"_n,   eosio::const_mem_fun<proposal, uint64_t, &proposal::by_status>>
+  >;
+
+} // namespace ExpenseDomain
+
+/**
+ *  @ingroup public_contracts
+ *  @brief Шасси расходов — 8 actions, MVP только Благорост.
+ */
+class [[eosio::contract("expense")]] expense : public contract {
+public:
+    using contract::contract;
+
+    /**
+     * @brief Создать и подать СЗ-расход.
+     *
+     * Создание и подача — одна транзакция (slug createexp). На входе: items + источник
+     * (source_wallet) + опц. callback на финализацию.
+     * Подписывает создатель (signact1 statement_doc, type=2010).
+     *
+     * Авторизация: coopname (прямой вызов backend'а) либо контракт-инициатор из
+     * contracts_whitelist (inline, например capital::createpgexp).
+     * Механика оплаты — per-item (item.mechanics: ADVANCE | DIRECT); ledger2-код
+     * операции выводится из механики позиции в момент оплаты payexp.
+     *
+     * Ставит вопрос в повестку совета (soviet::createagenda, тип createexp):
+     * утверждение совета → callback authexp, отклонение → declexp.
+     */
+    [[eosio::action]]
+    void createexp(name coopname, name username,
+                   checksum256 proposal_hash,
+                   name source_wallet,
+                   std::vector<ExpenseDomain::item> items,
+                   ExpenseDomain::callback_handler callback,
+                   document2 statement);
+
+    /**
+     * @brief Авторизовать СЗ советом (signact2 decision_doc, type=2011).
+     * Callback решения совета — вызывается только контрактом soviet после
+     * голосования и утверждения председателем. После этого расход доступен для оплаты.
+     */
+    [[eosio::action]]
+    void authexp(name coopname, checksum256 proposal_hash, document2 decision);
+
+    /**
+     * @brief Отклонить СЗ. Callback решения совета (отрицательный консенсус
+     * голосов «против» либо просрочка повестки) — вызывается только контрактом
+     * soviet. Возможно только до первой оплаты (CREATED / AUTHORIZED):
+     * после payexp средства уже ушли через ledger2, и СЗ завершается обычным
+     * путём reportexp / returnexp → closeexp.
+     */
+    [[eosio::action]]
+    void declexp(name coopname, checksum256 proposal_hash, std::string reason);
+
+    /**
+     * @brief Оплатить item — выдача аванса (ADVANCE) или прямая оплата организации (DIRECT).
+     * Контракт зовёт Ledger2::apply с кодом из набора операций кошелька-источника
+     * (EXPENSE_OPERATION_SETS: source_wallet + механика item'а → operation_code).
+     * actual_amount не может превышать план item (доплата — через overspendexp).
+     * DIRECT-item не имеет фазы подотчёта и помечается REPORTED сразу; когда все
+     * items REPORTED — proposal переходит в REPORT_SUBMITTED прямо из payexp.
+     */
+    [[eosio::action]]
+    void payexp(name coopname, checksum256 proposal_hash, checksum256 item_hash,
+                asset actual_amount);
+
+    /**
+     * @brief Отчёт о расходе (ADVANCE) — пайщик закрывает item чеком.
+     * Зовёт Ledger2::apply(o.exp.advrpt) на остаточный actual item'а (при полном
+     * возврате аванса burn пропускается). Когда все items reported — статус
+     * proposal становится REPORT_SUBMITTED.
+     */
+    [[eosio::action]]
+    void reportexp(name coopname, checksum256 proposal_hash, checksum256 item_hash);
+
+    /**
+     * @brief Закрытие расхода советом — финальный signact2 СЗ-отчёта.
+     * Если у proposal заполнен callback — отправляет inline action на (callback.contract, callback.action, callback.data).
+     */
+    [[eosio::action]]
+    void closeexp(name coopname, checksum256 proposal_hash);
+
+    /**
+     * @brief Возврат неиспользованного аванса (ADVANCE-остаток).
+     * Settlement-запись: уменьшает actual_amount item'а, статус остаётся PAID —
+     * фактически потраченная часть закрывается затем штатным reportexp.
+     * Зовёт Ledger2::apply(o.exp.advret).
+     */
+    [[eosio::action]]
+    void returnexp(name coopname, checksum256 proposal_hash, checksum256 item_hash,
+                   asset return_amount);
+
+    /**
+     * @brief Доплата при перерасходе (ADVANCE).
+     * Settlement-запись: увеличивает actual_amount item'а, статус остаётся PAID.
+     * Зовёт Ledger2::apply(o.exp.over) — выдача доплаты; закрытие подотчёта на
+     * полную сумму (выдано + доплата) делает последующий reportexp.
+     */
+    [[eosio::action]]
+    void overspendexp(name coopname, checksum256 proposal_hash, checksum256 item_hash,
+                      asset overspend_amount);
+};

components/contracts/cpp/ledger2/src/adjust/revert.cpp

@@ -67,12 +67,12 @@ void ledger2::revert(eosio::name coopname,
   eosio::check(original_operation_id != 0, "revert: original_operation_id обязателен");
 
   // -------- validate mirror_wallet_op --------
-  eosio::check(mirror_wallet_op <= 5, "revert: неизвестный mirror_wallet_op");
-  // Не позволяем откатывать через BLOCK/UNBLOCK — они асимметричны и нет
-  // адекватного зеркала в одной операции (BLOCK + UNBLOCK — обратные сами по себе).
-  eosio::check(mirror_wallet_op != static_cast<uint8_t>(WalletOp::BLOCK) &&
-               mirror_wallet_op != static_cast<uint8_t>(WalletOp::UNBLOCK),
-               "revert: BLOCK/UNBLOCK не подлежат откату через revert (они симметричны сами себе)");
+  // Зеркало revert — только TRANSFER (обмен wallet_from/wallet_to) либо BURN
+  // (зеркало ISSUE: изъятие с wallet_from). Бывшие BLOCK/UNBLOCK упразднены
+  // (2026-05-24); ISSUE/NONE как зеркало смысла не имеют.
+  eosio::check(mirror_wallet_op == static_cast<uint8_t>(WalletOp::TRANSFER) ||
+               mirror_wallet_op == static_cast<uint8_t>(WalletOp::BURN),
+               "revert: mirror_wallet_op должен быть TRANSFER или BURN");
 
   // -------- validate mirror wallets/accounts --------
   if (mirror_wallet_from.value != 0) {

components/contracts/cpp/ledger2/src/common/walletop.cpp

@@ -1,5 +1,5 @@
 /**
- * @brief Атомарная операция по кошельку (issue/transfer/block/unblock/burn/burn_blocked).
+ * @brief Атомарная операция по кошельку (issue/transfer/burn).
  *
  * Внутренний action ledger2 — вызывается только через inline из apply().
  * Auth: только сам ledger2 (require_auth(get_self())).
@@ -53,13 +53,15 @@ void ledger2::walletop(eosio::name coopname,
   eosio::check(amount.symbol == _root_govern_symbol,
                "walletop: некорректный символ валюты");
   eosio::check(memo.size() < 256, "walletop: memo > 255");
-  // op_code = 5 (NONE) намеренно не допускается: NONE-операции — это только
-  // бухпроводка без кошелькового движения, apply.cpp не диспатчит для них walletop.
-  // Прямой вызов с op_code=5 был бы no-op и сбил бы инвариант parity.
-  // Допустимы 0..4 (ISSUE/TRANSFER/BLOCK/UNBLOCK/BURN) и 6 (BURN_BLOCKED).
-  eosio::check(op_code <= static_cast<uint8_t>(WalletOp::BURN_BLOCKED) &&
-               op_code != static_cast<uint8_t>(WalletOp::NONE),
-               "walletop: неизвестный op_code");
+  // Допустимы только ISSUE(0), TRANSFER(1), BURN(4). NONE(5) — это только
+  // бухпроводка без кошелькового движения, apply.cpp для неё walletop не диспатчит;
+  // прямой вызов был бы no-op и сбил бы parity. Бывшие BLOCK(2)/UNBLOCK(3)/
+  // BURN_BLOCKED(6) упразднены (2026-05-24): резерв возврата теперь TRANSFER на
+  // w.wal.wpend, их op_code больше не валиден.
+  eosio::check(op_code == static_cast<uint8_t>(WalletOp::ISSUE) ||
+               op_code == static_cast<uint8_t>(WalletOp::TRANSFER) ||
+               op_code == static_cast<uint8_t>(WalletOp::BURN),
+               "walletop: недопустимый op_code");
 
   wallets2_index   wallets(get_self(), coopname.value);
   userwallets_index user_wallets(get_self(), coopname.value);
@@ -172,7 +174,7 @@ void ledger2::walletop(eosio::name coopname,
   // миграций 048/049.
   //
   // walletop по построению применяет одно и то же `amount` к L2 и L3 (см.
-  // ниже case'ы ISSUE/TRANSFER/BLOCK/UNBLOCK/BURN/BURN_BLOCKED), а sender-guard на
+  // ниже case'ы ISSUE/TRANSFER/BURN), а sender-guard на
   // строке 46-47 запрещает обход. Поэтому инвариант сохраняется по
   // конструкции; полную сверку выполняет бэкенд («стол бухгалтера»),
   // вне транзакционного hot path.
@@ -227,60 +229,6 @@ void ledger2::walletop(eosio::name coopname,
       cleanup_l3_if_empty(wallet_from);
       break;
     }
-    case WalletOp::BLOCK: {
-      eosio::check(wallet_from.value != 0, "walletop BLOCK: требуется wallet_from");
-      eosio::check(wallet_to.value == 0, "walletop BLOCK: wallet_to должен быть пустым");
-
-      auto it = wallets.find(wallet_from.value);
-      eosio::check(it != wallets.end() && it->available >= amount,
-                   std::string{"walletop BLOCK: недостаточно available на кошельке "} +
-                     wallet_from.to_string());
-      wallets.modify(it, payer, [&](auto& w) {
-        w.available -= amount;
-        w.blocked   += amount;
-      });
-
-      if (is_user_shared_l3(wallet_from)) {
-        auto uw = find_l3(wallet_from);
-        eosio::check(uw != user_wallets.get_index<"byuserwallet"_n>().end() &&
-                     uw->available >= amount,
-                     std::string{"walletop BLOCK: недостаточно L3-available у пайщика "} +
-                       username.to_string() + " на " + wallet_from.to_string());
-        auto uw_pri = user_wallets.find(uw->id);
-        user_wallets.modify(uw_pri, payer, [&](auto& r) {
-          r.available -= amount;
-          r.blocked   += amount;
-        });
-      }
-      break;
-    }
-    case WalletOp::UNBLOCK: {
-      eosio::check(wallet_from.value != 0, "walletop UNBLOCK: требуется wallet_from");
-      eosio::check(wallet_to.value == 0, "walletop UNBLOCK: wallet_to должен быть пустым");
-
-      auto it = wallets.find(wallet_from.value);
-      eosio::check(it != wallets.end() && it->blocked >= amount,
-                   std::string{"walletop UNBLOCK: недостаточно blocked на кошельке "} +
-                     wallet_from.to_string());
-      wallets.modify(it, payer, [&](auto& w) {
-        w.blocked   -= amount;
-        w.available += amount;
-      });
-
-      if (is_user_shared_l3(wallet_from)) {
-        auto uw = find_l3(wallet_from);
-        eosio::check(uw != user_wallets.get_index<"byuserwallet"_n>().end() &&
-                     uw->blocked >= amount,
-                     std::string{"walletop UNBLOCK: недостаточно L3-blocked у пайщика "} +
-                       username.to_string() + " на " + wallet_from.to_string());
-        auto uw_pri = user_wallets.find(uw->id);
-        user_wallets.modify(uw_pri, payer, [&](auto& r) {
-          r.blocked   -= amount;
-          r.available += amount;
-        });
-      }
-      break;
-    }
     case WalletOp::BURN: {
       eosio::check(wallet_from.value != 0, "walletop BURN: требуется wallet_from");
       eosio::check(wallet_to.value == 0, "walletop BURN: wallet_to должен быть пустым");
@@ -311,30 +259,6 @@ void ledger2::walletop(eosio::name coopname,
       eosio::check(false, "walletop NONE: запрещённый op_code");
       break;
     }
-    case WalletOp::BURN_BLOCKED: {
-      eosio::check(wallet_from.value != 0, "walletop BURN_BLOCKED: требуется wallet_from");
-      eosio::check(wallet_to.value == 0, "walletop BURN_BLOCKED: wallet_to должен быть пустым");
-
-      auto it = wallets.find(wallet_from.value);
-      eosio::check(it != wallets.end() && it->blocked >= amount,
-                   std::string{"walletop BURN_BLOCKED: недостаточно blocked на кошельке "} +
-                     wallet_from.to_string());
-      wallets.modify(it, payer, [&](auto& w) { w.blocked -= amount; });
-
-      if (is_user_shared_l3(wallet_from)) {
-        auto uw = find_l3(wallet_from);
-        eosio::check(uw != user_wallets.get_index<"byuserwallet"_n>().end() &&
-                     uw->blocked >= amount,
-                     std::string{"walletop BURN_BLOCKED: недостаточно L3-blocked у пайщика "} +
-                       username.to_string() + " на " + wallet_from.to_string());
-        auto uw_pri = user_wallets.find(uw->id);
-        user_wallets.modify(uw_pri, payer, [&](auto& r) { r.blocked -= amount; });
-      }
-
-      cleanup_l2_if_empty(wallet_from);
-      cleanup_l3_if_empty(wallet_from);
-      break;
-    }
   }
 
   // Post-mutation Σ L3 == L2: см. блок выше (строки 163-175). Снято

components/contracts/cpp/ledger2/src/migrate/migrate.cpp

@@ -1,4 +1,4 @@
-#include <vector>
+#include <array>
 
 /**
  * @brief Универсальное миграционное действие контракта ledger2 — точка
@@ -9,23 +9,33 @@
  * после её прогона на проде тело очищается до пустого `require_auth(get_self())`
  * (как в `capital::migrate`).
  *
- * Текущая задача (2026-05-21): чистка осиротевших L3-записей `w.cap.gen`
- * на voskhod после смены WalletKind GENERATOR_FUND с USER_SHARED на
- * COOPERATIVE (см. `lib/core/ledger2/wallets.hpp`).
+ * Текущая задача (2026-05-24): свёртка `blocked → available` по ВСЕМ коопам.
  *
- * Контекст: на voskhod `convertsegm` падал «недостаточно L3-средств у
- * пайщика» в проектах, где CRPS перераспределял доли между сегментами.
- * w.cap.gen был USER_SHARED, а CRPS в approvecmmt не делал per-user
- * компенсирующих TRANSFER между сегментами: `Σ COMMIT_RID == Σ ACCEPT_RID`
- * соблюдался только на проекте, не на пайщике.
+ * Контекст: механика «заблокированного» баланса упразднена (см.
+ * `lib/core/ledger2/operations.hpp` — удалены WalletOp BLOCK/UNBLOCK/BURN_BLOCKED;
+ * резерв возврата паевого теперь выражается переводом на кошелёк-резерв
+ * `w.wal.wpend`). Поле `blocked` остаётся в таблицах `wallets2`/`userwallets`
+ * как deprecated (физическое удаление поля = небезопасная смена layout таблицы
+ * на живых коопах, выносится в отдельный cleanup-деплой). Перед тем как поле
+ * перестанет поддерживаться кодом, накопленные `blocked`-остатки нужно вернуть
+ * в `available`, чтобы средства не «зависли» на упразднённом субсчёте.
  *
- * Архитектурный фикс: w.cap.gen — COOPERATIVE-пул без L3. Чтобы UI/бэкенд
- * не врали остатками по «личным» w.cap.gen, удаляем осиротевшие L3-записи
- * прямым `userwallets.erase`. L2-баланс `wallets2[w.cap.gen]` уже верен
- * (синхронен с Σ старых userwallets), его не трогаем.
+ * Действие: пройти всех кооперативов (cooperatives2 в scope registrator) и для
+ * каждого свернуть `blocked → available` на уровнях L2 (`wallets2`) и L3
+ * (`userwallets`): `available += blocked; blocked = 0`. Сумма средств на кошельке
+ * не меняется — только субсчёт.
  *
- * Идемпотентно: повторный вызов на чистой БД — no-op (lower_bound пуст).
- * Только voskhod: на остальных кооперативах w.cap.gen не использовался.
+ * Идемпотентно: после свёртки `blocked == 0`, повторный прогон — no-op.
+ *
+ * Сигнатура без аргументов — действие вызывается автоматически при деплое
+ * контракта (как и прочие задачи migrate); проходит по всем кооперативам сам.
+ *
+ * ПРЕДУСЛОВИЕ (операционное): на момент прогона не должно быть заявок на возврат
+ * «в полёте» (статусы pending/authorized в `wallet::withdraws`) — их `blocked`
+ * относится к старой механике и при свёртке в `available` вернётся пайщику как
+ * свободные средства, а последующий `completewthd` (BURN с `w.wal.wpend`) не
+ * найдёт резерва. Незавершённые заявки нужно довести (complete/decline) ДО
+ * деплоя с этой миграцией.
  *
  * @ingroup public_ledger2_actions
  *
@@ -34,24 +44,101 @@
 void ledger2::migrate() {
   require_auth(get_self());
 
-  const eosio::name target_coop = "voskhod"_n;
+  cooperatives2_index coops(_registrator, _registrator.value);
 
-  userwallets_index user_wallets(get_self(), target_coop.value);
-  auto idx = user_wallets.get_index<"bywallet"_n>();
+  for (auto c = coops.begin(); c != coops.end(); ++c) {
+    const eosio::name coopname = c->username;
 
-  // Собираем primary id записей до erase (модификация контейнера при
-  // итерации через secondary index — небезопасна).
-  std::vector<uint64_t> ids_to_erase;
-  for (auto it = idx.lower_bound(ledger2_wallets::GENERATOR_FUND.value);
-       it != idx.end() && it->wallet_name == ledger2_wallets::GENERATOR_FUND;
-       ++it) {
-    ids_to_erase.push_back(it->id);
+    // --- L3: userwallets[coopname] ---
+    // Модифицируем только не-ключевые поля (available/blocked) — итерация по
+    // первичному индексу с modify безопасна (порядок строк не меняется).
+    userwallets_index user_wallets(get_self(), coopname.value);
+    for (auto it = user_wallets.begin(); it != user_wallets.end(); ++it) {
+      if (it->blocked.amount <= 0) continue;
+      user_wallets.modify(it, get_self(), [&](auto& r) {
+        r.available += r.blocked;
+        r.blocked    = eosio::asset(0, r.blocked.symbol);
+      });
+    }
+
+    // --- L2: wallets2[coopname] ---
+    wallets2_index wallets(get_self(), coopname.value);
+    for (auto it = wallets.begin(); it != wallets.end(); ++it) {
+      if (it->blocked.amount <= 0) continue;
+      wallets.modify(it, get_self(), [&](auto& w) {
+        w.available += w.blocked;
+        w.blocked    = eosio::asset(0, w.blocked.symbol);
+      });
+    }
   }
 
-  for (uint64_t id : ids_to_erase) {
-    auto pri = user_wallets.find(id);
-    if (pri != user_wallets.end()) {
-      user_wallets.erase(pri);
+  // ──────────────────────────────────────────────────────────────────────────
+  // Разовая коррекция СЧЕТОВ под удаление фантомных пайщиков fgrtejiwnynn
+  // (инцидент 2026-06-04). Каждый из 6 дублей-аккаунтов при регистрации внёс
+  // минимальный паевой 300 RUB (o.reg.putmin: Dr 51 / Cr 80, ISSUE w.reg.minshr).
+  // Эти суммы — фантомные (нет реального пайщика), их нужно убрать из паевого
+  // фонда и с расчётного счёта. Снимаем L3-доли фантомов на w.reg.minshr,
+  // суммируем фактически снятое и ровно на эту сумму уменьшаем L2-кошелёк и
+  // бухсчета 80 (Cr) и 51 (Dr). Реальные пайщики (их доли на том же w.reg.minshr
+  // и счетах) не затрагиваются — трогаем только перечисленные username.
+  //
+  // Список синхронизирован с registrator::migrate и soviet::migrate.
+  // Идемпотентно: после первого прогона L3-строк фантомов нет → removed == 0 →
+  // L2/бухсчета не трогаются (вся коррекция в одной atomic-tx).
+  {
+    const eosio::name PHANTOM_COOP = "fgrtejiwnynn"_n;
+    const std::array<eosio::name, 6> PHANTOMS = {
+      "bbsezpgufvmm"_n, "errwcgjwverm"_n, "hcfsluqsfehw"_n,
+      "kgkzdadfpzki"_n, "nzuyijobapsv"_n, "tplwfwbujugq"_n,
+    };
+    const eosio::name MINSHR = ledger2_wallets::MIN_SHARE_FUND; // w.reg.minshr
+
+    eosio::asset removed(0, _root_govern_symbol);
+
+    // 1) Снимаем L3-доли фантомов на w.reg.minshr, суммируем снятое.
+    userwallets_index uw(get_self(), PHANTOM_COOP.value);
+    auto uw_byuser = uw.get_index<"byuser"_n>();
+    for (const auto& u : PHANTOMS) {
+      auto it = uw_byuser.lower_bound(u.value);
+      while (it != uw_byuser.end() && it->username == u) {
+        if (it->wallet_name == MINSHR) {
+          removed += it->available + it->blocked;
+          it = uw_byuser.erase(it);
+        } else {
+          ++it;
+        }
+      }
+    }
+
+    if (removed.amount > 0) {
+      // 2) L2 w.reg.minshr: available -= removed; удалить кошелёк, если опустел.
+      wallets2_index w2(get_self(), PHANTOM_COOP.value);
+      auto wit = w2.find(MINSHR.value);
+      if (wit != w2.end()) {
+        w2.modify(wit, get_self(), [&](auto& w) { w.available -= removed; });
+        if (wit->is_empty()) w2.erase(wit);
+      }
+
+      // 3) Бухсчета (scope=coopname): Cr 80 (паевой фонд) -= removed,
+      //    Dr 51 (расчётный счёт) -= removed; пересчёт сальдо по типу счёта.
+      //    Инвариант Σ Dr == Σ Cr сохраняется (обе стороны уменьшены на removed).
+      accounts2_index acc(get_self(), PHANTOM_COOP.value);
+
+      auto a80 = acc.find(ledger2_accounts::SHARE_FUND);
+      if (a80 != acc.end()) {
+        acc.modify(a80, get_self(), [&](auto& a) {
+          a.credit_balance -= removed;
+          a.balance = account2::compute_balance(a.account_type, a.debit_balance, a.credit_balance);
+        });
+      }
+
+      auto a51 = acc.find(ledger2_accounts::BANK_ACCOUNT);
+      if (a51 != acc.end()) {
+        acc.modify(a51, get_self(), [&](auto& a) {
+          a.debit_balance -= removed;
+          a.balance = account2::compute_balance(a.account_type, a.debit_balance, a.credit_balance);
+        });
+      }
     }
   }
 }

components/contracts/cpp/lib/consts.hpp

@@ -102,7 +102,10 @@ static const std::set<eosio::name> soviet_actions = {
 
     //WALLET
     "createwthd"_n, //создать заявление на возврат паевого взноса
-    
+
+    //EXPENSE
+    "createexp"_n, //служебная записка-смета о расходах (шасси расходов)
+
     //LEDGER
     "ledgerwthd"_n, //заявление на списание со счета через ledger
     
@@ -165,6 +168,7 @@ static constexpr uint64_t _capital_program_id = 4;
     static constexpr eosio::name _ledger = "ledger"_n;
     static constexpr eosio::name _ledger2 = "ledger2"_n;
     static constexpr eosio::name _apps = "apps"_n;
+    static constexpr eosio::name _expense = "expense"_n;
     static constexpr eosio::name _power_account = "eosio.power"_n;
     static constexpr eosio::name _saving_account = "eosio.saving"_n;
     
@@ -193,7 +197,8 @@ static constexpr uint64_t _capital_program_id = 4;
         "ledger"_n,
         "ledger2"_n,
         "capital"_n,
-        "apps"_n
+        "apps"_n,
+        "expense"_n
         // Добавьте остальные стандартные или пользовательские контракты по необходимости
       };
 
@@ -239,7 +244,7 @@ static constexpr uint64_t _capital_program_id = 4;
 #ifdef IS_TESTNET
     static constexpr uint64_t MIN_SOVIET_MEMBERS_COUNT = 1; /*!< минимальное количество членов совета (тест) */
 #else
-    static constexpr uint64_t MIN_SOVIET_MEMBERS_COUNT = 5; /*!< минимальное количество членов совета (прод) */
+    static constexpr uint64_t MIN_SOVIET_MEMBERS_COUNT = 3; /*!< минимальное количество членов совета (прод) */
 #endif
 
 /**