syntropy 0.30.0 → 0.32.0

data/examples/blog/app/posts/index.rb

@@ -0,0 +1,38 @@
+@post_store = import '_lib/post_store'
+@layout = import '_layout/default'
+
+export http_methods
+
+def get(req)
+  posts = @post_store.get_all
+  req.respond_html(
+    @template.render(posts:)
+  )
+end
+
+def post(req)
+  data = req.get_form_data
+  title = req.validate(data['title'], String, /.+/)
+  body = req.validate(data['body'], String, /.+/)
+  id = @post_store.create(title, body)
+
+  req.redirect("posts/#{id}")
+end
+
+@template = @layout.apply { |**props|
+  h1 "My blog"
+  props[:posts].each { |post|
+    div {
+      h2 {
+        a post[:title], href: "/posts/#{post[:id]}"
+      }
+      p post[:body]
+    }
+  }
+
+  div {
+    p {
+      a "New post", href: '/posts/new'
+    }
+  }
+}

data/examples/blog/app/posts/new.rb

@@ -0,0 +1,29 @@
+@post_store = import '/_lib/post_store'
+@layout = import '/_layout/default'
+
+export http_methods
+
+def get(req)
+  req.respond_html(
+    @template.render
+  )
+end
+
+@template = @layout.apply { |**props|
+  h1 "Create blog post"
+  div {
+    form(action: "/posts", method: 'post') {
+      div {
+        label 'Title', for: 'title'
+        input name: 'title', type: 'text'
+      }
+      div {
+        label 'Body', for: 'body'
+        textarea '', name: 'body', rows: 5
+      }
+      div {
+        button 'Submit', type: 'submit'
+      }
+    }
+  }
+}

data/examples/mcp-oauth/.ruby-version

@@ -0,0 +1 @@
+4.0.3

data/examples/mcp-oauth/Gemfile

@@ -0,0 +1,8 @@
+source 'https://gem.coop'
+
+gem 'syntropy', path: '../..'
+gem 'jwt'
+
+group :development do
+  gem 'minitest'
+end

data/examples/mcp-oauth/README.md

@@ -0,0 +1,128 @@
+# Syntropy OAuth 2.1 Example App
+
+This app implements a site that includes an MCP server with OAuth 2.1 authorization.
+
+## Authorization workflow:
+
+### Phase 1: Discovery
+
+- MCP client accesses the mcp endpoint:
+
+  `GET /mcp`
+
+  Response headers:
+
+  ```
+  HTTP/1.1 401 Unauthorized
+  WWW-Authenticate: Bearer realm="mcp", resource_metadata="http://localhost:1234/.well-known/oauth-protected-resource"
+  ```
+
+- MCP client makes a request to the protected resource endpoint in order to the
+  protected resource metadata:
+
+  `GET /.well-known/oauth-protected-resource`
+
+  Response JSON:
+
+  ```
+  {
+    resource:               "http://localhost:1234/",
+    authorization_servers:  ["http://localhost:1234/"],
+    scopes_supported:       ["mcp:read", "mcp:write"]
+  }
+  ```
+
+- MCP client makes a request to the authorization server:
+
+  `GET /.well-known/oauth-authorization-server`
+
+  Response JSON:
+
+  ```
+  {
+    issuer:                                 "http://localhost:1234/",
+    registration_endpoint:                  "http://localhost:1234/oauth/register",
+    authorization_endpoint:                 "http://localhost:1234/oauth/authorize",
+    token_endpoint:                         "http://localhost:1234/oauth/token",
+    scopes_supported:                       ["mcp:read", "mcp:write"],
+    response_types_supported:               ["code"]
+  }
+  ```
+
+### Phase 2: Dynamic Client Registration (DCR)
+
+- MCP client makes a request to the register endpoint
+
+  ```
+  POST /oauth/register
+  Content-Type: application/json
+
+  {
+    "client_name": "Cursor AI Agent",
+    "redirect_uris": ["http://localhost:8400/callback"],
+    "grant_types": ["authorization_code", "refresh_token"]
+  }
+  ```
+
+  Response:
+
+  ```
+  HTTP/1.1 201 Created
+  Content-Type: application/json
+
+  {
+    "client_id": "mcp_client_xyz789",
+    "client_name": "Cursor AI Agent",
+    "redirect_uris": ["http://localhost:8400/callback"],
+    "grant_types": ["authorization_code", "refresh_token"]
+  }
+  ```
+
+### Phase 3: Authorization Request with PKCE
+
+- MCP client opens a browser with a URL pointing to the authorization endpoint:
+
+  `GET /oauth/authorize?response_type=code&client_id=mcp_client_xyz789&redirect_uri=http%3A%2F%2Flocalhost%3A8400%2Fcallback&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&state=random_state_string HTTP/1.1`
+
+  the server leads the user through signin and consent workflow. Finally it
+  generates a temporary auth code and redirects to the client's callback URL:
+
+  Response:
+
+  ```
+  HTTP/1.1 302 Found
+  Location: http://localhost:8400/callback?code=splat-auth-code-123&state=random_state_string
+  ```
+
+### Phase 4: Token Exchange
+
+- MCP client grabs the code and exchanges it with the token endpoint:
+
+  ```
+  POST /oauth/token HTTP/1.1
+  Host: auth.example.com
+  Content-Type: application/x-www-form-urlencoded
+
+  grant_type=authorization_code&code=splat-auth-code-123&redirect_uri=http%3A%2F%2Flocalhost%3A8400%2Fcallback&client_id=mcp_client_xyz789&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
+  ```
+
+  The authorization server hashes the code_verifier and verifies it matches the
+  challenge submitted in Phase 3. If it does, it returns an access token:
+
+  ```
+  HTTP/1.1 200 OK
+  Content-Type: application/json
+
+  {
+    "access_token": "mcp_access_token_abc123",
+    "token_type": "Bearer",
+    "expires_in": 3600,
+    "refresh_token": "mcp_refresh_token_def456"
+  }
+  ```
+
+### And we're done
+
+The client can now seamlessly access the MCP resources by attaching the header:
+
+`Authorization: Bearer mcp_access_token_abc123`

data/examples/mcp-oauth/app/.well-known/oauth-authorization-server.rb

@@ -0,0 +1,18 @@
+# https://datatracker.ietf.org/doc/html/rfc8414#section-2
+export ->(req) {
+  req.respond_json(
+    {
+      issuer:                                 "http://localhost:1234/",
+      registration_endpoint:                  "http://localhost:1234/oauth/register",
+      authorization_endpoint:                 "http://localhost:1234/oauth/authorize",
+      token_endpoint:                         "http://localhost:1234/oauth/token",
+      scopes_supported:                       ["mcp:read", "mcp:write"],
+      response_types_supported:               ["code"]
+      # jwks_uri:                               "http://localhost:1234/.well-known/jwks.json",
+      # grant_types_supported:                  ["authorization_code", "refresh_token"],
+      # code_challenge_methods_supported:       ["S256"],
+      # claims_supported:                       ["aud", "iss", "exp", "scope", "sub"],
+      # client_id_metadata_document_supported:  true
+    }
+  )
+}

data/examples/mcp-oauth/app/.well-known/oauth-protected-resource.rb

@@ -0,0 +1,10 @@
+# https://datatracker.ietf.org/doc/html/rfc9728#name-protected-resource-metadata
+export ->(req) {
+  req.respond_json(
+    {
+      resource:                 "http://localhost:1234/",
+      authorization_servers:    ["http://localhost:1234/"],
+      scopes_supported:         ["mcp:read", "mcp:write"]
+    }
+  )
+}

data/examples/mcp-oauth/app/_lib/auth_store.rb

@@ -0,0 +1,23 @@
+export self
+
+require 'securerandom'
+
+@store = {}
+
+def store(params)
+  key = SecureRandom.hex(16)
+  @store[key] = params
+  key
+end
+
+def fetch(key)
+  @store[key]
+end
+
+def update(key, value)
+  @store[key] = value
+end
+
+def fetch_and_remove(key)
+  @store.delete(key)
+end

data/examples/mcp-oauth/app/index.md

@@ -0,0 +1 @@
+# Syntropy OAuth 2.1 Example

data/examples/mcp-oauth/app/mcp.rb

@@ -0,0 +1,85 @@
+AuthStore = import './_lib/auth_store'
+
+export ->(req) {
+  req.validate_http_method('post')
+  req.validate_content_type('application/json')
+
+  if !(token_info = valid_token?(req))
+    respond_unauthorized(req)
+    return
+  end
+
+  handle(req, token_info)
+}
+
+# @param req [Syntropy::Request]
+def valid_token?(req)
+  token = req.auth_bearer_token
+  return false if !token
+
+  token_info = AuthStore.fetch(token)
+  return false if !token_info
+
+  true
+end
+
+def respond_unauthorized(req)
+  req.respond_json(
+    {
+      error:    'unauthorized',
+      message:  'Authentication required'
+    },
+    ':status'           => HTTP::UNAUTHORIZED,
+    'WWW-Authenticate'  => <<~EOF.tr("\n", ' ')
+      Bearer realm="mcp",
+      resource_metadata="http://localhost:1234/.well-known/oauth-protected-resource"
+    EOF
+  )
+end
+
+def handle(req, token_info)
+  req.validate_http_method('post')
+  req.validate_content_type('application/json')
+  json = JSON.parse(req.read)
+
+  req.validate(json['jsonrpc'], '2.0')
+  req.validate(json['id'], [Integer, String])
+
+  method = req.validate(json['method'], String)
+  sym = :"handle_#{method}"
+  raise Syntropy::ValidationError, 'METHOD_NOT_FOUND: method not found' if !respond_to?(sym)
+
+  send(sym, req, json, token_info)
+rescue Syntropy::ValidationError => e
+  if (m = e.message.match(/(.+)\: (.+)/))
+    type, message = m[1], m[2]
+  else
+    type, message = 'INVALID_REQUEST', e.message
+  end
+  respond_error(req, json, type, message)
+end
+
+ERROR_CODES = {
+  'INVALID_REQUEST'   => -32600,
+  'METHOD_NOT_FOUND'  => -32601,
+  'INVALID_PARAMS'    => -32602,
+  'INTERNAL_ERROR'    => -32603,
+  'PARSE_ERROR'       => -32700
+}
+
+def respond_error(req, json, error_type, error_message)
+  error_code = ERROR_CODES[type] || ERROR_CODES['INTERNAL_ERROR']
+  req.respond_json(
+    {
+      jsonrpc: '2.0',
+      id: json['id'],
+      error: {
+        code:     error_code,
+        message:  error_message
+      }
+    }
+  )
+end
+
+def handle_initialize()
+end

data/examples/mcp-oauth/app/oauth/authorize.rb

@@ -0,0 +1,18 @@
+AuthStore = import '../_lib/auth_store'
+
+# https://datatracker.ietf.org/doc/html/rfc6749#section-3.1
+export ->(req) {
+  req.validate_http_method('get')
+  params = req.query
+  req.validate(params['response_type'], 'code')
+
+  client_info = AuthStore.fetch(params['client_id'])
+  req.validate(client_info, Hash)
+
+  key = AuthStore.store(req.query)
+  req.respond(nil, {
+    ':status' => Syntropy::HTTP::FOUND,
+    'Location' => '/signin',
+    'Set-Cookie' => "oauth_signin_id=#{key}"
+  })
+}

data/examples/mcp-oauth/app/oauth/consent.rb

@@ -0,0 +1,86 @@
+AuthStore = import '../_lib/auth_store'
+
+export ->(req) {
+  case req.method
+  when 'get'
+    render_consent_form(req)
+  when 'post'
+    validate_consent(req)
+  else
+    raise Syntropy::Error.method_not_allowed
+  end
+}
+
+def render_consent_form(req)
+  oauth_signin_id = req.cookies['oauth_signin_id']
+  auth_info = AuthStore.fetch(oauth_signin_id)
+  req.validate(auth_info, Hash)
+
+  client_id = auth_info['client_id']
+  req.validate(client_id, String)
+  client_info = AuthStore.fetch(client_id)
+
+  sid = auth_info['sid']
+  req.validate(sid, String)
+  session_info = AuthStore.fetch(sid)
+
+  req.respond_html(@consent_form.render(client_info, session_info))
+end
+
+def validate_consent(req)
+  data = req.get_form_data
+  decision = data['decision']
+  req.validate(decision, ['deny', 'allow'])
+
+  oauth_signin_id = req.cookies['oauth_signin_id']
+  auth_info = AuthStore.fetch(oauth_signin_id)
+  req.validate(auth_info, Hash)
+
+  callback_query = case decision
+  when 'deny'
+    {
+      error: 'access_denied',
+      state: auth_info['state']
+    }
+  when 'allow'
+    auth_code = AuthStore.store(auth_info)
+    {
+      code: auth_code,
+      state: auth_info['state']
+    }
+  end
+
+  uri = format(
+    '%s?%s', auth_info['redirect_uri'],
+    URI.encode_www_form(callback_query)
+  )
+  req.respond(
+    nil,
+    ':status' => Syntropy::HTTP::FOUND,
+    'Location' => uri
+  )
+end
+
+@consent_form = template { |client_info, session_info|
+  html {
+    head {
+      title 'My awesome site'
+    }
+    body {
+      h2 client_info['client_name']
+      p {
+        span 'wants to access my awesome site on behalf of '
+        em session_info[:username]
+        span '.'
+      }
+
+      form(action: '') {
+        div {
+          button 'Deny',  type: 'submit', name: 'decision', value: 'deny'
+          button 'Allow', type: 'submit', name: 'decision', value: 'allow'
+        }
+      }
+    }
+    auto_refresh!
+  }
+}

data/examples/mcp-oauth/app/oauth/register.rb

@@ -0,0 +1,14 @@
+AuthStore = import '../_lib/auth_store'
+
+# https://datatracker.ietf.org/doc/html/rfc7591
+export ->(req) {
+  req.validate_http_method('post')
+  req.validate_content_type('application/json')
+  client_info = JSON.parse(req.read)
+  client_id = AuthStore.store(client_info)
+
+  req.respond_json(
+    { client_id: }.merge(client_info),
+    ':status' => HTTP::CREATED
+  )
+}

data/examples/mcp-oauth/app/oauth/token.rb

@@ -0,0 +1,79 @@
+AuthStore = import '../_lib/auth_store'
+
+# https://datatracker.ietf.org/doc/html/rfc6749#section-5
+export ->(req) do
+  req.validate_http_method('post')
+  params = req.get_form_data
+  req.validate(
+    params['redirect_uri'], String,
+    message: 'invalid_request'
+  )
+
+  req.validate(
+    params['grant_type'], 'authorization_code',
+    message: 'unsupported_grant_type'
+  )
+
+  code = params['code']
+  auth_info = AuthStore.fetch(code)
+  req.validate(
+    auth_info, Hash,
+    message: 'invalid_request'
+  )
+
+  req.validate(
+    params['redirect_uri'], auth_info['redirect_uri'],
+    message: 'invalid_request'
+  )
+
+  client_id = params['client_id']
+  client_info = AuthStore.fetch(client_id)
+  req.validate(
+    client_info, Hash,
+    message: 'invalid_client'
+  )
+
+  code_verifier = params['code_verifier']
+  hashed = Base64.urlsafe_encode64(Digest::SHA256.digest(code_verifier), padding: false)
+  req.validate(
+    hashed, auth_info['code_challenge'],
+    message: 'invalid_grant'
+  )
+
+  session_info = AuthStore.fetch(auth_info['sid'])
+  req.validate(
+    session_info, Hash,
+    message: 'invalid_grant'
+  )
+
+  token_info = session_info.merge(
+    # some app-specific metadata
+    type: 'oauth',
+    ttl: 86400 * 30
+  )
+  token = AuthStore.store(token_info)
+
+  req.respond_json({
+    access_token: token,
+    token_type: 'Bearer',
+    expires_in: token_info[:ttl]
+  })
+rescue ValidationError => e
+  req.respond_json(
+    {
+      error: e.message
+    },
+    ':status' => Syntropy::HTTP::BAD_REQUEST
+  )
+rescue => e
+  status = Syntropy::Error.http_status(e)
+  raise if status == HTTP::INTERNAL_SERVER_ERROR
+
+  req.respond_json(
+    {
+      error: 'invalid_request',
+      error_description: e.message
+    },
+    ':status' => Syntropy::HTTP::BAD_REQUEST
+  )
+end

data/examples/mcp-oauth/app/signin.rb

@@ -0,0 +1,85 @@
+AuthStore = import '../_lib/auth_store'
+
+export ->(req) {
+  case req.method
+  when 'get'
+    render_signin_form(req)
+  when 'post'
+    validate_signin(req)
+  else
+    raise Syntropy::Error.method_not_allowed
+  end
+}
+
+def render_signin_form(req)
+  req.respond_html(@signin_form.render)
+end
+
+def validate_signin(req)
+  creds = req.get_form_data
+
+  if !valid_creds?(creds)
+    req.respond_html(
+      @signin_form.render,
+      ':status' => Syntropy::HTTP::UNAUTHORIZED
+    )
+    return
+  end
+
+  sid = AuthStore.store({
+    username: creds['username'],
+    timestamp: Time.now.to_i
+  })
+
+  oauth_signin_id = req.cookies['oauth_signin_id']
+  if oauth_signin_id
+    auth_info = AuthStore.fetch(oauth_signin_id)
+    AuthStore.update(oauth_signin_id, auth_info.merge('sid' => sid))
+    req.validate(auth_info, Hash)
+    req.respond(
+      nil,
+      ':status'     => Syntropy::HTTP::SEE_OTHER,
+      'Location'    => '/oauth/consent',
+    )
+    return
+  end
+
+  req.respond(
+      nil,
+      ':status'     => Syntropy::HTTP::SEE_OTHER,
+      'Location'    => '/',
+      'Set-Cookie'  => "sid=#{sid}"
+    )
+end
+
+def valid_creds?(creds)
+  (creds['username'] == 'foobar') && (creds['password'] == 'foobar')
+end
+
+@signin_form = template {
+  html {
+    head {
+      title 'My awesome site'
+    }
+    body {
+      h1 'Sign in:'
+
+      form(method: 'post') {
+        div {
+          label 'username:', for: 'username'
+          input type: 'text', name: 'username', required: true
+        }
+
+        div {
+          label 'password:', for: 'password'
+          input type: 'password', name: 'password', required: true
+        }
+
+        div {
+          input type: 'submit', value: 'Submit'
+        }
+      }
+    }
+    auto_refresh!
+  }
+}

data/examples/mcp-oauth/test/helper.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# require 'bundler/setup'
+# require 'syntropy'
+# require 'syntropy/test'
+# require 'minitest/autorun'
+
+# STDOUT.sync = true
+# STDERR.sync = true

data/examples/mcp-oauth/test/test_app.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'helper'
+
+class AppTest < Minitest::Test
+  APP_ROOT = File.expand_path(File.join(__dir__, '../app'))
+  HTTP = Syntropy::HTTP
+
+  def setup
+    @machine = UM.new
+    @app = Syntropy::App.new(
+      root_dir: APP_ROOT,
+      mount_path: '/',
+      machine: @machine
+    )
+    @test_harness = Syntropy::TestHarness.new(@app)
+  end
+
+  def test_root
+    req = @test_harness.request(
+      ':method' => 'GET',
+      ':path'   => '/'
+    )
+    assert_equal HTTP::OK, req.response_status
+    assert_match /Syntropy/, req.response_body
+  end
+end