lingara-embed 0.0.0 → 0.1.0.pre.alpha.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 922bfc696c0c0562bb8f3bc28249c072bfd44dec0de17199bb7fd957579c50ac
-  data.tar.gz: ef210c75eca3478291a4a1574e99d082fbe4b902e1bf3f48caa674b9216e78b8
+  metadata.gz: ad30f45110b5d96a048a1a9fa2fe6a576b471967e7518e6ad1f0398150242b80
+  data.tar.gz: 8501e28ac824097691621de281676538d34acf362b4b884631d020676405a736
 SHA512:
-  metadata.gz: 9666c98c7ad4771b36147a21f7b9a06ca3062b5d43b7ac45b004b9968a7db15a95c82ab3c68b38a695491fd39b4cc155c170685f4d64deea54eeeb2c510d8b21
-  data.tar.gz: 0bc95779729f24db56b3f5c590b0e3043b7c619136dde8c677a387219c60e9a027df336f07c13f2c37c05890639eb34bc6375a8b1c3874c8637b15e61bf2a96f
+  metadata.gz: 58c9d9dde0562e500e780361e5c3a3928a6625becbc842ace8dee85ceee6f1ef6cdeffb31ea4876e8be57b872e400b937080d3c1ca90f81cbc5d1cb9e8997306
+  data.tar.gz: d2f562b9cd9e91f16eb7fe577975d6c5d2a4ae2d6594d4f328a8e8a047ff7e934b66896e4c673b9060bd45caa02c60e91743ef51df5e3491ffc3ab4001bdda7d

data/README.md

@@ -1,4 +1,192 @@
-# lingara-embed
+# lingara-embed (Ruby)
 
-The official Ruby SDK for embedding Lingara in games and other platforms. Under development.
-This name is reserved; the first release will follow Lingara's webhooks and apps work.
+> `Lingara::Embed::MemoryDirectory` is lost on restart and not shared between
+> processes: production code passes a directory over its own database
+> ([below](#the-player-directory)).
+
+The Ruby server kit for embedding [Lingara](https://getlingara.com) in a game
+or a website. Your server already holds the client secret, so it vouches for
+its players. That takes four small jobs, and this gem does each one in a few
+lines over the [`lingara`](https://rubygems.org/gems/lingara) library:
+
+1. **mint** a player's embed token;
+2. **hand it over** to the player's game or browser;
+3. **route** Lingara's signed webhooks to the player each one concerns;
+4. **delete** a player.
+
+It also renders the `<lingara-embed>` widget snippet for a web page.
+
+## Install
+
+```sh
+gem install lingara-embed
+```
+
+or, in a Gemfile, `gem "lingara-embed"`. Ruby 3.3 or newer. The gem's one
+runtime dependency is `lingara`. `require "lingara/embed"` loads both.
+
+```ruby
+require "lingara/embed"
+
+client = Lingara::Client.new(client_id: ENV.fetch("LINGARA_CLIENT_ID"),
+                             client_secret: ENV.fetch("LINGARA_CLIENT_SECRET"))
+players = PlayerTable.new(DB)  # your directory, below
+server = Lingara::Embed::Server.new(client, directory: players)
+router = Lingara::Embed::PlayerRouter.new(ENV.fetch("LINGARA_WEBHOOK_SECRET"), directory: players)
+```
+
+Only a **metered** client may mint. Every other client gets
+`403 embed_needs_metered`.
+
+## 1. Mint, and hand the token over
+
+The player side asks your server for a token. This is your route, behind
+your own sign-in, so it only ever mints for the user it has authenticated.
+Here it is in Sinatra:
+
+```ruby
+post "/lingara/token" do
+  halt 401 unless current_user
+  minted = server.mint_token(current_user.id.to_s, origin: "https://game.example")
+  content_type :json
+  cache_control :no_store
+  Lingara::Embed.token_handoff(minted)  # {"token":"lgr_et_…","expires_at":"…Z"}
+end
+```
+
+- `mint_token(player_ref, scopes: nil, origin: nil)` makes exactly one
+  `POST /v1/embed/tokens` and returns the library's `Lingara::MintedToken`.
+  It then calls `directory.remember(player_ref, subject)`. Nothing is
+  cached. Each token lives 900 s, and the player kit asks again before it
+  expires.
+- `origin:` is your page's origin. It must be one of your client's
+  registered embed origins. A game's server mints without one.
+- `token_handoff` returns the one body every player kit and the widget read,
+  `{"token","expires_at"}`, with `expires_at` in UTC. It is the only place
+  the kit exposes the token. Everywhere else the token renders
+  `[REDACTED]`.
+- **Rate-limit this route per session.** Lingara limits each player, but
+  your route is the door anyone can knock on.
+- A failure raises the library's `Lingara::Error` (`ApiError`,
+  `OAuthError`, `MaintenanceError`, `TransportError`) unchanged, and nothing
+  is remembered. The library does the retries and the token refresh, so the
+  kit adds none of its own.
+
+## 2. Route a webhook to its player
+
+```ruby
+post "/lingara/webhook" do
+  status router.handle(request.body.read, request.env) { |routed|
+    next if seen?(routed.event.id)  # delivery is at least once: dedup on event.id
+    PracticeJob.perform_later(routed.player_ref, routed.event.to_h) if routed.player_ref
+  }
+end
+```
+
+`handle(body, headers)` verifies the signature on the **raw** body first,
+then looks the subject up in your directory, then calls your block with a
+`RoutedEvent` (`event`, `player_ref`). It returns the status for your
+route, always with an empty body:
+
+| Outcome | Status |
+|---|---|
+| your block returned | `204` |
+| a bad or missing signature, or a stale timestamp | `401`: neither the directory nor your block is called |
+| a valid signature over a body that is not an event | `400` |
+| your block or your directory raised | `500`: the error goes to `on_error:` |
+
+`headers` is a Hash or a Rack `env`, as it is. `player_ref` is `nil` for a
+subject your directory does not know, such as your own or a deleted
+player's. An event type newer than the library arrives as
+`Lingara::Events::UnknownEvent`. Answer it `204` like any other.
+
+- **Deduplicate on `event.id`.** Lingara redelivers every non-`2xx`, so the
+  same event can arrive twice.
+- Lingara waits 10 s for an answer. Enqueue slow work and return.
+- `on_error:` defaults to `Kernel#warn`. Pass your logger:
+  `PlayerRouter.new(secrets, directory: players, on_error: ->(e) { Rails.logger.error(e) })`.
+- During a secret rotation, pass both secrets:
+  `PlayerRouter.new([new_secret, old_secret], directory: players)`.
+- `route(body, headers)` returns the `RoutedEvent`, or raises
+  `Lingara::Events::VerificationError`, for a route that maps statuses
+  itself.
+
+## 3. Delete a player
+
+```ruby
+def destroy_account(user)
+  server.delete_player(user.id.to_s)  # revokes their tokens, then forgets their rows
+  user.destroy!
+end
+```
+
+Call this from your account-deletion path. Deleting an unknown player
+succeeds, so a retry is safe. If the call fails, the directory keeps its
+rows.
+
+## 4. The widget snippet
+
+```erb
+<%= Lingara::Embed.widget_snippet(plan_id: plan.id, token_endpoint: "/lingara/token",
+                                  locale: "fr", nonce: content_security_policy_nonce).html_safe %>
+```
+
+This renders the `<lingara-embed>` element and its two module scripts. The
+token is never in the markup. The element `POST`s to `token_endpoint` at
+run time, with `credentials: "same-origin"`, and reads `token_handoff`'s
+body.
+
+- **The CSP nonce.** If your page's `script-src` allows no inline script,
+  pass the request's nonce. Without it, a strict page blocks the third line
+  without any error.
+- **Same-origin credentials.** The token route is authenticated by your
+  page's cookies. An absolute `https://` endpoint on another origin gets no
+  cookies, so it must authenticate the user some other way.
+- Keywords: `plan_id:` and `token_endpoint:` (required), `surface:`,
+  `theme:`, `locale:`, `lingara_origin:`, `title:`, `id:` (one per widget on
+  a page), `nonce:`, `element_src:`. An invalid value raises
+  `Lingara::Embed::SnippetError`, whose `field` names the option
+  (`"planId"`, `"tokenEndpoint"`, …).
+
+## The player directory
+
+`subject` is a pairwise identifier that Lingara computes. Your server cannot
+derive a `player_ref` from it, so the mint records the pair, and the router
+reads it back. A directory is any object that answers these three methods:
+
+```ruby
+class PlayerTable
+  def initialize(db) = @rows = db[:lingara_players]
+
+  def remember(player_ref, subject)  # an upsert keyed on subject
+    @rows.insert_conflict(target: :subject, update: {player_ref: player_ref})
+      .insert(player_ref: player_ref, subject: subject)
+  end
+
+  def player_ref_for(subject) = @rows.where(subject: subject).get(:player_ref)
+
+  def forget(player_ref) = @rows.where(player_ref: player_ref).delete  # every row, idempotent
+end
+```
+
+Store it beside your players, in two columns:
+
+| `player_ref` | `subject` |
+|---|---|
+| `TEXT NOT NULL`, plain index | `TEXT NOT NULL`, **unique** index |
+
+A player may own more than one subject. A guest who links an account gets
+a second one, so the table is unique on `subject` only. The directory is
+optional for `Server` and required for `PlayerRouter`.
+
+## Conformance
+
+`make test-ruby` runs the unit tests (the shared snippet, handoff and
+webhook vectors), RuboCop and `rbs validate`. `make conformance-es-ruby`
+runs every case of the ES contract (`conformance/es/CONTRACT.md`) through
+this kit. The receiver runs on rack and webrick from
+`conformance-es/Gemfile`, which never reaches the gem.
+
+## License
+
+MIT

data/lib/lingara/embed/memory_directory.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Lingara
+  module Embed
+    # A process-local player directory, for tests and single-process demos.
+    # It is lost on restart and not shared between instances: production
+    # code passes any object answering the same three methods over its own
+    # database, a table of (player_ref, subject) unique on subject.
+    #
+    # `subject` is a pairwise HMAC computed by Lingara, so the mint's answer
+    # is the only moment a player_ref and its subject are in one place
+    # (ADR 1.10.26af D5). One player may own several subjects (a guest's,
+    # then a linked account's), so the store is keyed on subject only.
+    class MemoryDirectory
+      def initialize
+        @rows = {}
+        @lock = Mutex.new
+      end
+
+      # Upserts the row keyed on +subject+. A guest's subject is stable
+      # across mints, so remembering it again changes nothing.
+      def remember(player_ref, subject)
+        @lock.synchronize { @rows[subject] = player_ref }
+        nil
+      end
+
+      # The player a subject belongs to, or nil.
+      def player_ref_for(subject)
+        @lock.synchronize { @rows[subject] }
+      end
+
+      # Removes every row for the player. Idempotent.
+      def forget(player_ref)
+        @lock.synchronize { @rows.delete_if { |_, owner| owner == player_ref } }
+        nil
+      end
+
+      # Every row, subject => player_ref, as a copy.
+      def snapshot
+        @lock.synchronize { @rows.dup }
+      end
+
+      def inspect
+        "#<Lingara::Embed::MemoryDirectory rows=#{@lock.synchronize { @rows.size }}>"
+      end
+
+      def to_s
+        inspect
+      end
+    end
+  end
+end

data/lib/lingara/embed/player_router.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Lingara
+  module Embed
+    # Routes a Lingara webhook to its player (ADR 1.10.26af D8): the
+    # library's verifier on the raw body first, then the directory, so a
+    # forged event never reaches your store.
+    #
+    #   router = Lingara::Embed::PlayerRouter.new(ENV.fetch("LINGARA_WEBHOOK_SECRET"), directory: players)
+    #   status = router.handle(request.body.read, request.env) { |routed| enqueue(routed) }
+    #
+    # +secrets+ is one lgr_whsec_ secret or, during a rotation, a list; a
+    # malformed one raises the library's ArgumentError here, at startup.
+    # +directory+ is any object answering remember, player_ref_for and
+    # forget. +on_error+ receives what a 500 swallowed; its default writes
+    # one line through Kernel#warn.
+    class PlayerRouter
+      DEFAULT_ON_ERROR = ->(error) { Kernel.warn("lingara webhook: #{error.class}: #{error.message}") }
+
+      def initialize(secrets, directory:, on_error: DEFAULT_ON_ERROR)
+        @webhook = Lingara::Events::Webhook.new(secrets)
+        @directory = directory
+        @on_error = on_error
+      end
+
+      # Verifies the raw +body+ (a String, exactly as received) against
+      # +headers+ (a Hash or a Rack env), then looks the subject up. Raises
+      # Lingara::Events::VerificationError before the directory is asked.
+      def route(body, headers)
+        event = @webhook.verify(body, headers)
+        RoutedEvent.new(event: event, player_ref: @directory.player_ref_for(event.subject))
+      end
+
+      # #route, then the block, answered as the status your route sends with
+      # an empty body: 204 handled, 401 a bad signature, 400 a malformed
+      # payload under a valid signature, 500 the directory or the block
+      # raised (the error goes to on_error only). Every non-2xx is
+      # redelivered, so a slow block should enqueue and return.
+      def handle(body, headers, &on_event)
+        raise ArgumentError, "handle needs a block, the event handler" unless on_event
+        dispatch(body, headers, on_event)
+      end
+
+      def inspect
+        "#<Lingara::Embed::PlayerRouter webhook=#{@webhook.inspect}>"
+      end
+
+      def to_s
+        inspect
+      end
+
+      private
+
+      def dispatch(body, headers, on_event)
+        routed = verified_route(body, headers)
+        return routed if routed.is_a?(Integer)
+        on_event.call(routed)
+        204
+      rescue => e
+        @on_error.call(e)
+        500
+      end
+
+      # The routed event, or the status a verification failure answers.
+      def verified_route(body, headers)
+        route(body, headers)
+      rescue Lingara::Events::VerificationError => e
+        (e.reason == :malformed_payload) ? 400 : 401
+      end
+    end
+  end
+end

data/lib/lingara/embed/routed_event.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Lingara
+  module Embed
+    # A verified event and the player it concerns (ADR 1.10.26af D8).
+    # +event+ is the library's Lingara::Events::Event (UnknownEvent for a
+    # type newer than the library); +player_ref+ is nil for a subject the
+    # directory does not know: the integrator's own, or a deleted player.
+    RoutedEvent = Data.define(:event, :player_ref)
+  end
+end

data/lib/lingara/embed/server.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Lingara
+  module Embed
+    # Mint and delete (ADR 1.10.26af D4, D9): one library call each, the
+    # directory written only after a success. There is no cache: every
+    # #mint_token is one POST, so a token #delete_player revoked on another
+    # instance is never handed out again.
+    #
+    #   client = Lingara::Client.new(client_id: ENV.fetch("LINGARA_CLIENT_ID"),
+    #                                client_secret: ENV.fetch("LINGARA_CLIENT_SECRET"))
+    #   server = Lingara::Embed::Server.new(client, directory: players)
+    #
+    # +client+ is a Lingara::Client holding your client credentials: its
+    # token cache, retries and deprecation hook are the library's. A failed
+    # call raises the library's Lingara::Error unchanged.
+    class Server
+      # +directory+, optional, is any object answering remember,
+      # player_ref_for and forget (MemoryDirectory's shape).
+      def initialize(client, directory: nil)
+        @client = client
+        @directory = directory
+      end
+
+      # Mints a token for one player: one POST /v1/embed/tokens, then
+      # directory.remember(player_ref, subject). +scopes+ and +origin+ are
+      # sent only when given; +origin+ is your page's origin, one of your
+      # client's embed origins (a game's server mints without one). Returns
+      # the library's Lingara::MintedToken. On a failure nothing is
+      # remembered.
+      def mint_token(player_ref, scopes: nil, origin: nil)
+        body = {player_ref: player_ref}
+        body[:scopes] = scopes unless scopes.nil?
+        body[:origin] = origin unless origin.nil?
+        minted = @client.create_embed_token(**body).value
+        @directory&.remember(player_ref, minted.subject)
+        minted
+      end
+
+      # Deletes a player and revokes their tokens, then forgets them. An
+      # unknown player is a success; on a failure the row is kept.
+      def delete_player(player_ref)
+        @client.delete_embed_player(player_ref)
+        @directory&.forget(player_ref)
+        nil
+      end
+
+      def inspect
+        "#<Lingara::Embed::Server client=#{@client.inspect} directory=#{!@directory.nil?}>"
+      end
+
+      def to_s
+        inspect
+      end
+    end
+  end
+end

data/lib/lingara/embed/token_handoff.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lingara
+  module Embed
+    # The handoff body (ADR 1.10.26af D6, ES6): exactly
+    # {"token":"lgr_et_…","expires_at":"…"}, the shape every player kit and
+    # the widget read. This is the one place the kit exposes the token on
+    # purpose.
+    module TokenHandoff
+      module_function
+
+      # The JSON a token route returns for +minted+, a Lingara::MintedToken.
+      # The library holds expires_at as a Time, so it is written back as
+      # RFC 3339 in UTC; expires_in and subject are not forwarded.
+      def from(minted)
+        body(minted.token.expose_secret, rfc3339(minted.expires_at))
+      end
+
+      # The pure body over two strings, held to token-handoff.json: compact,
+      # these two keys in this order, / and non-ASCII unescaped. A String
+      # expires_at is copied byte for byte. Internal: integrators call
+      # Lingara::Embed.token_handoff.
+      def body(token, expires_at)
+        JSON.generate({"token" => token, "expires_at" => expires_at})
+      end
+
+      # +time+ in UTC with a Z, its fractional seconds only when non-zero:
+      # as many digits as it holds, at most nine, trailing zeros trimmed.
+      def rfc3339(time)
+        return time if time.is_a?(String)
+        utc = time.getutc
+        fraction = (utc.nsec.zero? ? "" : ".#{format("%09d", utc.nsec).sub(/0+\z/, "")}")
+        "#{utc.strftime("%Y-%m-%dT%H:%M:%S")}#{fraction}Z"
+      end
+    end
+  end
+end

data/lib/lingara/embed/version.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
+# Generated by make codegen-ruby from VERSION. DO NOT EDIT.
+
 module Lingara
   module Embed
-    VERSION = "0.0.0"
+    # This kit release, SemVer: the default elementSrc reads it.
+    VERSION = "0.1.0-alpha.7"
+
+    # The same version in the RubyGems spelling the gemspec uses.
+    GEM_VERSION = "0.1.0.pre.alpha.7"
   end
 end

data/lib/lingara/embed/widget_snippet.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Lingara
+  module Embed
+    # The first widget_snippet option refused. +field+ is the option's
+    # contract name, camelCase (planId, tokenEndpoint, …), never its value.
+    class SnippetError < ArgumentError
+      attr_reader :field
+
+      def initialize(field)
+        @field = field
+        super("the widget snippet's #{field} is not valid")
+      end
+    end
+
+    # The widget snippet (ADR 1.10.26af D7, ES4): the <lingara-embed>
+    # element and its two module scripts, rendered identically by all eight
+    # server kits. The token never appears in it, only the endpoint the
+    # element asks at run time.
+    module WidgetSnippet
+      DEFAULT_ELEMENT_SRC = "https://cdn.jsdelivr.net/npm/@lingara/embed@#{VERSION}/dist/lingara-embed.min.js"
+
+      # Unicode category Cc.
+      CONTROL = /[\u0000-\u001f\u007f-\u009f]/
+      # The contract's whitespace beyond Cc.
+      SPACE = /[\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]/
+      ORIGIN = %r{\A(https://[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*(:[0-9]{1,5})?|http://(localhost|127\.0\.0\.1)(:[0-9]{1,5})?)/?\z}
+
+      # Each option's rule, in the contract's order: the first refused is
+      # the one raised.
+      RULES = [
+        [:plan_id, "planId", ->(v) { v.match?(/\A[0-9A-Fa-f]{8}(-[0-9A-Fa-f]{4}){3}-[0-9A-Fa-f]{12}\z/) }],
+        [:surface, "surface", ->(v) { v.match?(/\A[a-z][a-z0-9-]{0,31}\z/) }],
+        [:theme, "theme", ->(v) { %w[light dark auto].include?(v) }],
+        [:locale, "locale", ->(v) { v.match?(/\A[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8}){0,3}\z/) }],
+        [:lingara_origin, "lingaraOrigin", ->(v) { v.match?(ORIGIN) }],
+        [:title, "title", ->(v) { v.length.between?(1, 80) && !v.match?(CONTROL) }],
+        [:id, "id", ->(v) { v.match?(/\A[A-Za-z][A-Za-z0-9_-]{0,63}\z/) }],
+        [:token_endpoint, "tokenEndpoint", ->(v) { v.match?(%r{\A(/(?!/)|https://)}) && WidgetSnippet.url_text?(v) }],
+        [:nonce, "nonce", ->(v) { v.match?(%r{\A[A-Za-z0-9+/=_-]{8,128}\z}) }],
+        [:element_src, "elementSrc", ->(v) { v.start_with?("https://") && WidgetSnippet.url_text?(v) }]
+      ].freeze
+
+      ATTRIBUTE_ESCAPES = {"&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;", "'" => "&#39;"}.freeze
+      SCRIPT_ESCAPES = {
+        '"' => '\\"', "\\" => "\\\\", "<" => "\\u003c", ">" => "\\u003e", "&" => "\\u0026",
+        "\u2028" => "\\u2028", "\u2029" => "\\u2029"
+      }.freeze
+
+      module_function
+
+      # The three lines to paste into a page, with no trailing newline.
+      # +plan_id+ (the plan your server made for this player, a UUID) and
+      # +token_endpoint+ (your token route: a path, or an https:// URL) are
+      # required; +nonce+ is your page's CSP nonce, written on both scripts.
+      # Raises SnippetError naming the first option refused.
+      def render(plan_id: nil, token_endpoint: nil, surface: nil, theme: nil, locale: nil,
+        lingara_origin: nil, title: nil, id: nil, nonce: nil, element_src: nil)
+        values = {plan_id: plan_id.to_s, token_endpoint: token_endpoint.to_s, surface: surface || "practice",
+                  theme: theme, locale: locale, lingara_origin: lingara_origin, title: title, id: id || "lingara-embed",
+                  nonce: nonce, element_src: element_src || DEFAULT_ELEMENT_SRC}
+        check(values)
+        lines(values)
+      end
+
+      # The first refused option, by its contract name, or nothing.
+      def check(values)
+        RULES.each do |key, field, ok|
+          value = values[key]
+          next if value.nil?
+          raise SnippetError, field unless value.is_a?(String) && value.valid_encoding? && ok.call(value)
+        end
+      end
+
+      def lines(v)
+        element = +"<lingara-embed"
+        [["id", v[:id]], ["surface", v[:surface]], ["plan-id", v[:plan_id]], ["theme", v[:theme]],
+          ["locale", v[:locale]], ["lingara-origin", v[:lingara_origin]], ["title", v[:title]]].each do |name, value|
+          element << %( #{name}="#{attribute(value)}") unless value.nil?
+        end
+        nonce = v[:nonce] ? %( nonce="#{attribute(v[:nonce])}") : ""
+        fetch = "document.getElementById(#{script_string(v[:id])}).tokenProvider = async () => " \
+          "(await fetch(#{script_string(v[:token_endpoint])}, { method: \"POST\", credentials: \"same-origin\" })).json();"
+        "#{element}></lingara-embed>\n" \
+          "<script type=\"module\"#{nonce} src=\"#{attribute(v[:element_src])}\"></script>\n" \
+          "<script type=\"module\"#{nonce}>#{fetch}</script>"
+      end
+
+      # At most 2048 UTF-8 bytes, with no control character or whitespace.
+      def url_text?(value)
+        value.bytesize <= 2048 && !value.match?(CONTROL) && !value.match?(SPACE)
+      end
+
+      # An attribute value: the five characters, and nothing else.
+      def attribute(value)
+        value.gsub(/[&<>"']/, ATTRIBUTE_ESCAPES)
+      end
+
+      # A JSON string literal that can never close the script or open a
+      # comment.
+      def script_string(value)
+        %("#{value.gsub(/["\\<>&\u2028\u2029]/, SCRIPT_ESCAPES)}")
+      end
+    end
+  end
+end

data/lib/lingara/embed.rb

@@ -1,9 +1,38 @@
 # frozen_string_literal: true
 
+# The Lingara embed server kit (ADR 1.10.26af): the four jobs a game's or a
+# site's server does for its players, over the `lingara` library. Mint a
+# player's token (Server#mint_token), hand it over (token_handoff), route a
+# signed webhook to its player (PlayerRouter), and delete a player
+# (Server#delete_player); widget_snippet renders the <lingara-embed> markup.
+#
+# This file is lib/lingara/embed.rb and the gem ships no lib/lingara.rb, so
+# `require "lingara"` stays the library's.
+
+require "lingara"
+
 require_relative "embed/version"
+require_relative "embed/routed_event"
+require_relative "embed/memory_directory"
+require_relative "embed/server"
+require_relative "embed/player_router"
+require_relative "embed/widget_snippet"
+require_relative "embed/token_handoff"
 
 module Lingara
-  # Placeholder: the Lingara embed SDK for Ruby is under development.
+  # The server kit's namespace. Lingara::MintedToken, Lingara::Error and
+  # Lingara::Events are the library's.
   module Embed
+    module_function
+
+    # The three lines to paste into a page; see WidgetSnippet.render.
+    def widget_snippet(**options)
+      WidgetSnippet.render(**options)
+    end
+
+    # The JSON body a token route returns; see TokenHandoff.
+    def token_handoff(minted)
+      TokenHandoff.from(minted)
+    end
   end
 end

data/sig/lingara_embed.rbs

@@ -1,5 +1,70 @@
+# The public surface of the gem `lingara-embed` (ADR 1.10.26af). The
+# library's own types (Lingara::Client, Lingara::MintedToken,
+# Lingara::Events::Event and its VerificationError) are the `lingara` gem's
+# signatures, so they are untyped here.
 module Lingara
   module Embed
     VERSION: String
+    GEM_VERSION: String
+
+    # Any object answering these three is a player directory (D5).
+    interface _Directory
+      def remember: (String player_ref, String subject) -> untyped
+      def player_ref_for: (String subject) -> String?
+      def forget: (String player_ref) -> untyped
+    end
+
+    def self.widget_snippet: (?plan_id: String?, ?token_endpoint: String?, ?surface: String?, ?theme: String?,
+                              ?locale: String?, ?lingara_origin: String?, ?title: String?, ?id: String?,
+                              ?nonce: String?, ?element_src: String?) -> String
+    def self.token_handoff: (untyped minted) -> String
+
+    class Server
+      def initialize: (untyped client, ?directory: _Directory?) -> void
+      def mint_token: (String player_ref, ?scopes: Array[String]?, ?origin: String?) -> untyped
+      def delete_player: (String player_ref) -> nil
+    end
+
+    class PlayerRouter
+      DEFAULT_ON_ERROR: ^(StandardError) -> untyped
+
+      def initialize: (String | Array[String] secrets, directory: _Directory,
+                       ?on_error: ^(StandardError) -> untyped) -> void
+      def route: (String body, Hash[untyped, untyped] headers) -> RoutedEvent
+      def handle: (String body, Hash[untyped, untyped] headers) { (RoutedEvent) -> untyped } -> Integer
+    end
+
+    class RoutedEvent < ::Data
+      attr_reader event: untyped
+      attr_reader player_ref: String?
+      def initialize: (event: untyped, player_ref: String?) -> void
+    end
+
+    class MemoryDirectory
+      def initialize: () -> void
+      def remember: (String player_ref, String subject) -> nil
+      def player_ref_for: (String subject) -> String?
+      def forget: (String player_ref) -> nil
+      def snapshot: () -> Hash[String, String]
+    end
+
+    class SnippetError < ArgumentError
+      attr_reader field: String
+      def initialize: (String field) -> void
+    end
+
+    module WidgetSnippet
+      DEFAULT_ELEMENT_SRC: String
+      def self.render: (?plan_id: String?, ?token_endpoint: String?, ?surface: String?, ?theme: String?,
+                        ?locale: String?, ?lingara_origin: String?, ?title: String?, ?id: String?,
+                        ?nonce: String?, ?element_src: String?) -> String
+    end
+
+    # Internal: integrators call Lingara::Embed.token_handoff.
+    module TokenHandoff
+      def self.from: (untyped minted) -> String
+      def self.body: (String token, String expires_at) -> String
+      def self.rfc3339: (Time | String time) -> String
+    end
   end
 end

metadata

@@ -1,35 +1,60 @@
 --- !ruby/object:Gem::Specification
 name: lingara-embed
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0.pre.alpha.7
 platform: ruby
 authors:
-- Christopher Goddard
+- Spinning Cat Studios
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
-dependencies: []
-description: Embed Lingara in games and other platforms, with Ruby.
+date: 2026-10-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lingara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0.pre.alpha.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0.pre.alpha.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+description: Mint a player's embed token, hand it over, route a signed Lingara webhook
+  to its player, delete a player, and render the <lingara-embed> widget snippet, over
+  the lingara library.
 email:
-- chrisjgoddard@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- Gemfile
 - LICENSE
 - README.md
-- Rakefile
 - lib/lingara/embed.rb
+- lib/lingara/embed/memory_directory.rb
+- lib/lingara/embed/player_router.rb
+- lib/lingara/embed/routed_event.rb
+- lib/lingara/embed/server.rb
+- lib/lingara/embed/token_handoff.rb
 - lib/lingara/embed/version.rb
+- lib/lingara/embed/widget_snippet.rb
 - sig/lingara_embed.rbs
-homepage: https://getlingara.com
+homepage: https://github.com/Spinning-Cat-Studios/lingara_embeddable_sdk
 licenses:
 - MIT
 metadata:
-  allowed_push_host: https://rubygems.org
-  homepage_uri: https://getlingara.com
+  source_code_uri: https://github.com/Spinning-Cat-Studios/lingara_embeddable_sdk/tree/main/ruby
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -48,5 +73,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: The official Ruby SDK for embedding Lingara (under development).
+summary: The official Ruby server kit for embedding Lingara in games and websites
 test_files: []

data/Gemfile

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in lingara-embed.gemspec
-gemspec
-
-gem "rake", "~> 13.0"

data/Rakefile

@@ -1,4 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-task default: %i[]