DID and VC services

Проект содержит два REST сервиса:

• DID service хранит DID Documents, историю версий и tombstone после деактивации.

• VC service хранит Verifiable Credentials и проверяет их через DID service.

Связь сервисов сделана через внутренний gRPC API DID service. VC service при создании и проверке credential резолвит issuer DID и subject DID. Если DID не найден или деактивирован, credential не считается валидным.

Функционал

DID service

• создать DID Document

• получить DID Document

• получить список DID с фильтром по deactivated

• полностью заменить DID Document

• частично обновить DID Document через JSON Merge Patch

• деактивировать DID без физического удаления

• получить историю версий

• получить конкретную версию

• parse DID и DID URL

• resolve DID

• dereference ключа или service по DID URL

VC service

• создать Verifiable Credential

• получить credential по id

• получить список credentials по subject DID

• получить статус credential

• отозвать credential

• проверить credential

• проверить связь с DID service при создании и verify

VC принимаются подписанными издателем (Content-Type: application/vc+jwt, ключ из assertionMethod DID издателя) и перепроверяются в verify — cryptographicallyVerified: true. Режим задаёт VC_PROOF: off, optional (по умолчанию), required. Проверка цепочки сертификатов и ГОСТ — за PKI-сервисом. Подробно — сценарий подписанных VC.

Подписанные операции DID

• публичные ключи в verificationMethod проверяются по существу: декодирование, длина, точка на кривой, x5c

• создание, изменение и деактивация DID подписываются контроллером или владельцем (owner) документа — заголовок DID-Operation-Proof

• режим задаёт DID_OPERATION_PROOF: off, optional (по умолчанию), required

• ревизии образуют хэш-цепочку, GET /v1/dids/{did}/history/verify перепроверяет историю

• утилита cmd/didsign создаёт ключи и подписи для ручных проверок

Подробно — сценарий подписанных операций.

DID-метод did:ru

did:ru:<agent|device|org>:<id> — самосертифицируемый идентификатор (выводится из ключа), у агентов и устройств обязателен owner. Спецификация — docs/did-method-ru.md, черновик записи для реестра W3C — docs/did-method-registration.json (публикация спецификации по адресу из specification — до подачи). DID других методов (did:i:*, did:scada:*) принимаются как раньше.

Демо

• http://localhost:8081/portal — портал участников: три компании (орган по сертификации, изготовитель, покупатель) выпускают сертификаты соответствия, приборы, паспорта, метки, передают и принимают приборы.

• http://localhost:8081/scan, /s/<DID> — проверка прибора по метке: камера, фото метки или ссылка.

• http://localhost:8081/console — сценарии DiCE и ИИ-агента по шагам.

Весь функционал по шагам — docs/demo.md. Контракт для партнёров (метка, скан, выпуск документов, поля, ошибки) — docs/partner/README.md и openapi.yaml.

Запуск

Запустить оба сервиса и PostgreSQL:

docker compose up -d --build

Проверить контейнеры:

docker compose ps

DID Swagger:

http://localhost:8080/swagger

VC Swagger:

http://localhost:8081/swagger

Person VC demo form:

http://localhost:8081/person-demo

Health checks:

http://localhost:8080/api/health
http://localhost:8081/api/health

Debug reset локальной базы доступен только при DEBUG=TRUE:

curl -X POST http://localhost:8081/api/debug/reset-db

Команда очищает данные DID, VC и Person, но не трогает таблицу миграций.

Build

Собрать локальные бинарники:

make build

Собрать Docker images:

make docker-build

Собрать и запустить контейнеры одной командой:

docker compose up -d --build

Очистка

Остановить контейнеры без удаления данных:

make docker-down

Остановить контейнеры и удалить локальные volume с данными PostgreSQL:

docker compose down -v

Удалить локальные бинарники:

make clean

Сценарии для Swagger

Что можно проверить:

• DID basic scenario

• VC basic scenario

• DID VC link scenario

• Person and VC scenario

• Negative scenarios

• Signed DID operations

• Signed Verifiable Credentials

Основные endpoints

DID service использует base path /api:

• POST /v1/dids

• GET /v1/dids

• GET /v1/dids/{did}

• PUT /v1/dids/{did}

• PATCH /v1/dids/{did}

• POST /v1/dids/parse

• GET /v1/dids/resolve

• GET /v1/dids/dereference

• GET /v1/dids/{did}/history

• GET /v1/dids/{did}/history/{versionId}

• GET /v1/dids/{did}/history/verify

VC service использует base path /api:

• POST /v1/credentials

• GET /v1/credentials

• GET /v1/credentials/{id}

• GET /v1/credentials/{id}/status

• POST /v1/credentials/{id}/verify

• POST /v1/credentials/{id}/revoke

• GET /v1/scan — проверка прибора по метке одним вызовом (verdict, caveats, паспорт, сертификат, владелец)

• GET /v1/labels/{did}, GET /v1/labels/{did}/qr.svg|png — метка прибора

• GET /v1/schemas, GET /v1/schemas/{type} — состав полей документов (JSON Schema)

• POST /v1/persons

• GET /v1/persons

• GET /v1/persons/{id}

• PATCH /v1/persons/{id}

• POST /v1/persons/{id}/credentials

• GET /v1/persons/{id}/credentials

Переменные окружения

Для запуска без Docker Compose:

DATABASE_URL=postgres://did:did@localhost:5432/did?sslmode=disable
BACKEND_ADDRESS=:8080
DID_GRPC_ADDRESS=:9090
VC_HTTP_ADDRESS=:8081
VC_DATABASE_URL=postgres://did:did@localhost:5432/did?sslmode=disable
DID_GRPC_ADDR=localhost:9090
VC_PUBLIC_URL=http://localhost:8081
LOG_LEVEL=info
DEBUG=FALSE

• VC_PUBLIC_URL — адрес реестра в метках (<VC_PUBLIC_URL>/s/<DID>); фиксируется до печати меток.

• API_TOKENS (оба сервиса) — токены партнёров partner=token,partner2=token2, не короче 16 символов. Пусто — API открыт (подписи сторон действуют всегда). С токенами закрыты выпуск, отзыв, изменения DID, списки, поиск и ленты; скан, метки, схемы, получение DID, чтение и проверка документов остаются публичными.

• DID_API_TOKEN — токен, с которым VC-сервис (identity) обращается к DID-сервису при API_TOKENS.

• VC_SCHEMAS_FILE — свой состав полей документов вместо встроенного internal/vc/credschema/default.json.

Журнал изменений