OAuth

​

ملّاك بيانات الاعتماد

• التطبيق ({ owner: 'app' }): بيانات اعتماد واحدة يستخدمها الوكيل للجميع، مثل حساب خدمة أو تثبيت بوت.
• مستخدم ({ owner: 'user', principalId, issuer? }): بيانات اعتماد واحدة لكل شخص سجّل الدخول. principalId هو معرّف المستخدم، وissuer يسمّي مزوّد الهوية الذي أصدره، فيكون alice من جهة إصدار وalice من جهة أخرى مالكَين مختلفَين. مع مصادقة المسارات يُطابَق مبدأ الطلب (principal) عليه هكذا: { owner: 'user', principalId: principal.id, issuer: principal.issuer }؛ وبيانات اعتماد المستخدم تحتاج إلى ذلك المبدأ، لأنه بدونه لا يوجد مستخدم يملكها.

import { tokenStoreKey } from '@lousho/build-ai-agent';

tokenStoreKey('github', { owner: 'app' }); // 'github|app'
tokenStoreKey('github', { owner: 'user', principalId: 'a|b', issuer: 'https://id.example.com' });
// 'github|user|https%3A%2F%2Fid.example.com|a%7Cb'

​

تخزين الرموز

import { memoryStore } from '@lousho/build-ai-agent';

const { tokens } = memoryStore();
const alice = { owner: 'user', principalId: 'alice', issuer: 'https://id.example.com' } as const;

await tokens.set('github', alice, { accessToken: 'gho_...', refreshToken: 'ghr_...', tokenType: 'Bearer', expiresAt: Date.now() + 3_600_000 });
const token = await tokens.get('github', alice); // { accessToken, refreshToken, ... } or undefined
const connected = await tokens.list({ owner: alice }); // [{ provider: 'github', owner, expiresAt, scope, hasRefreshToken: true, updatedAt }]
await tokens.delete('github', alice); // disconnect

• get وset وdelete تقرأ بيانات اعتماد واحدة وتكتبها (بالاستبدال) وتزيلها.
• list({ provider?, owner? }) تُرجع بيانات وصفية فقط: المزوّد والمالك ونوع الرمز وانتهاء الصلاحية والنطاق (scope) وهل يوجد رمز تحديث مخزَّن ووقت كتابة السجل. ولا تُرجع أبدًا رمز وصول أو رمز تحديث.
• putPending(state, value, ttlMs) وtakePending(state) تحفظان عملية تسجيل دخول جارية (مُتحقِّق PKCE ومكان العودة) بين إعادة التوجيه ورد النداء. تُرجع takePending القيمة مرة واحدة وتحذفها؛ وبعد ttlMs تزول. وstate من 16 إلى 128 حرفًا من A-Z وa-z و0-9 و_ و-؛ وأي state مشوَّه يُمرَّر إلى takePending ببساطة لا يُعثر عليه.
• setClient(provider, client) وgetClient(provider) تحفظان عميلًا مسجَّلًا لدى خادم التفويض (التسجيل الديناميكي للعميل). وقد يحتوي السجل سرًّا للعميل، لذلك يُشفَّر كما يُشفَّر الرمز.

node -e "console.log(Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64'))"

import { createAgent, fileStore, generateTokenKey } from '@lousho/build-ai-agent';

console.log(generateTokenKey()); // store it as a secret, e.g. LOUSHO_TOKEN_KEY

const agent = createAgent({ provider, store: fileStore('./.lousho', { tokenKey: process.env.LOUSHO_TOKEN_KEY }) });

• المفتاح الذي ليس 32 بايت بالضبط بصيغة base64 يسبب ConfigurationError عند إنشاء المخزن.
• بلا مفتاح، يعمل الوكيل الذي لا يخزّن رمزًا قط كما كان: القراءات لا تجد شيئًا. أما أول set أو setClient أو putPending فيرمي LOUSHO_TOKEN_KEY_MISSING، وكذلك قراءة سجل موجود.
• كل كتابة تستخدم متجه تهيئة (IV) عشوائيًا جديدًا من 12 بايت، فالرمز نفسه المكتوب مرتين يعطي نصَّين مشفَّرين مختلفَين. ويُوثَّق مفتاح السجل معه: فالنص المشفَّر المنسوخ إلى صف مالك آخر لا يُفكّ تشفيره. والصيغة المخزَّنة هي v1.<base64 iv>.<base64 ciphertext>.
• السجل المكتوب بمفتاح آخر، أو الذي تغيّر على القرص، يفشل بالخطأ LOUSHO_TOKEN_DECRYPT_FAILED، الذي يسمّي المزوّد ولا يذكر الرمز أبدًا.