seekrit-sdk 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e36b3af31987a52e24e023cfedfdf29832bfd6a707b16d64097b7ae398e8768
-  data.tar.gz: 267d89e6743ef4db98f7892ff887965a962c01404ab60d4183fc48cc7315ae40
+  metadata.gz: 32c907a8f2923c14214ae739aaf8f183b7db26f001f3d3026a8d1ef0764c8fe1
+  data.tar.gz: 55c2748d6c1719bcfd0f98df7580664d4bbb1293582df109a446373e10151ae3
 SHA512:
-  metadata.gz: a49c25989cb360f7acb086246be37855958925fc2efb39b908c53430e992da4efe8d67610264af5912ba5b667b7e5f35c5aa940bb3b0140710742eb282348651
-  data.tar.gz: d3273a2237dc9d0632052a2fd20b704f41cb06513110526af61b615fdf31767762c154641537235803dc297ec901e9de3047dc3fbcaaf582ddf3341443da7b1e
+  metadata.gz: b7be6491946e39019f3fe2d4212df1aa9736e0145729396e24719b40420b126151cf4d97531b51962b51a8c1f73d70d0ad7c3b63d5ff8644be957949ecf98382
+  data.tar.gz: 9a281b0d885e7e887456f04474feafbf8c41e70d57a60cff07e920add154ac3fbcbe1f90f5ae8b56f1664e98adb9660fbfdfb9f647528d65140531589f05b893

data/README.md

@@ -82,6 +82,19 @@ Seekrit::Client.new(with: { "shared" => "dev" }).resolve
 `#resolve` is **fail-closed**: any resolve or decrypt failure raises rather than
 returning partial results.
 
+## Secret references
+
+A secret's value may reference another with `${OTHER_SECRET}`. References are
+stored literally and expanded here, after the layers are merged — so a reference
+picks up whichever layer won that name, and rotating the referenced secret
+updates every value that uses it. `$${OTHER_SECRET}` is a literal; an unknown
+name is left as written; a reference cycle raises. Full rules:
+[seekrit.dev/docs/guides/references](https://seekrit.dev/docs/guides/references).
+
+```ruby
+client = Seekrit::Client.new(interpolate: false) # get the stored text instead
+```
+
 ## Zero-knowledge
 
 `GET /v1/resolve` returns ciphertext plus a data-encryption key wrapped to your
@@ -94,3 +107,12 @@ CLI, `seekrit run`, and every other seekrit client. See
 ## License
 
 MIT
+
+## Service token v2
+
+Keep one `SEEKRIT_TOKEN`: `skt_<id>_v2.<auth-secret>.<private-key>`.
+The client sends only `skt_<id>_v2.<auth-secret>` to the API and uses the private
+key locally to decrypt. Legacy tokens are rejected before any API request;
+upgrade clients and replace legacy tokens through the dashboard. A stolen
+HTTP credential cannot decrypt environment payloads, but stealing the full
+local bundle still exposes the private key. Treat the full bundle as a secret.

data/lib/seekrit/client.rb

@@ -21,21 +21,26 @@ module Seekrit
     # @param with [Hash] {group_slug => env_slug} overrides (the ?with= override).
     # @param open_timeout [Numeric] connection timeout, seconds.
     # @param read_timeout [Numeric] read timeout, seconds.
-    def initialize(token: nil, api_url: nil, with: {}, open_timeout: 10, read_timeout: 30)
+    # @param interpolate [Boolean] expand ${OTHER_SECRET} references in resolved
+    #   values (default true); false returns the stored text verbatim.
+    def initialize(token: nil, api_url: nil, with: {}, open_timeout: 10, read_timeout: 30,
+                   interpolate: true)
       @token = token || ENV["SEEKRIT_TOKEN"]
       raise Error, "no service token: pass token: or set SEEKRIT_TOKEN" unless @token && !@token.empty?
 
       @key = Crypto::TokenKey.parse(@token) # fail fast on a bad token
+      @token = Crypto.service_token_auth(@token)
       @api_url = (api_url || ENV["SEEKRIT_API_URL"] || DEFAULT_API_URL).sub(%r{/+\z}, "")
       @with = with || {}
       @open_timeout = open_timeout
       @read_timeout = read_timeout
+      @interpolate = interpolate
     end
 
     # Fetch, decrypt, and merge; returns { "NAME" => value }. Fail-closed.
     # @return [Hash{String=>String}]
     def resolve
-      Crypto.materialize(fetch, @key)
+      Crypto.materialize(fetch, @key, interpolate: @interpolate)
     end
 
     # Resolve and return a single secret's value, or +default+ if absent.

data/lib/seekrit/crypto.rb

@@ -3,6 +3,8 @@
 require "openssl"
 require "base64"
 
+require_relative "interpolate"
+
 module Seekrit
   # Zero-knowledge read path, byte-compatible with @seekrit/crypto and
   # crates/seekrit-core. Three steps:
@@ -12,17 +14,24 @@ module Seekrit
   #   3. Decrypt each secret                             (Crypto.decrypt_secret).
   #
   # Blob formats (all segments base64url, no padding):
-  #   token       skt_<id>_<pkcs8 private key>
+  #   token       skt_<id>_v2.<auth secret>.<pkcs8 private key>
   #   wrapped DEK wd1.<ephemeral pub (raw SEC1)>.<hkdf salt>.<iv>.<ciphertext||tag>
   #   secret      sc1.<iv>.<ciphertext||tag>
   module Crypto
     HKDF_INFO = "seekrit/wrap-dek/v1"
     CURVE = "prime256v1" # NIST P-256 / secp256r1
     # Only the first two underscores are separators; the key segment may contain "_".
-    TOKEN_RE = /\A(skt_[0-9A-Za-z]+)_([A-Za-z0-9_-]+)\z/.freeze
+    TOKEN_RE = /\A(skt_[0-9A-Za-z]+)_(?:v2\.[A-Za-z0-9_-]{43}\.)?([A-Za-z0-9_-]+)\z/.freeze
 
     module_function
 
+    def service_token_auth(token)
+      match = /\A(skt_[0-9A-Za-z]+_v2\.[A-Za-z0-9_-]{43})(?:\.[A-Za-z0-9_-]+)?\z/.match(token)
+      raise CryptoError, "a v2 service token is required for API access; replace legacy tokens in the dashboard" unless match
+
+      match[1]
+    end
+
     def b64url_decode(text)
       Base64.urlsafe_decode64(text + ("=" * ((4 - (text.length % 4)) % 4)))
     end
@@ -144,7 +153,11 @@ module Seekrit
     # Decrypt every layer and merge by precedence. Layers arrive lowest
     # precedence first (composed groups, then the app environment); later layers
     # overwrite earlier ones on a name collision.
-    def materialize(resolve_response, key)
+    #
+    # ${OTHER_SECRET} references are then expanded over the merged result (so a
+    # reference sees whichever layer won the name). Pass interpolate: false to
+    # get the stored text instead.
+    def materialize(resolve_response, key, interpolate: true)
       merged = {}
       resolve_response["layers"].each do |layer|
         dek = key.unwrap_dek(layer["wrappedDek"])
@@ -153,7 +166,9 @@ module Seekrit
           merged[secret["name"]] = decrypt_secret(dek, secret["ciphertext"], secret_aad(env_id, secret["name"]))
         end
       end
-      merged
+      return merged unless interpolate
+
+      Interpolate.interpolate_secrets(merged).values
     end
   end
 end

data/lib/seekrit/errors.rb

@@ -9,6 +9,19 @@ module Seekrit
   # from "tampered data" from "mismatched context".
   class CryptoError < Error; end
 
+  # A ${OTHER_SECRET} reference could not be expanded: a cycle, or an expansion
+  # that grows without bound. An *unknown* reference is not an error — it is left
+  # as literal text (see Seekrit::Interpolate.interpolate_secrets).
+  class ReferenceError < Error
+    # @return [String] "CYCLE" or "TOO_LARGE".
+    attr_reader :code
+
+    def initialize(code, message)
+      @code = code
+      super(message)
+    end
+  end
+
   # The resolve API returned a non-2xx response.
   class ApiError < Error
     # @return [Integer] HTTP status code.

data/lib/seekrit/interpolate.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Seekrit
+  # Secret references: ${OTHER_SECRET} inside a secret value.
+  #
+  # Expansion happens here, in-process, after the layers are merged — the API
+  # only ever holds the ciphertext of the literal ${OTHER_SECRET} text. The rules
+  # are fixed by the shared golden fixture (testdata/vectors.json, key
+  # "interpolation"), which every seekrit client is tested against:
+  #
+  #   * ${NAME} becomes NAME's value from the same merged set, recursively.
+  #   * NAME must look like an environment variable ([A-Za-z_][A-Za-z0-9_]*);
+  #     anything else (${FOO:-bar}, ${1}) is left exactly as written.
+  #   * A name that is not in the set is left literal and listed in +unresolved+,
+  #     so a stored value containing e.g. ${GITHUB_SHA} keeps working.
+  #   * $${NAME} is an escape for the literal text ${NAME}.
+  #   * A reference cycle raises ReferenceError.
+  module Interpolate
+    REFERENCE_NAME = /\A[A-Za-z_][A-Za-z0-9_]*\z/.freeze
+
+    # Cap on a single expanded value: nested references can multiply length.
+    MAX_EXPANDED_LENGTH = 1_048_576
+
+    # The outcome of expanding a variable set.
+    #
+    # @!attribute values
+    #   @return [Hash{String=>String}] the set with every reference expanded
+    # @!attribute expanded
+    #   @return [Array<String>] names whose value had a reference expanded
+    # @!attribute unresolved
+    #   @return [Array<String>] referenced names absent from the set, sorted
+    Interpolation = Struct.new(:values, :expanded, :unresolved)
+
+    module_function
+
+    # Split a value into literal runs and references — the single tokenizer the
+    # rules above are expressed in terms of. Yields [reference, text]: for a
+    # literal, +reference+ is nil; for a reference, +text+ is its raw ${NAME}
+    # source (used verbatim when the name turns out to be absent).
+    def scan(text)
+      return enum_for(:scan, text) unless block_given?
+
+      i = 0
+      while i < text.length
+        dollar = text.index("$", i)
+        if dollar.nil?
+          yield [nil, text[i..]]
+          return
+        end
+        yield [nil, text[i...dollar]] if dollar > i
+
+        # `$${` — escape: emit a literal `${` and skip all three characters, so
+        # the `{NAME}` that follows can never be read as a reference.
+        if text[dollar + 1, 2] == "${"
+          yield [nil, "${"]
+          i = dollar + 3
+          next
+        end
+
+        close = text[dollar + 1] == "{" ? text.index("}", dollar + 2) : nil
+        reference = close ? text[(dollar + 2)...close] : nil
+        if reference && REFERENCE_NAME.match?(reference)
+          yield [reference, text[dollar..close]]
+          i = close + 1
+          next
+        end
+
+        # A plain `$`, an unterminated `${`, or a non-name: literal. Advancing a
+        # single character lets a `${` later in the run still be recognized.
+        yield [nil, "$"]
+        i = dollar + 1
+      end
+    end
+
+    # Expand ${NAME} references throughout a merged variable set. The input hash
+    # is never mutated.
+    #
+    # @param values [Hash{String=>String}]
+    # @return [Interpolation]
+    # @raise [Seekrit::ReferenceError] on a reference cycle or unbounded growth
+    def interpolate_secrets(values)
+      state = { resolved: {}, unresolved: {}, stack: [] }
+      result = {}
+      expanded = []
+      values.each_key do |name|
+        value = resolve_reference(name, values, state)
+        result[name] = value
+        expanded << name if value != values[name]
+      end
+      Interpolation.new(result, expanded, state[:unresolved].keys.sort)
+    end
+
+    # Expand one present name's value, memoized so each is expanded once.
+    # @api private
+    def resolve_reference(name, values, state)
+      cached = state[:resolved][name]
+      return cached if cached
+
+      stack = state[:stack]
+      at = stack.index(name)
+      unless at.nil?
+        chain = stack[at..] + [name]
+        raise ReferenceError.new("CYCLE", "secret reference cycle: #{chain.join(' -> ')}")
+      end
+
+      stack.push(name)
+      out = +""
+      scan(values[name]) do |reference, text|
+        if reference.nil?
+          out << text
+        elsif values.key?(reference)
+          out << resolve_reference(reference, values, state)
+        else
+          state[:unresolved][reference] = true
+          out << text
+        end
+      end
+      stack.pop
+
+      if out.length > MAX_EXPANDED_LENGTH
+        raise ReferenceError.new("TOO_LARGE", "#{name} expands to more than #{MAX_EXPANDED_LENGTH} bytes")
+      end
+
+      state[:resolved][name] = out
+      out
+    end
+  end
+end

data/lib/seekrit/version.rb

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

data/lib/seekrit.rb

@@ -2,6 +2,7 @@
 
 require_relative "seekrit/version"
 require_relative "seekrit/errors"
+require_relative "seekrit/interpolate"
 require_relative "seekrit/crypto"
 require_relative "seekrit/client"
 

data/testdata/vectors.json

@@ -1,7 +1,8 @@
 {
-  "token": "skt_r36AUXMxoX0xkQoH8vimHN_MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg1bTaK96XZQzEUpfGe5dlc-sp3n7mF8WpZNVJweEJZ06hRANCAATgUoWLRDgyG0qsUzdQXzr1VSL-p9kSp_zhAULqF2qHUAWDPcuoX-f4JTUX6lyzPEs_0chQ9nKvgmEJUpXx9_q5",
-  "tokenId": "skt_r36AUXMxoX0xkQoH8vimHN",
-  "publicKeyJwk": "{\"key_ops\":[],\"ext\":true,\"kty\":\"EC\",\"x\":\"4FKFi0Q4MhtKrFM3UF869VUi_qfZEqf84QFC6hdqh1A\",\"y\":\"BYM9y6hf5_glNRfqXLM8Sz_RyFD2cq-CYQlSlfH3-rk\",\"crv\":\"P-256\"}",
+  "token": "skt_6EYgmoh8LuiPPAbM0SaVtc_v2.bh8OFkiEBdTJM4MBX75AMCPsR2Arp1i32sg8Ej0Vw7o.MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgra6e_i8D2dIWlz-43EVbrHz-g698-kxY22MCp95L7VGhRANCAATA4nkyQKLq4hD5YvzXLtNtKAK_g-H4LF260zk0bInSWMbDfx0vTTtOg0tRWoDYWbuIN0vb1YMZ5z13xH5aBsDx",
+  "authToken": "skt_6EYgmoh8LuiPPAbM0SaVtc_v2.bh8OFkiEBdTJM4MBX75AMCPsR2Arp1i32sg8Ej0Vw7o",
+  "tokenId": "skt_6EYgmoh8LuiPPAbM0SaVtc",
+  "publicKeyJwk": "{\"key_ops\":[],\"ext\":true,\"kty\":\"EC\",\"x\":\"wOJ5MkCi6uIQ-WL81y7TbSgCv4Ph-CxdutM5NGyJ0lg\",\"y\":\"xsN_HS9NO06DS1FagNhZu4g3S9vVgxnnPXfEfloGwPE\",\"crv\":\"P-256\"}",
   "resolve": {
     "scope": {
       "orgId": "org_test",
@@ -17,19 +18,19 @@
         "environmentId": "env_grouptest0000000001",
         "slug": "production",
         "groupSlug": "shared",
-        "wrappedDek": "wd1.BEoGSn3SoICO6tA13EjveZHvxTTRVijE0OUpBkzVkFU28q_jfgY4P9IkyrpjMVJK27zogh61rwC_NUBjoe2TKhY.5EI1On9xCtVuntRHMA6xFA.JNqiqNRxDpNN3hkP.8RxEujnGaEIUIVq9VVcOZlpC07-gxgyz25VCtffNZWSRh8J8iFfMA6p-_ubXSfv5",
+        "wrappedDek": "wd1.BGAAVA2nxO1UzcRZA_7ubZ9nLAGSf_Fc_6y07AHlv4N_q8dhQ0z4dwMHqUUaKPkkSnH8rnWkjnitlKHRmuIvoz8.dJ0ALJ9Wejh6nYiKM3adOA.VFgZWwqtT_ly6gP4.RIcWNi6id_QO9NtmCU4iFUEX9U9fUlqn2UNgmkgunpU_eVnKgMf6q8ui1PxcEBiw",
         "secrets": [
           {
             "name": "SHARED",
-            "ciphertext": "sc1.4XNyaS_ilRPDTlIg.LhAGzqP_cm4fx_dKeST8_3NITle_77x0Qjo"
+            "ciphertext": "sc1.oIjnQEJskdJ_nweV.MGETgRWPDkwhHm9e_jp567-b19Fn8DJohrU"
           },
           {
             "name": "DATABASE_URL",
-            "ciphertext": "sc1.-THIwVQA7yVq6SWt.1RaVPddl8QDuhc2wValcmtArCxafHBCAk24Fv00gB_FNc6k"
+            "ciphertext": "sc1.Fo69NaVLlUDFtGsk.tr8o0e7mMSB7DWkfZuv0eLOsNq7Fm-3dd2zOiPSXSHiwXbg"
           },
           {
             "name": "UNICODE",
-            "ciphertext": "sc1.7qB3RU8qhHKpqwbB.BsKeZYWDv4Qp9cWIB0I684pLazslk2nFtIq-OvgDjIaTaw3Pbw"
+            "ciphertext": "sc1.hu_o1qPHzmeJrT0q.5jIWUj9fTvGXjyeSyhtOMdvlWRenXqNy9F2uYg3XVgui0CYmdA"
           }
         ]
       },
@@ -37,19 +38,31 @@
         "source": "app",
         "environmentId": "env_apptest0000000000001",
         "slug": "production",
-        "wrappedDek": "wd1.BMywXqAVq3Ee3XX7mGBt2KLcRRwPLQn9FjlXc19Z8HNdDPsg-KyKLwg_uz4tgQ8MdVevMgtjfBkOiqmAi7ENI2Y.FLBNZ3z8-8CnYoBN-Azr9g.2x8wkp6BSw9QjnG2.3b32qenHIHC92eCehRW6QGWNFTlIe3nTKPje0WsRFWSHkjV6PYIxCXmlQaAJJkp3",
+        "wrappedDek": "wd1.BHVKzCsJECbpyULjVjFe-vw5mmKEJ26MZz02wc1RfzgozIRx9CrCFJJ0RkYWT_iuvAAG2rN7WNg5uNt0RQ6X14Q.Wfuvupy_B16u453L04UpSA.YPq62FodkXeezDd3.HgXwlx5gZRAnqmyk0WSz4HW9qVrb-DfEsvD76HKXkgigAShwBJ9g1qiVtSUgUgCo",
         "secrets": [
           {
             "name": "SHARED",
-            "ciphertext": "sc1.QF697pJ61KM9Xqj2.HH9PNlW7aIIWZvpLm6yc8ZCRRemlxoOS"
+            "ciphertext": "sc1.hVO-Xgq16bV52VDQ.gePrTLVlrjIINJCs_gomYWnwqS4sD1CP"
           },
           {
             "name": "API_KEY",
-            "ciphertext": "sc1.x4G_KqJP7ags8SBf.obw89lhKqcMAy1vzjdTjch88R7Trx9JtFWS2Rw"
+            "ciphertext": "sc1.KpB-GlAGsWiNUN5p.PY5HnW1tOA-ZCBSSslnqFld4sPGWLujiW_j8gQ"
           },
           {
             "name": "EMPTY",
-            "ciphertext": "sc1.qdub6o6QejpKH97e.KFe1fiDvtHF3agstKhL5ng"
+            "ciphertext": "sc1.qR6EjHPQkz6mZI37.PKrdRmvhq-N5bqYwWaK5Dg"
+          },
+          {
+            "name": "REFERENCING",
+            "ciphertext": "sc1.mc6E1roINLiI5H5U.jkSlIFcn3NxJLgStBEdpelOJ_aB9pouUIOu5YX7yIB0G_maOkBRA2UpFsFoXI1mRppEWwg"
+          },
+          {
+            "name": "ESCAPED_REF",
+            "ciphertext": "sc1.obgYCJstXaXFUJJg.tcI9_IOzvpSaXF96WPBowUKxph3dJ_7GvHs"
+          },
+          {
+            "name": "DANGLING_REF",
+            "ciphertext": "sc1.VJCnlvqadm3F6lge.kONf1u13yEIWc8pBjSs_XQDR9kmGi0wOTH35QE_QM8qJEhLuDg"
           }
         ]
       }
@@ -60,6 +73,363 @@
     "DATABASE_URL": "postgres://group/db",
     "UNICODE": "héllo-🌍-\n-tab\tend",
     "API_KEY": "sk-app-12345",
-    "EMPTY": ""
+    "EMPTY": "",
+    "REFERENCING": "url=postgres://group/db;shared=from-app",
+    "ESCAPED_REF": "${SHARED}",
+    "DANGLING_REF": "build-${NOT_A_SECRET}"
+  },
+  "interpolation": {
+    "cases": [
+      {
+        "name": "substitutes a reference",
+        "input": {
+          "HOST": "db.internal",
+          "URL": "postgres://app@${HOST}:5432/db"
+        },
+        "expected": {
+          "HOST": "db.internal",
+          "URL": "postgres://app@db.internal:5432/db"
+        },
+        "unresolved": []
+      },
+      {
+        "name": "expands recursively, repeats, and forward references",
+        "input": {
+          "ADDR": "${HOST}:${PORT}",
+          "HOST": "db.internal",
+          "PORT": "5432",
+          "PAIR": "${ADDR}|${ADDR}"
+        },
+        "expected": {
+          "ADDR": "db.internal:5432",
+          "HOST": "db.internal",
+          "PORT": "5432",
+          "PAIR": "db.internal:5432|db.internal:5432"
+        },
+        "unresolved": []
+      },
+      {
+        "name": "leaves unknown references literal and reports them",
+        "input": {
+          "TAG": "build-${GITHUB_SHA}",
+          "OTHER": "${NOPE}-${GITHUB_SHA}"
+        },
+        "expected": {
+          "TAG": "build-${GITHUB_SHA}",
+          "OTHER": "${NOPE}-${GITHUB_SHA}"
+        },
+        "unresolved": [
+          "GITHUB_SHA",
+          "NOPE"
+        ]
+      },
+      {
+        "name": "expands around an unknown reference",
+        "input": {
+          "HOST": "db.internal",
+          "URL": "${HOST}/${MISSING}"
+        },
+        "expected": {
+          "HOST": "db.internal",
+          "URL": "db.internal/${MISSING}"
+        },
+        "unresolved": [
+          "MISSING"
+        ]
+      },
+      {
+        "name": "$${NAME} escapes to a literal ${NAME}",
+        "input": {
+          "NAME": "expanded",
+          "TEMPLATE": "$${NAME} stays, ${NAME} goes"
+        },
+        "expected": {
+          "NAME": "expanded",
+          "TEMPLATE": "${NAME} stays, expanded goes"
+        },
+        "unresolved": []
+      },
+      {
+        "name": "leaves shell-style, non-name, and unterminated forms alone",
+        "input": {
+          "FOO": "value",
+          "DEFAULTED": "${FOO:-fallback}",
+          "POSITIONAL": "${1}",
+          "DOTTED": "${a.b}",
+          "EMPTY_REF": "${}",
+          "UNTERMINATED": "${FOO",
+          "PASSWORD": "p$$w0rd$"
+        },
+        "expected": {
+          "FOO": "value",
+          "DEFAULTED": "${FOO:-fallback}",
+          "POSITIONAL": "${1}",
+          "DOTTED": "${a.b}",
+          "EMPTY_REF": "${}",
+          "UNTERMINATED": "${FOO",
+          "PASSWORD": "p$$w0rd$"
+        },
+        "unresolved": []
+      },
+      {
+        "name": "recognizes a reference after an unterminated one",
+        "input": {
+          "A": "a",
+          "T": "${ ${A}"
+        },
+        "expected": {
+          "A": "a",
+          "T": "${ a"
+        },
+        "unresolved": []
+      },
+      {
+        "name": "handles empty values and multibyte text",
+        "input": {
+          "EMPTY": "",
+          "A": "héllo-🌍",
+          "T": "🌍${A}${EMPTY}🌍"
+        },
+        "expected": {
+          "EMPTY": "",
+          "A": "héllo-🌍",
+          "T": "🌍héllo-🌍🌍"
+        },
+        "unresolved": []
+      },
+      {
+        "name": "a diamond is not a cycle",
+        "input": {
+          "BASE": "b",
+          "LEFT": "${BASE}-l",
+          "RIGHT": "${BASE}-r",
+          "TOP": "${LEFT}+${RIGHT}"
+        },
+        "expected": {
+          "BASE": "b",
+          "LEFT": "b-l",
+          "RIGHT": "b-r",
+          "TOP": "b-l+b-r"
+        },
+        "unresolved": []
+      }
+    ],
+    "cycles": [
+      {
+        "name": "self reference",
+        "input": {
+          "A": "x${A}"
+        }
+      },
+      {
+        "name": "direct cycle",
+        "input": {
+          "A": "${B}",
+          "B": "${A}"
+        }
+      },
+      {
+        "name": "indirect cycle",
+        "input": {
+          "A": "${B}",
+          "B": "${C}",
+          "C": "${A}"
+        }
+      }
+    ]
+  },
+  "substitution": {
+    "note": "Placeholder substitution over plaintext alone — no crypto involved. Every implementation of the engine (apps/proxy/src/substitute.rs and the fetch/httpx shims in the language SDKs) runs these, so the rules can never drift apart. The lookup each harness must install: a name in `denied` returns Denied, otherwise a name present in `values` returns that Value, otherwise Unknown. A case has either `expected` + `names`, or `error`.",
+    "cases": [
+      {
+        "name": "substitutes a placeholder and reports the name",
+        "input": "Bearer {{seekrit:OPENAI_API_KEY}}",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [],
+        "expected": "Bearer sk-live",
+        "names": [
+          "OPENAI_API_KEY"
+        ]
+      },
+      {
+        "name": "passes text with no placeholder through untouched",
+        "input": "nothing to see here",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [],
+        "expected": "nothing to see here",
+        "names": []
+      },
+      {
+        "name": "repeats one name as many times as it appears",
+        "input": "{{seekrit:OPENAI_API_KEY}}::{{seekrit:OPENAI_API_KEY}}",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [],
+        "expected": "sk-live::sk-live",
+        "names": [
+          "OPENAI_API_KEY"
+        ]
+      },
+      {
+        "name": "reports two injected names, sorted",
+        "input": "{\"a\":\"{{seekrit:STRIPE_KEY}}\",\"b\":\"{{seekrit:OPENAI_API_KEY}}\"}",
+        "values": {
+          "OPENAI_API_KEY": "sk-live",
+          "STRIPE_KEY": "sk_test_1"
+        },
+        "denied": [],
+        "expected": "{\"a\":\"sk_test_1\",\"b\":\"sk-live\"}",
+        "names": [
+          "OPENAI_API_KEY",
+          "STRIPE_KEY"
+        ]
+      },
+      {
+        "name": "a denied name aborts the pass",
+        "input": "{{seekrit:SOME_OTHER}}",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [
+          "SOME_OTHER"
+        ],
+        "error": {
+          "code": "denied",
+          "name": "SOME_OTHER"
+        }
+      },
+      {
+        "name": "an allowed but unresolved name aborts the pass",
+        "input": "{{seekrit:MISSING}}",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [],
+        "error": {
+          "code": "unresolved",
+          "name": "MISSING"
+        }
+      },
+      {
+        "name": "a denial wins even when a valid placeholder came first",
+        "input": "{{seekrit:OPENAI_API_KEY}} then {{seekrit:SOME_OTHER}}",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [
+          "SOME_OTHER"
+        ],
+        "error": {
+          "code": "denied",
+          "name": "SOME_OTHER"
+        }
+      },
+      {
+        "name": "an unterminated marker is literal",
+        "input": "value {{seekrit:OPENAI_API_KEY",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [],
+        "expected": "value {{seekrit:OPENAI_API_KEY",
+        "names": []
+      },
+      {
+        "name": "an illegal character in the name makes the marker literal",
+        "input": "{{seekrit:bad-name}}",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [],
+        "expected": "{{seekrit:bad-name}}",
+        "names": []
+      },
+      {
+        "name": "an empty name is not a placeholder",
+        "input": "{{seekrit:}}",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [],
+        "expected": "{{seekrit:}}",
+        "names": []
+      },
+      {
+        "name": "whitespace inside the marker is not a placeholder",
+        "input": "{{ seekrit:OPENAI_API_KEY }}",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [],
+        "expected": "{{ seekrit:OPENAI_API_KEY }}",
+        "names": []
+      },
+      {
+        "name": "nesting is not expanded recursively",
+        "input": "{{seekrit:{{seekrit:OPENAI_API_KEY}}}}",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [],
+        "expected": "{{seekrit:sk-live}}",
+        "names": [
+          "OPENAI_API_KEY"
+        ]
+      },
+      {
+        "name": "a substituted value is never rescanned",
+        "input": "{{seekrit:OPENAI_API_KEY}}",
+        "values": {
+          "OPENAI_API_KEY": "{{seekrit:STRIPE_KEY}}",
+          "STRIPE_KEY": "sk_test_1"
+        },
+        "denied": [],
+        "expected": "{{seekrit:STRIPE_KEY}}",
+        "names": [
+          "OPENAI_API_KEY"
+        ]
+      },
+      {
+        "name": "extra closing braces stay literal",
+        "input": "{{seekrit:OPENAI_API_KEY}}}}",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [],
+        "expected": "sk-live}}",
+        "names": [
+          "OPENAI_API_KEY"
+        ]
+      },
+      {
+        "name": "multibyte text around a placeholder survives",
+        "input": "🌍 {{seekrit:OPENAI_API_KEY}} héllo",
+        "values": {
+          "OPENAI_API_KEY": "sk-live"
+        },
+        "denied": [],
+        "expected": "🌍 sk-live héllo",
+        "names": [
+          "OPENAI_API_KEY"
+        ]
+      },
+      {
+        "name": "an empty value substitutes to nothing",
+        "input": "[{{seekrit:EMPTY}}]",
+        "values": {
+          "EMPTY": ""
+        },
+        "denied": [],
+        "expected": "[]",
+        "names": [
+          "EMPTY"
+        ]
+      }
+    ]
   }
 }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: seekrit-sdk
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.5.0
 platform: ruby
 authors:
 - seekrit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-19 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies: []
 description: |
   Read-path SDK for seekrit, the zero-knowledge secrets manager. Authenticate
@@ -28,6 +28,7 @@ files:
 - lib/seekrit/client.rb
 - lib/seekrit/crypto.rb
 - lib/seekrit/errors.rb
+- lib/seekrit/interpolate.rb
 - lib/seekrit/railtie.rb
 - lib/seekrit/sdk.rb
 - lib/seekrit/version.rb
@@ -37,8 +38,9 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://seekrit.dev
-  documentation_uri: https://seekrit.dev/docs
+  documentation_uri: https://seekrit.dev/docs/guides/sdks
   source_code_uri: https://github.com/seekritdev/ruby-sdk
+  bug_tracker_uri: https://github.com/seekritdev/ruby-sdk/issues
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []