Merge pull request #1 from firebase/main

up

Author: tekintian

.gitattributes

@@ -5,4 +5,4 @@
 /.gitignore export-ignore
 /.travis.yml export-ignore
 /phpunit.xml.dist export-ignore
-/run-tests.sh export-ignore
+/.github export-ignore

.github/actions/entrypoint.sh

@@ -0,0 +1,21 @@
+#!/bin/sh -l
+
+apt-get update && \
+apt-get install -y --no-install-recommends \
+    git \
+    zip \
+    curl \
+    ca-certificates \
+    unzip \
+    wget
+
+curl --silent --show-error https://getcomposer.org/installer | php
+php composer.phar self-update
+
+echo "---Installing dependencies ---"
+
+# Add compatiblity for libsodium with older versions of PHP
+php composer.phar require --dev --with-dependencies paragonie/sodium_compat
+
+echo "---Running unit tests ---"
+vendor/bin/phpunit

.github/workflows/tests.yml

@@ -0,0 +1,57 @@
+name: Test Suite
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        php: [ "8.0", "8.1"]
+    name: PHP ${{matrix.php }} Unit Test
+    steps:
+      - uses: actions/checkout@v2
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+      - name: Install Dependencies
+        uses: nick-invision/retry@v1
+        with:
+          timeout_minutes: 10
+          max_attempts: 3
+          command: composer install
+      - name: Run Script
+        run: vendor/bin/phpunit
+
+  style:
+    runs-on: ubuntu-latest
+    name: PHP Style Check
+    steps:
+      - uses: actions/checkout@v2
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.0"
+      - name: Run Script
+        run: |
+          composer require friendsofphp/php-cs-fixer
+          vendor/bin/php-cs-fixer fix --diff --dry-run .
+          vendor/bin/php-cs-fixer fix --rules=native_function_invocation --allow-risky=yes --diff src
+
+  staticanalysis:
+    runs-on: ubuntu-latest
+    name: PHPStan Static Analysis
+    steps:
+    - uses: actions/checkout@v2
+    - name: Install PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: '8.0'
+    - name: Run Script
+      run: |
+        composer global require phpstan/phpstan
+        ~/.composer/vendor/bin/phpstan analyse

.gitignore

@@ -3,3 +3,4 @@ phpunit.phar
 phpunit.phar.asc
 composer.phar
 composer.lock
+.phpunit.result.cache

.travis.yml

@@ -13,7 +13,7 @@ modification, are permitted provided that the following conditions are met:
       disclaimer in the documentation and/or other materials provided
       with the distribution.
 
-    * Neither the name of Neuman Vong nor the names of other
+    * Neither the name of the copyright holder nor the names of other
       contributors may be used to endorse or promote products derived
       from this software without specific prior written permission.
 

LICENSE

@@ -1,4 +1,4 @@
-[![Build Status](https://travis-ci.org/firebase/php-jwt.png?branch=master)](https://travis-ci.org/firebase/php-jwt)
+![Build Status](https://github.com/firebase/php-jwt/actions/workflows/tests.yml/badge.svg)
 [![Latest Stable Version](https://poser.pugx.org/firebase/php-jwt/v/stable)](https://packagist.org/packages/firebase/php-jwt)
 [![Total Downloads](https://poser.pugx.org/firebase/php-jwt/downloads)](https://packagist.org/packages/firebase/php-jwt)
 [![License](https://poser.pugx.org/firebase/php-jwt/license)](https://packagist.org/packages/firebase/php-jwt)
@@ -16,14 +16,21 @@ Use composer to manage your dependencies and download PHP-JWT:
 composer require firebase/php-jwt
 ```
 
+Optionally, install the `paragonie/sodium_compat` package from composer if your
+php is < 7.2 or does not have libsodium installed:
+
+```bash
+composer require paragonie/sodium_compat
+```
+
 Example
 -------
 ```php
-<?php
-use \Firebase\JWT\JWT;
+use Firebase\JWT\JWT;
+use Firebase\JWT\Key;
 
 $key = "example_key";
-$token = array(
+$payload = array(
     "iss" => "http://example.org",
     "aud" => "http://example.com",
     "iat" => 1356999524,
@@ -36,8 +43,8 @@ $token = array(
  * https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40
  * for a list of spec-compliant algorithms.
  */
-$jwt = JWT::encode($token, $key);
-$decoded = JWT::decode($jwt, $key, array('HS256'));
+$jwt = JWT::encode($payload, $key, 'HS256');
+$decoded = JWT::decode($jwt, new Key($key, 'HS256'));
 
 print_r($decoded);
 
@@ -56,9 +63,7 @@ $decoded_array = (array) $decoded;
  * Source: http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#nbfDef
  */
 JWT::$leeway = 60; // $leeway in seconds
-$decoded = JWT::decode($jwt, $key, array('HS256'));
-
-?>
+$decoded = JWT::decode($jwt, new Key($key, 'HS256'));
 ```
 Example with RS256 (openssl)
 
@@ -75,8 +80,8 @@ openssl rsa -in id_rsa -pubout > id_rsa_pub.key
 
 ----------------------------
 ```php
-<?php
-use \Firebase\JWT\JWT;
+use Firebase\JWT\JWT;
+use Firebase\JWT\Key;
 
 $privateKey = <<<EOD
 -----BEGIN RSA PRIVATE KEY-----
@@ -120,17 +125,17 @@ ZwIDAQAB
 -----END PUBLIC KEY-----
 EOD;
 
-$token = array(
+$payload = array(
     "iss" => "example.org",
     "aud" => "example.com",
     "iat" => 1356999524,
     "nbf" => 1357000000
 );
 
-$jwt = JWT::encode($token, $privateKey, 'RS256');
+$jwt = JWT::encode($payload, $privateKey, 'RS256');
 echo "Encode:\n" . print_r($jwt, true) . "\n";
 
-$decoded = JWT::decode($jwt, $publicKey, array('RS256'));
+$decoded = JWT::decode($jwt, new Key($publicKey, 'RS256'));
 
 /*
  NOTE: This will now be an object instead of an associative array. To get
@@ -139,12 +144,120 @@ $decoded = JWT::decode($jwt, $publicKey, array('RS256'));
 
 $decoded_array = (array) $decoded;
 echo "Decode:\n" . print_r($decoded_array, true) . "\n";
-?>
+```
+
+Example with a passphrase
+-------------------------
+
+```php
+use Firebase\JWT\JWT;
+use Firebase\JWT\Key;
+
+// Your passphrase
+$passphrase = '[YOUR_PASSPHRASE]';
+
+// Your private key file with passphrase
+// Can be generated with "ssh-keygen -t rsa -m pem"
+$privateKeyFile = '/path/to/key-with-passphrase.pem';
+
+// Create a private key of type "resource"
+$privateKey = openssl_pkey_get_private(
+    file_get_contents($privateKeyFile),
+    $passphrase
+);
+
+$payload = array(
+    "iss" => "example.org",
+    "aud" => "example.com",
+    "iat" => 1356999524,
+    "nbf" => 1357000000
+);
+
+$jwt = JWT::encode($payload, $privateKey, 'RS256');
+echo "Encode:\n" . print_r($jwt, true) . "\n";
+
+// Get public key from the private key, or pull from from a file.
+$publicKey = openssl_pkey_get_details($privateKey)['key'];
+
+$decoded = JWT::decode($jwt, new Key($publicKey, 'RS256'));
+echo "Decode:\n" . print_r((array) $decoded, true) . "\n";
+```
+
+Example with EdDSA (libsodium and Ed25519 signature)
+----------------------------
+```php
+use Firebase\JWT\JWT;
+use Firebase\JWT\Key;
+
+// Public and private keys are expected to be Base64 encoded. The last
+// non-empty line is used so that keys can be generated with
+// sodium_crypto_sign_keypair(). The secret keys generated by other tools may
+// need to be adjusted to match the input expected by libsodium.
+
+$keyPair = sodium_crypto_sign_keypair();
+
+$privateKey = base64_encode(sodium_crypto_sign_secretkey($keyPair));
+
+$publicKey = base64_encode(sodium_crypto_sign_publickey($keyPair));
+
+$payload = array(
+    "iss" => "example.org",
+    "aud" => "example.com",
+    "iat" => 1356999524,
+    "nbf" => 1357000000
+);
+
+$jwt = JWT::encode($payload, $privateKey, 'EdDSA');
+echo "Encode:\n" . print_r($jwt, true) . "\n";
+
+$decoded = JWT::decode($jwt, new Key($publicKey, 'EdDSA'));
+echo "Decode:\n" . print_r((array) $decoded, true) . "\n";
+````
+
+Using JWKs
+----------
+
+```php
+use Firebase\JWT\JWK;
+use Firebase\JWT\JWT;
+
+// Set of keys. The "keys" key is required. For example, the JSON response to
+// this endpoint: https://www.gstatic.com/iap/verify/public_key-jwk
+$jwks = ['keys' => []];
+
+// JWK::parseKeySet($jwks) returns an associative array of **kid** to Firebase\JWT\Key
+// objects. Pass this as the second parameter to JWT::decode.
+JWT::decode($payload, JWK::parseKeySet($jwks));
+```
+
+Miscellaneous
+-------------
+
+#### Casting to array
+
+The return value of `JWT::decode` is the generic PHP object `stdClass`. If you'd like to handle with arrays
+instead, you can do the following:
+
+```php
+// return type is stdClass
+$decoded = JWT::decode($payload, $keys);
+
+// cast to array
+$decoded = json_decode(json_encode($decoded), true);
 ```
 
 Changelog
 ---------
 
+#### 6.0.0 / 2022-01-24
+
+ - **Backwards-Compatibility Breaking Changes**: See the [Release Notes](https://github.com/firebase/php-jwt/releases/tag/v6.0.0) for more information.
+ - New Key object to prevent key/algorithm type confusion (#365)
+ - Add JWK support (#273)
+ - Add ES256 support (#256)
+ - Add ES384 support (#324)
+ - Add Ed25519 support (#343)
+
 #### 5.0.0 / 2017-06-26
 - Support RS384 and RS512.
   See [#117](https://github.com/firebase/php-jwt/pull/117). Thanks [@joostfaassen](https://github.com/joostfaassen)!

README.md

@@ -2,6 +2,10 @@
     "name": "firebase/php-jwt",
     "description": "A simple library to encode and decode JSON Web Tokens (JWT) in PHP. Should conform to the current spec.",
     "homepage": "https://github.com/firebase/php-jwt",
+    "keywords": [
+        "php",
+        "jwt"
+    ],
     "authors": [
         {
             "name": "Neuman Vong",
@@ -16,14 +20,17 @@
     ],
     "license": "BSD-3-Clause",
     "require": {
-        "php": ">=5.3.0"
+        "php": "^8.0"
+    },
+    "suggest": {
+        "paragonie/sodium_compat": "Support EdDSA (Ed25519) signatures when libsodium is not present"
     },
     "autoload": {
         "psr-4": {
             "Firebase\\JWT\\": "src"
         }
     },
     "require-dev": {
-        "phpunit/phpunit": " 4.8.35"
+        "phpunit/phpunit": "^9.5"
     }
 }

composer.json

@@ -0,0 +1,5 @@
+parameters:
+    level: 7
+    paths:
+    - src
+    treatPhpDocTypesAsCertain: false

phpstan.neon.dist

@@ -8,7 +8,6 @@
          convertWarningsToExceptions="true"
          processIsolation="false"
          stopOnFailure="false"
-         syntaxCheck="false"
          bootstrap="tests/bootstrap.php"
 >
     <testsuites>