webuntis-api 0.1.0

data/lib/webuntis/client.rb

@@ -0,0 +1,540 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+require "securerandom"
+require "uri"
+
+module WebUntis
+  # A WebUntis session: logs in, keeps cookies and the JWT fresh, and exposes
+  # the {#rpc} and {#rest} namespaces.
+  class Client
+    DEFAULT_CLIENT_NAME = "webuntis-api"
+    TOKEN_SKEW = 30
+    TOKEN_FALLBACK_TTL = 600
+    ANONYMOUS_USER = "#anonymous#"
+    ANONYMOUS_OTP = "100170"
+    APP_DATA_PATH = "api/rest/view/v1/app/data"
+    LOGIN_MODES = %i[rpc form secret anonymous].freeze
+
+    # The current {Session}, the cookie jar, the logger, the `client` name sent to `authenticate`
+    # and the login flow in use (`:rpc`, `:form`, `:secret` or `:anonymous`).
+    attr_reader :session, :cookies, :logger, :client_name, :login_mode
+
+    def initialize(school:, username: nil, password: nil, secret: nil, anonymous: false,
+                   server: nil, tenant_id: nil, login: nil, school_year_id: nil,
+                   client_name: DEFAULT_CLIENT_NAME, http: nil, logger: nil,
+                   open_timeout: 10, read_timeout: 30, now: nil)
+      @school_query = school
+      @username = username
+      @password = password
+      @secret = secret
+      @anonymous = anonymous
+      @server = server
+      @configured_tenant_id = tenant_id
+      @login_mode = validate_login_mode(login || derive_login_mode)
+      @school_year_id = school_year_id
+      @client_name = client_name
+      @http = http || HTTP::NetHttp.new(open_timeout: open_timeout, read_timeout: read_timeout)
+      @logger = logger
+      @now = now || -> { Time.now }
+      @session = Session.new
+      @cookies = CookieJar.new
+      @logged_in = false
+    end
+
+    # The resolved tenant; discovered via {School.find} when no `server:` was given.
+    def school
+      @school ||= @server ? explicit_school : School.find(@school_query, http: @http)
+    end
+
+    # The `https://<host>/WebUntis` prefix every request is built from.
+    def base_url
+      school.base_url
+    end
+
+    # The JSON-RPC namespace (`jsonrpc.do`).
+    def rpc
+      @rpc ||= RPC.new(self)
+    end
+
+    # The modern REST namespace (`api/rest/view/...` plus the legacy `api/...` endpoints).
+    def rest
+      @rest ||= REST.new(self)
+    end
+
+    # True once a login succeeded and the session has not been invalidated since.
+    def logged_in?
+      @logged_in
+    end
+
+    # Logs in with the configured flow, replacing any existing session.
+    def login!
+      reset_state!
+      case @login_mode
+      when :rpc then login_rpc!
+      when :form then login_form!
+      when :secret then login_otp!(TOTP.code(@secret, at: now), @username)
+      when :anonymous then login_otp!(ANONYMOUS_OTP, ANONYMOUS_USER)
+      end
+      @logged_in = true
+      @session.tenant_id ||= tenant_id_without_app_data
+      self
+    end
+
+    # Ends the session via the `logout` JSON-RPC method and drops all local state.
+    def logout!
+      return self unless @logged_in
+
+      begin
+        rpc_post("logout", {})
+      rescue Error
+        nil
+      end
+      reset_state!
+      self
+    end
+
+    # Logs in unless a session is already open.
+    def ensure_login!
+      login! unless @logged_in
+      self
+    end
+
+    # The tenant id, from the constructor, the `Tenant-Id` cookie, discovery, or `app/data`.
+    def tenant_id
+      @tenant_id ||= tenant_id_without_app_data || app_data_metadata["tenant_id"]
+    end
+
+    # The school year id sent as `X-Webuntis-Api-School-Year-Id`, if any.
+    def school_year_id
+      Thread.current[school_year_key] || @school_year_id
+    end
+
+    # Runs the block with every REST call scoped to one school year (thread-locally).
+    def with_school_year(id)
+      previous = Thread.current[school_year_key]
+      Thread.current[school_year_key] = id
+      yield self
+    ensure
+      Thread.current[school_year_key] = previous
+    end
+
+    # The current JWT, minted lazily via `api/token/new` and refreshed before it expires.
+    def token
+      ensure_login!
+      return @session.token unless @session.token_stale?(now)
+
+      mint_token!(strict: false)
+    end
+
+    # Teachers from `getTeachers`, indexed by id and memoised for this session.
+    def teachers_by_id
+      @teachers_by_id ||= rpc.teachers.to_h { |teacher| [teacher["id"], teacher] }
+    end
+
+    # Class teachers per class: `{"class" => {id, name, long_name}, "teachers" => [{id, name, long_name, fore_name}]}`.
+    # `source: :rest` reads `timetable/filter?resourceType=CLASS` (`classTeacher1`/`classTeacher2`) for `date`;
+    # `source: :rpc` joins `getKlassen`'s `teacher1`/`teacher2` against `getTeachers` and also yields forenames.
+    def class_teachers(source: :rest, date: nil, school_year_id: nil, include_inactive: false)
+      case source
+      when :rest then rest_class_teachers(date || Date.today)
+      when :rpc then rpc_class_teachers(school_year_id, include_inactive)
+      else raise ArgumentError, "source must be :rest or :rpc, got #{source.inspect}"
+      end
+    end
+
+    # Performs one JSON-RPC call, re-authenticating once when the session expired.
+    def rpc_call(method, params = {})
+      ensure_login!
+      payload = rpc_post(method, params)
+      if not_authenticated?(payload)
+        login!
+        payload = rpc_post(method, params)
+      end
+      raise rpc_error(method, payload["error"]) if payload["error"]
+
+      payload["result"]
+    end
+
+    # Performs one REST call, re-authenticating once when the session is rejected: a 401/403, a redirect
+    # to `index.do`, or a failed call for which no JWT could be minted.
+    def rest_request(method, path, query: {}, body: nil)
+      ensure_login!
+      response = perform_rest(method, path, query, body)
+      if auth_rejected?(response) || sent_without_token?(response)
+        login!
+        response = perform_rest(method, path, query, body)
+      end
+      handle_rest(method, path, response)
+    end
+
+    def inspect
+      "#<WebUntis::Client school=#{@school_query.inspect} login=#{@login_mode.inspect} logged_in=#{@logged_in}>"
+    end
+
+    private
+
+    def now
+      @now.call
+    end
+
+    def school_year_key
+      @school_year_key ||= :"webuntis_school_year_#{object_id}"
+    end
+
+    def derive_login_mode
+      return :secret if @secret
+      return :anonymous if @anonymous
+
+      :rpc
+    end
+
+    def validate_login_mode(mode)
+      unless LOGIN_MODES.include?(mode)
+        raise ArgumentError, "login must be one of #{LOGIN_MODES.inspect}, got #{mode.inspect}"
+      end
+
+      missing = case mode
+                when :rpc, :form then { username: @username, password: @password }
+                when :secret then { username: @username, secret: @secret }
+                else {}
+                end.filter_map { |name, value| name if value.nil? || value.to_s.empty? }
+      raise ArgumentError, "login mode #{mode.inspect} requires #{missing.join(" and ")}" unless missing.empty?
+
+      mode
+    end
+
+    def explicit_school
+      School.new(
+        server: @server,
+        login_name: @school_query,
+        display_name: @school_query,
+        tenant_id: @configured_tenant_id
+      )
+    end
+
+    def reset_state!
+      @session = Session.new
+      @cookies = CookieJar.new
+      # The server expects the school name base64-encoded *and* prefixed with an underscore.
+      @cookies["schoolname"] = "_#{Util.base64(school.name)}"
+      @teachers_by_id = nil
+      @app_data = nil
+      @tenant_id = nil
+      @logged_in = false
+    end
+
+    def tenant_id_without_app_data
+      @configured_tenant_id || @cookies["Tenant-Id"] || school.tenant_id
+    end
+
+    def app_data_metadata
+      return @app_data if @app_data
+
+      # Set before the request: fetch_app_data builds its headers via tenant_id, which lands here again.
+      @app_data = {}
+      payload = fetch_app_data
+      @app_data = {
+        "tenant_id" => payload.dig("tenant", "id"),
+        "school_year_id" => payload.dig("currentSchoolYear", "id")
+      }
+      @session.tenant_id ||= @app_data["tenant_id"]
+      @session.school_year_id ||= @app_data["school_year_id"]
+      @app_data
+    end
+
+    def fetch_app_data
+      response = http_call(:get, "#{base_url}/#{APP_DATA_PATH}", headers: rest_headers)
+      @cookies.absorb(response)
+      payload = response.success? ? response.json : nil
+      payload.is_a?(Hash) ? payload : {}
+    end
+
+    def login_rpc!
+      payload = rpc_post("authenticate",
+                         { "user" => @username, "password" => @password, "client" => @client_name })
+      raise auth_error_from_rpc(payload["error"]) if payload["error"]
+
+      result = payload["result"]
+      unless result.is_a?(Hash) && result["sessionId"]
+        code = result.is_a?(Hash) ? result["code"] : nil
+        raise AuthError.new("login failed#{" with code #{code}" if code}", stage: :login)
+      end
+      store_rpc_session(result)
+    end
+
+    def store_rpc_session(result)
+      @session.session_id = result["sessionId"]
+      @session.person_id = result["personId"]
+      @session.person_type = result["personType"]
+      @session.klasse_id = result["klasseId"]
+      @cookies["JSESSIONID"] = result["sessionId"]
+    end
+
+    def login_form!
+      seed = http_call(:get, "#{base_url}/index.do", headers: { "Accept" => "text/html, */*" })
+      @cookies.absorb(seed)
+      response = http_call(
+        :post, "#{base_url}/j_spring_security_check",
+        headers: { "Content-Type" => "application/x-www-form-urlencoded", "Accept" => "text/html, */*" },
+        body: URI.encode_www_form(school: school.name, j_username: @username, j_password: @password)
+      )
+      @cookies.absorb(response)
+      # A form login answers 302 whether or not it worked; only a mintable JWT proves it did.
+      mint_token!
+      @session.session_id = @cookies["JSESSIONID"]
+    end
+
+    def login_otp!(otp, user)
+      url = "#{base_url}/jsonrpc_intern.do?" \
+            "#{URI.encode_www_form(m: "getUserData2017", school: school.name, v: "i2.2")}"
+      response = http_call(
+        :post, url,
+        headers: { "Content-Type" => "application/json", "Accept" => "application/json" },
+        body: JSON.generate(
+          "id" => SecureRandom.hex(8),
+          "method" => "getUserData2017",
+          "params" => [{ "auth" => { "clientTime" => (now.to_f * 1000).round, "user" => user, "otp" => otp } }],
+          "jsonrpc" => "2.0"
+        )
+      )
+      finish_otp_login(response, user)
+    end
+
+    def finish_otp_login(response, user)
+      unless response.success?
+        raise AuthError.new("OTP login failed (HTTP #{response.status})", stage: :login, status: response.status)
+      end
+
+      payload = response.json
+      raise auth_error_from_rpc(payload["error"]) if payload.is_a?(Hash) && payload["error"]
+
+      @cookies.absorb(response)
+      session_id = @cookies["JSESSIONID"]
+      raise AuthError.new("login returned no JSESSIONID cookie", stage: :login) if session_id.nil?
+
+      @session.session_id = session_id
+      load_person_from_app_config unless user == ANONYMOUS_USER
+    end
+
+    def load_person_from_app_config
+      response = http_call(:get, "#{base_url}/api/app/config", headers: { "Accept" => "application/json",
+                                                                          "Cookie" => cookie_header })
+      @cookies.absorb(response)
+      payload = response.json
+      user = payload.is_a?(Hash) ? payload.dig("data", "loginServiceConfig", "user") : nil
+      raise AuthError.new("app config did not contain a login service user", stage: :login) unless user.is_a?(Hash)
+
+      @session.person_id = user["personId"]
+      person = Array(user["persons"]).find { |entry| entry["id"] == user["personId"] }
+      @session.person_type = person && person["type"]
+    end
+
+    def mint_token!(strict: true)
+      response = http_call(:get, "#{base_url}/api/token/new",
+                           headers: { "Accept" => "text/plain, */*", "Cookie" => cookie_header }.compact)
+      @cookies.absorb(response)
+      value = response.body.to_s.strip
+      return store_token(value) if response.success? && !value.empty? && !html?(value)
+      if strict
+        raise AuthError.new("could not mint a JWT (HTTP #{response.status})", stage: :token,
+                                                                              status: response.status)
+      end
+
+      @session.forget_token
+      nil
+    end
+
+    def store_token(value)
+      expiry = jwt_expiry(value)
+      @session.token = value
+      if expiry
+        @session.token_expires_at = Time.at(expiry)
+        @session.stale_at = Time.at(expiry - TOKEN_SKEW)
+      else
+        @session.token_expires_at = now + TOKEN_FALLBACK_TTL
+        @session.stale_at = @session.token_expires_at
+      end
+      value
+    end
+
+    def jwt_expiry(token)
+      segment = token.split(".")[1]
+      return nil if segment.nil?
+
+      claims = JSON.parse(Util.base64url_decode(segment))
+      claims.is_a?(Hash) && claims["exp"].is_a?(Numeric) ? claims["exp"] : nil
+    rescue JSON::ParserError, ArgumentError
+      nil
+    end
+
+    def html?(value)
+      value.match?(/\A\s*<(!doctype|html)/i)
+    end
+
+    def cookie_header
+      @cookies.header
+    end
+
+    # Headers every modern REST call carries.
+    def rest_headers(json_body: false)
+      jwt = token
+      {
+        "Accept" => "application/json, text/plain, */*",
+        "Authorization" => jwt && "Bearer #{jwt}",
+        "Tenant-Id" => tenant_id&.to_s,
+        "X-Webuntis-Api-School-Year-Id" => school_year_id&.to_s,
+        "Cookie" => cookie_header,
+        "Content-Type" => json_body ? "application/json" : nil
+      }.compact
+    end
+
+    def perform_rest(method, path, query, body)
+      payload = body.nil? || body.is_a?(String) ? body : JSON.generate(body)
+      http_call(method, rest_url(path, query),
+                headers: rest_headers(json_body: !payload.nil?), body: payload)
+    end
+
+    def rest_url(path, query)
+      url = "#{base_url}/#{path.to_s.sub(%r{\A/+}, "")}"
+      encoded = REST.encode_query(query)
+      encoded.empty? ? url : "#{url}?#{encoded}"
+    end
+
+    def handle_rest(method, path, response)
+      @cookies.absorb(response)
+      unless response.success?
+        raise HttpError.new("HTTP #{response.status} for #{method.to_s.upcase} #{path}",
+                            status: response.status, body: response.body, method: method, path: path)
+      end
+
+      payload = response.json
+      check_api_error(payload, path)
+      payload
+    end
+
+    def check_api_error(payload, path)
+      return unless payload.is_a?(Hash)
+
+      key = payload.dig("data", "error", "data", "messageKey")
+      raise ApiError.new(key.to_s, message_key: key, body: payload, path: path) if key
+
+      message = payload["errorMessage"]
+      raise ApiError.new(message.to_s, body: payload, path: path) if message
+    end
+
+    def auth_rejected?(response)
+      return true if [401, 403].include?(response.status)
+
+      response.redirect? && response.location.to_s.include?("index.do")
+    end
+
+    # `api/token/new` redirects instead of minting once the session is dead, and the view API answers
+    # a request without a bearer token with 404 rather than 401.
+    def sent_without_token?(response)
+      !response.success? && @session.token.nil?
+    end
+
+    def rpc_url
+      "#{base_url}/jsonrpc.do?#{URI.encode_www_form(school: school.name)}"
+    end
+
+    def rpc_post(method, params)
+      body = JSON.generate(
+        "id" => SecureRandom.hex(8),
+        "method" => method,
+        "params" => Util.compact_params(params),
+        "jsonrpc" => "2.0"
+      )
+      response = http_call(:post, rpc_url, headers: rpc_headers, body: body)
+      @cookies.absorb(response)
+      unless response.success?
+        raise HttpError.new("HTTP #{response.status} for JSON-RPC #{method}", status: response.status,
+                                                                              body: response.body, method: :post,
+                                                                              path: "jsonrpc.do")
+      end
+
+      parse_rpc_body(response, method)
+    end
+
+    def parse_rpc_body(response, method)
+      payload = response.json
+      raise Error, "JSON-RPC #{method} returned a non-JSON body" unless payload.is_a?(Hash)
+
+      payload
+    end
+
+    def rpc_headers
+      { "Content-Type" => "application/json", "Accept" => "application/json", "Cookie" => cookie_header }.compact
+    end
+
+    def not_authenticated?(payload)
+      error = payload["error"]
+      return false unless error.is_a?(Hash)
+
+      error["code"] == -8520 || error["message"].to_s.downcase.include?("not authenticated")
+    end
+
+    def rpc_error(method, error)
+      error = {} unless error.is_a?(Hash)
+      RpcError.new("JSON-RPC #{method} failed: #{error["message"]}",
+                   code: error["code"], data: error["data"], method: method)
+    end
+
+    def auth_error_from_rpc(error)
+      error = {} unless error.is_a?(Hash)
+      AuthError.new("login failed: #{error["message"]}#{" (code #{error["code"]})" if error["code"]}",
+                    stage: :login)
+    end
+
+    def rest_class_teachers(date)
+      filter = rest.timetable_filter(resource_type: :class, start: date, end: date)
+      Array(filter["classes"]).map do |entry|
+        teachers = [entry["classTeacher1"], entry["classTeacher2"]].compact
+        {
+          "class" => resource_row(entry["class"]),
+          "teachers" => teachers.map { |teacher| resource_row(teacher).merge("fore_name" => nil) }
+        }
+      end
+    end
+
+    def resource_row(resource)
+      { "id" => resource["id"], "name" => resource["shortName"], "long_name" => resource["longName"] }
+    end
+
+    def rpc_class_teachers(school_year_id, include_inactive)
+      klassen = Array(rpc.classes(school_year_id: school_year_id))
+      unless klassen.any? { |klasse| klasse.key?("teacher1") || klasse.key?("teacher2") }
+        raise Error, "this account cannot see class teachers via getKlassen: no teacher1/teacher2 fields were returned"
+      end
+
+      klassen.filter_map do |klasse|
+        next if !include_inactive && klasse["active"] == false
+
+        {
+          "class" => { "id" => klasse["id"], "name" => klasse["name"], "long_name" => klasse["longName"] },
+          "teachers" => rpc_class_teachers_for(klasse)
+        }
+      end
+    end
+
+    def rpc_class_teachers_for(klasse)
+      [klasse["teacher1"], klasse["teacher2"]].filter_map do |id|
+        next if id.to_i.zero?
+
+        teacher = teachers_by_id[id]
+        next unless teacher
+
+        { "id" => teacher["id"], "name" => teacher["name"], "long_name" => teacher["longName"],
+          "fore_name" => teacher["foreName"] }
+      end
+    end
+
+    def http_call(method, url, headers: {}, body: nil)
+      response = @http.call(method, url, headers: headers, body: body)
+      @logger&.debug { "WebUntis #{method.to_s.upcase} #{URI.parse(url).path} -> #{response.status}" }
+      response
+    end
+  end
+end

data/lib/webuntis/cookie_jar.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module WebUntis
+  # A name-keyed cookie store; WebUntis only ever needs the newest value per name.
+  class CookieJar
+    def initialize
+      @cookies = {}
+    end
+
+    # Records the `Set-Cookie` values of one response.
+    def absorb(response)
+      response.set_cookies.each do |raw|
+        pair = raw.to_s.split(";", 2).first.to_s
+        name, value = pair.split("=", 2)
+        next if value.nil? || name.strip.empty?
+
+        self[name.strip] = value.strip
+      end
+      self
+    end
+
+    # The value of one cookie, without the double quotes a server may wrap it in (RFC 6265).
+    def [](name)
+      value = @cookies[name.to_s]
+      value&.match?(/\A".*"\z/) ? value[1..-2] : value
+    end
+
+    # Sets one cookie value; a nil value removes it.
+    def []=(name, value)
+      if value.nil?
+        @cookies.delete(name.to_s)
+      else
+        @cookies[name.to_s] = value.to_s
+      end
+    end
+
+    # The `Cookie` request header value, or nil when the jar is empty.
+    def header
+      return nil if @cookies.empty?
+
+      @cookies.map { |name, value| "#{name}=#{value}" }.join("; ")
+    end
+
+    # Drops every cookie.
+    def clear
+      @cookies.clear
+      self
+    end
+
+    # True when the jar holds no cookies.
+    def empty?
+      @cookies.empty?
+    end
+  end
+end

data/lib/webuntis/element_type.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module WebUntis
+  # The numeric element types WebUntis uses for classes, people, subjects and rooms.
+  module ElementType
+    CLASS = 1
+    TEACHER = 2
+    SUBJECT = 3
+    ROOM = 4
+    STUDENT = 5
+
+    NAMES = {
+      "class" => CLASS,
+      "klasse" => CLASS,
+      "teacher" => TEACHER,
+      "subject" => SUBJECT,
+      "room" => ROOM,
+      "student" => STUDENT
+    }.freeze
+
+    LABELS = {
+      CLASS => "CLASS",
+      TEACHER => "TEACHER",
+      SUBJECT => "SUBJECT",
+      ROOM => "ROOM",
+      STUDENT => "STUDENT"
+    }.freeze
+
+    # Coerces an Integer, Symbol or String element type to its numeric form.
+    def self.resolve(value)
+      return value if value.is_a?(Integer)
+      return nil if value.nil?
+
+      key = value.to_s.downcase
+      NAMES[key] || (raise Error, "unknown element type #{value.inspect}")
+    end
+
+    # Coerces an element type to the uppercase name the modern REST API expects.
+    def self.label(value)
+      return nil if value.nil?
+      return LABELS.fetch(value) { raise Error, "unknown element type #{value.inspect}" } if value.is_a?(Integer)
+
+      name = value.to_s.upcase
+      return name if LABELS.value?(name)
+
+      LABELS.fetch(resolve(value))
+    end
+  end
+end

data/lib/webuntis/errors.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module WebUntis
+  class Error < StandardError; end
+
+  # Raised when a school cannot be resolved to exactly one WebUntis tenant.
+  class DiscoveryError < Error
+    attr_reader :query, :matches
+
+    def initialize(message, query: nil, matches: [])
+      super(message)
+      @query = query
+      @matches = matches
+    end
+  end
+
+  # Raised when logging in, minting a JWT, or re-authenticating fails.
+  class AuthError < Error
+    attr_reader :stage, :status
+
+    def initialize(message, stage: nil, status: nil)
+      super(message)
+      @stage = stage
+      @status = status
+    end
+  end
+
+  # Raised when a JSON-RPC response carries an `error` member.
+  class RpcError < Error
+    attr_reader :code, :data, :method
+
+    def initialize(message, code: nil, data: nil, method: nil)
+      super(message)
+      @code = code
+      @data = data
+      @method = method
+    end
+  end
+
+  # Raised for any non-success HTTP status the client did not handle itself.
+  class HttpError < Error
+    attr_reader :status, :body, :method, :path
+
+    def initialize(message, status: nil, body: nil, method: nil, path: nil)
+      super(message)
+      @status = status
+      @body = body
+      @method = method
+      @path = path
+    end
+  end
+
+  # Raised when a 2xx REST body carries an application-level error envelope.
+  class ApiError < Error
+    attr_reader :message_key, :body, :path
+
+    def initialize(message, message_key: nil, body: nil, path: nil)
+      super(message)
+      @message_key = message_key
+      @body = body
+      @path = path
+    end
+  end
+end