adonis-oauth-mcp

Monorepo für zwei AdonisJS-Pakete. Sie werden gemeinsam versioniert und veröffentlicht, sodass Änderungen am Ressourcen-Registrierungsvertrag nie eine repo-übergreifende Koordination erfordern.

Die Abhängigkeit verläuft nur in eine Richtung: mcp → oauth. Nichts in oauth darf aus mcp importieren.

Layout

Jedes Paket folgt der AdonisJS-Paketkonvention:

index.ts       re-exports `configure` and `stubsRoot` (what `node ace configure` imports)
configure.ts   the configure hook, driving codemods and stubs
stubs/         .stub templates rendered into the target app
src/           runtime code the app imports
providers/     service providers registered by the configure hook
services/      container services, for code that cannot use dependency injection

Related MCP server: OAuth MCP Server

Entwicklung

npm install     # links the workspaces
npm run build   # tsc + copy stubs, per package
npm run typecheck
npm test        # runs against build/, so build first

Installieren Sie während der Entwicklung in eine App aus diesem Checkout (npm link, file: oder eine Git-Abhängigkeit) statt aus der Registry.

@dinko/adonis-oauth

Ein OAuth-2.1-Autorisierungsserver mit PKCE für AdonisJS-Anwendungen, die Drittanbieter-Clients Zugriffstokens aushändigen müssen.

Das Paket besitzt das Protokoll. Die Anwendung besitzt drei Dinge, die sie nicht delegieren kann: den Zustimmungsbildschirm, welches Token ausgestellt wird und die Routen.

npm i @dinko/adonis-oauth
node ace configure @dinko/adonis-oauth

Die Konfiguration erzeugt drei Dateien und überschreibt niemals eine vorhandene:

Routen

Nicht automatisch registriert — wo sie leben und welche Middleware sie schützt, ist Ihre Entscheidung. Fügen Sie sie zu start/routes.ts hinzu:

router.get('.well-known/oauth-authorization-server', [OauthController, 'getAuthorizationServer'])
router.get('.well-known/oauth-protected-resource/:resource', [OauthController, 'getProtectedResource'])

router
  .group(() => {
    router.post('token', [OauthController, 'token'])
    router
      .group(() => {
        router.post('authorize/approve', [OauthController, 'approveAuthorization'])
        router.post('authorize/deny', [OauthController, 'denyAuthorization'])
      })
      .use(middleware.auth())
  })
  .prefix('oauth')

Approve und deny müssen authentifiziert sein: Der Autorisierungscode ist an den Benutzer gebunden, der den Zugriff gewährt. Der Token-Endpunkt ist laut Spezifikation öffentlich und ist der Ort, an dem Autorisierungscodes eingelöst werden, daher ist er ein guter Ort für eine Drosselung.

Die Weiterleitung zurückgeben

Approve und deny antworten standardmäßig mit 200 { redirect_to }, und der Zustimmungsbildschirm navigiert selbst:

window.location.assign(response.redirect_to)

Das ist es, was ein Bildschirm braucht, der seine Entscheidung mit fetch oder axios übermittelt. Ein XHR folgt einer 302, indem es die Anfrage erneut ausführt, sodass die Seite nie navigiert: Der Benutzer bleibt auf dem Zustimmungsbildschirm, während die Anfrage Cross-Origin auf dem Callback des Clients landet und an CORS scheitert.

Setzen Sie redirectMode: 'http', wenn der Zustimmungsbildschirm ein einfaches HTML-Formular ist. Dort navigiert der Browser das Dokument, folgt also der 302 nativ, und der Benutzer landet beim Client.

Tokens ausstellen

Der Tokentyp hängt von der aufgerufenen Ressource ab, daher liegt diese Entscheidung bei jeder Ressource und nicht im Controller. Sobald das Paket die Anfrage validiert, den Autorisierungscode verbraucht und den PKCE-Verifier verifiziert hat, ruft es auf:

issueToken: async ({ userId, scopes, client, resource, ctx }) => {
  const user = await User.find(userId)
  if (!user) return null // rejects the exchange with invalid_grant

  const expiresIn = 30 * 24 * 60 * 60
  const token = await User.accessTokens.create(user, scopes, {
    name: `oauth:${client.id}`,
    expiresIn,
  })

  return { accessToken: token.value!.release(), expiresIn }
}

userId ist das, was mit dem Autorisierungscode gespeichert wurde: Das Paket hat keine Kenntnis von Ihrem Benutzermodell und lädt es nie.

Der Zustimmungsbildschirm

Die GET /oauth/authorize-Seite gehört Ihnen — Edge, Inertia oder ein separates Frontend. Das Paket validiert nur die Anfrage dahinter:

const validation = server.validateAuthorizationRequest(request.qs())

if (!validation.valid) {
  return view.render('oauth/authorize', { error: validation.error })
}

return view.render('oauth/authorize', {
  client: validation.client,
  requestedScopes: validation.scopes,
  authorizationFields: validation.fields, // post these back to approve
})

Optional: Anwendungen, die den Bildschirm woanders rendern, können es überspringen, da approve und deny die Anfrage selbst erneut validieren.

Konfiguration

export default defineConfig({
  issuer: env.get('APP_URL'),
  authorizationEndpoint: `${env.get('APP_URL')}/oauth/authorize`,
  tokenEndpoint: `${env.get('APP_URL')}/oauth/token`,

  // optional
  redirectMode: 'json', // or 'http'
  tokenEndpointAuthMethods: ['none'],
  authorizationCodeTtlSeconds: 10 * 60,
  authorizationCodesTable: 'oauth_authorization_codes',
  authenticatedUserId: (ctx) => ctx.auth.user?.id, // defaults to this

  resources: [mcpResource],
})

Jede Ressource deklariert:

Loopback-Redirect-URIs (http://localhost/callback) matchen auf jedem Port, gemäß RFC 8252, und redirectUriPatterns erlaubt ein einzelnes :param-Segment für Clients, deren Callback eine ID trägt.