shojiku 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 707c37a88e032ed04277d749ea4247cf14da6f6f0de05027201d59b227ecdb51
-  data.tar.gz: aa9468c6655f56945089db380531d2557434cda0c0e6f064d0fb562cccd9ceb4
+  metadata.gz: 3b481d059f220a867ef40b179f1144342866f85f742e6efec0b7c6a6ee153207
+  data.tar.gz: 0b9644e8961d4c0f759929b7d0dbd7d3bb76415fe63d5efd7d65f20a1899be1b
 SHA512:
-  metadata.gz: e78ce31fa9fa5049477ab3a4af7a357fccc319bdd61e57ab52fa6054142a700a45c113126c31eefac98aca67ad4aa2dd2cb3b649adbb7cba97e004afee2713a6
-  data.tar.gz: a1d82a98e85e251c34cead95ab6e3d70c3fb2e6e19cd0e7ee493823f9d6b5e57b9cf9f64a5439e39af113b73e3eb649163a83042772a304319a17a8051e4d66f
+  metadata.gz: e2220169bdc93028f743bcfe407a3bcfb8f830ee3a8b9a1109bd121c76c76f07675583cbff1300b19be836305e202b6a455255d7643869c4dc01d806b3d80bde
+  data.tar.gz: 82a9ebddebaca0137c4b72a5c6ac858767f4f7a7f0b555a5288405f2cf0f23d8ce0ea07b5925d2a6af04b39878e2a26ab93f3f3b4d43417546815ddaffb31cea

data/README.md

@@ -1,15 +1,9 @@
 # Shojiku for Ruby
 
-Ruby bindings for [Shojiku](../../README.md) — a document engine that
+Ruby bindings for [Shojiku](https://shojiku.pages.dev) — a document engine that
 turns a YAML template plus your data into a deterministic PDF, signs it,
 and verifies it.
 
-> **Unreleased.** The gem is written and gated but not published yet —
-> all seven Shojiku SDKs publish together at v0.1.0. Until then, install
-> from a repository clone (see [Building the engine
-> library](#building-the-engine-library) below), or use the CLI or the
-> Docker image — see the [quickstart](../../docs/quickstart.md).
-
 ## Install
 
 ```bash
@@ -104,6 +98,39 @@ on a passing verdict as well as a failing one. A document whose
 signature does not verify comes back as a *failed* result that still
 carries the full report.
 
+### Signing with a key this process never holds
+
+When the private key lives in a cloud KMS, an HSM or a smartcard, use
+`ExternalSigner` instead. Shojiku hands out the bytes a signature has to
+cover; your block signs them wherever the key is and hands the signature
+back, so the key never enters your application:
+
+```ruby
+provider = Shojiku::ExternalSigner.new(cert: "signer.crt",
+                                       algorithm: :ecdsa_p256_sha256) do |to_be_signed|
+  kms.sign(key_id: ENV.fetch("KEY_ID"), message: to_be_signed,
+           message_type: "RAW", signing_algorithm: "ECDSA_SHA_256").signature
+end
+
+signed = result.artifact.sign(provider)
+```
+
+The call site is unchanged — which provider you pass is the only
+difference, and a provider registered by name works the same way under
+`strict:`. This gem ships no cloud client of its own: the block is
+whichever client your application already uses.
+
+Two details worth getting right. The bytes handed to the block are the
+CMS **signed attributes**, not the document's digest — a service that
+signs a digest must hash *these* bytes with SHA-256 itself. And the
+signature is that operation's raw output: PKCS#1 v1.5 bytes for
+`:rsa_pkcs1_sha256`, an ASN.1 DER sequence for `:ecdsa_p256_sha256`,
+which is what AWS KMS and Google Cloud KMS both return unchanged.
+
+Exceptions raised inside your block are *not* swallowed into a failed
+result: an outage at your key service is not a fact about the document,
+and `Result#failure?` would read as one.
+
 ### Results, not exceptions
 
 Nothing raises in the normal flow. Every operation returns a result you
@@ -282,7 +309,9 @@ Nothing in this gem downloads anything, at install time or at run time.
 
 ## Building the engine library
 
-Until the platform gems are published, build the library from a clone:
+The platform gems carry the library, so this is only for a platform they
+do not cover, or for working against an engine you changed. Build it from
+a clone:
 
 ```bash
 make capi-lib
@@ -307,13 +336,15 @@ Ruby 3.3 or newer.
 
 ## Documentation
 
-- [Template reference](../../docs/engine/README.md) — how to write the
-  YAML the engine renders
-- [SDK policy](../../docs/agents/sdk.md) — the lifecycle contract every
-  Shojiku SDK implements
+- [Template reference](https://github.com/kengos/shojiku/blob/main/docs/engine/README.md) —
+  how to write the YAML the engine renders
+- [SDK policy](https://github.com/kengos/shojiku/blob/main/docs/agents/sdk.md) —
+  the lifecycle contract every Shojiku SDK implements
 
 ## License
 
-Licensed under any of [Apache-2.0](../../LICENSE-APACHE),
-[MIT](../../LICENSE-MIT), or [BSD-3-Clause](../../LICENSE-BSD), at your
-option.
+Licensed under any of
+[Apache-2.0](https://github.com/kengos/shojiku/blob/main/LICENSE-APACHE),
+[MIT](https://github.com/kengos/shojiku/blob/main/LICENSE-MIT), or
+[BSD-3-Clause](https://github.com/kengos/shojiku/blob/main/LICENSE-BSD),
+at your option.

data/lib/shojiku/client.rb

@@ -128,8 +128,11 @@ module Shojiku
     # Signs an artifact with `provider`, returning a {Result}. The signed
     # bytes begin with the input byte for byte — signing appends a revision.
     #
-    # `provider` is a {LocalPem} (or another provider object), or the NAME of
-    # one registered in configuration. A strict client takes the name only.
+    # `provider` is a {LocalPem} (a key in this process), an {ExternalSigner}
+    # (a key that never enters it — a cloud KMS, an HSM, a smartcard), or the
+    # NAME of one registered in configuration. A strict client takes the name
+    # only. Which kind it is changes nothing here: the provider knows how to
+    # reach the engine for its own sort of key.
     def sign(artifact, provider)
       signer = @settings.lockdown.provider!(provider)
       @settings.lockdown.signable!(artifact)
@@ -177,10 +180,7 @@ module Shojiku
     # The signed document inherits the origin of what it signed: appending a
     # revision does not launder where the document came from.
     def signed(artifact, provider)
-      snapshot = @engine.sign(
-        pdf: artifact.bytes, key: provider.key, certificate: provider.certificate,
-        passphrase: provider.passphrase
-      )
+      snapshot = provider.sign_with(@engine, artifact.bytes)
       Outcome.document(snapshot, step: :sign, client: self, origin: artifact.origin)
     rescue MaterialUnreadable => e
       Result.failed(Failure.new(step: :sign, kind: e.kind, message: e.message))

data/lib/shojiku/engine.rb

@@ -33,46 +33,78 @@ module Shojiku
     INT32 = "l"
     SIZE = Fiddle::SIZEOF_SIZE_T == 8 ? "Q" : "L"
 
+    # Every data argument crosses as a (pointer, length) PAIR — nothing is
+    # NUL-terminated, because PDF bytes contain NUL — and every call ends with
+    # the out-slot the result handle is written to. Spelling the signatures as
+    # a table rather than one call each keeps them impossible to disagree
+    # with the header: an operation's arity is the count of its arguments.
+    PAIR = [VOIDP, SIZE_T].freeze
+    OUT = [VOIDP].freeze
+
     # Only the lifecycle the SDK contract defines is bound: engine info,
     # render, sign, verify. `validate` and `preview` are the authoring
     # surface's, not an artifact lifecycle's — the Designer reaches them
     # through the WASM bindings, and binding them here would be surface with
     # no contract behind it.
+    SIGNATURES = {
+      shojiku_engine_info: OUT,
+      shojiku_render: PAIR + OUT,
+      shojiku_sign: (PAIR * 4) + OUT,
+      shojiku_sign_prepare: (PAIR * 3) + OUT,
+      shojiku_sign_complete: (PAIR * 4) + OUT,
+      shojiku_verify: (PAIR * 2) + OUT
+    }.freeze
+
     def initialize(library)
       @library = library
-      @info = library.function(:shojiku_engine_info, [VOIDP], INT)
-      @render = library.function(:shojiku_render, [VOIDP, SIZE_T, VOIDP], INT)
-      @sign = library.function(
-        :shojiku_sign,
-        [VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP], INT
-      )
-      @verify = library.function(:shojiku_verify, [VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP], INT)
+      @calls = SIGNATURES.to_h { |name, args| [name, library.function(name, args, INT)] }
       declare_accessors(library)
     end
 
     def engine_info
-      invoke { |out| @info.call(out) }
+      invoke { |out| call(:shojiku_engine_info, out) }
     end
 
     def render(request)
-      invoke { |out| @render.call(request, request.bytesize, out) }
+      invoke { |out| call(:shojiku_render, request, request.bytesize, out) }
     end
 
     def sign(pdf:, key:, certificate:, passphrase: nil)
       invoke do |out|
-        @sign.call(
-          pdf, pdf.bytesize, key, key.bytesize, certificate, certificate.bytesize,
-          passphrase, passphrase ? passphrase.bytesize : 0, out
-        )
+        call(:shojiku_sign, pdf, pdf.bytesize, key, key.bytesize,
+             certificate, certificate.bytesize,
+             passphrase, passphrase ? passphrase.bytesize : 0, out)
+      end
+    end
+
+    # The two halves of signing with a key held elsewhere. Both take the same
+    # document, certificate and algorithm — the pair is stateless, so the
+    # second call re-derives what the first prepared.
+    def sign_prepare(pdf:, certificate:, algorithm:)
+      invoke do |out|
+        call(:shojiku_sign_prepare, pdf, pdf.bytesize, certificate, certificate.bytesize,
+             algorithm, algorithm.bytesize, out)
+      end
+    end
+
+    def sign_complete(pdf:, certificate:, algorithm:, signature:)
+      invoke do |out|
+        call(:shojiku_sign_complete, pdf, pdf.bytesize, certificate, certificate.bytesize,
+             algorithm, algorithm.bytesize, signature, signature.bytesize, out)
       end
     end
 
     def verify(pdf:, anchors:)
-      invoke { |out| @verify.call(pdf, pdf.bytesize, anchors, anchors.bytesize, out) }
+      invoke { |out| call(:shojiku_verify, pdf, pdf.bytesize, anchors, anchors.bytesize, out) }
     end
 
     private
 
+    # The one place a lifecycle call crosses.
+    def call(name, *)
+      @calls.fetch(name).call(*)
+    end
+
     def declare_accessors(library)
       buffers = %i[shojiku_result_pdf shojiku_result_json shojiku_result_diagnostics_json
                    shojiku_result_error_json]

data/lib/shojiku/external_signer.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # A signing provider for a key this process is never given.
+  #
+  # The second provider, and the shape {LocalPem}'s own comment promised: a
+  # new class rather than new arguments on `sign`, so the call site is
+  # unchanged in all seven SDKs.
+  #
+  # The engine hands out the bytes a signature has to cover; the block signs
+  # them wherever the key actually lives — AWS KMS, Google Cloud KMS, an HSM,
+  # a smartcard, another service entirely — and hands the signature back:
+  #
+  #   provider = Shojiku::ExternalSigner.new(cert: "signer.crt",
+  #                                          algorithm: :ecdsa_p256_sha256) do |to_be_signed|
+  #     kms.sign(key_id: ENV.fetch("KEY_ID"), message: to_be_signed,
+  #              message_type: "RAW", signing_algorithm: "ECDSA_SHA_256").signature
+  #   end
+  #   client.sign(artifact, provider)
+  #
+  # Shojiku ships no cloud client of its own, deliberately: the block is
+  # whatever client your application already has, and the SDK stays a wrapper
+  # with nothing to keep in step with a vendor's releases.
+  #
+  # **What the block receives is the signed ATTRIBUTES, not the document
+  # digest.** A service that signs a digest must hash these bytes with SHA-256
+  # itself. Signing the document digest instead produces a document that fails
+  # verification, so the distinction is not cosmetic.
+  #
+  # The signature is the raw output of that operation: PKCS#1 v1.5 bytes for
+  # `:rsa_pkcs1_sha256`, an ASN.1 DER sequence for `:ecdsa_p256_sha256` —
+  # which is what both major cloud key services return unchanged.
+  #
+  # The certificate comes either from a path (`cert:`) or from bytes already
+  # in memory (`cert_pem:`), explicit rather than sniffed, exactly as
+  # {LocalPem} takes its material.
+  class ExternalSigner
+    FORMS = "`cert:` (a path) or `cert_pem:` (bytes)"
+
+    # The wire spellings the engine accepts, keyed by the Ruby-side names.
+    # A Symbol reads better at a call site; a String is accepted because
+    # configuration files produce them.
+    ALGORITHMS = {
+      rsa_pkcs1_sha256: "rsa-pkcs1-sha256",
+      ecdsa_p256_sha256: "ecdsa-p256-sha256"
+    }.freeze
+
+    attr_reader :algorithm
+
+    def initialize(cert: nil, cert_pem: nil, algorithm: nil, &block)
+      @cert_path = cert
+      @cert_pem = cert_pem
+      @algorithm = wire_algorithm(algorithm)
+      @block = block
+      one_source!(cert, cert_pem)
+      raise UsageError, "ExternalSigner needs a block that signs the bytes it is given" unless block
+    end
+
+    # Redacted for the same reason {LocalPem} is. Nothing here is key
+    # material — that is the point of this provider — but a block closes over
+    # whatever built it, which in practice is a client holding credentials.
+    def inspect
+      "#<#{self.class.name} cert=#{form} algorithm=#{@algorithm}>"
+    end
+
+    def certificate
+      @certificate ||= @cert_pem || Material.read(@cert_path, "certificate_unreadable")
+    end
+
+    # Signs `pdf` in two calls, with the block in between.
+    #
+    # Both engine calls take the same document, certificate and algorithm:
+    # the pair is stateless, so the second re-derives what the first prepared.
+    # Keeping them inside ONE method is what makes that impossible to get
+    # wrong from Ruby — there is no way to pair a prepare of one document
+    # with a complete of another.
+    #
+    # A prepare that did not succeed is returned as it is: an unreadable
+    # certificate or a document the signer refuses is a fact about the
+    # inputs, and paying for a signature afterwards would tell the caller
+    # nothing new.
+    def sign_with(engine, pdf)
+      prepared = engine.sign_prepare(pdf: pdf, certificate: certificate, algorithm: @algorithm)
+      return prepared unless prepared.status.zero? && prepared.success
+
+      engine.sign_complete(
+        pdf: pdf, certificate: certificate, algorithm: @algorithm,
+        signature: signature_for(prepared)
+      )
+    end
+
+    private
+
+    # Runs the block over the bytes the engine wants signed.
+    #
+    # The block's own exceptions are deliberately not rescued: it is the
+    # caller's code talking to the caller's key service, and turning its
+    # failures into a failed {Result} would file a caller's outage under
+    # "something was wrong with this document".
+    # `unpack1("m")` rather than `Base64.decode64`: base64 is a bundled gem
+    # now, and this SDK's runtime dependency list is exactly one entry
+    # (fiddle) on purpose. The unpack directive is core String, so decoding
+    # the payload costs nothing an application has to install.
+    def signature_for(prepared)
+      to_be_signed = JSON.parse(prepared.json).fetch("toBeSigned").unpack1("m")
+      signature = @block.call(to_be_signed)
+      unless signature.is_a?(String) && !signature.empty?
+        raise UsageError,
+              "the signer block must return the signature as a non-empty String of bytes"
+      end
+
+      signature.b
+    end
+
+    def wire_algorithm(algorithm)
+      raise UsageError, "ExternalSigner needs `algorithm:` (#{named})" if algorithm.nil?
+
+      ALGORITHMS.fetch(algorithm.to_sym) do
+        raise UsageError, "`algorithm:` must be one of #{named}"
+      end
+    end
+
+    def named
+      ALGORITHMS.keys.map(&:inspect).join(" or ")
+    end
+
+    # The path, or a note that the bytes came from memory — a configured path
+    # is not secret, and it is the one thing worth seeing when a provider
+    # loaded the wrong certificate.
+    def form
+      @cert_path ? @cert_path.to_s : "[pem bytes]"
+    end
+
+    # Explicit, never sniffed, in BOTH directions — {LocalPem}'s rule, for
+    # the same reason: guessing whether a string is a path or a PEM body is
+    # how the wrong file gets read.
+    def one_source!(path, pem)
+      raise UsageError, "ExternalSigner takes either #{FORMS}, not both" if path && pem
+      return if path || pem
+
+      raise UsageError, "ExternalSigner needs either #{FORMS}"
+    end
+  end
+end

data/lib/shojiku/local_pem.rb

@@ -3,10 +3,10 @@
 module Shojiku
   # A signing provider backed by a PEM key and certificate.
   #
-  # The only provider this release has. KMS and HSM providers are a recorded
-  # deferral, which is why this is a named class rather than a pair of
-  # arguments on `sign` — a second provider then adds a class, not a signature
-  # change in seven languages.
+  # For a key this process may hold. When it may not — a cloud KMS, an HSM, a
+  # smartcard — the provider is an {ExternalSigner} instead, which is why this
+  # is a named class rather than a pair of arguments on `sign`: the second
+  # provider added a class, not a signature change in seven languages.
   #
   # The material comes either from paths (`key:` / `cert:`) or from bytes
   # already in memory (`key_pem:` / `cert_pem:`), so a key fetched from a
@@ -53,6 +53,16 @@ module Shojiku
       @certificate ||= @cert_pem || Material.read(@cert_path, "certificate_unreadable")
     end
 
+    # Signs `pdf`, in one call, with the key this provider holds.
+    #
+    # Each provider knows how to reach the engine for its own kind of key, so
+    # the client asks the provider rather than branching on its class — the
+    # difference between a local key and one held elsewhere is two engine
+    # calls instead of one, and that belongs here.
+    def sign_with(engine, pdf)
+      engine.sign(pdf: pdf, key: key, certificate: certificate, passphrase: passphrase)
+    end
+
     private
 
     # The path, or a note that the bytes came from memory. A configured file

data/lib/shojiku/version.rb

@@ -3,5 +3,5 @@
 module Shojiku
   # Tracks the engine workspace version. All seven SDKs move together while
   # everything is pre-1.0 and publish together at the first public release.
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/shojiku.rb

@@ -14,6 +14,7 @@ require_relative "shojiku/result"
 require_relative "shojiku/verification_report"
 require_relative "shojiku/artifact"
 require_relative "shojiku/local_pem"
+require_relative "shojiku/external_signer"
 require_relative "shojiku/lockdown"
 require_relative "shojiku/sources"
 require_relative "shojiku/template_root"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shojiku
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - kengos
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-02 00:00:00.000000000 Z
+date: 2026-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fiddle
@@ -45,6 +45,7 @@ files:
 - lib/shojiku/engine.rb
 - lib/shojiku/env.rb
 - lib/shojiku/errors.rb
+- lib/shojiku/external_signer.rb
 - lib/shojiku/failure.rb
 - lib/shojiku/library.rb
 - lib/shojiku/local_pem.rb
@@ -58,13 +59,13 @@ files:
 - lib/shojiku/template_root.rb
 - lib/shojiku/verification_report.rb
 - lib/shojiku/version.rb
-homepage: https://github.com/kengos/shojiku
+homepage: https://shojiku.pages.dev
 licenses:
 - MIT
 - Apache-2.0
 - BSD-3-Clause
 metadata:
-  homepage_uri: https://github.com/kengos/shojiku
+  homepage_uri: https://shojiku.pages.dev
   source_code_uri: https://github.com/kengos/shojiku/tree/main/sdk/ruby
   documentation_uri: https://github.com/kengos/shojiku/blob/main/docs/engine/README.md
   rubygems_mfa_required: 'true'