shojiku 0.1.0

data/lib/shojiku/lockdown.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # The input ceiling an operator can declare, and the named signing
+  # providers that go with it.
+  #
+  # Once signing is in the loop, template input is a security boundary:
+  # whoever controls the bytes controls what gets signed. A strict client
+  # therefore narrows where signable input may come from.
+  #
+  # * The bytes-first entrance ({Client#generate_source}) is refused, so
+  #   every document this client signs came from the configured template
+  #   root, with its containment rules.
+  # * An artifact this client did not render ({Client#artifact}) may not be
+  #   signed — those bytes are the caller's, exactly like a bytes-first
+  #   template.
+  # * Signing material must be a provider REGISTERED in configuration and
+  #   named at the call site, so a key path never appears in
+  #   request-handling code and the material is loaded by one object rather
+  #   than rebuilt per request.
+  #
+  # **Verification is never restricted.** Verifying bytes of unknown
+  # provenance is the entire point of verify, and a locked-down deployment is
+  # precisely the one that needs to check an archived document it did not
+  # produce.
+  #
+  # Refusals raise {UsageError} rather than returning a failed {Result}:
+  # strict disables an ENTRANCE, so calling it is the program contradicting
+  # its own deployment's configuration — not a fact about a document — and a
+  # failed result is something `if result.success?` can swallow.
+  #
+  # The six other SDKs mirror this with identical semantics. It is contract,
+  # not ecosystem idiom.
+  class Lockdown
+    def initialize(strict:, providers: nil)
+      @strict = strict
+      # Registered under symbols whatever the caller wrote them as. A
+      # configuration hash keyed by strings is the ordinary Ruby spelling,
+      # and looking it up only by symbol would answer "no signing provider
+      # named `invoice` is registered" for a provider named exactly that.
+      @providers = (providers || {}).transform_keys(&:to_sym)
+    end
+
+    def strict?
+      @strict
+    end
+
+    # The bytes-first entrance.
+    def source_entrance!
+      return unless @strict
+
+      raise UsageError,
+            "this client is strict: templates must come from the template root, so " \
+            "`generate_source` is disabled. Use `generate(name, params)`."
+    end
+
+    # An artifact about to be signed. Only a document laid out from a template
+    # the ROOT resolved qualifies — bytes handed over whole, and bytes laid
+    # out from a caller's own template, are the same trust class here. That
+    # closes the gap a boolean "was it loaded" would leave open: an artifact
+    # from another client's bytes-first render is not this deployment's
+    # document either.
+    def signable!(artifact)
+      return unless @strict && artifact.origin != :rendered
+
+      raise UsageError,
+            "this client is strict: only a document rendered from its own template " \
+            "root may be signed (this one is #{artifact.origin}). It can still be " \
+            "verified."
+    end
+
+    # The provider to sign with.
+    #
+    # A Symbol or String is a registered name, in strict mode and out of it —
+    # naming providers is good practice everywhere, and only the REFUSAL of
+    # the alternative is strict's. A provider object is accepted only when
+    # this client is not strict.
+    def provider!(provider)
+      return registered!(provider) if provider.is_a?(Symbol) || provider.is_a?(String)
+      return provider unless @strict
+
+      raise UsageError,
+            "this client is strict: sign with the name of a provider registered in " \
+            "configuration, not with a provider object."
+    end
+
+    private
+
+    def registered!(name)
+      @providers.fetch(name.to_sym) do
+        raise UsageError, "no signing provider named `#{Echo.bounded(name)}` is registered"
+      end
+    end
+  end
+end

data/lib/shojiku/log.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # The optional host-side log channel.
+  #
+  # Silent unless an application supplies a logger, and deliberately narrow:
+  # it reports what the BINDING did — which library it loaded, which ABI
+  # revision it found, which lifecycle step ran and for how long — and never
+  # what the document contained. Params, rendered bytes, diagnostics and key
+  # material are all outside this channel BY RULE, because a log line is the
+  # easiest way for a secret to leave a process, and because a diagnostic
+  # belongs to the {Result} the caller already has.
+  #
+  # What does cross is bounded first ({Echo}), so a hostile template name
+  # cannot smuggle control characters into a log file.
+  #
+  # Any object answering `debug` is accepted — `Logger`, `Rails.logger`, or an
+  # application's own — so the gem's runtime dependency list stays at exactly
+  # one entry. The cross-language rule the other six mirror: each SDK accepts
+  # its ecosystem's standard logger interface, optionally.
+  class Log
+    def initialize(logger = nil)
+      @logger = logger
+    end
+
+    # Records one host event. The message is built only when someone is
+    # listening: a silent log costs a nil check, not string formatting.
+    def event(name, **fields)
+      return unless @logger
+
+      @logger.debug("shojiku #{name}#{render(fields)}")
+    end
+
+    # Times one lifecycle operation and returns what the block returned.
+    #
+    # The block is expected to produce a {Result}, whose verdict is recorded
+    # as `ok` — the one thing worth knowing about an operation that is not
+    # its content.
+    def timed(name, **fields)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = yield
+      event(name, **fields, ms: elapsed_ms(started), ok: result.success?)
+      result
+    end
+
+    private
+
+    def elapsed_ms(started)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(1)
+    end
+
+    def render(fields)
+      fields.map { |key, value| " #{key}=#{value}" }.join
+    end
+  end
+end

data/lib/shojiku/outcome.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # Turning one engine {Snapshot} into the {Result} an application sees.
+  #
+  # The C surface's two levels of failure meet here, and keeping them apart is
+  # the whole job: a non-zero status is the CALLER's mistake and raises, while
+  # everything a DOCUMENT can do wrong comes back as a failed result with the
+  # engine's diagnostics attached.
+  module Outcome
+    class << self
+      # A non-zero status is the C surface saying the CALLER got it wrong — a
+      # null pointer, a request the schema rejects, an argument past a hard
+      # cap. That is programmer misuse in Ruby terms, so it raises.
+      def guard!(snapshot)
+        return if snapshot.status.zero?
+
+        raise UsageError,
+              "the engine refused the call (status #{snapshot.status}): #{snapshot.error}"
+      end
+
+      # A rendered or signed document. Diagnostics are attached either way: a
+      # render that WORKED can still have warned.
+      def document(snapshot, step:, client:, origin:)
+        guard!(snapshot)
+        diagnostics = Diagnostic.parse(snapshot.diagnostics)
+        return refused(snapshot, step, diagnostics) unless snapshot.success
+
+        Result.succeeded(artifact(snapshot, diagnostics, client, origin), diagnostics)
+      end
+
+      # A verification verdict.
+      #
+      # The report is parsed BEFORE the verdict is read, because it rides a
+      # FAILED verify too — that is the whole point of carrying `not_checked`.
+      # Diagnostics are parsed on both paths for the same reason they are on a
+      # render: whatever the engine noticed belongs to the caller, and an
+      # operation that drops them makes its result mean something different
+      # from every other operation's.
+      def verdict(snapshot)
+        guard!(snapshot)
+        diagnostics = Diagnostic.parse(snapshot.diagnostics)
+        report = snapshot.json.empty? ? nil : VerificationReport.parse(snapshot.json)
+        return Result.succeeded(report, diagnostics) if snapshot.success
+
+        failure = Failure.from_error_json(
+          snapshot.error, step: :verify, diagnostics: diagnostics
+        )
+        Result.new(value: report, diagnostics: diagnostics, failure: failure)
+      end
+
+      private
+
+      def artifact(snapshot, diagnostics, client, origin)
+        DocumentArtifact.new(
+          bytes: snapshot.pdf, diagnostics: diagnostics, client: client,
+          page_count: page_count(snapshot.json), origin: origin
+        )
+      end
+
+      def refused(snapshot, step, diagnostics)
+        Result.failed(
+          Failure.from_error_json(snapshot.error, step: step, diagnostics: diagnostics)
+        )
+      end
+
+      # Absent (not zero) on a signed artifact: signing appends a revision to
+      # bytes it never laid out, and the surface returns no JSON payload for
+      # it at all.
+      def page_count(json)
+        json.empty? ? nil : JSON.parse(json)["pageCount"]
+      end
+    end
+  end
+end

data/lib/shojiku/request.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # The one JSON envelope every document operation crosses with.
+  #
+  # Both entrances build it: sources resolved from a template NAME and
+  # sources the application handed over as BYTES produce the same request,
+  # because the C surface has one request schema — and that schema rejects
+  # unknown keys, so a key the engine may legitimately not receive is dropped
+  # rather than sent as null.
+  class Request
+    def initialize(sources:, params:, lang: nil, font_dirs: [], locale_dirs: [])
+      @sources = sources
+      @params = params
+      @lang = lang
+      @font_dirs = font_dirs
+      @locale_dirs = locale_dirs
+    end
+
+    # The serialized envelope, turning the one failure JSON generation has
+    # into this gem's own exception.
+    #
+    # Params that are not valid UTF-8 are programmer misuse — the engine's
+    # surface is UTF-8 by contract, so there is nothing to render — but a bare
+    # `JSON::GeneratorError` escaping from `generate` would make callers
+    # rescue a foreign class they never invited into their code.
+    def json
+      JSON.generate(envelope)
+    rescue JSON::GeneratorError, Encoding::UndefinedConversionError => e
+      raise UsageError, "params could not be serialized as UTF-8 JSON: #{e.message}"
+    end
+
+    private
+
+    def envelope
+      {
+        template: @sources.template,
+        definitions: @sources.definitions,
+        params: params_source,
+        lang: @lang,
+        fontDirs: @font_dirs,
+        localeDirs: @locale_dirs,
+        assetsDir: @sources.assets_dir
+      }.compact
+    end
+
+    # A String params is the caller's own source text, passed through
+    # VERBATIM: the engine parses JSON or YAML (YAML is a superset), so
+    # re-encoding it here would only be a chance to change it. Anything else
+    # is serialized as JSON.
+    #
+    # There is deliberately no per-format method family — format dispatch is
+    # the engine's, and an SDK that offered `generate_yaml` would be claiming
+    # a distinction the engine does not make.
+    def params_source
+      @params.is_a?(String) ? @params : JSON.generate(@params)
+    end
+  end
+end

data/lib/shojiku/result.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # What every lifecycle operation returns.
+  #
+  # Nothing in the normal flow raises. A template that will not render, a key
+  # that will not sign, a signature that does not verify are all data you
+  # query — `success?`, the value, the engine's diagnostics either way, and on
+  # failure the {Failure} trace.
+  #
+  # Diagnostics ride on a SUCCESS too. A render that worked can still have
+  # warned about an overflowing box, and a caller that only looks at failures
+  # never sees them.
+  class Result
+    attr_reader :value, :diagnostics, :failure
+
+    def self.succeeded(value, diagnostics)
+      new(value: value, diagnostics: diagnostics)
+    end
+
+    def self.failed(failure)
+      new(failure: failure, diagnostics: failure.diagnostics)
+    end
+
+    def initialize(value: nil, diagnostics: [], failure: nil)
+      @value = value
+      @diagnostics = diagnostics
+      @failure = failure
+    end
+
+    def success?
+      @failure.nil?
+    end
+
+    def failure?
+      !success?
+    end
+
+    # `value` under the name of what the operation produced. Both are the same
+    # object; the aliases exist so calling code reads as what it is doing.
+    alias artifact value
+    alias report value
+
+    # The value, or a raised {UnwrapError} when the operation failed.
+    #
+    # The opt-in bridge for a script that wants a stack trace rather than a
+    # branch, and the ONE place this API raises for something other than a
+    # misused argument. That is why the ruling is stated rather than implied,
+    # and frozen for every Shojiku SDK: **calling unwrap on a failed result is
+    # programmer misuse** — a caller who has not checked `success?` is
+    # asserting the operation worked. Application code that handles failure
+    # keeps using `success?` and {#failure}; nothing in this gem calls these.
+    #
+    # (Go is the recorded exception: the language has no exceptions, so its
+    # SDK mirrors the shape as an error return rather than a panic.)
+    def value!
+      raise UnwrapError, @failure if @failure
+
+      @value
+    end
+
+    alias artifact! value!
+    alias report! value!
+
+    # Only the diagnostics that are errors — the ones that explain a refusal.
+    def errors
+      @diagnostics.select(&:error?)
+    end
+
+    # Only the warnings, which a SUCCESSFUL result can carry.
+    def warnings
+      @diagnostics.select(&:warning?)
+    end
+  end
+end

data/lib/shojiku/settings.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # One client's resolved configuration, plus the collaborators built from it.
+  #
+  # {Config} answers "what was configured"; this answers "what does THIS
+  # client use", which is the merge of the process-wide defaults with the
+  # arguments the client was constructed with. Keeping it out of {Client}
+  # keeps the precedence rules in one readable place instead of spread across
+  # a constructor.
+  #
+  # Everything is built lazily and memoized: a bytes-first application never
+  # configures a template root, and demanding one at construction would refuse
+  # a legitimate client.
+  class Settings
+    attr_reader :lang
+
+    def initialize(**overrides)
+      @config = Shojiku.config.merge(overrides)
+      @lang = @config.lang
+    end
+
+    # A copy that renders in `lang`, for {Client#with_lang}. Everything
+    # already built — the opened library, the template root, the lockdown —
+    # is carried over by `dup`, so deriving a client re-opens nothing.
+    def with_lang(lang)
+      copy = dup
+      copy.override_lang(lang)
+      copy
+    end
+
+    def env
+      @env ||= Env.new(enabled: @config.env)
+    end
+
+    def log
+      @log ||= Log.new(@config.logger)
+    end
+
+    def lockdown
+      @lockdown ||= Lockdown.new(strict: @config.strict, providers: @config.providers)
+    end
+
+    def library
+      @library ||= Library.new(path: @config.library, env: env, log: log)
+    end
+
+    def font_dirs
+      @font_dirs ||= @config.font_dirs || env.paths("SHOJIKU_FONT_DIR")
+    end
+
+    def locale_dirs
+      @locale_dirs ||= @config.locale_dirs || env.paths("SHOJIKU_LOCALE_DIR")
+    end
+
+    # The template root, or nil when nothing configured one.
+    #
+    # `defined?` rather than `||=` because nil is a legitimate answer here and
+    # would otherwise be re-resolved on every call.
+    def template_root
+      return @template_root if defined?(@template_root)
+
+      root = @config.templates || env["SHOJIKU_TEMPLATE_ROOT"]
+      @template_root = root ? TemplateRoot.new(root) : nil
+    end
+
+    protected
+
+    # Only {#with_lang} calls this, on a copy nobody else can see yet.
+    def override_lang(lang)
+      @lang = lang
+    end
+  end
+end

data/lib/shojiku/sources.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # The sources one render runs over: the template text, the definitions text
+  # when there are any, and the directory bundled assets resolve against.
+  #
+  # A value rather than a file layout, because there are two ways to get one
+  # and only one of them involves the filesystem. {TemplateRoot} produces it
+  # by resolving a NAME; {Client#generate_source} produces it from bytes the
+  # application already has. Everything downstream — the request envelope, the
+  # engine — sees the same object either way, which is what keeps the second
+  # entrance from being a second code path.
+  Sources = Data.define(:template, :definitions, :assets_dir)
+end

data/lib/shojiku/template_root.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # Resolving a template NAME to the sources behind it.
+  #
+  # A name is an identifier, never a path. A bundle format will take this
+  # lookup over later, so nothing outside this class may assume a directory is
+  # how names resolve — callers ask for `"receipt_ja"` and get sources back.
+  #
+  # **The rejection rules are the union across platforms, not the host's.**
+  # Windows is a first-class target (it is what the .NET SDK's market runs
+  # on), so a backslash is a separator, `C:name` is drive-relative,
+  # `\\host\share` is a UNC path and `CON`/`NUL` are reserved devices —
+  # every one of them refused on EVERY platform. A template name that is
+  # valid on one machine is valid on all of them, which is the only way the
+  # same application deploys to both.
+  class TemplateRoot
+    # Reserved DOS device names. Windows resolves these no matter what
+    # directory you are in and no matter what extension you append.
+    DEVICES = (%w[CON PRN AUX NUL] +
+               (1..9).flat_map { |n| ["COM#{n}", "LPT#{n}"] }).freeze
+
+    # A name is ONE segment. Refusing both separators outright subsumes
+    # traversal, absolute paths and nested lookups in a single rule — the
+    # simplest thing six other SDKs can mirror without drifting.
+    SEPARATORS = %r{[/\\]}
+    DRIVE_RELATIVE = /\A[A-Za-z]:/
+    CONTROL = /[\x00-\x1f\x7f]/
+
+    TEMPLATE_FILE = "templates.yml"
+    DEFINITIONS_FILE = "definitions.yml"
+
+    # Each rule, and what a caller is told when it fires. The keys are the
+    # predicate names below, so adding a rule is one entry plus one method.
+    RULES = {
+      "separator" => "a name is one segment, so `/` and `\\` are never part of it " \
+                     "(which is also what makes `..` traversal impossible)",
+      "control" => "it contains a control character",
+      "drive_relative" => "it is drive-relative, which Windows resolves against " \
+                          "that drive's current directory",
+      "device" => "it is a reserved device name on Windows"
+    }.freeze
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+    end
+
+    # Resolves `name`, or raises {Rejected} naming why it will not.
+    #
+    # Rejection is an exception INSIDE this class and a failed Result outside
+    # it (see {Client#generate}) — a hostile template name is a fact about the
+    # request, not a bug in the calling program.
+    def resolve(name)
+      identifier!(name)
+      reject!(name)
+      dir = File.join(@path, name)
+      real = contained!(dir)
+      Sources.new(
+        template: read!(File.join(real, TEMPLATE_FILE)),
+        definitions: optional(File.join(real, DEFINITIONS_FILE)),
+        assets_dir: real
+      )
+    end
+
+    # A refused name or an unreadable template, with the machine-readable
+    # `kind` the failure trace carries.
+    class Rejected < StandardError
+      attr_reader :kind, :cause_message
+
+      def initialize(kind, message, cause_message: nil)
+        @kind = kind
+        @cause_message = cause_message
+        super(message)
+      end
+    end
+
+    private
+
+    # A name is an IDENTIFIER, so anything that is not a string is a bug in
+    # the calling program rather than a hostile request — and it has to be
+    # caught here, because a Symbol otherwise passes every rule below (a
+    # Regexp matches one happily) and dies inside `File.join` as a `TypeError`
+    # from a stdlib method the caller never called.
+    #
+    # A BLANK string is the other case and stays a refused request: it can
+    # arrive straight from a form field.
+    def identifier!(name)
+      return if name.is_a?(String)
+
+      raise UsageError,
+            "a template name must be a String; got #{name.class}. Sources you " \
+            "already hold go to `generate_source`."
+    end
+
+    def reject!(name)
+      raise Rejected.new("template_name", "a template name must not be empty") if blank?(name)
+
+      RULES.each_key do |rule|
+        next unless send(:"#{rule}?", name)
+
+        raise Rejected.new(
+          "template_name",
+          "`#{Echo.bounded(name)}` is not a template name: #{RULES.fetch(rule)}"
+        )
+      end
+    end
+
+    def blank?(name)
+      name.strip.empty?
+    end
+
+    def separator?(name)
+      SEPARATORS.match?(name)
+    end
+
+    def control?(name)
+      CONTROL.match?(name)
+    end
+
+    def drive_relative?(name)
+      DRIVE_RELATIVE.match?(name)
+    end
+
+    # Trailing dots and spaces are STRIPPED by Windows before it resolves a
+    # name, so `CON.` and `"CON "` are the CON device just as `CON` is.
+    # Without that strip they slip past this rule and are refused later, by
+    # containment — still refused, but with a message about a missing
+    # template rather than about a reserved name.
+    def device?(name)
+      stem = name.split(".").first.to_s.sub(/[.\s]+\z/, "")
+      DEVICES.include?(stem.upcase)
+    end
+
+    # The check a name-shape rule cannot make: after following whatever the
+    # filesystem has there, is the answer still inside the root? A symlink is
+    # what this exists for — it passes every rule above and still points out.
+    def contained!(dir)
+      root = File.realpath(@path)
+      real = File.realpath(dir)
+      inside = real == root || real.start_with?("#{root}#{File::SEPARATOR}")
+      return real if inside
+
+      raise Rejected.new("template_escapes_root",
+                         "the template resolves outside the template root")
+    rescue Errno::ENOENT, Errno::ENOTDIR => e
+      raise Rejected.new("template_not_found", "no template by that name", cause_message: e.message)
+    end
+
+    def read!(path)
+      File.read(path, encoding: Encoding::UTF_8)
+    rescue SystemCallError => e
+      raise Rejected.new("template_unreadable", "the template could not be read",
+                         cause_message: e.message)
+    end
+
+    def optional(path)
+      File.file?(path) ? read!(path) : nil
+    end
+  end
+end

data/lib/shojiku/verification_report.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # What verification found — INCLUDING what it did not look at.
+  #
+  # `not_checked` is a field, not a footnote, and this binding passes it
+  # through untouched. A "valid" verdict that quietly skipped revocation is
+  # worse than no verifier at all: it turns a missing capability into a false
+  # assurance, which is exactly the trust a signing feature sells. Dropping it
+  # on the way through an SDK would be the same lie one layer up.
+  #
+  # The four checks stay separate for the same reason. "The signature is valid
+  # but covers only part of the file" is a different fact from "the signature
+  # is wrong", and a caller that cannot tell them apart cannot explain the
+  # answer to anyone.
+  class VerificationReport
+    # The outcome of one check: `passed`, or `failed` with the reason.
+    class Check
+      attr_reader :status, :reason
+
+      def initialize(item)
+        @status = item["status"]
+        @reason = item["reason"]
+      end
+
+      def passed?
+        @status == "passed"
+      end
+
+      def to_s
+        @reason ? "#{@status}: #{@reason}" : @status.to_s
+      end
+    end
+
+    attr_reader :signature, :coverage, :certificate_validity, :trust_chain, :not_checked
+
+    def self.parse(json)
+      new(JSON.parse(json))
+    end
+
+    def initialize(payload)
+      @valid = payload["valid"]
+      @signature = Check.new(payload["signature"])
+      @coverage = Check.new(payload["coverage"])
+      @certificate_validity = Check.new(payload["certificateValidity"])
+      @trust_chain = Check.new(payload["trustChain"])
+      @not_checked = Array(payload["notChecked"]).map(&:to_sym).freeze
+    end
+
+    # Whether every check this release PERFORMS passed. Read `not_checked`
+    # beside it: this is not "the document is trustworthy", it is "nothing we
+    # looked at was wrong".
+    def valid?
+      @valid == true
+    end
+
+    def checks
+      { signature: @signature, coverage: @coverage,
+        certificate_validity: @certificate_validity, trust_chain: @trust_chain }
+    end
+  end
+end

data/lib/shojiku/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+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"
+end