التحقق من الردود

كل ردّ يرسله أنيس — نجاحًا كان أم رفضًا — موقَّع. يتخلّص العميل من أي ردّ لا يستطيع التحقق منه: لا يسجّله ثم يمضي، ولا يتصرف بناءً عليه. وردّ طلب الشراء الذي لا يمكن التحقق منه يُعامَل كأنه لم يصل قط — فالنتيجة مجهولة، ويُستأنف طلب الشراء بمعرّف العملية نفسه.

ما الذي يوقّعه أنيس

تُوقَّع الردود باستخدام ECDSA P-256 وSHA-256، بالتسمية sig1، مع المعاملات created وkeyid وalg — ودون expires. الأجزاء الموقّعة، بهذا الترتيب:

يُبنى نصّ التوقيع كما يُبنى في الاستدعاء: سطر واحد لكل جزء، ثم "@signature-params" دون محرف سطر جديد بعده.

"@status": 200
"content-digest": sha-256=:epGQsVay09pY/GXv6MpAjMbsZ7VvobF1nAdylVo/mMk=:
"x-request-id": 01J9R2K8T4V6XQ0M3B7C5D9E1F
"signature-input";req: sig1=("@method" "@authority" "@path" "@query" "x-anis-date");created=1789804800;expires=1789804860;keyid="…";alg="ecdsa-p256-sha256"
"@signature-params": ("@status" "content-digest" "x-request-id" "signature-input";req);created=1789804800;keyid="partner-response-signing/v1-active";alg="ecdsa-p256-sha256"

يقع ;req خارج علامات الاقتباس، بالشكل نفسه في سطره وفي @signature-params.

خطوات الفحص، بالترتيب

1. وجود Signature وSignature-Input كليهما؛ والتسمية هي sig1؛ وalg هو ecdsa-p256-sha256.
2. يطابق المحتوى ترويسة Content-Digest الخاصة به — ويُفحص ذلك قبل التوقيع. التوقيع يغطي ترويسة البصمة لا المحتوى، لذا فالعميل الذي يفحص التوقيع أولًا يقبل محتوى مستبدَلًا كلما أُعيدت كتابة البصمة هي الأخرى.
3. أعد بناء قائمة الأجزاء الموقّعة مما يحمله الردّ (الجدول أعلاه)، واشترط أن تذكر Signature-Input في الردّ تلك القائمة بالضبط. لا تثق أبدًا بالقائمة التي يعلنها الردّ: فالردّ الموقّع توقيعًا صحيحًا على قائمة أقصر يترك محتواه دون حماية.
4. تقع قيمة created ضمن 60 ثانية من ساعتك — فالردّ ليس له expires، ودون هذا الحدّ يمكن إعادة إرسال ردّ ملتقَط إليك إلى ما لا نهاية.
5. يسمّي keyid مفتاحًا من المفاتيح المنشورة لأنيس (أدناه).
6. التوقيع 64 بايتًا، ويجتاز التحقق على نصّ التوقيع المُعاد بناؤه.

أي شيء غير ذلك: تخلّص من الردّ. وتغطي أمثلة اختبار الردود كل فحص من هذه الفحوص.

المفاتيح العامة لأنيس

GET /.well-known/partner-signing-keys.json — المسار الوحيد الذي لا يحتاج إلى توقيع — ينشر كل مفتاح قد يوقّع ردًّا، بما في ذلك المفتاح التالي قبل تدوير المفاتيح، والمفتاح السابق بعده. لكلٍّ منها kid، وهو ما يسمّيه keyid في الردّ. تعامل مع kid على أنه اسم مُبهم (opaque).

• خزّن المستند مؤقتًا (cache). عندما يسمّي ردٌّ قيمة kid ليست لديك، اجلب المستند مجددًا مرة واحدة — فهذه هي العلامة المعتادة على تدوير المفاتيح. لا تُعِد الجلب بلا حدّ عند ظهور مفاتيح مجهولة.
• ارفض المستند بأكمله إذا حمل أيُّ مفتاح عنصرًا خاصًا (d) — لا ذلك المفتاح وحده. المستند الذي يُسرّب مفتاحًا خاصًا لا يُوثق به إطلاقًا.
• كل إحداثية طولها 32 بايتًا بالضبط. ارفض أي مفتاح بشكل مختلف.

الردّ الوحيد غير الموقّع

إذا تعذّر التوقيع لدى أنيس نفسه، فإنه يردّ بـ 503 دون توقيع. تعامل معه كأي ردّ لا تستطيع التحقق منه: أعد محاولة استدعاء القراءة، واستأنف طلب الشراء بمعرّف العملية نفسه.