Railsのbuild_associationの挙動がよくわからなかったので調べてみた

こんにちは!kossyです!




今回は、Railsのbuild_associationの挙動がよくわからなかったので調べてみました。



Ruby 2.7.6
Rails 6.0.5.1




前提として、userがreservation(予約)を1つ持つという関連が組まれていることとします。この場合、userクラスのインスタンスメソッドとして自動的にbuild_reservationメソッドが定義されます。


ソースコードを見る

build_associationを定義しているのは singular_association.rb でした。

github.com

    # Defines the (build|create)_association methods for belongs_to or has_one association
    def self.define_constructors(mixin, name)
      mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
        def build_#{name}(*args, &block)
          association(:#{name}).build(*args, &block)
        end
        def create_#{name}(*args, &block)
          association(:#{name}).create(*args, &block)
        end
        def create_#{name}!(*args, &block)
          association(:#{name}).create!(*args, &block)
        end
      CODE
    end

class_evalで動的にメソッド定義を行ってますね。

では実際に呼び出される時はどのような挙動になるのでしょうか。試しにuserクラスに適当なインスタンスメソッドを定義して、binding.pryでdebugしてみましょう。

class User
  has_one :reservation

  def test_method
    binding.pry

    build_reservation
  end
end

この状態でコンソールを開いて、userインスタンスに対してtest_methodを実行します。するとREPLが起動するので、stepメソッドでメソッド内部に移動すると、

lib/active_record/associations/builder/singular_association.rb:29

    28: def build_#{name}(*args, &block)
 => 29:   association(:#{name}).build(*args, &block)
    30: end

動的にメソッド定義を行っている場所に辿り着きました。buildメソッドでインスタンス定義を行なっていると思われるので、処理を見てみます。

lib/active_record/associations/singular_association.rb:21

    20: def build(attributes = {}, &block)
 => 21:   record = build_record(attributes, &block)
    22:   set_new_record(record)
    23:   record
    24: end

build_recordは実際に関連先のインスタンスを生成する処理かと思います。set_new_recordの処理も見てみます。

lib/active_record/associations/has_one_association.rb:75

    74: def set_new_record(record)
 => 75:   replace(record, false)
    76: end

replaceメソッドの中身はこちら。

    42: def replace(record, save = true)
 => 43:   raise_on_type_mismatch!(record) if record
    44:
    45:   return target unless load_target || record
    46:
    47:   assigning_another_record = target != record
    48:   if assigning_another_record || record.has_changes_to_save?
    49:     save &&= owner.persisted?
    50:
    51:     transaction_if(save) do
    52:       remove_target!(options[:dependent]) if target && !target.destroyed? && assigning_another_record
    53:
    54:       if record
    55:         set_owner_attributes(record)
    56:         set_inverse_instance(record)
    57:
    58:         if save && !record.save
    59:           nullify_owner_attributes(record)
    60:           set_owner_attributes(target) if target
    61:           raise RecordNotSaved, "Failed to save the new associated #{reflection.name}."
    62:         end
    63:       end
    64:     end
    65:   end
    66:
    67:   self.target = record
    68: end

いくつかのバリデーションを行った後、target(関連先のレコード)が既に存在していて、関連先のレコードが削除されておらず、新しい関連先のレコードがある場合、

remove_target!メソッドを呼んでいます。メソッド名から察するに、既に存在している関連先のレコードを削除するメソッドだと思いますが、処理を追ってみます。

    78: def remove_target!(method)
 => 79:   case method
    80:   when :delete
    81:     target.delete
    82:   when :destroy
    83:     target.destroyed_by_association = reflection
    84:     target.destroy
    85:   else
    86:     nullify_owner_attributes(target)
    87:     remove_inverse_instance(target)
    88:
    89:     if target.persisted? && owner.persisted? && !target.save
    90:       set_owner_attributes(target)
    91:       raise RecordNotSaved, "Failed to remove the existing associated #{reflection.name}. " \
    92:                             "The record failed to save after its foreign key was set to nil."
    93:     end
    94:   end
    95: end

私の実行環境だと引数のmethodは:destroyでした。

82行目で関連先のレコードに組まれたAssociationのレコードを削除し、83行目で関連先のレコードを削除しています。


まとめ

build_associationメソッドは、既に関連先のレコード(今回だとreservation)が存在する場合は、そのレコードを削除して新たなインスタンスを生成していました。更新時にbuild_associationを呼ぶ場合は挙動を頭に入れた上で実行した方がよさそうですね。(思わぬバグを誘発するかも)

Railsでddtraceを使う際に、Datadogのログに残すリクエストをフィルタリングしたい

こんにちは!kossyです!




さて、今回はDatadog の Ruby 用トレースクライアントであるddtrace gemで、Datadogのトレース対象とするリクエストをフィルタリングする方法について、ブログに残してみたいと思います。




環境
Rails 6.1.4
Ruby 2.7.6
ddtrace 1.4.1




実装方法

結論、以下のコードをconfig/initializers/datadog.rbに記載すればOKです。

Datadog::Pipeline.before_flush(
  Datadog::Pipeline::SpanFilter.new { |span| span.resource =~ /フィルタリングしたいControllerクラス/ },
)

例えばサーバーヘルスチェック用のAPIをトレース対象から除外したい場合は、

Datadog::Pipeline.before_flush(
  Datadog::Pipeline::SpanFilter.new { |span| span.resource =~ /HealthcheckController/ },
)

のように記載すればOKです。


複数のAPIをフィルタリングしたい場合

複数のクラスをトレース対象から除外したい場合は、「|」で繋いで記載すればOKです。

Datadog::Pipeline.before_flush(
  Datadog::Pipeline::SpanFilter.new { |span| span.resource =~ /HealthcheckController|PingController/ },
)

意図通り動くか、正規表現部分のチェックをしてみましょう。

# マッチした場合は0が返る
"HealthcheckController" =~ /PingController|HealthcheckController/
=> 0

# マッチしない場合はnilが返る
"HealthcheckController" =~ /PingController/
=> nil

"HealthcheckController" =~ /HealthcheckController/
=> 0

大いに参考にさせていただいたサイト

docs.datadoghq.com
s3.amazonaws.com

Dockerを使った開発時にpryやirbの履歴を保存したい

こんにちは!kossyです!

今回は開発環境にDockerを使ってRailsアプリを開発する際に、pryやirbの履歴を保存する方法についてブログに残してみたいと思います。




環境
Ruby 2.6.9
Rails 6.0.3
docker-compose version 1.27.0



docker-compose.ymlの編集

まずはdocker-compose.ymlを編集します。

# docker-compose.yml

volumes:
  - history:/usr/local/history

environment:
  IRB_HISTORY_PATH: /usr/local/history/.irb_history
  PRY_HISTORY_PATH: /usr/local/history/.pry_history

environmentにirbもpryも指定していますが、「普段使うデバッガだけ記載する」でもOKです。(複数人で開発する場合はいろんなデバッガを使われる可能性があるので複数記載するでもOK)

.irbrcの作成

irbをメインのデバッガとして使いたい場合は、アプリケーションのルートディレクトリ直下に.irbrcを作成します。

# .irbrc

path = ENV['IRB_HISTORY_PATH']
if path
  IRB.conf[:HISTORY_FILE] = path
end

ENV定数からirbの履歴を保存するパスを取得し、もしパスが設定されていれば、IRBクラスのconfigにパスを指定しています。

.pryrcの作成

pryをメインのデバッガとして使いたい場合は、アプリケーションのルートディレクトリ直下に.pryrcを作成します。

# .pryrc

path = ENV['PRY_HISTORY_PATH']
if path
  Pry.config.history_file = path
end

こちらも.irbrcとやっていることはほとんど一緒で、参照するパスと扱うクラスが違うだけですね。

IRB.confのソースコードを読んでみる

せっかくなので、IRBクラスのソースコードを読んでみましょうか。

docker-composeコマンドでコンテナを立てて rails c でコンソールを立ち上げて検証してみます。

# railsという名前のコンテナを立てる
docker-compose run --rm rails bundle exec rails c
IRB.method(:conf).source_location
=> ["/usr/local/lib/ruby/2.6.0/irb.rb", 350]

source_locationを実行したところ、irb.rbの350行目にconfメソッドが生えているようです。

github.com

コメント部分の記述が詳しかったので、こちらを読んでみます。

# === History
#
# By default, irb will store the last 1000 commands you used in
# <code>IRB.conf[:HISTORY_FILE]</code> (<code>~/.irb_history</code> by default).
#
# If you want to disable history, add the following to your +.irbrc+:
#
#     IRB.conf[:SAVE_HISTORY] = nil
#

デフォルトでは1000コマンドまで保存できて、IRB.conf[:HISTORY_FILE]に保存されるとのこと。(デフォルトは~/.irb_history)

また、履歴の保存をしたくない場合は、.irbrcに IRB.conf[:SAVE_HISTORY] = nil と記載すればOKとのこと。

irb.rbは約900行ほどのファイルなのですが、1/3はコメントが記載されてました。何ができるか知りたい場合は公式ドキュメントに加えて、コメント部分も読んでみるとよさそうです。


Pry.configのソースコードを読んでみる

次はPry.configのソースコードを確認してみましょうか。

Pry.config.method(:history_file).source_location
=> ["/bundle/ruby/2.6.0/gems/pry-0.13.1/lib/pry/config/attributable.rb", 13]

実際にhistory_fileの記載があったのはこちらのファイルでした。

github.com

# @return [String]
attribute :history_file

# 省略

history_file: Pry::History.default_file,

Pry::History.default_fileの定義はこちら。

    def self.default_file
      history_file =
        if (xdg_home = Pry::Env['XDG_DATA_HOME'])
          # See XDG Base Directory Specification at
          # https://standards.freedesktop.org/basedir-spec/basedir-spec-0.8.html
          xdg_home + '/pry/pry_history'
        elsif File.exist?(File.expand_path('~/.pry_history'))
          '~/.pry_history'
        else
          '~/.local/share/pry/pry_history'
        end
      File.expand_path(history_file)
    end

ざっくり言うと基本的にはpry_historyというファイルに履歴が格納されていくコードになっていました。

もう一度.pryrcのコードを見てみます。

# .pryrc

path = ENV['PRY_HISTORY_PATH']
if path
  Pry.config.history_file = path
end

history_fileがattribute として定義されていて書き込みが可能になっているので、default_fileメソッドで定義されたファイルパスを.pryrcで上書きしていることになりますね。

おわりに

dockerの場合だとvolumeの設定をしないとコマンドの実行履歴が揮発してしまうので、一手間加えないとコマンドの実行履歴が保存されないんですね。(コンテナの中で全て完結するんだからそれはそう)

IRBやPryのソースコードを読むことがほとんどなかったので、いい勉強になりました。

大いに参考にさせていただいた記事

素晴らしい記事の執筆、誠にありがとうございます。

r7kamura.com

複数のフラグを1つのカラムで管理できるGem「flag_shih_tzu」の使い方とユースケース

こんにちは!kossyです!

今回は、複数のフラグを1つのカラムで管理できるGem「flag_shih_tzu」の使い方とユースケースについて、

備忘録としてブログに残してみたいと思います。

環境

flag_shih_tzu とは

Booleanを含んだ配列を、一つの整数として格納できるActiveRecordのエクステンションです。MySQL, PostgreSQLSQLite等、DBを問わず動作します。

使い方は簡単で、has_flagメソッドに、管理したいフラグ名を数値と共に渡すだけで実現できます。

ちなみに、「shih_tzu」の由来は犬の品種の一つである、「シーズー」から命名したらしいです。

使い方

まずはApplicationRecordを継承したモデルに FlagShihTzu モジュールをincludeします。

class Admin < ActiveRecord::Base
  include FlagShihTzu
end

次に、フラグを格納するカラムを作成するマイグレーションファイルを用意します。

  def change
    add_column :admins, :function_flags, :integer, default: 0, null: false, comment: '機能利用フラグ'
  end

次に、has_flagメソッドに数値と管理したいフラグ名をシンボルで渡します。

columnにカラム名を渡せば、渡したカラムでフラグを管理することができます。

class Admin < ActiveRecord::Base
  include FlagShihTzu

  has_flag(
    1 => :use_announcement,
    2 => :use_term_of_service_version,
    3 => :use_privacy_policy,
    :column => 'function_flags'
  )
end

これで準備完了です。

各種メソッド

上記の定義を行った場合、以下のインスタンスメソッドが定義されます。

Admin#all_features # [:use_announcement, :use_term_of_service_version, :use_privacy_policy]
Admin#selected_features
Admin#select_all_features
Admin#unselect_all_features
Admin#selected_features=

Admin#use_announcement
Admin#use_announcement?
Admin#use_announcement=
Admin#not_use_announcement
Admin#not_use_announcement?
Admin#not_use_announcement=
Admin#use_announcement_changed?
Admin#has_use_announcement?

Admin#use_term_of_service_version
Admin#use_term_of_service_version?
Admin#use_term_of_service_version=
Admin#not_use_term_of_service_version
Admin#not_use_term_of_service_version?
Admin#not_use_term_of_service_version=
Admin#use_term_of_service_version_changed?
Admin#has_use_term_of_service_version?

Admin#use_privacy_policy
Admin#use_privacy_policy?
Admin#use_privacy_policy=
Admin#not_use_privacy_policy
Admin#not_use_privacy_policy?
Admin#not_use_privacy_policy=
Admin#use_privacy_policy_changed?
Admin#use_privacy_policy?

また、以下のクラスメソッドも定義されます。

Admin.use_announcement         # :conditions => "(admins.function_flags in (1,3,5,7))"
Admin.not_use_announcement     # :conditions => "(admins.function_flags not in (1,3,5,7))"
Admin.use_term_of_service_version           # :conditions => "(admins.function_flags in (2,3,6,7))"
Admin.not_use_term_of_service_version       # :conditions => "(admins.function_flags not in (2,3,6,7))"
Admin.use_privacy_policy      # :conditions => "(admins.function_flags in (4,5,6,7))"
Admin.not_use_privacy_policy  # :conditions => "(admins.function_flags not in (4,5,6,7))"

他にも、callbackメソッドやフラグをupdateするメソッドも定義されますので、

より詳しく知りたい方はReadMeをご覧ください。

github.com

ユースケース

複数のフラグを1つのカラムで管理したくなる時がいつか?という観点で考えてみました。

1. 機能利用フラグを管理したい時

例えば管理者権限があるとして、管理者の中でも権限を弱くしたい、といったビジネス要求は往々にしてあります。

そういった際に機能ごとに使用権限を管理することになることが多いと思いますが、機能ごとにフラグのカラムを用意していくと、

機能が追加されるたびにフラグのカラムを追加することになり、管理コストが増します。

そういったケースで、このGemが役に立つのではないでしょうか。

他にもあると思うので随時更新します。

おわりに

実際に開発中のプロダクトでも、際限なく機能利用フラグが増えていっているので、すぐにでも導入したいと思いました。

既にたくさんのフラグが生えているテーブルからの移行については知見がまだないので、そういったケースでどう移行を実現するのか?は需要がありそうな気がしています。

外来診療管理システムのデータモデルを考えてみた

こんにちは!kossyです。

今回は、外来診療管理システムのデータモデルの例が掲載されている書籍がありまして、そちらの内容を自分なりに咀嚼してRDBMSに落とし込んでみたので、備忘録としてブログに残してみたいと思います。

WIPですので随時更新します。

登場人物

  • 患者
  • 医師
  • システム管理者

ユーザーストーリー

患者

DB設計

テーブルは全てid、created_at、updated_atカラムが定義されているものとします。

patients

患者テーブル

name type options description
number string null: false 患者番号
born_on date null: false 生年月日
sex integer null: false 性別
job_id bigint foreign_key: true, index: true, optional: true 職業(外部キー)

jobs

職業テーブル

name type options description
name string null: false, index: true 職業名

insurance_cards

保険証テーブル

name type options description
symbol string null: false 記号
number string null: false 番号
delivery_on date null: false 交付日
acquisition_on date 資格取得日
relationship integer null: false 続柄
expires_on date 有効期限
insurer_number string null: false, 6桁or8桁 保険者番号

備考

  • 被用者保険か国民健康保険かで記載してある項目にバラつきがあり、必ずnullになることもあるが、許容する

departments

診療科テーブル

name type options description
name string null: false 診療科名

doctors

医師テーブル

name type options description
last_name string null: false
first_name string null: false
last_name_kana string null: false 姓(カナ)
first_name_kana string null: false 名(カナ)

doctor_departments

医師と診療科の中間テーブル

name type options description
doctor_id bigint null: false, index: true, foreign_key: true 外部キー
department_id bigint null: false, index: true, foreign_key: true 外部キー

consultations

受診履歴テーブル

name type options description
patient_id bigint null: false, index: true, foreign_key: true 外部キー
doctor_id bigint null: false, index: true, foreign_key: true 外部キー
visited_on date null: false 受診日
self_pay_ratio integer null: false 自己負担割合
chief_complaint text null: false 主訴
findings text null: false 所見
visit_category integer null: false 受診区分。初診または再診
status integer null: false 受診状況

medical_histories

既往歴テーブル

name type options description
patient_id bigint null: false, index: true, foreign_key: true 外部キー
age integer null: false 罹患時年齢
name string 傷病名
descriptions text 摘要

consultation_schedules

診察日程テーブル

name type options description
department_id bigint null: false, index: true, foreign_key: true 外部キー
schedule_on date null: false, index: true 診察日
time_category integer null: false 午前/午後区分
patient_count integer null: false, default: 0 診察患者数
max_wait_patient_count integer null: false, default: 0 最大待ち患者数

doctor_schedules

医師日程テーブル

name type options description
doctor_id bigint null: false, index: true, foreign_key: true 外部キー
consultation_schedule_id bigint null: false, index: true, foreign_key: true 外部キー
patient_count integer null: false, default: 0 診察患者数

business_times

診察受付日時テーブル

name type options description
am_start_at datetime null: false 午前診察開始日時
am_start_at datetime null: false 午前診察終了日時
pm_start_at datetime null: false 午後診察開始日時
pm_start_at datetime null: false 午後診察終了日時

sy_masters

傷病マスターテーブル

name type options description
code string null: false, index: true 傷病コード
name string null: false, index: true 傷病名

consultation_sy_details

傷病明細テーブル

name type options description
code string null: false, index: true 傷病コード
consultation_id bigint null: false, index: true, foreign_key: true 外部キー
outcome_category integer null: false 転帰区分
is_main_disease boolean null: false, default: false 主傷病フラグ

treatment_masters

処置マスターテーブル

name type options description
code string null: false 処置コード
name string null: false 処置名
category integer null: false 処置区分(処置/注射/点滴)

treatment_details

処置明細テーブル

name type options description
code string null: false 処置コード
consultation_id bigint null: false, index: true, foreign_key: true 外部キー
descriptions text null: false 摘要

medicine_masters

薬品マスターテーブル

name type options description
code string null: false 薬品コード
name string null: false 薬品名
unit string null: false 単位

consultation_medicine_details

投薬明細テーブル

name type options description
code string null: false 薬品コード
dosing string null: false 服用方法
per_time integer null: false 1回あたり服用量
doses integer null: false 服用回数
way string null: false 投薬方法

Time-based One-Time Passwordの仕組みを提供するGem「rotp」をサクッと試して内部実装を把握する

こんにちは!kossyです!



今回はTime-based One-Time Passwordの仕組みを提供するGem「rotp」をサクッと試して内部実装を把握してみたので、ブログに残してみたいと思います。




環境
Ruby 2.6.6
Rails 6.0.3
MacOS catalina
rotp 6.2.0



まずはコンソールでサクッと試す

github.com

何はともあれGemfileの編集とbundle install。

#  Gemfile

gem 'rotp'
your_app $ bundle

インストールが終了したらReadMeを見ながらコンソールで試してみます。

$ totp = ROTP::TOTP.new("kossywebengineer", issuer: "Test Service")

$ totp.now
=> 388204

$ totp.verify('388204')
=> 1622295690

# 30秒後に再度実行

$ totp.verify('388204')
=> nil

# 前回実行時から6桁の認証コードが変わっている

$ totp.now
=> 197355

30秒で認証コードが更新されていることがわかります。
verifyメソッドを実行してnilが返った場合は、ワンタイムパスワードが間違っていて認証に失敗したことを表していると思われます。

ちなみにQRコードを生成したい場合は、provisioning_uriメソッドを使います。

$ uri = totp.provisioning_uri('kossywebengineer@example.com')
=> "otpauth://totp/Test%20Service:kossywebengineer%40example.com?secret=kossy-web-engineer&issuer=Test%20Service

このURIQRコード生成サイトでQRコード化します。

qr.quel.jp

生成したQRコードスマホの GoogleAuthenticator 等のアプリで読み取ります。

play.google.com

GoogleAuthenticatorに6桁の認証コードが表示されますので、そのコードをvefiryメソッドに渡してみます。

$ totp.verify('651353')
=> 1622295720

認証に成功しました。

サクッと実行して挙動を確認してみましたが、rotpでは認証の部分のみの実装のため、もしWebアプリ内で2要素認証を組み込むとなると、

QRコードの生成」
「2要素認証を有効にしているかどうか」
「secret_keyの管理(newの引数に渡す認証keyです)」
「そのsecret_keyは有効になっているものかどうか」

等を管理する必要があります。上記(QRコードの生成は別ですが)をよしなに行ってくれているのが、devise_two_factorというGemになります。

github.com


rotpの内部実装を追ってみる

ここからはrotpの内部実装をソースコードを実行しながら追ってみたいと思います。

ROTP::TOTP.new

initializeメソッドから見ていきます。

module ROTP
  DEFAULT_INTERVAL = 30
  class TOTP < OTP
    attr_reader :interval, :issuer

    # @option options [Integer] interval (30) the time interval in seconds for OTP
    #     This defaults to 30 which is standard.
    def initialize(s, options = {})
      @interval = options[:interval] || DEFAULT_INTERVAL
      @issuer = options[:issuer]
      super
    end

  # 省略
end

引数で渡されたintervalとissuerをインスタンス変数として定義し、superクラス(OTPクラス)のinitializeを呼び出す実装になっていました。

コンソールで試してみます。

$ totp = ROTP::TOTP.new("kossywebengineer", interval: 15, issuer: "Test Service")
=> #<ROTP::TOTP:0x000056128fa78698
 @digest="sha1",
 @digits=6,
 @interval=15,
 @issuer="Test Service",
 @secret="kossy-web-engineer">

$ totp.now
=> 086478

# 15秒後に再度実行。認証コードが変わっている

$ totp.now
=> 800896

インターバルを15秒に設定したので、15秒で認証コードが更新されています。

OTPクラスのinitializeメソッドも見てみましょう。

module ROTP
  class OTP
    attr_reader :secret, :digits, :digest
    DEFAULT_DIGITS = 6

    # @param [String] secret in the form of base32
    # @option options digits [Integer] (6)
    #     Number of integers in the OTP.
    #     Google Authenticate only supports 6 currently
    # @option options digest [String] (sha1)
    #     Digest used in the HMAC.
    #     Google Authenticate only supports 'sha1' currently
    # @returns [OTP] OTP instantiation
    def initialize(s, options = {})
      @digits = options[:digits] || DEFAULT_DIGITS
      @digest = options[:digest] || 'sha1'
      @secret = s
    end
end

デフォルトのdigits(認証コードの桁数)は「6」で、ハッシュ関数は「sha1」となっています。

こちらもコンソールで試してみましょう。

$ totp = ROTP::TOTP.new("kossywebengineer", digits: 8, issuer: "Test Service")
=>  #<ROTP::TOTP:0x000056128a41b228
 @digest="sha1",
 @digits=8,
 @interval=30,
 @issuer="Test Service",
 @secret="kossywebengineer">

$ totp.now
=> "95928414"

$ totp = ROTP::TOTP.new("kossywebengineer", digest: 'md5', issuer: "Test Service")
=> #<ROTP::TOTP:0x000056128d676b78
 @digest="md5",
 @digits=6,
 @interval=30,
 @issuer="Test Service",
 @secret="kossywebengineer">

# サポートされていないdigestを指定するとnow実行時に例外が上がる
$ ROTP::TOTP.new("kossywebengineer", digest: 'sha0', issuer: "Test Service").now
=> RuntimeError: Unsupported digest algorithm (sha0).: first num too large

$ ROTP::TOTP.new("kossywebengineer", digest: 'sha128', issuer: "Test Service").now
=> RuntimeError: Unsupported digest algorithm (sha128).: first num too large

認証アプリにGoogleAuthenticatorを用いた場合、サポートしている桁数が6桁なので、8桁のdigitsには対応していないので注意が必要とのこと。(2021年5月時点)

同様にdigestも「sha1」のみのサポートとのこと。

残りの処理はsecret_keyのインスタンス変数化処理でした。

initializeメソッドも一通り把握できたので、次はnowメソッドを見てみます。

ROTP::TOTP#now

# Generate the current time OTP
# @return [Integer] the OTP as an integer
def now
  generate_otp(timecode(Time.now))
end

# generate_otpメソッドはROTP::OTPクラスに定義されています。

# @param [Integer] input the number used seed the HMAC
# @option padded [Boolean] (false) Output the otp as a 0 padded string
# Usually either the counter, or the computed integer
# based on the Unix timestamp
def generate_otp(input)
  hmac = OpenSSL::HMAC.digest(
    OpenSSL::Digest.new(digest),
    byte_secret,
    int_to_bytestring(input)
  )

  offset = hmac[-1].ord & 0xf
  code = (hmac[offset].ord & 0x7f) << 24 |
          (hmac[offset + 1].ord & 0xff) << 16 |
          (hmac[offset + 2].ord & 0xff) << 8 |
          (hmac[offset + 3].ord & 0xff)
  (code % 10**digits).to_s.rjust(digits, '0')
end

generate_otpに渡しているtimecodeメソッドを見てみます。

def timecode(time)
  timeint(time) / interval # intervalはinitialize時にセットされた値です。デフォルトはintで「30」
end

# Ensure UTC int
def timeint(time)
  return time.to_i unless time.class == Time

  time.utc.to_i
end

引数がTimeクラスの値でなければ引数をto_iしたものを返却して、そうでない場合は.utc.to_iした値を返却していました。

返却された値を、initialize時に設定したintervalの値で割った値を返却するメソッドでした。

generate_otpの処理は、引数の数値とdigits、secret_keyをBase32でdecodeした値を元に、ワンタイムパスワードを生成しています。このワンタイムパスワードがnowメソッドの返り値となります。

次にverifyメソッドを見てみます。

ROTP::TOTP#verify

# Verifies the OTP passed in against the current time OTP
# and adjacent intervals up to +drift+.  Excludes OTPs
# from `after` and earlier.  Returns time value of
# matching OTP code for use in subsequent call.
# @param otp [String] the one time password to verify
# @param drift_behind [Integer] how many seconds to look back
# @param drift_ahead [Integer] how many seconds to look ahead
# @param after [Integer] prevent token reuse, last login timestamp
# @param at [Time] time at which to generate and verify a particular
#   otp. default Time.now
# @return [Integer, nil] the last successful timestamp
#   interval
def verify(otp, drift_ahead: 0, drift_behind: 0, after: nil, at: Time.now)
  timecodes = get_timecodes(at, drift_behind, drift_ahead)

  timecodes = timecodes.select { |t| t > timecode(after) } if after

  result = nil
  timecodes.each do |t|
    result = t * interval if super(otp, generate_otp(t))
  end
  result
end

コメントアウト部分を訳してみます。

渡された OTP を、現在時刻の OTP および +drift+ までの隣接する間隔に対して検証します。 「後」以前の OTP を除外します。
後続の呼び出しで使用するために、一致する OTP コードの時間値を返します。

@param otp [String] 検証するワンタイムパスワード
@param drift_behind [Integer] 遡って何秒か
@param drift_ahead [Integer] 先読みする秒数
@param after [Integer] は、トークンの再利用、最終ログインのタイムスタンプを防止します
@param at [Time] 特定の

driftは認証コードが有効な期間を設定できるものです。例えばSMSで認証コードを伝える場合、デフォルトの30秒のままだと受け取ってからすぐに認証期限が切れてしまいますが、
driftの設定を長めに設定することで、この問題を回避することができます。

Google翻訳なので一部日本語がおかしいところもありますが、概ね内容は理解できました。

まずはget_timecodesメソッドから読んでみます。

# Get back an array of timecodes for a period
def get_timecodes(at, drift_behind, drift_ahead)
  now = timeint(at)
  timecode_start = timecode(now - drift_behind)
  timecode_end = timecode(now + drift_ahead)
  (timecode_start..timecode_end).step(1).to_a
end

先ほど読んだtimeintメソッドとtimecodeメソッドを使いながら、引数のdrift値を使ってRangeオブジェクトから配列を生成して返却するメソッドになっています。

返り値は以下のような値になります。

=> [54078254, 54078255, 54078256, 54078257, 54078258, ...]

このtimecodesを引数のafterが渡されていれば、afterで指定された秒数で計算したtimecodeよりも数値が大きいものをselectして、新たなtimecodesを生成しています。

読み進めるとsuperメソッドでOTPクラスのverifyが呼ばれているので、こちらも読んでみます。

def verify(input, generated)
  raise ArgumentError, '`otp` should be a String' unless
      input.is_a?(String)

  time_constant_compare(input, generated)
end

# constant-time compare the strings
def time_constant_compare(a, b)
  return false if a.empty? || b.empty? || a.bytesize != b.bytesize

  l = a.unpack "C#{a.bytesize}"
  res = 0
  b.each_byte { |byte| res |= byte ^ l.shift }
  res == 0
end

こちらもコンソールで試してみます。

$ totp = ROTP::TOTP.new("kossywebengineer", issuer: "Test Service")

$ a, b = [totp.now] * 2 # 今回のコードは435752です

$ a.empty? || b.empty? || a.bytesize != b.bytesize
=> false

$ l = a.unpack "C#{a.bytesize}" # a.bytesizeの返り値は6です
=> [52, 51, 53, 55, 53, 50]

$ b.each_byte { |byte| res |= byte ^ l.shift }
=> "435752"

$ res
=> 0

# ここからeach_bytesの挙動の確認
$ l = a.unpack "C#{a.bytesize}"

$ res |= b.bytes[0] ^ l.shift
=> 0
$ res |= b.bytes[1] ^ l.shift
=> 0
$  res |= b.bytes[2] ^ l.shift
=> 0
$  res |= b.bytes[3] ^ l.shift
=> 0
$  res |= b.bytes[4] ^ l.shift
=> 0
$  res |= b.bytes[5] ^ l.shift
=> 0

$ l
=> []

引数で渡されたワンタイムパスワードと、現在のワンタイムパスワードをバイナリにしてビット演算し、両者が一致(0だったら)していれば TRUE が返る処理になっていました。

なぜこのような処理になっているかはrotp内では言及されていませんでしたが、deviseに似たような処理があり、以下のブログで、
「これは、認証用の文字列 (ハッシュされたパスワードか API トークンかに関係なく) を比較するときに本当に実行したいことです。
これにより、アプリケーションでタイミング攻撃を使用することがはるかに難しくなります。」

と言及されていました。なので、Timing Attackを軽減させるための実装なのかもしれません。

spazidigitali.com

寄り道が長くなってしまいました。

OTPクラスのverifyが TRUE だった場合、timecodeとintervalを乗算した値が返り値となります。

一度もvefiryが TRUE にならなかった場合は、nilが返り値となります。


まとめ

Tokenの生成やビット演算など、普段Webアプリの実装をしているとあまり見かけないコードにお目にかかることができました。

2要素認証の機能をごくごく簡単に実装できる素晴らしいGemだと思うので、機会があれば使ってみようかと思います。

メールのFromに特殊文字を入れるとBounceすることがある

こんにちは!kossyです!




さて、今回はメール送信時にFromに特殊文字を入れてBounceする事案に遭遇したので、
ブログに残してみたいと思います。



[Sample] Sampleメールです

上記のように、送信元の文字の始まりが 半角の [ の場合、メールがBounceされてしまうことがあります。

Ruby On Rails のActionMailer等でメールを送信している場合、以下のような記述になっていると、問題が発生する可能性があります。

mail from: "[Sample] <no-reply@sample.com>", subject: 'Sample'

どうしてもFromに差出人名を入れたい場合は、半角カッコではなく、「【 」の ような全角カッコを使うようにしましょう。

mail from: "【Sample】 <no-reply@sample.com>", subject: 'Sample'

ActionMailerでHeaderの中身を確認したい

こんにちは!kossyです!




今回はActionMailerで送信するメールのHeaderの中身をコンソールから確認する方法について、

ブログに残してみたいと思います。




環境
Ruby 2.6.9
Rails 6.1.4
sendgrid



deliver_now を使う

Jobでメール送信をQueueする場合はdeliver_laterを使うのが一般的だと思いますが、

deliver_nowを使うと、JobではなくWebサーバー上で同期的にメールを送信することができます。

mail = SampleMailer.send_mail.deliver_now
<Mail::Message:99301180,
  Multipart: false,
  Headers:
    <Date: Thu, 03 Feb 2022 18:01:39 +0900>,
    <From: sample <no-reply-qa@mail.sample.com>>,
    <To: ["samplestaff001@sample.co.jp", "samplestaff002@sample.co.jp"]>,
    <Bcc: ["sample.co.jp"]>,
    <Message-ID: <sample@ip-10-1-3-173.ap-northeast-1.compute.internal.mail>>,
    <Subject: 【sample】サンプルメールです。>,
    <Mime-Verscomn: 1.0>,
    <Content-Type: text/html>,
    <Content-Transfer-Encoding: quoted-printable>,
    <categories: www.sample.xyz, sample>,
    <send-at: 1643878898>,
    <custom-args: {:send_at=>1643878898, :environment=>"www.sample.xyz",:mailer=>"sample"}>
>

Headersの部分がメール送信時のHeaderになります。

ちなみにdeliver_nowの返り値は Mail::Message オブジェクトになっているので、 headerメソッドのfield_summaryというメソッドが使えます。

github.com

field_summaryメソッドを使うと、Header部分をinspectした値を得られます。

mail.header.field_summary
=> "<Date: Thu, 03 Feb 2022 18:01:39 +0900>,
    <From: Sample <no-reply-sample@mail.sample.xyz>>,
    <To: [\"sample1@sample.co.jp\", \"sample2@sample.co.jp\"]>,
    <Bcc: [\"sample3@sample.co.jp\"]>,
    <Message-ID: <sample@ip-10-1-3-173.ap-northeast-1.compute.internal.mail>>,
    <Subject: 【sample】サンプルメールです。>,
    <Mime-Version: 1.0>,
    <Content-Type: text/html>,
    <Content-Transfer-Encoding: quoted-printable>,
    <categories: www.sample.xyz, sample>,
    <send-at: 1643878898>,
    <custom-args: {:send_at=>1643878898, :environment=>\"www.sample.xyz\",
      :mailer=>\"sample\"}>"

勉強になりました。

RailsのActiveRecordを使ったモデルに定義されたassociation情報を全て取得する reflect_on_all_associations のソースコードを読んでみる

こんにちは!kossyです!




諸事情ありブログを書かずにおりました、、、

月8 ~ 10本ペースは守りたいと思いつつも、なかなか時間の確保が厳しいですね、、、(根性が足りないと言われればその通りなのですが)




今回は、RailsActiveRecordを使ったモデルに定義されたassociation情報を全て取得する reflect_on_all_associations のソースコードを読んでみたので、

備忘録としてブログに残してみたいと思います。




環境
Ruby 2.6.9
Rails 6.1.4




reflect_on_all_associations

まずは適当な箇所にbinding.pryを仕込んで、stepメソッドで処理の内部を見てみます。

From: /usr/local/bundle/gems/activerecord-6.0.4.1/lib/active_record/reflection.rb:104 ActiveRecord::Reflection::ClassMethods#reflect_on_all_associations:

    103: def reflect_on_all_associations(macro = nil)
 => 104:   association_reflections = reflections.values
    105:   association_reflections.select! { |reflection| reflection.macro == macro } if macro
    106:   association_reflections
    107: end

[1] pry(User)>

定義元はこちらですね。

github.com

いろいろ実行する前に、コメントアウト部分を読んでみます。

Returns an array of AssociationReflection objects for all the associations in the class.

If you only want to reflect on a certain association type, pass in the symbol :has_many, :has_one, :belongs_to as the first parameter.

クラス内のすべての関連付けのAssociationReflectionオブジェクトの配列を返します。

特定の関連付けタイプのみを反映する場合は、最初のパラメーターとしてシンボル:has_many、:has_one、:belongs_toを渡します。

出典: https://github.com/rails/rails/blob/main/activerecord/lib/active_record/reflection.rb

返り値は配列になるとのこと。一旦exitで抜けて、メソッドの中に入らずに返り値を確認してみます。

$  User.reflect_on_all_associations
=> [#<ActiveRecord::Reflection::HasManyReflection:0x000055b2c512eaa8
  @active_record=
   User(id: integer, email: string, encrypted_password: string, reset_password_token: string, reset_password_sent_at: datetime, remember_created_at: datetime, unique_session_id: string, created_at: datetime, updated_at: datetime),
  @constructable=true,
  @foreign_type=nil,
  @klass=nil,
  @name=:posts,
  @options={:dependent=>:destroy},
  @plural_name="posts",
  @scope=nil,
  @type=nil>]

$ User.reflect_on_all_associations.class
=> Array

$ User.reflect_on_all_associations.size
=> 1

$ User.reflect_on_all_associations.first.class
=> ActiveRecord::Reflection::HasManyReflection

返り値は配列になっていて、ActiveRecord::Reflection::HasManyReflectionクラスのオブジェクトが配列の中身に格納されていました。


ソースコードを追ってみる

ここからはもう一度stepメソッドを使ってメソッドの中身を追ってみます。

From: /usr/local/bundle/gems/activerecord-6.0.4.1/lib/active_record/reflection.rb:104 ActiveRecord::Reflection::ClassMethods#reflect_on_all_associations:

    103: def reflect_on_all_associations(macro = nil)
 => 104:   association_reflections = reflections.values
    105:   association_reflections.select! { |reflection| reflection.macro == macro } if macro
    106:   association_reflections
    107: end

# 引数を渡して実行してないため、nilが返る
>  macro
=> nil

# hashが返り値になっている
> reflections
=> {"posts"=>
  #<ActiveRecord::Reflection::HasManyReflection:0x000055b2c512eaa8
   @active_record=
    User(id: integer, email: string, encrypted_password: string, reset_password_token: string, reset_password_sent_at: datetime, remember_created_at: datetime, unique_session_id: string, created_at: datetime, updated_at: datetime),
   @constructable=true,
   @foreign_type=nil,
   @klass=nil,
   @name=:posts,
   @options={:dependent=>:destroy},
   @plural_name="posts",
   @scope=nil,
   @type=nil>}

# posts keyの中身が配列で返っている
> reflections.values
=> [#<ActiveRecord::Reflection::HasManyReflection:0x000055b2c512eaa8
  @active_record=
   User(id: integer, email: string, encrypted_password: string, reset_password_token: string, reset_password_sent_at: datetime, remember_created_at: datetime, unique_session_id: string, created_at: datetime, updated_at: datetime),
  @constructable=true,
  @foreign_type=nil,
  @klass=nil,
  @name=:posts,
  @options={:dependent=>:destroy},
  @plural_name="posts",
  @scope=nil,
  @type=nil>]

一通り処理の内容は理解できました。reflectionsオブジェクトの中身をよしなにいじって、モデルに定義されたassociation情報を返している感じですね。


応用的な使い方

以下のように書くと、そのモデルに定義されているassociation名の配列を得ることができます。

$ User.reflect_on_all_associations.map(&:name)
=> [:posts]

例えば、has_manyなレコードが存在する場合に何かしらの処理を加えたい、という場合に以下のように書くことができます。

has_many_association_names = User.reflect_on_all_associations(:has_many).map(&:name)

if has_many_association_names.any? { |name| user.public_send(name).exists? }
  # 何かしらの処理
else
  # 何かしらの処理
end

こう書くことで、新たに関連を追加した時に、わざわざ定数にsymbolを追加しなくてもよくなり、コードの変更箇所を減らすことができます。




勉強になりました。

SmartHealthCardsの発行と検証を行うことができるGem 「health_cards」の JWSの生成周りのソースコードを読んでみる

こんにちは!kossyです!




今回はSmartHealthCardsの発行と検証を行うことができるGem 「health_cards」の JWSの生成周りのソースコードを読んでみたので、

備忘録としてブログに残してみたいと思います。




環境
Ruby 3.0.3
Rails 6.1.3.1
MacOS Catalina latest



HealthCards::Issuer#issue_jws

例によってtest_appディレクトリのファイルを基に動作を確認してみます。

github.com

$ key = HealthCards::PrivateKey.generate_key

$ issuer = HealthCards::Issuer.new(key: key, url: 'http://example.com')

$ jws = issuer.issue_jws(FHIR::Bundle.new)

From: health_cards/lib/health_cards/issuer.rb:35 HealthCards::Issuer#issue_jws:

    33: def issue_jws(bundle, type: Payload)
    34:   binding.pry
 => 35:   card = create_payload(bundle, type: type)
    36:   JWS.new(header: jws_header, payload: card.to_s, key: key)
    37: end

$ bundle
=> #<FHIR::Bundle:0x00007fb0c1cbfce0
 @entry=[],
 @id=nil,
 @identifier=nil,
 @implicitRules=nil,
 @language=nil,
 @link=[],
 @meta=nil,
 @signature=nil,
 @timestamp=nil,
 @total=nil,
 @type=nil>

$ type
=> HealthCards::Payload

一通り引数の中身を確認できたので、まずは HealthCards::Issuer#create_payload メソッドから見てみます。


HealthCards::Issuer#create_payload

github.com

# Create a Payload from the supplied FHIR bundle
#
# @param bundle [FHIR::Bundle, String] the FHIR bundle used as the Health Card payload
# @return [Payload::]
def create_payload(bundle, type: Payload)
  type.new(issuer: url, bundle: bundle)
end

コメントアウト部分を訳してみます。

引数で渡されたFHIRバンドルからペイロードを作成します。

bundle (FHIR::BundleまたはString) : HealthCardのPayloadとして使用されるFHIRバンドル
返り値は HealthCards::Payload インスタンス

出典: https://github.com/dvci/health_cards/blob/main/lib/health_cards/issuer.rb

FHIR::Bundle はfhir_model というGemで定義されているクラスです。

github.com

stepメソッドでcreate_payloadメソッドの処理を追ってみます。

From: health_cards/issuer.rb:24 HealthCards::Issuer#create_payload:

    23: def create_payload(bundle, type: Payload)
 => 24:   type.new(issuer: url, bundle: bundle)
    25: end

$ type.new(issuer: url, bundle: bundle)
=> #<HealthCards::Payload:0x00007fb103fa2240
 @bundle=
  #<FHIR::Bundle:0x00007fb0c1cbfce0
   @entry=[],
   @id=nil,
   @identifier=nil,
   @implicitRules=nil,
   @language=nil,
   @link=[],
   @meta=nil,
   @signature=nil,
   @timestamp=nil,
   @total=nil,
   @type=nil>,
 @issuer="http://example.com">

コメントアウトに記載があった通り、HealthCards::Payloadクラスのインスタンスが返りました。

github.com

SmartHealthCardsの仕様に則ってPayloadを管理するクラスのようですね。

spec.smarthealth.cards

本記事内では SmartHealthCards の仕様の深掘りは避けたいと思います、、、(それだけで1本のブログになりそうなので)

次はHealthCards::JWSクラスの実装を深掘ってみます。

HealthCards::JWS

github.com

   
# frozen_string_literal: true

module HealthCards
  # Create JWS from a payload
  class JWS
    class << self
      include Encoding

      # Creates a JWS from a String representation, or returns the HealthCards::JWS object
      # that was passed in
      # @param jws [String, HealthCards::JWS] the JWS string, or a JWS object
      # @param public_key [HealthCards::PublicKey] the public key associated with the JWS
      # @param key [HealthCards::PrivateKey] the private key associated with the JWS
      # @return [HealthCards::JWS] A new JWS object, or the JWS object that was passed in
      def from_jws(jws, public_key: nil, key: nil)
        return jws if jws.is_a?(HealthCards::JWS) && public_key.nil? && key.nil?

        unless jws.is_a?(HealthCards::JWS) || jws.is_a?(String)
          raise ArgumentError,
                'Expected either a HealthCards::JWS or String'
        end

        header, payload, signature = jws.to_s.split('.').map { |entry| decode(entry) }
        header = JSON.parse(header)
        JWS.new(header: header, payload: payload, signature: signature,
                public_key: public_key, key: key)
      end
    end

    attr_reader :key, :public_key, :payload
    attr_writer :signature
    attr_accessor :header

    # Create a new JWS

    def initialize(header: nil, payload: nil, signature: nil, key: nil, public_key: nil)
      # Not using accessors because they reset the signature which requires both a key and a payload
      @header = header
      @payload = payload
      @signature = signature if signature
      @key = key
      @public_key = public_key || key&.public_key
    end

    # The kid value from the JWS header, used to identify the key to use to verify
    # @return [String]
    def kid
      header['kid']
    end

    # Set the private key used for signing issued health cards
    #
    # @param key [HealthCards::PrivateKey, nil] the private key used for signing issued health cards
    def key=(key)
      PrivateKey.enforce_valid_key_type!(key, allow_nil: true)

      @key = key

      # If it's a new private key then the public key and signature should be updated
      return if @key.nil?

      reset_signature
      self.public_key = @key.public_key
    end

    # Set the public key used for signing issued health cards
    #
    # @param public_key [HealthCards::PublicKey, nil] the private key used for signing issued health cards
    def public_key=(public_key)
      PublicKey.enforce_valid_key_type!(public_key, allow_nil: true)

      @public_key = public_key
    end

    # Set the JWS payload. Setting a new payload will result in the a new signature
    # @param new_payload [Object]
    def payload=(new_payload)
      @payload = new_payload
      reset_signature
    end

    # The signature component of the card
    #
    # @return [String] the unencoded signature
    def signature
      return @signature if @signature

      raise MissingPrivateKeyError unless key

      @signature ||= key.sign(jws_signing_input)
    end

    # Export the card to a JWS String
    # @return [String] the JWS
    def to_s
      [JSON.generate(header), payload, signature].map { |entry| JWS.encode(entry) }.join('.')
    end

    # Verify the digital signature on the jws
    #
    # @return [Boolean]
    def verify
      raise MissingPublicKeyError unless public_key

      public_key.verify(jws_signing_input, signature)
    end

    private

    def jws_signing_input
      "#{JWS.encode(@header.to_json)}.#{encoded_payload}"
    end

    def encoded_payload
      JWS.encode(payload)
    end

    # Resets the signature
    #
    # This method is primarily used when an attribute that affects
    # the signature is changed (e.g. the private key changes, the payload changes)
    def reset_signature
      @signature = nil
      signature if key && payload
    end
  end
end

まずは initializeメソッドから見てみます。

HealthCards::JWS#initialize
# Create a new JWS
# 新しいJWSを作成します。

def initialize(header: nil, payload: nil, signature: nil, key: nil, public_key: nil)
  # Not using accessors because they reset the signature which requires both a key and a payload
  @header = header
  @payload = payload
  @signature = signature if signature
  @key = key
  @public_key = public_key || key&.public_key
end

stepメソッドで処理を追ってみます。

From: health_cards/lib/health_cards/issuer.rb:36 HealthCards::Issuer#issue_jws:

    33: def issue_jws(bundle, type: Payload)
    34:   binding.pry
    35:   card = create_payload(bundle, type: type)
 => 36:   JWS.new(header: jws_header, payload: card.to_s, key: key)
    37: end

$ step

From: health_cards/lib/health_cards/issuer.rb:63 HealthCards::Issuer#jws_header:

    62: def jws_header
 => 63:   { 'zip' => 'DEF', 'alg' => 'ES256', 'kid' => key.public_key.kid }
    64: end

$ key.public_key.kid
=> "v_HwwS_bad-bOABD3Uf9DpmMNMpKD_OxKtYluML1Mxs"

zipやalg、kidとはなんぞや?についてはrfc7516に記載があります。

datatracker.ietf.org

alg

4.1.1. "alg" (Algorithm) Header Parameter

This parameter has the same meaning, syntax, and processing rules as the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except that the Header Parameter identifies the cryptographic algorithm used to encrypt or determine the value of the CEK.
The encrypted content is not usable if the "alg" value does not represent a supported algorithm, or if the recipient does not have a key that can be used with that algorithm.

A list of defined "alg" values for this use can be found in the IANA "JSON Web Signature and Encryption Algorithms" registry established by [JWA]; the initial contents of this registry are the values defined in Section 4.1 of [JWA].

このパラメーターは、[JWS]のセクション4.1.1で定義されている「alg」ヘッダーパラメーターと同じ意味、構文、および処理ルールを持ちます。
ただし、ヘッダーパラメーターは、CEKの値を暗号化または決定するために使用される暗号化アルゴリズムを識別します。

「alg」値がサポートされているアルゴリズムを表していない場合、または受信者がそのアルゴリズムで使用できるキーを持っていない場合、暗号化されたコンテンツは使用できません。

この使用のために定義された「alg」値のリストは、[JWA]によって確立されたIANA「JSONWeb署名および暗号化アルゴリズムレジストリにあります。
このレジストリの初期の内容は、[JWA]のセクション4.1で定義されている値です。

出典: https://datatracker.ietf.org/doc/html/rfc7516#section-4

RFC7518によると、ES256 アルゴリズムが recommended として記載されていました。

そのため、health_cards GemでもデフォルトのalgパラメータにES256を指定しているものと思われます。

datatracker.ietf.org

zip

The "zip" (compression algorithm) applied to the plaintext before encryption, if any. The "zip" value defined by this specification

is:

o "DEF" - Compression with the DEFLATE [RFC1951] algorithm

Other values MAY be used. Compression algorithm values can be registered in the IANA "JSON Web Encryption Compression Algorithms" registry established by [JWA].
The "zip" value is a case-sensitive string.
If no "zip" parameter is present, no compression is applied to the plaintext before encryption.
When used, this Header Parameter MUST be integrity protected; therefore, it MUST occur only within the JWE Protected Header.
Use of this Header Parameter is OPTIONAL. This Header Parameter MUST be understood and processed by implementations.

暗号化する前にプレーンテキストに適用される「zip」(圧縮アルゴリズム)。この仕様で定義されている「zip」値は次のとおりです。

o "DEF"-DEFLATE [RFC1951]アルゴリズムによる圧縮

他の値が使用される場合があります。圧縮アルゴリズムの値は、[JWA]によって確立されたIANA "JSON Web Encryption Compression Algorithms"レジストリに登録できます。
「zip」値は、大文字と小文字が区別される文字列です。 「zip」パラメータが存在しない場合、暗号化の前にプレーンテキストに圧縮は適用されません。
使用する場合、このヘッダーパラメーターは整合性を保護する必要があります。したがって、JWE保護ヘッダー内でのみ発生する必要があります。
このヘッダーパラメータの使用はオプションです。このヘッダーパラメータは、実装によって理解および処理される必要があります。

出典: https://datatracker.ietf.org/doc/html/rfc7516#section-4

平たく言うと、コンテンツを暗号化する前に、zip headerで指定されているアルゴリズム(今回はDEFLATE)でプレーンテキストを圧縮できるということかと思われます。

kid

This parameter has the same meaning, syntax, and processing rules as the "kid" Header Parameter defined in Section 4.1.4 of [JWS],
except that the key hint references the public key to which the JWE was encrypted;
this can be used to determine the private key needed to decrypt the JWE.
This parameter allows originators to explicitly signal a change of key to JWE recipients.



このパラメーターは、[JWS]のセクション4.1.4で定義されている「kid」ヘッダーパラメーターと同じ意味、構文、および処理ルールを持ちます。
ただし、キーヒントはJWEが暗号化された公開キーを参照します。 これは、JWEを復号化するために必要な秘密鍵を決定するために使用できます。
このパラメーターを使用すると、発信者はキーの変更をJWE受信者に明示的に通知できます。

出典: https://datatracker.ietf.org/doc/html/rfc7516#section-4

RFC7515の4.1.4を見てみます。

datatracker.ietf.org

The "kid" (key ID) Header Parameter is a hint indicating which key was used to secure the JWS.
This parameter allows originators to explicitly signal a change of key to recipients.
The structure of the "kid" value is unspecified.
Its value MUST be a case-sensitive string. Use of this Header Parameter is OPTIONAL.

When used with a JWK, the "kid" value is used to match a JWK "kid" parameter value.


「kid」(キーID)ヘッダーパラメータは、JWSを保護するために使用されたキーを示すヒントです。
このパラメーターを使用すると、発信者は受信者にキーの変更を明示的に通知できます。
「kid」値の構造は指定されていません。
その値は大文字と小文字を区別する文字列でなければなりません。 このヘッダーパラメータの使用はオプションです。

JWKとともに使用する場合、「kid」値はJWK「kid」パラメーター値と一致するために使用されます。

「kid」値の構造は指定されていません。が、「その値は大文字と小文字を区別する文字列でなければなりません。」とのこと。

「発信者は受信者にキーの変更を明示的に通知できます。」も抑えておけば一旦はよさそうです。

寄り道がだいぶ長くなりました。実際に JWS.new で生成される値は以下の通りです。

$ jws = JWS.new(header: jws_header, payload: card.to_s, key: key)
=> #<HealthCards::JWS:0x00007fb0c0058200
 @header={"zip"=>"DEF", "alg"=>"ES256", "kid"=>"Nx1LIgqlyubgocWo7EgptlZ4Cg0iuOuUPw1a5U7ATk8"},
 @key=
  #<HealthCards::PrivateKey:0x00007fb0e3f71ef8
   @key=#<OpenSSL::PKey::EC:0x00007fb0e3f71f20>,
   @public_key=
    #<HealthCards::PublicKey:0x00007fb10760b700
     @coordinates=
      {:x=>"5cIFHiDkh35xAmGnAj5cxIBk99KQWvwo9r6cqpon6Kk",
       :y=>"wyc5x3azGxi0CaFt8yVUJHdaXblJhjh7hTnL2WqI9ek",
       :kty=>"EC",
       :crv=>"P-256"},
     @key=#<OpenSSL::PKey::EC:0x00007fb0a54a4568>>>,
 @payload="",
 @public_key=
  #<HealthCards::PublicKey:0x00007fb10760b700
   @coordinates=
    {:x=>"5cIFHiDkh35xAmGnAj5cxIBk99KQWvwo9r6cqpon6Kk", :y=>"wyc5x3azGxi0CaFt8yVUJHdaXblJhjh7hTnL2WqI9ek", :kty=>"EC", :crv=>"P-256"},
   @key=#<OpenSSL::PKey::EC:0x00007fb0a54a4568>>>

まとめ

HealthCard::JWSのソースコードを読むためには RFCの7515 ~ 7518 あたりの知識が総出で必要になりますね、、、

ただ、RFCだけ読んでも、「実際にどうやって書くの?」までは想像しづらかったりするので、

プレーンなRubyコードでJWS周りのコードを実装している health_cardsのコードを読むのは正解だったと思います。