1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
|
local ext = require('panto').ext
local json = ext.json
local async = require('panto_mcp.async')
local config = require('panto_mcp.config')
local M = {}; M.__index=M
local function nonempty(v) return type(v)=='string' and v~='' and not v:find('[%z\1-\32\127]') end
-- Credentials, fragments and ambiguous authorities are never accepted.
function M.url(value)
if type(value)~='string' or value:find('[%z\1-\32\127\\#]') then return nil end
local scheme,authority,tail=value:match('^([A-Za-z]+)://([^/?]+)(.*)$')
if not scheme then return nil end
scheme=scheme:lower(); if scheme~='https' and scheme~='http' then return nil end
local host,port
if authority:sub(1,1)=='[' then host,port=authority:match('^(%[[%x:]+%])(:?%d*)$')
else host,port=authority:match('^([A-Za-z0-9.-]+)(:?%d*)$') end
if not host or port==':' then return nil end
if port~='' and (not tonumber(port:sub(2)) or tonumber(port:sub(2))<1 or tonumber(port:sub(2))>65535) then return nil end
host=host:lower()
local literal_loopback=host=='[::1]'
local mapped_loopback=false
if host:sub(1,1)=='[' then
local address=host:sub(2,-2); local left,right=address:match('^(.-)::(.-)$')
local groups={}
for group in (left or address):gmatch('[^:]+') do groups[#groups+1]=tonumber(group,16) end
if left then
local suffix={}; for group in right:gmatch('[^:]+') do suffix[#suffix+1]=tonumber(group,16) end
while #groups+#suffix<8 do groups[#groups+1]=0 end
for _,group in ipairs(suffix) do groups[#groups+1]=group end
end
if #groups==8 then
local zeros=true; for i=1,5 do if groups[i]~=0 then zeros=false end end
literal_loopback=zeros and groups[6]==0 and groups[7]==0 and groups[8]==1
mapped_loopback=zeros and groups[6]==0xffff and groups[7]>=0x7f00 and groups[7]<=0x7fff
end
end
local a,b,c,d=host:match('^(%d+)%.(%d+)%.(%d+)%.(%d+)$')
if a then
for _,octet in ipairs({a,b,c,d}) do
if (#octet>1 and octet:sub(1,1)=='0') or tonumber(octet)>255 then return nil end
end
literal_loopback=a=='127'
elseif host:match('^[%d.]+$') then return nil end
for octet in host:gmatch('[^.]+') do if octet:match('^0x%x+$') then return nil end end
if scheme=='http' and not literal_loopback then return nil end
if (scheme=='https' and port==':443') or (scheme=='http' and port==':80') then port='' end
local origin=scheme..'://'..host..port
if tail=='/' then tail='' end
return origin..tail,origin,tail:match('^[^?]*'),literal_loopback or mapped_loopback or host=='localhost' or host=='localhost.' or host:match('%.localhost%.?$')~=nil
end
function M.prm_urls(resource)
local _,origin,path=M.url(resource); if not origin then return {} end
local root=origin..'/.well-known/oauth-protected-resource'
return path~='' and {root..path,root} or {root}
end
function M.metadata_urls(issuer)
local _,origin,path=M.url(issuer)
if not origin or issuer:find('?',1,true) then return {} end
path=path:gsub('/$','')
local urls={origin..'/.well-known/oauth-authorization-server'..path,origin..'/.well-known/openid-configuration'..path}
if path~='' then urls[#urls+1]=origin..path..'/.well-known/openid-configuration' end
return urls
end
function M.scopes(value)
local out,seen={},{}
if type(value)=='string' then
local parts={}; for part in value:gmatch('%S+') do parts[#parts+1]=part end; value=parts
end
if type(value)~='table' then return out end
for _,v in ipairs(value) do
local valid=type(v)=='string' and v~=''
if valid then
for i=1,#v do
local byte=v:byte(i)
if byte<33 or byte>126 or byte==34 or byte==92 then valid=false; break end
end
end
if valid and not seen[v] then seen[v]=true; out[#out+1]=v end
end
return out
end
function M.union(a,b)
local out=M.scopes(a); local seen={}; for _,v in ipairs(out) do seen[v]=true end
for _,v in ipairs(M.scopes(b)) do if not seen[v] then seen[v]=true; out[#out+1]=v end end
return out
end
-- Commas inside quoted strings are not challenge separators; quoted-pairs are unescaped.
function M.challenge(header)
if type(header)~='string' or #header>16384 or header:find('[\r\n%z]') then return {} end
local chunks,begin,quoted,escaped={},1,false,false
for i=1,#header do
local c=header:sub(i,i)
if escaped then escaped=false
elseif quoted and c=='\\' then escaped=true
elseif c=='"' then quoted=not quoted
elseif c==',' and not quoted then chunks[#chunks+1]=header:sub(begin,i-1); begin=i+1 end
end
if quoted or escaped then return {} end
chunks[#chunks+1]=header:sub(begin)
local candidates,current={},nil
for _,chunk in ipairs(chunks) do
chunk=chunk:match('^%s*(.-)%s*$')
local scheme,rest=chunk:match('^([%w!#$%%&\'*+.^_`|~-]+)%s+(.+)$')
if scheme and not rest:match('^=') then
current={scheme=scheme:lower()}; candidates[#candidates+1]=current; chunk=rest
elseif chunk:match('^[%w_-]+$') then
current={scheme=chunk:lower()}; candidates[#candidates+1]=current; chunk=''
end
if current and chunk~='' then
local key,value=chunk:match('^([%w!#$%%&\'*+.^_`|~-]+)%s*=%s*(.-)%s*$')
if key then
key=key:lower()
if value:sub(1,1)=='"' and value:sub(-1)=='"' then
value=value:sub(2,-2):gsub('\\(.)','%1')
elseif not value:match('^[%w!#$%%&\'*+.^_`|~-]+$') then current.invalid=true end
if current[key]~=nil then current.invalid=true end
current[key]=value
else current.invalid=true end
end
end
local first
for _,c in ipairs(candidates) do
if c.scheme=='bearer' and not c.invalid then
local safe={resource_metadata=c.resource_metadata,scope=c.scope,error=c.error}
if c.resource_metadata then return safe end
first=first or safe
end
end
return first or {}
end
function M.validate_metadata(metadata,issuer)
if type(metadata)~='table' or metadata.issuer~=issuer then return nil,'OAuth metadata issuer mismatch' end
if not M.url(metadata.authorization_endpoint) or not M.url(metadata.token_endpoint) then return nil,'OAuth metadata has unsafe endpoints' end
local s256=false
for _,method in ipairs(type(metadata.code_challenge_methods_supported)=='table' and metadata.code_challenge_methods_supported or {}) do
if method=='S256' then s256=true end
end
if not s256 then return nil,'OAuth server must advertise PKCE S256' end
if metadata.authorization_response_iss_parameter_supported~=nil and type(metadata.authorization_response_iss_parameter_supported)~='boolean' then
return nil,'Invalid OAuth issuer-response metadata'
end
return true
end
function M.session_name(server,resource,issuer,client_id)
local identity=json.encode({resource=resource,issuer=issuer,client_id=client_id})
return 'mcp.'..server:sub(1,91)..'.'..require('panto_mcp.hash').sha256(identity):sub(1,32)
end
function M.new(cfg,opts)
opts=opts or {}
local resource,origin,_,loopback=M.url(cfg.url)
local self=setmetatable({cfg=cfg,name=cfg.auth,auth=opts.auth or ext.auth,
state=opts.state or ext.state,request_fn=opts.request_fn or ext.http_request,
timer_factory=opts.timer_factory or async.timer,clock=opts.clock or require('luv').now,
timers={},resource=resource,origin=origin,loopback=loopback},M)
self.key='mcp.oauth.server_'..cfg.name
if not cfg.auth and self.state then
local stored=self.state.get(self.key)
if type(stored)=='table' and stored.version==2 and stored.fingerprint==cfg.fingerprint and stored.resource==resource and self:available() then
self.name=stored.name
self:define(stored)
end
end
return self
end
function M:available()
return type(self.auth)=='table' and type(self.auth.define)=='function' and type(self.auth.status)=='function'
and type(self.auth.login)=='function' and type(self.auth.refresh)=='function' and type(self.auth.complete)=='function'
end
function M:login_error() return 'Authentication required; run /mcp-login '..self.cfg.name end
function M:recovery_error(text)
if self.cfg.auth then return text..'; check configured auth with panto auth login/status' end
local hint=(self.cfg.oauth and self.cfg.oauth.client_id) and 'check the configured OAuth client/issuer' or
('try /mcp-login '..self.cfg.name..' --reregister to replace a stale DCR client')
return text..'; '..hint
end
function M:usable()
local state=self:auth_status().state
return state=='logged_in' or (state=='pending' and self.login_usable==true)
end
function M:configured_error()
return 'Configured auth session rejected (HTTP 401); check its credentials/type with panto auth login/status'
end
function M:auth_status()
if not self.name or not self:available() then return {state='logged_out'} end
local now=self.clock()
if not self.cached_status or now>=(self.status_at or 0)+1000 then
self.cached_status=self.auth.status(self.name) or {state='logged_out'}; self.status_at=now
end
return self.cached_status
end
function M:status()
if not self:available() then return 'unavailable' end
if not self.cfg.auth and not self.definition then return 'undiscovered' end
local state=self:auth_status().state
if self.login_required and state~='pending' then return 'login_required' end
return state
end
function M:request_auth()
if self.cfg.auth then return self.cfg.auth end
if self.definition and (self.refreshing or (not self.login_required and self:usable())) then return self.name end
end
function M:blocked()
if self.refreshing then return false end
return not self.cfg.auth and self.definition and (self.login_required or not self:usable())
end
function M:before_request()
if self.refreshing then
local ok,err=self.refreshing:await(); if not ok then return nil,err end
end
if self:blocked() then return nil,self:login_error() end
if not self.definition and self.discovery_error and self.clock()<self.retry_at then return nil,self.discovery_error end
return true
end
function M:url_allowed(url)
local canonical,_,_,loopback=M.url(url)
return canonical and (not loopback or self.loopback)
end
function M:define(stored)
if not self:available() then return nil,'MCP OAuth requires a newer panto with panto.ext.auth' end
if not self.resource then return nil,'MCP OAuth requires HTTPS (or literal loopback HTTP)' end
local configured=self.cfg.oauth
if configured and ((configured.issuer and configured.issuer~=stored.issuer) or
(configured.client_id and (not configured.issuer or configured.client_id~=stored.client_id))) then
return nil,'Configured oauth.issuer does not match the discovered authorization server/client'
end
if not self:url_allowed(stored.issuer) or #M.metadata_urls(stored.issuer)==0 then return nil,'Unsafe OAuth issuer for this resource' end
local ok,err=M.validate_metadata(stored.metadata,stored.issuer); if not ok then return nil,err end
if not self:url_allowed(stored.metadata.authorization_endpoint) or not self:url_allowed(stored.metadata.token_endpoint) then return nil,'Unsafe OAuth endpoint for this resource' end
if not nonempty(stored.client_id) or stored.client_secret~=nil then return nil,'Invalid/public-only OAuth client registration; configure oauth.client_id and oauth.issuer' end
local name=M.session_name(self.cfg.name,self.resource,stored.issuer,stored.client_id)
local spec={type='oauth_pkce',authorization_url=stored.metadata.authorization_endpoint,token_url=stored.metadata.token_endpoint,
client_id=stored.client_id,client_secret=configured and configured.client_secret,
scopes=M.scopes(stored.scopes),resource=self.resource,issuer=stored.issuer,
require_iss=stored.metadata.authorization_response_iss_parameter_supported==true}
if not self.auth.define(name,spec) then return nil,'Cannot define MCP OAuth session (check session name/config collision)' end
if self.name and self.name~=name then
-- Runtime definitions are process-local; a stored old name may need restoring for logout.
if not self.auth.define(self.name,self.spec or spec) then return nil,'Cannot restore the previous OAuth session for logout' end
local ok=self.auth.logout and self.auth.logout(self.name)
if not ok then return nil,'Cannot retire the previous OAuth session' end
end
if self.name~=name then self.cached_status=nil; self.login_usable=nil end
self.name=name; self.definition=stored; self.spec=spec
return true
end
function M:save()
if self.state and self.definition then
local d=self.definition
return self.state.set(self.key,{version=2,name=self.name,fingerprint=self.cfg.fingerprint,resource=self.resource,issuer=d.issuer,
metadata=d.metadata,client_id=d.client_id,scopes=d.scopes})
end
return true
end
function M:invalidate(reregister)
if self.cfg.auth then return end
if self.definition then
self.previous_issuer=self.definition.issuer; self.requested_scopes=self.spec.scopes
end
if reregister and self.state and self.previous_issuer then
self.state.set('mcp.oauth.registration_'..config.hash(self.previous_issuer),nil)
end
if self.state then self.state.set(self.key,nil) end
self.login_poll=(self.login_poll or 0)+1
self.definition=nil; self.spec=nil; self.cached_status=nil; self.login_required=nil; self.login_url=nil
self.discovery_error=nil; self.retry_at=nil; self.backoff=nil
end
function M:fetch(url,body)
if self.closed then return nil,'session ended' end
if not self:url_allowed(url) then return nil,'Unsafe OAuth discovery URL for this resource' end
local future=async.future()
local opts={url=url,method=body and 'POST' or 'GET',timeout_ms=10000,max_bytes=1024*1024,headers={Accept='application/json'}}
if body then opts.body=json.encode(body); opts.headers['Content-Type']='application/json' end
local ok,handle=pcall(self.request_fn,opts,function(response)
if self.closed then future:resolve(nil,'session ended'); return end
if not response or response.status<200 or response.status>=300 then future:resolve(nil,'OAuth discovery/registration request failed'); return end
local decoded,value=pcall(json.decode,response.body or '')
if not decoded or type(value)~='table' then future:resolve(nil,'Invalid OAuth metadata JSON'); return end
future:resolve(value)
end)
if not ok or not handle then return nil,'OAuth HTTP request could not start' end
self.requests=self.requests or {}; self.requests[handle]=future
local value,err=future:await(); self.requests[handle]=nil
return value,err
end
function M:discover(challenge)
if self.cfg.auth then return nil,self:configured_error() end
challenge=challenge or {}
if self.definition then return true end
if self.discovering then return self.discovering:await() end
if self.discovery_error and self.clock()<self.retry_at then return nil,self.discovery_error end
if not self:available() then return nil,'MCP OAuth requires a newer panto with panto.ext.auth and HTTP POST support' end
if not self.resource then return nil,'MCP OAuth requires HTTPS (or literal loopback HTTP)' end
local future=async.future(); self.discovering=future
local function work()
local urls=challenge.resource_metadata and {challenge.resource_metadata} or M.prm_urls(self.resource)
local prm,expected_resource
for i,url in ipairs(urls) do
local value=self:fetch(url)
if value then
prm=value; expected_resource=(not challenge.resource_metadata and i==2) and self.origin or self.resource
break
end
end
if not prm then return nil,'Cannot discover OAuth protected-resource metadata' end
if M.url(prm.resource)~=expected_resource then return nil,'OAuth protected-resource metadata resource mismatch' end
local servers=type(prm.authorization_servers)=='table' and prm.authorization_servers or {}
local issuer=servers[1]
local pinned=self.cfg.oauth and self.cfg.oauth.issuer
if pinned then
issuer=nil
for _,candidate in ipairs(servers) do if candidate==pinned then issuer=candidate; break end end
if not issuer then return nil,'Configured oauth.issuer is not advertised by the resource' end
end
if not issuer or #M.metadata_urls(issuer)==0 or not self:url_allowed(issuer) then return nil,'OAuth resource has no safe authorization server' end
local metadata
for _,url in ipairs(M.metadata_urls(issuer)) do
local value=self:fetch(url)
if value then
local valid,why=M.validate_metadata(value,issuer); if not valid then return nil,why end
metadata={issuer=issuer,authorization_endpoint=value.authorization_endpoint,token_endpoint=value.token_endpoint,
code_challenge_methods_supported={'S256'},registration_endpoint=value.registration_endpoint,
authorization_response_iss_parameter_supported=value.authorization_response_iss_parameter_supported}
break
end
end
if not metadata then return nil,'Cannot discover OAuth authorization-server metadata' end
if not self:url_allowed(metadata.authorization_endpoint) or not self:url_allowed(metadata.token_endpoint) then return nil,'Unsafe OAuth endpoint for this resource' end
local registration=self.cfg.oauth
local registration_key='mcp.oauth.registration_'..config.hash(issuer)
if not registration or not registration.client_id then
registration=self.state and self.state.get(registration_key)
if type(registration)=='table' and registration.client_secret~=nil then
return nil,self:recovery_error('Confidential DCR is unsupported')
end
if type(registration)~='table' or registration.issuer~=issuer or not nonempty(registration.client_id) then
if not self:url_allowed(metadata.registration_endpoint) then return nil,'OAuth server needs configured oauth.client_id and oauth.issuer (no safe DCR endpoint)' end
local value,why=self:fetch(metadata.registration_endpoint,{client_name='panto-mcp',application_type='native',
redirect_uris={'http://127.0.0.1/callback'},token_endpoint_auth_method='none',
grant_types={'authorization_code','refresh_token'},response_types={'code'}})
if not value then return nil,why end
if value.client_secret~=nil or (value.token_endpoint_auth_method~=nil and value.token_endpoint_auth_method~='none') then
return nil,'Confidential DCR is unsupported; configure oauth.client_id, oauth.issuer and optional oauth.client_secret'
end
if not nonempty(value.client_id) then return nil,'Invalid OAuth registration response' end
registration={issuer=issuer,client_id=value.client_id}
if self.state and not self.state.set(registration_key,registration) then return nil,'Cannot persist OAuth registration' end
end
end
local scopes=challenge.scope
if scopes==nil then scopes=prm.scopes_supported end
if scopes==nil then scopes=self.cfg.oauth and self.cfg.oauth.scopes end
if self.previous_issuer==issuer then scopes=M.union(scopes,self.requested_scopes) end
local ok,why=self:define({issuer=issuer,metadata=metadata,client_id=registration.client_id,scopes=M.scopes(scopes)})
if not ok then return nil,why end
if not self:save() then return nil,'Cannot persist OAuth discovery' end
if self.previous_issuer and self.previous_issuer~=issuer and self.state then
self.state.set('mcp.oauth.registration_'..config.hash(self.previous_issuer),nil)
end
return true
end
local ok,value,err=pcall(work)
if not ok then value=nil; err='OAuth discovery failed' end
if not value then
self.backoff=math.min((self.backoff or 2500)*2,60000); self.retry_at=self.clock()+self.backoff; self.discovery_error=err
else self.backoff=nil; self.discovery_error=nil; self.retry_at=nil end
self.discovering=nil; future:resolve(value,err)
return value,err
end
function M:poll(callback,remaining,active)
if self.closed then return end
local t
t=self.timer_factory(1000,function()
self.timers[t]=nil
if self.closed or (active and not active()) then return end
local status=self:auth_status()
if status.state~='pending' then callback(status); return end
if remaining<=1000 then callback(nil); return end
self:poll(callback,remaining-1000,active)
end)
self.timers[t]=true
end
function M:refresh()
if self.refreshing then return self.refreshing:await() end
local future=async.future(); self.refreshing=future
local ok=self.auth.refresh(self.name)
if not ok then self.refreshing=nil; return nil,self.cfg.auth and self:configured_error() or self:recovery_error(self:login_error()) end
self.cached_status={state='pending'}; self.status_at=self.clock()
self:poll(function(status)
self.refreshing=nil
if status and status.state=='logged_in' and not status.error then future:resolve(true)
else future:resolve(nil,self.cfg.auth and self:configured_error() or self:recovery_error(self:login_error())) end
end,70000)
return future:await()
end
function M:recover(data)
local challenge=data.challenge or {}
if data.http_status==403 then
if challenge.error~='insufficient_scope' then return nil,'Forbidden (HTTP 403); check server permissions' end
if self.cfg.auth then return nil,'Configured auth session needs additional scopes; update its scopes and use panto auth login' end
if not self.definition then return nil,'Insufficient scope (HTTP 403); no OAuth definition is available' end
local scopes=M.union(M.union(self.spec.scopes,self:auth_status().scopes),challenge.scope)
self.definition.scopes=scopes
local ok,err=self:define(self.definition); if not ok then return nil,err end
self:save()
return nil,'Additional permission required; run /mcp-login '..self.cfg.name
end
if not self:available() then
return nil,self.cfg.auth and self:configured_error() or 'MCP OAuth requires a newer panto with panto.ext.auth and HTTP POST support'
end
if data.auth_used then
local ok,err=self:refresh()
if ok or self.cfg.auth then return ok,err end
self:invalidate()
local discovered,why=self:discover(challenge)
self.login_required=not self:usable() or nil
return nil,discovered and err or self:recovery_error(why)
end
local ok,err=self:discover(challenge)
if not ok then return nil,err end
if self:request_auth() then return true end
return nil,self:login_error()
end
function M:login(callback_url,on_success,on_error)
if not self:available() then return nil,self.cfg.auth and 'Configured auth login requires a newer panto and an oauth_pkce session; use panto auth login instead' or 'MCP OAuth requires a newer panto with panto.ext.auth' end
if not self.cfg.auth and not self.definition then return nil,'OAuth discovery is not ready; retry /mcp-login '..self.cfg.name..' after checking /mcp' end
local usable=self:usable()
local result
if callback_url then
if not self.auth.complete(self.name,callback_url) then return nil,'OAuth callback rejected; check the URL/state/issuer and retry' end
elseif self.login_url and self:auth_status().state=='pending' then result={url=self.login_url}
else
result=self.auth.login(self.name)
if not result then
local text='Cannot start OAuth login; check that the configured auth session is oauth_pkce'
return nil,self.cfg.auth and text or self:recovery_error(text)
end
self.login_url=result.url
end
self.login_usable=usable; self.login_required=not usable or nil
self.cached_status={state='pending'}; self.status_at=self.clock()
self.login_poll=(self.login_poll or 0)+1
local generation=self.login_poll
self:poll(function(status)
self.login_required=nil; self.login_url=nil
if status and status.state=='logged_in' and not status.error then
self.login_usable=nil; on_success()
elseif on_error then
on_error(self:recovery_error('OAuth login failed or timed out'))
end
end,670000,function() return generation==self.login_poll end)
return result and result.url or true
end
function M:close()
self.closed=true
for t in pairs(self.timers) do async.close(t) end; self.timers={}
for handle,future in pairs(self.requests or {}) do handle:cancel(); future:resolve(nil,'session ended') end
if self.refreshing then self.refreshing:resolve(nil,'session ended') end
end
return M
|