nkeys-rb 0.4.5.0-arm-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f780464183e5852119c9a266f95ff9f5997e6f4946f4b2772aaf98219f9a49a
+  data.tar.gz: e490e1a316931b12938dda7c981cab573a952ad240578430e5bf96106d4f2eaa
+SHA512:
+  metadata.gz: 788180ecd8fdd6e907661148f20264a9efe987a457ddce2a4a63054df406fb62bbe55d05be3c17101e1782f495815722b8f7b6794cae61faa2c7fbd0c06a2f54
+  data.tar.gz: bd54abf9d2ac2f0fdc098176f527ea70582cdb9c94354b511831325f772fb02237864e4b3a97e0ffea4bbbb3cb51bac4d8e8faa36d2bb700469f40e5300effee

data/README.md

@@ -0,0 +1,121 @@
+# nkeys-rb
+
+Ruby bindings for the Rust [`nkeys`](https://crates.io/crates/nkeys) crate.
+
+NKeys is the NATS key format: an Ed25519 keypair whose public half is
+base32-encoded behind a prefix byte naming its role (`A...` account, `U...`
+user, `N...` server), with a CRC-16 check — plus a separate x25519 "xkey"
+(`X...`) used for encryption rather than signing.
+
+## Why this exists
+
+There is already an `nkeys` gem on rubygems.org. It stopped at 0.1.0 and is
+incomplete in two ways that matter to anything implementing NATS
+[auth callout](https://docs.nats.io/learn/security/auth-callout):
+
+1. Its `public_key` hardcodes the **user** prefix byte, so an account keypair
+   reports a `U...` key rather than the `A...` a server config names in
+   `auth_callout.issuer`. A verdict signed by a key the server cannot name is
+   refused.
+2. It has no concept of **xkeys** at all — no prefix, no key type, no
+   seal/open — so the encrypted form of auth callout cannot be spoken.
+
+Hence the name: `nkeys-rb`, because `nkeys` is taken.
+
+This gem is only the key primitives. Building the NATS JWTs an auth callout
+answers with is ordinary Ruby work (JSON, base64url, `SHA512-256`, base32) and
+deliberately lives in the caller.
+
+## Usage
+
+```ruby
+require "nkeys"
+
+account = NKeys::KeyPair.generate("account")
+account.public_key            # => "A..."  — goes in the server config
+account.seed                  # => "SA..." — goes in a secret
+
+signature = account.sign("payload")
+account.verify("payload", signature)   # => true
+
+# Verify-only, from a public key alone.
+NKeys::KeyPair.from_public_key(account.public_key).verify("payload", signature)
+
+# xkeys encrypt rather than sign.
+service = NKeys::XKey.generate
+server  = NKeys::XKey.generate
+
+sealed = server.seal("credentials", service.public_key)
+service.open(sealed, server.public_key)   # => "credentials"
+```
+
+Roles accepted by `KeyPair.generate`: `account`, `user`, `server`, `operator`,
+`cluster`.
+
+## Development
+
+The repository ships a `flake.nix` with Ruby, the Rust toolchain and the
+libclang that `rb_sys`' bindgen needs:
+
+```bash
+direnv allow          # or: nix develop
+bundle install
+bundle exec rake compile
+bin/test
+```
+
+## Versioning
+
+The gem version is `<nkeys crate version>.<our release>`:
+
+```
+nkeys-rb 0.4.5.0
+         └─┬─┘ └ our release against that crate
+           └ the Rust nkeys crate this wraps
+```
+
+So `nkeys-rb 0.4.5.2` is the third build of this gem against `nkeys 0.4.5`. The
+crate is pinned exactly in `ext/nkeys/Cargo.toml` (`version = "=0.4.5"`) so the
+claim cannot quietly become false — `bin/increment-version` moves both together.
+
+Depend on it pessimistically to the fourth segment (`~> 0.4.5.0`) and you track
+our fixes without silently moving to a new crate.
+
+## Releasing
+
+Consumers must never need Rust. That is the whole point: `bundle install` should
+find a gem for its platform with the `.so` already inside, rather than a source
+gem that shells out to `cargo`.
+
+A release is TWO kinds of gem for the same version — the source gem (the
+fallback for any platform not precompiled) and one precompiled gem per platform.
+CI builds the second kind; `bin/release-gem` builds the first and pushes both.
+
+```bash
+bin/increment-version           # bump our segment: 0.4.5.0 -> 0.4.5.1
+# ...or, to track a new crate release (also repins ext/nkeys/Cargo.toml):
+# bin/increment-version 0.4.6   # -> 0.4.6.0
+git commit -am "Bump to $(ruby -Ilib -rnkeys/version -e 'print NKeys::VERSION')"
+git push origin main            # cross-compile.yml builds the platform gems
+# ...wait for that run to go green...
+bin/release-gem                 # downloads them, builds the source gem, pushes all
+```
+
+`bin/release-gem` refuses to run if the local version is not ahead of what is
+already on RubyGems, and if the latest green CI run built a different version it
+says so rather than publishing a mismatched set. It tolerates gems that are
+already published, so a release that dies partway through can simply be re-run.
+
+It needs the [GitHub CLI](https://cli.github.com) to fetch the CI artifacts.
+
+## Testing
+
+Specs are co-located with the code they cover, in `__END__` blocks, and run with
+[scampi](https://github.com/general-intelligence-systems/scampi):
+
+```bash
+bin/test
+```
+
+`bundle exec lefthook install` wires that plus a trufflehog secret scan into a
+pre-commit hook.

data/lib/nkeys/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module NKeys
+  # <nkeys crate version>.<our release>. The first three segments say which
+  # version of the Rust crate this gem wraps; the fourth is ours, bumped for
+  # changes on the Ruby side against that same crate. Managed by
+  # bin/increment-version -- edit that, not this.
+  VERSION = "0.4.5.0"
+end

data/lib/nkeys.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# NATS NKeys for Ruby, over the Rust `nkeys` crate.
+#
+# The classes (NKeys::KeyPair, NKeys::XKey) are defined by the native
+# extension's #[magnus::init]; this file only locates and requires the compiled
+# object. See ext/nkeys/src/lib.rs for what each method does and why this is a
+# binding rather than a pure-Ruby implementation.
+#
+#   account = NKeys::KeyPair.generate("account")
+#   account.public_key                  # => "A..."
+#   account.seed                        # => "SA..."
+#   account.sign("payload")             # => raw Ed25519 signature bytes
+#
+#   xkey  = NKeys::XKey.generate
+#   xkey.public_key                     # => "X..."
+#   sealed = xkey.seal("secret", recipient_public_key)
+#   xkey.open(sealed, sender_public_key)
+
+require_relative "nkeys/version"
+
+module NKeys
+end
+
+# Precompiled ("fat") gems ship one .so per Ruby minor version under a versioned
+# subdir (lib/nkeys/3.3/nkeys_rb.so). A locally source-compiled build lands flat,
+# in lib/nkeys/. Try the versioned path first, then fall back to the flat one.
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require_relative "nkeys/#{Regexp.last_match(1)}/nkeys_rb"
+rescue LoadError
+  require_relative "nkeys/nkeys_rb"
+end
+
+__END__
+  describe "NKeys::KeyPair" do
+    it "prefixes the public key by role" do
+      # The whole reason this binding exists: the pure-Ruby nkeys gem reports a
+      # U... key for every role, so an account key could not be named in a
+      # server's auth_callout.issuer.
+      NKeys::KeyPair.generate("account").public_key.should.start_with "A"
+      NKeys::KeyPair.generate("user").public_key.should.start_with "U"
+      NKeys::KeyPair.generate("server").public_key.should.start_with "N"
+    end
+
+    it "rejects an unknown role" do
+      lambda { NKeys::KeyPair.generate("wombat") }.should.raise(ArgumentError)
+    end
+
+    it "round-trips through its seed" do
+      original = NKeys::KeyPair.generate("account")
+      restored = NKeys::KeyPair.from_seed(original.seed)
+
+      # A seed carries its own role, so the restored key keeps the A... prefix
+      # without being told which role it was.
+      restored.public_key.should == original.public_key
+    end
+
+    it "signs and verifies" do
+      key = NKeys::KeyPair.generate("account")
+      signature = key.sign("payload")
+
+      key.verify("payload", signature).should == true
+      key.verify("tampered", signature).should == false
+    end
+
+    it "verifies with a public-key-only keypair" do
+      key = NKeys::KeyPair.generate("account")
+      signature = key.sign("payload")
+
+      NKeys::KeyPair.from_public_key(key.public_key).verify("payload", signature).should == true
+    end
+
+    it "cannot sign with a public-key-only keypair" do
+      key = NKeys::KeyPair.from_public_key(NKeys::KeyPair.generate("account").public_key)
+
+      lambda { key.sign("payload") }.should.raise(RuntimeError)
+    end
+  end
+
+  describe "NKeys::XKey" do
+    it "prefixes the public key with X" do
+      NKeys::XKey.generate.public_key.should.start_with "X"
+    end
+
+    it "round-trips a sealed message between two xkeys" do
+      # The shape auth callout uses: the server seals a request to the service's
+      # xkey, and the service seals its response back to the server's.
+      server  = NKeys::XKey.generate
+      service = NKeys::XKey.generate
+
+      sealed = server.seal("credentials", service.public_key)
+      service.open(sealed, server.public_key).should == "credentials"
+    end
+
+    it "refuses to open a message sealed for someone else" do
+      server    = NKeys::XKey.generate
+      service   = NKeys::XKey.generate
+      stranger  = NKeys::XKey.generate
+
+      sealed = server.seal("credentials", service.public_key)
+
+      lambda { stranger.open(sealed, server.public_key) }.should.raise(RuntimeError)
+    end
+
+    it "round-trips through its seed" do
+      original = NKeys::XKey.generate
+      restored = NKeys::XKey.from_seed(original.seed)
+
+      restored.public_key.should == original.public_key
+    end
+  end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: nkeys-rb
+version: !ruby/object:Gem::Version
+  version: 0.4.5.0
+platform: arm-linux
+authors:
+- Nathan Kidd
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: scampi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: lefthook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: 'NATS NKeys for Ruby, as a native extension over the Rust `nkeys` crate:
+  Ed25519 keypairs across every key role, and the x25519 XKey sealing used by NATS
+  auth callout. Named nkeys-rb because the plain `nkeys` gem name is taken by an unrelated
+  pure-Ruby implementation.'
+email:
+- nathankidd@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/nkeys.rb
+- lib/nkeys/3.3/nkeys_rb.so
+- lib/nkeys/3.4/nkeys_rb.so
+- lib/nkeys/4.0/nkeys_rb.so
+- lib/nkeys/version.rb
+homepage: https://github.com/n-at-han-k/nkeys-rb
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/n-at-han-k/nkeys-rb
+  source_code_uri: https://github.com/n-at-han-k/nkeys-rb
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Ruby bindings for the Rust nkeys crate.
+test_files: []