skaidb 1.0.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5792e9877643c116649c834851fc097027b72fd01ab0f40920dd4e99d977a0d
-  data.tar.gz: 6d035367f1b2f97b6f49306ef5ff6b77974a2825e73356740d66237e2577a1d1
+  metadata.gz: 4524df0a2c1434d82de3ae0e2202e408ce54a9ea2a0b2f892247e6623b739e3c
+  data.tar.gz: 0c1431641d973133fce8fb4e5fb965c7fbf3730a239250f1b3773cbcf1c5da51
 SHA512:
-  metadata.gz: e2aec63bcdd3ef8d199d223c7de91343370dceaea32fd626b1cb085606d533c613909d3653e60a662e1874f0293ebc9c6c3633f931d39f1ea569970668867e63
-  data.tar.gz: 3b4e1accd06da21f72da0148e3340bee4eeb1dbe3fbc98c51ce9b0d9891b6075a653c6386258582cadf8b3d49de8f596713e562213bd29c471c78c18865946e5
+  metadata.gz: f4f4b9390ed85e9504f325b14b8ae1a9f8f4b54edfd9622e2bc514b0d47b208e763f46887016388ffc6db20625e14ea6a9dda26e5d53daa6fa86f5addbd6b992
+  data.tar.gz: 8afeaab18359327ad49ff27d07227068e6243b1c2ae4df6da6ed0ee44d87233cebb12d00601c0f930fdbe715f0fbe467ba2034bb70f92e8880fa44dbc7ebe3dd

data/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to the skaidb Ruby driver. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [1.1.0] - 2026-09-26
+
+### Added
+- Certificate login (wire mechanism EXTERNAL): `auth_mechanism: :certificate`
+  with `tls_client_cert:` / `tls_client_key:` (PEM files). AuthStart carries
+  the optional user, an empty client nonce and mechanism byte 2; the
+  outcome's signature is not verified, since TLS authenticated the server.
+  `user:` is optional under it and, when given, must equal the certificate's
+  Common Name. `Skaidb::AuthMechanism` resolves the option.
+- `tls_client_cert:` / `tls_client_key:` also present a client certificate
+  under SCRAM, for servers that verify client certificates; either turns TLS
+  on, and they must be given together.
+- The shared wire-protocol conformance suite: `conformance/vectors.json` and
+  its contract, vendored byte-identical, run by `test/conformance_test.rb`
+  (values, SCRAM, auth outcomes, every case through the public API; nothing
+  skipped). CI fails when the vendored vectors differ from
+  https://skaidb.org/conformance/vectors.json.
+- `Result#kind` (`:rows`, `:mutation`, `:ddl`, `:stream`): a DDL
+  acknowledgement was indistinguishable from "0 rows affected".
+- `Skaidb.salted_password` and `Skaidb.auth_message`, the SCRAM pieces the
+  handshake uses, so they can be checked against the reference vectors.
+
+### Changed
+- `Connection#stream` with a block returns a `Result` instead of `nil`. Found
+  by the conformance suite: a stream with no rows had no way to report its
+  column names, and a non-row statement sent over the streaming opcode
+  dropped its affected-row count. A row stream now returns `kind: :stream`
+  with the column names in `fields`; a non-row statement returns its
+  `:mutation` (with `cmd_tuples`) or `:ddl` Result.
+- `Skaidb.connect`'s `user:` defaults to `nil`, which still means
+  `"anonymous"` under SCRAM and an empty user under certificate login.
+
 ## [1.0.3] - 2026-09-20
 
 Release automation: published from GitHub Actions. No code change.

data/README.md

@@ -54,13 +54,13 @@ Xcode command-line tools on macOS). `gem install skaidb` and vendoring reuse
 the `bigdecimal` already installed.
 
 Or vendor the single file: copy
-[`lib/skaidb.rb`](https://github.com/porcupin26/skaidb-ruby/blob/v1.0.3/lib/skaidb.rb)
+[`lib/skaidb.rb`](https://github.com/porcupin26/skaidb-ruby/blob/v1.1.0/lib/skaidb.rb)
 into your project and `require_relative` it. It has no dependencies beyond
 Ruby's standard library.
 
 Every release is also attached as a `.gem` to its
 [GitHub release](https://github.com/porcupin26/skaidb-ruby/releases) for
-installs without registry access: `gem install ./skaidb-1.0.3.gem`.
+installs without registry access: `gem install ./skaidb-1.1.0.gem`.
 
 ## Quick start
 
@@ -117,7 +117,9 @@ Skaidb.connect(
   timeout: 10.0,               # TCP connect timeout in seconds; nil = none
   database: nil,               # run USE <database> as part of connecting
   seeds: nil,                  # ["db1", "db2:7000", …] tried in random order
-  tls: false, tls_ca: nil, tls_insecure: false, tls_server_name: "skaidb"
+  tls: false, tls_ca: nil, tls_insecure: false, tls_server_name: "skaidb",
+  tls_client_cert: nil, tls_client_key: nil,   # PEM files: present a client certificate
+  auth_mechanism: :scram       # or :certificate: the client certificate is the login
 ) # => Skaidb::Connection (or the block's value when a block is given)
 ```
 
@@ -163,8 +165,19 @@ conn = Skaidb.connect(host: "db1", tls_insecure: true)            # dev only: no
 
 Any of the three enables TLS. The server name sent as SNI and checked against
 the certificate is `tls_server_name` (default `"skaidb"`, the SAN skaidb's own
-certificates carry). SCRAM runs inside the TLS session. The driver does not
-present a client certificate. Details: [docs/tls.md](https://github.com/porcupin26/skaidb-ruby/blob/main/docs/tls.md).
+certificates carry). SCRAM runs inside the TLS session.
+
+`tls_client_cert:` / `tls_client_key:` present a client certificate; with
+`auth_mechanism: :certificate` that certificate is the login (its Common Name
+is the user, no password is sent):
+
+```ruby
+conn = Skaidb.connect(host: "db1", tls_ca: "/etc/skaidb/ca.crt",
+                      tls_client_cert: "app.crt", tls_client_key: "app.key",
+                      auth_mechanism: :certificate)
+```
+
+Details: [docs/tls.md](https://github.com/porcupin26/skaidb-ruby/blob/main/docs/tls.md).
 
 ### Consistency
 
@@ -255,6 +268,8 @@ shaped like `PG::Result`:
   cell by index or column name.
 - `cmd_tuples`: rows affected by `INSERT`/`UPDATE`/`DELETE`; `0` for a
   `SELECT` and for DDL.
+- `kind`: `:rows`, `:mutation` (a count in `cmd_tuples`) or `:ddl` (a bare
+  acknowledgement), which tells "DDL succeeded" from "0 rows affected".
 - `result_sets`: for a `CALL` whose procedure `EMIT`s several result sets,
   every set in order (each a `Result`); the last set is the result's own
   `rows`/`fields`. Empty for an ordinary reply.
@@ -274,8 +289,10 @@ end
 first = conn.stream("SELECT id FROM big ORDER BY id").first(10)   # Enumerator form
 ```
 
-`stream` takes SQL text only (no parameters). A non-row statement returns
-`nil` without yielding.
+`stream` takes SQL text only (no parameters). With a block it returns a
+`Result` whose `kind` is `:stream` and whose `fields` are the column names
+(the rows went to the block); a non-row statement returns its `:mutation` /
+`:ddl` Result without yielding.
 
 **The abandon/drain rule.** The connection is busy for the whole stream:
 a statement from another thread waits for it. Leaving the block early —
@@ -404,7 +421,7 @@ frame after every handshake. It shows up as `client_name = 'ruby'` /
 
 ```sql
 SELECT client_name, client_version FROM drivers;
--- ruby | 1.0.3
+-- ruby | 1.1.0
 ```
 
 The server records the row asynchronously, so a `SELECT` immediately after
@@ -424,6 +441,30 @@ know the opcode answers with an error the driver ignores.
   binary protocol on port 7000; the server's REST/JSON gateway (port 7080)
   is a dependency-free alternative for other clients.
 
+## Conformance
+
+`test/conformance_test.rb` runs skaidb's shared wire-protocol conformance
+suite, vendored byte-identical from the server repository in
+[`conformance/`](https://github.com/porcupin26/skaidb-ruby/tree/main/conformance)
+(`vectors.json` plus the contract in its `README.md`), as part of `rake test`:
+
+- every value vector decodes to the expected Ruby value and encodes back to
+  the reference bytes (a Uuid cell is compared as its canonical String, the
+  form the driver returns);
+- every SCRAM vector (auth message, salted password, client proof, server
+  signature) through the driver's own SCRAM code;
+- the auth outcomes against a fake server that verifies the client proof
+  independently: `ok` connects, a server signature that does not verify
+  fails the connect, `denied` fails with the server's reason;
+- every case through the public API (`exec`, `stream`, `exec_params`,
+  `exec_batch`, and sequences of them on one connection), checking the exact
+  request bytes and the decoded result. The vectors' `?` placeholders are
+  passed as this driver's `$1`, `$2`, ….
+
+Nothing is skipped: the test prints `skipped call methods: none`. CI also
+fails when the vendored `vectors.json` differs from the published
+<https://skaidb.org/conformance/vectors.json>.
+
 ## Examples
 
 [`examples/`](https://github.com/porcupin26/skaidb-ruby/tree/main/examples)

data/docs/api.md

@@ -8,7 +8,7 @@ Everything lives under the `Skaidb` module in `lib/skaidb.rb`.
 |---|---|---|
 | `host` | `"localhost"` | Node to dial (ignored when `seeds` is given). |
 | `port` | `7000` | Binary-protocol port; also the port for a seed without one. |
-| `user` | `"anonymous"` | SCRAM user name. |
+| `user` | `"anonymous"` (SCRAM), `""` (certificate) | User name. Under `auth_mechanism: :certificate` it is optional and, when given, must equal the certificate's Common Name. |
 | `password` | `""` | SCRAM password. Empty skips server-signature verification (anonymous connect). |
 | `consistency` | `:quorum` | Default level for every statement: `:one`, `:quorum`, `:all`, `"ONE"`…, or `0`/`1`/`2`. |
 | `timeout` | `10.0` | TCP connect timeout in seconds; `nil` for none. Reads are not bounded. |
@@ -18,12 +18,18 @@ Everything lives under the `Skaidb` module in `lib/skaidb.rb`.
 | `tls_ca` | `nil` | PEM file to trust instead of the system store; implies `tls`. |
 | `tls_insecure` | `false` | TLS without any certificate verification; implies `tls`. Development only. |
 | `tls_server_name` | `"skaidb"` | SNI name, also checked against the certificate's SANs. |
+| `tls_client_cert` | `nil` | PEM file of a client certificate to present in the TLS handshake; implies `tls`. Needs `tls_client_key`. |
+| `tls_client_key` | `nil` | PEM file of that certificate's private key. |
+| `auth_mechanism` | `:scram` | `:scram` (user + password) or `:certificate` (the client certificate is the login, wire mechanism EXTERNAL; needs `tls_client_cert`/`tls_client_key`). Strings and the aliases `"password"`, `"external"`, `"x509"` are accepted. |
 
 With a block, yields the connection and closes it when the block returns
 (the block's value is returned). Raises `Skaidb::ConnectionError` when no
 endpoint accepts the handshake (`no reachable endpoint in …: <last error>`),
 `authentication denied: …` on a wrong password, and
 `server signature mismatch` when the server fails mutual authentication.
+Raises `Skaidb::Error` before dialing for an unknown `auth_mechanism`, a
+`tls_client_cert` without its `tls_client_key` (or the reverse), and
+`:certificate` without a client certificate.
 
 ## `Skaidb::Connection`
 
@@ -49,8 +55,11 @@ endpoint accepts the handshake (`no reachable endpoint in …: <last error>`),
 - `prepare_server(sql) → [id, nparams] | nil` — prepare a statement with `?`
   placeholders on the server; `nil` when the server refuses. Cached per
   connection (240 entries); the cache is cleared on re-dial.
-- `stream(sql, consistency: nil) { |row| … } → nil` — see
-  [streaming.md](streaming.md). Without a block returns an Enumerator.
+- `stream(sql, consistency: nil) { |row| … } → Result` — see
+  [streaming.md](streaming.md). For a row stream the returned Result has
+  `kind == :stream`, the column names in `fields` and no `rows` (they went to
+  the block); a statement without rows returns its `:mutation` / `:ddl`
+  Result without yielding. Without a block returns an Enumerator.
 - `subscribe(stream_name, after: nil, poll: 0.5) { |event| … }` — yields a
   `CREATE STREAM` log's events forever, each a Hash with `"id"`, `"op"`,
   `"k"`, `"ts"`, `"doc"`. Polls `_stream_<name>` 500 rows at a time with a
@@ -91,6 +100,7 @@ Shaped like `PG::Result`; `Enumerable` over row Hashes.
 | `[i]` | Row `i` as a Hash, or `nil`. |
 | `getvalue(row, col)` | One cell; `col` is an index or a column name. |
 | `cmd_tuples` | Rows affected by `INSERT`/`UPDATE`/`DELETE`; `0` for `SELECT` and DDL. |
+| `kind` | What the server answered: `:rows` (a result set, or several in `result_sets`), `:mutation` (a count in `cmd_tuples`), `:ddl` (a bare acknowledgement — no rows and no count), `:stream` (the summary `stream` returns). |
 | `result_sets` | For a `CALL` whose body `EMIT`s, every result set in order (each a `Result`); the last one is this result's own `rows`/`fields`. `[]` otherwise. |
 
 ## `Skaidb::Pool`

data/docs/streaming.md

@@ -13,11 +13,14 @@ end
 ```
 
 - `stream(sql, consistency: nil)` takes SQL text only — no parameters.
-- With a block it returns `nil` after the last row.
+- With a block it returns a `Skaidb::Result` after the last row: `kind` is
+  `:stream`, `fields` holds the column names (known even when no row
+  arrived), and `rows` is empty because the rows went to the block.
 - Without a block it returns an Enumerator: `conn.stream(sql).first(10)`,
   `.each_slice(1000)`, `.lazy.map { … }`, and the rest of Enumerable work.
 - A non-row statement (an `INSERT`, DDL, `USE`) answers with its ordinary
-  result over the same opcode; `stream` returns `nil` without yielding.
+  result over the same opcode; `stream` returns that Result (`kind`
+  `:mutation` with `cmd_tuples`, or `:ddl`) without yielding.
 - A server without the streaming opcode raises `Skaidb::QueryError`
   (`server does not support streaming: …`).
 

data/docs/tls.md

@@ -42,16 +42,44 @@ OpenSSL's message.
 
 ## What runs inside the session
 
-The TCP connection is upgraded to TLS *before* the SCRAM handshake, so the
+The TCP connection is upgraded to TLS *before* the login handshake, so the
 user name, nonces and proof all travel encrypted; with `seeds:`, each
-endpoint is upgraded and authenticated in turn until one succeeds. The
-driver does not present a client certificate; authentication is SCRAM.
+endpoint is upgraded and authenticated in turn until one succeeds.
+
+## Client certificates
+
+`tls_client_cert:` / `tls_client_key:` (PEM files) make the driver present a
+client certificate in the TLS handshake, which a server with
+`client_tls = "required"` and client verification needs. Either one turns TLS
+on, and they go together. On its own the certificate only opens the TLS
+session; the login is still the SCRAM user.
+
+With `auth_mechanism: :certificate` the certificate IS the login (wire
+mechanism EXTERNAL): the server maps its Common Name to a role and no
+password is sent. The server needs `auth.x509_enabled`, and its client CA
+must have signed the certificate.
+
+```ruby
+conn = Skaidb.connect(host: "db1", tls_ca: "/etc/skaidb/ca.crt",
+                      tls_client_cert: "/etc/app/app.crt",
+                      tls_client_key: "/etc/app/app.key",
+                      auth_mechanism: :certificate, database: "app")
+```
+
+Pass `user:` only to assert the expected identity: a certificate mapped to a
+different role fails the connect. The server's answer carries no signature
+to check — TLS already authenticated the server, so keep `tls_ca:` (or the
+system store) and do not combine a certificate login with `tls_insecure`.
+`Skaidb::Pool` passes these keywords through like the others.
 
 ## Failures
 
 - Wrong CA, expired certificate, name mismatch: `Skaidb::ConnectionError`
   with the OpenSSL message, from `connect` (or from the statement that
   triggered a re-dial).
+- A certificate login the server refuses (no role for the CN, `user:` not
+  matching it, x509 login disabled): `Skaidb::ConnectionError` with
+  `authentication denied: <reason>`.
 - Plain TCP against a `client_tls = required` server: the handshake cannot
   complete, so `connect` raises `Skaidb::ConnectionError`
   (`no reachable endpoint in …`) naming the underlying failure.

data/lib/skaidb.rb

@@ -34,7 +34,7 @@ require "bigdecimal"
 module Skaidb
   # The package version — the single source of truth. The gemspec reads it,
   # and it is what the driver reports to the server in the Hello frame.
-  VERSION = "1.0.3"
+  VERSION = "1.1.0"
 
   # Base class for every error raised by this driver.
   class Error < StandardError; end
@@ -73,6 +73,29 @@ module Skaidb
     end
   end
 
+  # Login mechanisms (the optional last byte of AuthStart, PROTOCOL.md §2.4).
+  module AuthMechanism
+    # SCRAM-SHA-256 with +user+ / +password+ (the default).
+    SCRAM = :scram
+    # EXTERNAL: the TLS client certificate is the credential.
+    CERTIFICATE = :certificate
+
+    WIRE = { SCRAM => 0, CERTIFICATE => 2 }.freeze
+    ALIASES = {
+      "scram" => SCRAM, "password" => SCRAM,
+      "certificate" => CERTIFICATE, "external" => CERTIFICATE, "x509" => CERTIFICATE
+    }.freeze
+
+    # Resolve +:scram+ / +:certificate+ (or a String, or an alias:
+    # "password", "external", "x509") into +:scram+ or +:certificate+.
+    def self.resolve(value)
+      m = ALIASES[value.to_s.downcase] if value.is_a?(String) || value.is_a?(Symbol)
+      return m if m
+
+      raise Error, "unknown auth_mechanism #{value.inspect} (use :scram or :certificate)"
+    end
+  end
+
   # Value type tags (§4 of PROTOCOL.md).
   module Tags
     NULL = 0
@@ -490,12 +513,25 @@ module Skaidb
 
   # ---- SCRAM-SHA-256 (§2) --------------------------------------------------
 
+  # The SaltedPassword: PBKDF2-HMAC-SHA-256 of the UTF-8 password, 32 bytes.
+  def self.salted_password(password, salt, iterations)
+    OpenSSL::KDF.pbkdf2_hmac(
+      password.to_s.dup.force_encoding("UTF-8"), salt: salt, iterations: iterations, length: 32, hash: "sha256"
+    )
+  end
+
+  # The AuthMessage both sides sign: username, client nonce, server nonce,
+  # lowercase-hex salt and decimal iteration count, joined with NUL bytes.
+  def self.auth_message(username, client_nonce, server_nonce, salt, iterations)
+    [username, client_nonce, server_nonce, salt.unpack1("H*"), iterations.to_s]
+      .map { |part| part.to_s.dup.force_encoding("UTF-8") }
+      .join("\0")
+  end
+
   # Compute the client proof and the expected server signature.
   def self.scram(password, salt, iterations, auth_message)
     digest = OpenSSL::Digest::SHA256
-    salted = OpenSSL::KDF.pbkdf2_hmac(
-      password, salt: salt, iterations: iterations, length: 32, hash: "sha256"
-    )
+    salted = salted_password(password, salt, iterations)
     client_key = OpenSSL::HMAC.digest(digest.new, salted, "Client Key")
     stored_key = OpenSSL::Digest::SHA256.digest(client_key)
     client_sig = OpenSSL::HMAC.digest(digest.new, stored_key, auth_message)
@@ -525,6 +561,23 @@ module Skaidb
     [bytes].pack("V") + b.b
   end
 
+  # AuthStart for the certificate login (mechanism EXTERNAL): username (may
+  # be empty), an empty client nonce, mechanism byte 2.
+  def self.certificate_auth_start(user)
+    [10].pack("C") + enc_str(user) + enc_str("") + [AuthMechanism::WIRE[AuthMechanism::CERTIFICATE]].pack("C")
+  end
+
+  # Check the AuthOutcome that answers a certificate AuthStart: returns on
+  # Ok (the signature is deliberately not checked), raises ConnectionError
+  # with the server's reason on Denied.
+  def self.parse_certificate_outcome(payload)
+    r = Reader.new(payload)
+    raise ConnectionError, "bad handshake outcome" unless r.u8 == 13
+    raise ConnectionError, "authentication denied: #{r.text}" unless r.u8 == 1
+
+    nil
+  end
+
   # ---- Result --------------------------------------------------------------
 
   # A query result, shaped like +PG::Result+. Enumerable over row Hashes
@@ -543,8 +596,15 @@ module Skaidb
     #   whose body EMITted), in order; this Result is the LAST of them.
     #   Empty for an ordinary single-set reply.
     attr_reader :result_sets
-
-    def initialize(fields:, rows:, cmd_tuples: 0, result_sets: [])
+    # @return [Symbol] what the server answered: +:rows+ (a result set, or
+    #   several — see +result_sets+), +:mutation+ (an affected-row count in
+    #   +cmd_tuples+), +:ddl+ (a bare acknowledgement: no rows, no count), or
+    #   +:stream+ (returned by Connection#stream once every row was yielded:
+    #   +fields+ holds the column names, +rows+ is empty).
+    attr_reader :kind
+
+    def initialize(fields:, rows:, cmd_tuples: 0, result_sets: [], kind: :rows)
+      @kind = kind
       @result_sets = result_sets
       @fields = fields
       @rows = rows
@@ -620,8 +680,17 @@ module Skaidb
 
     def initialize(host:, port:, user:, password:, consistency:, timeout:,
                    database: nil, tls: false, tls_ca: nil, tls_insecure: false,
-                   tls_server_name: "skaidb", seeds: nil)
+                   tls_server_name: "skaidb", seeds: nil, tls_client_cert: nil,
+                   tls_client_key: nil, auth_mechanism: :scram)
       @consistency = Consistency.resolve(consistency)
+      @auth_mechanism = AuthMechanism.resolve(auth_mechanism)
+      if tls_client_cert.to_s.empty? != tls_client_key.to_s.empty?
+        raise Error, "tls_client_cert and tls_client_key go together"
+      end
+      if @auth_mechanism == AuthMechanism::CERTIFICATE && (!tls || tls_client_cert.to_s.empty?)
+        raise Error, "certificate authentication needs TLS with a client certificate " \
+                     "(tls_client_cert: and tls_client_key:)"
+      end
       @mutex = Mutex.new
       @closed = false
       # Transport died; the next statement re-dials (see ensure_live!).
@@ -634,7 +703,8 @@ module Skaidb
       @dial_args = { host: host, port: port, user: user, password: password,
                      timeout: timeout, database: database, tls: tls, tls_ca: tls_ca,
                      tls_insecure: tls_insecure, tls_server_name: tls_server_name,
-                     seeds: seeds }
+                     seeds: seeds, tls_client_cert: tls_client_cert,
+                     tls_client_key: tls_client_key }
       dial!
     end
 
@@ -666,8 +736,15 @@ module Skaidb
         begin
           @sock = Socket.tcp(h, prt, connect_timeout: timeout)
           @sock.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
-          @sock = tls_wrap(@sock, tls_ca, tls_insecure, tls_server_name) if tls
-          handshake(user.to_s, password.to_s)
+          if tls
+            @sock = tls_wrap(@sock, tls_ca, tls_insecure, tls_server_name,
+                             @dial_args[:tls_client_cert], @dial_args[:tls_client_key])
+          end
+          if @auth_mechanism == AuthMechanism::CERTIFICATE
+            handshake_certificate(user.to_s)
+          else
+            handshake(user.to_s, password.to_s)
+          end
           last = nil
           break
         rescue StandardError => e
@@ -710,8 +787,16 @@ module Skaidb
     # unreachable. +tls_server_name+ must match a SAN on the server
     # certificate — skaidb's own certs carry DNS:skaidb, which is usually NOT
     # the address dialled.
-    def tls_wrap(sock, ca_file, insecure, server_name)
+    #
+    # +client_cert+ / +client_key+ (PEM files) present a client certificate in
+    # the TLS handshake: the credential of the certificate login, and what a
+    # server that verifies client certificates asks for.
+    def tls_wrap(sock, ca_file, insecure, server_name, client_cert = nil, client_key = nil)
       ctx = OpenSSL::SSL::SSLContext.new
+      if client_cert && !client_cert.to_s.empty?
+        ctx.cert = OpenSSL::X509::Certificate.new(File.read(client_cert))
+        ctx.key = OpenSSL::PKey.read(File.read(client_key))
+      end
       if insecure
         # Encrypts, but authenticates nothing: a man in the middle can present
         # any certificate. Development only.
@@ -845,6 +930,12 @@ module Skaidb
     # the whole stream), which is what keeps it out of the pool. Iterate with
     # a block or +each+ if you mean to reuse the connection.
     #
+    # With a block it returns a Result once the stream ends: for a row stream
+    # +kind+ is +:stream+ and +fields+ holds the column names (known even when
+    # no row arrived) while +rows+ stays empty — the rows went to the block;
+    # a statement that produces no rows returns its ordinary +:mutation+ or
+    # +:ddl+ Result without yielding.
+    #
     # Takes no parameters — the streaming opcode carries SQL text.
     def stream(sql, consistency: nil)
       return enum_for(:stream, sql, consistency: consistency) unless block_given?
@@ -855,6 +946,7 @@ module Skaidb
       sql_bytes = sql.dup.force_encoding("UTF-8").b
       req = [5, level].pack("CC") + [sql_bytes.bytesize].pack("V") + sql_bytes
       live = false
+      summary = nil
       @mutex.synchronize do
         write_frame(req)
         r = Reader.new(read_frame)
@@ -863,8 +955,10 @@ module Skaidb
         when 3
           msg = r.text
           raise QueryError, msg.include?("unknown opcode") ? "server does not support streaming: #{msg}" : msg
-        when 1, 2
-          return nil # not row-producing
+        when 1
+          return Result.new(fields: [], rows: [], cmd_tuples: r.u64, kind: :mutation) # not row-producing
+        when 2
+          return Result.new(fields: [], rows: [], cmd_tuples: 0, kind: :ddl)
         when 5
           # The server has already committed to a row stream, so from here
           # the socket carries frames this call owns — mark it BEFORE
@@ -879,6 +973,7 @@ module Skaidb
           live = true
           @streaming = true
           cols = Array.new(r.u32) { r.text }
+          summary = Result.new(fields: cols, rows: [], cmd_tuples: 0, kind: :stream)
           begin
             while live
               fr = Reader.new(read_frame)
@@ -914,7 +1009,7 @@ module Skaidb
           raise QueryError, "unexpected response tag #{tag} to stream request"
         end
       end
-      nil
+      summary
     end
 
     # Prepare +sql+ on the SERVER, returning [id, nparams], or nil when the
@@ -1143,9 +1238,7 @@ module Skaidb
       iterations = r.u32
       server_nonce = r.text
 
-      salt_hex = salt.unpack1("H*") # lowercase hex
-      auth_message = [user, client_nonce, server_nonce, salt_hex, iterations.to_s]
-                     .join("\0").dup.force_encoding("UTF-8")
+      auth_message = Skaidb.auth_message(user, client_nonce, server_nonce, salt, iterations)
       proof, expected_sig = Skaidb.scram(password, salt, iterations, auth_message)
 
       write_frame([12].pack("C") + proof) # 32 raw bytes, not length-prefixed
@@ -1163,6 +1256,17 @@ module Skaidb
       end
     end
 
+    # EXTERNAL (PROTOCOL.md §2.4): the TLS client certificate is the
+    # credential, its Common Name the username; +user+ may be empty or must
+    # equal it. AuthStart carries an empty client nonce and mechanism byte 2,
+    # and the server answers AuthOutcome at once. The outcome's 32-byte
+    # signature is NOT verified — there is no shared secret to verify it
+    # with; TLS already authenticated the server.
+    def handshake_certificate(user)
+      write_frame(Skaidb.certificate_auth_start(user))
+      Skaidb.parse_certificate_outcome(read_frame)
+    end
+
     # -- query --
 
     def run(sql, consistency)
@@ -1205,9 +1309,9 @@ module Skaidb
         last = sets.last || Result.new(fields: [], rows: [], cmd_tuples: 0)
         Result.new(fields: last.fields, rows: last.rows, cmd_tuples: 0, result_sets: sets)
       when 1 # Mutation
-        Result.new(fields: [], rows: [], cmd_tuples: r.u64)
+        Result.new(fields: [], rows: [], cmd_tuples: r.u64, kind: :mutation)
       when 2 # Ddl
-        Result.new(fields: [], rows: [], cmd_tuples: 0)
+        Result.new(fields: [], rows: [], cmd_tuples: 0, kind: :ddl)
       when 3 # Error — a statement error, connection stays usable
         raise QueryError, r.text
       else
@@ -1226,18 +1330,31 @@ module Skaidb
   # @param password [String]
   # @param consistency [Symbol, String, Integer] :one / :quorum / :all (or 0/1/2)
   # @param timeout [Numeric, nil] connect/IO timeout in seconds
+  # @param tls_client_cert [String, nil] PEM file of a client certificate to
+  #   present over TLS (with +tls_client_key+); turns TLS on
+  # @param tls_client_key [String, nil] PEM file of its private key
+  # @param auth_mechanism [Symbol, String] +:scram+ (user + password, the
+  #   default) or +:certificate+ (the client certificate is the login; +user+
+  #   is optional and, when given, must equal the certificate's Common Name)
   # @yield [conn] optional block; the connection is closed when it returns
   # @return [Connection] (or the block's value when a block is given)
-  def self.connect(host: "localhost", port: 7000, user: "anonymous",
+  def self.connect(host: "localhost", port: 7000, user: nil,
                    password: "", consistency: :quorum, timeout: 10.0,
                    database: nil, tls: false, tls_ca: nil, tls_insecure: false,
-                   tls_server_name: "skaidb", seeds: nil)
-    tls = true if tls_ca || tls_insecure
+                   tls_server_name: "skaidb", seeds: nil, tls_client_cert: nil,
+                   tls_client_key: nil, auth_mechanism: :scram)
+    tls = true if tls_ca || tls_insecure || tls_client_cert
+    # A SCRAM login with no user is "anonymous"; a certificate login with no
+    # user sends an empty one and lets the certificate's CN decide.
+    user = "anonymous" if user.nil? && AuthMechanism.resolve(auth_mechanism) == AuthMechanism::SCRAM
     conn = Connection.new(host: host, port: port, user: user,
                           password: password, consistency: consistency,
                           timeout: timeout, database: database, tls: tls,
                           tls_ca: tls_ca, tls_insecure: tls_insecure,
-                          tls_server_name: tls_server_name, seeds: seeds)
+                          tls_server_name: tls_server_name, seeds: seeds,
+                          tls_client_cert: tls_client_cert,
+                          tls_client_key: tls_client_key,
+                          auth_mechanism: auth_mechanism)
     return conn unless block_given?
 
     begin

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skaidb
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.0
 platform: ruby
 authors:
 - skaidb contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-20 00:00:00.000000000 Z
+date: 2026-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal