easy_code_sign 0.1.0

data/lib/easy_code_sign.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative "easy_code_sign/version"
+require_relative "easy_code_sign/errors"
+require_relative "easy_code_sign/configuration"
+require_relative "easy_code_sign/providers/base"
+require_relative "easy_code_sign/providers/pkcs11_base"
+require_relative "easy_code_sign/providers/safenet"
+require_relative "easy_code_sign/signable/base"
+require_relative "easy_code_sign/signable/gem_file"
+require_relative "easy_code_sign/signable/zip_file"
+require_relative "easy_code_sign/signable/pdf_file"
+require_relative "easy_code_sign/pdf/timestamp_handler"
+require_relative "easy_code_sign/pdf/appearance_builder"
+require_relative "easy_code_sign/timestamp/request"
+require_relative "easy_code_sign/timestamp/response"
+require_relative "easy_code_sign/timestamp/client"
+require_relative "easy_code_sign/timestamp/verifier"
+require_relative "easy_code_sign/verification/result"
+require_relative "easy_code_sign/verification/trust_store"
+require_relative "easy_code_sign/verification/certificate_chain"
+require_relative "easy_code_sign/verification/signature_checker"
+require_relative "easy_code_sign/deferred_signing_request"
+require_relative "easy_code_sign/signer"
+require_relative "easy_code_sign/verifier"
+
+module EasyCodeSign
+  class << self
+    # Get the current configuration
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure EasyCodeSign
+    # @yield [Configuration] the configuration object
+    # @return [Configuration]
+    def configure
+      yield(configuration)
+      configuration
+    end
+
+    # Reset configuration to defaults
+    # @return [Configuration]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Get a provider instance based on current configuration
+    # @return [Providers::Base] a provider instance
+    def provider
+      @provider ||= build_provider
+    end
+
+    # Reset the cached provider instance
+    # @return [void]
+    def reset_provider!
+      @provider = nil
+    end
+
+    # Sign a file using the configured provider
+    #
+    # @param file_path [String] path to the file to sign
+    # @param pin [String, nil] PIN for the token (uses callback if nil)
+    # @param output_path [String, nil] output path for signed file
+    # @param timestamp [Boolean] whether to add timestamp (default: from config)
+    # @param algorithm [Symbol] signature algorithm (default: :sha256_rsa)
+    # @return [SigningResult] signing result with file path and metadata
+    #
+    # @example Sign a gem
+    #   EasyCodeSign.sign("my_gem-1.0.0.gem", pin: "1234")
+    #
+    # @example Sign with timestamp
+    #   EasyCodeSign.sign("archive.zip", pin: "1234", timestamp: true)
+    #
+    def sign(file_path, pin: nil, output_path: nil, timestamp: nil, algorithm: :sha256_rsa)
+      signer = Signer.new
+      signer.sign(file_path, pin: pin, output_path: output_path, timestamp: timestamp, algorithm: algorithm)
+    end
+
+    # Verify a signed file
+    #
+    # @param file_path [String] path to the signed file
+    # @param check_timestamp [Boolean] whether to verify timestamp (default: true)
+    # @param trust_store [Verification::TrustStore, nil] custom trust store
+    # @return [Verification::Result] verification result
+    #
+    # @example Verify a signed gem
+    #   result = EasyCodeSign.verify("signed.gem")
+    #   puts result.valid? ? "Valid!" : result.errors.join(", ")
+    #
+    def verify(file_path, check_timestamp: true, trust_store: nil)
+      verifier = Verifier.new(trust_store: trust_store)
+      verifier.verify(file_path, check_timestamp: check_timestamp)
+    end
+
+    # Phase 1 of deferred PDF signing.
+    # Prepares a PDF with placeholder signature and returns a DeferredSigningRequest
+    # containing the digest to be signed by an external signer (Fortify, WebCrypto, etc.).
+    #
+    # @param file_path [String] path to the PDF
+    # @param pin [String, nil] PIN for hardware token (needed for certificate retrieval)
+    # @param digest_algorithm [String] "sha256", "sha384", or "sha512"
+    # @param timestamp [Boolean] whether to reserve timestamp space
+    # @return [DeferredSigningRequest]
+    #
+    # @example
+    #   request = EasyCodeSign.prepare_pdf("document.pdf", pin: "1234")
+    #   request.digest_base64 #=> "abc123..."  (send to external signer)
+    #
+    def prepare_pdf(file_path, pin: nil, digest_algorithm: "sha256", timestamp: false, **extra_options)
+      signer = Signer.new
+      signer.prepare_pdf(file_path, pin: pin, digest_algorithm: digest_algorithm,
+                                    timestamp: timestamp, **extra_options)
+    end
+
+    # Phase 2 of deferred PDF signing.
+    # Embeds an externally-produced raw signature into the prepared PDF.
+    #
+    # @param deferred_request [DeferredSigningRequest] from prepare_pdf
+    # @param raw_signature [String] raw signature bytes from external signer
+    # @return [SigningResult]
+    #
+    # @example
+    #   result = EasyCodeSign.finalize_pdf(request, raw_signature)
+    #   result.file_path #=> "document_prepared.pdf"
+    #
+    def finalize_pdf(deferred_request, raw_signature, **options)
+      signer = Signer.new
+      signer.finalize_pdf(deferred_request, raw_signature, **options)
+    end
+
+    # Create a verifier instance for batch operations
+    # @param trust_store [Verification::TrustStore, nil]
+    # @return [Verifier]
+    def verifier(trust_store: nil)
+      Verifier.new(trust_store: trust_store)
+    end
+
+    # List available token slots
+    # @return [Array<Hash>] array of slot information
+    def list_slots
+      provider.list_slots
+    end
+
+    # Create a signer instance for batch operations
+    # @return [Signer]
+    def signer
+      Signer.new
+    end
+
+    # Detect file type and return appropriate signable handler
+    # @param file_path [String] path to file
+    # @return [Signable::Base] signable handler
+    def signable_for(file_path, **options)
+      extension = File.extname(file_path).downcase
+
+      case extension
+      when ".gem"
+        Signable::GemFile.new(file_path, **options)
+      when ".zip", ".jar", ".apk", ".war", ".ear"
+        Signable::ZipFile.new(file_path, **options)
+      when ".pdf"
+        Signable::PdfFile.new(file_path, **options)
+      else
+        raise InvalidFileError, "Unsupported file type: #{extension}"
+      end
+    end
+
+    private
+
+    def build_provider
+      configuration.validate!
+
+      case configuration.provider
+      when :safenet
+        Providers::Safenet.new(configuration)
+      else
+        raise ConfigurationError, "Unknown provider: #{configuration.provider}"
+      end
+    end
+  end
+end

data/plugin/.gitignore

@@ -0,0 +1,21 @@
+# Built extension output
+dist/
+
+# Ruby dependencies
+.bundle/
+vendor/bundle/
+
+# Logs
+*.log
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Editor files
+*.swp
+*.swo
+*~
+
+# Native host packaged binaries
+native_host/dist/

data/plugin/Gemfile

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Opal - Ruby to JavaScript compiler
+gem "opal", "~> 1.8"
+gem "opal-sprockets", "~> 1.0"
+
+# Required for Ruby 3.4+
+gem "base64"
+
+# Build tooling
+gem "rake", "~> 13.0"
+
+# For watching file changes during development
+gem "listen", "~> 3.8"
+
+# Testing - use minitest (native host tests are plain Ruby)
+gem "minitest", "~> 5.0"
+
+group :development do
+  # Code quality
+  gem "rubocop", require: false
+end

data/plugin/Gemfile.lock

@@ -0,0 +1,134 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    base64 (0.3.0)
+    concurrent-ruby (1.3.6)
+    ffi (1.17.3)
+    ffi (1.17.3-aarch64-linux-gnu)
+    ffi (1.17.3-aarch64-linux-musl)
+    ffi (1.17.3-arm-linux-gnu)
+    ffi (1.17.3-arm-linux-musl)
+    ffi (1.17.3-arm64-darwin)
+    ffi (1.17.3-x86-linux-gnu)
+    ffi (1.17.3-x86-linux-musl)
+    ffi (1.17.3-x86_64-darwin)
+    ffi (1.17.3-x86_64-linux-gnu)
+    ffi (1.17.3-x86_64-linux-musl)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    minitest (5.27.0)
+    opal (1.8.2)
+      ast (>= 2.3.0)
+      parser (~> 3.0, >= 3.0.3.2)
+    opal-sprockets (1.0.4)
+      opal (>= 1.0, < 2.0)
+      sprockets (~> 4.0)
+      tilt (>= 1.4)
+    parallel (1.27.0)
+    parser (3.3.10.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.7.0)
+    racc (1.8.1)
+    rack (3.2.4)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    regexp_parser (2.11.3)
+    rubocop (1.82.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    sprockets (4.2.2)
+      concurrent-ruby (~> 1.0)
+      logger
+      rack (>= 2.2.4, < 4)
+    tilt (2.6.1)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  ruby
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  base64
+  listen (~> 3.8)
+  minitest (~> 5.0)
+  opal (~> 1.8)
+  opal-sprockets (~> 1.0)
+  rake (~> 13.0)
+  rubocop
+
+CHECKSUMS
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  ffi (1.17.3) sha256=0e9f39f7bb3934f77ad6feab49662be77e87eedcdeb2a3f5c0234c2938563d4c
+  ffi (1.17.3-aarch64-linux-gnu) sha256=28ad573df26560f0aedd8a90c3371279a0b2bd0b4e834b16a2baa10bd7a97068
+  ffi (1.17.3-aarch64-linux-musl) sha256=020b33b76775b1abacc3b7d86b287cef3251f66d747092deec592c7f5df764b2
+  ffi (1.17.3-arm-linux-gnu) sha256=5bd4cea83b68b5ec0037f99c57d5ce2dd5aa438f35decc5ef68a7d085c785668
+  ffi (1.17.3-arm-linux-musl) sha256=0d7626bb96265f9af78afa33e267d71cfef9d9a8eb8f5525344f8da6c7d76053
+  ffi (1.17.3-arm64-darwin) sha256=0c690555d4cee17a7f07c04d59df39b2fba74ec440b19da1f685c6579bb0717f
+  ffi (1.17.3-x86-linux-gnu) sha256=868a88fcaf5186c3a46b7c7c2b2c34550e1e61a405670ab23f5b6c9971529089
+  ffi (1.17.3-x86-linux-musl) sha256=f0286aa6ef40605cf586e61406c446de34397b85dbb08cc99fdaddaef8343945
+  ffi (1.17.3-x86_64-darwin) sha256=1f211811eb5cfaa25998322cdd92ab104bfbd26d1c4c08471599c511f2c00bb5
+  ffi (1.17.3-x86_64-linux-gnu) sha256=3746b01f677aae7b16dc1acb7cb3cc17b3e35bdae7676a3f568153fb0e2c887f
+  ffi (1.17.3-x86_64-linux-musl) sha256=086b221c3a68320b7564066f46fed23449a44f7a1935f1fe5a245bd89d9aea56
+  json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
+  language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  listen (3.9.0) sha256=db9e4424e0e5834480385197c139cb6b0ae0ef28cc13310cfd1ca78377d59c67
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  minitest (5.27.0) sha256=2d3b17f8a36fe7801c1adcffdbc38233b938eb0b4966e97a6739055a45fa77d5
+  opal (1.8.2) sha256=cedde4e1691d7cdaaf0aadac99fbf1fdb5bb90fe2dcc60e968f984601bd5d4e3
+  opal-sprockets (1.0.4) sha256=ba247b54c1cea23a4858f70a8851322c170436ed904b2c9c9d76d0b07e25ccfc
+  parallel (1.27.0) sha256=4ac151e1806b755fb4e2dc2332cbf0e54f2e24ba821ff2d3dcf86bf6dc4ae130
+  parser (3.3.10.0) sha256=ce3587fa5cc55a88c4ba5b2b37621b3329aadf5728f9eafa36bbd121462aabd6
+  prism (1.7.0) sha256=10062f734bf7985c8424c44fac382ac04a58124ea3d220ec3ba9fe4f2da65103
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rack (3.2.4) sha256=5d74b6f75082a643f43c1e76b419c40f0e5527fcfee1e669ac1e6b73c0ccb6f6
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  rb-fsevent (0.11.2) sha256=43900b972e7301d6570f64b850a5aa67833ee7d87b458ee92805d56b7318aefe
+  rb-inotify (0.11.1) sha256=a0a700441239b0ff18eb65e3866236cd78613d6b9f78fea1f9ac47a85e47be6e
+  regexp_parser (2.11.3) sha256=ca13f381a173b7a93450e53459075c9b76a10433caadcb2f1180f2c741fc55a4
+  rubocop (1.82.1) sha256=09f1a6a654a960eda767aebea33e47603080f8e9c9a3f019bf9b94c9cab5e273
+  rubocop-ast (1.49.0) sha256=49c3676d3123a0923d333e20c6c2dbaaae2d2287b475273fddee0c61da9f71fd
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  sprockets (4.2.2) sha256=761e5a49f1c288704763f73139763564c845a8f856d52fba013458f8af1b59b1
+  tilt (2.6.1) sha256=35a99bba2adf7c1e362f5b48f9b581cce4edfba98117e34696dde6d308d84770
+  unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
+  unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
+
+BUNDLED WITH
+  4.0.3

data/plugin/README.md

@@ -0,0 +1,248 @@
+# EasySign Browser Plugin
+
+Browser extension for signing PDF documents using hardware security tokens (HSM/smart cards).
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Web App (Rails, etc.)                              │
+│  window.EasySign.sign(pdfBlob, options)            │
+└─────────────────┬───────────────────────────────────┘
+                  │ postMessage
+┌─────────────────▼───────────────────────────────────┐
+│  Content Script (Opal.rb → JS)                      │
+│  Bridges page ↔ extension, validates origins        │
+└─────────────────┬───────────────────────────────────┘
+                  │ chrome.runtime.sendMessage
+┌─────────────────▼───────────────────────────────────┐
+│  Background Service Worker (Opal.rb → JS)           │
+│  Opens PIN popup, manages native connection         │
+└─────────────────┬───────────────────────────────────┘
+                  │ Native Messaging (JSON over stdio)
+┌─────────────────▼───────────────────────────────────┐
+│  Native Host (Ruby → Packaged Binary)               │
+│  Uses EasyCodeSign gem for actual signing           │
+│  Accesses PKCS#11 hardware token                    │
+└─────────────────────────────────────────────────────┘
+```
+
+## Development Setup
+
+### Prerequisites
+
+- Ruby 3.2+
+- Node.js (optional, for alternative build tools)
+- Chrome or Firefox browser
+
+### Install Dependencies
+
+```bash
+cd plugin
+bundle install
+```
+
+### Build Extension
+
+```bash
+# Build all components
+bundle exec rake build
+
+# Watch for changes during development
+bundle exec rake watch
+
+# Clean build artifacts
+bundle exec rake clean
+```
+
+### Load Extension in Browser
+
+**Chrome:**
+1. Open `chrome://extensions`
+2. Enable "Developer mode"
+3. Click "Load unpacked"
+4. Select the `plugin/dist` directory
+
+**Firefox:**
+1. Open `about:debugging`
+2. Click "This Firefox"
+3. Click "Load Temporary Add-on"
+4. Select `plugin/dist/manifest.json`
+
+### Install Native Host (Development)
+
+```bash
+# For Chrome
+./native_host/install/install_chrome.sh
+
+# For Firefox
+./native_host/install/install_firefox.sh
+```
+
+## Web App Integration
+
+### Check Availability
+
+```javascript
+window.EasySign.isAvailable()
+  .then(result => {
+    console.log('Extension installed:', result.available);
+    console.log('Token connected:', result.tokenPresent);
+    console.log('Available slots:', result.slots);
+  })
+  .catch(err => {
+    console.error('EasySign not available:', err);
+  });
+```
+
+### Sign a PDF
+
+```javascript
+// Get PDF as Blob (from file input, fetch, etc.)
+const pdfBlob = await fetch('/document.pdf').then(r => r.blob());
+
+// Sign the PDF
+window.EasySign.sign(pdfBlob, {
+  reason: 'Approved',
+  location: 'New York',
+  visibleSignature: true,
+  signaturePosition: 'bottom_right',
+  timestamp: true
+})
+.then(result => {
+  console.log('Signed by:', result.signer_name);
+  console.log('Signed at:', result.signed_at);
+
+  // Download signed PDF
+  const url = URL.createObjectURL(result.blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = 'signed_document.pdf';
+  a.click();
+
+  // Or upload to server
+  const formData = new FormData();
+  formData.append('signed_pdf', result.blob, 'signed.pdf');
+  fetch('/upload', { method: 'POST', body: formData });
+})
+.catch(err => {
+  console.error('Signing failed:', err.message, err.code);
+});
+```
+
+### Verify a Signed PDF
+
+```javascript
+window.EasySign.verify(signedPdfBlob)
+  .then(result => {
+    if (result.payload.valid) {
+      console.log('Signature is valid!');
+      console.log('Signer:', result.payload.signerName);
+    } else {
+      console.log('Signature invalid:', result.payload.errors);
+    }
+  });
+```
+
+## API Reference
+
+### `window.EasySign.isAvailable()`
+
+Check if extension is installed and token is connected.
+
+**Returns:** `Promise<Object>`
+- `available` (boolean): Extension is installed and native host is connected
+- `tokenPresent` (boolean): Hardware token is connected
+- `slots` (Array): List of available token slots
+
+### `window.EasySign.sign(pdfBlob, options)`
+
+Sign a PDF document. Opens PIN entry popup.
+
+**Parameters:**
+- `pdfBlob` (Blob): The PDF file to sign
+- `options` (Object):
+  - `reason` (string): Reason for signing
+  - `location` (string): Location of signing
+  - `visibleSignature` (boolean): Add visible signature annotation
+  - `signaturePosition` (string): Position (`top_left`, `top_right`, `bottom_left`, `bottom_right`)
+  - `signaturePage` (number): Page number for signature (default: 1)
+  - `timestamp` (boolean): Add RFC 3161 timestamp
+
+**Returns:** `Promise<Object>`
+- `blob` (Blob): Signed PDF file
+- `signer_name` (string): Name from signing certificate
+- `signed_at` (string): ISO 8601 timestamp
+- `timestamped` (boolean): Whether timestamp was added
+
+### `window.EasySign.verify(pdfBlob, options)`
+
+Verify a signed PDF document.
+
+**Parameters:**
+- `pdfBlob` (Blob): The signed PDF file
+- `options` (Object):
+  - `checkTimestamp` (boolean): Verify timestamp (default: true)
+
+**Returns:** `Promise<Object>` with verification details
+
+## Error Handling
+
+```javascript
+window.EasySign.sign(pdfBlob, options)
+  .catch(err => {
+    switch (err.code) {
+      case 'TOKEN_NOT_FOUND':
+        alert('Please connect your hardware token');
+        break;
+      case 'PIN_INCORRECT':
+        alert('Incorrect PIN');
+        break;
+      case 'TOKEN_LOCKED':
+        alert('Token is locked. Contact administrator.');
+        break;
+      case 'CANCELLED':
+        // User cancelled - no action needed
+        break;
+      default:
+        alert('Signing failed: ' + err.message);
+    }
+  });
+```
+
+## Building for Production
+
+### Package Native Host
+
+The native host can be packaged as a self-contained executable:
+
+```bash
+cd native_host
+bundle exec rake build:package
+```
+
+This creates platform-specific binaries in `native_host/dist/`.
+
+### Create Installer
+
+```bash
+# macOS
+./create_installer_macos.sh
+
+# Windows
+./create_installer_windows.bat
+
+# Linux
+./create_installer_linux.sh
+```
+
+## Security
+
+- PIN is entered only in browser popup, never on web pages
+- PIN is passed directly to native host, never stored
+- Origin validation restricts which websites can use the API
+- All signing happens in the native host, private keys never leave the token
+
+## License
+
+MIT License - See LICENSE file