Proper upgrade docs to 3.0

[ksmithut]

So I see that there is a revised API. I've been looking through the docs to find replacement APIs to the functions I was using, but am having trouble finding them.

Specifically, here's what I'm looking for:

• Typescript types don't seem to be importing. Could be a configuration issue, but only noticed it after the upgrade.
• JWK.asKey() I used this because I would have keys/algorithms stored as environment variables, and use this to import them as valid JWKs. Maybe I was using this wrong, but would love to learn about alternatives
• new JWKS.KeyStore(allKeys) I used this to gather all of the keys and then be able to expose the public versions of them in a /.well-known/jwks.json endpoint so clients could validate the JWTs that I sign without having to send the token anywhere. There is a method to import jwks from a remove endpoint, but I needed to use the store to be the source.

Overall, I love the promise based API, the more streamlined way to generate key/pairs and secrets. Just want to make sure I'm not missing something, or if there's a better way to be doing what I'm trying to do.

[panva]

@ksmithut not all v2.x apis are carried over, some of them for now, some of them will never be. One of the reasons why i'm declaring v2.x as a supported major is that i understand not everyone will be able to upgrade to v3.x. So, if you can't, don't. Stay on 2.x, its still supported.

Typescript types don't seem to be importing.

How is this manifesting?

JWK.asKey()

parseJWK - Converts a JWK to a runtime-specific key representation.

new JWKS.KeyStore

There is no keystore abstraction in v3.x, there will be more of these eventually - for local JWKS verification, or decryption.

I used this to gather all of the keys and then be able to expose the public versions of them in a /.well-known/jwks.json endpoint so clients could validate the JWTs that I sign without having to send the token anywhere.

Now i ask, is this a critical piece of functionality? Composing a public key JWKS endpoint response is rather trivial, as it's just cherry-picking JWK properties, isn't it?

[ksmithut]

Typescript types don't seem to be importing.

How is this manifesting?

I was mistaken. I was importing jose instead of one of the submodules.

parseJWK - Converts a JWK to a runtime-specific key representation.

Right. Before, if I had a String or Buffer representation of the private key and which algorithm it came from, I could create a Key out of it. But I suppose I could use the JWK version of the private key. That's probably better anyway.

Now i ask, is this a critical piece of functionality? Composing a public key JWKS endpoint response is rather trivial, as it's just cherry-picking JWK properties, isn't it?

It was a quality of life thing. It was nice to use the keystore abstraction for verifying tokens as well as exposing that endpoint, but it is trivial to accomplish what I need to.

I think this new API is moving in a great direction, I was just expressing some concerns that the API removals weren't completely laid out. But thinking of it as a completely new library has helped me come to grips with things. Thanks for all the great work!

[panva]

The respective runtimes offer a way to import a pem/der encoded key natively, hence there's no need for an API like so in this module. Only for JWK format because node doesn't have that particular affordance yet.

Using crypto module's crypto.createPublicKey, crypto.createPrivateKey you can "import" private keys as key objects to pass to v3.x as keys in node runtime. Same way as you can use SubtleCrypto.importKey in the browser and use this module the same there.