Project

pkce

0.0
The project is in a healthy, maintained state
pkcebkuhlmann/pkceHomepageDocumentationSource CodeBug Tracker
An OAuth Proof Key for Code Exchange (PKCE) challenge and code verifier.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Popularity
Downloads
45,952
Stars
3
Forks
0
Watchers
3
 Releases
Current version
2.8.0
Total releases
20
First release
2022-06-25
Latest release
2024-11-09
 Development
Primary Language
Ruby
Licenses
Hippocratic-2.1
Average date of last 50 commits
2024-05-23
Reverse Dependencies
0

 Dependencies

Runtime

dry-monads
~> 1.6
 Project Readme

Proof Key for Code Exchange (PKCE)

Proof Key for Code Exchange (PKCE) is an authorization code flow extension to OAuth which is necessary for mobile authentication but works well for web flows because the added security is transparent to the user. Specifically, PKCE prevents the following types of attacks:

  • Authorization code interception

  • Authorization code injection

This gem is an implementation of the RFC 7636 specification so you can leverage PKCE in your own code.

Table of Contents
  • Features
  • Requirements
  • Setup
  • Usage
  • Development
    • Architecture
  • Tests
  • License
  • Security
  • Code of Conduct
  • Contributions
  • Developer Certificate of Origin
  • Versions
  • Community
  • Credits

Features

  • Implements the RFC 7636 specification.

  • Provides a simple object API for obtaining a challenge and verify code.

  • Provides max length security by default.

  • Answers a monad result.

Requirements

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install pkce --trust-policy HighSecurity

To install without security, run:

gem install pkce

You can also add the gem directly to your project:

bundle add pkce

Once the gem is installed, you only need to require it:

require "pkce"

Usage

The object API is simple to work with as you only need to interact with the PKCE constant. Example:

code = PKCE.call.success
code.challenge  # e2tGChTfGON-C55i0yu13-urIgDFuMCmo73F7TZmoiw
code.verify     # hYnx2WTJo7Bgu1-GqPUIYtRkb2W7pRBawkmdDi3omPdramb27Fp4rps_w6ozns-gbVCKFC2-Kno4P_b1H3FuxnlYIOd9Bo5yoTXq_xEHDJaB_fOfn2NaiCtcWQ8Bs91I

You can also pass in a custom length (default is maximum):

code = PKCE.call(length: 35).success
code.challenge  # R1b1Ka3jmrLKvQ7xW5QmP5MsCSEWtdoA2lo3r-SZDfg
code.verify     # ucKkqwoMzc9cyPcSGMbuVf3ivr4sep2mq15hGN9sVzl4X7g

In case of a failure, you’ll get a proper error message:

PKCE.call(length: 100).failure  # Invalid PKCE verifier length: 100. Must be between 32..96.

Due to the fact that PKCE answers back a monad, you have all of the power of pattern matching at your fingertips as well:

include Dry::Monads[:result]

case PKCE.call
  in Success(code) then puts code.inspect
  in Failure(message) then puts message
end

Finally, since the code answered back is a Data object that you can easily test and interact with:

PKCE.call.success
#<data PKCE::Code challenge="ROMnfvHt04xhM80WB2PyPK67GGrG35UdFEf0DEBkes0", verify="cUq917cDIROAUkew-OjIdfIz1OYyv-ERt9NnSdzlxz4XSYzdbRycVuRDD2SBIDBiKnXUamxvpxNRsUMBQ1PvBdtziGs_oYe98MDWmM8J2_NJQBVg2kP-B2OqBdMp00qh">

Development

To contribute, run:

git clone https://github.com/bkuhlmann/pkce
cd pkce
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Architecture

The following documents the workflow used to process and build authorization codes.

Sequence Diagram

Tests

To test, run:

bin/rake

Credits