persona-protocol 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c3d3ff355f856b7467643bf5e39a108d11be6d4e8f471e01203b1b9059836d4
+  data.tar.gz: 6d30790a52861e0f69f6bc0d21d1807d56de740236cf61db336d12e96d423ea2
+SHA512:
+  metadata.gz: 3b6a984f0354d4c0f0079921b32ab9a7a5c6e1fdc2cb4f10c790ca85dd06ef294e248937407b615a2b6ee96958adeb4db81c8f6806c003ba06b34d21e3dbd098
+  data.tar.gz: fee2f202019c0341c2f3ef0064b3d851a8e83b1938eb6f21df3b986ba69eedf437792fd15905d072cc975ce5ddda39749f7711edc7ce545a329c9e28c6019f95

data/AUTHORS

@@ -0,0 +1,6 @@
+# This is the list of people who have contributed to persona-protocol and are
+# referred to collectively as "UNIBA COMMONS Authors" in the copyright notices.
+#
+# Format: Name <email>
+
+Haruma Kikuchi <haruma@uniba.jp>

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UNIBA COMMONS Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/persona/account_link.rb

@@ -0,0 +1,98 @@
+module Persona
+  # Binds a verified OIDC identity (provider + subject) to a persona.
+  #
+  # Structurally the same event as redeeming a recovery code: the subject
+  # identifies a "holder" — the persona already bound to it, if any — and the
+  # acting browser is either adopted into that holder or has the subject
+  # linked to it. When the browser is already a *different* joined persona
+  # with contributions, the two are folded together via the store's merge,
+  # gated by a confirmation preview.
+  #
+  # Callers pass the browser's agent_uid so an anonymous browser can be
+  # bound; current_user (resolved from the X-Agent-Id header or the session
+  # cookie, depending on transport) is the persona the browser is currently
+  # acting as, or nil when still anonymous.
+  #
+  # All persistence goes through a storage port so the decision logic stays
+  # host-agnostic. The port is an object implementing:
+  #
+  #   holder_for(provider:, subject:)            -> user | nil
+  #   within_transaction { ... }                 atomic scope; yields
+  #   create_guest!(agent_uid:, user_agent:)     -> user, already bound to
+  #                                              agent_uid, with the app's
+  #                                              usual join side effects run
+  #   add_account_binding!(user, provider:, subject:)
+  #   agent_binding?(user, agent_uid:)           -> boolean
+  #   add_agent_binding!(user, agent_uid:, user_agent:)
+  #   merge_preview(source:, target:)            -> opaque preview object,
+  #                                              MUST NOT change data
+  #   merge!(source:, target:)                   move all bindings and domain
+  #                                              records from source to
+  #                                              target, then retire source
+  #
+  # User objects are the host's own; the only requirement is a stable #id.
+  # Consumers register their implementation via
+  # Persona.config.account_link_store (an ActiveRecord example lives in
+  # examples/ at the repository root).
+  module AccountLink
+    # agent_uid is set only when the browser must persist a (new) one via
+    # setAgentId — i.e. the anonymous cases. merge_preview is present only
+    # when confirmation is required, in which case NOTHING was changed.
+    Result = Struct.new(:user, :agent_uid, :merged, :merge_preview, keyword_init: true)
+
+    module_function
+
+    def perform(identity:, current_user:, agent_uid:, user_agent: nil, confirm_merge: false,
+                store: Persona.config.account_link_store)
+      raise ConfigurationError, 'Persona.config.account_link_store is not configured — ' \
+                                'provide an object implementing the AccountLink storage port' if store.nil?
+
+      holder = holder_for(identity, store: store)
+
+      # Conflict peek: the browser is joined as someone other than the
+      # subject's current holder. Return the preview without touching data so
+      # the user can still cancel; the client re-sends with confirm_merge.
+      if current_user && holder && current_user.id != holder.id && !confirm_merge
+        return Result.new(
+          user: current_user,
+          agent_uid: nil,
+          merged: false,
+          merge_preview: store.merge_preview(source: current_user, target: holder),
+        )
+      end
+
+      store.within_transaction do
+        # Subject not yet linked to any persona: bind it to the acting
+        # persona, creating a fresh guest first if the browser is anonymous.
+        if holder.nil?
+          holder = current_user || store.create_guest!(agent_uid: agent_uid, user_agent: user_agent)
+          store.add_account_binding!(holder, provider: identity.provider, subject: identity.subject)
+        end
+
+        merged = false
+        if current_user && current_user.id != holder.id
+          store.merge!(source: current_user, target: holder)
+          merged = true
+        end
+
+        # Ensure this browser's agent_uid resolves to the holder. For a joined
+        # browser that was just merged, merge! already moved its binding; for
+        # an anonymous browser adopting an existing holder, add it now.
+        unless store.agent_binding?(holder, agent_uid: agent_uid)
+          store.add_agent_binding!(holder, agent_uid: agent_uid, user_agent: user_agent)
+        end
+
+        Result.new(
+          user: holder,
+          agent_uid: current_user ? nil : agent_uid,
+          merged: merged,
+          merge_preview: nil,
+        )
+      end
+    end
+
+    def holder_for(identity, store: Persona.config.account_link_store)
+      store.holder_for(provider: identity.provider, subject: identity.subject)
+    end
+  end
+end

data/lib/persona/claim_code.rb

@@ -0,0 +1,36 @@
+require 'digest'
+require 'securerandom'
+
+module Persona
+  # Single-use claim codes (docs/spec §6): generation, input
+  # normalization, display formatting, and digest-at-rest. Codes use
+  # Crockford base32 (no I, L, O, U) so they survive being read aloud or
+  # typed. Storage keeps only the digest; consumption is the consumer's
+  # concern (single-use, atomic — P-7).
+  module ClaimCode
+    ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'.freeze
+
+    module_function
+
+    # 16 chars ≈ 80 bits — fine for a short-lived, single-use code. Raise
+    # the length for codes expected to sit unused for long periods.
+    def generate(length: 16)
+      Array.new(length) { ALPHABET[SecureRandom.random_number(ALPHABET.length)] }.join
+    end
+
+    # Accept a pasted code in any spacing or case.
+    def normalize(input)
+      input.to_s.upcase.gsub(/[^0-9A-Z]/, '')
+    end
+
+    # Group into 4-char blocks for display: "3F7K-9B2D-…".
+    def format(code)
+      normalize(code).scan(/.{1,4}/).join('-')
+    end
+
+    # What gets persisted instead of the code (P-7).
+    def digest(code)
+      Digest::SHA256.hexdigest(normalize(code))
+    end
+  end
+end

data/lib/persona/oidc/link_store.rb

@@ -0,0 +1,100 @@
+require 'json'
+require 'securerandom'
+
+module Persona
+  module Oidc
+    # Short-lived Redis storage that ties the OIDC redirect round-trip to the
+    # browser that started it — without ever putting the agent_uid in a URL.
+    #
+    #   begin            : put_pending(state, agent_uid:, provider:)
+    #   /auth/oidc/callback : take_pending(state) -> {agent_uid:, provider:}
+    #                                                            (single use)
+    #                         put_result(link_token, ...)       hands the
+    #                                                            verified subject
+    #                                                            back to the app
+    #   complete         : peek_result(link_token) -> {...}     (non-destructive,
+    #                                                            so the merge
+    #                                                            confirm can re-read)
+    #                         drop_result(link_token)           on final success
+    #
+    # The Redis dependency is injected: pass either a raw client (responds to
+    # #get / #set / #del) or a connection pool (responds to #with yielding a
+    # client). Consumers register the instance via Persona.config.link_store.
+    class LinkStore
+      PENDING_PREFIX = 'persona:oidc:pending:'.freeze
+      RESULT_PREFIX = 'persona:oidc:result:'.freeze
+      PENDING_TTL = 600 # 10 min to complete the IdP round-trip
+      RESULT_TTL = 300  # 5 min to finish the client-side confirm
+
+      def initialize(redis:)
+        @redis = redis
+      end
+
+      def generate_token
+        SecureRandom.urlsafe_base64(32)
+      end
+
+      # provider records which registered IdP this round-trip was begun for,
+      # so the callback verifies against the same provider (multi-provider
+      # deployments; docs/spec §7). stash carries the provider's per-flow
+      # secrets (PKCE code_verifier, nonce) from authorize to verify.
+      def put_pending(state, agent_uid:, provider:, stash: nil)
+        write(PENDING_PREFIX + state, { agent_uid: agent_uid, provider: provider, stash: stash }, PENDING_TTL)
+      end
+
+      # Consumes the pending entry (state is single-use, CSRF-style).
+      def take_pending(state)
+        take(PENDING_PREFIX + state)
+      end
+
+      def put_result(link_token, provider:, subject:, agent_uid:)
+        write(
+          RESULT_PREFIX + link_token,
+          { provider: provider, subject: subject, agent_uid: agent_uid },
+          RESULT_TTL,
+        )
+      end
+
+      # Non-destructive: the merge-preview first call must leave the token
+      # valid for the confirm call.
+      def peek_result(link_token)
+        read(RESULT_PREFIX + link_token)
+      end
+
+      def drop_result(link_token)
+        with_redis { |conn| conn.del(RESULT_PREFIX + link_token) }
+      end
+
+      private
+
+      def with_redis(&block)
+        if @redis.respond_to?(:with)
+          @redis.with(&block)
+        else
+          yield @redis
+        end
+      end
+
+      def write(key, hash, ttl)
+        with_redis { |conn| conn.set(key, hash.to_json, ex: ttl) }
+      end
+
+      def read(key)
+        raw = with_redis { |conn| conn.get(key) }
+        return nil if raw.nil?
+
+        JSON.parse(raw, symbolize_names: true)
+      end
+
+      def take(key)
+        with_redis do |conn|
+          raw = conn.get(key)
+          conn.del(key)
+          return nil if raw.nil?
+
+          JSON.parse(raw, symbolize_names: true)
+        end
+      end
+    end
+  end
+end

data/lib/persona/oidc/verifier.rb

@@ -0,0 +1,222 @@
+require 'json'
+require 'uri'
+require 'net/http'
+require 'digest'
+require 'base64'
+require 'securerandom'
+require 'jwt'
+
+module Persona
+  module Oidc
+    # Default HTTP client (Net::HTTP) used by Verifier for discovery, JWKS, and
+    # the token exchange. Injectable — tests pass a fake responding to the same
+    # #get / #post_form contract. Returns the response body on 2xx, nil otherwise.
+    class NetHttpClient
+      def get(url)
+        uri = URI(url)
+        request(uri, Net::HTTP::Get.new(uri))
+      end
+
+      def post_form(url, params)
+        uri = URI(url)
+        req = Net::HTTP::Post.new(uri)
+        req['Accept'] = 'application/json'
+        req.set_form_data(params)
+        request(uri, req)
+      end
+
+      private
+
+      def request(uri, req)
+        res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
+        res.is_a?(Net::HTTPSuccess) ? res.body : nil
+      end
+    end
+
+    # Production OIDC verifier provider (docs/spec §7, P-16): the
+    # authorization-code + PKCE flow, OIDC discovery, code exchange, and
+    # id_token validation against the IdP's published JWKS. Mirrors the
+    # TypeScript createOidcVerifierProvider.
+    #
+    # Signature verification uses the jwt gem's OpenSSL backend and covers
+    # RS256 and ES256. EdDSA (Ed25519) is intentionally not enabled here — it
+    # needs rbnacl in Ruby — so an IdP signing with EdDSA must expose an
+    # RS256/ES256 key or wait for that follow-up.
+    #
+    # The clock (#now) is injectable so expiry is checked here rather than by
+    # the jwt gem, matching the TS verifier and keeping tests deterministic.
+    class Verifier
+      ALLOWED_ALGS = %w[RS256 ES256].freeze
+
+      attr_reader :name
+
+      def initialize(
+        name:, issuer:, client_id:, redirect_uri:,
+        client_secret: nil, scope: 'openid email',
+        authorization_endpoint: nil, token_endpoint: nil, jwks_uri: nil,
+        authorize_params: {}, require_hosted_domain: nil, allowed_email_domain: nil,
+        http: NetHttpClient.new, now: -> { Time.now.to_i }, clock_tolerance: 60
+      )
+        @name = name
+        @issuer = issuer.to_s.sub(%r{/\z}, '')
+        @client_id = client_id
+        @redirect_uri = redirect_uri
+        @client_secret = client_secret
+        @scope = scope
+        @explicit_endpoints = { authorization_endpoint: authorization_endpoint,
+                                token_endpoint: token_endpoint, jwks_uri: jwks_uri }
+        @authorize_params = authorize_params
+        @require_hosted_domain = require_hosted_domain
+        @allowed_email_domain = allowed_email_domain
+        @http = http
+        @now = now
+        @clock_tolerance = clock_tolerance
+        @discovery = nil
+        @jwks = nil
+      end
+
+      # Preset for uniba/auth (github.com/uniba/auth): the uniba.jp shared OIDC
+      # AS. Fills in the name, scope, and hd=uniba.jp upstream constraint; the
+      # issuer and client credentials stay per-deployment. auth is not yet
+      # published, so the token-claim domain check defaults to the email domain
+      # (provisional). Pass allowed_email_domain: nil to disable it.
+      def self.uniba_auth(issuer:, client_id:, redirect_uri:, client_secret: nil,
+                          allowed_email_domain: 'uniba.jp',
+                          http: NetHttpClient.new, now: -> { Time.now.to_i })
+        new(
+          name: 'uniba-auth', issuer: issuer, client_id: client_id, redirect_uri: redirect_uri,
+          client_secret: client_secret, scope: 'openid email',
+          authorize_params: { hd: 'uniba.jp' }, allowed_email_domain: allowed_email_domain,
+          http: http, now: now,
+        )
+      end
+
+      def authorize(state)
+        code_verifier = SecureRandom.urlsafe_base64(32)
+        nonce = SecureRandom.urlsafe_base64(16)
+        query = {
+          response_type: 'code', client_id: @client_id, redirect_uri: @redirect_uri,
+          scope: @scope, state: state, nonce: nonce,
+          code_challenge: base64url(Digest::SHA256.digest(code_verifier)),
+          code_challenge_method: 'S256',
+        }.merge(@authorize_params)
+        url = "#{discovery.fetch(:authorization_endpoint)}?#{URI.encode_www_form(query)}"
+        AuthorizeStart.new(url: url, stash: { code_verifier: code_verifier, nonce: nonce })
+      end
+
+      def verify(params, stash = nil)
+        code = params[:code] || params['code']
+        return nil if code.nil? || code.to_s.empty?
+
+        tokens = exchange_code(code, stash)
+        id_token = tokens && (tokens['id_token'] || tokens[:id_token])
+        return nil if id_token.nil?
+
+        validate_id_token(id_token, stash)
+      end
+
+      private
+
+      def discovery
+        return @discovery if @discovery
+
+        if @explicit_endpoints.values.all?
+          return @discovery = @explicit_endpoints
+        end
+
+        body = @http.get("#{@issuer}/.well-known/openid-configuration")
+        raise "OIDC discovery failed for #{@issuer}" if body.nil?
+
+        doc = JSON.parse(body)
+        if doc['issuer'] && doc['issuer'].sub(%r{/\z}, '') != @issuer
+          raise "OIDC issuer mismatch: expected #{@issuer}, got #{doc['issuer']}"
+        end
+
+        @discovery = {
+          authorization_endpoint: @explicit_endpoints[:authorization_endpoint] || doc['authorization_endpoint'],
+          token_endpoint: @explicit_endpoints[:token_endpoint] || doc['token_endpoint'],
+          jwks_uri: @explicit_endpoints[:jwks_uri] || doc['jwks_uri'],
+        }
+      end
+
+      def exchange_code(code, stash)
+        form = { grant_type: 'authorization_code', code: code,
+                 redirect_uri: @redirect_uri, client_id: @client_id }
+        code_verifier = stash && stash_value(stash, :code_verifier)
+        form[:code_verifier] = code_verifier if code_verifier
+        form[:client_secret] = @client_secret if @client_secret
+
+        body = @http.post_form(discovery.fetch(:token_endpoint), form)
+        return nil if body.nil?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def validate_id_token(id_token, stash)
+        loader = lambda do |options|
+          @jwks = nil if options[:invalidate]
+          { keys: jwks_keys }
+        end
+        # Verify the signature (and restrict algorithms) with the jwt gem; check
+        # every claim here, against the injected clock.
+        payload, = JWT.decode(id_token, nil, true, algorithms: ALLOWED_ALGS, jwks: loader,
+                                                   verify_expiration: false)
+        return nil unless valid_claims?(payload, stash)
+
+        Identity.new(provider: @name, subject: payload['sub'])
+      rescue JWT::DecodeError, JWT::JWKError
+        nil
+      end
+
+      def valid_claims?(payload, stash)
+        now = @now.call
+        return false unless payload['iss'].to_s.sub(%r{/\z}, '') == @issuer
+
+        aud = payload['aud']
+        return false unless aud == @client_id || (aud.is_a?(Array) && aud.include?(@client_id))
+
+        exp = payload['exp']
+        return false unless exp.is_a?(Numeric) && exp + @clock_tolerance > now
+
+        nbf = payload['nbf']
+        return false if nbf.is_a?(Numeric) && nbf - @clock_tolerance > now
+
+        if stash
+          nonce = stash_value(stash, :nonce)
+          return false unless nonce.nil? || payload['nonce'] == nonce
+        end
+
+        return false if @require_hosted_domain && payload['hd'] != @require_hosted_domain
+
+        if @allowed_email_domain
+          email = payload['email'].to_s.downcase
+          return false unless payload['email_verified'] == true &&
+                              email.end_with?("@#{@allowed_email_domain.downcase}")
+        end
+
+        sub = payload['sub']
+        !(sub.nil? || sub.to_s.empty?)
+      end
+
+      def jwks_keys
+        return @jwks if @jwks
+
+        body = @http.get(discovery.fetch(:jwks_uri))
+        raise 'JWKS fetch failed' if body.nil?
+
+        @jwks = JSON.parse(body)['keys']
+      end
+
+      # Stash may come back from JSON storage with either symbol or string keys.
+      def stash_value(stash, key)
+        stash[key] || stash[key.to_s]
+      end
+
+      def base64url(bytes)
+        Base64.urlsafe_encode64(bytes, padding: false)
+      end
+    end
+  end
+end

data/lib/persona/oidc.rb

@@ -0,0 +1,59 @@
+require 'cgi'
+
+module Persona
+  # OIDC account linking — the verification half of binding a persona to an
+  # external identity provider. persona-protocol owns the flow (docs/spec
+  # §7); the application registers one provider object per IdP via
+  # Persona.config.register_oidc_provider, and gains new providers by
+  # updating this gem and registering them — not by reimplementing the flow.
+  #
+  # A provider is any object exposing:
+  #
+  #   name              -> String   stable identifier stored on account
+  #                                 bindings ('google', 'uniba-auth', ...)
+  #   authorize(state)  -> AuthorizeStart   the authorize URL plus any per-flow
+  #                                         secrets (PKCE verifier, nonce) to
+  #                                         stash with the state
+  #   verify(params, stash = nil) -> Identity | nil   callback verification,
+  #                                                   using the stashed secrets
+  #
+  # Persona::Oidc::Verifier is the production implementation (code exchange +
+  # JWKS validation); StubProvider is the local stand-in.
+  module Oidc
+    # The verified outcome of an OIDC round-trip: which provider vouched for
+    # the browser, and the stable subject the token was issued for. This
+    # pair becomes an account binding.
+    Identity = Struct.new(:provider, :subject, keyword_init: true)
+
+    # What #authorize returns: where to send the browser, and the per-flow
+    # secrets to stash with the state and hand back to #verify on the
+    # callback. The stub needs no stash; a real code+PKCE flow does.
+    AuthorizeStart = Struct.new(:url, :stash, keyword_init: true)
+
+    # Local / development stand-in for a real provider. Its authorize URL
+    # points at an app-local page, and #verify trusts a subject handed
+    # straight through the callback params — NO cryptographic verification.
+    # It exists so the whole bind / adopt / merge flow can be exercised
+    # before any real IdP is wired up. MUST NOT be deployed to production
+    # (protocol.md P-16).
+    class StubProvider
+      attr_reader :name
+
+      def initialize(name: 'stub', authorize_path: '/auth/oidc/start')
+        @name = name
+        @authorize_path = authorize_path
+      end
+
+      def authorize(state)
+        AuthorizeStart.new(url: "#{@authorize_path}?state=#{CGI.escape(state)}", stash: nil)
+      end
+
+      def verify(params, _stash = nil)
+        subject = params[:sub] || params['sub']
+        return nil if subject.nil? || subject.to_s.empty?
+
+        Identity.new(provider: name, subject: subject)
+      end
+    end
+  end
+end

data/lib/persona/version.rb

@@ -0,0 +1,3 @@
+module Persona
+  VERSION = '0.1.0'.freeze
+end

data/lib/persona.rb

@@ -0,0 +1,147 @@
+require 'securerandom'
+
+require_relative 'persona/version'
+require_relative 'persona/claim_code'
+require_relative 'persona/oidc'
+require_relative 'persona/oidc/verifier'
+require_relative 'persona/oidc/link_store'
+require_relative 'persona/account_link'
+
+# Persona — the app-agnostic core of the "anonymous identity you carry per
+# browser" mechanism. The protocol itself is specified in docs/spec;
+# this gem is one adapter around it.
+#
+# The identity records themselves (agent_uid -> user resolution, guest
+# creation, bindings, recovery codes, merge) live on the consumer's models.
+# This gem owns the *seams* where app-specific concerns plug in:
+#
+#   - on_join                  domain side effects to run when a browser joins
+#   - guest_nickname_generator what a fresh guest is named when none is given
+#   - guest_email_factory      the placeholder identifier stored on a new guest
+#   - oidc_providers           registered identity providers (see oidc.rb)
+#   - account_link_store       the AccountLink storage port (see account_link.rb)
+#   - link_store               the OIDC round-trip store (see oidc/link_store.rb)
+#   - AGENT_ID_HEADER / AGENT_ID_PARAM / NOT_JOINED_CODE  the wire protocol
+#
+# Consumer wiring examples live in examples/ at the repository root.
+module Persona
+  class ConfigurationError < StandardError; end
+
+  # HTTP header and WebSocket query param (for transports that can't set
+  # custom headers) that carry the browser-generated agent_uid. The value
+  # itself is never echoed back in responses — docs/spec P-3 / H-3.
+  AGENT_ID_HEADER = 'X-Agent-Id'.freeze
+  AGENT_ID_PARAM = 'agent_id'.freeze
+
+  # Error code returned when a write is attempted by a visitor who hasn't
+  # opted in yet; the client reacts by starting the join handshake and
+  # retrying. How the code travels (GraphQL extension, HTTP status + body,
+  # HTML fragment) is transport-specific — the name is the protocol.
+  NOT_JOINED_CODE = 'NOT_JOINED'.freeze
+
+  # Default guest-nickname vocabulary: adjective-noun-hex, readable and
+  # collision-resistant enough for a display handle. Consumers can replace
+  # the whole generator via Persona.config.guest_nickname_generator.
+  NICKNAME_ADJECTIVES = %w[
+    azure crimson emerald golden silver violet amber coral indigo jade
+    onyx pearl ruby sapphire topaz cobalt scarlet teal magenta saffron
+  ].freeze
+
+  NICKNAME_NOUNS = %w[
+    otter falcon mantis lynx ibis pangolin heron badger marmot newt
+    raven sparrow tapir gecko axolotl puffin lemur kestrel quokka tern
+  ].freeze
+
+  # Env values treated as "off" for feature flags, mirroring the usual
+  # Rails-style boolean casting so consumers coming from ActiveModel see no
+  # behavior change. Anything else non-empty counts as "on".
+  FALSEY_ENV_VALUES = %w[0 f F false FALSE off OFF].freeze
+
+  # Injection points for the app-specific parts of the persona flow. Every
+  # default is a self-contained generic — the gem has no domain dependencies
+  # until the app overrides a seam.
+  class Config
+    # Called with the freshly-resolved guest user on every join (both the
+    # first join and returning visits). Must be idempotent. Defaults to a
+    # no-op; the app injects its membership side effects here.
+    attr_accessor :on_join
+
+    # Builds the display nickname for a new guest when the caller supplies
+    # none.
+    attr_accessor :guest_nickname_generator
+
+    # Builds the placeholder email/identifier persisted on a new guest user.
+    # It MUST NOT be derived from the agent_uid or the session credential: this
+    # value is exposable (a settings page, a profile view echoes it), so
+    # deriving it would leak the credential back (P-3). The default draws from
+    # independent randomness for exactly this reason.
+    attr_accessor :guest_email_factory
+
+    # Registered OIDC providers by name (see Persona::Oidc for the provider
+    # contract). Empty by default: register providers explicitly, including
+    # the development stub — an unregistered provider can never verify.
+    attr_reader :oidc_providers
+
+    def register_oidc_provider(provider)
+      @oidc_providers[provider.name] = provider
+      provider
+    end
+
+    # Storage port for AccountLink — an object implementing the contract
+    # documented in Persona::AccountLink. No default: consumers that enable
+    # account linking must provide one backed by their own persistence.
+    attr_accessor :account_link_store
+
+    # Storage for the OIDC redirect round-trip, e.g.
+    # Persona::Oidc::LinkStore.new(redis: <client or pool>). No default:
+    # consumers that enable account linking must provide one.
+    attr_accessor :link_store
+
+    def initialize
+      @on_join = ->(_user) {}
+      @guest_nickname_generator = -> { Persona.generate_nickname }
+      @guest_email_factory = -> { "agent-#{SecureRandom.hex(8)}@guest.local" }
+      @oidc_providers = {}
+      @account_link_store = nil
+      @link_store = nil
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Discards all wiring and returns to defaults. Intended for test suites.
+    def reset_config!
+      @config = Config.new
+    end
+
+    def generate_nickname
+      "#{NICKNAME_ADJECTIVES.sample}-#{NICKNAME_NOUNS.sample}-#{SecureRandom.hex(2)}"
+    end
+
+    # Resolves a registered OIDC provider by name; unknown names raise so a
+    # begin/callback for a provider the app never registered fails loudly.
+    def oidc_provider(name)
+      config.oidc_providers.fetch(name) do
+        raise ConfigurationError, "unknown OIDC provider #{name.inspect} — " \
+                                  'register it via Persona.config.register_oidc_provider'
+      end
+    end
+
+    # Account linking (OIDC binding to an external IdP) is opt-in and off by
+    # default — until it is enabled, no /auth/oidc routes or link mutations
+    # do anything. Toggled by the PERSONA_ACCOUNT_LINKING env var.
+    def account_linking_enabled?
+      value = ENV.fetch('PERSONA_ACCOUNT_LINKING', nil)
+      return false if value.nil? || value.empty?
+
+      !FALSEY_ENV_VALUES.include?(value)
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: persona-protocol
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- UNIBA COMMONS Authors
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: 'Seams, OIDC verifier contract, and account-link decision logic for the
+  persona-protocol: start using an app with no login, carry a per-browser persona,
+  and optionally graft it onto a verified account later.'
+email:
+- haruma@uniba.jp
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AUTHORS
+- LICENSE
+- lib/persona.rb
+- lib/persona/account_link.rb
+- lib/persona/claim_code.rb
+- lib/persona/oidc.rb
+- lib/persona/oidc/link_store.rb
+- lib/persona/oidc/verifier.rb
+- lib/persona/version.rb
+homepage: https://github.com/uniba-commons/persona-protocol
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: 'Portable anonymous identity: browser-carried personas with optional OIDC
+  account linking'
+test_files: []