commonguy25/authproof-sdkإيصالات تفويض موقعة تشفيرياً للوكلاء الذكاء الاصطناعي. حدد بالضبط ما يمكن للذكاء الاصطناعي فعله وما لا يمكنه فعله — موقعة، قابلة للتحقق، مقاومة للتلاعب.
AuthProof هو بروتوكول تفويض تشفيري لوكلاء AI. معظم البروتوكولات في هذا المجال تنفذ ضد سياسة يحددها المشغل - مما يعطي المشغل سلطة توسيع أو إعادة تفسير نية المستخدم الأصلية بعد وقوع الحدث. AuthProof مبني على نموذج ثقة مختلف: المفتاح الخاص للمستخدم يوقع كائن التفويض الذي يتحكم في التنفيذ، ويتم التحقق من حالة النموذج الحية في وقت التفويض وقبل التنفيذ مباشرة. مزيج السلطة الموقعة من المستخدم والتحكم بحالة النموذج الحية هو الادعاء المحدد - وليس قصة إنفاذ واسعة.
ما الذي يجعله مختلفًا:
المستخدم هو سلطة التوقيع. كل بروتوكول منافس (AIP, AITH, OAP, SAGA, AgentSpec) ينفذ ضد سياسة يحددها المشغل. في AuthProof، يوقع المفتاح الخاص للمستخدم كائن التفويض مباشرة. لا يمكن للمشغل توسيع النطاق بعد أن وقع المستخدم.
التزام بحالة النموذج على مرحلتين. يتم قياس النموذج في وقت التفويض وإعادة قياسه مباشرة قبل التنفيذ. إذا انحرف النموذج بين هاتين النقطتين، يتم حظر التنفيذ في التحقق قبل التنفيذ.
تمييز تحديث المزود عن الاستبدال الخبيث. يصنف البروتوكول تغييرات حالة النموذج إلى فئتين: تحديثات المزود الشرعية (PROVIDER_UPDATE_REQUIRES_REAUTH) والتبديلات غير المصرح بها (MALICIOUS_MODEL_SUBSTITUTION). ينتج كل منهما رمز سبب رفض قابل للقراءة آليًا يحدد المكونات التي تغيرت.
البوابة الحتمية التي تعمل قبل تنفيذ أي إجراء للوكيل.
يجلس PreExecutionVerifier خارج بيئة تشغيل الوكيل. لا تحصل بيئة التشغيل على التحكم أبدًا حتى يمر المدقق. لا يمكن للوكيل المخترق أو الخبيث تخطيه — يعمل قبل بدء بيئة التشغيل.
تحدث عمليات التحقق التقليدية من التفويض داخل بيئة تشغيل الوكيل. إذا تم اختراق بيئة التشغيل، يمكن تخطي تلك الفحوصات أو إعادة ترتيبها أو تجاوزها. يلغي PreExecutionVerifier سطح الهجوم هذا عن طريق نقل التفويض خارج بيئة التشغيل بالكامل. لا ينفذ الوكيل إلا إذا — وفقط إذا — نجحت جميع الفحوصات الستة المتسلسلة أولاً.
import { PreExecutionVerifier, DelegationLog } from 'authproof-sdk/pre-execution-verifier' import { RevocationRegistry } from 'authproof-sdk'
// 1. Set up the gate const delegationLog = new DelegationLog() const revocationRegistry = new RevocationRegistry() await revocationRegistry.init({ privateKey, publicJwk })
const verifier = new PreExecutionVerifier({ delegationLog, revocationRegistry }) await verifier.init({ privateKey: verifierKey, publicJwk: verifierPub })
// 2. Register your delegation receipt delegationLog.add(receiptHash, receipt)
// 3. Gate every action â before the agent runs const result = await verifier.check({ receiptHash, action: { operation: 'read', resource: 'calendar' }, operatorInstructions: 'Summarize meetings. Stay within scope.', programHash, // optional: prevents code substitution attacks })
if (!result.allowed) {
throw new Error(Blocked: ${result.blockedReason})
}
// Agent runtime only reaches here after all six checks pass
### ستة فحوصات متسلسلة (تتوقف عند أول فشل)
| # | الفحص | يمنع عند |
|---|-------|-------------|
| 1 | توقيع الإيصال | توقيع ECDSA P-256 غير صالح أو الإيصال معدل |
| 2 | الإلغاء | تم إلغاء الإيصال عبر `RevocationRegistry` |
| 3 | النافذة الزمنية | الإيصال منتهي الصلاحية أو غير صالح بعد (أوراكل الطابع الزمني للسجل، وليس ساعة العميل) |
| 4 | النطاق | الإجراء غير موجود في `ScopeSchema.allowedActions` أو فشل مطابقة النطاق النصية |
| 5 | تعليمات المشغل | التعليمات الحالية لا تتطابق مع التجزئة المقفلة في الإيصال عند الإصدار |
| 6 | تجزئة البرنامج | `programHash` المقدمة لا تتطابق مع تجزئة `executes` الملتزمة (منع استبدال الكود) |
يتم تسجيل كل نتيجة فحص - سواء نجاح أو فشل - تلقائيًا في `ActionLog` غير قابل للتغيير موقّع بمفتاح المدقق الخاص.
### تكاملات الوسيطة
أغلفة جاهزة للإطارات الشائعة. يتحكم كل غلاف في كل استدعاء عبر `PreExecutionVerifier` قبل تنفيذ الكود المغلف.
- **[LangChain](https://github.com/commonguy25/authproof-sdk/blob/HEAD/src/middleware/langchain.js)** — يغلف أي وكيل بطريقة `invoke()`
- **[Express/HTTP](https://github.com/commonguy25/authproof-sdk/blob/HEAD/src/middleware/express.js)** — وسيطة طلب لأي إطار متوافق مع Express
- **[غلاف الدالة العامة](https://github.com/commonguy25/authproof-sdk/blob/HEAD/src/middleware/generic.js)** — يغلف أي دالة غير متزامنة```js
// LangChain
import { authproofMiddleware } from 'authproof-sdk/middleware/langchain'
const guardedAgent = authproofMiddleware(agent, { receiptHash, verifier })
// Express
import { authproofMiddleware } from 'authproof-sdk/middleware/express'
app.use(authproofMiddleware({ verifier, getReceiptHash: (req) => req.headers['x-receipt-hash'] }))
// Any function
import { guardFunction } from 'authproof-sdk/middleware/generic'
const guardedExecute = guardFunction(executeAction, { receiptHash, verifier, action })
كل إطار عمل حالي من IETF لهوية الوكيل — AIP, draft-klrc-aiagent-auth, WIMSE — يتناول الثقة من الخدمة إلى الوكيل: كيف تتحقق خدمة المصب من أن الوكيل مخوَّل باستدعائها. لا يتناول أي منها ثقة المستخدم إلى المشغل.
سلسلة التفويض في الأنظمة الوكيلة الحالية هي:``` User â Operator â Agent â Services
يوجّه المستخدم المُشغِّل. يوجّه المُشغِّل الوكيل. لكن لا يوجد أي سجل تشفيري لنية المستخدم الأصلية في لحظة التفويض. يصبح المُشغِّل طرفًا ثالثًا موثوقًا يتمتع بسلطة غير خاضعة للرقابة لتوسيع تعليمات المستخدم أو تشويهها أو حذفها قبل وصولها إلى الوكيل.
النتائج:
- لا يمكن للمستخدمين إثبات ما فوّضوه.
- لا يوجد لدى الجهات التنظيمية مسار تدقيق.
- لا يوجد لدى المحاكم سلسلة أدلة.
- لا تستطيع الوكلاء التمييز بين تعليمات المُشغِّل المشروعة والتعليمات المخترقة أو الخارجة عن السيطرة.
يسد AuthProof هذه الفجوة.
---
## البدائية الأساسية: إيصال التفويض
**إيصال التفويض** هو كائن تفويض موقع يُثبَّت في سجل لامركزي للإلحاق قبل بدء أي إجراء للوكيل. يحتوي على أربعة حقول إلزامية:
### النطاق
قائمة سماح صريحة للعمليات المسموح بها. كل ما ليس مدرجًا ممنوع افتراضيًا. يُعبَّر عنه بتنسيق منظم — وليس بلغة طبيعية. فئات العمليات:
| الفئة | الوصف |
|---|---|
| `reads` | وصول للقراءة إلى موارد محددة |
| `writes` | وصول للكتابة إلى موارد محددة |
| `deletes` | حذف موارد محددة |
| `executes` | تنفيذ برنامج محدد، بالإشارة إلى **تجزئة توقيع القدرة الثابتة** الخاصة به |
`executes` هي الفئة الأكثر خطورة. يجب أن تشير إلى التجزئة التشفيرية لرسم بياني للقدرات الثابتة (DAG) لبرنامج Safescript — وليس إلى اسم أو URI أو وصف. عدم تطابق التجزئة يعني عدم التنفيذ.
### الحدود
محظورات صريحة لا يمكن تجاوزها بتعليمات المُشغِّل تحت أي ظرف. حدود صلبة يحددها المستخدم وتستمر بعد أي تعليمات لاحقة من المُشغِّل.
### الإطار الزمني
فترة صلاحية التفويض. **الطابع الزمني للسجل** هو مرجع الوقت — وليس ساعة العميل. ساعات العميل مستبعدة صراحةً من التحقق من الوقت.
### تجزئة تعليمات المُشغِّل
تجزئة تشفيرية لتعليمات المُشغِّل المُعلنة في وقت التفويض. إذا قام المُشغِّل لاحقًا بتوجيه الوكيل بشكل مختلف، يمكن اكتشاف التناقض من السجل دون أي افتراضات ثقة إضافية.
يوقع المستخدم على هذا الكائن بمفتاحه الخاص عبر **WebAuthn/FIDO2 باستخدام المنطقة الآمنة للجهاز**. يتم نشر التوقيع في السجل قبل أي إجراء للوكيل. كل إجراء لاحق للوكيل يشير إلى تجزئة الإيصال. الإجراءات خارج النطاق غير صالحة تشفيريًا.
---
## بنية طبقة الثقة
ثلاث طبقات بروتوكول تقضي على ثلاثة أطراف ثالثة موثوقة:
### الطبقة 1 — بيان القدرة المُوقَّع *(يزيل الثقة في السجل)*
في النظام البيئي الحالي لـ MCP، لا يوجد أي تصديق تشفيري بأن أوصاف خادم الأداة تتطابق مع ما يفعله بالفعل. يمكن للمُشغِّل تقديم مخطط وصف (schema) تعسفي.
الحل: تنشر خوادم الأدوات **بيان قدرة مُوقَّع تشفيريًا** قبل حدوث أي تفويض من المستخدم. يشير حقل `scope` في إيصال التفويض إلى **تجزئة هذا البيان** — وليس إلى مخطط وصف المُشغِّل المُبلَغ ذاتيًا. يمكن اكتشاف الاختلاف بين سلوك الخادم والبيان في طبقة السجل.
### الطبقة 2 — إيصال التفويض *(يزيل الثقة في المُشغِّل)*
يتم تسجيل نية المستخدم الأصلية بشكل غير قابل للتغيير قبل وصول تعليمات المُشغِّل إلى الوكيل. انحراف المُشغِّل قابل للإثبات.
### الطبقة 3 — تنفيذ Safescript *(يزيل الثقة في الكود)*
[Safescript](https://github.com/safescript) هي لغة صندوق رمل مفتوحة المصدر لتنفيذ الوكيل الذكي. هيكلها الثابت للرسم البياني DAG يعني أن توقيع القدرة الكامل لكل برنامج يمكن حسابه قبل تشغيله — لا توزيع ديناميكي، لا توسع لقدرات وقت التشغيل.
تشير فئة نطاق `executes` إلى تجزئة توقيع قدرة محددة لـ Safescript. إذا لم يتطابق البرنامج الذي يوفره المُشغِّل مع التجزئة الملتزمة، يتم منع التنفيذ. لا يمكن استبدال الوكيل ببرنامج مختلف بعد التفويض.
---
## بداية سريعة```js
import { AuthProof, Scope, KeyCustody } from 'authproof-sdk';
// Initialize with hardware-backed key custody (recommended)
const authproof = new AuthProof({
custody: KeyCustody.HARDWARE, // WebAuthn/FIDO2 via device secure enclave
log: 'https://log.authproof.dev',
});
// Define permitted operations â explicit allowlist, deny-by-default
const scope = new Scope()
.allow('reads', ['resource://calendar/events', 'resource://email/inbox'])
.allow('writes', ['resource://calendar/events'])
.deny('deletes', '*')
.execute('sha256:a3f1c9d8...', { program: 'scheduler-v1.sg' }); // Safescript hash
// Hard limits that survive any operator instruction
const boundaries = {
never: ['external-network', 'credential-store', 'payment-methods'],
};
// Issue the Delegation Receipt â anchored to log before any agent action
const receipt = await authproof.delegate({
scope,
boundaries,
window: { duration: '8h' }, // validated against log timestamp
operatorInstructions: instructionText, // hashed and committed
});
// receipt.id â unique receipt identifier
// receipt.hash â reference in every agent action
// receipt.log â append-only log anchor
// Agent-side: validate an action against the receipt
const check = await authproof.validate({
receiptHash: receipt.hash,
action: { class: 'writes', resource: 'resource://calendar/events' },
});
if (!check.authorized) {
// Out-of-scope action: surface a micro-receipt request to the user
const microReceipt = await authproof.requestMicroReceipt({
action: check.requestedAction,
parent: receipt.hash,
});
}
بالنسبة لاستدعاءات الأدوات غير المغطاة في إيصال التفويض الأصلي، لا يمكن للوكيل المتابعة بصمت. ينص البروتوكول على:
تتطلب الإجراءات غير المعروفة تفويضًا صريحًا جديدًا من المستخدم. يتبع حل التبعيات نفس القاعدة - تُفحص التبعيات مقابل تجزئة بيان التبعية الملتزم به وقت التفويض. التبعيات غير المتوقعة هي انتهاك للنطاق.
يحمل كل حدث تفويض معرف إيصال فريد. يشير كل وكيل متزامن إلى تجزئة الإيصال الخاصة به. يمكن تمييزهم بالإيصال، وليس بهوية الوكيل.
| النموذج |
|---|
الاحتفاظ بالعتاد هو الخيار الافتراضي الموصى به. لا يغادر المفتاح الخاص البيئة الآمنة أبدًا؛ التوقيع محمي بواسطة القياسات الحيوية للجهاز أو رقم التعريف الشخصي.
يحدد إيصال التفويض ما هو مصرح لوكيل AI بفعله. يسجل سجل الإجراءات ما فعله بالفعل - ويجعل أي انحراف قابلًا للتحقق الفوري.
كل إجراء يتخذه الوكيل ينتج إدخالًا موقعًا ومختومًا بالوقت مرتبطًا بالإيصال النشط. تشكل الإدخالات سلسلة واضحة التلاعب: يدمج كل إدخال تجزئة SHA-256 للإدخال السابق، لذا يمكن اكتشاف أي تعديل بأثر رجعي دون طرف ثالث موثوق. طريقة diff() هي البدائية الأساسية للتدقيق - تقوم بمحاذاة النطاق المصرح به في الإيصال مقابل كل إجراء مسجل وتعيد أي انحرافات.```js
import AuthProof, { ActionLog } from 'authproof-sdk';
// 1. Issue a delegation receipt as normal const { privateKey, publicJwk } = await AuthProof.generateKey();
const { receipt, receiptId } = await AuthProof.create({ scope: 'Search the web for competitor pricing. Read calendar events.', boundaries: 'Do not send emails. Do not make purchases.', instructions: 'Cite sources. Keep under 500 words.', ttlHours: 4, privateKey, publicJwk, });
// 2. Initialize the action log with the agent's signing key const log = new ActionLog(); await log.init({ privateKey, publicJwk });
// Register the receipt so diff() knows what was authorized log.registerReceipt(receiptId, receipt);
// 3. Record each action the agent takes const e1 = await log.record(receiptId, { operation: 'Search competitor pricing', resource: 'web/search', parameters: { query: 'rival.com pricing 2024' }, });
const e2 = await log.record(receiptId, { operation: 'Read calendar events', resource: 'calendar/events', parameters: { range: 'this_week' }, });
// 4. Verify an individual entry (signature + chain integrity) const check = await log.verify(e1.entryId); // { valid: true, reason: 'Signature and chain integrity verified' }
// 5. Diff: authorized scope vs. everything that was done const report = log.diff(receiptId); // { // clean: true, // totalEntries: 2, // compliant: [{ entry: {...}, reason: '"Search competitor pricing" matches authorized scope' }, ...], // violations: [], // }
// A scope violation surfaces immediately await log.record(receiptId, { operation: 'Send email', resource: 'email/outbox' }); const auditReport = log.diff(receiptId); // auditReport.violations[0].reason â // '"Send email" outside authorized scope (0% scope match, 92% boundary overlap)'
### واجهة API لسجل الإجراءات
| الطريقة | الوصف |
|---|---|
| `new ActionLog()` | إنشاء مثيل سجل جديد. الحالة موجودة في الذاكرة. |
| `log.init({ privateKey, publicJwk })` | التهيئة باستخدام مفتاح ECDSA P-256 للوكيل. مطلوب قبل `record()`. |
| `log.registerReceipt(receiptHash, receipt)` | تسجيل إيصال لمقارنة النطاق. مطلوب قبل `diff()`. |
| `log.record(receiptHash, action)` | إلحاق إدخال موقع ومتسلسل. يُرجع الإدخال المغلق. |
| `log.verify(entryId)` | التحقق من توقيع إدخال واحد وموقعه في السلسلة. يُرجع `{ valid, reason }`. |
| `log.getEntries(receiptHash)` | جميع الإدخالات لإيصال بالترتيب الزمني. |
| `log.diff(receiptHash)` | مقارنة جميع الإدخالات بنطاق الإيصال. يُرجع `{ compliant, violations, clean }`. |
### تحذير الإنتاج
الطوابع الزمنية في v1 تستخدم ساعة العميل. بالنسبة لسياقات الامتثال أو القانونية حيث يجب أن تكون الطوابع الزمنية قابلة للتحقق بشكل مستقل، استبدلها بجهة طوابع زمنية موثوقة وفقًا لـ RFC 3161 قبل النشر في الإنتاج.
### مهم
حدد النطاق دائمًا باستخدام مصفوفات `allowedActions` الصريحة. مطابقة النطاق النصية متاحة للتطوير فقط وغير مناسبة لسياقات الإنتاج أو الامتثال.
---
## النشر السري
شغّل وكلاء AuthProof داخل بيئات تنفيذ موثوقة معتمدة بالأجهزة (TEEs). تربط فئة `ConfidentialRuntime` إيصالات التفويض بقياسات العلبة (enclave)، لذا فإن أي استبدال لأوزان النموذج أو كود المدقق أو المنصة يمكن اكتشافه قبل التنفيذ.
### متطلبات الأجهزة
- **Intel TDX** — Intel Ice Lake Xeon أو أحدث (الجيل الرابع من Xeon Scalable). Azure DCdsv3-series، GCP C3 Confidential VMs.
- **AMD SEV-SNP** — AMD EPYC الجيل الثالث (Milan) أو أحدث. Azure DCasv5-series، AWS m6a مع Nitro Enclaves.
### إنشاء إيصال مع ربط قياس TEE```javascript
import { AuthProofClient } from 'authproof-sdk';
const client = new AuthProofClient();
const { receipt } = await client.delegate({
scope: 'Summarize calendar events',
operatorInstructions: 'Stay within scope.',
expiresIn: '2h',
privateKey,
publicJwk,
teeConfig: {
platform: 'intel-tdx',
verifierHash: verifierCodeHash, // SHA-256 of your verifier binary
modelHash: modelWeightsHash, // SHA-256 of model weights
},
});
// receipt.teeMeasurement.expectedMrenclave is now bound to the receipt
import { ConfidentialRuntime } from 'authproof-sdk';
// Generate deployment configuration const config = ConfidentialRuntime.azureTDXConfig({ receiptHash, verifierHash, modelHash, region: 'eastus', }); // config.vmSize === 'Standard_DC4ds_v3' // config.attestationEndpoint === 'https://sharedeus.eus.attest.azure.net' // config.receiptBinding binds the receipt to the VM measurement
// At runtime inside the VM: const runtime = new ConfidentialRuntime({ platform: 'intel-tdx', verifier, actionLog, }); const result = await runtime.launch({ receiptHash, agentFn, operatorInstructions, verifierHash, modelHash, teeMeasurement: receipt.teeMeasurement, // mismatch blocks execution });
متطلبات SKU في Azure: `Standard_DC4ds_v3` أو أكبر من سلسلة DCdsv3-series. قم بتمكين تشفير قرص نظام التشغيل السري (Confidential OS disk encryption). استخدم نقطة نهاية مشتركة لـ Microsoft Azure Attestation (MAA) للتحقق من الاقتباس.
### النشر على AWS Nitro Enclaves```javascript
const config = ConfidentialRuntime.awsNitroConfig({
receiptHash,
verifierHash,
modelHash,
region: 'us-east-1',
});
// config.instanceType === 'c6a.xlarge'
// config.enclaveOptions.enabled === true
// config.pcr0 is the combined receipt+verifier+model measurement
متطلبات AWS: c6a.xlarge أو أكبر مع --enclave-options Enabled. استخدم nitro-cli لبناء وتشغيل صورة enclave. يجب أن يتطابق PCR0 في مستند المصادقة مع config.pcr0 لكي يكون ربط الإيصال صحيحًا.
const manifest = ConfidentialRuntime.kubernetesConfig({ receiptHash, platform: 'intel-tdx', namespace: 'production', }); // manifest is a full K8s List containing: // - Pod with TDX node selector and attestation sidecar // - ServiceAccount with minimal RBAC // - ConfigMap with receipt binding
Apply with `kubectl apply -f` after serializing to YAML. The node selector `intel.feature.node.kubernetes.io/tdx: "true"` requires the Intel Device Plugin for Kubernetes.
### وحدة نواة eBPF — مساعدة مطلوبة
طبقة تطبيق TEE مكتملة من جانب مساحة المستخدم (`ConfidentialRuntime`, `TokenPreparer`). الخطوة النهائية للتطبيق — التحقق من رمز القدرة الموقع على كل استدعاء نظام عبر خطاف eBPF LSM — تتطلب وحدة نواة مفتوحة للمساهمة.
المهندسون ذوو الخبرة في eBPF LSM (Isovalent, Red Canary, أو ما شابه) مرحب بهم بشكل خاص. افتح مشكلة أو طلب سحب على https://github.com/Commonguy25/authproof-sdk/issues
---
## أمثلة
مثالان قابلان للتشغيل موجودان في مجلد `examples/`.
**[`examples/langchain-example.js`](https://github.com/commonguy25/authproof-sdk/blob/HEAD/examples/langchain-example.js)** — يُظهر مسار تكامل LangChain الكامل: إنشاء زوج مفاتيح، إصدار إيصال تفويض، تهيئة `PreExecutionVerifier`، وتغليف أي وكيل بـ `authproofMiddleware` بحيث يتم حظر كل استدعاء `invoke()` قبل أن يحصل وقت تشغيل الوكيل على السيطرة. يتضمن وكيلًا وهميًا يمكنك تشغيله فورًا ونمط الكود الدقيق لـ `AgentExecutor` حقيقي. قم بتشغيله باستخدام `npm run example:langchain`.
**[`examples/webauthn-example.html`](https://github.com/commonguy25/authproof-sdk/blob/HEAD/examples/webauthn-example.html)** — عرض توضيحي مستقل بثلاث بطاقات في المتصفح لتدفق التفويض الكامل. تتيح لك البطاقة 1 تحديد النطاق والحدود وتعليمات المشغل، ثم توقيع إيصال باستخدام مفتاح محلي (استبدل `navigator.credentials` بـ WebAuthn الحقيقي). تعرض البطاقة 2 معرف الإيصال وتاريخ انتهاء الصلاحية ومطالبة النظام وJSON الخام. تتيح لك البطاقة 3 كتابة أي إجراء مقترح والتحقق منه مقابل الإيصال في الوقت الفعلي، مع إظهار كل نتيجة فحص. افتح مباشرة في متصفح — لا حاجة لخطوة بناء.
---
## التثبيت```bash
npm install authproof-sdk
WHITEPAPER.md| الوصف |
|---|
| الموصى به |
|---|
| العتاد | WebAuthn/FIDO2 عبر البيئة الآمنة للجهاز. المفتاح الخاص لا يغادر العتاد أبدًا. | نعم - افتراضي |
| مفوض | مدير المفاتيح الموثوق يحتفظ بالمفتاح نيابة عن المستخدم. | البيئات التي لا تدعم FIDO2 |
| الاحتفاظ الذاتي | يحتفظ المستخدم بمفتاحه الخاص ويديره. | المستخدمون المتقدمون، سير العمل المعزول |