saro-dat 4.3.4 → 4.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87e1f1949bc6ed97274fa1141ca2d76915b75a09e6010f111f4bfce321316396
-  data.tar.gz: '05139251e2a28e03dd44cbe709b6612267373046c67c789052679dfbd13aec23'
+  metadata.gz: 9e9d9a8073169dbbd0fb625d174acca960f30687ccf78b0d0d9424ca2d4d8ba2
+  data.tar.gz: 1e727fef007baebc0960c14cbe57362db21d0311fc6486b0d6f3164d5da42dee
 SHA512:
-  metadata.gz: 6b43afc3cac0deb85eb1bbd5174049d91d07a033319078d7f0af2ecc5b3e290e8a0dd768e7a2de9db7cdedc50d62827f2103e5065a8811400c23376aef28650f
-  data.tar.gz: 3a4840105836a569f47af5cecb6bc57bd7aa79ee511b74d66e1cee2b96b4359c226e624849ab9f64be7d1d3cbd560d886bb0d33bd34fb51a6ebc9f6e53adbb71
+  metadata.gz: afea00f884102f1a5e84bf8992a024cb08810d04637625f0d09553b9e48ae0e1d01e9946734177db764a76846c1ff083d02c592c492d331d39bf1ffd8d05945b
+  data.tar.gz: 2b8184f5c8279fc6717d15ccd4a82f4580d6e90dfb660eb6c4a151fa03ae5727cfa7cd08e694a192c8ddd96ecf9ba2a0b64d77dd6fcf21121d577445231bcb6c

data/.idea/vcs.xml

@@ -3,5 +3,6 @@
   <component name="VcsDirectoryMappings">
     <mapping directory="" vcs="Git" />
     <mapping directory="$PROJECT_DIR$/../.." vcs="Git" />
+    <mapping directory="$PROJECT_DIR$/.." vcs="Git" />
   </component>
 </project>

data/PUBLISH.md

@@ -9,7 +9,9 @@ bundle install
 ```
 gem build saro-dat.gemspec
 gem signin
-gem push saro-dat-4.3.4.gem
+# glob, not a pinned filename: a hardcoded version silently pushes a stale
+# package after a version bump
+gem push saro-dat-*.gem
 ```
 
 ## install

data/README.md

@@ -6,14 +6,14 @@
 - [Example](https://dat.saro.me/libs/gems-saro-dat)
 
 ### Support Platform
-- [Rust](https://github.com/saro-lab/dat/tree/master/clients/dat-rust)
-- [Java, Kotlin](https://github.com/saro-lab/dat/tree/master/clients/dat-maven)
-- [Javascript, Typescript](https://github.com/saro-lab/dat/tree/master/clients/dat-npm)
-- [C#](https://github.com/saro-lab/dat/tree/master/clients/dat-nuget)
-- [Python](https://github.com/saro-lab/dat/tree/master/clients/dat-pypi)
-- [Go](https://github.com/saro-lab/dat/tree/master/clients/dat-go)
-- [Ruby](https://github.com/saro-lab/dat/tree/master/clients/dat-ruby)
-- [C/C++ (Vcpkg)](https://github.com/saro-lab/dat/tree/master/clients/dat-vcpkg)
+- [Rust](https://github.com/saro-lab/dat/tree/master/dat-rust)
+- [Java, Kotlin](https://github.com/saro-lab/dat/tree/master/dat-maven)
+- [Javascript, Typescript](https://github.com/saro-lab/dat/tree/master/dat-npm)
+- [C#](https://github.com/saro-lab/dat/tree/master/dat-nuget)
+- [Python](https://github.com/saro-lab/dat/tree/master/dat-pypi)
+- [Go](https://github.com/saro-lab/dat/tree/master/dat-go)
+- [Ruby](https://github.com/saro-lab/dat/tree/master/dat-ruby)
+- [C/C++ (Vcpkg)](https://github.com/saro-lab/dat/tree/master/dat-vcpkg)
 - [Cert(Key) Server (Docker)](https://github.com/saro-lab/dat)
 
 ## Support algorithm

data/lib/saro/dat/crypto.rb

@@ -2,6 +2,7 @@
 
 require 'openssl'
 require 'securerandom'
+require_relative 'error'
 require_relative 'util'
 
 module Saro
@@ -23,7 +24,7 @@ module Saro
     def self.get_crypto_config(algorithm)
       config = CRYPTO_CONFIG[algorithm]
       return config if config
-      raise ArgumentError, "Unsupported DAT Crypto Algorithm: #{algorithm}"
+      raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_ALG_UNSUPPORTED, "unknown crypto algorithm: #{algorithm}")
     end
 
     class DatCrypto
@@ -31,6 +32,14 @@ module Saro
 
       def initialize(algorithm, key_bytes, config = nil)
         @config = config || Saro::Dat.get_crypto_config(algorithm)
+        # OpenSSL accepts any valid AES length, so a 16-byte key would silently
+        # become AES-128 under an IV-AES256-GCM label without this check.
+        if key_bytes.bytesize != @config[:length]
+          raise Saro::Dat::Error.new(
+            Saro::Dat::ErrorCode::KEY_INVALID,
+            "#{algorithm} key must be #{@config[:length]} bytes, got #{key_bytes.bytesize}"
+          )
+        end
         @algorithm = algorithm
         @key_bytes = key_bytes
       end
@@ -63,20 +72,35 @@ module Saro
         cipher.iv_len = 12
         cipher.iv = nonce
         
-        ciphertext = cipher.update(data) + cipher.final
-        tag = cipher.auth_tag
+        begin
+          ciphertext = cipher.update(data) + cipher.final
+          tag = cipher.auth_tag
+        rescue OpenSSL::Cipher::CipherError => e
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CRYPTO_BACKEND, "aes-gcm encrypt failed", cause: e)
+        end
 
         nonce + ciphertext + tag
       end
 
+      # Decrypts base64url-encoded ciphertext.
+      def decrypt_base64(base64_str)
+        decrypt(Saro::Dat::Util.decode_base64_url(base64_str))
+      end
+
+      # Decrypts raw (already decoded) ciphertext: nonce(12) + ciphertext + tag(16).
+      # Use #decrypt_base64 for encoded input. The branch used to be picked from
+      # the string's encoding tag, so raw ciphertext that merely carried a UTF-8
+      # tag was silently mangled by the base64 decoder.
       def decrypt(data)
-        if data.is_a?(String) && data.encoding != Encoding::BINARY
-          data = Saro::Dat::Util.decode_base64_url(data)
-        end
         return "".b if data.nil? || data.empty?
 
-        if data.length <= 12 + 16 # nonce(12) + tag(16)
-          raise ArgumentError, "Invalid data length"
+        # Slice by bytes, never by characters: String#[] is character-indexed on
+        # a non-binary string, so raw ciphertext carrying a UTF-8 tag would be
+        # split at the wrong offsets.
+        data = data.b if data.is_a?(String) && data.encoding != Encoding::BINARY
+
+        if data.bytesize <= 12 + 16 # nonce(12) + tag(16)
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CRYPTO_DATA_INVALID, "ciphertext is shorter than iv(12) + tag(16)")
         end
 
         nonce = data[0, 12]
@@ -90,7 +114,15 @@ module Saro
         cipher.iv = nonce
         cipher.auth_tag = tag
 
-        res = cipher.update(ciphertext) + cipher.final
+        # cipher.final 에서 나는 실패는 GCM 인증 태그 불일치다 — 변조된 secure 이거나
+        # 잘못된 인증서 키다. 예전에는 OpenSSL::Cipher::CipherError 가 그대로 공개
+        # API 밖으로 새어 나갔다. 서명 검증을 건너뛰는 경로에서는 이것이 유일한
+        # 무결성 검사이므로 백엔드 오류(CRYPTO_BACKEND)와 반드시 구분한다.
+        begin
+          res = cipher.update(ciphertext) + cipher.final
+        rescue OpenSSL::Cipher::CipherError => e
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CRYPTO_TAG_MISMATCH, "gcm authentication tag mismatch", cause: e)
+        end
         res.force_encoding('BINARY')
         res
       end

data/lib/saro/dat/dat.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'error'
 require_relative 'util'
 
 module Saro
@@ -7,6 +8,13 @@ module Saro
     class Dat
       attr_reader :dat, :expire, :cid, :plain, :secure, :signature, :format
 
+      # 파싱이 실패한 이유. 성공이면 nil 이다.
+      #
+      # 예전에는 빈 `rescue StandardError` 가 모든 실패를 삼키고 @format=false
+      # 하나만 남겼다. 어느 필드가 왜 틀렸는지가 전부 사라져 호출부는
+      # "Invalid DAT: Format" 밖에 볼 수 없었다.
+      attr_reader :error
+
       def initialize(dat_str)
         @dat = dat_str || ''
         @format = false
@@ -15,22 +23,79 @@ module Saro
         @plain = "".b
         @secure = "".b
         @signature = "".b
+        @error = nil
+
+        if @dat.empty?
+          @error = Saro::Dat::Error.new(Saro::Dat::ErrorCode::TOKEN_MALFORMED, "token is empty")
+          return
+        end
+
+        # 1) 먼저 구조를 확정한다. 파트가 5개가 아니면 그건 만료된 토큰이 아니라
+        #    애초에 토큰이 아니다.
+        #    split 의 limit 을 -1 로 준다: 기본값은 뒤쪽 빈 필드를 버려서
+        #    "a.b.c.d.e." (6필드) 가 5파트로 보였고, 빈 서명("a.b.c.d.")은
+        #    4파트로 보여 서명 오류를 구조 오류로 오인하게 만들었다.
+        parts = @dat.split('.', -1)
+        if parts.length != 5
+          @error = Saro::Dat::Error.new(Saro::Dat::ErrorCode::TOKEN_MALFORMED, "expected exactly 5 dot-separated fields")
+          return
+        end
+
+        # 2) 구조가 맞은 뒤에야 값을 본다. 필드마다 어디서 틀렸는지 코드를 붙인다.
+        begin
+          @expire = Saro::Dat::Util.parse_u64(parts[0])
+        rescue Saro::Dat::Error => e
+          @error = Saro::Dat::Error.new(Saro::Dat::ErrorCode::TOKEN_MALFORMED, "expire field is not a plain decimal u64", cause: e)
+          return
+        end
+
+        begin
+          @cid = Saro::Dat::Util.parse_u64_hex(parts[1])
+        rescue Saro::Dat::Error => e
+          @error = Saro::Dat::Error.new(Saro::Dat::ErrorCode::TOKEN_MALFORMED, "cid field is not a plain hex u64", cause: e)
+          return
+        end
+
+        begin
+          @plain = Saro::Dat::Util.decode_base64_url(parts[2])
+        rescue Saro::Dat::Error => e
+          @error = Saro::Dat::Error.new(Saro::Dat::ErrorCode::TOKEN_MALFORMED, "plain field is not base64url", cause: e)
+          return
+        end
+
+        begin
+          @secure = Saro::Dat::Util.decode_base64_url(parts[3])
+        rescue Saro::Dat::Error => e
+          @error = Saro::Dat::Error.new(Saro::Dat::ErrorCode::TOKEN_MALFORMED, "secure field is not base64url", cause: e)
+          return
+        end
+
+        # 빈 서명은 구조 오류가 아니라 서명 오류다 (error.pre2.md: DAT_SIG_MALFORMED
+        # 가 "빈 서명"을 포함한다). 위조(SIG_MISMATCH)와도 구분된다.
+        if parts[4].empty?
+          @error = Saro::Dat::Error.new(Saro::Dat::ErrorCode::SIG_MALFORMED, "signature field is empty")
+          return
+        end
 
-        if !@dat.empty?
-          parts = @dat.split('.')
-          if parts.length == 5
-            begin
-              @expire = parts[0].to_i
-              @cid = parts[1].to_i(16)
-              @plain = Saro::Dat::Util.decode_base64_url(parts[2])
-              @secure = Saro::Dat::Util.decode_base64_url(parts[3])
-              @signature = Saro::Dat::Util.decode_base64_url(parts[4])
-              @format = (!@signature.empty? && @expire >= 0)
-            rescue StandardError
-              @format = false
-            end
-          end
+        begin
+          @signature = Saro::Dat::Util.decode_base64_url(parts[4])
+        rescue Saro::Dat::Error => e
+          @error = Saro::Dat::Error.new(Saro::Dat::ErrorCode::SIG_MALFORMED, "signature field is not base64url", cause: e)
+          return
         end
+
+        if @signature.empty?
+          @error = Saro::Dat::Error.new(Saro::Dat::ErrorCode::SIG_MALFORMED, "signature field is empty")
+          return
+        end
+
+        @format = true
+      end
+
+      # 파싱에 실패했으면 그 코드로 던진다.
+      def raise_if_invalid!
+        raise @error if @error
+        nil
       end
 
       def self.from_value(value)
@@ -40,7 +105,7 @@ module Saro
 
       def expired
         return true unless @format
-        Time.now.to_i > @expire
+        Time.now.to_i >= @expire
       end
 
       alias_method :expired?, :expired

data/lib/saro/dat/dat_certificate.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'error'
 require_relative 'crypto'
 require_relative 'signature'
 require_relative 'util'
@@ -10,10 +11,20 @@ module Saro
       attr_reader :cid, :signature_key, :crypto_key, :dat_issuance_start_seconds, :dat_issuance_end_seconds, :dat_ttl_seconds
 
       def initialize(cid, dat_issuance_start_seconds, dat_issuance_duration_seconds, dat_ttl_seconds, signature_key, crypto_key)
-        @cid = cid
-        @dat_issuance_start_seconds = dat_issuance_start_seconds
-        @dat_issuance_end_seconds = dat_issuance_start_seconds + dat_issuance_duration_seconds
-        @dat_ttl_seconds = dat_ttl_seconds
+        @cid = u64!("cid", cid)
+        @dat_issuance_start_seconds = u64!("dat_issuance_start_seconds", dat_issuance_start_seconds)
+        duration = u64!("dat_issuance_duration_seconds", dat_issuance_duration_seconds)
+        @dat_ttl_seconds = u64!("dat_ttl_seconds", dat_ttl_seconds)
+        # Ruby 정수는 자동으로 bignum 이 되므로 그냥 더하면 u64 를 넘겨도 조용히
+        # 통과한다. 기준 구현(rust)의 checked_add 와 같은 경계를 여기서 강제한다.
+        @dat_issuance_end_seconds = u64!(
+          "dat_issuance_start_seconds + dat_issuance_duration_seconds",
+          @dat_issuance_start_seconds + duration
+        )
+        u64!(
+          "dat_issuance_start_seconds + dat_issuance_duration_seconds + dat_ttl_seconds",
+          @dat_issuance_end_seconds + @dat_ttl_seconds
+        )
         @signature_key = signature_key
         @crypto_key = crypto_key
       end
@@ -41,12 +52,15 @@ module Saro
 
       def self.imports(format_str)
         parts = format_str.split(".")
-        raise ArgumentError, "Invalid Certificate format" if parts.length != 8
+        if parts.length != 8
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CERT_MALFORMED, "expected exactly 8 dot-separated fields")
+        end
 
-        cid = parts[0].to_i(16)
-        dat_issuance_start_seconds = parts[1].to_i
-        dat_issuance_duration_seconds = parts[2].to_i
-        dat_ttl_seconds = parts[3].to_i
+        # 필드 파싱 실패는 인증서가 깨진 것이지 호출자의 인자 문제가 아니다.
+        cid = _field("cid") { Saro::Dat::Util.parse_u64_hex(parts[0]) }
+        dat_issuance_start_seconds = _field("issuance_start_seconds") { Saro::Dat::Util.parse_u64(parts[1]) }
+        dat_issuance_duration_seconds = _field("issuance_duration_seconds") { Saro::Dat::Util.parse_u64(parts[2]) }
+        dat_ttl_seconds = _field("dat_ttl_seconds") { Saro::Dat::Util.parse_u64(parts[3]) }
         signature_algorithm = parts[4]
         crypto_algorithm = parts[5]
         signature_key = Saro::Dat::DatSignature.imports(signature_algorithm, parts[6])
@@ -76,6 +90,23 @@ module Saro
         @signature_key.support_verify_only
       end
 
+      U64_MAX = 0xFFFFFFFFFFFFFFFF
+      private_constant :U64_MAX
+
+      private def u64!(name, value)
+        unless value.is_a?(Integer) && !value.is_a?(TrueClass) && value >= 0 && value <= U64_MAX
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CERT_MALFORMED, "#{name} must fit in u64: #{value}")
+        end
+        value
+      end
+
+      def self._field(name)
+        yield
+      rescue Saro::Dat::Error => e
+        raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CERT_MALFORMED, "#{name} field is not a plain number", cause: e)
+      end
+      private_class_method :_field
+
       # For Ruby conventions
       alias_method :issuable?, :issuable
       alias_method :expired?, :expired

data/lib/saro/dat/dat_cms_manager.rb

@@ -4,6 +4,7 @@ require 'net/http'
 require 'uri'
 require 'logger'
 require 'thread'
+require_relative 'error'
 require_relative 'dat_manager'
 require_relative 'dat'
 
@@ -12,6 +13,11 @@ module Saro
     class DatCmsManager
       DAT_CMS_API_VERSION = "v1"
 
+      # `stop` waits at most this long for an in-flight HTTP sync to finish.
+      # The thread is never killed: past the grace period it is left to complete
+      # its request and exit on its own at the top of the loop.
+      STOP_JOIN_TIMEOUT_SECONDS = 1.0
+
       def initialize(uri:, token:, interval_seconds: 60, verify_only: false, dat_manager: nil)
         @uri = uri
         @token = token
@@ -19,10 +25,19 @@ module Saro
         @verify_only = verify_only
         @manager = dat_manager || DatManager.new
         @version = 0
+        # Two separate locks: @lock guards an in-flight sync (taken non-blocking,
+        # held across the HTTP request), @lifecycle guards the stop flag and the
+        # sleep condition. Sharing one lock made `stop` block for the whole
+        # request timeout.
         @lock = Mutex.new
+        @lifecycle = Mutex.new
+        @stop_cond = ConditionVariable.new
         @stopped = false
         @logger = Logger.new($stdout)
         @logger.level = Logger::DEBUG
+        # 최초 sync 실패는 여전히 생성을 막지 않는다(list.md F-3). 다만 이제 로그로만
+        # 사라지지 않고 #last_error 로 조회할 수 있다.
+        @last_error = Saro::Dat::Error.new(Saro::Dat::ErrorCode::CMS_NOT_SYNCED)
 
         sync
 
@@ -32,17 +47,55 @@ module Saro
       end
 
       def stop
-        @lock.synchronize do
+        thread = nil
+        @lifecycle.synchronize do
+          return if @stopped
           @stopped = true
-          @thread&.kill # 혹은 다른 방식으로 스레드 중지
+          # Wakes the scheduler out of its sleep immediately instead of killing
+          # it in the middle of a request.
+          @stop_cond.broadcast
+          thread = @thread
         end
+        thread&.join(STOP_JOIN_TIMEOUT_SECONDS)
+        nil
+      end
+
+      def stopped?
+        @lifecycle.synchronize { @stopped }
+      end
+
+      # 마지막 동기화 실패. 한 번도 성공하지 못했으면 DAT_CMS_NOT_SYNCED, 정상이면 nil.
+      # 재시도 여부는 err.retry 로 판정한다.
+      attr_reader :last_error
+
+      def version
+        @version
       end
 
       def sync
+        err = sync_or_raise
+        @last_error = nil
+        err
+      rescue Saro::Dat::Error => e
+        # 상태 신호는 실패로 기록하지 않는다 — 이전 동기화가 도는 중일 뿐이다.
+        unless e.retry == :state
+          @last_error = e
+          @logger.error("[CRITICAL] DAT CMS SYNC #{@uri}: #{e.code} #{e.detail}")
+        end
+        nil
+      rescue StandardError => e
+        @last_error = Saro::Dat::Error.new(Saro::Dat::ErrorCode::CMS_UNKNOWN, "unclassified cms failure", cause: e)
+        @logger.error("[CRITICAL] DAT CMS SYNC #{@uri}: #{e.message}")
+        nil
+      end
+
+      # 실패를 코드로 던진다. #sync 는 이것을 잡아 #last_error 에 담기만 한다 —
+      # 기존 호출부가 갑자기 예외를 받지 않도록.
+      private def sync_or_raise
         # non-blocking lock
         unless @lock.try_lock
-          @logger.warn("Last request ignored (Duplicate request)")
-          return
+          @logger.debug("cms sync skipped, previous sync still running: #{@uri}")
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CMS_SYNC_IN_PROGRESS)
         end
 
         begin
@@ -50,55 +103,82 @@ module Saro
           request = Net::HTTP::Get.new(url)
           request["Authorization"] = @token
 
-          response = Net::HTTP.start(url.host, url.port, use_ssl: url.scheme == 'https', open_timeout: 10, read_timeout: 10) do |http|
-            http.request(request)
-          end
+          # 연결 거부·DNS 실패·TLS 실패·타임아웃이 전부 여기로 온다. 전부 일시적이다.
+          response =
+            begin
+              Net::HTTP.start(url.host, url.port, use_ssl: url.scheme == 'https', open_timeout: 10, read_timeout: 10) do |http|
+                http.request(request)
+              end
+            rescue StandardError => e
+              raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CMS_UNREACHABLE, "cannot reach #{@uri}", cause: e)
+            end
 
-          if response.code != "200"
-            @logger.error("Response status error, status:#{response.code} in #{url}")
-            return
-          end
+          # HTTP 상태를 갈라 낸다. 예전에는 전부 하나의 로그라 401(영구)에도
+          # 60초마다 영원히 재시도했다.
+          status = response.code.to_i
+          raise self.class.http_status_error(status) unless status.between?(200, 299)
 
           body = response.body
           if body.nil? || body.empty?
             @logger.debug("No new certificate: #{url}")
-            return
+            return nil
           end
 
           lines = body.split("\n", 2)
           if lines.length < 2
             if body.start_with?("\n")
-              @logger.error("Invalid response: #{url}")
-              return
+              raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CMS_MALFORMED, "response has no version line")
             end
             @logger.debug("No new certificate: #{url}")
-            return
+            return nil
           end
 
           new_version_str = lines[0].strip
           new_certificates = lines[1].strip
 
-          if new_version_str.empty?
-            @logger.error("Invalid version in response: #{url}")
-            return
+          unless new_version_str.match?(/\A[0-9]+\z/)
+            raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CMS_MALFORMED, "version line is not a plain decimal integer")
           end
+          new_version = new_version_str.to_i
 
-          begin
-            new_version = Integer(new_version_str)
-            renew_count = @manager.imports(new_certificates, clear: false)
-            @version = new_version
-            @logger.debug("Renewed #{renew_count} certificates for version #{new_version}: #{url}")
-          rescue ArgumentError => e
-            @logger.error("Failed to parse version or certificates: #{e.message}")
+          # 서버가 우리보다 과거 버전을 돌려주면 전체 재동기화 지시다. 오류가 아니라
+          # 상태 신호이며, 아래 imports 가 clear: true 라 그 자체로 처리된다.
+          if new_version < @version
+            @logger.warn("#{Saro::Dat::ErrorCode::CMS_VERSION_RESET}: #{@version} -> #{new_version}")
           end
 
-        rescue StandardError => e
-          @logger.error("[Exception] DAT CMS Sync #{@uri}: #{e.message}")
+          # 인증서 적용 실패의 원인(CERT_*/KEY_*)을 버리지 않고 체이닝한다.
+          renew_count =
+            begin
+              # clear: true, like rust's `manager.import(&certs, true)`. The CMS
+              # response is the authoritative full set for that version, so
+              # revoked certificates disappear instead of lingering until they
+              # expire on their own.
+              @manager.imports(new_certificates, clear: true)
+            rescue Saro::Dat::Error => e
+              raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CMS_IMPORT_FAILED, "cannot apply received certificates", cause: e)
+            end
+
+          # Only a successful import advances the version, matching rust:
+          # a rejected payload is re-requested rather than skipped.
+          @version = new_version
+          @logger.debug("Renewed #{renew_count} certificates for version #{new_version}: #{url}")
+          nil
         ensure
           @lock.unlock
         end
       end
 
+      def self.http_status_error(status)
+        case status
+        when 401 then Saro::Dat::Error.new(Saro::Dat::ErrorCode::CMS_UNAUTHORIZED, "http 401")
+        when 403 then Saro::Dat::Error.new(Saro::Dat::ErrorCode::CMS_FORBIDDEN, "http 403")
+        when 404 then Saro::Dat::Error.new(Saro::Dat::ErrorCode::CMS_ENDPOINT_NOT_FOUND, "http 404")
+        when 500..599 then Saro::Dat::Error.new(Saro::Dat::ErrorCode::CMS_SERVER_ERROR, "http #{status}")
+        else Saro::Dat::Error.new(Saro::Dat::ErrorCode::CMS_HTTP_STATUS, "http #{status}")
+        end
+      end
+
       def get_manager
         @manager
       end
@@ -120,16 +200,26 @@ module Saro
       def schedule_sync
         @thread = Thread.new do
           loop do
-            sleep(@interval_seconds)
-            break if @stopped
+            break unless wait_interval
             run_sync_task
           end
         end
       end
 
+      # Interruptible sleep: returns false as soon as `stop` signals, so the
+      # scheduler exits promptly without Thread#kill.
+      def wait_interval
+        @lifecycle.synchronize do
+          return false if @stopped
+          @stop_cond.wait(@lifecycle, @interval_seconds)
+          !@stopped
+        end
+      end
+
       def run_sync_task
         sync
       rescue StandardError => e
+        # sync 는 이미 스스로 삼키므로 여기 오는 것은 예상 밖의 실패다.
         @logger.error("Error in sync task: #{e.message}")
       end
     end
@@ -168,13 +258,21 @@ module Saro
       end
 
       def build
-        parsed = URI.parse(@uri)
-        
+        parsed =
+          begin
+            URI.parse(@uri)
+          rescue URI::InvalidURIError => e
+            raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_URI_INVALID, "cannot be parsed as a uri", cause: e)
+          end
+
+        unless %w[http https].include?(parsed.scheme)
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_URI_INVALID, "scheme must be http or https")
+        end
         if parsed.path && parsed.path != '' && parsed.path != '/'
-          raise ArgumentError, "uri must be path-less: #{@uri}"
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_URI_INVALID, "must be path-less: #{@uri}")
         end
         if parsed.query
-          raise ArgumentError, "uri must be query-less: #{@uri}"
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_URI_INVALID, "must be query-less: #{@uri}")
         end
 
         path = @verify_only ? "/v1/certs/verify-only" : "/v1/certs"

data/lib/saro/dat/dat_manager.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'set'
+require_relative 'error'
 require_relative 'dat_certificate'
 require_relative 'dat'
 require_relative 'signature'
@@ -23,23 +24,38 @@ module Saro
       end
 
       def import_certificates(input_certs, clear: false)
+        # rust returns early on an empty input without touching the state, so an
+        # empty CMS response can never wipe the certificates held by a manager
+        # that is importing with clear: true.
+        return 0 if input_certs.nil? || input_certs.empty?
+
+        # Duplicate detection runs before any mutation (rust checks the whole
+        # input up front), so a bad payload cannot leave a half-applied state.
+        seen_cids = Set.new
+        input_certs.each do |cert|
+          if seen_cids.include?(cert.cid)
+            raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CERT_DUPLICATE_CID, "duplicate cid #{cert.cid.to_s(16)}")
+          end
+          seen_cids.add(cert.cid)
+        end
+
         renew_count = 0
         @write_lock.synchronize do
           certificates = clear ? [] : @state.certificates.dup
 
-          before_cids = Set.new(certificates.map(&:cid))
-          seen_cids = Set.new
+          cids = Set.new(certificates.map(&:cid))
 
           input_certs.each do |cert|
-            raise ArgumentError, "Duplicate CID: #{cert.cid}" if seen_cids.include?(cert.cid)
-            seen_cids.add(cert.cid)
-            next if cert.expired
-            next if before_cids.include?(cert.cid)
+            next if cids.include?(cert.cid)
 
+            cids.add(cert.cid)
             certificates << cert
             renew_count += 1
           end
 
+          # Expired certificates are dropped from the *merged* list, not just
+          # from the incoming one, so a renewal sweeps out what has aged out.
+          certificates.reject!(&:expired)
           certificates.sort_by!(&:dat_issuance_end_seconds)
 
           # Find latest issuable certificate as issuer
@@ -68,24 +84,73 @@ module Saro
       end
 
       def issue(plain, secure)
-        issuer = @state.issuer
-        raise RuntimeError, "Invalid DAT: Signing Key Does Not Exist" unless issuer
+        state = @state
+        issuer = state.issuer
+        unless issuer
+          # 예전에는 이 다섯 가지가 "Invalid DAT: Signing Key Does Not Exist"
+          # 문자열 하나였다. 대응이 전부 다르다 — 발급창 전이면 기다리면 되고,
+          # verify-only 뿐이면 배포 설정 실수이며, 0건이면 CMS 접속 문제다.
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::MANAGER_NO_CERTIFICATE) if state.certificates.empty?
+          raise Saro::Dat::Error.new(
+            Saro::Dat::ErrorCode::MANAGER_NO_ISSUABLE_CERTIFICATE,
+            cause: no_issuable_cause(state.certificates)
+          )
+        end
 
         self.class._issue(issuer, plain, secure)
       end
 
       def parse(dat_input)
         dat = Saro::Dat::Dat.from_value(dat_input)
-        raise ArgumentError, "Invalid DAT: Format" unless dat.format
+        # 파싱 실패의 코드를 그대로 올린다.
+        dat.raise_if_invalid!
 
-        certificate = @state.by_cid[dat.cid]
+        # 만료를 cid 조회보다 먼저 본다. 기준 구현(rust)이 토큰을 읽는 시점에
+        # 만료를 판정하므로, 모르는 cid 의 만료 토큰도 만료로 보고된다.
+        raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::TOKEN_EXPIRED) if dat.expired?
 
-        raise ArgumentError, "Invalid DAT: CID(Certificate ID) Not Found" unless certificate
+        certificate = @state.by_cid[dat.cid]
+        unless certificate
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CERT_NOT_FOUND, "cid #{dat.cid.to_s(16)}")
+        end
 
         self.class._parse(certificate, dat)
       end
 
-      private
+      # 발급 가능한 인증서가 없을 때 왜 없는지 가려낸다.
+      private def no_issuable_cause(certificates)
+        now = Time.now.to_i
+        signable_seen = false
+        not_yet = false
+        ended = false
+
+        certificates.each do |cert|
+          next unless cert.signable
+          signable_seen = true
+          if now < cert.dat_issuance_start_seconds
+            not_yet = true
+          elsif now > cert.dat_issuance_end_seconds
+            ended = true
+          end
+        end
+
+        code =
+          if !signable_seen
+            Saro::Dat::ErrorCode::CERT_VERIFY_ONLY
+          elsif not_yet
+            # 기다리면 풀리는 유일한 사유다. 하나라도 있으면 이것을 앞세운다.
+            Saro::Dat::ErrorCode::CERT_NOT_YET_ISSUABLE
+          elsif ended
+            Saro::Dat::ErrorCode::CERT_ISSUANCE_ENDED
+          else
+            Saro::Dat::ErrorCode::CERT_EXPIRED
+          end
+        Saro::Dat::Error.new(code)
+      end
+
+      # NOTE: 아래 `private` 는 `def self.` 메서드에 적용되지 않는다. _issue/_parse 는
+      # 예전부터 실제로는 public 이었고 테스트·벤치가 그렇게 쓰고 있다. 오해를 없애려
+      # 위치를 옮기고, 정말 감춰야 하는 것만 private_class_method 로 막는다.
 
       def self._issue(cert, plain, secure)
         now = Time.now.to_i
@@ -105,11 +170,14 @@ module Saro
 
       def self._parse(cert, dat_input)
         dat = Saro::Dat::Dat.from_value(dat_input)
-        raise RuntimeError, "Invalid DAT: Format" unless dat.format
-        raise RuntimeError, "Invalid DAT: Expired" if dat.expired?
+        # 같은 조건이 여기서는 RuntimeError, DatManager#parse 에서는 ArgumentError
+        # 였다. 이제 양쪽 모두 같은 코드를 던진다.
+        dat.raise_if_invalid!
+        raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::TOKEN_EXPIRED) if dat.expired?
 
+        # verify 는 불일치일 때만 false 를 준다. 연산 실패는 SIG_BACKEND 로 올라온다.
         unless cert.signature_key.verify(dat.body_string, dat.signature)
-          raise RuntimeError, "Invalid DAT: Signature"
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::SIG_MISMATCH)
         end
 
         decrypted_secure = cert.crypto_key.decrypt(dat.secure)

data/lib/saro/dat/error.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Saro
+  module Dat
+    # DAT 통합 오류 코드 (error.pre2.md).
+    #
+    # 코드 문자열은 모든 공식 클라이언트와 CMS 서버가 공유하는 공개 계약이다. 메시지는 자유롭게 바꿔도
+    # 되지만 코드는 바꾸지 않는다.
+    #
+    # - 분류는 원인이다. "어느 함수에서 났는가"가 아니라 "무엇이 잘못됐는가"다.
+    # - *_UNKNOWN 은 각 영역의 폴백 전용이다. "알 수 없는 X" 라는 뜻으로 쓰지 않는다.
+    # - 하위 원인은 버리지 않고 #cause 로 보존한다.
+    module ErrorCode
+      # TOKEN : DAT 토큰 문자열
+      TOKEN_MALFORMED = "DAT_TOKEN_MALFORMED"
+      TOKEN_EXPIRED   = "DAT_TOKEN_EXPIRED"
+      TOKEN_UNKNOWN   = "DAT_TOKEN_UNKNOWN"
+
+      # CERT : 인증서
+      CERT_MALFORMED        = "DAT_CERT_MALFORMED"
+      CERT_EXPIRED          = "DAT_CERT_EXPIRED"
+      CERT_NOT_YET_ISSUABLE = "DAT_CERT_NOT_YET_ISSUABLE"
+      CERT_ISSUANCE_ENDED   = "DAT_CERT_ISSUANCE_ENDED"
+      CERT_VERIFY_ONLY      = "DAT_CERT_VERIFY_ONLY"
+      CERT_NOT_FOUND        = "DAT_CERT_NOT_FOUND"
+      CERT_NOT_SYNCED       = "DAT_CERT_NOT_SYNCED"
+      CERT_DUPLICATE_CID    = "DAT_CERT_DUPLICATE_CID"
+      CERT_UNKNOWN          = "DAT_CERT_UNKNOWN"
+
+      # SIG : 서명
+      SIG_MISMATCH   = "DAT_SIG_MISMATCH"
+      SIG_MALFORMED  = "DAT_SIG_MALFORMED"
+      SIG_KEY_MISSING = "DAT_SIG_KEY_MISSING"
+      SIG_BACKEND    = "DAT_SIG_BACKEND"
+      SIG_UNKNOWN    = "DAT_SIG_UNKNOWN"
+
+      # CRYPTO : secure 페이로드
+      CRYPTO_TAG_MISMATCH = "DAT_CRYPTO_TAG_MISMATCH"
+      CRYPTO_DATA_INVALID = "DAT_CRYPTO_DATA_INVALID"
+      CRYPTO_BACKEND      = "DAT_CRYPTO_BACKEND"
+      CRYPTO_UNKNOWN      = "DAT_CRYPTO_UNKNOWN"
+
+      # KEY : 키 재료
+      KEY_INVALID                 = "DAT_KEY_INVALID"
+      KEY_VERIFY_ONLY_UNSUPPORTED = "DAT_KEY_VERIFY_ONLY_UNSUPPORTED"
+      KEY_UNKNOWN                 = "DAT_KEY_UNKNOWN"
+
+      # MANAGER : 매니저 보유 상태
+      MANAGER_NO_CERTIFICATE          = "DAT_MANAGER_NO_CERTIFICATE"
+      MANAGER_NO_ISSUABLE_CERTIFICATE = "DAT_MANAGER_NO_ISSUABLE_CERTIFICATE"
+      MANAGER_DISPOSED                = "DAT_MANAGER_DISPOSED"
+      MANAGER_UNKNOWN                 = "DAT_MANAGER_UNKNOWN"
+
+      # CMS : 서버 응답·전송
+      CMS_UNREACHABLE      = "DAT_CMS_UNREACHABLE"
+      CMS_UNAUTHORIZED     = "DAT_CMS_UNAUTHORIZED"
+      CMS_FORBIDDEN        = "DAT_CMS_FORBIDDEN"
+      CMS_ENDPOINT_NOT_FOUND = "DAT_CMS_ENDPOINT_NOT_FOUND"
+      CMS_SERVER_ERROR     = "DAT_CMS_SERVER_ERROR"
+      CMS_HTTP_STATUS      = "DAT_CMS_HTTP_STATUS"
+      CMS_MALFORMED        = "DAT_CMS_MALFORMED"
+      CMS_IMPORT_FAILED    = "DAT_CMS_IMPORT_FAILED"
+      CMS_VERSION_RESET    = "DAT_CMS_VERSION_RESET"
+      CMS_NOT_SYNCED       = "DAT_CMS_NOT_SYNCED"
+      CMS_SYNC_IN_PROGRESS = "DAT_CMS_SYNC_IN_PROGRESS"
+      CMS_NOT_SUPPORTED    = "DAT_CMS_NOT_SUPPORTED"
+      CMS_UNKNOWN          = "DAT_CMS_UNKNOWN"
+
+      # CONFIG : 호출자가 넘긴 값
+      CONFIG_ALG_UNSUPPORTED   = "DAT_CONFIG_ALG_UNSUPPORTED"
+      CONFIG_URI_INVALID       = "DAT_CONFIG_URI_INVALID"
+      CONFIG_ARGUMENT_INVALID  = "DAT_CONFIG_ARGUMENT_INVALID"
+      CONFIG_UNKNOWN           = "DAT_CONFIG_UNKNOWN"
+
+      # INTERNAL : 실행 환경
+      INTERNAL_UNAVAILABLE = "DAT_INTERNAL_UNAVAILABLE"
+      INTERNAL_UNKNOWN     = "DAT_INTERNAL_UNKNOWN"
+
+      # 재시도 분류. 애매하면 :permanent 다 — 영구 오류에 대한 무한 재시도가
+      # 이 체계 이전의 실제 결함이었다.
+      TRANSIENT = [
+        CERT_NOT_YET_ISSUABLE, CERT_NOT_SYNCED, MANAGER_NO_CERTIFICATE,
+        CMS_UNREACHABLE, CMS_SERVER_ERROR, CMS_NOT_SYNCED
+      ].freeze
+
+      STATE = [CMS_VERSION_RESET, CMS_SYNC_IN_PROGRESS].freeze
+
+      # 위조·변조 시도의 직접 증거.
+      SECURITY = [SIG_MISMATCH, CRYPTO_TAG_MISMATCH].freeze
+    end
+
+    # DAT 의 단일 오류 타입.
+    #
+    # 예전에는 정의만 되어 있고 아무도 쓰지 않았다. 대신 ArgumentError 와
+    # RuntimeError 가 같은 조건에 뒤섞여 던져져서(예: "Invalid DAT: Format" 이
+    # DatManager#parse 에서는 ArgumentError, DatManager._parse 에서는
+    # RuntimeError) 호출부가 어느 쪽을 잡아야 할지 알 수 없었다.
+    class Error < StandardError
+      # 공개 계약인 오류 코드. 모든 공식 클라이언트에서 동일하다.
+      attr_reader :code
+      # 사람이 읽는 설명. 자유롭게 바꿔도 된다.
+      attr_reader :detail
+
+      def initialize(code, detail = nil, cause: nil)
+        @code = code
+        @detail = detail
+        @explicit_cause = cause
+        super(detail ? "#{code}: #{detail}" : code)
+      end
+
+      # Ruby 는 rescue 안에서 raise 하면 #cause 를 자동으로 채운다. 그 동작은
+      # 그대로 두고, 명시적으로 넘긴 하위 원인이 있으면 그쪽을 우선한다.
+      # DAT_MANAGER_NO_ISSUABLE_CERTIFICATE 의 사유 코드가 이 경로로 실린다.
+      def cause
+        @explicit_cause || super
+      end
+
+      # :transient  - 같은 입력으로 재시도하면 해소될 수 있다. 백오프 후 재시도.
+      # :permanent  - 설정·입력·배포를 고쳐야 한다. 재시도하지 않는다.
+      # :state      - 오류가 아닌 상태 신호. 흐름 제어에만 쓴다.
+      #
+      # 중간값을 두지 않는다 — 호출부가 분기할 수 없기 때문이다.
+      def retry
+        if @code == ErrorCode::MANAGER_NO_ISSUABLE_CERTIFICATE
+          # 발급창 시작 전이면 기다리면 풀린다. 나머지 사유는 안 풀린다.
+          c = cause
+          return :transient if c.is_a?(Error) && c.code == ErrorCode::CERT_NOT_YET_ISSUABLE
+          return :permanent
+        end
+        return :transient if ErrorCode::TRANSIENT.include?(@code)
+        return :state if ErrorCode::STATE.include?(@code)
+        :permanent
+      end
+
+      # 위조·변조 시도의 직접 증거. 다른 실패와 같은 경로로 로깅하지 않는다.
+      def security_event?
+        ErrorCode::SECURITY.include?(@code)
+      end
+
+      def inspect
+        "#<Saro::Dat::Error #{@code}#{@detail ? " #{@detail.inspect}" : ''}>"
+      end
+
+      class << self
+        # 어떤 예외에서든 DAT 오류 코드를 꺼낸다. DAT 오류가 아니면 nil 이다.
+        def code_of(e)
+          e.is_a?(Error) ? e.code : nil
+        end
+
+        # DAT 오류가 아닌 것을 감싼다. 이미 Error 면 그대로 둔다.
+        # 원본은 cause 로 반드시 보존한다.
+        def wrap(code, detail, e)
+          return e if e.is_a?(Error)
+          new(code, detail, cause: e)
+        end
+      end
+    end
+  end
+end

data/lib/saro/dat/signature.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'openssl'
+require_relative 'error'
 require_relative 'util'
 
 module Saro
@@ -30,7 +31,7 @@ module Saro
     def self.get_signature_config(algorithm)
       config = SIGNATURE_CONFIG[algorithm]
       return config if config
-      raise ArgumentError, "Unsupported DAT Crypto Algorithm: #{algorithm}"
+      raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_ALG_UNSUPPORTED, "unknown signature algorithm: #{algorithm}")
     end
 
     class DatSignature
@@ -46,15 +47,34 @@ module Saro
       private_class_method def self.create_ec_key(curve_name, priv_bn = nil, pub_octet = nil)
         if priv_bn
           group = OpenSSL::PKey::EC::Group.new(curve_name)
+
+          # d must be in [1, n-1]; OpenSSL would otherwise happily build a key
+          # whose signatures can never verify.
+          if priv_bn <= 0 || priv_bn >= group.order
+            raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::KEY_INVALID, "ecdsa private scalar out of range [1, n-1]")
+          end
+
           pub_octet ||= group.generator.mul(priv_bn).to_octet_string(:uncompressed)
-          
+
           asn1 = OpenSSL::ASN1::Sequence.new([
             OpenSSL::ASN1::Integer.new(1),
             OpenSSL::ASN1::OctetString.new(priv_bn.to_s(2).rjust((group.degree + 7) / 8, "\x00".b)),
             OpenSSL::ASN1::ASN1Data.new([OpenSSL::ASN1::ObjectId.new(curve_name)], 0, :CONTEXT_SPECIFIC),
             OpenSSL::ASN1::ASN1Data.new([OpenSSL::ASN1::BitString.new(pub_octet)], 1, :CONTEXT_SPECIFIC)
           ])
-          OpenSSL::PKey::EC.new(asn1.to_der)
+          key = OpenSSL::PKey::EC.new(asn1.to_der)
+
+          # Cross-check that the imported public point really belongs to the
+          # private scalar. Without this a mismatched pair imports cleanly and
+          # produces signatures that can never verify (rust's
+          # EcdsaKeyPair::from_private_key_and_public_key rejects it at import).
+          begin
+            key.check_key
+          rescue OpenSSL::PKey::PKeyError, OpenSSL::PKey::ECError => e
+            raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::KEY_INVALID, "ecdsa key pair rejected: #{e.message}", cause: e)
+          end
+
+          key
         elsif pub_octet
           spki = OpenSSL::ASN1::Sequence.new([
             OpenSSL::ASN1::Sequence.new([
@@ -63,9 +83,15 @@ module Saro
             ]),
             OpenSSL::ASN1::BitString.new(pub_octet)
           ])
-          OpenSSL::PKey::EC.new(spki.to_der)
+          key = OpenSSL::PKey::EC.new(spki.to_der)
+          begin
+            key.check_key
+          rescue OpenSSL::PKey::PKeyError, OpenSSL::PKey::ECError => e
+            raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::KEY_INVALID, "ecdsa public key rejected: #{e.message}", cause: e)
+          end
+          key
         else
-          raise ArgumentError, "Either private key or public key must be provided"
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_ARGUMENT_INVALID, "either private key or public key must be provided")
         end
       end
 
@@ -76,6 +102,11 @@ module Saro
           new(algorithm, key, key, config)
         else
           key = OpenSSL::PKey::EC.generate(config[:curve])
+          begin
+            key.check_key
+          rescue OpenSSL::PKey::PKeyError, OpenSSL::PKey::ECError => e
+            raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::INTERNAL_UNKNOWN, "generated ecdsa key pair is invalid: #{e.message}", cause: e)
+          end
           new(algorithm, key, key, config)
         end
       end
@@ -86,7 +117,7 @@ module Saro
 
         if config[:name] == "HMAC"
           if bytes_data.bytesize != config[:hmac_len]
-            raise ArgumentError, "Invalid HMAC key length: expected #{config[:hmac_len]}, got #{bytes_data.bytesize}"
+            raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::KEY_INVALID, "hmac key must be #{config[:hmac_len]} bytes, got #{bytes_data.bytesize}")
           end
           new(algorithm, bytes_data, bytes_data, config)
         else
@@ -106,7 +137,7 @@ module Saro
           elsif bytes_data.bytesize == public_len
             verifying_key = create_ec_key(config[:curve], nil, bytes_data)
           else
-            raise ArgumentError, "Invalid ECDSA key length"
+            raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::KEY_INVALID, "ecdsa key length matches neither private+public nor public")
           end
 
           new(algorithm, signing_key, verifying_key, config)
@@ -115,7 +146,7 @@ module Saro
 
       def exports(verify_only = false)
         if verify_only && !support_verify_only
-          raise ArgumentError, "#{config[:name]} does not supported verifying only key"
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::KEY_VERIFY_ONLY_UNSUPPORTED, @algorithm.to_s)
         end
 
         if @config[:name] == "HMAC"
@@ -136,9 +167,9 @@ module Saro
       end
 
       def sign(body)
-        raise ArgumentError, "Signature key is not supported - verifying only key" unless @signing_key
+        raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::SIG_KEY_MISSING, "this key is verify-only") unless @signing_key
         body = normalize_body(body)
-        raise ArgumentError, "Sign Error - body is empty" if body.nil? || body.empty?
+        raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_ARGUMENT_INVALID, "body to sign is empty") if body.nil? || body.empty?
 
         if @config[:name] == "HMAC"
           OpenSSL::HMAC.digest(@config[:hash], @signing_key, body)
@@ -148,30 +179,58 @@ module Saro
         end
       end
 
+      # Verifies a raw (already decoded) signature.
+      # Use #verify_base64 for a base64url-encoded signature: the branch used to
+      # be picked from the string's encoding tag, so a raw signature that merely
+      # carried a UTF-8 tag was silently run through the base64 decoder.
       def verify(body, signature)
+        verify_bytes(body, signature)
+      end
+
+      # Verifies a base64url-encoded signature.
+      def verify_base64(body, signature_base64)
+        sig_bytes = begin
+          Saro::Dat::Util.decode_base64_url(signature_base64)
+        rescue Saro::Dat::Error => e
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::SIG_MALFORMED, "signature is not base64url", cause: e)
+        end
+        verify_bytes(body, sig_bytes)
+      end
+
+      private def verify_bytes(body, sig_bytes)
         body = normalize_body(body)
         return false if body.nil? || body.empty?
 
-        sig_bytes = if signature.is_a?(String) && signature.encoding != Encoding::BINARY
-                      Saro::Dat::Util.decode_base64_url(signature)
-                    else
-                      signature
-                    end
+        # Same reason as DatCrypto#decrypt: the raw signature is split in half by
+        # byte offset, which String#[] only honours on a binary string.
+        sig_bytes = sig_bytes.b if sig_bytes.is_a?(String) && sig_bytes.encoding != Encoding::BINARY
 
+        # false 는 "서명이 안 맞는다"만 뜻한다. 예전에는 `rescue StandardError => false`
+        # 가 잘못된 키 타입·손상된 핸들·라이브러리 버그까지 전부 삼켜서 프로그래밍
+        # 오류가 위조 시도로 보고됐다. 그래서 연산 실패는 SIG_BACKEND 로 갈라 낸다.
         if @config[:name] == "HMAC"
           begin
             actual_sig = OpenSSL::HMAC.digest(@config[:hash], @verifying_key, body)
-            # Use fixed-time comparison if possible
-            return actual_sig == sig_bytes
-          rescue StandardError
-            return false
+          rescue StandardError => e
+            raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::SIG_BACKEND, "hmac computation failed", cause: e)
           end
+          # 길이가 다르면 볼 것도 없이 불일치다.
+          return false unless sig_bytes.is_a?(String) && actual_sig.bytesize == sig_bytes.bytesize
+          OpenSSL.fixed_length_secure_compare(actual_sig, sig_bytes)
         else
+          der_sig = begin
+            raw_to_der_signature(sig_bytes)
+          rescue StandardError
+            # r||s 길이가 곡선과 안 맞는다 = 서명 자체의 형식 오류. 위조가 아니다.
+            raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::SIG_MALFORMED, "ecdsa signature is not a valid r||s pair")
+          end
           begin
-            der_sig = raw_to_der_signature(sig_bytes)
             @verifying_key.dsa_verify_asn1(OpenSSL::Digest.digest(@config[:hash], body), der_sig)
-          rescue StandardError
+          rescue OpenSSL::PKey::PKeyError, OpenSSL::PKey::ECError
+            # OpenSSL 이 서명을 해독조차 못 한 경우다. 불일치로 본다.
             false
+          rescue StandardError => e
+            raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::SIG_BACKEND, "ecdsa verification failed to run", cause: e)
           end
         end
       end

data/lib/saro/dat/util.rb

@@ -1,12 +1,44 @@
 # frozen_string_literal: true
 
 require 'base64'
+require_relative 'error'
 
 module Saro
   module Dat
     module Util
       module_function
 
+      U64_MAX = 0xFFFFFFFFFFFFFFFF
+
+      # Strict unsigned 64-bit decimal parse, matching rust's `parse::<u64>()`.
+      # Ruby's String#to_i never raises and Integer() accepts `0x`, `_` and
+      # surrounding whitespace, so the character set is checked explicitly.
+      # 무엇을 파싱하다 실패했는지에 따라 코드가 갈린다(토큰이면 TOKEN_MALFORMED,
+      # 인증서면 CERT_MALFORMED). 여기서는 중립적인 인자 오류로 두고, 각 호출부에서
+      # 정확한 코드로 감싼다.
+      def parse_u64(s)
+        unless s.is_a?(String) && s.match?(/\A[0-9]+\z/)
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_ARGUMENT_INVALID, "not an unsigned decimal integer: #{s.inspect}")
+        end
+        v = s.to_i
+        if v > U64_MAX
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_ARGUMENT_INVALID, "exceeds u64: #{s.inspect}")
+        end
+        v
+      end
+
+      # Strict unsigned 64-bit hex parse, matching rust's `u64::from_str_radix(s, 16)`.
+      def parse_u64_hex(s)
+        unless s.is_a?(String) && s.match?(/\A[0-9a-fA-F]+\z/)
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_ARGUMENT_INVALID, "not an unsigned hex integer: #{s.inspect}")
+        end
+        v = s.to_i(16)
+        if v > U64_MAX
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_ARGUMENT_INVALID, "exceeds u64: #{s.inspect}")
+        end
+        v
+      end
+
       def encode_base64_url(s)
         return "".b if s.nil?
         if s.is_a?(String)
@@ -27,12 +59,18 @@ module Saro
           return "".b if s.empty?
         end
         
-        # More robust way for older Ruby
-        s = s.to_s.tr('-_', '+/')
+        # Base64.decode64 is RFC 2045 and silently drops invalid characters, so
+        # "!!!!invalid@@@@" would decode to arbitrary bytes instead of raising.
+        # urlsafe_decode64 is strict, matching rust's decoder.
+        s = s.to_s
         rem = s.bytesize % 4
         s += ("=" * (4 - rem)) if rem > 0
 
-        Base64.decode64(s).b
+        begin
+          Base64.urlsafe_decode64(s).b
+        rescue ArgumentError => e
+          raise Saro::Dat::Error.new(Saro::Dat::ErrorCode::CONFIG_ARGUMENT_INVALID, "not a valid base64url string", cause: e)
+        end
       end
 
       def decode_base64_url_str(s)

data/lib/saro-dat.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Error 는 다른 모든 파일이 참조하므로 가장 먼저 로드한다.
+require_relative 'saro/dat/error'
 require_relative 'saro/dat/util'
 require_relative 'saro/dat/crypto'
 require_relative 'saro/dat/signature'
@@ -7,9 +9,3 @@ require_relative 'saro/dat/dat_certificate'
 require_relative 'saro/dat/dat'
 require_relative 'saro/dat/dat_manager'
 require_relative 'saro/dat/dat_cms_manager'
-
-module Saro
-  module Dat
-    class Error < StandardError; end
-  end
-end

data/saro-dat.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "saro-dat"
-  spec.version       = "4.3.4"
+  spec.version       = "4.6.0"
   spec.authors       = ["marker"]
   spec.email         = ["j@saro.me"]
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: saro-dat
 version: !ruby/object:Gem::Version
-  version: 4.3.4
+  version: 4.6.0
 platform: ruby
 authors:
 - marker
@@ -116,6 +116,7 @@ files:
 - lib/saro/dat/dat_certificate.rb
 - lib/saro/dat/dat_cms_manager.rb
 - lib/saro/dat/dat_manager.rb
+- lib/saro/dat/error.rb
 - lib/saro/dat/signature.rb
 - lib/saro/dat/util.rb
 - saro-dat.gemspec