sdkey 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a8d89ff1ef1aa3fb22572fa04b869e0bbc3d43874a8fc26609e8b14304484a66
+  data.tar.gz: b93267523e955d18224b0663a97157e7957a19115eab13f18f37a74ee1793d27
+SHA512:
+  metadata.gz: 88436c0ae334d358ac3a27f570180d5ba8ec63ace13f9a7a9d9aede0fbdad5994ad68291900435c70fb793b23a8403c42c03d54b3197482ca2726f1ff7af912f
+  data.tar.gz: 2e256ba0ee1a0a83c53086ec54c303fa75ad46403d03eeebc9d5141efa4f0e409b966214253ea32e6186beb8a8ba8d5e3bf011faf275f1dbaa8b9b013c01f7cf

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SDKeyDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/PROTOCOL.md

@@ -0,0 +1,276 @@
+# 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.
+
+## Embed at build time
+
+| Constant | Description |
+|---|---|
+| `API_BASE_URL` | e.g. `https://api.sdkey.dev` (no trailing slash) |
+| `APP_ID` | Application UUID |
+| `APP_VERSION` | Exact app version string (must match `applications.version`) |
+| `APP_PUBLIC_KEY` | Ed25519 public key, 32 raw bytes (or base64 of those bytes) |
+
+## Algorithms
+
+| Primitive | Spec |
+|---|---|
+| App identity | Ed25519 sign / verify |
+| Session key | HKDF-SHA256 → 32-byte AES key |
+| Payload seal | AES-256-GCM, 12-byte IV, 128-bit tag |
+| Canonical JSON | Object keys sorted lexicographically, no insignificant whitespace |
+| Clock skew | Reject if `\|now - timestamp\| > 60` seconds |
+
+## Session key derivation
+
+```
+IKM  = clientNonce (32) || serverNonce (32)
+salt = SESSION_HKDF_SALT (from signed hello as hkdfSaltB64)
+info = UTF8("sdkey-session-v1" || appId)
+OKM  = HKDF-SHA256(IKM, salt, info, length=32)
+```
+
+## Flow
+
+### 1. `POST /api/v1/session/init`
+
+Request:
+
+```json
+{
+  "appId": "<uuid>",
+  "clientNonceB64": "<base64 32 bytes>",
+  "clientVersion": "<exact app version>"
+}
+```
+
+`clientVersion` must exactly match the application's configured version. Mismatch → `APP_OUTDATED`. Banned client IP → `IP_BANNED`. Disabled app → `APP_DISABLED`.
+
+Success response (no `message` field):
+
+```json
+{
+  "success": true,
+  "sessionId": "<uuid>",
+  "serverNonceB64": "...",
+  "hkdfSaltB64": "...",
+  "timestamp": 1720000000,
+  "signatureB64": "...",
+  "v": 1
+}
+```
+
+Failures are plaintext JSON. Customizable text for `APP_DISABLED` / `APP_OUTDATED` / `IP_BANNED` is in `error` (from app `responseMessages`):
+
+```json
+{
+  "success": false,
+  "error": "Client version outdated",
+  "code": "APP_OUTDATED"
+}
+```
+
+**Client must** verify Ed25519 signature over canonical JSON of:
+
+```json
+{
+  "appId": "...",
+  "hkdfSaltB64": "...",
+  "serverNonceB64": "...",
+  "sessionId": "...",
+  "timestamp": 1720000000,
+  "v": 1
+}
+```
+
+Then derive the AES session key.
+
+### 2. `POST /api/v1/licenses/validate`
+
+Outer request envelope (HTTPS JSON):
+
+```json
+{
+  "sessionId": "...",
+  "ivB64": "...",
+  "ciphertextB64": "...",
+  "tagB64": "..."
+}
+```
+
+Inner plaintext (before AES-GCM seal):
+
+```json
+{
+  "hwid": "...",
+  "licenseKey": "SDKY-....",
+  "nonce": "<base64 16 bytes>",
+  "timestamp": 1720000001,
+  "v": 1
+}
+```
+
+`hwid` is **optional**. When omitted, the server skips HWID lock, HWID mismatch, and HWID-ban checks. When present and the app has `hwidLockEnabled` (default true), first-use binding and mismatch rules apply. IP bans apply regardless of HWID. Message strings for many codes are editable per app (`responseMessages` on `PATCH /api/v1/apps/:id/settings`).
+
+Response envelope:
+
+```json
+{
+  "sessionId": "...",
+  "ivB64": "...",
+  "ciphertextB64": "...",
+  "tagB64": "...",
+  "signatureB64": "..."
+}
+```
+
+After AES-GCM open, **both success and failure plaintext include `message`** (not a top-level `error`). Success uses the app's `OK` response message. Success also includes integer `subscriptionTier` (≥ 0; default `0` when the license was created without a tier):
+
+```json
+{
+  "success": true,
+  "code": "OK",
+  "message": "validated",
+  "status": "active",
+  "expiresAt": "2026-01-01T00:00:00.000Z",
+  "subscriptionTier": 0,
+  "sessionId": "...",
+  "timestamp": 1720000001,
+  "v": 1
+}
+```
+
+Sealed failure plaintext example:
+
+```json
+{
+  "success": false,
+  "code": "HWID_MISMATCH",
+  "message": "Hardware ID mismatch",
+  "status": null,
+  "expiresAt": null,
+  "sessionId": "...",
+  "timestamp": 1720000001,
+  "v": 1
+}
+```
+
+Plaintext validate (integration / when `CRYPTO_ENFORCE` is off): success has top-level `message`; failures use `{ success: false, error, code }`.
+
+**Client order of operations (mandatory):**
+
+1. AES-GCM open → plaintext JSON  
+2. Ed25519 verify(`APP_PUBLIC_KEY`, `canonicalJson(plaintext)`, `signature`)  
+3. Check `timestamp` skew and `sessionId` match  
+4. Only then honor `success`
+
+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)
+
+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`).
+
+### `POST /api/v1/client/register`
+
+```json
+{
+  "appId": "<uuid>",
+  "username": "player1",
+  "password": "••••••••",
+  "email": "optional@example.com",
+  "licenseKey": "SDKY-....",
+  "hwid": "...",
+  "clientVersion": "1.0.0"
+}
+```
+
+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.
+
+### `POST /api/v1/client/login`
+
+```json
+{
+  "appId": "<uuid>",
+  "username": "player1",
+  "password": "••••••••",
+  "hwid": "...",
+  "clientVersion": "1.0.0"
+}
+```
+
+### `POST /api/v1/client/upgrade`
+
+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`).
+
+```json
+{
+  "appId": "<uuid>",
+  "username": "player1",
+  "licenseKey": "SDKY-....",
+  "hwid": "...",
+  "clientVersion": "1.0.0"
+}
+```
+
+### Auth success shape
+
+Success has **no** customizable `message` field:
+
+```json
+{
+  "success": true,
+  "sessionToken": "<opaque>",
+  "expiresAt": "2026-01-01T00:00:00.000Z",
+  "user": {
+    "id": "<uuid>",
+    "username": "player1",
+    "email": null,
+    "applicationId": "<uuid>"
+  },
+  "license": {
+    "id": "<uuid>",
+    "status": "active",
+    "expiresAt": null,
+    "subscriptionTier": 1
+  },
+  "session": {
+    "ip": "203.0.113.1",
+    "hwid": "..."
+  }
+}
+```
+
+`license` may be `null` when the user has no linked license. Never send or echo passwords in responses.
+
+## Failure codes
+
+### Sealed validate / crypto session
+
+`SESSION_EXPIRED`, `CLOCK_SKEW`, `REPLAY`, `LICENSE_NOT_FOUND`, `APP_MISMATCH`, `BANNED`, `EXPIRED`, `HWID_MISMATCH`, `DECRYPT_FAIL`, `APP_DISABLED`, `APP_OUTDATED`, `HWID_BANNED`, `IP_BANNED`
+
+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)
+
+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.)
+
+Error body — customizable text is in **`error`** (not `message`):
+
+```json
+{ "success": false, "error": "License tier must be higher than the current tier", "code": "TIER_NOT_HIGHER" }
+```
+
+## 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.
+- Debugger skip-verify remains a residual bypass class for determined attackers.
+
+## Account modes vs validate wire format
+
+**Dashboard Private mode does not change this validate protocol.** Sealed validate still sends plaintext `licenseKey` inside the AES-GCM inner payload. Private mode only changes how developers mint and store inventory (client-side mint → server stores hash/prefix only).
+
+Future hash-only validate (anti-replay + app binding without presenting plaintext) is explicitly out of scope for this release.
+
+## 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).

data/README.md

@@ -0,0 +1,181 @@
+# sdkey
+
+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).
+
+**Version:** `0.2.0` (RubyGems / git tag `v0.2.0`)
+
+## Install
+
+```bash
+gem install sdkey
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "sdkey", "~> 0.2.0"
+```
+
+Requires Ruby 3.1+ with OpenSSL (Ed25519, AES-GCM, HKDF).
+
+## Quick start
+
+Embed these values from the SDKey dashboard when you ship your app. `app_version` must **exactly match** the application version configured on the server (`clientVersion`); mismatch returns `APP_OUTDATED`.
+
+```ruby
+require "sdkey"
+
+client = Sdkey::Client.new(
+  api_base_url: "https://api.sdkey.dev",
+  app_id: "YOUR_APP_ID",
+  app_version: "1.0.0",
+  app_public_key_b64: "YOUR_APP_PUBLIC_KEY_BASE64"
+)
+
+begin
+  # hwid is optional (omit for web clients — server skips HWID checks)
+  result = client.validate("SDKY-XXXX-XXXX-XXXX-XXXX", "machine-hwid")
+  if result.success
+    puts "licensed #{result.status} #{result.expires_at} tier=#{result.subscription_tier}"
+    puts "message #{result.message}"
+  else
+    puts "denied #{result.code} #{result.message}"
+  end
+rescue Sdkey::Error => err
+  # Init / transport failures use `error` text from the server when present
+  puts "#{err.code} #{err.message}"
+  raise
+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.
+
+### Client auth (plaintext JSON)
+
+```ruby
+reg = client.register(
+  username: "player1",
+  password: "••••••••",
+  license_key: "SDKY-XXXX-XXXX-XXXX-XXXX",
+  hwid: "machine-hwid" # optional
+)
+if reg.success
+  puts [reg.session_token, reg.user, reg.license].inspect
+else
+  puts "#{reg.code} #{reg.error}"
+end
+
+login = client.login(username: "player1", password: "••••••••")
+upgrade = client.upgrade(username: "player1", license_key: "SDKY-HIGHER-TIER-KEY")
+```
+
+`upgrade` takes **username + license key only** (no password). The new key’s `subscriptionTier` must be strictly greater than the user’s current tier.
+
+## Where `message` vs `error` appears
+
+Per-app `responseMessages` may customize many strings. The SDK surfaces whatever the server returns.
+
+| Surface | Success text field | Failure text field |
+|---|---|---|
+| Session init | *(none)* | `error` (raised as `Sdkey::Error#message`) |
+| Sealed validate | `message` | `message` |
+| Client register / login / upgrade | *(none)* | `error` on `ClientAuthResult` |
+
+### Example JSON shapes
+
+**Init failure** (plaintext):
+
+```json
+{ "success": false, "error": "Client version outdated", "code": "APP_OUTDATED" }
+```
+
+**Sealed validate success** (`message`):
+
+```json
+{
+  "success": true,
+  "code": "OK",
+  "message": "validated",
+  "status": "active",
+  "expiresAt": "2026-01-01T00:00:00.000Z",
+  "subscriptionTier": 0,
+  "sessionId": "...",
+  "timestamp": 1720000001,
+  "v": 1
+}
+```
+
+**Sealed validate failure** (still `message`, not `error`):
+
+```json
+{
+  "success": false,
+  "code": "HWID_MISMATCH",
+  "message": "Hardware ID mismatch",
+  "status": null,
+  "expiresAt": null,
+  "sessionId": "...",
+  "timestamp": 1720000001,
+  "v": 1
+}
+```
+
+**Client auth failure** (`error`):
+
+```json
+{
+  "success": false,
+  "error": "License tier must be higher than the current tier",
+  "code": "TIER_NOT_HIGHER"
+}
+```
+
+## API
+
+### `Sdkey::Client.new(...)`
+
+| Option | Type | Description |
+|---|---|---|
+| `api_base_url` | `String` | API origin (no trailing slash) |
+| `app_id` | `String` | Application UUID |
+| `app_version` | `String` | Exact app version → sent as `clientVersion` |
+| `app_public_key_b64` | `String` | Raw Ed25519 public key (32 bytes), base64 |
+| `http_post` | callable | Optional HTTP POST override (tests / custom transport) |
+
+### Methods
+
+- `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/*`
+- `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`
+
+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`.
+
+This package does **not** include developer tooling / Bearer (`sdk_live_…`) management APIs.
+
+## Security notes
+
+- Never ship app **private** keys in a client.
+- Do not skip signature verification — that is the anti-spoof binding.
+- This package is open source; the SDKey server remains a separate product.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+Repository: https://github.com/SDKeyDev/sdkey-ruby
+
+## License
+
+MIT

data/lib/sdkey/client.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "time"
+require "uri"
+
+require_relative "crypto/constants"
+require_relative "crypto/encoding"
+require_relative "crypto/seal"
+require_relative "errors"
+require_relative "types"
+
+module Sdkey
+  # SDKey license client (sealed session protocol + plaintext client auth).
+  #
+  # 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).
+  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}, "")
+      @app_id = app_id
+      @app_version = app_version
+      @app_public_key_b64 = app_public_key_b64
+      @http_post = http_post || method(:default_http_post)
+      @public_key = nil
+      @session = nil
+    end
+
+    # Active session, if any.
+    def session
+      @session
+    end
+    alias get_session session
+
+    # Drop the current session (next +validate+ will re-init).
+    def clear_session
+      @session = nil
+    end
+
+    def init
+      @public_key = Crypto::Seal.import_public_key(@app_public_key_b64)
+      client_nonce = SecureRandom.random_bytes(Crypto::Constants::CLIENT_NONCE_BYTES)
+
+      begin
+        status, body = @http_post.call(
+          "#{@api_base_url}/api/v1/session/init",
+          {
+            "appId" => @app_id,
+            "clientNonceB64" => Crypto::Encoding.bytes_to_base64(client_nonce),
+            "clientVersion" => @app_version
+          }
+        )
+      rescue StandardError => e
+        raise Error.new("NETWORK", "session init request failed", e)
+      end
+
+      if status < 200 || status >= 300 || !body["success"]
+        raise Error.new(
+          (body["code"] || "INIT_FAILED").to_s,
+          (body["error"] || "session init failed").to_s
+        )
+      end
+
+      hello = {
+        "appId" => @app_id,
+        "hkdfSaltB64" => body["hkdfSaltB64"],
+        "serverNonceB64" => body["serverNonceB64"],
+        "sessionId" => body["sessionId"],
+        "timestamp" => body["timestamp"],
+        "v" => Crypto::Constants::PROTOCOL_VERSION
+      }
+
+      unless Crypto::Seal.verify_signature(@public_key, hello, body["signatureB64"])
+        raise Error.new("HELLO_SIGNATURE_INVALID", "hello signature verification failed")
+      end
+
+      aes_key = Crypto::Seal.derive_session_aes_key(
+        client_nonce: client_nonce,
+        server_nonce: Crypto::Encoding.base64_to_bytes(body["serverNonceB64"]),
+        salt_b64: body["hkdfSaltB64"],
+        app_id: @app_id
+      )
+
+      @session = SessionState.new(
+        session_id: body["sessionId"],
+        aes_key: aes_key,
+        server_nonce_b64: body["serverNonceB64"],
+        hkdf_salt_b64: body["hkdfSaltB64"]
+      )
+      @session
+    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(
+          SecureRandom.random_bytes(Crypto::Constants::VALIDATE_NONCE_BYTES)
+        ),
+        "timestamp" => Time.now.to_i,
+        "v" => Crypto::Constants::PROTOCOL_VERSION
+      }
+      if hwid
+        # Keep lexicographic key order for the sealed inner JSON.
+        inner = {
+          "hwid" => hwid,
+          "licenseKey" => inner["licenseKey"],
+          "nonce" => inner["nonce"],
+          "timestamp" => inner["timestamp"],
+          "v" => inner["v"]
+        }
+      end
+
+      sealed = Crypto::Seal.seal_aes_gcm(
+        session.aes_key,
+        JSON.generate(inner)
+      )
+
+      begin
+        _status, envelope = @http_post.call(
+          "#{@api_base_url}/api/v1/licenses/validate",
+          {
+            "sessionId" => session.session_id
+          }.merge(sealed.as_wire)
+        )
+      rescue StandardError => e
+        raise Error.new("NETWORK", "validate request failed", e)
+      end
+
+      unless envelope["ivB64"] && envelope["ciphertextB64"] && envelope["tagB64"] && envelope["signatureB64"]
+        clear_session if envelope["code"] == "SESSION_EXPIRED"
+        raise Error.new(
+          (envelope["code"] || "VALIDATE_RESPONSE_INVALID").to_s,
+          (envelope["error"] || "invalid validate response").to_s
+        )
+      end
+
+      plain_bytes = Crypto::Seal.open_aes_gcm(
+        session.aes_key,
+        {
+          "ivB64" => envelope["ivB64"],
+          "ciphertextB64" => envelope["ciphertextB64"],
+          "tagB64" => envelope["tagB64"]
+        }
+      )
+      plaintext = JSON.parse(plain_bytes)
+
+      unless Crypto::Seal.verify_signature(public_key, plaintext, envelope["signatureB64"])
+        raise Error.new("RESPONSE_SIGNATURE_INVALID", "response signature verification failed")
+      end
+
+      raise Error.new("SESSION_MISMATCH", "sessionId mismatch") if plaintext["sessionId"] != session.session_id
+      if (Time.now.to_i - plaintext["timestamp"].to_i).abs > Crypto::Constants::CLOCK_SKEW_SECONDS
+        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
+      )
+    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)
+
+      parse_auth_result(response)
+    end
+
+    def parse_auth_result(body)
+      unless body["success"]
+        return ClientAuthResult.new(
+          success: false,
+          code: body["code"]&.to_s,
+          error: body["error"]&.to_s
+        )
+      end
+
+      user_raw = body["user"]
+      license_raw = body["license"]
+      session_raw = body["session"]
+
+      user = nil
+      if user_raw.is_a?(Hash)
+        user = ClientAuthUser.new(
+          id: user_raw["id"].to_s,
+          username: user_raw["username"].to_s,
+          email: user_raw["email"],
+          application_id: user_raw["applicationId"].to_s
+        )
+      end
+
+      license = nil
+      if license_raw.is_a?(Hash)
+        license = ClientAuthLicense.new(
+          id: license_raw["id"].to_s,
+          status: license_raw["status"].to_s,
+          expires_at: license_raw["expiresAt"],
+          subscription_tier: (license_raw["subscriptionTier"] || 0).to_i
+        )
+      end
+
+      session = nil
+      if session_raw.is_a?(Hash)
+        session = ClientAuthSessionInfo.new(
+          ip: session_raw["ip"].to_s,
+          hwid: session_raw["hwid"]
+        )
+      end
+
+      ClientAuthResult.new(
+        success: true,
+        session_token: body["sessionToken"]&.to_s,
+        expires_at: body["expiresAt"],
+        user: user,
+        license: license,
+        session: session
+      )
+    end
+
+    def default_http_post(url, body)
+      uri = URI(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(body)
+      response = http.request(request)
+      parsed = response.body.to_s.empty? ? {} : JSON.parse(response.body)
+      parsed = {} unless parsed.is_a?(Hash)
+      [response.code.to_i, parsed]
+    rescue JSON::ParserError
+      [response.code.to_i, {}]
+    end
+  end
+
+  # Alias matching Python naming.
+  SdkeyClient = Client
+end

data/lib/sdkey/crypto/canonical_json.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Sdkey
+  module Crypto
+    # Deterministic JSON encoding for Ed25519 signing.
+    # Object keys sorted lexicographically, no insignificant whitespace.
+    module CanonicalJson
+      module_function
+
+      def canonical_json(value)
+        canonicalize(value).encode("UTF-8")
+      end
+
+      def canonicalize(value)
+        case value
+        when nil
+          "null"
+        when true
+          "true"
+        when false
+          "false"
+        when Integer
+          value.to_s
+        when Float
+          raise ArgumentError, "canonicalJson: non-finite numbers are not allowed" unless value.finite?
+
+          JSON.generate(value)
+        when String
+          JSON.generate(value)
+        when Array
+          "[#{value.map { |item| canonicalize(item) }.join(",")}]"
+        when Hash
+          stringified = {}
+          value.each { |k, v| stringified[k.to_s] = v }
+          keys = stringified.keys.sort
+          body = keys.map do |key|
+            "#{JSON.generate(key)}:#{canonicalize(stringified[key])}"
+          end.join(",")
+          "{#{body}}"
+        else
+          raise TypeError, "canonicalJson: unsupported type #{value.class}"
+        end
+      end
+    end
+  end
+end

data/lib/sdkey/crypto/constants.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Sdkey
+  module Crypto
+    # Wire-protocol constants (protocol v1).
+    module Constants
+      PROTOCOL_VERSION = 1
+
+      CLOCK_SKEW_SECONDS = 60
+
+      CLIENT_NONCE_BYTES = 32
+      SERVER_NONCE_BYTES = 32
+      VALIDATE_NONCE_BYTES = 16
+
+      AES_GCM_IV_BYTES = 12
+      AES_GCM_TAG_BITS = 128
+      AES_GCM_TAG_BYTES = 16
+      SESSION_AES_KEY_BYTES = 32
+
+      SESSION_HKDF_INFO_PREFIX = "sdkey-session-v1"
+
+      VALIDATE_FAILURE_CODES = %w[
+        SESSION_EXPIRED
+        CLOCK_SKEW
+        REPLAY
+        LICENSE_NOT_FOUND
+        APP_MISMATCH
+        BANNED
+        EXPIRED
+        HWID_MISMATCH
+        DECRYPT_FAIL
+        APP_DISABLED
+        APP_OUTDATED
+        HWID_BANNED
+        IP_BANNED
+      ].freeze
+    end
+  end
+end

data/lib/sdkey/crypto/encoding.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Sdkey
+  module Crypto
+    # Base64 helpers (standard and URL-safe).
+    module Encoding
+      module_function
+
+      def bytes_to_base64(data)
+        Base64.strict_encode64(data.b)
+      end
+
+      def base64_to_bytes(b64)
+        normalized = b64.tr("-_", "+/")
+        pad = (4 - (normalized.length % 4)) % 4
+        Base64.decode64(normalized + ("=" * pad)).b
+      end
+    end
+  end
+end

data/lib/sdkey/crypto/seal.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+require_relative "canonical_json"
+require_relative "constants"
+require_relative "encoding"
+
+module Sdkey
+  module Crypto
+    # Ed25519, HKDF session keys, and AES-GCM seal helpers.
+    module Seal
+      SealedEnvelope = Struct.new(:iv_b64, :ciphertext_b64, :tag_b64, keyword_init: true) do
+        def as_wire
+          {
+            "ivB64" => iv_b64,
+            "ciphertextB64" => ciphertext_b64,
+            "tagB64" => tag_b64
+          }
+        end
+      end
+
+      module_function
+
+      def import_public_key(public_key_b64)
+        raw = Encoding.base64_to_bytes(public_key_b64)
+        OpenSSL::PKey.new_raw_public_key("ED25519", raw)
+      end
+
+      def verify_signature(public_key, payload, signature_b64)
+        signature = Encoding.base64_to_bytes(signature_b64)
+        message = CanonicalJson.canonical_json(payload)
+        public_key.verify(nil, signature, message)
+      rescue OpenSSL::PKey::PKeyError, OpenSSL::OpenSSLError
+        false
+      end
+
+      def derive_session_aes_key(client_nonce:, server_nonce:, salt_b64:, app_id:)
+        ikm = client_nonce.b + server_nonce.b
+        salt = Encoding.base64_to_bytes(salt_b64)
+        info = "#{Constants::SESSION_HKDF_INFO_PREFIX}#{app_id}".b
+        OpenSSL::KDF.hkdf(
+          ikm,
+          salt: salt,
+          info: info,
+          length: Constants::SESSION_AES_KEY_BYTES,
+          hash: "SHA256"
+        )
+      end
+
+      def seal_aes_gcm(aes_key, plaintext)
+        iv = SecureRandom.random_bytes(Constants::AES_GCM_IV_BYTES)
+        cipher = OpenSSL::Cipher.new("aes-256-gcm")
+        cipher.encrypt
+        cipher.key = aes_key
+        cipher.iv = iv
+        ciphertext = cipher.update(plaintext.b) + cipher.final
+        tag = cipher.auth_tag(Constants::AES_GCM_TAG_BYTES)
+        SealedEnvelope.new(
+          iv_b64: Encoding.bytes_to_base64(iv),
+          ciphertext_b64: Encoding.bytes_to_base64(ciphertext),
+          tag_b64: Encoding.bytes_to_base64(tag)
+        )
+      end
+
+      def open_aes_gcm(aes_key, envelope)
+        if envelope.is_a?(SealedEnvelope)
+          iv_b64 = envelope.iv_b64
+          ciphertext_b64 = envelope.ciphertext_b64
+          tag_b64 = envelope.tag_b64
+        else
+          iv_b64 = envelope["ivB64"] || envelope[:ivB64] || envelope["iv_b64"] || envelope[:iv_b64]
+          ciphertext_b64 = envelope["ciphertextB64"] || envelope[:ciphertextB64] ||
+                           envelope["ciphertext_b64"] || envelope[:ciphertext_b64]
+          tag_b64 = envelope["tagB64"] || envelope[:tagB64] || envelope["tag_b64"] || envelope[:tag_b64]
+        end
+
+        iv = Encoding.base64_to_bytes(iv_b64)
+        ciphertext = Encoding.base64_to_bytes(ciphertext_b64)
+        tag = Encoding.base64_to_bytes(tag_b64)
+
+        cipher = OpenSSL::Cipher.new("aes-256-gcm")
+        cipher.decrypt
+        cipher.key = aes_key
+        cipher.iv = iv
+        cipher.auth_tag = tag
+        cipher.update(ciphertext) + cipher.final
+      end
+    end
+  end
+end

data/lib/sdkey/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Sdkey
+  # Protocol and transport errors for the SDKey client.
+  class Error < StandardError
+    attr_reader :code, :cause
+
+    def initialize(code, message, cause = nil)
+      super(message)
+      @code = code
+      @cause = cause
+    end
+  end
+
+  # Alias matching Python/TS naming in docs.
+  SdkeyError = Error
+end

data/lib/sdkey/types.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Sdkey
+  # Constructor options for {Client}.
+  SdkeyClientOptions = Struct.new(
+    :api_base_url,
+    :app_id,
+    :app_version,
+    :app_public_key_b64,
+    :http_post,
+    keyword_init: true
+  )
+
+  SessionState = Struct.new(
+    :session_id,
+    :aes_key,
+    :server_nonce_b64,
+    :hkdf_salt_b64,
+    keyword_init: true
+  )
+
+  ValidateResult = Struct.new(
+    :success,
+    :code,
+    :message,
+    :status,
+    :expires_at,
+    :subscription_tier,
+    :timestamp,
+    keyword_init: true
+  )
+
+  ClientAuthUser = Struct.new(
+    :id,
+    :username,
+    :email,
+    :application_id,
+    keyword_init: true
+  )
+
+  ClientAuthLicense = Struct.new(
+    :id,
+    :status,
+    :expires_at,
+    :subscription_tier,
+    keyword_init: true
+  )
+
+  ClientAuthSessionInfo = Struct.new(
+    :ip,
+    :hwid,
+    keyword_init: true
+  )
+
+  # Result of register / login / upgrade (plaintext client auth).
+  ClientAuthResult = Struct.new(
+    :success,
+    :code,
+    :error,
+    :session_token,
+    :expires_at,
+    :user,
+    :license,
+    :session,
+    keyword_init: true
+  )
+end

data/lib/sdkey/version.rb

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

data/lib/sdkey.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "sdkey/version"
+require_relative "sdkey/errors"
+require_relative "sdkey/types"
+require_relative "sdkey/crypto/constants"
+require_relative "sdkey/crypto/encoding"
+require_relative "sdkey/crypto/canonical_json"
+require_relative "sdkey/crypto/seal"
+require_relative "sdkey/client"
+
+# Official Ruby client for the SDKey license authentication protocol.
+module Sdkey
+  PROTOCOL_VERSION = Crypto::Constants::PROTOCOL_VERSION
+  CLOCK_SKEW_SECONDS = Crypto::Constants::CLOCK_SKEW_SECONDS
+  CLIENT_NONCE_BYTES = Crypto::Constants::CLIENT_NONCE_BYTES
+  SERVER_NONCE_BYTES = Crypto::Constants::SERVER_NONCE_BYTES
+  VALIDATE_NONCE_BYTES = Crypto::Constants::VALIDATE_NONCE_BYTES
+  AES_GCM_IV_BYTES = Crypto::Constants::AES_GCM_IV_BYTES
+  SESSION_AES_KEY_BYTES = Crypto::Constants::SESSION_AES_KEY_BYTES
+  SESSION_HKDF_INFO_PREFIX = Crypto::Constants::SESSION_HKDF_INFO_PREFIX
+  VALIDATE_FAILURE_CODES = Crypto::Constants::VALIDATE_FAILURE_CODES
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: sdkey
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- SDKeyDev
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: Sealed session protocol (Ed25519, HKDF, AES-256-GCM) plus plaintext client
+  auth.
+email:
+- support@sdkey.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- PROTOCOL.md
+- README.md
+- lib/sdkey.rb
+- lib/sdkey/client.rb
+- lib/sdkey/crypto/canonical_json.rb
+- lib/sdkey/crypto/constants.rb
+- lib/sdkey/crypto/encoding.rb
+- lib/sdkey/crypto/seal.rb
+- lib/sdkey/errors.rb
+- lib/sdkey/types.rb
+- lib/sdkey/version.rb
+homepage: https://github.com/SDKeyDev/sdkey-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/SDKeyDev/sdkey-ruby
+  source_code_uri: https://github.com/SDKeyDev/sdkey-ruby
+  changelog_uri: https://github.com/SDKeyDev/sdkey-ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby client for the SDKey license authentication protocol
+test_files: []