ai2web 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8142d4c3ef57f6bb7ba24a60b478f4cab0e981c1acf0613f6ace7fe81b69a0a4
+  data.tar.gz: c1ddfcec49f61c4ac55299ce2dfba7467c742faf48d65c7559e581ee4d467eb1
+SHA512:
+  metadata.gz: 82e19660de9ef91eb1a7167038ec9cb15db553d726936380e768305fcdb736cae9598445954d3433cc4915e05b677e977132002cbad2786a30ddfa26fc991177
+  data.tar.gz: dbb147055be31d20c74aab55c6bee8c21dc6f0d6d6574f76a6e0ef35cf0b1280737527b151b14622dfb372032c68407086e215ee036630ca5805a81ca3b03937

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to the AI2Web Ruby SDK are documented here. Versioning is independent per
+language SDK; this SDK targets the AI2Web **v0.2** manifest and mirrors `@ai2web/core`.
+
+## [0.1.0] - 2026-07-19
+
+Initial release. Full parity with the Python/TypeScript reference SDKs, verified against the shared
+conformance contract (`test/conformance_cases.json`).
+
+- Fluent manifest builder (`Ai2Web.ai2web`) incl. the v0.2 optional modules (`governance`,
+  `usage_policy`, `legal`, `agent_identity`, `knowledge`) and action `intent` / `bindings`.
+- AI Readiness validator + scorer (`Ai2Web.validate`), spec §9/§11.
+- Capability negotiation (`Ai2Web.negotiate`), spec §5.
+- Framework-agnostic request handler (`Ai2Web.handle`) with action input-schema validation.
+- SSRF guard (`Ai2Web.safe_public_url?` / `.assert_safe_public_url!` / `.same_origin?`).
+- JSON-Schema-subset validator (`Ai2Web.validate_schema`).
+- `llms.txt` and `agent.json` projections (`Ai2Web.to_llms_txt` / `.to_agent_json`), RFC-0015.
+- Zero runtime dependencies; requires Ruby 3.0+.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI2Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,85 @@
+<div align="center">
+  <a href="https://ai2web.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ai2web-foundation/.github/main/profile/ai2web-logo-white.svg">
+      <img alt="AI2Web" src="https://raw.githubusercontent.com/ai2web-foundation/.github/main/profile/ai2web-logo-black.svg" width="200">
+    </picture>
+  </a>
+</div>
+
+# AI2Web Ruby SDK (`ai2web`)
+
+[![CI](https://github.com/ai2web-foundation/ai2web-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/ai2web-foundation/ai2web-ruby/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/ai2web)](https://rubygems.org/gems/ai2web)
+
+The Ruby reference implementation of the [AI2Web protocol](https://github.com/ai2web-foundation/ai2web-spec) - for Rails, Sinatra, Rack, or plain Ruby. Mirrors `@ai2web/core`.
+
+```bash
+gem install ai2web
+# or add to your Gemfile:
+gem "ai2web"
+```
+
+```ruby
+require "ai2web"
+
+manifest = Ai2Web.ai2web(name: "Example Store", url: "https://example.com", type: "ecommerce")
+  .capability("content")
+  .capability("commerce", endpoint: "/ai2w/products", checkout: true)
+  .transports(mcp: { enabled: true, endpoint: "/ai2w/mcp" }, rest: { enabled: true })
+  .auth(methods: %w[none oauth2], oauth2: { pkce: true, scopes: ["checkout"] })
+  .consent(requires_user_approval_for: ["purchase"])
+  .contact(support: "help@example.com")
+  .build
+
+result = Ai2Web.validate(manifest)   # { score: 90+, tier: "Standard", ... }
+
+# Serve every AI2Web route from one call (framework-agnostic):
+res = Ai2Web.handle({ manifest: manifest }, request.method, request.path, body, origin)
+# => { status:, headers:, body: }  -- render body as JSON (or text for /llms.txt)
+```
+
+Inputs may use **symbol or string keys** - the builder normalises to the string-keyed JSON the
+spec defines, so `validate` also works directly on a `JSON.parse`d manifest.
+
+## Modules
+
+| Module | Entry points |
+| --- | --- |
+| `Ai2Web::Manifest` | `Ai2Web.ai2web(site)` - fluent capability-model builder |
+| `Ai2Web::Validator` | `Ai2Web.validate(manifest)` + AI Readiness scoring (spec §9/§11) |
+| `Ai2Web::Negotiator` | `Ai2Web.negotiate(manifest, agent)` capability negotiation (spec §5) |
+| `Ai2Web::Server` | `Ai2Web.handle(opts, method, path, body, origin)` framework-agnostic router |
+| `Ai2Web::Safety` | `Ai2Web.safe_public_url?(url)` / `.assert_safe_public_url!(url)` SSRF guard |
+| `Ai2Web::Schema` | `Ai2Web.validate_schema(value, schema)` action input validation |
+| `Ai2Web::Export` | `Ai2Web.to_llms_txt(m)` / `.to_agent_json(m)` projections (RFC-0015) |
+
+The builder also carries the v0.2 optional modules - `.governance(...)`, `.usage_policy(...)`,
+`.legal(...)`, `.agent_identity(...)`, `.knowledge(...)` - and actions accept `intent` and
+`bindings`. All are additive: a minimal manifest stays valid without them.
+
+### Serving from Rack / Sinatra
+
+```ruby
+res = Ai2Web.handle({ manifest: MANIFEST, actions: { "track_order" => ->(body) { track(body) } } },
+                    env["REQUEST_METHOD"], env["PATH_INFO"], parsed_body, request_origin)
+
+body = res[:body].is_a?(String) ? res[:body] : JSON.generate(res[:body])
+[res[:status], res[:headers], [body]]
+```
+
+`handle` routes `/ai2w`, `/.well-known/ai2w`, `/llms.txt`, `/.well-known/agent.json` (+ `/agent.json`),
+`/ai2w/negotiate`, `/ai2w/actions/:name` and capability modules `/ai2w/:name`, validating action
+input against each action's declared `input_schema` unless you pass `validate_input: false`.
+
+## Test
+
+```bash
+ruby test/run.rb     # dependency-free; includes the shared conformance contract
+```
+
+Requires **Ruby 3.0+**. Zero runtime dependencies.
+
+## Licence
+
+MIT.

data/lib/ai2web/export.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Ai2Web
+  # Export adapters (RFC-0015): project the one canonical AI2Web manifest into other wire formats
+  # and discovery surfaces. Port of @ai2web/core export.ts.
+  #
+  # Each export is a best-effort projection; where a target cannot represent a field, it is omitted
+  # rather than misstated. The canonical /ai2w manifest stays authoritative for execution.
+  module Export
+    module_function
+
+    def enabled_capabilities(m)
+      caps = m["capabilities"].is_a?(Hash) ? m["capabilities"] : {}
+      caps.select { |_k, v| Util.enabled?(v) }.keys
+    end
+
+    # Project the manifest to an `llms.txt` document: a plain-text summary and set of links a model
+    # can read for content and guidance. Reads only; no actions are exposed here.
+    def to_llms_txt(manifest)
+      m = Util.deep_stringify(manifest)
+      site = m["site"].is_a?(Hash) ? m["site"] : {}
+      base = Util.trim_url(site["url"].to_s)
+      lines = ["# #{site["name"]}"]
+      lines += ["", "> #{site["description"]}"] if Util.truthy?(site["description"])
+
+      caps = enabled_capabilities(m)
+      lines += ["", "## Capabilities", *caps.map { |c| "- #{c}" }] unless caps.empty?
+
+      knowledge = m["knowledge"].is_a?(Array) ? m["knowledge"] : []
+      unless knowledge.empty?
+        lines << ""
+        lines << "## Knowledge"
+        knowledge.each do |k|
+          ref = k["ref"].to_s
+          ref = base + (ref.start_with?("/") ? "" : "/") + ref unless ref.start_with?("http")
+          lines << "- [#{k["name"] || k["id"]}](#{ref})"
+        end
+      end
+
+      actions = m["actions"].is_a?(Array) ? m["actions"] : []
+      unless actions.empty?
+        lines << ""
+        lines << "## Actions"
+        actions.each { |a| lines << "- #{a["name"]}: #{a["description"]}" }
+      end
+
+      lines += ["", "## Discovery", "- Manifest: #{base}/ai2w"]
+      "#{lines.join("\n")}\n"
+    end
+
+    # Project the manifest to a generic `agent.json` style capability document. Best-effort,
+    # format-neutral projection of identity, capabilities, actions (with bindings), knowledge and
+    # policies. Consent/governance a target cannot express are carried as a `policies` object
+    # rather than dropped silently.
+    def to_agent_json(manifest)
+      m = Util.deep_stringify(manifest)
+      site = m["site"].is_a?(Hash) ? m["site"] : {}
+      actions = m["actions"].is_a?(Array) ? m["actions"] : []
+      consent = m["consent"].is_a?(Hash) ? m["consent"] : {}
+      {
+        "schema" => "agent-capabilities",
+        "name" => site["name"],
+        "description" => site["description"],
+        "url" => site["url"],
+        "identity" => m["identity"],
+        "capabilities" => enabled_capabilities(m),
+        "actions" => actions.map do |a|
+          bindings = a["bindings"].is_a?(Array) && !a["bindings"].empty? ? a["bindings"] : [{ "kind" => "rest", "ref" => a["endpoint"] }]
+          {
+            "name" => a["name"],
+            "intent" => a["intent"],
+            "description" => a["description"],
+            "risk" => a["risk"],
+            "requires_consent" => a["requires_user_approval"],
+            "requires_auth" => a["requires_auth"],
+            "input_schema" => a["input_schema"],
+            "bindings" => bindings
+          }
+        end,
+        "knowledge" => m["knowledge"],
+        "transports" => m["transports"],
+        "policies" => {
+          "consent" => consent["requires_user_approval_for"],
+          "governance" => m["governance"],
+          "usage" => m["usage_policy"],
+          "legal" => m["legal"]
+        }
+      }
+    end
+  end
+
+  module_function
+
+  def to_llms_txt(manifest) = Export.to_llms_txt(manifest)
+  def to_agent_json(manifest) = Export.to_agent_json(manifest)
+end

data/lib/ai2web/manifest.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ai2Web
+  # Fluent AI2Web (ai2w) manifest builder - "describe your website once".
+  #
+  # Every setter returns self, so calls chain. Inputs may use symbol or string keys; the builder
+  # stores string keys internally so the result round-trips cleanly as JSON.
+  #
+  #   manifest = Ai2Web.ai2web(name: "Store", url: "https://store.example", type: "ecommerce")
+  #     .capability("content")
+  #     .capability("commerce", endpoint: "/ai2w/products", checkout: true)
+  #     .contact(support: "help@store.example")
+  #     .build
+  class Manifest
+    def initialize(site)
+      @m = { "protocol" => "ai2w", "version" => "0.2", "site" => Util.deep_stringify(site), "capabilities" => {} }
+    end
+
+    def self.for_site(name:, url:, type:, **extra)
+      new({ "name" => name, "url" => url, "type" => type }.merge(Util.deep_stringify(extra)))
+    end
+
+    def capability(name, value = true)
+      value = { "enabled" => true }.merge(Util.deep_stringify(value)) if value.is_a?(Hash)
+      @m["capabilities"][name.to_s] = value
+      self
+    end
+
+    def transports(t)
+      (@m["transports"] ||= {}).merge!(Util.deep_stringify(t))
+      self
+    end
+
+    def auth(a)
+      @m["auth"] = Util.deep_stringify(a)
+      self
+    end
+
+    def consent(c)
+      @m["consent"] = Util.deep_stringify(c)
+      self
+    end
+
+    def action(a)
+      (@m["actions"] ||= []) << Util.deep_stringify(a)
+      capability("actions", "endpoint" => "/ai2w/actions")
+      self
+    end
+
+    def events(e)
+      e = Util.deep_stringify(e)
+      @m["events"] = e
+      capability("events", "endpoint" => e["endpoint"] || "/ai2w/events")
+      self
+    end
+
+    def agent_service(s)
+      @m["agent_service"] = Util.deep_stringify(s)
+      self
+    end
+
+    def identity(i)
+      @m["identity"] = Util.deep_stringify(i)
+      self
+    end
+
+    def contact(c)
+      @m["contact"] = Util.deep_stringify(c)
+      self
+    end
+
+    # --- v0.2 optional modules (all additive; a minimal manifest stays valid without them). ---
+    def governance(g)
+      @m["governance"] = Util.deep_stringify(g)
+      self
+    end
+
+    def usage_policy(u)
+      @m["usage_policy"] = Util.deep_stringify(u)
+      self
+    end
+
+    def legal(l)
+      @m["legal"] = Util.deep_stringify(l)
+      self
+    end
+
+    def agent_identity(a)
+      base = @m["identity"].is_a?(Hash) ? @m["identity"] : {}
+      @m["identity"] = base.merge("agent" => Util.deep_stringify(a))
+      self
+    end
+
+    def knowledge(k)
+      @m["knowledge"] = Util.deep_stringify(k)
+      self
+    end
+
+    # Attach a vendor extension. The key is namespaced with `x-` if not already.
+    def extension(key, value)
+      key = key.to_s
+      key = "x-#{key}" unless key.start_with?("x-")
+      @m[key] = Util.deep_stringify(value)
+      self
+    end
+
+    def build = @m
+    def to_h = @m
+
+    # Serialize to a JSON string. Pretty-printed by default; pass `indent: 0` for compact output.
+    # Accepts (and ignores) a JSON generator state so the object still works when nested inside
+    # another `JSON.generate` call.
+    def to_json(*_args, indent: 2)
+      indent.to_i.positive? ? JSON.pretty_generate(@m) : JSON.generate(@m)
+    end
+  end
+
+  module_function
+
+  def ai2web(site) = Manifest.new(site)
+  def manifest(site) = Manifest.new(site)
+end

data/lib/ai2web/negotiator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Ai2Web
+  # Capability negotiation (spec section 5). Port of @ai2web/core negotiate().
+  module Negotiator
+    module_function
+
+    def endpoint_of(name, value)
+      return value["endpoint"] if value.is_a?(Hash) && value["endpoint"].is_a?(String)
+
+      "/ai2w/#{name}"
+    end
+
+    def negotiate(manifest, agent = nil)
+      m = Util.deep_stringify(manifest)
+      agent = Util.deep_stringify(agent || {})
+      caps = m["capabilities"].is_a?(Hash) ? m["capabilities"] : {}
+      site_caps = caps.select { |_k, v| Util.enabled?(v) }.keys
+
+      want_caps = agent.key?("capabilities") ? (agent["capabilities"] || []) : site_caps
+      capabilities = site_caps.select { |c| want_caps.include?(c) }
+      unsupported = want_caps.reject { |c| site_caps.include?(c) }
+
+      # Only transports explicitly enabled are negotiable.
+      transports = m["transports"].is_a?(Hash) ? m["transports"] : {}
+      site_transports = transports.select { |_k, v| v.is_a?(Hash) && v["enabled"] == true }.keys
+      want_transports = agent.key?("transports") ? (agent["transports"] || []) : site_transports
+      transport = want_transports.find { |t| site_transports.include?(t) }
+
+      auth_block = m["auth"].is_a?(Hash) ? m["auth"] : {}
+      site_auth = auth_block["methods"] || ["none"]
+      want_auth = agent.key?("auth") ? (agent["auth"] || []) : site_auth
+      auth =
+        if site_auth.include?("oauth2") && want_auth.include?("oauth2")
+          "oauth2"
+        else
+          picked = want_auth.find { |a| site_auth.include?(a) }
+          picked.nil? && site_auth.include?("none") ? "none" : picked
+        end
+
+      endpoints = {}
+      capabilities.each { |c| endpoints[c] = endpoint_of(c, caps[c]) }
+      if !transport.nil? && transports[transport].is_a?(Hash) && transports[transport]["endpoint"]
+        endpoints[transport] = transports[transport]["endpoint"]
+      end
+
+      {
+        negotiated: { transport: transport, capabilities: capabilities, auth: auth, endpoints: endpoints },
+        unsupported: unsupported
+      }
+    end
+  end
+
+  module_function
+
+  def negotiate(manifest, agent = nil) = Negotiator.negotiate(manifest, agent)
+end

data/lib/ai2web/safety.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Ai2Web
+  # SSRF guard. Parity with @ai2web/core safety.
+  #
+  # Blocks the obvious pivots (loopback, private ranges, cloud metadata, link-local, non-http
+  # schemes) AND the alternative IP encodings that HTTP clients resolve to those same addresses
+  # (decimal / hex / octal / short-form IPv4, and IPv4-mapped IPv6). This is a literal host/IP
+  # check - not by itself DNS-rebind safe.
+  module Safety
+    IPV4_RE = /\A(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})\z/.freeze
+    IPV4_TAIL = /(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})\z/.freeze
+
+    module_function
+
+    # True if a standard dotted-quad is loopback/private/reserved (or has an invalid octet).
+    def ipv4_blocked?(host)
+      m = IPV4_RE.match(host)
+      return false unless m
+
+      parts = m.captures.map(&:to_i)
+      return true if parts.any? { |p| p > 255 } # not a real address; refuse
+
+      a, b = parts[0], parts[1]
+      return true if [0, 10, 127].include?(a)
+      return true if a == 169 && b == 254         # link-local + cloud metadata (169.254.169.254)
+      return true if a == 172 && b >= 16 && b <= 31
+      return true if a == 192 && b == 168
+      return true if a == 100 && b >= 64 && b <= 127 # CGNAT
+
+      false
+    end
+
+    def safe_public_url?(raw)
+      begin
+        u = URI.parse(raw.to_s)
+      rescue URI::InvalidURIError
+        return false
+      end
+      return false unless %w[https http].include?(u.scheme)
+
+      host = (u.host || "").downcase.sub(/\A\[/, "").sub(/\]\z/, "")
+      return false if host.empty? || host == "localhost" || host.end_with?(".localhost")
+
+      # IPv6 literal.
+      if host.include?(":")
+        # IPv4-mapped / compat (::ffff:a.b.c.d, ::a.b.c.d): range-check the embedded IPv4.
+        m = IPV4_TAIL.match(host)
+        return false if m && ipv4_blocked?(m[1])
+        return false if host == "::1" || host.start_with?("fc", "fd", "fe80")
+
+        return true
+      end
+
+      # Hex-encoded IP (0x7f000001, or a dotted octet like 0x7f): a client resolves these to an IP.
+      return false if host.match?(/(^|\.)0x/)
+
+      # Standard dotted-quad IPv4.
+      return !ipv4_blocked?(host) if IPV4_RE.match?(host)
+
+      # Any remaining all-numeric host is an alternative IPv4 encoding (decimal integer, octal, or
+      # short form like 127.1) that a client resolves to an IP. No real domain looks like this.
+      return false unless host.match?(/[a-z]/)
+
+      true
+    end
+
+    def assert_safe_public_url!(raw)
+      raise ArgumentError, "ai2w: refusing to fetch non-public or unsafe URL: #{raw}" unless safe_public_url?(raw)
+
+      raw
+    end
+
+    def same_origin?(a, b)
+      pa = URI.parse(a.to_s)
+      pb = URI.parse(b.to_s)
+      [pa.scheme, pa.host, pa.port] == [pb.scheme, pb.host, pb.port]
+    rescue URI::InvalidURIError
+      false
+    end
+  end
+
+  module_function
+
+  # Convenience top-level aliases so callers can use `Ai2Web.safe_public_url?` etc.
+  def safe_public_url?(raw) = Safety.safe_public_url?(raw)
+  def assert_safe_public_url!(raw) = Safety.assert_safe_public_url!(raw)
+  def same_origin?(a, b) = Safety.same_origin?(a, b)
+end

data/lib/ai2web/schema.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Ai2Web
+  # Result of {Ai2Web.validate_schema}. `valid` is a boolean; `errors` is an array of strings.
+  SchemaResult = Struct.new(:valid, :errors) do
+    def valid? = valid
+  end
+
+  # Minimal JSON-Schema-subset validator for action input schemas. Port of @ai2web/core
+  # validateSchema: pragmatic (object with typed/required properties, primitives, arrays, enum)
+  # rather than the whole of JSON Schema. Used by the server to validate incoming requests
+  # against an action's declared input_schema.
+  module Schema
+    module_function
+
+    def type_of(value)
+      case value
+      when nil then "null"
+      when true, false then "boolean"
+      when Integer, Float then "number"
+      when String then "string"
+      when Array then "array"
+      when Hash then "object"
+      else "unknown"
+      end
+    end
+
+    # Validate a value against a JSON-Schema-subset. An empty/absent schema accepts anything.
+    def validate_schema(value, schema, path = "input")
+      errors = []
+      schema = Util.deep_stringify(schema)
+      return SchemaResult.new(true, errors) unless schema.is_a?(Hash) && !schema.empty?
+
+      value = Util.deep_stringify(value)
+      declared = schema["type"]
+      has_declared = declared.is_a?(String) && !declared.empty?
+
+      if has_declared
+        ok = if declared == "integer"
+               value.is_a?(Integer) && value != true && value != false
+             else
+               type_of(value) == declared
+             end
+        unless ok
+          errors << "#{path}: expected #{declared}, got #{type_of(value)}"
+          return SchemaResult.new(false, errors) # wrong base type: stop
+        end
+      end
+
+      enum = schema["enum"]
+      errors << "#{path}: value is not one of the allowed options" if enum.is_a?(Array) && !enum.include?(value)
+
+      is_object = value.is_a?(Hash)
+      if (declared == "object" || (!has_declared && is_object)) && is_object
+        props = schema["properties"].is_a?(Hash) ? schema["properties"] : {}
+        (schema["required"] || []).each do |key|
+          errors << "#{path}.#{key}: required" unless value.key?(key)
+        end
+        props.each do |key, sub|
+          errors.concat(validate_schema(value[key], sub, "#{path}.#{key}").errors) if value.key?(key)
+        end
+      end
+
+      if (declared == "array" || (!has_declared && value.is_a?(Array))) && value.is_a?(Array) && schema["items"]
+        value.each_with_index do |item, i|
+          errors.concat(validate_schema(item, schema["items"], "#{path}[#{i}]").errors)
+        end
+      end
+
+      SchemaResult.new(errors.empty?, errors)
+    end
+  end
+
+  module_function
+
+  def validate_schema(value, schema, path = "input") = Schema.validate_schema(value, schema, path)
+end

data/lib/ai2web/server.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Ai2Web
+  # Framework-agnostic AI2Web request handler. Port of @ai2web/server.
+  #
+  # Returns a Hash { status:, headers:, body: }; adapt it to Rails / Sinatra / Rack / etc. `body`
+  # is a Ruby Hash (serialize to JSON in your adapter) or a String for text responses.
+  module Server
+    CORS = {
+      "access-control-allow-origin" => "*",
+      "access-control-allow-methods" => "GET, POST, OPTIONS",
+      "access-control-allow-headers" => "content-type, authorization"
+    }.freeze
+
+    ACTION_RE = %r{\A/ai2w/actions/([a-z0-9_-]+)\z}i.freeze
+    MODULE_RE = %r{\A/ai2w/([a-z0-9_-]+)\z}i.freeze
+
+    module_function
+
+    def json(status, body)
+      { status: status, headers: { "content-type" => "application/json; charset=utf-8" }.merge(CORS), body: body }
+    end
+
+    def error(status, code, message, retryable: false)
+      json(status, { "error" => { "code" => code, "message" => message, "retryable" => retryable } })
+    end
+
+    def text(status, content_type, body)
+      { status: status, headers: { "content-type" => content_type }.merge(CORS), body: body }
+    end
+
+    def opt(opts, key)
+      opts[key] || opts[key.to_s]
+    end
+
+    def lookup(table, name)
+      table[name] || table[name.to_sym]
+    end
+
+    def handle(opts, method, path, body = nil, origin = nil)
+      manifest = Util.deep_stringify(opt(opts, :manifest))
+      modules = opt(opts, :modules) || {}
+      actions = opt(opts, :actions) || {}
+      validate_input = opts.key?(:validate_input) || opts.key?("validate_input") ? opt(opts, :validate_input) : true
+      declared_actions = {}
+      (manifest["actions"] || []).each { |a| declared_actions[a["name"]] = a if a.is_a?(Hash) }
+
+      trimmed = path.to_s.gsub(%r{\A/+|/+\z}, "")
+      path = trimmed.empty? ? "/" : "/#{trimmed}"
+      method = method.to_s.upcase
+
+      return { status: 204, headers: CORS.dup, body: nil } if method == "OPTIONS"
+
+      if path == "/.well-known/ai2w"
+        return json(200, { "ai2w" => "#{Util.trim_url(origin)}/ai2w" }) if origin && !origin.to_s.empty?
+
+        return json(200, manifest)
+      end
+
+      if ["/ai2w", "/ai", "/.ai"].include?(path)
+        return error(405, "invalid_request", "Use GET for the manifest.") if method != "GET"
+
+        return json(200, manifest)
+      end
+
+      # Multi-surface projections (RFC-0015): the one canonical manifest, emitted in other discovery
+      # formats so agents that speak llms.txt or agent.json need not parse ai2w first.
+      if path == "/llms.txt"
+        return error(405, "invalid_request", "Use GET for llms.txt.") if method != "GET"
+
+        return text(200, "text/plain; charset=utf-8", Ai2Web.to_llms_txt(manifest))
+      end
+      if ["/.well-known/agent.json", "/agent.json"].include?(path)
+        return error(405, "invalid_request", "Use GET for agent.json.") if method != "GET"
+
+        return json(200, Ai2Web.to_agent_json(manifest))
+      end
+
+      if path == "/ai2w/negotiate"
+        b = body.is_a?(Hash) ? Util.deep_stringify(body) : {}
+        agent = b["agent"].is_a?(Hash) ? b["agent"] : {}
+        supports = agent["supports"] || b["supports"] || b
+        supports = {} unless supports.is_a?(Hash)
+        return json(200, Ai2Web.negotiate(manifest, supports))
+      end
+
+      if (m = ACTION_RE.match(path))
+        name = m[1].tr("-", "_")
+        fn = lookup(actions, name)
+        return error(404, "unsupported_capability", "Unknown action '#{name}'.") unless fn
+
+        declared = declared_actions[name]
+        if Util.truthy?(validate_input) && declared && declared["input_schema"]
+          result = Ai2Web.validate_schema(body.nil? ? {} : body, declared["input_schema"])
+          unless result.valid
+            return error(400, "invalid_request",
+                         "Request does not match the declared input schema: #{result.errors.join("; ")}.")
+          end
+        end
+        return json(200, fn.call(body))
+      end
+
+      if (m = MODULE_RE.match(path))
+        name = m[1]
+        fn = lookup(modules, name)
+        return error(404, "unsupported_capability", "Module '#{name}' not exposed.") unless fn
+
+        return json(200, fn.call(body))
+      end
+
+      error(404, "invalid_request", "No AI2Web route for #{path}.")
+    end
+  end
+
+  module_function
+
+  def handle(opts, method, path, body = nil, origin = nil) = Server.handle(opts, method, path, body, origin)
+end

data/lib/ai2web/util.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Ai2Web
+  # Small shared helpers. AI2Web manifests are JSON documents, so the SDK works internally with
+  # string-keyed hashes; +deep_stringify+ lets callers pass symbol keys and still get parity.
+  module Util
+    module_function
+
+    # Recursively convert every Hash key to a String (values untouched). Idempotent.
+    def deep_stringify(obj)
+      case obj
+      when Hash then obj.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify(v) }
+      when Array then obj.map { |e| deep_stringify(e) }
+      else obj
+      end
+    end
+
+    # Mirror of @ai2web/core `_has`: a capability/transport is on when it is `true` or an
+    # object with `enabled: true`.
+    def enabled?(value)
+      value == true || (value.is_a?(Hash) && value["enabled"] == true)
+    end
+
+    # Python-style truthiness, used only where the reference validator relies on `bool(...)`
+    # (empty hash/array/string are falsy). Keeps exact scoring/tier parity with the other SDKs.
+    def truthy?(value)
+      case value
+      when nil, false then false
+      when Hash, Array, String then !value.empty?
+      when Numeric then value != 0
+      else true
+      end
+    end
+
+    # Strip trailing slashes from a URL/base.
+    def trim_url(url)
+      url.to_s.sub(%r{/+\z}, "")
+    end
+  end
+end

data/lib/ai2web/validator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Ai2Web
+  # AI2Web validation + AI Readiness scoring.
+  #
+  # Port of @ai2web/core validateManifest (spec sections 9 & 11). MUST stay in exact parity with
+  # the TypeScript reference and ai2web-spec/conformance/cases.json.
+  #
+  # {Ai2Web.validate} returns a Hash:
+  #   { valid: Boolean, errors: [String], checks: [{ ok:, points:, label:, hint: }],
+  #     score: Integer (0..100), tier: "Invalid"|"Basic"|"Standard"|"Enterprise" }
+  module Validator
+    VERSION_RE = /\A\d+\.\d+(\.\d+)?\z/.freeze
+
+    module_function
+
+    def validate(manifest)
+      m = Util.deep_stringify(manifest)
+      errors = []
+      checks = []
+      caps = m["capabilities"].is_a?(Hash) ? m["capabilities"] : {}
+      cap = ->(name) { caps[name] }
+
+      errors << "protocol must be 'ai2w'" if m["protocol"] != "ai2w"
+      errors << "version missing/invalid" unless VERSION_RE.match?(m["version"].to_s)
+      site = m["site"].is_a?(Hash) ? m["site"] : {}
+      %w[name url type].each { |k| errors << "site.#{k} missing" unless Util.truthy?(site[k]) }
+      errors << "capabilities empty" unless caps.is_a?(Hash) && !caps.empty?
+
+      actions_exist =
+        Util.enabled?(cap.call("actions")) ||
+        (m["actions"].is_a?(Array) && !m["actions"].empty?) ||
+        Util.enabled?(cap.call("commerce")) ||
+        Util.enabled?(cap.call("booking"))
+
+      score = 0
+      add = lambda do |ok, points, label, hint|
+        checks << { ok: ok, points: points, label: label, hint: ok ? nil : hint }
+        score += points if ok
+      end
+
+      add.call(errors.empty?, 30, "Valid discovery manifest", "fix errors")
+      add.call(Util.enabled?(cap.call("content")), 6, "Content", "expose content module")
+      add.call(Util.enabled?(cap.call("commerce")) || Util.enabled?(cap.call("booking")) || Util.enabled?(cap.call("services")), 6,
+               "Products / services / booking", "expose a commerce/services/booking module")
+      add.call(Util.enabled?(cap.call("search")), 4, "Search", "add a search capability")
+      add.call(actions_exist, 5, "Actions", "declare actions")
+      add.call(Util.enabled?(cap.call("events")), 6, "Events / subscriptions", "publish subscribable events")
+      agent_service = m["agent_service"].is_a?(Hash) ? m["agent_service"] : {}
+      add.call(Util.truthy?(agent_service["enabled"]), 4, "Agent service (A2A)", "expose /ai2w/agent")
+
+      commerce = cap.call("commerce")
+      add.call(!Util.enabled?(commerce) || (commerce.is_a?(Hash) && commerce["checkout"] == true),
+               4, "Checkout", "commerce present but checkout missing")
+
+      transports = m["transports"].is_a?(Hash) ? m["transports"] : {}
+      mcp = transports["mcp"].is_a?(Hash) ? transports["mcp"] : {}
+      rest = transports["rest"].is_a?(Hash) ? transports["rest"] : {}
+      add.call(mcp["enabled"] == true, 8, "MCP transport", "expose an MCP endpoint")
+      add.call(rest["enabled"] == true || Util.truthy?(transports["feeds"]), 4, "REST / feeds", "expose REST or feeds")
+
+      auth = m["auth"].is_a?(Hash) ? m["auth"] : {}
+      oauth2 = auth["oauth2"].is_a?(Hash) ? auth["oauth2"] : {}
+      oauth_ok = (auth["methods"] || []).include?("oauth2") && oauth2["pkce"] == true
+      consent = m["consent"].is_a?(Hash) ? m["consent"] : {}
+      consent_declared = ((consent["requires_user_approval_for"]) || []).length.positive?
+      add.call(!actions_exist || oauth_ok, 8, "OAuth2 + PKCE", "protected actions need oauth2+pkce")
+      add.call(!actions_exist || consent_declared, 7, "Consent declared", "declare consent for sensitive actions")
+
+      add.call(Util.truthy?(m["identity"]), 4, "Identity", "add identity (legal_name, policies)")
+      add.call(Util.truthy?(m["contact"]), 4, "Contact", "add support/security contact")
+
+      score = [100, score].min
+
+      basic = errors.empty?
+      standard = basic && Util.truthy?(m["transports"]) && (!actions_exist || consent_declared) && Util.truthy?(m["contact"])
+      enterprise = standard && Util.truthy?(m["identity"]) && Util.truthy?(m["auth"]) && Util.truthy?(m["rate_limits"])
+      tier = if enterprise then "Enterprise"
+             elsif standard then "Standard"
+             elsif basic then "Basic"
+             else "Invalid"
+             end
+
+      { valid: errors.empty?, errors: errors, checks: checks, score: score, tier: tier }
+    end
+  end
+
+  module_function
+
+  def validate(manifest) = Validator.validate(manifest)
+end

data/lib/ai2web/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ai2Web
+  VERSION = "0.1.0"
+end

data/lib/ai2web.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# AI2Web (ai2w) Ruby SDK.
+#
+# Describe your website once. AI2Web makes it understandable to every AI.
+#
+# Top-level API (all also reachable via their modules):
+#   Ai2Web.ai2web(site)                 -> Ai2Web::Manifest   (fluent builder)
+#   Ai2Web.validate(manifest)           -> Hash               (AI Readiness score + tier)
+#   Ai2Web.negotiate(manifest, agent)   -> Hash               (capability negotiation)
+#   Ai2Web.handle(opts, method, path, body, origin) -> Hash   (framework-agnostic router)
+#   Ai2Web.validate_schema(value, schema) -> Ai2Web::SchemaResult
+#   Ai2Web.safe_public_url?(url) / .assert_safe_public_url!(url) / .same_origin?(a, b)
+#   Ai2Web.to_llms_txt(manifest) / .to_agent_json(manifest)   (RFC-0015 projections)
+require_relative "ai2web/version"
+require_relative "ai2web/util"
+require_relative "ai2web/safety"
+require_relative "ai2web/schema"
+require_relative "ai2web/validator"
+require_relative "ai2web/negotiator"
+require_relative "ai2web/export"
+require_relative "ai2web/manifest"
+require_relative "ai2web/server"

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: ai2web
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- AI2Web Foundation
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-19 00:00:00.000000000 Z
+dependencies: []
+description: The Ruby implementation of the AI2Web protocol - describe your website
+  once and make it understandable and actionable to any AI agent. Fluent manifest
+  builder, AI Readiness validator/scorer, capability negotiation, a framework-agnostic
+  request handler for Rails/Sinatra/Rack, an SSRF guard, and llms.txt / agent.json
+  projections (RFC-0015). Mirrors @ai2web/core. Zero runtime dependencies.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ai2web.rb
+- lib/ai2web/export.rb
+- lib/ai2web/manifest.rb
+- lib/ai2web/negotiator.rb
+- lib/ai2web/safety.rb
+- lib/ai2web/schema.rb
+- lib/ai2web/server.rb
+- lib/ai2web/util.rb
+- lib/ai2web/validator.rb
+- lib/ai2web/version.rb
+homepage: https://ai2web.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://ai2web.dev
+  source_code_uri: https://github.com/ai2web-foundation/ai2web-ruby
+  changelog_uri: https://github.com/ai2web-foundation/ai2web-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ai2web-foundation/ai2web-ruby/issues
+  documentation_uri: https://ai2web.dev/docs
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: AI2Web (ai2w) Ruby SDK - capability model, manifest builder, validator, negotiation,
+  server handler.
+test_files: []