ProofKit

التوثيق

الـ API ومواصفة الإيصال

عنوان واحد ومستند JSON واحد في الرد. الرد هو الإيصال الموقّع.

POST /api/v1/check

المحتوى: {"text": "…"} — UTF-8، من 5 إلى 20000 حرف. لا حاجة إلى مفتاح في الخطة المجانية.

curl -X POST https://proof.sapir861.com/api/v1/check \
  -H "content-type: application/json" \
  -d '{"text":"See Marbury v. Madison, 5 U.S. 137 (1803)."}'
الرمزالمعنى
200إيصال: {body, sig, digest, log}
400النص مفقود أو قصير جدًا أو يتجاوز 20000 حرف
429rate_limited (ذروة) أو monthly_limit — الخطة المجانية 100 إحالة شهريًا لكل شبكة

يبيّن رأس الرد x-proofkit-remaining عدد الإحالات المجانية المتبقية هذا الشهر. تحصل خطتا Pro وTeam على مفتاح API بحدود أعلى: أرسله بصيغة Authorization: Bearer pk_live_…، وسيتضمن الرد x-proofkit-plan. المفتاح غير الصالح يعيد 401 invalid_api_key؛ والخطة المنتهية تعود إلى الخطة المجانية.

حقول الإيصال

الحقلالوصف
body.specsapir-receipt/1
body.kindcitation-check
body.tsوقت الفحص بتوقيت UTC بصيغة ISO-8601
body.input_sha256SHA-256 للنص المُدخل كما هو (يثبت أي نص فُحص دون حفظه)
body.checkerالطريقة والمصدر المستخدمان
body.results[]jurisdiction (US|UK|EU|ECHR), cite, name, verdict, note, source, opinion, matched_case
verdictverified · mismatch (إحالة حقيقية لقضية أخرى) · not_found · ambiguous · exists_name_unchecked · unverifiable · unchecked
body.summarytotal, verified, flagged
body.keyمفتاح التوقيع العام (Ed25519، JWK x)
sigتوقيع Ed25519 ‏(base64url) على JSON القانوني لـ body
digestSHA-256 بالنظام الست عشري لـ JSON القانوني لـ body
logالموضع n وتجزئة السلسلة hash في سجل الشفافية العلني

JSON القانوني: مفاتيح الكائنات مرتبة، بلا مسافات، مع تهريب نصوص JSON القياسي، وتُحذف الحقول undefined.

التحقق

  1. رتّب body بالصيغة القانونية.
  2. يجب أن يساوي SHA-256 قيمة digest.
  3. تحقّق من sig بـ Ed25519 على البايتات نفسها بالمفتاح من /.well-known/proofkit-pubkey؛ ويجب أن يساوي body.key.x.
import { readFileSync } from "node:fs";   // node verify.mjs receipt.json  (Node 20+)
const r = JSON.parse(readFileSync(process.argv[2] || "receipt.json", "utf8"));
const canon = o => o === null || typeof o !== "object" ? JSON.stringify(o) : Array.isArray(o) ? "[" + o.map(canon).join(",") + "]"
  : "{" + Object.keys(o).sort().filter(k => o[k] !== undefined).map(k => JSON.stringify(k) + ":" + canon(o[k])).join(",") + "}";
const msg = new TextEncoder().encode(canon(r.body));
const hex = Buffer.from(await crypto.subtle.digest("SHA-256", msg)).toString("hex");
const pub = (await (await fetch("https://proof.sapir861.com/.well-known/proofkit-pubkey")).json()).jwk;
const key = await crypto.subtle.importKey("jwk", pub, { name: "Ed25519" }, false, ["verify"]);
const ok = await crypto.subtle.verify({ name: "Ed25519" }, key, Buffer.from(r.sig, "base64url"), msg);
console.log(ok && hex === r.digest && pub.x === r.body.key.x ? "VALID" : "INVALID");

الحدود. اقرأها قبل الاعتماد على النتيجة

  • التغطية: الولايات المتحدة — CourtListener (يعمل؛ بعض مجموعات الولايات والمجموعات القديمة غير مكتملة). المملكة المتحدة — Find Case Law (تجريبي؛ موثوق منذ 2022). الاتحاد الأوروبي — EUR-Lex، محكمة العدل والمحكمة العامة (تجريبي). المحكمة الأوروبية لحقوق الإنسان — HUDOC (تجريبي). لكل نتيجة حقل jurisdiction.
  • لا يمكن فحص إحالات Westlaw ‏(WL) وLexis وإحالات الملك العام في قاعدة مفتوحة، لذا تُصنّف unverifiable.
  • مطابقة الاسم تتم كلمة بكلمة (≥ 0.5). أسماء القضايا القصيرة جدًا أو غير المألوفة قد تعطي mismatch لقضية حقيقية. افتح رابط المصدر دائمًا.
  • نتحقق من وجود القضية وهويتها، لا من دعمها للحجة.