sdkey 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8d89ff1ef1aa3fb22572fa04b869e0bbc3d43874a8fc26609e8b14304484a66
-  data.tar.gz: b93267523e955d18224b0663a97157e7957a19115eab13f18f37a74ee1793d27
+  metadata.gz: ba734c87928d03dc312c980d12c99f297fbcd08669ee4a2edc9619c043682644
+  data.tar.gz: fdc9bacd2081741881c91f6ab348a2cc4a46c1db63b136b95d65057b371f2f64
 SHA512:
-  metadata.gz: 88436c0ae334d358ac3a27f570180d5ba8ec63ace13f9a7a9d9aede0fbdad5994ad68291900435c70fb793b23a8403c42c03d54b3197482ca2726f1ff7af912f
-  data.tar.gz: 2e256ba0ee1a0a83c53086ec54c303fa75ad46403d03eeebc9d5141efa4f0e409b966214253ea32e6186beb8a8ba8d5e3bf011faf275f1dbaa8b9b013c01f7cf
+  metadata.gz: 5869f2b9fa8ea8b67df19b28c812bfbdc530fd35fb92070b64d8892eb70bef6819f228f549192cf6afc2e23cd2f27c774ad6057aa8edff04a58d073453be7d7b
+  data.tar.gz: 3943b769039107de69655837c68164b57bd7c938b646f2a76227445be35b596511223dd265eb3f6bf187571ac2ee3af7939dd5cd1581544cefd5435415aa42f2

data/PROTOCOL.md

@@ -1,6 +1,6 @@
 # SDKey Client Protocol (C++ / C# / TypeScript implementer guide)
 
-This document describes the SDKey client wire protocol. Native clients must implement the same byte layouts and verification order. An in-repo TypeScript helper (`SdkeyClient` in `@sdkey/sdk`) implements this protocol for session init, sealed validate, and client auth.
+This document describes the SDKey client wire protocol. Native clients must implement the same byte layouts and verification order. An in-repo TypeScript helper (`SdkeyClient` in `@sdkey/sdk`) implements this protocol for session init, sealed validate, and sealed client auth (register / login / upgrade).
 
 ## Embed at build time
 
@@ -166,35 +166,77 @@ Plaintext validate (integration / when `CRYPTO_ENFORCE` is off): success has top
 
 Skipping step 2 defeats anti-spoof protection. A patched binary that skips verify can still be attacked offline — document this honestly to customers.
 
-## Public client auth (plaintext JSON)
+## Sealed client auth (register / login / upgrade)
 
-These endpoints are **not** sealed. They still require `appId` + `clientVersion` (exact match) and are subject to IP bans. Optional `hwid` follows the same skip-when-omitted rules as validate (HWID ban only checked when `hwid` is present). Rate limit: 30 / min / IP (`clientAuth`). Opaque `sessionToken` TTL: 7 days (`USER_SESSION_TTL_SECONDS`).
+Client register, login, and upgrade use the **same sealed-session wire model as validate**: `POST /session/init` first, then outer `sealedEnvelopeSchema`, inner nonce / timestamp / `v`, replay + clock-skew checks, and **sign then seal** responses. Application binding (`applicationId`) and version gating come from the crypto session — do **not** put `appId` or `clientVersion` in the inner body.
+
+**`CRYPTO_ENFORCE`:** sealed envelopes are always accepted. Plaintext JSON client-auth bodies (with `appId` + `clientVersion`) are only accepted when `CRYPTO_ENFORCE=false` (local / integration). Production with `CRYPTO_ENFORCE=true` rejects plaintext on these paths with `400 CRYPTO_REQUIRED`.
+
+Optional `hwid` follows the same skip-when-omitted rules as validate. Rate limit: 30 / min / IP (`clientAuth`). Opaque `sessionToken` TTL: 7 days (`USER_SESSION_TTL_SECONDS`).
+
+Outer request envelope (HTTPS JSON) — identical to validate:
+
+```json
+{
+  "sessionId": "...",
+  "ivB64": "...",
+  "ciphertextB64": "...",
+  "tagB64": "..."
+}
+```
+
+Response envelope (adds `signatureB64`) — identical to validate:
+
+```json
+{
+  "sessionId": "...",
+  "ivB64": "...",
+  "ciphertextB64": "...",
+  "tagB64": "...",
+  "signatureB64": "..."
+}
+```
+
+**Client order of operations (mandatory)** — same as validate:
+
+1. AES-GCM open → plaintext JSON  
+2. Ed25519 verify(`APP_PUBLIC_KEY`, `canonicalJson(plaintext)`, `signature`)  
+3. Check `timestamp` skew (±60s) and `sessionId` match  
+4. Only then honor `success` / `sessionToken`
+
+Sealed business failures (and crypto protocol failures after a valid session) typically return HTTP **200** with a sealed body so clients always take the decrypt/verify path.
 
 ### `POST /api/v1/client/register`
 
+Inner plaintext (before AES-GCM seal):
+
 ```json
 {
-  "appId": "<uuid>",
   "username": "player1",
   "password": "••••••••",
   "email": "optional@example.com",
   "licenseKey": "SDKY-....",
   "hwid": "...",
-  "clientVersion": "1.0.0"
+  "nonce": "<base64 16 bytes>",
+  "timestamp": 1720000001,
+  "v": 1
 }
 ```
 
-Username: 3–64 chars, `[a-zA-Z0-9._-]`. Password: 8–128. `licenseKey` may be required by app setting `requireLicenseToRegister` (default true) → `LICENSE_REQUIRED` when missing. Success returns an opaque user session (see below). HTTP `201` on success.
+Username: 3–64 chars, `[a-zA-Z0-9._-]`. Password: 8–128. `email`, `licenseKey`, and `hwid` are optional on the wire. `licenseKey` may be required by app setting `requireLicenseToRegister` (default true) → `LICENSE_REQUIRED` when missing. Success returns an opaque user session inside the sealed plaintext (see below).
 
 ### `POST /api/v1/client/login`
 
+Inner plaintext:
+
 ```json
 {
-  "appId": "<uuid>",
   "username": "player1",
   "password": "••••••••",
   "hwid": "...",
-  "clientVersion": "1.0.0"
+  "nonce": "<base64 16 bytes>",
+  "timestamp": 1720000001,
+  "v": 1
 }
 ```
 
@@ -202,23 +244,43 @@ Username: 3–64 chars, `[a-zA-Z0-9._-]`. Password: 8–128. `licenseKey` may be
 
 Upgrade the user's linked license with a higher-tier key. **No password** — username + new key only. New key's `subscriptionTier` must be **greater than** the user's current tier (no linked license → current = `0`).
 
+Inner plaintext:
+
 ```json
 {
-  "appId": "<uuid>",
   "username": "player1",
   "licenseKey": "SDKY-....",
   "hwid": "...",
-  "clientVersion": "1.0.0"
+  "nonce": "<base64 16 bytes>",
+  "timestamp": 1720000001,
+  "v": 1
 }
 ```
 
-### Auth success shape
+### Sealed auth response plaintext
+
+After AES-GCM open, **both success and failure plaintext include `message`** (not a top-level `error`). Signed fields:
+
+| Field | Notes |
+|---|---|
+| `success` | boolean |
+| `code` | stable machine code |
+| `message` | human-readable (editable per app for many codes) |
+| `sessionId` | must match request session |
+| `timestamp` | unix seconds |
+| `v` | protocol version (`1`) |
+| `sessionToken`, `expiresAt`, `user`, `license`, `session` | present on success |
 
-Success has **no** customizable `message` field:
+Success example:
 
 ```json
 {
   "success": true,
+  "code": "OK",
+  "message": "ok",
+  "sessionId": "...",
+  "timestamp": 1720000001,
+  "v": 1,
   "sessionToken": "<opaque>",
   "expiresAt": "2026-01-01T00:00:00.000Z",
   "user": {
@@ -240,8 +302,36 @@ Success has **no** customizable `message` field:
 }
 ```
 
+Sealed failure plaintext example:
+
+```json
+{
+  "success": false,
+  "code": "INVALID_CREDENTIALS",
+  "message": "Invalid username or password",
+  "sessionId": "...",
+  "timestamp": 1720000001,
+  "v": 1
+}
+```
+
 `license` may be `null` when the user has no linked license. Never send or echo passwords in responses.
 
+Plaintext client-auth bodies (when `CRYPTO_ENFORCE=false` only) still use top-level `error` on failure and omit the sealed `message` / `sessionId` / `timestamp` / `v` envelope fields — local integration only.
+
+## Sealed operations checklist
+
+Every path below accepts a sealed envelope (and **requires** it when `CRYPTO_ENFORCE=true`). Paths are relative to `/api/v1/`.
+
+| Operation | Method + path | Inner body (sealed) | Notes |
+|---|---|---|---|
+| Validate | `POST /licenses/validate` | `licenseKey`, optional `hwid`, `nonce`, `timestamp`, `v` | Sign-then-seal response; verify order above |
+| Register | `POST /client/register` | `username`, `password`, optional `email` / `licenseKey` / `hwid`, `nonce`, `timestamp`, `v` | `appId` / `clientVersion` from session |
+| Login | `POST /client/login` | `username`, `password`, optional `hwid`, `nonce`, `timestamp`, `v` | Same outer envelope + verify order |
+| Upgrade | `POST /client/upgrade` | `username`, `licenseKey`, optional `hwid`, `nonce`, `timestamp`, `v` | No password; tier must increase |
+
+Registry source of truth in-repo: `SEALED_CLIENT_OPERATIONS` in `@sdkey/shared`.
+
 ## Failure codes
 
 ### Sealed validate / crypto session
@@ -250,16 +340,25 @@ Success has **no** customizable `message` field:
 
 Cryptographic protocol failures after a valid session typically return HTTP **200** with a sealed body so clients always take the decrypt/verify path. Session init failures (version / IP / disabled) return plaintext JSON errors.
 
-### Client auth (plaintext JSON error body)
+### Sealed client auth
 
-Also: `LICENSE_REQUIRED`, `INVALID_CREDENTIALS`, `USERNAME_TAKEN`, `USER_NOT_FOUND`, `TIER_NOT_HIGHER`, plus shared codes such as `APP_OUTDATED`, `APP_DISABLED`, `IP_BANNED`, `HWID_BANNED`, `LICENSE_NOT_FOUND`, `BANNED`, `EXPIRED`, `APP_MISMATCH`. (`REGISTER_DISABLED` is a reserved editable message key.)
+Also: `LICENSE_REQUIRED`, `INVALID_CREDENTIALS`, `USERNAME_TAKEN`, `USER_NOT_FOUND`, `TIER_NOT_HIGHER`, plus shared codes such as `APP_OUTDATED`, `APP_DISABLED`, `IP_BANNED`, `HWID_BANNED`, `LICENSE_NOT_FOUND`, `BANNED`, `EXPIRED`, `APP_MISMATCH`, `SESSION_EXPIRED`, `CLOCK_SKEW`, `REPLAY`, `DECRYPT_FAIL`. (`REGISTER_DISABLED` is a reserved editable message key.)
 
-Error body — customizable text is in **`error`** (not `message`):
+Sealed failure plaintext — customizable text is in **`message`** (not top-level `error`):
 
 ```json
-{ "success": false, "error": "License tier must be higher than the current tier", "code": "TIER_NOT_HIGHER" }
+{
+  "success": false,
+  "code": "TIER_NOT_HIGHER",
+  "message": "License tier must be higher than the current tier",
+  "sessionId": "...",
+  "timestamp": 1720000001,
+  "v": 1
+}
 ```
 
+Plaintext client-auth failures (`CRYPTO_ENFORCE=false` only) still use `{ "success": false, "error": "...", "code": "..." }`.
+
 ## Threat model notes
 
 - TLS alone is insufficient: an attacker who injects at the process boundary after decrypt can feed `success: true` unless Ed25519 verify binds the response to the app public key.
@@ -273,4 +372,4 @@ Future hash-only validate (anti-replay + app binding without presenting plaintex
 
 ## Developer tooling (not part of sealed protocol)
 
-Cookie or `Authorization: Bearer sdk_live_…` covers dashboard-equivalent management: `PATCH /api/v1/apps/:id/settings`, ban list/delete, `POST /api/v1/licenses/:id/ban` with scopes, create licenses with `subscriptionTier`, `POST /api/v1/licenses/:id/tier`, and `GET /api/v1/apps/:id/users`. See the web docs (API keys + API reference).
+Cookie or `Authorization: Bearer sdk_live_…` covers dashboard-equivalent management: `PATCH /api/v1/apps/:id/settings`, `DELETE /api/v1/apps/:id` (cascades licenses, users, bans, logs), ban list/delete, `POST /api/v1/licenses/:id/ban` with scopes, create licenses with `subscriptionTier`, `POST /api/v1/licenses/:id/tier`, `POST /api/v1/licenses/:id/reset-hwid`, `POST /api/v1/apps/:id/users` (create end-user; optional `licenseKey`, respects `requireLicenseToRegister`), `POST /api/v1/apps/:id/users/:userId/reset-hwid`, and `GET /api/v1/apps/:id/users`. See the web docs (API keys + API reference).

data/README.md

@@ -2,9 +2,9 @@
 
 Official Ruby client for [SDKey](https://docs.sdkey.dev) license authentication.
 
-Implements the sealed session protocol: Ed25519-verified handshake, HKDF session keys, and AES-256-GCM validate envelopes, plus plaintext client auth (`register` / `login` / `upgrade`). See [PROTOCOL.md](./PROTOCOL.md).
+Implements the sealed session protocol: Ed25519-verified handshake, HKDF session keys, and AES-256-GCM envelopes for validate and client auth (`register` / `login` / `upgrade`). See [PROTOCOL.md](./PROTOCOL.md).
 
-**Version:** `0.2.0` (RubyGems / git tag `v0.2.0`)
+**Version:** `0.3.0` (RubyGems / git tag `v0.3.0`)
 
 ## Install
 
@@ -15,7 +15,7 @@ gem install sdkey
 Or in a Gemfile:
 
 ```ruby
-gem "sdkey", "~> 0.2.0"
+gem "sdkey", "~> 0.3.0"
 ```
 
 Requires Ruby 3.1+ with OpenSSL (Ed25519, AES-GCM, HKDF).
@@ -50,9 +50,11 @@ rescue Sdkey::Error => err
 end
 ```
 
-`validate` calls `init` automatically when no session exists. Sessions last ~15 minutes server-side; on `SESSION_EXPIRED` the client clears local state so the next call re-handshakes.
+`validate`, `register`, `login`, and `upgrade` call `init` automatically when no session exists. Sessions last ~15 minutes server-side; on `SESSION_EXPIRED` the client clears local state so the next call re-handshakes. An active session is reused across sealed operations (no second `session/init`).
 
-### Client auth (plaintext JSON)
+### Client auth (sealed session)
+
+Register / login / upgrade use the same sealed envelope as validate. Application binding and version gating come from the crypto session — do **not** send `appId` or `clientVersion` in the auth body. With `CRYPTO_ENFORCE=true`, plaintext client-auth bodies are rejected (`CRYPTO_REQUIRED`).
 
 ```ruby
 reg = client.register(
@@ -64,6 +66,7 @@ reg = client.register(
 if reg.success
   puts [reg.session_token, reg.user, reg.license].inspect
 else
+  # Sealed failures surface server `message` on ClientAuthResult#error
   puts "#{reg.code} #{reg.error}"
 end
 
@@ -81,7 +84,7 @@ Per-app `responseMessages` may customize many strings. The SDK surfaces whatever
 |---|---|---|
 | Session init | *(none)* | `error` (raised as `Sdkey::Error#message`) |
 | Sealed validate | `message` | `message` |
-| Client register / login / upgrade | *(none)* | `error` on `ClientAuthResult` |
+| Sealed register / login / upgrade | `message` | `message` (mapped to `ClientAuthResult#error`) |
 
 ### Example JSON shapes
 
@@ -122,13 +125,27 @@ Per-app `responseMessages` may customize many strings. The SDK surfaces whatever
 }
 ```
 
-**Client auth failure** (`error`):
+**Sealed client-auth outer request** (identical to validate):
+
+```json
+{
+  "sessionId": "...",
+  "ivB64": "...",
+  "ciphertextB64": "...",
+  "tagB64": "..."
+}
+```
+
+**Sealed client-auth failure** (`message` inside the opened plaintext):
 
 ```json
 {
   "success": false,
-  "error": "License tier must be higher than the current tier",
-  "code": "TIER_NOT_HIGHER"
+  "code": "TIER_NOT_HIGHER",
+  "message": "License tier must be higher than the current tier",
+  "sessionId": "...",
+  "timestamp": 1720000001,
+  "v": 1
 }
 ```
 
@@ -140,7 +157,7 @@ Per-app `responseMessages` may customize many strings. The SDK surfaces whatever
 |---|---|---|
 | `api_base_url` | `String` | API origin (no trailing slash) |
 | `app_id` | `String` | Application UUID |
-| `app_version` | `String` | Exact app version → sent as `clientVersion` |
+| `app_version` | `String` | Exact app version → sent as `clientVersion` on session init |
 | `app_public_key_b64` | `String` | Raw Ed25519 public key (32 bytes), base64 |
 | `http_post` | callable | Optional HTTP POST override (tests / custom transport) |
 
@@ -148,19 +165,23 @@ Per-app `responseMessages` may customize many strings. The SDK surfaces whatever
 
 - `init` — challenge handshake; verifies the signed hello; derives the AES session key; sends `clientVersion`
 - `validate(license_key, hwid = nil)` — sealed validate; omits `hwid` JSON key when not provided; **always** decrypts then verifies the Ed25519 signature before trusting `success`
-- `register(...)` / `login(...)` / `upgrade(...)` — plaintext `POST /api/v1/client/*`
+- `register(...)` / `login(...)` / `upgrade(...)` — sealed `POST /api/v1/client/*` (same outer envelope + verify order as validate)
 - `session` / `clear_session` — inspect or drop the local session
 
 ### Errors
 
 Protocol / transport failures raise `Sdkey::Error` with a `code` and `message` (server `error` text when the API provides one):
 
-`INIT_FAILED` · `APP_OUTDATED` · `HELLO_SIGNATURE_INVALID` · `VALIDATE_RESPONSE_INVALID` · `RESPONSE_SIGNATURE_INVALID` · `SESSION_MISMATCH` · `CLOCK_SKEW` · `NETWORK`
+`INIT_FAILED` · `APP_OUTDATED` · `HELLO_SIGNATURE_INVALID` · `VALIDATE_RESPONSE_INVALID` · `SEALED_RESPONSE_INVALID` · `RESPONSE_SIGNATURE_INVALID` · `SESSION_MISMATCH` · `CLOCK_SKEW` · `NETWORK`
 
-License denials (banned, HWID mismatch, etc.) return a normal `ValidateResult` with `success: false` — they are not raised. Auth denials return `ClientAuthResult` with `success: false`, `code`, and `error`.
+License denials (banned, HWID mismatch, etc.) return a normal `ValidateResult` with `success: false` — they are not raised. Auth denials return `ClientAuthResult` with `success: false`, `code`, and `error` (from sealed `message`).
 
 This package does **not** include developer tooling / Bearer (`sdk_live_…`) management APIs.
 
+## Breaking changes (0.3.0)
+
+Client auth is sealed. Plaintext `POST /api/v1/client/{register,login,upgrade}` bodies with `appId` / `clientVersion` no longer work when the API has `CRYPTO_ENFORCE=true` (`CRYPTO_REQUIRED`). Public method signatures are unchanged.
+
 ## Security notes
 
 - Never ship app **private** keys in a client.

data/lib/sdkey/client.rb

@@ -13,12 +13,10 @@ require_relative "errors"
 require_relative "types"
 
 module Sdkey
-  # SDKey license client (sealed session protocol + plaintext client auth).
+  # SDKey license client (sealed session protocol).
   #
-  # Flow: +init+ (session handshake) → +validate(license_key, hwid=nil)+ (sealed).
-  # +validate+ calls +init+ automatically when no session exists.
-  #
-  # Plaintext client auth: +register+ / +login+ / +upgrade+ (no sealed session required).
+  # Flow: +init+ (session handshake) → sealed +validate+ / +register+ / +login+ / +upgrade+.
+  # Sealed RPCs call +init+ automatically when no session exists.
   class Client
     def initialize(api_base_url:, app_id:, app_version:, app_public_key_b64:, http_post: nil)
       @api_base_url = api_base_url.to_s.sub(%r{/+\z}, "")
@@ -36,7 +34,7 @@ module Sdkey
     end
     alias get_session session
 
-    # Drop the current session (next +validate+ will re-init).
+    # Drop the current session (next sealed RPC will re-init).
     def clear_session
       @session = nil
     end
@@ -95,10 +93,6 @@ module Sdkey
     end
 
     def validate(license_key, hwid = nil)
-      init if @session.nil? || @public_key.nil?
-      session = @session
-      public_key = @public_key
-
       inner = {
         "licenseKey" => license_key,
         "nonce" => Crypto::Encoding.bytes_to_base64(
@@ -118,6 +112,61 @@ module Sdkey
         }
       end
 
+      plaintext = sealed_rpc("licenses/validate", inner)
+
+      clear_session if plaintext["code"] == "SESSION_EXPIRED"
+
+      tier_raw = plaintext["subscriptionTier"]
+      subscription_tier = tier_raw.nil? ? nil : tier_raw.to_i
+
+      ValidateResult.new(
+        success: !!plaintext["success"],
+        code: plaintext["code"].to_s,
+        message: plaintext["message"].to_s,
+        status: plaintext["status"],
+        expires_at: plaintext["expiresAt"],
+        subscription_tier: subscription_tier,
+        timestamp: plaintext["timestamp"].to_i
+      )
+    end
+
+    def register(username:, password:, email: nil, license_key: nil, hwid: nil)
+      fields = {
+        "username" => username,
+        "password" => password
+      }
+      fields["email"] = email unless email.nil?
+      fields["licenseKey"] = license_key unless license_key.nil?
+      fields["hwid"] = hwid unless hwid.nil?
+      client_auth("register", fields)
+    end
+
+    def login(username:, password:, hwid: nil)
+      fields = {
+        "username" => username,
+        "password" => password
+      }
+      fields["hwid"] = hwid unless hwid.nil?
+      client_auth("login", fields)
+    end
+
+    def upgrade(username:, license_key:, hwid: nil)
+      fields = {
+        "username" => username,
+        "licenseKey" => license_key
+      }
+      fields["hwid"] = hwid unless hwid.nil?
+      client_auth("upgrade", fields)
+    end
+
+    private
+
+    # Seal +inner+, POST to +/api/v1/{path}+, then open → verify → sessionId + skew.
+    def sealed_rpc(path, inner)
+      init if @session.nil? || @public_key.nil?
+      session = @session
+      public_key = @public_key
+
       sealed = Crypto::Seal.seal_aes_gcm(
         session.aes_key,
         JSON.generate(inner)
@@ -125,20 +174,21 @@ module Sdkey
 
       begin
         _status, envelope = @http_post.call(
-          "#{@api_base_url}/api/v1/licenses/validate",
+          "#{@api_base_url}/api/v1/#{path}",
           {
             "sessionId" => session.session_id
           }.merge(sealed.as_wire)
         )
       rescue StandardError => e
-        raise Error.new("NETWORK", "validate request failed", e)
+        raise Error.new("NETWORK", "#{path} request failed", e)
       end
 
       unless envelope["ivB64"] && envelope["ciphertextB64"] && envelope["tagB64"] && envelope["signatureB64"]
         clear_session if envelope["code"] == "SESSION_EXPIRED"
+        default_code = path == "licenses/validate" ? "VALIDATE_RESPONSE_INVALID" : "SEALED_RESPONSE_INVALID"
         raise Error.new(
-          (envelope["code"] || "VALIDATE_RESPONSE_INVALID").to_s,
-          (envelope["error"] || "invalid validate response").to_s
+          (envelope["code"] || default_code).to_s,
+          (envelope["error"] || "invalid #{path} response").to_s
         )
       end
 
@@ -161,72 +211,21 @@ module Sdkey
         raise Error.new("CLOCK_SKEW", "response clock skew")
       end
 
-      clear_session if plaintext["code"] == "SESSION_EXPIRED"
-
-      tier_raw = plaintext["subscriptionTier"]
-      subscription_tier = tier_raw.nil? ? nil : tier_raw.to_i
-
-      ValidateResult.new(
-        success: !!plaintext["success"],
-        code: plaintext["code"].to_s,
-        message: plaintext["message"].to_s,
-        status: plaintext["status"],
-        expires_at: plaintext["expiresAt"],
-        subscription_tier: subscription_tier,
-        timestamp: plaintext["timestamp"].to_i
-      )
+      plaintext
     end
 
-    def register(username:, password:, email: nil, license_key: nil, hwid: nil)
-      body = {
-        "appId" => @app_id,
-        "username" => username,
-        "password" => password,
-        "clientVersion" => @app_version
-      }
-      body["email"] = email unless email.nil?
-      body["licenseKey"] = license_key unless license_key.nil?
-      body["hwid"] = hwid unless hwid.nil?
-      client_auth("register", body)
-    end
-
-    def login(username:, password:, hwid: nil)
-      body = {
-        "appId" => @app_id,
-        "username" => username,
-        "password" => password,
-        "clientVersion" => @app_version
-      }
-      body["hwid"] = hwid unless hwid.nil?
-      client_auth("login", body)
-    end
-
-    def upgrade(username:, license_key:, hwid: nil)
-      body = {
-        "appId" => @app_id,
-        "username" => username,
-        "licenseKey" => license_key,
-        "clientVersion" => @app_version
-      }
-      body["hwid"] = hwid unless hwid.nil?
-      client_auth("upgrade", body)
-    end
-
-    private
-
-    def client_auth(action, body)
-      begin
-        _status, response = @http_post.call(
-          "#{@api_base_url}/api/v1/client/#{action}",
-          body
-        )
-      rescue StandardError => e
-        raise Error.new("NETWORK", "#{action} request failed", e)
-      end
-
-      raise Error.new("UNKNOWN", "invalid #{action} response") unless response.is_a?(Hash)
+    def client_auth(action, fields)
+      inner = fields.merge(
+        "nonce" => Crypto::Encoding.bytes_to_base64(
+          SecureRandom.random_bytes(Crypto::Constants::VALIDATE_NONCE_BYTES)
+        ),
+        "timestamp" => Time.now.to_i,
+        "v" => Crypto::Constants::PROTOCOL_VERSION
+      )
 
-      parse_auth_result(response)
+      plaintext = sealed_rpc("client/#{action}", inner)
+      clear_session if plaintext["code"] == "SESSION_EXPIRED"
+      parse_auth_result(plaintext)
     end
 
     def parse_auth_result(body)
@@ -234,7 +233,7 @@ module Sdkey
         return ClientAuthResult.new(
           success: false,
           code: body["code"]&.to_s,
-          error: body["error"]&.to_s
+          error: (body["message"] || body["error"])&.to_s
         )
       end
 

data/lib/sdkey/types.rb

@@ -52,7 +52,7 @@ module Sdkey
     keyword_init: true
   )
 
-  # Result of register / login / upgrade (plaintext client auth).
+  # Result of register / login / upgrade (sealed client auth).
   ClientAuthResult = Struct.new(
     :success,
     :code,

data/lib/sdkey/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sdkey
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sdkey
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - SDKeyDev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-22 00:00:00.000000000 Z
+date: 2026-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -24,8 +24,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.2'
-description: Sealed session protocol (Ed25519, HKDF, AES-256-GCM) plus plaintext client
-  auth.
+description: Sealed session protocol (Ed25519, HKDF, AES-256-GCM) for validate and
+  client auth.
 email:
 - support@sdkey.dev
 executables: []