HTTP API

POST orders

Принять заказ (Audit.md §6). Тело — либо голый заказ, подписанный проверяемым и спонсором, либо конверт:

{"order": {…}, "scopeText": "что проверить", "contact": "любой текст, необязательно"}

В конверте order.scope.uri = <база>scopes/order-<orderId>.md, а SHA-256 от scopeText (1–8192 байт) равен order.scope.digest. Контакт — до 256 байт без управляющих символов; он не публикуется.

202 {"orderId", "state": "queued-for-review", "digest"} — заказ в очереди; это ещё не согласие аудитора.

Ошибки: 422 order_invalid, 409 order_conflict (под этим id уже другой заказ), 503 inbox_full (1000 заказов), 413 oversize, 429 rate_limited.

POST responses

Ответ проверяемого на аттестацию (Audit.md §5.7.5). Тело — голый подписанный ответ, до 16 КиБ; attestationId и responseId — 16–128 символов [A-Za-z0-9_-]. После записи список статусов переподписывается, и ответ появляется рядом с аттестацией.

201 {"uri", "digest"}

Ошибки: 404 attestation_unknown, 422 subject_response_invalid, 409 response_conflict — ответы неизменяемы.

POST hub/api/claim 5 токенов

Забронировать имя и получить делегированный ключ статусов, который манифест должен назвать.

{"slug": "my-auditor"}

Имя: ^[a-z][a-z0-9-]{2,31}$, не из зарезервированных (admin, api, hub, audit, onym, onym-audit, foundation, sobor, root, status, www). Бронь живёт 30 минут; повторный вызов в этот срок возвращает ту же бронь.

200 {"slug", "statusKey", "base", "componentId", "expires"}

Ошибки: 409 — имя занято; 422 — имя недопустимо.

POST hub/api/register 10 токенов

Опубликовать или заменить манифест вместе с документами, на которые он ссылается.

{"slug": "my-auditor",
 "manifest": {…подписанный манифест…},
 "docs": {"policies/independence.md": "текст", "offers/manual-review.json": "{…}", …}}

• componentId = onym:component:<имя>; statusEndpoint = <база>status.json; statusKey — выданный при claim;
• contact — любой текст до 256 байт без управляющих символов (ссылкой на страницах он становится, только если начинается с mailto: или https://);
• повторная регистрация — только тем же ключом оператора (иначе 403) и не старее текущей: validUntil не раньше, а при равном — те же байты (иначе 409);
• пути документов: (policies|methodology|scopes|reports|offers|notes)/<имя>.(md|json); принимаются только документы, на которые ссылается манифест;
• каждая ссылка манифеста указывает либо на файл этого аудитора, либо на общий документ основного места, и дайджест совпадает;
• оферты подписаны ключом аудитора, относятся к методике из манифеста, не истекли и не откатывают опубликованную версию.

201 {"page", "manifest", "digest"}

POST hub/api/a/{slug}/publish 5 токенов

Опубликовать аттестацию с её документами.

{"attestation": {…},
 "docs": {"scopes/….md": "…", "reports/….json": "…", "orders/<orderId>.json": "…"}}

• подписана ключом аудитора, status = statusEndpoint, unsolicited.policy = дайджест опубликованной политики;
• id новый: аттестации неизменяемы, исправление — новая аттестация, которая заменяет старую (supersede);
• методика, область, шкала и отчёт закреплены так же, как при регистрации;
• для engagement: "commissioned" прикладывается ровно один заказ с тремя подписями (проверяемый, спонсор, аудитор); orderRef — его дайджест; проверяемый, спонсор, артефакт, методика и область совпадают.

201 {"uri", "digest"} — опубликовано.
202 {"uri", "digest", "held": true, "releaseAt"} — провал по заказу с эмбарго: аттестация, отчёт, заказ и область удерживаются хабом и выходят сами, когда эмбарго кончится.

POST hub/api/a/{slug}/revoke 5 токенов

{"revocation": {…подписанный отзыв…}}

Отзыв принимается всегда, даже когда хранилище заполнено.

201 {"uri"}

Ошибки: 404 — нет аттестации; 409 — уже отозвана.

POST a/{slug}/responses 5 токенов

Ответ проверяемого на аттестацию аудитора хаба. Тело — голый подписанный ответ. Не больше 10 ответов на аттестацию; ответы неизменяемы (409).

201 {"uri"}

GET hub/api/a/{slug}/export

Список всех файлов дерева аудитора — чтобы перенести его на свой сервер: хаб — заменяемый вариант по умолчанию.

200 {"base", "files": ["manifest.json", …]}

POST hub/api/a/{slug}/stellar-link 5 токенов 🔏 ключ аудитора

Связать аудитора с его существующим аккаунтом в основной сети Stellar. Сначала владелец аккаунта одной транзакцией (кабинет аудитора формирует её сам, подписать можно любым кошельком: по QR-коду, ссылкой SEP-7 или в Stellar Lab) пишет на этот аккаунт две записи данных:

Так согласие обеих сторон видно в сети: аккаунт подписал транзакцию, ключ аудитора — доказательство. Аккаунту аудитора не нужно существовать в основной сети. Затем:

{"request": {"action": "stellar-link" | "stellar-unlink", "auditor": "onym:component:<имя>",
             "account": "G…", "issuedAt": "…", "signature": "…"}}

Хаб читает аккаунт на horizon.stellar.org и проверяет обе записи. Если всё сходится, он публикует сам подписанный запрос как a/<имя>/stellar-link.json; страница аудитора перепроверяет его в браузере так же.

201 {"account", "uri"}; stellar-unlink → {"unlinked": true} (записи на аккаунте удаляет их владелец).

Ошибки: 403 — подпись не ключа аудитора или несвежий запрос; 422 — записей нет, в них другой ключ или подпись не сходится.

POST a/{slug}/orders 10 токенов

{"order": {…}, "scopeText": "что проверить", "contact": "необязательно"}

• заказ подписан проверяемым и спонсором и точно соответствует оферте аудитора: методика, модель цены, условия раскрытия;
• fee.offerId — оферта из манифеста или rsp-…, ответ на ещё открытую заявку (тогда спонсор — автор заявки, а проверяемый, методика и артефакт совпадают с заявкой);
• scope.uri = <база>scopes/order-<orderId>.md, scopeText (1–8000 байт) хешируется в scope.digest;
• контакт необязателен: любой текст до 256 байт; его видит только аудитор.

202 {"orderId", "state": "queued-for-review", "digest"}. Заявка, на которую ответили офертой, закрывается.

Ошибки: 409 — заказ уже выполнен или под этим id другой; 503 — в очереди 100 заказов.

POST hub/api/a/{slug}/order-status 1 токен 🔏 ключ спонсора

{"request": {"action": "order-status", "orderId": "…", "sponsor": "onym:key:…",
             "issuedAt": "…", "signature": "…"}}

200 {"queued": bool, "held": bool} — ждёт ли заказ в очереди и не удерживается ли его результат под эмбарго. Никто, кроме владельца ключа заказа, этого не узнает.

POST hub/api/a/{slug}/inbox 2 токена 🔏 ключ аудитора

{"request": {"action": "list" | "decline", "auditor": "onym:component:<имя>",
             "orderId": "…только для decline", "issuedAt": "…", "signature": "…"}}

list → {"orders": [{"order", "scopeText", "contact", "receivedAt"}], "held": [{"attestationId", "releaseAt"}]}
decline → {"declined": "<orderId>"}

POST hub/api/requests 5 токенов

{"request": {
  "requestVersion": 1,
  "requestId": "req-<20 символов [a-z0-9]>",
  "to": null | "onym:key:…",
  "subject": "onym:component:<имя>",
  "methodologyClass": "security-review" | "conformance-run",
  "artifact": {"kind": "source" | "build" | "deployment", "source": "…", "revision": "…", "artifactHash": null},
  "scopeText": "1–8000 байт",
  "requester": "onym:key:…",
  "issuedAt": "…", "expiresAt": "… (не позже чем через 30 дней)",
  "signature": "…ключом requester"
}}

to: null — заявка видна всем; иначе только адресату. conformance-run принимается только для kind: "deployment".

201 {"requestId", "digest"}

Ошибки: 409 — такой id уже есть; 503 — открыто 500 заявок.

GET hub/api/requests

200 — открытые публичные заявки, от новых к старым: [{…заявка, "responses": N}].

POST hub/api/requests/for 2 токена 🔏 ключ адресата

{"request": {"action": "requests-for", "key": "onym:key:…", "issuedAt": "…", "signature": "…"}}

200 — заявки, адресованные этому ключу.

POST hub/api/requests/{id}/responses 5 токенов

Аудитор отвечает офертой.

{"slug": "my-auditor", "offer": {…}}

offerId = rsp-<суффикс requestId>; оферта подписана ключом аудитора, методика — из заявки; на адресную заявку отвечает только адресат; область закреплена; оферта не истекла и не откатывает прежнюю.

201 {"offer": "<uri>"}

Ошибки: 404 — заявка закрыта или истекла.

POST hub/api/requests/{id}/mine 2 токена 🔏 ключ автора заявки

{"request": {"action": "responses", "requestId": "…", "issuedAt": "…", "signature": "…"}}

200 {"open": bool, "responses": [{"slug", "name", "operator", "fingerprint", "page", "completedOrders", "customers", "offer"}]}

POST hub/api/vault 2 токена 🔏 ключ хранилища

Чтобы один и тот же заказчик видел свои заказы и заявки на любом устройстве, приложение хранит их список зашифрованным (AES-256-GCM, ключ выводится из фразы) под отдельным ключом подписи, выведенным из той же фразы. Хаб хранит шифртекст, который не может прочитать, под ключом, который больше нигде не встречается.

{"request": {"action": "get" | "put", "key": "onym:key:…", "data": "base64, только для put",
             "issuedAt": "…", "signature": "…"}}

get → {"data", "updatedAt"} или {"data": null}
put → {"updatedAt"}; данные — до 256 КиБ; всего на хабе — до 20 000 хранилищ.

POST hub/api/fetch 2 токена

{"url": "https://…"}

Только JSON и текст, до 1 МиБ (иначе 415).

200 {"url", "status", "contentType", "setsCookie", "digest", "size", "body"}

POST hub/api/digest 20 токенов

{"url": "https://…/app.apk"}

Хеширует файл потоком, до 300 МиБ, не возвращая его, — чтобы закрепить точные байты сборки.

200 {"url", "status", "digest", "size"}

POST hub/api/conformance/discovery 20 токенов

{"manifestUrl": "https://…/manifest.json"}

Запускает набор проверок соответствия Discovery-провайдера (42 проверки) против манифеста с "seat": "discovery"; к другим сервисам набор не применяется (422). Таймаут — 3 минуты.

200 — канонический отчёт: {suite, suiteVersion, runAt, manifestUri, result, documents: [{role, uri, digest, size}], checks: [{id, clause, level, title, outcome, detail}]}

GET hub/api/auditors

[{"slug", "name", "operator", "fingerprint", "page", "attestations", "offers", "completedOrders", "customers"}]

GET hub/api/seat

То же для основного места ("slug": "").

GET hub/api/library

Все аттестации всех аудиторов, от новых к старым. Это указатель, а не авторитет: каждую запись браузер проверяет по подписанным файлам.

[{"attestationId", "auditor", "auditorSlug", "auditorBase", "fingerprint", "subject", "result", "state", "methodologyClass", "kind", "source", "engagement", "issuedAt", "expiresAt", "orderRef", "uri"}]

curl -s https://foldy.io/audit/hub/api/library | jq '.[0]'