sqrl-core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ed49b9ca739655cee06b71573b4ef1c7f8c799e2a3692fb35e7dd0f1d80d212
+  data.tar.gz: a2a6f2e31558e35661eb5d882616c837d174359786a19f5e5ba85d03fb4326a6
+SHA512:
+  metadata.gz: d878db822fc637d3e9e9aa6a4c93b2b168c65a1432f4496b5dc013c1b16d4e7a0ee8acb946561091addc966e71479c00fd9467c8719e74454d3a46590c7ce456
+  data.tar.gz: 0c1ea6ad5a25c496b2bb43c871f5ce7355bd7143ae7cbcdb2c1bc33755952f8854ef6a4c1fa4d96bbf42ca40bcee13cf399c739b903f961460b3148d6e68cded

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0 — 2026-10-20
+
+First release.
+
+- Complete SQRL wire protocol: `query`, `ident`, `disable`, `enable`, `remove`, every TIF
+  bit, `ask`/`btn` with a server-side accept-list, `sin`/`ins`/`pins`, previous identities
+  and re-keying, `x=` path extension, Alt-IDs, `can=`, Client Provided Session.
+- Cryptography on OpenSSL only: EnHash, EnScrypt, AES-256-GCM, Ed25519, X25519.
+- S4 identity files (type 1/2/3, binary and text), rescue codes, password changes,
+  re-keying, base56 textual identities; all published test vectors pass and GRC's reference
+  client request bodies are reproduced byte for byte.
+- `SQRL::Session`: the client transaction state machine; `sqrl://` (HTTPS) only unless
+  `insecure: true` (loopback testing mode).
+- `SQRL::Server::Handler` with `Config`, three store interfaces, in-memory and Redis store
+  sets, one-time CPS tokens, nut single use, `server=` echo verification, IP matching
+  (`require_ip_match`, on by default), `allowed_hosts`, `prune_every`, `before_issue` /
+  `before_handle` hooks and `SQRL::Server::RateLimited`.
+- A shared store-contract spec for store implementations.
+- Requires Ruby 3.1 or newer.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel P. Clark
+
+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/README.md

@@ -0,0 +1,164 @@
+# sqrl-core
+
+A pure-Ruby implementation of [SQRL](https://www.grc.com/sqrl/sqrl.htm) (Secure Quick
+Reliable Login): the cryptography, the identity key derivations and identity lock, S4
+identity storage, the base56 textual identity, the client transaction state machine and a
+server-side protocol handler with pluggable stores. Everything the other `sqrl-*` gems build
+on. The only runtime dependency is Ruby's bundled `openssl` gem (3.0 or newer, which ships
+with Ruby 3.1+).
+
+## Install
+
+```ruby
+gem "sqrl-core"
+```
+
+```ruby
+require "sqrl/core"   # or require "sqrl"
+```
+
+## What it implements
+
+- **Wire protocol**: `query`, `ident`, `disable`, `enable`, `remove`; `ids`/`pids`/`urs`
+  signatures over `client || server`; every TIF bit, with undefined bits aborting the
+  client; `ask`/`btn` (with a server-side accept-list); `sin`/`ins`/`pins`; previous
+  identities and re-keying; `sqrlonly`/`hardlock`/`cps`/`suk`/`noiptest`; the `x=` path
+  extension; Alt-IDs; `can=`; Client Provided Session (`url=`). The request bodies
+  reproduce GRC's reference client log byte for byte.
+- **Cryptography**: EnHash, EnScrypt (iteration- and duration-based), AES-256-GCM,
+  Ed25519, X25519, all through OpenSSL.
+- **Identities**: IMK/ILK/IUK, per-site keys, the identity lock (RLK/SUK/VUK/URSK),
+  indexed secrets; S4 identity files (type 1, 2 and 3 blocks, `sqrldata` binary and
+  `SQRLDATA` text), rescue codes, password changes, re-keying with up to four previous
+  identities; the base56 textual identity with check characters.
+- **Server engine**: `SQRL::Server::Handler`, a port of the reference server whose state
+  sits behind three store interfaces, with nut single use, `server=` echo verification,
+  IP matching, identity binding, superseded handling, one-time CPS tokens, rate-limit and
+  prune hooks. In-memory and Redis store sets ship here; ActiveRecord and cache sets live
+  in `sqrl-rails`.
+
+## Client: one transaction
+
+```ruby
+identity = SQRL::UnlockedIdentity.from_iuk(SecureRandom.random_bytes(32))
+session  = SQRL::Session.new(identity, "sqrl://example.com/sqrl/cli?nut=…",
+                             options: SQRL::ClientOptions.new(cps: true))
+
+request = session.query                 # => Request(url:, body:, command:, client_text:)
+session.feed(http_post(request))        # the server's base64url body
+session.state                           # => :unknown | :known | :previous_known | :transient | :superseded | :failed
+session.pending_ask                     # => SQRL::Ask or nil; answer with session.set_button(1)
+
+request = session.ident                 # creates the account, logs in, or re-keys, as the answer dictates
+session.feed(http_post(request))
+session.cps_url                         # validated https URL to send the browser to (nil without cps)
+
+session.disable                         # needs only ids
+session.enable(iuk)                     # needs the IUK (rescue code) for urs
+session.remove(iuk)
+```
+
+`SQRL::URL.parse` gives the site key (`site_key_bytes(alt_id)`), the POST URL and the
+cancel URL. Only `sqrl://` (HTTPS) is accepted; `SQRL::Session.new(..., insecure: true)`
+additionally accepts the draft-era `qrl://` for loopback hosts, which exists solely for the
+browser extension's local test server.
+
+## Server
+
+```ruby
+config  = SQRL::Server::Config.new(host: "example.com")
+handler = SQRL::Server::Handler.new(config: config, stores: SQRL::Server::Memory.stores)
+
+login  = handler.new_login_url(ip: request_ip, return_to: "/account")
+login.url                               # "sqrl://example.com/sqrl/cli?nut=…" for the page and the QR code
+login.pending_login_id                  # keep in the browser session; never give it to the client
+
+result = handler.handle(nut: params["nut"], body: raw_post_body, ip: request_ip)
+result.body                             # base64url text to return with status 200
+result.authenticated?                   # true after a successful ident/enable
+result.cps_url                          # the one-time url= handed to the client, when it asked for cps
+
+handler.status(pending_login_id)        # {authenticated:, idk:} for the browser's poller
+handler.claim_cps(token)                # PendingLogin or nil; single use, expires after cps_token_ttl
+handler.prune!
+```
+
+### Config options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `host` | `nil` | public host (with port) placed in `sqrl://` URLs; identities derive from it, so set it in production |
+| `path` | `/sqrl/cli` | the endpoint path, also used in `qry=` |
+| `callback_path` | `/sqrl/callback` | where the default CPS `url=` points (plus `?t=TOKEN`) |
+| `insecure_http` | `false` | loopback-only testing mode issuing `qrl://`; refused for other hosts, warns once |
+| `path_extension` | `nil` | `x=N`: include the first N characters of the path in the site key |
+| `nut_ttl` | `300` | seconds a login-page nut stays valid |
+| `cps_token_ttl` | `60` | seconds a CPS token stays claimable |
+| `require_ip_match` | `true` | refuse a client whose IP differs from the browser's unless it sends `noiptest` |
+| `ask` | `nil` | `SQRL::Ask` (or a callable receiving a context hash) posed in the query reply; `accept:` limits the buttons that let `ident` proceed |
+| `sin` | `nil` | secret-index challenge (string or callable); the client answers with `ins`/`pins` |
+| `on_unknown_identity` | `:create` | `:create` an association, `:link` only when the pending login carries a `link_user_ref`, or `:refuse` |
+| `on_authenticated` | `nil` | callable `(identity, pending_login, command)` after a successful command |
+| `cps_url` | `nil` | callable `(token, pending_login) -> URL` replacing the default |
+| `allowed_hosts` | `nil` | strings or regexps the request host must match when `host` is derived |
+| `prune_every` | `1000` | call `prune!` opportunistically every N requests (`nil` disables) |
+| `before_issue` / `before_handle` | `nil` | hooks that may raise `SQRL::Server::RateLimited` |
+| `clock` / `logger` | `nil` | injectable clock (tests) and logger |
+
+### Stores
+
+The handler keeps every record behind three small interfaces, documented in
+`SQRL::Server::NutStore`, `IdentityStore` and `PendingLoginStore`:
+
+| Store | Records | Must be atomic |
+| --- | --- | --- |
+| nuts | one per issued nut: pending login, expected `server=` echo, IP, bound identity, expiry | `consume` (exactly one caller wins) |
+| identities | one per association: `idk`, `suk`, `vuk`, flags, `ins`, login count, `user_ref` | `rekey` |
+| pending logins | one per login page view: authenticated identity, `ip_matched`, ask state, CPS token, `return_to` | `claim_cps_token` (single use) |
+
+Implementations: `SQRL::Server::Memory.stores` (per process; development and tests),
+`SQRL::Server::Redis.stores(redis: Redis.new)` (requires the `redis` gem; `GETDEL` and Lua
+scripts for the single-use operations, TTLs for expiry), and in `sqrl-rails`
+`SQRL::Rails::Stores::ActiveRecord` and `::Cache`. A shared "a SQRL store set" spec under
+`spec/support/store_contract.rb` exercises any implementation, including concurrent
+consume and claim races.
+
+## Identities
+
+```ruby
+file = SQRL::S4Identity.parse(File.binread("me.sqrl"))     # binary "sqrldata" or "SQRLDATA" text
+unlocked = file.unlock("correct horse")                      # EnScrypt over the type 1 block
+iuk = file.unlock_iuk("1198-8748-7132-2838-8318-7570")        # the rescue code frees the IUK
+file.to_text                                                 # "SQRLDATA…" export
+SQRL::Textual.encode(file.rescue_only.to_bytes)              # base56 textual identity
+
+new_file = SQRL::S4Identity.create(iuk, "password", SQRL::Storage.generate_rescue_code)
+new_file.set_password(unlocked, "new password")
+new_file.rekey(unlocked, iuk, new_iuk, "password", new_rescue_code)
+```
+
+EnScrypt cost: one scrypt iteration (N=512, r=256) takes roughly 45 ms with OpenSSL 3, so
+unlocking a real identity file takes a few seconds and creating one takes the configured
+password and rescue durations. Tests and bots use `SQRL::UnlockedIdentity.from_iuk`
+directly and skip EnScrypt.
+
+## Test vectors
+
+`SQRL::TestVectors` carries every published vector: the Spec-Vectors-Identity (password,
+rescue code, textual identity, IMK, per-site keys), GRC's `SQRL.log` query and ident
+bodies, the EnScrypt vectors from grc.com and the newsgroup, the base56 examples validated
+against GRC's client, and the Android client's sample identity file. The specs assert the
+request bodies byte for byte.
+
+## Authority and credits
+
+GRC's specification documents (*SQRL Explained*, *Operating Details* v1.01, *Cryptography*
+v1.04, *On The Wire* v1.07) are the authority. The Rust implementation in
+[SQRL-extension](https://github.com/danielpclark/SQRL-extension) is one careful reading of
+them and the practical source for this port; where the two differ, the documents win. SQRL
+was designed by Steve Gibson of Gibson Research Corporation, who placed the specification in
+the public domain.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/sqrl/core.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name: `gem "sqrl-core"` is required as `require "sqrl/core"`
+# (the dash maps to a directory, as for every extension-style gem name). It loads the whole
+# library; `require "sqrl"` remains available and loads the same thing.
+require_relative "../sqrl"

data/lib/sqrl/crypto.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module SQRL
+  # Cryptographic primitives used by SQRL.
+  #
+  # * EnHash: 16 chained iterations of SHA-256 whose outputs are XORed together.
+  # * EnScrypt: scrypt (N = 2**log_n, r = 256, p = 1, dkLen = 32) chained and XORed over
+  #   many iterations, either for a fixed iteration count or for a fixed duration.
+  # * HMAC-SHA256, AES-256-GCM, Ed25519 and X25519 via OpenSSL.
+  #
+  # All byte arguments and results are binary-encoded Strings.
+  module Crypto
+    # scrypt +r+ parameter mandated by SQRL.
+    SCRYPT_R = 256
+    # scrypt +p+ parameter mandated by SQRL.
+    SCRYPT_P = 1
+    # Default scrypt log2(N) used by SQRL clients (N = 512).
+    DEFAULT_LOG_N = 9
+
+    module_function
+
+    # SHA-256 digest.
+    # @param data [String] bytes
+    # @return [String] 32 binary bytes
+    def sha256(data)
+      OpenSSL::Digest.new("SHA256").digest(data)
+    end
+
+    # HMAC-SHA256.
+    # @param key [String] key bytes
+    # @param data [String] message bytes
+    # @return [String] 32 binary bytes
+    def hmac_sha256(key, data)
+      OpenSSL::HMAC.digest("SHA256", key, data)
+    end
+
+    # EnHash: SHA-256 applied 16 times in a chain; all 16 outputs XORed together.
+    def enhash(input)
+      current = sha256(input)
+      acc = current.bytes
+      15.times do
+        current = sha256(current)
+        current.each_byte.with_index { |b, i| acc[i] ^= b }
+      end
+      acc.pack("C*")
+    end
+
+    # One raw scrypt invocation with SQRL's parameters (r = 256, p = 1, dkLen = 32).
+    def scrypt_once(password, salt, log_n = DEFAULT_LOG_N)
+      OpenSSL::KDF.scrypt(password.b, salt: salt.b, N: 1 << log_n, r: SCRYPT_R, p: SCRYPT_P, length: 32)
+    rescue OpenSSL::KDF::KDFError => e
+      raise CryptoError, "scrypt unavailable or failed (FIPS mode?): #{e.message}"
+    end
+
+    # EnScrypt with a fixed iteration count.
+    #
+    # The first iteration uses the caller-supplied salt; each subsequent iteration uses the
+    # previous iteration's output as its salt, and the result is the XOR of every
+    # iteration's output. The block, if given, is called after each iteration with the
+    # number of iterations completed.
+    def enscrypt_iterations(password, salt, log_n, iterations)
+      iterations = [iterations.to_i, 1].max
+      key = scrypt_once(password, salt, log_n)
+      acc = key.bytes
+      yield 1 if block_given?
+      (1...iterations).each do |i|
+        key = scrypt_once(password, key, log_n)
+        key.each_byte.with_index { |b, j| acc[j] ^= b }
+        yield i + 1 if block_given?
+      end
+      acc.pack("C*")
+    end
+
+    # EnScrypt for (at least) +duration_ms+ milliseconds. +now_ms+ is a callable returning
+    # a monotonic millisecond clock (injectable for tests). Returns +[key, iterations]+;
+    # the iteration count must be stored so the key can be re-derived with
+    # enscrypt_iterations. The block, if given, receives +(elapsed_ms, duration_ms)+.
+    def enscrypt_duration(password, salt, log_n, duration_ms, now_ms: method(:monotonic_ms))
+      start = now_ms.call
+      key = scrypt_once(password, salt, log_n)
+      acc = key.bytes
+      iterations = 1
+      elapsed = [now_ms.call - start, 0].max
+      yield elapsed, duration_ms if block_given?
+      while elapsed < duration_ms && iterations < 0xFFFF_FFFF
+        key = scrypt_once(password, key, log_n)
+        key.each_byte.with_index { |b, j| acc[j] ^= b }
+        iterations += 1
+        elapsed = [now_ms.call - start, 0].max
+        yield elapsed, duration_ms if block_given?
+      end
+      [acc.pack("C*"), iterations]
+    end
+
+    # @return [Integer] a monotonic clock in milliseconds (the default +now_ms+ for {enscrypt_duration})
+    def monotonic_ms
+      (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
+    end
+
+    # AES-256-GCM encryption. Returns ciphertext followed by the 16-byte tag.
+    def aes_gcm_encrypt(key, iv, aad, plaintext)
+      cipher = OpenSSL::Cipher.new("aes-256-gcm").encrypt
+      cipher.key = key
+      cipher.iv = iv
+      cipher.auth_data = aad
+      out = cipher.update(plaintext.b) + cipher.final
+      out + cipher.auth_tag(16)
+    end
+
+    # AES-256-GCM decryption of +ciphertext || tag+. Raises CryptoError when the tag does
+    # not verify.
+    def aes_gcm_decrypt(key, iv, aad, ciphertext_and_tag)
+      raise CryptoError, "ciphertext too short" if ciphertext_and_tag.bytesize < 16
+
+      ciphertext = ciphertext_and_tag.byteslice(0, ciphertext_and_tag.bytesize - 16)
+      tag = ciphertext_and_tag.byteslice(-16, 16)
+      cipher = OpenSSL::Cipher.new("aes-256-gcm").decrypt
+      cipher.key = key
+      cipher.iv = iv
+      cipher.auth_tag = tag
+      cipher.auth_data = aad
+      cipher.update(ciphertext) + cipher.final
+    rescue OpenSSL::Cipher::CipherError
+      raise CryptoError, "authentication tag mismatch"
+    end
+
+    # Ed25519 signing key object from a 32-byte seed.
+    def ed25519_from_seed(seed)
+      raise CryptoError, "ed25519 seed must be 32 bytes" unless seed.bytesize == 32
+
+      OpenSSL::PKey.new_raw_private_key("ED25519", seed.b)
+    end
+
+    # Public key bytes of the Ed25519 key derived from +seed+.
+    def ed25519_public(seed)
+      ed25519_from_seed(seed).raw_public_key
+    end
+
+    # Sign +msg+ with the Ed25519 key derived from +seed+; returns the 64-byte signature.
+    def ed25519_sign(seed, msg)
+      ed25519_from_seed(seed).sign(nil, msg.b)
+    end
+
+    # Verify an Ed25519 signature. Returns true/false; never raises on bad input.
+    def ed25519_verify(public_key, msg, signature)
+      return false unless public_key.bytesize == 32 && signature.bytesize == 64
+
+      OpenSSL::PKey.new_raw_public_key("ED25519", public_key.b).verify(nil, signature.b, msg.b)
+    rescue OpenSSL::PKey::PKeyError
+      false
+    end
+
+    # X25519 public key for a scalar (scalar multiplication of the base point).
+    def x25519_base(scalar)
+      OpenSSL::PKey.new_raw_private_key("X25519", scalar.b).raw_public_key
+    end
+
+    # X25519 Diffie-Hellman: +scalar * point+.
+    def x25519(scalar, point)
+      OpenSSL::PKey.new_raw_private_key("X25519", scalar.b)
+                   .derive(OpenSSL::PKey.new_raw_public_key("X25519", point.b))
+    end
+  end
+end

data/lib/sqrl/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SQRL
+  # Base class for every error raised by the SQRL gems.
+  class Error < StandardError; end
+
+  # Input could not be parsed (bad base64, bad header, bad length...).
+  class FormatError < Error; end
+
+  # A cryptographic check failed (bad password, bad rescue code, bad signature...).
+  class CryptoError < Error; end
+
+  # The protocol state does not permit the requested operation.
+  class ProtocolError < Error; end
+end

data/lib/sqrl/identity.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module SQRL
+  # Key derivations that flow from the Identity Unlock Key, and the unlocked in-memory
+  # identity.
+  #
+  # * IUK - Identity Unlock Key: the 256-bit root secret, only available after the user
+  #   enters the rescue code. Needed to enable/remove an account and to re-key.
+  # * IMK - Identity Master Key = EnHash(IUK). Derives every per-site key.
+  # * ILK - Identity Lock Key = X25519(IUK, basepoint). Given to sites via SUK/VUK.
+  # * Per-site seed = HMAC-SHA256(key = IMK, msg = site key string); the Ed25519 key pair
+  #   from that seed is the site identity (idk / ids).
+  # * INK = EnHash(per-site seed); ins = HMAC-SHA256(INK, sin).
+  # * RLK/SUK/VUK - per-account identity lock values, see Identity.make_server_lock.
+  # * URSK - Unlock Request Signing Key = Ed25519 seed X25519(IUK, SUK).
+  module Identity
+    # The identity-lock values a client sends to a server when creating or re-keying an
+    # account.
+    ServerLock = Struct.new(:suk, :vuk, keyword_init: true)
+
+    module_function
+
+    # Identity Master Key = EnHash(IUK).
+    # @param iuk [String] 32 bytes
+    # @return [String] 32 bytes
+    def imk_from_iuk(iuk)
+      Crypto.enhash(iuk)
+    end
+
+    # Identity Lock Key = X25519(IUK, basepoint).
+    # @param iuk [String] 32 bytes
+    # @return [String] 32 bytes
+    def ilk_from_iuk(iuk)
+      Crypto.x25519_base(iuk)
+    end
+
+    # Per-site Ed25519 seed = HMAC-SHA256(key = IMK, msg = site key).
+    # @param imk [String] 32 bytes
+    # @param site_key [String] see {SQRL::URL#site_key_bytes}
+    # @return [String] 32 bytes
+    def site_seed(imk, site_key)
+      Crypto.hmac_sha256(imk, site_key)
+    end
+
+    # Indexed-secret response: ins = HMAC-SHA256(key = EnHash(site seed), msg = sin).
+    def indexed_secret(site_seed, sin)
+      Crypto.hmac_sha256(Crypto.enhash(site_seed), sin)
+    end
+
+    # Generate SUK/VUK for an Identity Lock Key using a fresh Random Lock Key.
+    def make_server_lock(ilk, rlk = Util.random_bytes(32))
+      suk = Crypto.x25519_base(rlk)
+      dhk = Crypto.x25519(rlk, ilk)
+      vuk = Crypto.ed25519_public(dhk)
+      Util.wipe(dhk)
+      ServerLock.new(suk: suk, vuk: vuk)
+    end
+
+    # Unlock Request Signing Key seed: X25519(IUK, SUK). Its Ed25519 public key equals the
+    # VUK the server stored, which lets the server verify a +urs+ signature.
+    def unlock_request_seed(iuk, suk)
+      Crypto.x25519(iuk, suk)
+    end
+  end
+
+  # A decrypted identity held in memory. +previous_iuks+ are ordered most-recent first.
+  class UnlockedIdentity
+    attr_reader :imk, :ilk, :previous_iuks
+
+    def initialize(imk, ilk, previous_iuks = [])
+      raise ArgumentError, "imk must be 32 bytes" unless imk.bytesize == 32
+      raise ArgumentError, "ilk must be 32 bytes" unless ilk.bytesize == 32
+
+      @imk = imk.b.freeze
+      @ilk = ilk.b.freeze
+      @previous_iuks = previous_iuks.map { |k| k.b.freeze }.freeze
+    end
+
+    # Build a brand-new identity from an Identity Unlock Key.
+    def self.from_iuk(iuk, previous_iuks = [])
+      new(Identity.imk_from_iuk(iuk), Identity.ilk_from_iuk(iuk), previous_iuks)
+    end
+
+    # Per-site Ed25519 seed for the current identity.
+    # @param site_key [String]
+    # @return [String] 32 bytes
+    def site_seed(site_key)
+      Identity.site_seed(@imk, site_key)
+    end
+
+    # Per-site Ed25519 public key (idk) for the current identity.
+    def site_public_key(site_key)
+      Crypto.ed25519_public(site_seed(site_key))
+    end
+
+    # @return [Integer] number of previous identities available for +pidk+
+    def previous_count
+      @previous_iuks.length
+    end
+
+    # Per-site Ed25519 seed for previous identity +index+ (0 = most recent), or nil.
+    def previous_site_seed(index, site_key)
+      iuk = @previous_iuks[index]
+      return nil unless iuk
+
+      Identity.site_seed(Identity.imk_from_iuk(iuk), site_key)
+    end
+
+    # Per-site public key (pidk) for previous identity +index+, or nil.
+    def previous_site_public_key(index, site_key)
+      seed = previous_site_seed(index, site_key)
+      seed && Crypto.ed25519_public(seed)
+    end
+
+    # Generate the SUK/VUK pair for a new account association on a server.
+    def make_lock
+      Identity.make_server_lock(@ilk)
+    end
+
+    # Unlock request signing seed using a previous identity's IUK (re-keying an account
+    # still associated with that previous identity).
+    def previous_unlock_request_seed(index, suk)
+      iuk = @previous_iuks[index]
+      iuk && Identity.unlock_request_seed(iuk, suk)
+    end
+
+    # Whether +iuk+ is the IUK this identity was derived from.
+    def matches_iuk?(iuk)
+      Util.secure_compare(Identity.imk_from_iuk(iuk), @imk)
+    end
+
+    # 16 hex characters identifying the identity without revealing key material.
+    def fingerprint
+      Util.hex_encode(Crypto.sha256("sqrl-fingerprint#{@imk}"))[0, 16]
+    end
+
+    # @return [String] a short description with secret material redacted
+    def inspect
+      "#<SQRL::UnlockedIdentity fingerprint=#{fingerprint} previous=#{previous_count}>"
+    end
+    alias to_s inspect
+  end
+end