shojiku 0.1.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d86825fdae8fc7dccbb563e21959290f8753f59cd8f420af7bd409dde7b98500
+  data.tar.gz: b5b298be47d729631ed20fe951ddbb6029f92d4d6066c59aa38cd2faef1ed53c
+SHA512:
+  metadata.gz: e27af49e536e8d94c556f997369e36ae430e9d5fa47f8cf10e91d014001651646ce2fc2464da2f84c9426666e2681a5a9b437ba65ac283ce40ad3493f23671d4
+  data.tar.gz: 1d85cc726209f3cc6f5d0b8468db35209caa5c9cb9f57278b56e83c4949e9ee893863593446b749cf81cb38e7bdd4866d3ff043ed50eb19bc57aad6ba6e38aea

data/README.md

@@ -0,0 +1,319 @@
+# Shojiku for Ruby
+
+Ruby bindings for [Shojiku](../../README.md) — 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
+bundle add shojiku
+```
+
+Platform gems carry a prebuilt engine library, so there is no build step
+on the supported platforms (Linux and macOS on x86-64 and arm64, Windows
+on x86-64). The engine is loaded through `fiddle` from the standard
+library rather than as a native extension, which means one binary serves
+every supported Ruby — no recompile when you upgrade the interpreter.
+
+## Usage
+
+```ruby
+require "shojiku"
+
+client = Shojiku::Client.new(templates: "app/templates")
+
+result = client.generate("receipt_ja", {
+  customer: { name: "Yamada Shoji K.K." },
+  items: [{ name: "Consulting", qty: 1, price: 120_000 }],
+})
+
+if result.success?
+  result.artifact.write("receipt.pdf")
+else
+  result.failure.causes.each { |cause| warn cause.to_s }
+end
+```
+
+`params` is a Hash, or a String you already have — JSON *or* YAML, since
+the engine parses either and a String is passed through verbatim. There
+is no per-format method: format dispatch is the engine's.
+
+To render one template in several locales, derive a client:
+
+```ruby
+client.with_lang("ja-JP").generate("receipt_ja", params)
+```
+
+A derived client shares the loaded engine — deriving re-opens nothing —
+and the locale it names beats the one the client was built with.
+
+### Sources you already hold
+
+`generate` resolves a template *name* against the configured root.
+When the sources come from somewhere else — object storage, a database,
+a heredoc — hand them over directly:
+
+```ruby
+result = client.generate_source(
+  template: File.read("invoice.yml"),   # source text, never a path
+  definitions: definitions_yaml,        # optional
+  assets_dir: "app/templates/invoice",  # optional; bundled images resolve here
+  params: params
+)
+```
+
+Fetching the bytes stays your application's act: this gem opens no
+sockets and reads no template off disk here. `template:` is **source
+text** — a value that looks like a path is a template that fails to
+parse, not a file this gem will open — so the containment rules that
+guard the name entrance are not being bypassed, they are simply not
+involved. A deployment that wants to forbid this entrance entirely
+declares [`strict:`](#locking-down-where-signable-input-comes-from).
+
+An archived document goes back in the same way:
+
+```ruby
+archived = client.artifact(File.binread("2026-invoices/0042.pdf"))
+archived.verify(anchors: "ca.crt")
+```
+
+Signing is a separate step over the rendered document, and verification
+is a separate step over that:
+
+```ruby
+signed = result.artifact.sign(
+  Shojiku::LocalPem.new(key: "signer.key", cert: "signer.crt")
+)
+
+checked = signed.artifact.verify(anchors: "ca.crt")
+checked.report.valid?        # every check this release performs passed
+checked.report.not_checked   # => [:revocation, :timestamp]
+```
+
+**Read `not_checked` beside the verdict.** `valid?` means "nothing we
+looked at was wrong", not "this document is trustworthy" — revocation
+and timestamping are not checked in this release, and the report says so
+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.
+
+### Results, not exceptions
+
+Nothing raises in the normal flow. Every operation returns a result you
+query — `success?`, the artifact or report, and the engine's diagnostics
+either way (a render that *worked* can still have warned about an
+overflowing box). A failure carries a trace: which step failed, a stable
+`kind`, the message, and the cause chain underneath it.
+
+```ruby
+result.warnings.each { |d| logger.warn("#{d.code}: #{d.message}") }
+result.failure.step        # => :generate
+result.failure.kind        # => "template_not_found"
+result.failure.causes      # => [the failure, its cause, …]
+```
+
+Diagnostics keep the engine's stable `code` and typed `args` untouched,
+so an application that renders its own localized messages has everything
+it needs. This gem never translates them.
+
+Exceptions are reserved for what Ruby reserves them for: programmer
+misuse (`Shojiku::UsageError`) and an environment with no engine in it
+(`Shojiku::LibraryNotFound`).
+
+For a script that would rather have a stack trace than a branch, there
+is an opt-in unwrap:
+
+```ruby
+client.generate("receipt_ja", params).artifact!.write("receipt.pdf")
+```
+
+`artifact!` / `report!` raise `Shojiku::UnwrapError` (carrying the whole
+failure) when the result failed. The ruling behind them is deliberate
+and shared by 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?`.
+
+## Templates
+
+Template names are **identifiers, never paths**. A name resolves against
+the configured template root:
+
+```text
+app/templates/
+  receipt_ja/
+    templates.yml     (required)
+    definitions.yml   (optional)
+    assets/           (optional — bundled images resolve against it)
+```
+
+Names containing a path separator, a `..` segment, a drive letter, a UNC
+prefix, a control character, or a reserved Windows device name (`CON`,
+`NUL`, `COM1`, …) are refused — on **every** platform, not only the ones
+where they would resolve, so a name that works in development works in
+production. A name that resolves outside the root through a symlink is
+refused after canonicalization.
+
+Every one of those is a *failed result*: a hostile name is a fact about
+the request, not a bug in your program. A name that is not a String at
+all is the other thing, and raises.
+
+## Configuration
+
+```ruby
+Shojiku::Client.new(
+  templates: "app/templates",   # the template root
+  font_dirs: ["vendor/fonts"],  # extra font-pack search directories
+  locale_dirs: ["vendor/locales"],
+  lang: "ja-JP",                # overrides the template's own default
+  library: "/opt/lib/libshojiku_capi.so",
+  logger: Rails.logger,         # optional; host events only (see Logging)
+  strict: true,                 # the input ceiling (see below)
+  providers: { invoice: … },    # signing providers, by name
+  env: true                     # consult SHOJIKU_* variables at all
+)
+```
+
+| Variable | What it sets |
+| --- | --- |
+| `SHOJIKU_TEMPLATE_ROOT` | the template root |
+| `SHOJIKU_FONT_DIR` | font-pack directories (`PATH`-separated) |
+| `SHOJIKU_LOCALE_DIR` | locale-pack directories (`PATH`-separated) |
+| `SHOJIKU_LIBRARY` | the engine library to load |
+
+`env: false` disables **all** of them at once, for an application that
+wants its configuration to come from nowhere but its own code.
+
+The same settings can be defaults for every client, in the idiom an
+initializer expects:
+
+```ruby
+Shojiku.configure do |config|
+  config.templates = "app/templates"
+  config.lang = "ja-JP"
+  config.logger = Rails.logger
+end
+```
+
+This sets defaults for the constructor; it does not add a precedence
+layer. An explicit argument still wins, and a configured value still
+wins over the environment — with `strict:` the one deliberate exception
+(below). `Shojiku.reset_configuration!` drops the lot, which is what a
+test suite wants between examples.
+
+### Locking down where signable input comes from
+
+Once you sign what you render, template input is a security boundary:
+whoever controls the bytes controls what gets signed. An operator can
+declare a ceiling:
+
+```ruby
+Shojiku.configure do |config|
+  config.strict = true
+  config.providers = { invoice: Shojiku::LocalPem.new(key: "signer.key", cert: "signer.crt") }
+end
+
+client.sign(document, :invoice)   # by name; the key path is not here
+```
+
+A strict client:
+
+- refuses `generate_source`, so every document it signs came from the
+  template root and its containment rules;
+- signs only a document it rendered from that root — bytes handed over
+  whole (`client.artifact`) and bytes laid out from a caller's own
+  template are the same trust class, and signing does not launder them;
+- takes signing material only as the **name** of a provider registered
+  in configuration, so a key path never appears in request-handling code
+  and the material is loaded by one object.
+
+**Verification is never restricted.** Verifying bytes of unknown
+provenance is the point of verify, and a locked-down deployment is
+exactly the one that has to check an archived document it did not
+produce.
+
+Refusals raise `Shojiku::UsageError` rather than returning a failed
+result: strict disables an *entrance*, so calling it is the program
+contradicting its own deployment, not a fact about a document — and a
+failed result is something `if result.success?` can swallow. Strict is
+also the one setting `Shojiku.configure` wins outright: a restriction an
+operator declared must not be lifted by `Client.new(strict: false)`.
+
+### Logging
+
+Optional, silent by default, and narrow on purpose:
+
+```ruby
+Shojiku::Client.new(templates: "app/templates", logger: Rails.logger)
+```
+
+Any object answering `debug` is accepted (this gem takes no logger
+dependency). It reports what the *binding* did — which library it
+loaded and why that one, the ABI revision it found, which lifecycle step
+ran, for how long, and whether it worked. It never logs params, document
+bytes, key material, a passphrase, or the engine's diagnostics: a log
+line is the easiest way for a secret to leave a process, and the
+diagnostics already belong to the result you are holding.
+
+### Threads
+
+A render, a signature and a verification each release Ruby's global VM
+lock for the duration of the call into the engine, so a long render does
+not block other threads in the process. `Client` is safe to share across
+threads, and the engine library itself may be called concurrently — the
+same params produce the same bytes whether one thread is rendering or
+eight are.
+
+Explicit configuration wins for the template root and the pack
+directories — what an application renders is the application's own
+decision. `SHOJIKU_LIBRARY` is the one that goes the other way and beats
+an explicit `library:`, because *where the engine lives* is a deployment
+decision that has to be able to override application code. That is the
+same order `SHOJIKU_BIN` has in the SDKs that shell out to the CLI.
+
+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:
+
+```bash
+make capi-lib
+```
+
+It lands in `dist/capi/local/`; point `SHOJIKU_LIBRARY` at it, or pass
+`library:` to the client.
+
+## Development
+
+Every gate runs in a container — no Ruby toolchain needed locally:
+
+```bash
+make verify:sdk:ruby
+```
+
+`make test:sdk:ruby` and `make lint:sdk:ruby` are the faster slices.
+
+## Requirements
+
+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
+
+## License
+
+Licensed under any of [Apache-2.0](../../LICENSE-APACHE),
+[MIT](../../LICENSE-MIT), or [BSD-3-Clause](../../LICENSE-BSD), at your
+option.

data/lib/shojiku/artifact.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # A rendered (and possibly signed) document.
+  #
+  # The application sees bytes and metadata — never a layout-engine internal,
+  # and never a handle it has to free. Freeing is the binding's job and it is
+  # already done by the time this object exists.
+  class DocumentArtifact
+    # The PDF, as binary. Always `ASCII-8BIT`: PDF bytes are not text and
+    # tagging them as any character encoding is how a document gets corrupted
+    # by a well-meaning transcode on the way to disk.
+    attr_reader :bytes
+
+    # How many pages the engine laid out. `nil` for an artifact that was
+    # signed rather than rendered — signing appends a revision to bytes it
+    # never measured, and a zero there would read as "a document with no
+    # pages".
+    attr_reader :page_count
+
+    attr_reader :diagnostics
+
+    # Where this document came from, which is what a strict client signs on:
+    #
+    # * `:rendered` — laid out from a template the configured root resolved,
+    # * `:source` — laid out from template bytes the application supplied,
+    # * `:loaded` — bytes the application supplied whole ({Client#artifact}).
+    #
+    # Only the first is signable under a {Lockdown}: in the other two the
+    # provenance of what gets signed is the application's rather than the
+    # deployment's, which is the distinction strict exists to draw. Signing
+    # inherits the origin of what it signed — appending a revision does not
+    # launder where the document came from. Verification is never restricted.
+    attr_reader :origin
+
+    # `origin` defaults to the LEAST privileged value, not the most: every
+    # internal path states it explicitly, so the default only ever applies to
+    # an artifact somebody built by hand — which is bytes handed over whole,
+    # and must not become signable under a lockdown by omission.
+    def initialize(bytes:, diagnostics:, client:, page_count: nil, origin: :loaded)
+      @bytes = bytes
+      @page_count = page_count
+      @diagnostics = diagnostics
+      @client = client
+      @origin = origin
+    end
+
+    # Whether these bytes were handed over whole rather than laid out here.
+    def loaded?
+      @origin == :loaded
+    end
+
+    # Writes the document. Binary mode explicitly — a PDF contains NUL and
+    # every other byte value, and text mode would translate line endings on
+    # Windows.
+    def write(path)
+      File.binwrite(path, @bytes)
+      path
+    end
+
+    def size
+      @bytes.bytesize
+    end
+
+    # Signs this document, returning a {Result} carrying the signed artifact.
+    # The signed bytes begin with these bytes byte for byte: signing appends a
+    # revision, it never rewrites what was there.
+    def sign(provider)
+      @client.sign(self, provider)
+    end
+
+    # Verifies this document against caller-supplied trust anchors, returning
+    # a {Result} carrying a {VerificationReport}.
+    def verify(anchors: nil, anchors_pem: nil)
+      @client.verify(self, anchors: anchors, anchors_pem: anchors_pem)
+    end
+  end
+end

data/lib/shojiku/client.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Shojiku
+  # The entry point: a configured engine, and the sources to render with it.
+  #
+  # ```ruby
+  # client = Shojiku::Client.new(templates: "app/templates")
+  # result = client.generate("receipt_ja", customer: { name: "…" })
+  # result.artifact.write("receipt.pdf") if result.success?
+  # ```
+  #
+  # **Two entrances, deliberately.** {#generate} takes a template NAME and
+  # resolves it against the configured root, which is where the containment
+  # rules live. {#generate_source} takes the sources as BYTES the application
+  # already has — fetched from object storage, read out of a database, written
+  # inline — because fetching is the application's act and this gem downloads
+  # nothing. Root containment does not apply to bytes a caller supplied: there
+  # is no root to be contained by, which is exactly why a strict client
+  # refuses that entrance (see {Lockdown}).
+  #
+  # **Precedence, and its one deliberate asymmetry.** An explicit `templates:`
+  # beats {Shojiku.configure}, which beats `SHOJIKU_TEMPLATE_ROOT`; the pack
+  # directories resolve the same way. What an application renders is the
+  # application's own decision. An explicit `library:` is the other way round —
+  # `SHOJIKU_LIBRARY` beats it — because where the ENGINE lives is an
+  # operator's decision that has to be able to win over application code, the
+  # same order the subprocess SDKs give `SHOJIKU_BIN`. Passing `env: false`
+  # disables every one of those lookups at once. `strict:` is the one setting
+  # {Shojiku.configure} wins outright, for the reason in {Lockdown}.
+  class Client
+    ANCHOR_FORMS = "`anchors:` (paths) or `anchors_pem:` (bytes)"
+
+    def initialize(templates: nil, font_dirs: nil, locale_dirs: nil, lang: nil, library: nil,
+                   logger: nil, strict: nil, providers: nil, env: nil)
+      @settings = Settings.new(
+        templates:, font_dirs:, locale_dirs:, lang:, library:, logger:, strict:, providers:, env:
+      )
+      @engine = Engine.new(@settings.library)
+    end
+
+    def template_root
+      @settings.template_root
+    end
+
+    # A copy of this client that renders in `lang`, for the call — or the
+    # request — that needs a locale other than this client's own. A
+    # multi-locale application renders one template in each buyer's locale
+    # without building (or configuring) a second client.
+    #
+    # **A derived client rather than a `lang:` keyword on {#generate}, and
+    # that is a Ruby spelling of a contract every SDK shares.** `generate`
+    # takes its params as a trailing Hash, so a keyword argument beside it
+    # would turn the natural `generate("receipt", customer: …)` into an
+    # `unknown keyword: :customer` error — Ruby resolves that ambiguity
+    # against the common case. The other six, whose params are an ordinary
+    # argument, express the same override as a per-call option; what they
+    # mirror is that a per-call locale beats the client-wide one, not the
+    # spelling.
+    #
+    # The opened library, the template root and the lockdown are shared:
+    # deriving a client re-opens nothing.
+    def with_lang(lang)
+      copy = dup
+      copy.settings = @settings.with_lang(lang)
+      copy
+    end
+
+    # What this build of the engine can do — its version, capability keys and
+    # builtin locales. Gate a feature on this rather than on a gem version.
+    #
+    # A plain Hash, deliberately. The payload is an append-only wire this SDK
+    # does not model, exactly as a diagnostic's typed `args` pass through
+    # untranslated: a typed value object would have to grow a field in seven
+    # languages every time the engine adds one, and an application reading a
+    # key its engine is too old to send already has to handle nil.
+    def engine_info
+      snapshot = @engine.engine_info
+      Outcome.guard!(snapshot)
+      JSON.parse(snapshot.json)
+    end
+
+    # Renders `name` with `params`, returning a {Result}.
+    #
+    # `params` may be a Hash (serialized here) or a String you already have —
+    # JSON or YAML, since the engine parses either and a String is passed
+    # through verbatim. To render in another locale, see {#with_lang}.
+    #
+    # A rejected template name is a FAILED RESULT, not an exception: a hostile
+    # name is a fact about the request, not a bug in the program. A name that
+    # is not a String at all IS a bug in the program, and raises.
+    def generate(name, params = {})
+      sources = template_root!.resolve(name)
+      render(sources, params, origin: :rendered, template: Echo.bounded(name))
+    rescue TemplateRoot::Rejected => e
+      Result.failed(rejection(e, :generate))
+    end
+
+    # Renders sources the APPLICATION supplies, returning a {Result}.
+    #
+    # For templates that do not live in a directory this gem can see: fetched
+    # from object storage, stored in a database, or written inline. Fetching
+    # them stays the application's act — nothing here opens a socket.
+    #
+    # `assets_dir:` is per call rather than per client, because bundled assets
+    # belong to a template rather than to a deployment. Without it, bundled
+    # image sources are disabled: inline sources have no directory of their
+    # own. The locale is overridden the same way as for {#generate}, with
+    # {#with_lang} — one spelling, not two.
+    def generate_source(template:, definitions: nil, assets_dir: nil, params: {})
+      @settings.lockdown.source_entrance!
+      sources = Sources.new(template: template, definitions: definitions,
+                            assets_dir: assets_dir)
+      render(sources, params, origin: :source)
+    end
+
+    # Re-enters an archived document, so bytes signed some time ago can be
+    # verified — or re-signed — without hand-building an artifact.
+    #
+    # The result is marked as LOADED: its bytes are the caller's rather than
+    # this client's own render, which is a distinction a strict client acts
+    # on. `page_count` is nil, honestly: nothing here laid anything out.
+    def artifact(bytes)
+      DocumentArtifact.new(bytes: bytes, diagnostics: [], client: self, origin: :loaded)
+    end
+
+    # 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.
+    def sign(artifact, provider)
+      signer = @settings.lockdown.provider!(provider)
+      @settings.lockdown.signable!(artifact)
+      @settings.log.timed(:sign) { signed(artifact, signer) }
+    end
+
+    # Verifies an artifact against trust anchors, returning a {Result} whose
+    # value is a {VerificationReport}.
+    #
+    # Anchors are required and are given as paths (`anchors:`, one or several)
+    # or as PEM bytes (`anchors_pem:`, which may carry several concatenated).
+    # Which form you passed is explicit rather than sniffed, and passing both
+    # raises rather than silently preferring one. There is no fallback to the
+    # machine's trust store, because the engine never consults one — a default
+    # would answer a different question than you asked.
+    #
+    # A signature that does not verify is a FAILED result that still carries
+    # the report, so `not_checked` reaches you either way.
+    def verify(artifact, anchors: nil, anchors_pem: nil)
+      pem = anchor_material(anchors, anchors_pem)
+      @settings.log.timed(:verify) do
+        Outcome.verdict(@engine.verify(pdf: artifact.bytes, anchors: pem))
+      end
+    rescue MaterialUnreadable => e
+      Result.failed(Failure.new(step: :verify, kind: e.kind, message: e.message))
+    end
+
+    protected
+
+    # Written only by {#with_lang}, on a copy that is not yet visible to
+    # anyone — a derived client is built, not mutated.
+    attr_writer :settings
+
+    private
+
+    def render(sources, params, origin:, **fields)
+      request = Request.new(sources: sources, params: params, lang: @settings.lang,
+                            font_dirs: @settings.font_dirs, locale_dirs: @settings.locale_dirs)
+      @settings.log.timed(:generate, **fields) do
+        snapshot = @engine.render(request.json)
+        Outcome.document(snapshot, step: :generate, client: self, origin: origin)
+      end
+    end
+
+    # 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
+      )
+      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))
+    end
+
+    def template_root!
+      return template_root if template_root
+
+      raise UsageError,
+            "no template root: pass Shojiku::Client.new(templates: …), set it with " \
+            "Shojiku.configure, or set SHOJIKU_TEMPLATE_ROOT (which `env: false` " \
+            "disables). Sources you already hold go to `generate_source`."
+    end
+
+    def anchor_material(paths, pem)
+      raise UsageError, "verify takes either #{ANCHOR_FORMS}, not both" if paths && pem
+      return pem if pem
+      raise UsageError, "verify needs #{ANCHOR_FORMS}" if paths.nil?
+
+      Array(paths).map { |path| Material.read(path, "anchor_unreadable") }.join("\n")
+    end
+
+    def rejection(error, step)
+      cause = if error.cause_message
+                Failure.new(step: step, kind: "io", message: error.cause_message)
+              end
+      Failure.new(step: step, kind: error.kind, message: error.message, cause: cause)
+    end
+  end
+end