hershel-theodore-layton / simple-web-token
An implementation of the Simple Web Token specification.
Installs: 197
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Language:Hack
Requires
- hhvm: ^4.102
Requires (Dev)
- facebook/fbexpect: ^2.8
- hhvm/hacktest: ^2.3
- hhvm/hhast: ^4.102
- hhvm/hhvm-autoload: ^3.2
This package is auto-updated.
Last update: 2024-08-26 18:01:56 UTC
README
An implementation of the Simple Web Token specification.
Usage
// This example assumes you have some `$your_key_store`, // which maps key names to keys. $serialized = SimpleWebToken\sign( vec[ tuple('com.example.user_id', '4'), tuple(SimpleWebToken\Token::EXPIRES_ON, (string)(\time() + 300)), tuple('com.example.secret_key_used', '#1') ], SimpleWebToken\this_is_the_secret_key($your_key_store->load('#1')), ); $token = SimpleWebToken\parse($serialized); $key = $your_key_store->loadKey( $token->getUniqueKeys() |> idx($$, 'com.example.secret_key_used', 'default') ); $state = $token->validate($key, \time()); switch ($state) { case SimpleWebToken\Validity::VALID: case SimpleWebToken\Validity::EXPIRED: case SimpleWebToken\Validity::INVALID: } // Or the shorthand $token->isOkay($key, \time()); // This returns `true` for `::VALID` only.
Performance vs. purity
The native functions \hash()
and \hash_hmac()
are not pure in hhvm version 4.172
and below (the most recent version released to date). \hash()
has been made pure
in October 2023. This repository includes SimpleWebToken\sha256_pure()
as
a replacement for \hash()
, which is pure.
When running in repo auth mode, the jit will kick in and make the performance of
this polyfill about 20% of the native \hash()
function. The performance deficit
is greater before the jit has optimized it, especially when not running in repo
auth mode. If you have a very high traffic to your site and CPU cycles are scarce,
you will definitely feel the hit of the unoptimized bytecodes shuffling bytes
around. You may opt to use SimpleWebToken\sha256_native()
to regain all
performance, at the cost of requiring [defaults]
.
If you are running a build of hhvm@next at or after this commit from October 2023. You can pass a native wrapper with a pure context.
License
This code is licensed under the MIT License, but note, this code implements the Simple Web Token specification.
The Simple Web Token specification version 0.9.5.1, which can be found here, is licensed under the Open Web Foundation Agreement Version 0.9. This license is permissive, as long as you do not take non-defensive patent legal action against implementers of the specification. This also applies to this implementation (and implementer).
Acknowledgments
The Simple Web Token specification has been authored by:
- Dick Hardt (dick.hardt@microsoft.com), Editor
- Yaron Goland (yarong@microsoft.com)
The implementation of SHA-256 in Hack was heavily based on amosnier's C implementation.
This Hack implementation can be found here.
The implementation in C can be found here.
The C code is licensed under The Unlicense
or BSD-0-Clause
at your option.
Both licenses are public domain equivalent and do not require attribution.
Thank you Amosnier, porting it was a pleasant experience.
I believe to have met the requirements imposed on me by the third-party licenses. If you spot a violation of any third-party licenses in under this Github namespace, you may notify me by filing a Github Issue on the affected projects.