touchque 5.0.0

data/lib/touchque/code_reply.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Touchque
+  # A code the person types back on the phone (tq.login.request(..., reply: {...})): a sign-in
+  # code another service sent them (a text message, WhatsApp, e-mail). Each request gets a
+  # one-time P-256 key pair; its public key goes with the request, the phone encrypts what was
+  # typed to it, and only you can open it: Touchque stores and hands back nothing but the
+  # ciphertext (tq.login.status(request_id)["reply"]["ct"]).
+  #
+  # ECDH P-256, HKDF-SHA256 (salt: the request id, info "touchque-code-reply-v1"), AES-256-GCM
+  # (additional data "touchque-code-reply:<request id>"), as
+  # "v1.<the phone's one-time key, x9.63>.<nonce|ciphertext|tag>", base64url.
+  module CodeReply
+    INFO = "touchque-code-reply-v1"
+    CT_RE = /\Av1\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)\z/
+    CODE_RE = /\A[A-Za-z0-9 -]{4,20}\z/
+
+    module_function
+
+    # A one-time key pair for one request: send "publicKey" (the uncompressed P-256 point,
+    # base64url) as reply[:key], keep "privateKey" (PKCS#8 DER, base64url) server-side.
+    def new_key
+      key = OpenSSL::PKey::EC.generate("prime256v1")
+      { "publicKey" => Util.b64url(key.public_key.to_bn(:uncompressed).to_s(2)), "privateKey" => Util.b64url(key.private_to_der) }
+    end
+
+    # The code the person typed, or nil when ct does not open with this key for this request.
+    def open(private_key, request_id, ct)
+      m = CT_RE.match(ct.to_s)
+      return nil unless m
+
+      epk = Util.b64url_decode(m[1])
+      box = Util.b64url_decode(m[2])
+      return nil unless epk.bytesize == 65 && epk.getbyte(0) == 4 && box.bytesize >= 12 + 16 + 1
+
+      priv = OpenSSL::PKey.read(Util.b64url_decode(private_key))
+      peer = OpenSSL::PKey::EC::Point.new(priv.group, OpenSSL::BN.new(epk, 2))
+      shared = priv.dh_compute_key(peer)
+      key = OpenSSL::KDF.hkdf(shared, salt: request_id.to_s, info: INFO, length: 32, hash: "SHA256")
+      d = OpenSSL::Cipher.new("aes-256-gcm").decrypt
+      d.key = key
+      d.iv = box.byteslice(0, 12)
+      d.auth_tag = box.byteslice(box.bytesize - 16, 16)
+      d.auth_data = "touchque-code-reply:#{request_id}"
+      code = (d.update(box.byteslice(12, box.bytesize - 28)) + d.final).force_encoding("UTF-8").strip
+      CODE_RE.match?(code) ? code : nil
+    rescue OpenSSL::OpenSSLError, ArgumentError, EncodingError
+      nil
+    end
+  end
+end

data/lib/touchque/cross_app_access.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Touchque
+  # A refused ID-JAG or exchange (Cross App Access). +error+ is the OAuth error:
+  # invalid_grant for a bad ID-JAG, else what the server answered.
+  class IdJagError < Error
+    attr_reader :error, :status
+
+    def initialize(error, message, status = nil)
+      @error = error
+      @status = status
+      super(message)
+    end
+  end
+
+  # Cross App Access: Identity Assertion JWT Authorization Grants (ID-JAG,
+  # draft-ietf-oauth-identity-assertion-authz-grant, an open standard). An
+  # organization's identity provider (Touchque SSO) decides which of its apps may reach
+  # which other service for its members; the app trades a member's ID token for an
+  # ID-JAG there, then the ID-JAG for an access token at the other service's
+  # authorization server, with no consent screen per member. Your own authorization
+  # server takes them with IdJagVerifier.
+  #
+  #   jag = Touchque::CrossAppAccess.request_id_jag(issuer: "https://sso.touchque.com", client_id: id, client_secret: secret,
+  #                                                 id_token: id_token, audience: "https://auth.files.example")
+  #   tokens = Touchque::CrossAppAccess.redeem_id_jag(token_endpoint: "https://auth.files.example/token", client_id: "acme",
+  #                                                   client_secret: files_secret, assertion: jag["assertion"])
+  module CrossAppAccess
+    ID_JAG_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:id-jag"
+    ID_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:id_token"
+    TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange"
+    JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer"
+
+    module_function
+
+    # https, or http on this machine (tests).
+    def safe_url?(url)
+      u = URI.parse(url.to_s)
+      u.scheme == "https" || (u.scheme == "http" && %w[localhost 127.0.0.1 ::1 [::1]].include?(u.host))
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def get_json(url)
+      status, text, = Transport.call("GET", url, timeout: 5)
+      raise "#{url} answered #{status}" if status >= 400
+
+      Util.parse_json(text) || {}
+    end
+
+    # The identity provider's OpenID configuration, checked against its issuer.
+    def discover(issuer, fetch = method(:get_json))
+      meta = fetch.call("#{issuer.chomp("/")}/.well-known/openid-configuration")
+      raise ConfigError, "the identity provider's metadata does not match its issuer" unless meta["issuer"] == issuer
+
+      meta
+    end
+
+    def post_form(url, fields, basic = nil)
+      raise ConfigError, "#{url} must be an https URL" unless safe_url?(url)
+
+      headers = { "Content-Type" => "application/x-www-form-urlencoded" }
+      if basic
+        raw = "#{URI.encode_www_form_component(basic[0]).gsub("+", "%20")}:#{URI.encode_www_form_component(basic[1]).gsub("+", "%20")}"
+        headers["Authorization"] = "Basic #{[raw].pack("m0")}"
+      end
+      status, text, = Transport.call("POST", url, headers: headers, body: Transport.form(fields), timeout: 10)
+      data = Util.parse_json(text)
+      data = {} unless data.is_a?(Hash)
+      raise IdJagError.new((data["error"] || "server_error").to_s, (data["error_description"] || "#{url} answered #{status}").to_s, status) if status >= 400
+
+      data
+    end
+
+    def scope_text(scope)
+      scope.is_a?(Array) ? scope.join(" ") : scope
+    end
+
+    # Trades a member's ID token for an ID-JAG at the identity provider (token exchange,
+    # client_secret_basic): { "assertion", "expires_in", "scope" }.
+    def request_id_jag(client_id:, client_secret:, id_token:, audience:, issuer: nil, token_endpoint: nil, resource: nil, scope: nil)
+      unless token_endpoint
+        raise ConfigError, "request_id_jag needs issuer or token_endpoint" if issuer.to_s.empty?
+
+        token_endpoint = discover(issuer)["token_endpoint"]
+        raise ConfigError, "the identity provider names no token_endpoint" unless token_endpoint.is_a?(String)
+      end
+      data = post_form(token_endpoint, {
+                         "grant_type" => TOKEN_EXCHANGE_GRANT, "requested_token_type" => ID_JAG_TOKEN_TYPE,
+                         "subject_token" => id_token, "subject_token_type" => ID_TOKEN_TYPE,
+                         "audience" => audience, "resource" => resource, "scope" => scope_text(scope)
+                       }, [client_id, client_secret])
+      unless data["issued_token_type"] == ID_JAG_TOKEN_TYPE && data["access_token"].is_a?(String)
+        raise IdJagError.new("invalid_response", "the identity provider did not answer with an ID-JAG")
+      end
+
+      { "assertion" => data["access_token"], "expires_in" => data["expires_in"], "scope" => data["scope"] }
+    end
+
+    # Trades an ID-JAG for an access token at the other service's authorization server (jwt-bearer).
+    def redeem_id_jag(token_endpoint:, client_id:, assertion:, client_secret: nil, resource: nil, scope: nil)
+      fields = { "grant_type" => JWT_BEARER_GRANT, "assertion" => assertion, "resource" => resource, "scope" => scope_text(scope) }
+      fields["client_id"] = client_id if client_secret.to_s.empty?
+      post_form(token_endpoint, fields, client_secret.to_s.empty? ? nil : [client_id, client_secret])
+    end
+  end
+
+  # Your authorization server, taking ID-JAGs from an organization's identity provider:
+  # checks the one an authenticated client presents (jwt-bearer grant) and uses it once.
+  #
+  #   verifier = Touchque::IdJagVerifier.new(issuer: "https://sso.touchque.com", audience: "https://auth.files.example")
+  #   claims = verifier.verify(params[:assertion], client_id: authenticated_client_id)
+  #
+  # +first_use+ (a callable jti, exp → true when new) lets several processes share a
+  # store such as Redis SET NX; memory in this process by default.
+  class IdJagVerifier
+    def initialize(issuer:, audience:, jwks_uri: nil, clock_skew: 60, first_use: nil, fetch: nil)
+      if issuer.to_s.empty? || audience.to_s.empty?
+        raise ConfigError, "IdJagVerifier needs issuer (the identity provider) and audience (your authorization server's issuer)"
+      end
+
+      @issuer = issuer
+      @audience = audience
+      @jwks_uri = jwks_uri
+      @skew = clock_skew
+      @first_use = first_use || method(:remember_once)
+      @fetch = fetch || CrossAppAccess.method(:get_json)
+      @keys = {}
+      @keys_at = 0
+      @tried_at = 0
+      @seen = {}
+      @lock = Mutex.new
+    end
+
+    # The ID-JAG, checked and used once: its claims, or IdJagError (error invalid_grant).
+    def verify(assertion, client_id:)
+      bad = ->(message) { IdJagError.new("invalid_grant", message) }
+      parts = JWS.split(assertion)
+      raise bad.call("assertion is not a JWT") unless parts
+
+      head, c, input, sig = parts
+      raise bad.call("not an ID-JAG (typ oauth-id-jag+jwt)") unless head["typ"] == "oauth-id-jag+jwt"
+      raise bad.call("unsupported signature") unless %w[RS256 ES256 EdDSA].include?(head["alg"]) && head["kid"].is_a?(String)
+
+      key = begin
+        key_for(head["kid"])
+      rescue StandardError => e
+        raise IdJagError.new("temporarily_unavailable", "the identity provider's keys could not be read: #{e.message}")
+      end
+      raise bad.call("signature does not verify") unless key && JWS.verify(head["alg"], key, input, sig)
+
+      now = Util.now
+      auds = c["aud"].is_a?(Array) ? c["aud"] : [c["aud"]]
+      raise bad.call("another issuer") unless c["iss"] == @issuer
+      raise bad.call("not for this authorization server") unless auds.length == 1 && auds[0] == @audience
+      raise bad.call("issued to another client") unless c["client_id"].is_a?(String) && c["client_id"] == client_id
+      raise bad.call("expired") unless c["exp"].is_a?(Numeric) && c["exp"] + @skew >= now
+      raise bad.call("issued in the future") unless c["iat"].is_a?(Numeric) && c["iat"] - @skew <= now
+      raise bad.call("sub and jti are required") unless c["sub"].is_a?(String) && c["jti"].is_a?(String)
+      raise bad.call("already used") unless @first_use.call(c["jti"], c["exp"].to_i)
+
+      {
+        "iss" => c["iss"], "sub" => c["sub"], "aud" => auds[0], "client_id" => c["client_id"], "jti" => c["jti"],
+        "issued_at" => c["iat"].to_i, "expires_at" => c["exp"].to_i,
+        "scopes" => c["scope"].is_a?(String) && !c["scope"].empty? ? c["scope"].split(" ") : [],
+        "resource" => c["resource"], "tenant" => c["tenant"], "email" => c["email"], "auth_time" => c["auth_time"], "amr" => c["amr"],
+        "claims" => c
+      }
+    end
+
+    private
+
+    def remember_once(jti, exp)
+      @lock.synchronize do
+        now = Util.now
+        @seen.delete_if { |_, until_at| until_at < now }
+        return false if @seen.key?(jti)
+
+        @seen[jti] = exp + @skew
+        true
+      end
+    end
+
+    def load_keys
+      unless @jwks_uri
+        @jwks_uri = CrossAppAccess.discover(@issuer, @fetch)["jwks_uri"]
+        raise "the identity provider names no jwks_uri" unless @jwks_uri.is_a?(String)
+      end
+      @keys = (@fetch.call(@jwks_uri)["keys"] || []).each_with_object({}) { |k, h| h[k["kid"]] = k if k["kid"] }
+      @keys_at = Util.now
+    end
+
+    def key_for(kid)
+      @lock.synchronize do
+        load_keys if @keys_at.zero? || Util.now - @keys_at > 600
+        if !@keys.key?(kid) && Util.now - @tried_at > 60
+          @tried_at = Util.now
+          load_keys
+        end
+        @keys[kid]
+      end
+    end
+  end
+end

data/lib/touchque/crypto.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Touchque
+  # Key helpers for AI agents (Touchque::Agent): new key pairs and RFC 7638 thumbprints.
+  module AgentKeys
+    # DER prefixes of the key formats OpenSSL reads (the key bytes follow them).
+    ED25519_PKCS8 = ["302e020100300506032b657004220420"].pack("H*")
+    ED25519_SPKI = ["302a300506032b6570032100"].pack("H*")
+    P256_SPKI = ["3059301306072a8648ce3d020106082a8648ce3d030107034200"].pack("H*")
+
+    module_function
+
+    # A new key pair: ES256 (P-256, default) or EdDSA (Ed25519), kid = the RFC 7638
+    # thumbprint. Register "publicJwk"; keep "privateJwk" where the agent runs.
+    def generate(alg = "ES256")
+      case alg
+      when "EdDSA"
+        key = OpenSSL::PKey.generate_key("ED25519")
+        public_jwk = { "kty" => "OKP", "crv" => "Ed25519", "x" => Util.b64url(key.public_to_der[-32, 32]) }
+        d = key.private_to_der[-32, 32]
+      when "ES256"
+        key = OpenSSL::PKey::EC.generate("prime256v1")
+        point = key.public_key.to_octet_string(:uncompressed)
+        public_jwk = { "kty" => "EC", "crv" => "P-256", "x" => Util.b64url(point[1, 32]), "y" => Util.b64url(point[33, 32]) }
+        d = pad32(key.private_key.to_s(2))
+      else
+        raise ConfigError, "alg must be ES256 or EdDSA"
+      end
+      kid = thumbprint(public_jwk)
+      {
+        "privateJwk" => public_jwk.merge("d" => Util.b64url(d), "kid" => kid, "alg" => alg),
+        "publicJwk" => public_jwk.merge("kid" => kid, "alg" => alg)
+      }
+    end
+
+    # RFC 7638 thumbprint of a P-256 or Ed25519 public key (the default kid).
+    def thumbprint(jwk)
+      jwk = Util.stringify(jwk)
+      canonical = if jwk["kty"] == "EC"
+                    "{\"crv\":#{Util.js_string(jwk["crv"])},\"kty\":\"EC\",\"x\":#{Util.js_string(jwk["x"])},\"y\":#{Util.js_string(jwk["y"])}}"
+                  else
+                    "{\"crv\":#{Util.js_string(jwk["crv"])},\"kty\":#{Util.js_string(jwk["kty"])},\"x\":#{Util.js_string(jwk["x"])}}"
+                  end
+      Util.b64url(Util.sha256(canonical))
+    end
+
+    # base64url SHA-256 of an access token, as a DPoP proof carries it ("ath").
+    def access_token_hash(token)
+      Util.b64url(Util.sha256(token))
+    end
+
+    def pad32(bytes)
+      bytes = bytes.b
+      bytes.bytesize >= 32 ? bytes : ("\0" * (32 - bytes.bytesize)).b + bytes
+    end
+
+    # An EC P-256 public key from its JWK coordinates.
+    def ec_public_key(x, y)
+      OpenSSL::PKey.read(P256_SPKI + "\x04".b + pad32(Util.b64url_decode(x)) + pad32(Util.b64url_decode(y)))
+    end
+
+    # An EC P-256 private key (SEC1 DER) from its JWK parts.
+    def ec_private_key(d, x, y)
+      der = ["30770201010420"].pack("H*") + pad32(Util.b64url_decode(d)) +
+            ["a00a06082a8648ce3d030107a144034200"].pack("H*") + "\x04".b +
+            pad32(Util.b64url_decode(x)) + pad32(Util.b64url_decode(y))
+      OpenSSL::PKey.read(der)
+    end
+
+    def ed25519_private_key(seed)
+      OpenSSL::PKey.read(ED25519_PKCS8 + seed.b)
+    end
+
+    def ed25519_public_key(raw)
+      OpenSSL::PKey.read(ED25519_SPKI + raw.b)
+    end
+
+    # An RSA public key from its JWK modulus and exponent.
+    def rsa_public_key(n, e)
+      int = ->(b64) { OpenSSL::ASN1::Integer.new(OpenSSL::BN.new(Util.b64url_decode(b64), 2)) }
+      rsa = OpenSSL::ASN1::Sequence.new([int.call(n), int.call(e)]).to_der
+      spki = OpenSSL::ASN1::Sequence.new([
+        OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::ObjectId.new("rsaEncryption"), OpenSSL::ASN1::Null.new(nil)]),
+        OpenSSL::ASN1::BitString.new(rsa)
+      ]).to_der
+      OpenSSL::PKey.read(spki)
+    end
+
+    # JOSE's raw r||s as an ECDSA DER signature.
+    def raw_to_der(raw)
+      r = OpenSSL::BN.new(raw[0, 32], 2)
+      s = OpenSSL::BN.new(raw[32, 32], 2)
+      OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::Integer.new(r), OpenSSL::ASN1::Integer.new(s)]).to_der
+    end
+
+    # An ECDSA DER signature as JOSE's raw r||s (64 bytes).
+    def der_to_raw(der)
+      seq = OpenSSL::ASN1.decode(der)
+      seq.value.map { |i| pad32(i.value.to_s(2)) }.join.b
+    end
+  end
+
+  # An ES256 or EdDSA private key that signs compact JWS (agent assertions, DPoP proofs).
+  class SigningKey
+    attr_reader :alg, :public_jwk
+
+    # A JWK (Hash or its JSON text) or an EC P-256 PEM.
+    def self.load(key, who)
+      jwk = if key.is_a?(Hash)
+              Util.stringify(key)
+            elsif key.is_a?(String) && key.lstrip.start_with?("{")
+              Util.parse_json(key)
+            end
+      return from_jwk(jwk) if jwk.is_a?(Hash)
+      return from_pem(key, who) if key.is_a?(String)
+
+      raise ConfigError, "#{who}: the private key must be a JWK (Hash or JSON) or an EC PEM"
+    end
+
+    def self.new_es256
+      key = OpenSSL::PKey::EC.generate("prime256v1")
+      point = key.public_key.to_octet_string(:uncompressed)
+      new("ES256", key, { "kty" => "EC", "crv" => "P-256", "x" => Util.b64url(point[1, 32]), "y" => Util.b64url(point[33, 32]) })
+    end
+
+    def self.from_jwk(jwk)
+      raise ConfigError, "The agent key must be the PRIVATE key (it has no d)" if jwk["d"].to_s.empty?
+
+      d = Util.b64url_decode(jwk["d"])
+      if jwk["kty"] == "OKP" && jwk["crv"] == "Ed25519" && d.bytesize == 32
+        key = AgentKeys.ed25519_private_key(d)
+        return new("EdDSA", key, { "kty" => "OKP", "crv" => "Ed25519", "x" => Util.b64url(key.public_to_der[-32, 32]) })
+      end
+      if jwk["kty"] == "EC" && jwk["crv"] == "P-256" && jwk["x"] && jwk["y"]
+        key = AgentKeys.ec_private_key(jwk["d"], jwk["x"], jwk["y"])
+        return new("ES256", key, { "kty" => "EC", "crv" => "P-256", "x" => jwk["x"], "y" => jwk["y"] })
+      end
+      raise ConfigError, "The agent key must be EC P-256 or Ed25519"
+    rescue OpenSSL::PKey::PKeyError, ArgumentError
+      raise ConfigError, "The agent key could not be read"
+    end
+
+    def self.from_pem(pem, who)
+      key = OpenSSL::PKey.read(pem)
+      raise ConfigError, "An EC agent key must be on P-256" unless key.is_a?(OpenSSL::PKey::EC) && key.group.curve_name == "prime256v1"
+
+      point = key.public_key.to_octet_string(:uncompressed)
+      new("ES256", key, { "kty" => "EC", "crv" => "P-256", "x" => Util.b64url(point[1, 32]), "y" => Util.b64url(point[33, 32]) })
+    rescue OpenSSL::PKey::PKeyError, ArgumentError
+      raise ConfigError, "#{who}: the private key must be a JWK (Hash or JSON) or an EC P-256 PEM"
+    end
+
+    def initialize(alg, key, public_jwk)
+      @alg = alg
+      @key = key
+      @public_jwk = public_jwk
+    end
+
+    def sign(input)
+      return @key.sign(nil, input) if @alg == "EdDSA"
+
+      AgentKeys.der_to_raw(@key.sign(OpenSSL::Digest.new("SHA256"), input))
+    end
+
+    # A compact JWS; "alg" is added to the header.
+    def jws(header, payload)
+      input = "#{Util.b64url(Util.json(header.merge("alg" => @alg)))}.#{Util.b64url(Util.json(payload))}"
+      "#{input}.#{Util.b64url(sign(input))}"
+    end
+  end
+
+  # JWS signature checks for the algorithms Touchque uses.
+  module JWS
+    module_function
+
+    # [header, claims, signing input, signature] of a compact JWS, or nil.
+    def split(token)
+      parts = token.to_s.split(".", -1)
+      return nil unless parts.length == 3
+
+      header = Util.parse_json(Util.b64url_decode(parts[0]).force_encoding("UTF-8"))
+      claims = Util.parse_json(Util.b64url_decode(parts[1]).force_encoding("UTF-8"))
+      return nil unless header.is_a?(Hash) && claims.is_a?(Hash)
+
+      [header, claims, "#{parts[0]}.#{parts[1]}", Util.b64url_decode(parts[2])]
+    rescue ArgumentError
+      nil
+    end
+
+    def verify(alg, jwk, input, signature)
+      jwk = Util.stringify(jwk)
+      case alg
+      when "ES256"
+        return false unless jwk["kty"] == "EC" && jwk["crv"] == "P-256" && signature.bytesize == 64
+
+        AgentKeys.ec_public_key(jwk["x"], jwk["y"]).verify(OpenSSL::Digest.new("SHA256"), AgentKeys.raw_to_der(signature), input)
+      when "RS256"
+        return false unless jwk["kty"] == "RSA"
+
+        AgentKeys.rsa_public_key(jwk["n"], jwk["e"]).verify(OpenSSL::Digest.new("SHA256"), signature, input)
+      when "EdDSA"
+        return false unless jwk["kty"] == "OKP" && jwk["crv"] == "Ed25519" && signature.bytesize == 64
+
+        raw = Util.b64url_decode(jwk["x"])
+        raw.bytesize == 32 && AgentKeys.ed25519_public_key(raw).verify(nil, signature, input)
+      else
+        false
+      end
+    rescue OpenSSL::PKey::PKeyError, OpenSSL::ASN1::ASN1Error, ArgumentError
+      false
+    end
+  end
+end