secretspec 0.13.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dc73c5ea8c78355e47695fa927734801e216aa8030a5ccc4a6d302b001016395
+  data.tar.gz: 22617049b8d9524dbf3ec9b618d288dc35a33ecfc4a50da093c09cf168ceaf7d
+SHA512:
+  metadata.gz: 376fe5488f605295ad89700536a691eca4454096a0f6db26b622ac3152447326d8bc9dc87f2f31100558622a1fb4e16fa44f15b718fc119ec99e5a607c456c7a
+  data.tar.gz: fbd4e2b1412b451bf4b87ec538b1faa439b8f2e0aee9880332833f98593316e22a6b243fa16ab1d6e608989ec65ac8a0dbb58c8183dd43981c255c036b371828

data/README.md

@@ -0,0 +1,47 @@
+# secretspec (Ruby SDK)
+
+Ruby bindings for [SecretSpec](https://secretspec.dev/), a declarative secrets
+manager. A thin client over the `secretspec-ffi` C ABI, statically linked into a
+native C extension at build time (no runtime library to locate). Resolution
+happens in the Rust core, so the SDK inherits every provider with no Ruby-side
+logic.
+
+```ruby
+require "secretspec"
+
+resolved = Secretspec::SecretSpec.builder
+                                 .with_provider("keyring://")
+                                 .with_profile("production")
+                                 .with_reason("boot web app")
+                                 .load
+
+puts resolved.provider, resolved.profile
+db = resolved.secrets["DATABASE_URL"]
+puts db.get             # the value, or the file path for as_path secrets
+resolved.set_as_env!    # export everything into ENV
+```
+
+A missing required secret raises `Secretspec::MissingRequiredError`; any other
+failure raises `Secretspec::Error` (with a stable `#kind`).
+
+## Cleanup
+
+`as_path` secrets are materialized to temp files that outlive the call. Pass a
+block to `load` (which closes automatically) or call `resolved.close` when done
+so the secret files do not accumulate in the temp dir.
+
+## Value-free report
+
+`report` returns the inventory/preflight view: per-secret status and provenance,
+never a value. Unlike `load`, it does not raise when a required secret is missing
+— it appears as a `SecretReport` with status `"missing_required"`.
+
+```ruby
+report = Secretspec::SecretSpec.builder.with_profile("production").report
+report.secrets.each { |s| puts [s.name, s.status, s.required].join(" ") }
+```
+
+## Library discovery
+
+The native library is found via the `SECRETSPEC_FFI_LIB` environment variable,
+or a Cargo `target` directory found by searching up from the working directory.

data/ext/secretspec/extconf.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Builds the secretspec native extension, statically linking the secretspec-ffi
+# archive (libsecretspec_ffi.a) into the extension object. A Rust staticlib does
+# not carry its own native dependency closure, so the archive's transitive system
+# libs (captured from `rustc --print native-static-libs`, never hardcoded) are
+# appended to the link line after it.
+
+require "mkmf"
+
+ext_dir = __dir__
+pkg_dir = File.expand_path("../..", ext_dir) # secretspec-rb
+repo_root = File.expand_path("..", pkg_dir)  # workspace root (dev checkout)
+vendor = File.join(pkg_dir, "vendor")
+
+# The staticlib: explicit contract, the bundled platform-gem copy, or a Cargo
+# target dir (dev checkout, newest of release/debug).
+def find_staticlib(vendor, repo_root)
+  env = ENV["SECRETSPEC_FFI_STATICLIB"]
+  return env if env && !env.empty? && File.exist?(env)
+
+  bundled = File.join(vendor, "libsecretspec_ffi.a")
+  return bundled if File.exist?(bundled)
+
+  %w[release debug]
+    .map { |p| File.join(repo_root, "target", p, "libsecretspec_ffi.a") }
+    .select { |c| File.exist?(c) }
+    .max_by { |c| File.mtime(c) }
+end
+
+# The archive's transitive native deps: explicit contract, the bundled manifest,
+# or captured live from rustc (dev checkout).
+def find_native_libs(vendor, repo_root)
+  env = ENV["SECRETSPEC_FFI_NATIVE_LIBS"]
+  return env if env && !env.empty?
+
+  manifest = File.join(vendor, "native-static-libs.txt")
+  return File.read(manifest).strip if File.exist?(manifest)
+
+  note = `cd #{repo_root} && cargo rustc -q -p secretspec-ffi --crate-type staticlib -- --print native-static-libs 2>&1`
+  note[/native-static-libs:\s*(.*)/, 1].to_s.strip
+end
+
+staticlib = find_staticlib(vendor, repo_root)
+abort("secretspec: could not locate libsecretspec_ffi.a; set SECRETSPEC_FFI_STATICLIB") unless staticlib
+
+# Header: the bundled vendor copy (platform gem) or the ffi crate's include dir.
+include_dir =
+  if File.exist?(File.join(vendor, "secretspec.h"))
+    vendor
+  else
+    File.join(repo_root, "secretspec-ffi", "include")
+  end
+
+$INCFLAGS << " -I#{include_dir}"
+# $LOCAL_LIBS is emitted before $libs on the link line, so the archive (pulled
+# for the referenced symbols) precedes the system libs it depends on.
+$LOCAL_LIBS << " #{staticlib}"
+$libs = "#{$libs} #{find_native_libs(vendor, repo_root)}"
+
+create_makefile("secretspec/secretspec_ext")

data/ext/secretspec/secretspec_ext.c

@@ -0,0 +1,64 @@
+/*
+ * Native glue for the secretspec Ruby SDK.
+ *
+ * A thin C extension that statically links the secretspec-ffi archive
+ * (libsecretspec_ffi.a) and exposes its three C ABI functions to Ruby as
+ * Secretspec::Native.c_resolve / c_abi_version. The Rust resolver is embedded in
+ * this extension object, so there is no separate cdylib to ship or dlopen.
+ */
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <stdlib.h>
+#include "secretspec.h"
+
+static void *
+resolve_nogvl(void *arg)
+{
+    return secretspec_resolve((const char *)arg);
+}
+
+/*
+ * Secretspec::Native.c_resolve(request_json) -> String or nil
+ *
+ * Marshals the JSON request to the Rust resolver and copies the owned response
+ * into a Ruby String before freeing it. Returns nil if the resolver returns NULL
+ * (catastrophic allocation failure); the Ruby wrapper turns that into an Error.
+ *
+ * The resolver may block on network-backed providers (1Password, LastPass,
+ * Vault), so it runs with the GVL released — otherwise the round-trip would
+ * freeze every other Ruby thread. The request bytes are copied into a C-owned
+ * buffer first: the Ruby string may move once the GVL is released.
+ */
+static VALUE
+native_resolve(VALUE self, VALUE request_json)
+{
+    char *request = strdup(StringValueCStr(request_json));
+    if (request == NULL) {
+        return Qnil;
+    }
+    char *result = rb_thread_call_without_gvl(
+        resolve_nogvl, request, RUBY_UBF_IO, NULL);
+    free(request);
+    if (result == NULL) {
+        return Qnil;
+    }
+    VALUE out = rb_str_new_cstr(result);
+    secretspec_free(result);
+    return out;
+}
+
+/* Secretspec::Native.c_abi_version -> String (static, not freed). */
+static VALUE
+native_abi_version(VALUE self)
+{
+    return rb_str_new_cstr(secretspec_abi_version());
+}
+
+void
+Init_secretspec_ext(void)
+{
+    VALUE mod = rb_define_module("Secretspec");
+    VALUE native = rb_define_module_under(mod, "Native");
+    rb_define_singleton_method(native, "c_resolve", native_resolve, 1);
+    rb_define_singleton_method(native, "c_abi_version", native_abi_version, 0);
+}

data/lib/secretspec.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+# Ruby SDK for SecretSpec, a declarative secrets manager.
+#
+# A thin client over the secretspec-ffi C ABI. The Rust resolver is statically
+# linked into a native extension (secretspec_ext), so the SDK inherits every
+# provider with no Ruby-side logic and there is nothing to locate at runtime.
+# Mirrors the Rust derive crate's vocabulary.
+
+require "json"
+
+# The compiled extension lives next to this file in a source/dev checkout, but in
+# an installed gem RubyGems places it in a separate extensions dir already on
+# $LOAD_PATH. Put this file's dir on the path so the absolute require resolves in
+# both layouts.
+$LOAD_PATH.unshift(__dir__) unless $LOAD_PATH.include?(__dir__)
+require "secretspec/secretspec_ext"
+
+module Secretspec
+  # Response wire-format version this SDK understands. Tracks secretspec-ffi's
+  # RESOLVE_SCHEMA_VERSION; a mismatch means the loaded library is incompatible.
+  RESOLVE_SCHEMA_VERSION = 1
+
+  # Wire-format version of the value-free report. Tracks secretspec's
+  # RESOLUTION_REPORT_SCHEMA_VERSION.
+  REPORT_SCHEMA_VERSION = 1
+
+  # A resolution failure (bad manifest, provider error, reason policy).
+  class Error < StandardError
+    attr_reader :kind
+
+    def initialize(kind, message)
+      @kind = kind
+      super("#{message} (kind: #{kind})")
+    end
+  end
+
+  # One or more required secrets were not found anywhere.
+  class MissingRequiredError < Error
+    attr_reader :missing
+
+    def initialize(missing)
+      @missing = missing
+      super("missing_required", "missing required secret(s): #{missing.join(', ')}")
+    end
+  end
+
+  # One resolved secret. Exactly one of +value+ / +path+ is set.
+  ResolvedSecret = Struct.new(:value, :path, :as_path, :source, :source_provider) do
+    # The usable string: the file path for as_path secrets, else the value.
+    def get
+      as_path ? path : value
+    end
+  end
+
+  # A successful resolution, mirroring the Rust Resolved wrapper.
+  Resolved = Struct.new(:provider, :profile, :secrets, :missing_optional) do
+    # Export each resolved secret into ENV by its declared name. Secrets with no
+    # usable value (e.g. under no_values) are skipped rather than deleted from
+    # ENV (assigning nil would remove the variable).
+    def set_as_env!
+      secrets.each do |name, secret|
+        value = secret.get
+        ENV[name] = value unless value.nil?
+      end
+    end
+
+    # Flat { "SECRET_NAME" => value } hash (the file path for as_path). A secret
+    # with no usable value (e.g. under no_values) maps to nil, matching the null
+    # the other SDKs emit. Feed this to a quicktype-generated deserializer (e.g.
+    # from_dynamic!). See `secretspec schema`.
+    def fields
+      secrets.transform_values(&:get)
+    end
+
+    # Remove the temp files backing any as_path secrets in this result. The
+    # resolver persists those files (mode 0400) so their paths stay valid after
+    # resolve returns; the caller owns their lifetime. Call #close (or pass a
+    # block to Builder#load, which closes automatically) when done so secret
+    # files do not accumulate in the temp dir. A file already gone is not an
+    # error.
+    def close
+      secrets.each_value do |secret|
+        next unless secret.as_path && secret.path
+
+        File.delete(secret.path) if File.exist?(secret.path)
+      end
+      nil
+    end
+  end
+
+  # Value-free resolution outcome for one declared secret: how it would resolve
+  # and from where, never the value itself.
+  SecretReport = Struct.new(:name, :status, :required, :source_provider,
+                            :default_applied, :generated, :as_path)
+
+  # A value-free resolution snapshot. Unlike Resolved, a missing required secret
+  # is a "missing_required" status here, not an error, so a report describes a
+  # profile even when its secrets are not all available.
+  Report = Struct.new(:provider, :profile, :secrets)
+
+  # The narrow C ABI, statically linked into the secretspec_ext extension. The
+  # Native.c_resolve / c_abi_version C functions are defined in
+  # ext/secretspec/secretspec_ext.c; these wrappers add the Ruby-side error type.
+  module Native
+    class << self
+      def resolve(request_json)
+        result = c_resolve(request_json)
+        raise Error.new("ffi", "secretspec_resolve returned null") if result.nil?
+
+        result
+      end
+
+      def abi_version
+        c_abi_version
+      end
+    end
+  end
+
+  # Entry point mirroring the derive crate's SecretSpec::builder().
+  class SecretSpec
+    def self.builder
+      Builder.new
+    end
+  end
+
+  # Fluent builder for a resolution.
+  class Builder
+    def initialize
+      @request = {}
+    end
+
+    def with_path(path)
+      @request["path"] = path if path
+      self
+    end
+
+    def with_provider(provider)
+      @request["provider"] = provider if provider
+      self
+    end
+
+    def with_profile(profile)
+      @request["profile"] = profile if profile
+      self
+    end
+
+    def with_reason(reason)
+      @request["reason"] = reason if reason
+      self
+    end
+
+    # Omit secret values, returning only structure and provenance.
+    def with_no_values(no_values = true)
+      @request["no_values"] = no_values
+      self
+    end
+
+    # Resolve the secrets. Raises MissingRequiredError if a required secret is
+    # missing, and Error for any other failure.
+    #
+    # Without a block, returns the Resolved (the caller should #close it when
+    # done to clean up any as_path temp files). With a block, yields the Resolved
+    # and closes it afterwards, returning the block's value.
+    def load
+      response = parse_response(JSON.generate(@request), "resolve", RESOLVE_SCHEMA_VERSION)
+
+      missing = response["missing_required"] || []
+      raise MissingRequiredError.new(missing) unless missing.empty?
+
+      secrets = {}
+      (response["secrets"] || {}).each do |name, entry|
+        secrets[name] = ResolvedSecret.new(
+          entry["value"], entry["path"], entry["as_path"] || false,
+          entry["source"], entry["source_provider"]
+        )
+      end
+
+      resolved = Resolved.new(
+        response["provider"], response["profile"], secrets,
+        response["missing_optional"] || []
+      )
+      return resolved unless block_given?
+
+      begin
+        yield resolved
+      ensure
+        resolved.close
+      end
+    end
+
+    # Resolve a value-free Report (the inventory/preflight view, the same one the
+    # CLI exposes as `check --json`). Unlike #load, never raises
+    # MissingRequiredError: a missing required secret appears as a SecretReport
+    # with status "missing_required".
+    def report
+      request = @request.merge("mode" => "report")
+      response = parse_response(JSON.generate(request), "report", REPORT_SCHEMA_VERSION)
+
+      secrets = (response["secrets"] || []).map do |s|
+        SecretReport.new(s["name"], s["status"], s["required"],
+                         s["source_provider"], s["default_applied"],
+                         s["generated"], s["as_path"])
+      end
+      Report.new(response["provider"], response["profile"], secrets)
+    end
+
+    private
+
+    # Resolve a JSON request payload and return the validated "response" hash, or
+    # raise. +kind+ is "resolve" or "report"; it selects the schema version to
+    # enforce and labels the version-mismatch message.
+    def parse_response(payload, kind, expected_version)
+      envelope = JSON.parse(Native.resolve(payload))
+
+      unless envelope["ok"]
+        err = envelope["error"] || {}
+        raise Error.new(err["kind"] || "unknown", err["message"] || "")
+      end
+
+      response = envelope["response"]
+      raise Error.new("ffi", "secretspec_resolve reported ok with no response") if response.nil?
+
+      version = response["schema_version"]
+      unless version == expected_version
+        raise Error.new("version",
+                        "unsupported #{kind} schema version #{version} " \
+                        "(expected #{expected_version}); the secretspec-ffi " \
+                        "library and this SDK are out of sync")
+      end
+
+      response
+    end
+  end
+
+  def self.abi_version
+    Native.abi_version
+  end
+end

data/vendor/native-static-libs.txt

@@ -0,0 +1 @@
+-ldbus-1 -lgcc_s -lutil -lrt -lpthread -lm -ldl -lc

data/vendor/secretspec.h

@@ -0,0 +1,51 @@
+/*
+ * SecretSpec C ABI.
+ *
+ * A deliberately narrow, JSON-in / JSON-out boundary. The entire native surface
+ * is the three functions below; all richness lives in the versioned JSON
+ * contract so language bindings stay thin.
+ *
+ * Request JSON (all fields optional):
+ *   { "path": ".../secretspec.toml", "provider": "keyring://",
+ *     "profile": "production", "reason": "boot", "no_values": false }
+ *
+ * Response envelope:
+ *   { "ok": true,  "response": { ...resolve response... } }
+ *   { "ok": false, "error": { "kind": "io", "message": "..." } }
+ *
+ * The response (when ok) carries secret values unless "no_values" was set.
+ * Treat returned strings as sensitive and free them promptly.
+ */
+#ifndef SECRETSPEC_H
+#define SECRETSPEC_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Resolve secrets described by `request_json` (a NUL-terminated UTF-8 JSON
+ * string). Returns a newly allocated, NUL-terminated JSON response envelope
+ * that the caller OWNS and must release with secretspec_free().
+ *
+ * Returns NULL only on catastrophic allocation failure.
+ */
+char *secretspec_resolve(const char *request_json);
+
+/*
+ * Free a string previously returned by secretspec_resolve(). NULL is ignored.
+ * Must not be called twice on the same pointer.
+ */
+void secretspec_free(char *ptr);
+
+/*
+ * Return the ABI version as a static NUL-terminated string. Do NOT free; the
+ * pointer is valid for the lifetime of the loaded library.
+ */
+const char *secretspec_abi_version(void);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* SECRETSPEC_H */

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: secretspec
+version: !ruby/object:Gem::Version
+  version: 0.13.0
+platform: x86_64-linux
+authors:
+- Cachix
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-03 00:00:00.000000000 Z
+dependencies: []
+description: 'Ruby bindings for SecretSpec: a native extension that statically links
+  the secretspec-ffi C ABI.'
+email:
+executables: []
+extensions:
+- ext/secretspec/extconf.rb
+extra_rdoc_files: []
+files:
+- README.md
+- ext/secretspec/extconf.rb
+- ext/secretspec/secretspec_ext.c
+- lib/secretspec.rb
+- vendor/libsecretspec_ffi.a
+- vendor/native-static-libs.txt
+- vendor/secretspec.h
+homepage: https://secretspec.dev/
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.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: Declarative secrets, every environment, any provider (Ruby SDK)
+test_files: []