tokens من AgentStore، مفهرسةً بالـprovider وبمالك الـcredential. وتغطي كيف تحصل الأداة على واحد: تستدعي ctx.getToken(provider)، وإذا لم يربط المستخدم حسابه بعد يتوقف الـrun إلى أن يسجّل الدخول (أدوات تحتاج تسجيل دخول). وخوادم MCP عبر HTTP تسجّل الدخول بـOAuth أيضًا (خوادم MCP مع OAuth).
من يملك credential
كل credential مخزَّن له provider (اسم مثلgithub، من 1 إلى 64 حرفًا من A-Z وa-z و0-9 و_ و-) ومالك:
- التطبيق (
{ owner: 'app' }): credential واحد يستخدمه الـagent للجميع، مثل service account أو تثبيت bot. - مستخدم (
{ owner: 'user', principalId, issuer? }): credential واحد لكل شخص مسجّل دخوله.principalIdهو معرّف المستخدم، وissuerاسم مزوّد الهوية الذي أصدره. أي أنaliceمن issuer وaliceمن issuer آخر مالكان مختلفان. مع مصادقة المسارات ينعكس principal الطلب عليه هكذا:{ owner: 'user', principalId: principal.id, issuer: principal.issuer }. وcredential المستخدم يحتاج هذا الـprincipal، لأن بدونه لا يوجد مستخدم يملكه. والـprincipal الذي ليس لهissuer(مستخدم Slack أو GitHub أو Telegram أو Discord، أوbasic()، أوapiToken()) يأخذissuer: 'authenticator:<name>'، فنفس المعرّف من authenticatorين مختلفين (SlackU04ABCDEFودخول GitHub باسمU04ABCDEF) مالكان اثنان، ولا يتشاركان token أبدًا.
نقل الـtokens المخزَّنة قبل namespace الـauthenticator
الـtokens المخزَّنة لـprincipal بدون issuer موجودة تحت المفتاح القديم (<provider>|user||<id>). هذا المفتاح كان مشتركًا بين كل الـauthenticators، لذلك الـSDK لا يقرأه كبديل احتياطي: لو فعل لسلّم token الخاص بـauthenticator إلى authenticator آخر. والمستخدمون الذين لا يُعثر على الـtoken الخاص بهم يسجّلون الدخول من جديد. وللاحتفاظ بالـtoken، ينقلها المشغّل الذي يعرف لأي authenticator تنتمي الـtokens القديمة مرة واحدة:
tokenStoreKey(provider, owner) هو مفتاح سجل الـcredential: <provider>|app، أو <provider>|user|<issuer>|<principalId> مع percent-encoding للـissuer والمعرّف (الـissuer الغائب جزء فارغ). الترميز يجعل المفتاح واضحًا: معرّف principal فيه | لا يمكن أن يتصادم مع مالك آخر.
تخزين tokens
AgentStore.tokens هو OAuthTokenStore:
getوsetوdeleteتقرأ وتكتب (تستبدل) وتحذف credential واحد.list({ provider?, owner? })تعيد metadata فقط: الـprovider والمالك ونوع الـtoken وانتهاء الصلاحية والـscope وهل يوجد refresh token مخزَّن ومتى كُتب السجل. ولا تعيد أبدًا access token ولا refresh token.putPending(state, value, ttlMs)وtakePending(state)تحفظان تسجيل دخول جاريًا (الـPKCE verifier ومكان العودة) بين الـredirect والـcallback.takePendingتعيده مرة واحدة وتحذفه، وبعدttlMsيختفي.stateمن 16 إلى 128 حرفًا منA-Zوa-zو0-9و_و-؛ وأيstateمشوَّه يُمرَّر إلىtakePendingببساطة لا تجد شيئًا.setClient(provider, client)وgetClient(provider)تحفظان client مسجَّل لدى authorization server (dynamic client registration). والسجل يمكن أن يحتوي client secret، لذلك يُشفَّر مثل الـtoken.
tokens:
المفتاح. الـstores الدائمة تشفّر كل سجل بـAES-256-GCM بمفتاح 32 بايت تمرّره أنت بصيغة base64: إما خيار
tokenKey، وإلا متغير البيئة LOUSHO_TOKEN_KEY. لا يوجد مفتاح افتراضي، ولا شيء يُشتق من كلمة مرور. ولّد واحدًا بـgenerateTokenKey() أو من الـshell:
process.env: أضف المفتاح كـsecret (wrangler secret put LOUSHO_TOKEN_KEY) ومرّر env.LOUSHO_TOKEN_KEY في tokenKey. والـWorker الذي يولّده lousho build --target=cloudflare-worker يفعل هذا عنك.
- إذا لم يكن المفتاح 32 بايت base64 بالضبط، يظهر
ConfigurationErrorعند بناء الـstore. - دون مفتاح، الـagent الذي لا يخزّن token أبدًا يعمل كالمعتاد: القراءات لا تجد شيئًا. وأول
setأوsetClientأوputPendingيرميLOUSHO_TOKEN_KEY_MISSING، وكذلك قراءة سجل موجود. - كل كتابة تستخدم IV عشوائي جديد من 12 بايت، فنفس الـtoken المكتوب مرتين يعطي ciphertext مختلفين. ومفتاح السجل مُوثَّق مع الـIV: الـciphertext المنسوخ إلى صف مالك آخر لا ينجح فكّ تشفيره. الصيغة المخزَّنة:
v1.<base64 iv>.<base64 ciphertext>. - سجل مكتوب بمفتاح آخر، أو تغيّر على القرص، يفشل بـ
LOUSHO_TOKEN_DECRYPT_FAILED— والخطأ يسمّي الـprovider ولا يذكر الـtoken أبدًا.
tokenKey: [newKey, oldKey] أو LOUSHO_TOKEN_KEY="<new>,<old>". الكتابة تستخدم المفتاح الأول، والقراءة تجرّب كل واحد بالترتيب، فالـtokens تنتقل للمفتاح الجديد كلما جُدِّدت. لا يوجد أمر يعيد تشفير كل السجلات؛ وبمجرد أن تُسقط المفتاح القديم، لم تعد الـtokens التي لا تزال مكتوبة به تُقرأ، ومستخدموها يسجّلون الدخول من جديد (احذف تلك السجلات).
لا شيء يسجّل الـtoken. الـstores لا تضع أبدًا access token ولا refresh token ولا PKCE verifier ولا client secret في رسالة خطأ ولا سطر log ولا cause لخطأ. وقيم الـtokens ليست جزءًا من أحداث الـagent ولا الـtranscripts ولا الـcheckpoints ولا الـtraces ولا الـcassettes المسجَّلة، إلا إذا أعادتها أداة بنفسها. والأداة التي تستخدم token تعيد جواب الـAPI، لا الـtoken.
الاتساق. SQLite يأخذ تسجيل الدخول المعلّق في transaction واحدة، والـfile store يحجزه بإنشاء ملف حصري، فيحصل عليه مستدعٍ واحد بالضبط. أما Workers KV فلا transactions فيه: takePending تقرأ ثم تحذف، فيمكن أن يقرأ callbackان في موقعَي edge مختلفَين، ضمن تأخير انتشار KV (حتى دقيقة تقريبًا)، نفس الـstate. والـstate قيمة عشوائية 256-bit لا يحملها إلا متصفح المستخدم، فإعادة استخدامها لا تمنح شيئًا لمن لا يملكها أصلًا. وtokens.list() في KVStore تحتاج list() الخاصة بالـbinding (الـKV namespace الحقيقي فيها؛ نسخة fake مصنوعة يدويًا يمكن ألا تملكها). وprune() في SqliteStore تحذف أيضًا تسجيلات الدخول المعلّقة المنتهية؛ والـfile store يسقطها عند بدء تسجيل الدخول التالي، وKV ينهيها بنفسه.
أدوات تحتاج تسجيل دخول
عرّف الـprovider مرة واحدة، على مستوى الـmodule بجانب الأدوات التي تستخدمه، بـdefineOAuthProvider(). والأداة تطلب الـtoken بـctx.getToken(provider):
getToken()تقرأ منstore.tokensالـtoken الخاص بـprincipal الـrun (principal) (credentialOwner: 'user'، وهو الافتراضي) أو الخاص بالتطبيق (credentialOwner: 'app'). والـtoken الذي تنتهي صلاحيته خلال 60 ثانية ومعه refresh token يُجدَّد أولًا علىtokenUrlويُحفظ. والاستدعاءات المتزامنة في الـprocess نفسه التي تحتاج التجديد نفسه تتشارك request واحدًا، فالـprovider الذي يدوّر الـrefresh tokens (استخدام واحد) لا يستلم الـrefresh token نفسه مرتين. وإذا رفض الخادم التجديد يُحذف الـtoken، إلا إذا أصبح في الـstore خلال ذلك token مختلف (جدّده process آخر)؛ وعندئذٍ يُستخدم ذلك بدلًا منه.- دون token صالح يتوقف الـrun، بالضبط مثل approval:
finishReason: 'awaiting-approval'، وapproval معلّق بـkind: 'sign-in'، durable في مخازن الـagent. وبعد تسجيل المستخدم وقبول الـapproval، يعمل الـtool call من جديد من البداية. استدعِgetToken()قبل أي شيء له side effect: أي عمل يُنجز قبلها يتكرر مرتين. ctx.requireAuth(provider)لرمز رفضته الـAPI (استجابة 401): تحذف الـtoken المخزَّن وتوقف لتسجيل دخول جديد.- credential المستخدم تحتاج principal: في run ليس له principal (لا route auth ولا channel) تُفشل
getToken()الاستدعاء بـLOUSHO_OAUTH_PRINCIPAL_REQUIREDولا يتوقف شيء. - الـagent يحتاج token store (
storeفيهtokens)؛ وبدونه يتوقف الـrun بـLOUSHO_OAUTH_STORE_MISSING. - الـprovider يُسجَّل باسمه
nameعلى مستوى الـprocess، فيستطيع الـcallback أن يكمل تسجيل دخول بدأ في request آخر أو قبل restart. وتعريف الاسم نفسه مرة أخرى يستبدله.
credentialOwner: 'app' يحمل token واحدًا للجميع (تثبيت bot، service account). ومستخدم الدردشة لا يُرسَل له رابط تسجيل الدخول أبدًا، لأن من يفتحه سيربط حسابه هو كـcredential للـagent لكل المستخدمين: ودون الـtoken يفشل الاستدعاء بـLOUSHO_OAUTH_APP_SIGNIN_REQUIRED. والمشغّل يسجّل دخول التطبيق مرة واحدة بـagent.oauth.signInUrl(provider):
ما يراه المستخدم
يصل الإيقاف مثل أي approval، ومعه الرابط المطلوب فتحه:- حدث
approval.requested(وrun.doneالذي يليه بـfinishReason: 'awaiting-approval') فيهkind: 'sign-in'وsignIn: { provider, displayName?, url }. وagent.approvals.list()تعيد السجل نفسه. اعرضurl؛ وحين يعود المستخدم، وافق على الإيقاف (“I’ve signed in”) بـagent.approvals.resolve({ id, approved: true })أوPOST /chat/:id/approvals/:approvalId { "approved": true }. الموافقة قبل أن يخزّن الـcallback الـtoken ترميLOUSHO_SIGNIN_PENDING(HTTP 409 على المسار) ويبقى الـrun موقوفًا. أماapproved: falseفتلغي: يستلم الـmodel خطأ أداة بـkind: 'denied'نصه “Sign-in to GitHub was cancelled.”. - الـ
approvecallback لا يُسأل عن تسجيل دخول أبدًا: المستخدم وحده يستطيع تسجيل الدخول. - تطبيقات React وVue وSvelte تستلمه كـ
pendingApproval.kind === 'sign-in'معpendingApproval.signIn: اعرض الرابط واستدعِapprove()حين يقول المستخدم إنه انتهى (reject()تلغي). وجزءdata-lousho-approvalمن stream الـAI SDK يحملkindوsignInأيضًا. - القنوات تنشر الرسالة الافتراضية “Sign in to GitHub to continue: <url>” بلا أزرار Approve / Deny. وSlack يرسلها بـ
chat.postEphemeralللمستخدم الذي بدأ الـturn، وDiscord كرسالة ephemeral متابعة، فلا أحد غيره في الـthread يرى الرابط. أما Teams وTelegram فليس لديهما رسالة يراها مستخدم واحد فقط، لذلك يرسلان الرابط فقط في محادثة 1:1 مع الـbot؛ وفي محادثة جماعية أو قناة ينشران بدلًا منه “please sign in from a private chat with me”. وGitHub لا ينشرها في thread عام أبدًا. وخلفcreateDeployedServer()وlousho devيكمل الـcallback دورة القناة الموقوفة بنفسه، وتُنشر الإجابة في مكان السؤال نفسه. - صفحة الدردشة في
lousho devتعرض الرابط مع “I’ve signed in” و”Cancel”؛ وlousho chatوlousho acpيعرضان الرابط ويسألان من جديد إلى أن يسجّل المستخدم الدخول.
مسار callback
يجب أن يشيرredirectUri إلى GET /oauth/callback في الـagent المخدَّم، بالضبط كما سُجّل لدى الـprovider:
المسار ليس خلف route auth ولا bearer token: الـredirect من المتصفح لا يحمل API token. وحمايته هي
state: 32 بايت عشوائية، استخدام واحد، صالحة 10 دقائق. يستدعي agent.oauth.complete({ state, code, error }) ويرد بصفحة HTML صغيرة (“Signed in to GitHub. You can close this tab.”، أو نص الإلغاء إذا أرسل الـprovider error)، مع cache-control: no-store، وبدون script، وبدون أن يعكس أي قيمة من الـquery. وstate غير المعروفة أو المستخدمة أو المنتهية يُجاب بـ400؛ ورفض تبادل الـcode يُجاب بـ502 (LOUSHO_OAUTH_TOKEN_EXCHANGE_FAILED). وإذا اجتاز طلب الـcallback مصادقة المسار (كوكي session تقبلها دالة المصادقة الخاصة بك، مثلًا)، يُرفض تسجيل دخول بدأ لمستخدم آخر.
agent.oauth.complete() تخزّن الـtoken فقط: الـclient الذي عرض الرابط يكمل الـrun بالموافقة على الإيقاف. وإذا كنت تخدم مسارًا خاصًا بك، افعل الشيء نفسه:
complete() القيمة outcome: 'declined'، وعندئذٍ تلغي الموافقة على الإيقاف الاستدعاء مثل approved: false.
approval وتسجيل الدخول معًا
الأداة التي فيهاneedsApproval تسأل أولًا: بوابة الـapproval تعمل قبل execute الخاصة بالأداة. وبعد القبول يبدأ الاستدعاء، فلا تجد getToken() token ويتوقف الـrun مرة أخرى، هذه المرة لتسجيل الدخول. وبعد تسجيل الدخول، الموافقة على هذا الإيقاف تنفّذ الاستدعاء مرة واحدة؛ ولا يُعرض على المراجع ثانيةً. والاستدعاء الذي يحتاج تسجيل دخول لدى اثنين من الـproviders يتوقف مرة لكل واحد منهما، بالتتابع.
وإذا احتاجت عدة استدعاءات في turn واحد للـmodel إلى تسجيل دخول، يتوقف الـrun عند الأول؛ والباقي يعمل بعد أن يُبتّ فيه، مثل بقية turn توقف على approval.
الأمان
- PKCE والـstate. كل تسجيل دخول يستخدم PKCE مع S256 (verifier من 32 بايت) و
stateعشوائية من 32 بايت. الـverifier يُحفظ فقط في السجل المعلّق المشفَّر (store.tokens.putPending) — أبدًا في snapshot الـapproval ولا checkpoint ولا حدث. وstateلاستخدام واحد وتنتهي بعد 10 دقائق. ورابط التفويض يحملstateوالـchallenge، وكلاهما آمن للعرض؛ أما authorization code فلا يُسجَّل أبدًا. - التشفير. الـtokens وتسجيلات الدخول المعلّقة تُشفَّر في التخزين عبر الـstores الدائمة (تخزين الـtokens).
- ربط الـprincipal. token المستخدم يُخزَّن للـprincipal الذي يتصرف الـrun الموقوف نيابةً عنه، أيًّا كان من يكمّل الـcallback، والـrun لا يقرأ إلا token الـprincipal الخاص به. وtokens مستخدمَين لا تختلط أبدًا؛ والـid نفسه من issuer آخر هو مستخدم آخر. أما credential التطبيق فلا يسجّل دخولها إلا المشغّل.
- من يرى الرابط. من يفتح رابط تسجيل دخول يربط حسابه هو بالمستخدم الذي طلبه. اعرضه لذلك المستخدم فقط: في stream الـrun نفسه، أو رسالة ephemeral في قناة مشتركة (Slack وDiscord)، أو محادثة 1:1 (Telegram وTeams)، ولا في محادثة جماعية أو thread عام أبدًا.
- لا تُعِد token من أداة أبدًا. أعِد جواب الـAPI. وكشبكة أمان: إذا كانت نتيجة أداة أو خطأ مرميّ منها يحتوي token سلّمته
getToken()أثناء ذلك الاستدعاء، يُستبدل بـ[REDACTED]قبل تسجيله، وتحذير يسمّي الأداة. النتيجة تُفحص بصيغتها JSON (القيم والمفاتيح وURLوحقول instance من class)، والخطأ في رسالته والـstack وسلسلةcause، والـtoken يُطابَق حرفيًا وبترميز base64 أو base64url (headerBasic). وهذا الحجب شبكة أمان، لا ضمان: الـtoken الذي يُحسب له hash أو يُقسَّم أو يُحوَّل بأي طريقة أخرى لا يُكتشف. والـtokens لا تدخل أبدًا في أحداث الـagent ولا transcripts ولا checkpoints ولا سجلات الـapproval ولا trace spans ولا cassettes مسجَّلة.
خوادم MCP مع OAuth
خوادم MCP المستضافة مثل Linear وGitHub وAtlassian وNotion تتطلب OAuth 2.1 كما تعرّفه مواصفة تفويض MCP. أعطِ مدخل HTTP فيmcpServers حقل oauth والـSDK يتولى البروتوكول: يقرأ metadata المورد المحمي للخادم (RFC 9728) ليجد authorization server الخاص به، ويقرأ metadata ذلك الخادم (RFC 8414)، ويسجّل client إذا لم يكن لديك واحد (dynamic client registration، RFC 7591)، ويسجّل الدخول بـPKCE (S256) وresource indicator (RFC 8707). والـtokens تُحفظ في token store الـagent (مشفَّرة في الـstores الدائمة) تحت اسم provider mcp-<server>، ويجدّدها MCP SDK حين يرفض الخادم واحدًا منتهيًا.
oauth يقبل:
redirectUri(مطلوب): عنوان الـcallback للـagent، أي مسار الـcallback في الـagent المنشور.clientId، وclientSecretلـconfidential client: client سجّلته بنفسك لدى authorization server. ودونclientId، يسجّل الـSDK واحدًا عند أول تسجيل دخول (باسمclientName، والافتراضيlousho، وredirectUriهو الـredirect URI الوحيد له) ويحتفظ به في الـtoken store.scopes: تُطلب حين لا تسمّي metadata الخادم أيًّا منها.
agent.oauth.mcpSignInUrl('<server>') (آخر سطر في المثال أعلاه) تعيد رابط التفويض؛ يفتحه المشغّل ويوافق، ومسار الـcallback في الـagent المنشور، الذي يشارك الـstore نفسه، يخزّن الـtoken. والرابط يعمل مرة واحدة، لمدة 10 دقائق. وmcpSignInUrl() تصنع رابطًا جديدًا دائمًا، حتى لو كان هناك token مخزَّن، فهي أيضًا تعيد ربط التطبيق بحساب آخر. وأول ready() أو tool call بعدها يتصل بالـtoken الجديد؛ ولا شيء يحتاج restart.
needs-auth. إلى أن يُسجَّل دخول التطبيق، أو بعد إلغاء الـgrant (الـtoken مرفوض ومعه الـrefresh token)، تكون حالة الخادم 'needs-auth' والاتصال يفشل بـLOUSHO_MCP_AUTH_REQUIRED: ready() وأول send() يرفضان به (أو، مع connectMcp(servers, { onError: 'skip' })، يُترك الخادم خارجًا). وtool call مرفوض أثناء run يصبح نتيجة خطأ للـmodel، بالرمز نفسه؛ والـrun لا يتوقف، لأن مستخدم الدردشة لا يسجّل الدخول عن التطبيق أبدًا. والاتصال لا يسجّل client ولا يبدأ تسجيل دخول من نفسه: mcpSignInUrl() وحدها تفعل.
الأمان.
oauthيحتاج url بـhttps؛ وhttpالعادي مسموح فقط لـlocalhostو127.0.0.1و[::1]. وheadersتظل تعمل بجانبoauth(header بمفتاح API مثلًا) وتُرسَل فقط إلى origin خادم MCP نفسه، ولا تُرسَل إلى authorization server أبدًا؛ وheaderAuthorizationمعoauthيُرفض.- الـtoken يُرسَل فقط إلى الـ
urlالذي أُخذ له. وإذا تغيّرurlالمدخل، لا يُستخدم الـgrant المخزَّن ولا أي client مسجَّل، ويحتاج الخادم إلى تسجيل دخول جديد. والـSDK يرفض أيضًا metadata المورد المحمي إذا كانresourceفيها لا يطابق عنوان الخادم. - الـtokens وauthorization codes وPKCE verifiers وclient secret لا تظهر أبدًا في رسائل الأخطاء ولا أسطر الـlogs ولا
status()ولا أحداث الـagent ولا نتائج الأدوات؛ وخطأ authorization server يُبلَّغ عنه برمزerrorالخاص بـOAuth فقط.
private_key_jwt غير مدعومة.
لاستخدام connectMcp() بدون agent، مرّر الـstore هكذا: connectMcp(servers, { tokens: store.tokens }). هي تستخدم الـtoken المخزَّن، وتسجيل الدخول يمر عبر agent.oauth.mcpSignInUrl() في agent على الـstore نفسه.