hanzoai/jose
2
0
Fork 0
mirror of https://github.com/hanzoai/jose.git synced 2026-09-24 17:00:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(types): trim published declaration comments

Browse Source 
Signed-off-by: Filip Skokan <[email protected]>
This commit is contained in:
Filip Skokan
2026-07-30 00:37:15 +02:00
parent 882c770fe8
commit d162246556
51 changed files with 629 additions and 612 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/jwe/compact/decrypt/interfaces/CompactDecryptGetKey.md
+1 -3
View File
@@ -16,9 +16,7 @@ verified at the time of this function call.
▸ **CompactDecryptGetKey**(`protectedHeader`, `token`): [`JWK`](../../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../../types/interfaces/KeyObject.md) \| `KeyType` \| [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`JWK`](../../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../../types/interfaces/KeyObject.md) \| `KeyType`\>
Dynamic key resolution function. No token components have been verified at the time of this
function call.
If a suitable key for the token cannot be matched, throw an error instead.
function call. If a suitable key for the token cannot be matched, throw an error instead.
## Parameters
docs/jwe/compact/encrypt/classes/CompactEncrypt.md
+3 -4
View File
@@ -112,10 +112,9 @@ You should not use this method. It is only really intended for test and vector
▸ **setKeyManagementParameters**(`parameters`): `this`
Sets the JWE Key Management parameters to be used when encrypting.
(ECDH-ES) Use of this method is needed for ECDH based algorithms to set the "apu" (Agreement
PartyUInfo) or "apv" (Agreement PartyVInfo) parameters.
Sets the JWE Key Management parameters to be used when encrypting. For ECDH based algorithms,
use this method to set the "apu" (Agreement PartyUInfo) or "apv" (Agreement PartyVInfo)
parameters.
#### Parameters
docs/jwe/flattened/decrypt/interfaces/FlattenedDecryptGetKey.md
+1 -3
View File
@@ -16,9 +16,7 @@ verified at the time of this function call.
▸ **FlattenedDecryptGetKey**(`protectedHeader`, `token`): [`JWK`](../../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../../types/interfaces/KeyObject.md) \| `KeyType` \| [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`JWK`](../../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../../types/interfaces/KeyObject.md) \| `KeyType`\>
Dynamic key resolution function. No token components have been verified at the time of this
function call.
If a suitable key for the token cannot be matched, throw an error instead.
function call. If a suitable key for the token cannot be matched, throw an error instead.
## Parameters
docs/jwe/flattened/encrypt/classes/FlattenedEncrypt.md
+3 -4
View File
@@ -131,10 +131,9 @@ You should not use this method. It is only really intended for test and vector
▸ **setKeyManagementParameters**(`parameters`): `this`
Sets the JWE Key Management parameters to be used when encrypting.
(ECDH-ES) Use of this method is needed for ECDH based algorithms to set the "apu" (Agreement
PartyUInfo) or "apv" (Agreement PartyVInfo) parameters.
Sets the JWE Key Management parameters to be used when encrypting. For ECDH based algorithms,
use this method to set the "apu" (Agreement PartyUInfo) or "apv" (Agreement PartyVInfo)
parameters.
#### Parameters
docs/jwe/general/decrypt/interfaces/GeneralDecryptGetKey.md
+1 -3
View File
@@ -16,9 +16,7 @@ verified at the time of this function call.
▸ **GeneralDecryptGetKey**(`protectedHeader`, `token`): [`JWK`](../../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../../types/interfaces/KeyObject.md) \| `KeyType` \| [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`JWK`](../../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../../types/interfaces/KeyObject.md) \| `KeyType`\>
Dynamic key resolution function. No token components have been verified at the time of this
function call.
If a suitable key for the token cannot be matched, throw an error instead.
function call. If a suitable key for the token cannot be matched, throw an error instead.
## Parameters
docs/jwe/general/encrypt/interfaces/Recipient.md
+3 -4
View File
@@ -58,10 +58,9 @@ A shorthand for calling [encrypt()](../classes/GeneralEncrypt.md#encrypt) on the
▸ **setKeyManagementParameters**(`parameters`): `Recipient`
Sets the JWE Key Management parameters to be used when encrypting.
(ECDH-ES) Use of this method is needed for ECDH based algorithms to set the "apu" (Agreement
PartyUInfo) or "apv" (Agreement PartyVInfo) parameters.
Sets the JWE Key Management parameters to be used when encrypting. For ECDH based algorithms,
use this method to set the "apu" (Agreement PartyUInfo) or "apv" (Agreement PartyVInfo)
parameters.
#### Parameters
docs/jwks/local/functions/createLocalJWKSet.md
+4 -1
View File
@@ -7,7 +7,10 @@ Support from the community to continue maintaining and improving this module is
▸ **createLocalJWKSet**(`jwks`): [`LocalJWKSet`](../interfaces/LocalJWKSet.md)
Returns a function that resolves a JWS JOSE Header to a public key object from a locally stored,
or otherwise available, JSON Web Key Set.
or otherwise available, JSON Web Key Set. Selection respects the header's "alg" (Algorithm) and
"kid" (Key ID) as well as the JWK's "use" (Public Key Use) and "key_ops" (Key Operations).
Exactly one key must match; if multiple keys match, the thrown `JWKSMultipleMatchingKeys` can be
iterated.
It uses the "alg" (JWS Algorithm) Header Parameter to determine the right JWK "kty" (Key Type),
then proceeds to match the JWK "kid" (Key ID) with one found in the JWS Header Parameters (if
docs/jwks/remote/functions/createRemoteJWKSet.md
+4 -1
View File
@@ -9,7 +9,10 @@ Support from the community to continue maintaining and improving this module is
Returns a function that resolves a JWS JOSE Header to a public key object downloaded from a
remote endpoint returning a JSON Web Key Set, that is, for example, an OAuth 2.0 or OIDC
jwks_uri. The JSON Web Key Set is fetched when no key matches the selection process but only as
frequently as the `cooldownDuration` option allows to prevent abuse.
frequently as the `cooldownDuration` option allows to prevent abuse. Selection respects the
header's "alg" (Algorithm) and "kid" (Key ID) as well as the JWK's "use" (Public Key Use) and
"key_ops" (Key Operations). Exactly one key must match; if multiple keys match, the thrown
`JWKSMultipleMatchingKeys` can be iterated.
It uses the "alg" (JWS Algorithm) Header Parameter to determine the right JWK "kty" (Key Type),
then proceeds to match the JWK "kid" (Key ID) with one found in the JWS Header Parameters (if
docs/jwks/remote/variables/jwksCache.md
+3 -2
View File
@@ -12,8 +12,9 @@ Support from the community to continue maintaining and improving this module is
> code.
This option is intended for cloud computing runtimes that cannot keep an in memory cache between
their code's invocations. Use in runtimes where an in memory cache between requests is available
is not desirable.
their code's invocations. The supplied writable object seeds the resolver's cache and is updated
with `jwks` and `uat` after a successful fetch; persist it whenever `uat` changes. Using this in
runtimes that can keep an in-memory cache between requests is not desirable.
When passed to [createRemoteJWKSet](../functions/createRemoteJWKSet.md) this allows the passed in
object to:
docs/jws/compact/verify/interfaces/CompactVerifyGetKey.md
+1 -3
View File
@@ -20,9 +20,7 @@ verified at the time of this function call.
▸ **CompactVerifyGetKey**(`protectedHeader`, `token`): [`JWK`](../../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../../types/interfaces/KeyObject.md) \| `KeyType` \| [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`JWK`](../../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../../types/interfaces/KeyObject.md) \| `KeyType`\>
Dynamic key resolution function. No token components have been verified at the time of this
function call.
If a suitable key for the token cannot be matched, throw an error instead.
function call. If a suitable key for the token cannot be matched, throw an error instead.
## Parameters
docs/jws/flattened/verify/interfaces/FlattenedVerifyGetKey.md
+1 -3
View File
@@ -20,9 +20,7 @@ verified at the time of this function call.
▸ **FlattenedVerifyGetKey**(`protectedHeader`, `token`): [`JWK`](../../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../../types/interfaces/KeyObject.md) \| `KeyType` \| [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`JWK`](../../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../../types/interfaces/KeyObject.md) \| `KeyType`\>
Dynamic key resolution function. No token components have been verified at the time of this
function call.
If a suitable key for the token cannot be matched, throw an error instead.
function call. If a suitable key for the token cannot be matched, throw an error instead.
## Parameters
docs/jws/general/verify/interfaces/GeneralVerifyGetKey.md
+1 -3
View File
@@ -20,9 +20,7 @@ verified at the time of this function call.
▸ **GeneralVerifyGetKey**(`protectedHeader`, `token`): [`JWK`](../../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../../types/interfaces/KeyObject.md) \| `KeyType` \| [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`JWK`](../../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../../types/interfaces/KeyObject.md) \| `KeyType`\>
Dynamic key resolution function. No token components have been verified at the time of this
function call.
If a suitable key for the token cannot be matched, throw an error instead.
function call. If a suitable key for the token cannot be matched, throw an error instead.
## Parameters
docs/jwt/decrypt/interfaces/JWTDecryptGetKey.md
+1 -3
View File
@@ -16,9 +16,7 @@ the time of this function call.
▸ **JWTDecryptGetKey**(`protectedHeader`, `token`): [`JWK`](../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../types/interfaces/KeyObject.md) \| `KeyType` \| [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`JWK`](../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../types/interfaces/KeyObject.md) \| `KeyType`\>
Dynamic key resolution function. No token components have been verified at the time of this
function call.
If a suitable key for the token cannot be matched, throw an error instead.
function call. If a suitable key for the token cannot be matched, throw an error instead.
## Parameters
docs/jwt/decrypt/interfaces/JWTDecryptOptions.md
+25 -43
View File
@@ -12,9 +12,8 @@ Combination of JWE Decryption options and JWT Claims Set verification options.
• `optional` **audience?**: `string` \| `string`[]
Expected JWT "aud" (Audience) Claim value(s).
This option makes the JWT "aud" (Audience) Claim presence required.
Expected JWT "aud" (Audience) Claim value(s). This option makes the JWT "aud" (Audience) Claim
presence required.
***
@@ -22,13 +21,10 @@ This option makes the JWT "aud" (Audience) Claim presence required.
• `optional` **clockTolerance?**: `string` \| `number`
Clock skew tolerance
- In seconds when number (e.g. 5)
- Resolved into a number of seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
Used when validating the JWT "nbf" (Not Before) and "exp" (Expiration Time) claims, and when
validating the "iat" (Issued At) claim if the [`maxTokenAge` option](../../../types/interfaces/JWTClaimVerificationOptions.md#maxtokenage) is set.
Clock skew tolerance in seconds when a number (e.g. 5), or resolved into seconds when a string
(e.g. "5 seconds", "10 minutes", "2 hours"). Used when validating the JWT "nbf" (Not Before)
and "exp" (Expiration Time) claims, and when validating the "iat" (Issued At) claim if the
[`maxTokenAge` option](../../../types/interfaces/JWTClaimVerificationOptions.md#maxtokenage) is set.
***
@@ -47,20 +43,15 @@ A list of accepted JWE "enc" (Encryption Algorithm) Header Parameter values. By
An object with keys representing recognized "crit" (Critical) Header Parameter names. The value
for those is either `true` or `false`. `true` when the Header Parameter MUST be integrity
protected, `false` when it's irrelevant.
protected, `false` when it's irrelevant. The JWS extension Header Parameter `b64` is always
recognized and processed properly; no other registered Header Parameters currently receive this
built-in treatment.
This makes the "Extension Header Parameter "..." is not recognized" error go away.
Use this when a given JWS/JWT/JWE profile requires the use of proprietary non-registered "crit"
(Critical) Header Parameters. This will only make sure the Header Parameter is syntactically
correct when provided and that it is optionally integrity protected. It will not process the
Header Parameter in any way or reject the operation if it is missing. You MUST still verify the
Header Parameter was present and process it according to the profile's validation steps after
the operation succeeds.
The JWS extension Header Parameter `b64` is always recognized and processed properly. No other
registered Header Parameters that need this kind of default built-in treatment are currently
available.
> [!WARNING]\
> This only checks that the Header Parameter is syntactically correct when provided and,
> optionally, integrity protected. It does not process the Header Parameter or reject the
> operation when it is missing. You MUST still verify its presence and process it according to
> the profile's validation steps after the operation succeeds.
#### Index Signature
@@ -80,9 +71,8 @@ Date to use when comparing NumericDate claims, defaults to `new Date()`.
• `optional` **issuer?**: `string` \| `string`[]
Expected JWT "iss" (Issuer) Claim value(s).
This option makes the JWT "iss" (Issuer) Claim presence required.
Expected JWT "iss" (Issuer) Claim value(s). This option makes the JWT "iss" (Issuer) Claim
presence required.
***
@@ -102,11 +92,8 @@ all PBES2 Key Management Algorithms, these need to be explicitly allowed using t
Maximum allowed size (in bytes) of the decompressed plaintext when the JWE `"zip"` (Compression
Algorithm) Header Parameter is present. By default this value is set to 250000 (250 KB). The
value must be `0`, a positive safe integer, or `Infinity`.
Set to `0` to reject all compressed JWEs during decryption.
Set to `Infinity` to disable the decompressed size limit.
value must be `0`, a positive safe integer, or `Infinity`. Set it to `0` to reject all
compressed JWEs during decryption or to `Infinity` to disable the decompressed size limit.
***
@@ -124,12 +111,9 @@ this value is set to 10000.
• `optional` **maxTokenAge?**: `string` \| `number`
Maximum time elapsed (in seconds) from the JWT "iat" (Issued At) Claim value.
- In seconds when number (e.g. 5)
- Resolved into a number of seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
This option makes the JWT "iat" (Issued At) Claim presence required.
Maximum time elapsed from the JWT "iat" (Issued At) Claim value, in seconds when a number (e.g.
5), or resolved into seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours"). This
option makes the JWT "iat" (Issued At) Claim presence required.
***
@@ -150,9 +134,8 @@ present.
• `optional` **subject?**: `string`
Expected JWT "sub" (Subject) Claim value.
This option makes the JWT "sub" (Subject) Claim presence required.
Expected JWT "sub" (Subject) Claim value. This option makes the JWT "sub" (Subject) Claim
presence required.
***
@@ -160,6 +143,5 @@ This option makes the JWT "sub" (Subject) Claim presence required.
• `optional` **typ?**: `string`
Expected JWT "typ" (Type) Header Parameter value.
This option makes the JWT "typ" (Type) Header Parameter presence required.
Expected JWT "typ" (Type) Header Parameter value. This option makes the JWT "typ" (Type) Header
Parameter presence required.
docs/jwt/encrypt/classes/EncryptJWT.md
+28 -47
View File
@@ -157,25 +157,19 @@ You should not use this method. It is only really intended for test and vector
▸ **setExpirationTime**(`input`): `this`
Set the "exp" (Expiration Time) Claim.
- If a `number` is passed as an argument it is used as the claim directly.
- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
claim.
- If a `string` is passed as an argument it is resolved to a time span, and then added to the
current unix timestamp and used as the claim.
Set the "exp" (Expiration Time) Claim. A `number` is used directly, a `Date` is converted to a
Unix timestamp, and a `string` is parsed as a time span relative to the current Unix timestamp.
String units may be seconds, minutes, hours, days, weeks, or years; months are unsupported and
a year is 365.25 days. A leading `-` or trailing `"ago"` subtracts the time span.
Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
day".
Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
alias for a year.
Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
"mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
"year", "years", "yr", "yrs", and "y".
If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
subtracted from the current unix timestamp. A "from now" suffix can also be used for
readability when adding to the current unix timestamp.
A "from now" suffix can be used for readability when adding to the current Unix timestamp.
#### Parameters
@@ -217,26 +211,20 @@ You should not use this method. It is only really intended for test and vector
▸ **setIssuedAt**(`input?`): `this`
Set the "iat" (Issued At) Claim.
- If no argument is used the current unix timestamp is used as the claim.
- If a `number` is passed as an argument it is used as the claim directly.
- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
claim.
- If a `string` is passed as an argument it is resolved to a time span, and then added to the
current unix timestamp and used as the claim.
Set the "iat" (Issued At) Claim. With no argument the current Unix timestamp is used. A
`number` is used directly, a `Date` is converted to a Unix timestamp, and a `string` is parsed
as a time span relative to the current Unix timestamp. String units may be seconds, minutes,
hours, days, weeks, or years; months are unsupported and a year is 365.25 days. A leading `-`
or trailing `"ago"` subtracts the time span.
Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
day".
Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
alias for a year.
Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
"mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
"year", "years", "yr", "yrs", and "y".
If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
subtracted from the current unix timestamp. A "from now" suffix can also be used for
readability when adding to the current unix timestamp.
A "from now" suffix can be used for readability when adding to the current Unix timestamp.
#### Parameters
@@ -290,10 +278,9 @@ Set the "jti" (JWT ID) Claim.
▸ **setKeyManagementParameters**(`parameters`): `this`
Sets the JWE Key Management parameters to be used when encrypting.
(ECDH-ES) Use of this method is needed for ECDH based algorithms to set the "apu" (Agreement
PartyUInfo) or "apv" (Agreement PartyVInfo) parameters.
Sets the JWE Key Management parameters to be used when encrypting. For ECDH based algorithms,
use this method to set the "apu" (Agreement PartyUInfo) or "apv" (Agreement PartyVInfo)
parameters.
#### Parameters
@@ -311,25 +298,19 @@ PartyUInfo) or "apv" (Agreement PartyVInfo) parameters.
▸ **setNotBefore**(`input`): `this`
Set the "nbf" (Not Before) Claim.
- If a `number` is passed as an argument it is used as the claim directly.
- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
claim.
- If a `string` is passed as an argument it is resolved to a time span, and then added to the
current unix timestamp and used as the claim.
Set the "nbf" (Not Before) Claim. A `number` is used directly, a `Date` is converted to a Unix
timestamp, and a `string` is parsed as a time span relative to the current Unix timestamp.
String units may be seconds, minutes, hours, days, weeks, or years; months are unsupported and
a year is 365.25 days. A leading `-` or trailing `"ago"` subtracts the time span.
Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
day".
Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
alias for a year.
Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
"mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
"year", "years", "yr", "yrs", and "y".
If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
subtracted from the current unix timestamp. A "from now" suffix can also be used for
readability when adding to the current unix timestamp.
A "from now" suffix can be used for readability when adding to the current Unix timestamp.
#### Parameters
docs/jwt/sign/classes/SignJWT.md
+25 -43
View File
@@ -145,25 +145,19 @@ Set the "aud" (Audience) Claim.
▸ **setExpirationTime**(`input`): `this`
Set the "exp" (Expiration Time) Claim.
- If a `number` is passed as an argument it is used as the claim directly.
- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
claim.
- If a `string` is passed as an argument it is resolved to a time span, and then added to the
current unix timestamp and used as the claim.
Set the "exp" (Expiration Time) Claim. A `number` is used directly, a `Date` is converted to a
Unix timestamp, and a `string` is parsed as a time span relative to the current Unix timestamp.
String units may be seconds, minutes, hours, days, weeks, or years; months are unsupported and
a year is 365.25 days. A leading `-` or trailing `"ago"` subtracts the time span.
Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
day".
Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
alias for a year.
Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
"mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
"year", "years", "yr", "yrs", and "y".
If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
subtracted from the current unix timestamp. A "from now" suffix can also be used for
readability when adding to the current unix timestamp.
A "from now" suffix can be used for readability when adding to the current Unix timestamp.
#### Parameters
@@ -181,26 +175,20 @@ readability when adding to the current unix timestamp.
▸ **setIssuedAt**(`input?`): `this`
Set the "iat" (Issued At) Claim.
- If no argument is used the current unix timestamp is used as the claim.
- If a `number` is passed as an argument it is used as the claim directly.
- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
claim.
- If a `string` is passed as an argument it is resolved to a time span, and then added to the
current unix timestamp and used as the claim.
Set the "iat" (Issued At) Claim. With no argument the current Unix timestamp is used. A
`number` is used directly, a `Date` is converted to a Unix timestamp, and a `string` is parsed
as a time span relative to the current Unix timestamp. String units may be seconds, minutes,
hours, days, weeks, or years; months are unsupported and a year is 365.25 days. A leading `-`
or trailing `"ago"` subtracts the time span.
Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
day".
Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
alias for a year.
Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
"mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
"year", "years", "yr", "yrs", and "y".
If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
subtracted from the current unix timestamp. A "from now" suffix can also be used for
readability when adding to the current unix timestamp.
A "from now" suffix can be used for readability when adding to the current Unix timestamp.
#### Parameters
@@ -254,25 +242,19 @@ Set the "jti" (JWT ID) Claim.
▸ **setNotBefore**(`input`): `this`
Set the "nbf" (Not Before) Claim.
- If a `number` is passed as an argument it is used as the claim directly.
- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
claim.
- If a `string` is passed as an argument it is resolved to a time span, and then added to the
current unix timestamp and used as the claim.
Set the "nbf" (Not Before) Claim. A `number` is used directly, a `Date` is converted to a Unix
timestamp, and a `string` is parsed as a time span relative to the current Unix timestamp.
String units may be seconds, minutes, hours, days, weeks, or years; months are unsupported and
a year is 365.25 days. A leading `-` or trailing `"ago"` subtracts the time span.
Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
day".
Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
alias for a year.
Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
"mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
"year", "years", "yr", "yrs", and "y".
If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
subtracted from the current unix timestamp. A "from now" suffix can also be used for
readability when adding to the current unix timestamp.
A "from now" suffix can be used for readability when adding to the current Unix timestamp.
#### Parameters
docs/jwt/unsecured/classes/UnsecuredJWT.md
+25 -43
View File
@@ -115,25 +115,19 @@ Set the "aud" (Audience) Claim.
▸ **setExpirationTime**(`input`): `this`
Set the "exp" (Expiration Time) Claim.
- If a `number` is passed as an argument it is used as the claim directly.
- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
claim.
- If a `string` is passed as an argument it is resolved to a time span, and then added to the
current unix timestamp and used as the claim.
Set the "exp" (Expiration Time) Claim. A `number` is used directly, a `Date` is converted to a
Unix timestamp, and a `string` is parsed as a time span relative to the current Unix timestamp.
String units may be seconds, minutes, hours, days, weeks, or years; months are unsupported and
a year is 365.25 days. A leading `-` or trailing `"ago"` subtracts the time span.
Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
day".
Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
alias for a year.
Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
"mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
"year", "years", "yr", "yrs", and "y".
If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
subtracted from the current unix timestamp. A "from now" suffix can also be used for
readability when adding to the current unix timestamp.
A "from now" suffix can be used for readability when adding to the current Unix timestamp.
#### Parameters
@@ -151,26 +145,20 @@ readability when adding to the current unix timestamp.
▸ **setIssuedAt**(`input?`): `this`
Set the "iat" (Issued At) Claim.
- If no argument is used the current unix timestamp is used as the claim.
- If a `number` is passed as an argument it is used as the claim directly.
- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
claim.
- If a `string` is passed as an argument it is resolved to a time span, and then added to the
current unix timestamp and used as the claim.
Set the "iat" (Issued At) Claim. With no argument the current Unix timestamp is used. A
`number` is used directly, a `Date` is converted to a Unix timestamp, and a `string` is parsed
as a time span relative to the current Unix timestamp. String units may be seconds, minutes,
hours, days, weeks, or years; months are unsupported and a year is 365.25 days. A leading `-`
or trailing `"ago"` subtracts the time span.
Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
day".
Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
alias for a year.
Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
"mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
"year", "years", "yr", "yrs", and "y".
If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
subtracted from the current unix timestamp. A "from now" suffix can also be used for
readability when adding to the current unix timestamp.
A "from now" suffix can be used for readability when adding to the current Unix timestamp.
#### Parameters
@@ -224,25 +212,19 @@ Set the "jti" (JWT ID) Claim.
▸ **setNotBefore**(`input`): `this`
Set the "nbf" (Not Before) Claim.
- If a `number` is passed as an argument it is used as the claim directly.
- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
claim.
- If a `string` is passed as an argument it is resolved to a time span, and then added to the
current unix timestamp and used as the claim.
Set the "nbf" (Not Before) Claim. A `number` is used directly, a `Date` is converted to a Unix
timestamp, and a `string` is parsed as a time span relative to the current Unix timestamp.
String units may be seconds, minutes, hours, days, weeks, or years; months are unsupported and
a year is 365.25 days. A leading `-` or trailing `"ago"` subtracts the time span.
Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
day".
Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
alias for a year.
Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
"mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
"year", "years", "yr", "yrs", and "y".
If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
subtracted from the current unix timestamp. A "from now" suffix can also be used for
readability when adding to the current unix timestamp.
A "from now" suffix can be used for readability when adding to the current Unix timestamp.
#### Parameters
docs/jwt/verify/interfaces/JWTVerifyGetKey.md
+1 -3
View File
@@ -20,9 +20,7 @@ the time of this function call.
▸ **JWTVerifyGetKey**(`protectedHeader`, `token`): [`JWK`](../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../types/interfaces/KeyObject.md) \| `KeyType` \| [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`JWK`](../../../types/type-aliases/JWK.md) \| [`KeyObject`](../../../types/interfaces/KeyObject.md) \| `KeyType`\>
Dynamic key resolution function. No token components have been verified at the time of this
function call.
If a suitable key for the token cannot be matched, throw an error instead.
function call. If a suitable key for the token cannot be matched, throw an error instead.
## Parameters
docs/jwt/verify/interfaces/JWTVerifyOptions.md
+23 -38
View File
@@ -24,9 +24,8 @@ A list of accepted JWS "alg" (Algorithm) Header Parameter values. By default all
• `optional` **audience?**: `string` \| `string`[]
Expected JWT "aud" (Audience) Claim value(s).
This option makes the JWT "aud" (Audience) Claim presence required.
Expected JWT "aud" (Audience) Claim value(s). This option makes the JWT "aud" (Audience) Claim
presence required.
***
@@ -34,13 +33,10 @@ This option makes the JWT "aud" (Audience) Claim presence required.
• `optional` **clockTolerance?**: `string` \| `number`
Clock skew tolerance
- In seconds when number (e.g. 5)
- Resolved into a number of seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
Used when validating the JWT "nbf" (Not Before) and "exp" (Expiration Time) claims, and when
validating the "iat" (Issued At) claim if the [`maxTokenAge` option](../../../types/interfaces/JWTClaimVerificationOptions.md#maxtokenage) is set.
Clock skew tolerance in seconds when a number (e.g. 5), or resolved into seconds when a string
(e.g. "5 seconds", "10 minutes", "2 hours"). Used when validating the JWT "nbf" (Not Before)
and "exp" (Expiration Time) claims, and when validating the "iat" (Issued At) claim if the
[`maxTokenAge` option](../../../types/interfaces/JWTClaimVerificationOptions.md#maxtokenage) is set.
***
@@ -50,20 +46,15 @@ validating the "iat" (Issued At) claim if the [`maxTokenAge` option](../../../ty
An object with keys representing recognized "crit" (Critical) Header Parameter names. The value
for those is either `true` or `false`. `true` when the Header Parameter MUST be integrity
protected, `false` when it's irrelevant.
protected, `false` when it's irrelevant. The JWS extension Header Parameter `b64` is always
recognized and processed properly; no other registered Header Parameters currently receive this
built-in treatment.
This makes the "Extension Header Parameter "..." is not recognized" error go away.
Use this when a given JWS/JWT/JWE profile requires the use of proprietary non-registered "crit"
(Critical) Header Parameters. This will only make sure the Header Parameter is syntactically
correct when provided and that it is optionally integrity protected. It will not process the
Header Parameter in any way or reject the operation if it is missing. You MUST still verify the
Header Parameter was present and process it according to the profile's validation steps after
the operation succeeds.
The JWS extension Header Parameter `b64` is always recognized and processed properly. No other
registered Header Parameters that need this kind of default built-in treatment are currently
available.
> [!WARNING]\
> This only checks that the Header Parameter is syntactically correct when provided and,
> optionally, integrity protected. It does not process the Header Parameter or reject the
> operation when it is missing. You MUST still verify its presence and process it according to
> the profile's validation steps after the operation succeeds.
#### Index Signature
@@ -83,9 +74,8 @@ Date to use when comparing NumericDate claims, defaults to `new Date()`.
• `optional` **issuer?**: `string` \| `string`[]
Expected JWT "iss" (Issuer) Claim value(s).
This option makes the JWT "iss" (Issuer) Claim presence required.
Expected JWT "iss" (Issuer) Claim value(s). This option makes the JWT "iss" (Issuer) Claim
presence required.
***
@@ -93,12 +83,9 @@ This option makes the JWT "iss" (Issuer) Claim presence required.
• `optional` **maxTokenAge?**: `string` \| `number`
Maximum time elapsed (in seconds) from the JWT "iat" (Issued At) Claim value.
- In seconds when number (e.g. 5)
- Resolved into a number of seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
This option makes the JWT "iat" (Issued At) Claim presence required.
Maximum time elapsed from the JWT "iat" (Issued At) Claim value, in seconds when a number (e.g.
5), or resolved into seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours"). This
option makes the JWT "iat" (Issued At) Claim presence required.
***
@@ -119,9 +106,8 @@ present.
• `optional` **subject?**: `string`
Expected JWT "sub" (Subject) Claim value.
This option makes the JWT "sub" (Subject) Claim presence required.
Expected JWT "sub" (Subject) Claim value. This option makes the JWT "sub" (Subject) Claim
presence required.
***
@@ -129,6 +115,5 @@ This option makes the JWT "sub" (Subject) Claim presence required.
• `optional` **typ?**: `string`
Expected JWT "typ" (Type) Header Parameter value.
This option makes the JWT "typ" (Type) Header Parameter presence required.
Expected JWT "typ" (Type) Header Parameter value. This option makes the JWT "typ" (Type) Header
Parameter presence required.
docs/key/generate_secret/type-aliases/GeneratedSecret.md
+4 -5
View File
@@ -6,12 +6,11 @@ Support from the community to continue maintaining and improving this module is
• **GeneratedSecret**\<`Alg`\> = `Alg` *extends* `"A128CBC-HS256"` \| `"A192CBC-HS384"` \| `"A256CBC-HS512"` ? [`Uint8Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) : `string` *extends* `Alg` ? [`CryptoKey`](../../../types/type-aliases/CryptoKey.md) \| [`Uint8Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) : [`CryptoKey`](../../../types/type-aliases/CryptoKey.md)
Resolves what [generateSecret](../functions/generateSecret.md) returns for a given JWA Algorithm Identifier.
The AES_CBC_HMAC_SHA2 content encryption algorithms have no [CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey) representation, so
they yield a [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array); every other supported identifier yields a
Resolves what [generateSecret](../functions/generateSecret.md) returns for a given JWA Algorithm Identifier. The
AES_CBC_HMAC_SHA2 content encryption algorithms have no [CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey) representation, so they
yield a [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array); every other supported identifier yields a
[CryptoKey](../../../types/type-aliases/CryptoKey.md). When the identifier is not statically known this resolves to
the union, as before.
their union.
## Type Parameters
docs/key/import/type-aliases/ImportedJWK.md
+5 -7
View File
@@ -6,13 +6,11 @@ Support from the community to continue maintaining and improving this module is
• **ImportedJWK**\<`JWKType`\> = `JWKType` *extends* `object` ? [`Uint8Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) : `JWKType` *extends* `object` ? [`CryptoKey`](../../../types/type-aliases/CryptoKey.md) : [`CryptoKey`](../../../types/type-aliases/CryptoKey.md) \| [`Uint8Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)
Resolves what [importJWK](../functions/importJWK.md) returns for a given JWK type.
The "kty" (Key Type) Parameter fully determines the outcome at runtime: `"oct"` yields a
[Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) secret, every other supported key type yields a
[CryptoKey](../../../types/type-aliases/CryptoKey.md). When "kty" is not statically known — the usual case for a JWK
parsed from JSON, or for a value typed as [JWK](../../../types/type-aliases/JWK.md) — this resolves to the union, as
before.
Resolves what [importJWK](../functions/importJWK.md) returns for a given JWK type. The "kty" (Key Type) Parameter fully
determines the outcome at runtime: `"oct"` yields a [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) secret, every other
supported key type yields a [CryptoKey](../../../types/type-aliases/CryptoKey.md). When "kty" is not statically known
— the usual case for a JWK parsed from JSON, or for a value typed as [JWK](../../../types/type-aliases/JWK.md) — this
resolves to their union.
## Type Parameters
docs/types/interfaces/CompactJWEHeaderParameters.md
+5 -7
View File
@@ -66,9 +66,8 @@ JWE "crit" (Critical) Header Parameter
• `optional` **jwk?**: [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)\<[`JWK`](../type-aliases/JWK.md), `"d"` \| `"p"` \| `"q"` \| `"k"` \| `"dp"` \| `"dq"` \| `"qi"` \| `"priv"` \| `"oth"`\>
"jwk" (JSON Web Key) Header Parameter
Must be a public JSON Web Key; private and symmetric key parameters are not permitted.
"jwk" (JSON Web Key) Header Parameter. This must be a public JSON Web Key; private and
symmetric key parameters are not permitted.
***
@@ -116,10 +115,9 @@ Must be a public JSON Web Key; private and symmetric key parameters are not perm
• `optional` **zip?**: `string`
JWE "zip" (Compression Algorithm) Header Parameter.
The only supported value is `"DEF"` (DEFLATE). Requires the `CompressionStream` /
`DecompressionStream` APIs to be available in the runtime.
JWE "zip" (Compression Algorithm) Header Parameter. The only supported value is `"DEF"`
(DEFLATE), and it requires the `CompressionStream` / `DecompressionStream` APIs to be available
in the runtime.
#### See
docs/types/interfaces/CompactJWSHeaderParameters.md
+2 -3
View File
@@ -63,9 +63,8 @@ JWS "crit" (Critical) Header Parameter
• `optional` **jwk?**: [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)\<[`JWK`](../type-aliases/JWK.md), `"d"` \| `"p"` \| `"q"` \| `"k"` \| `"dp"` \| `"dq"` \| `"qi"` \| `"priv"` \| `"oth"`\>
"jwk" (JSON Web Key) Header Parameter
Must be a public JSON Web Key; private and symmetric key parameters are not permitted.
"jwk" (JSON Web Key) Header Parameter. This must be a public JSON Web Key; private and
symmetric key parameters are not permitted.
***
docs/types/interfaces/CritOption.md
+8 -13
View File
@@ -14,20 +14,15 @@ Shared Interface with a "crit" property for all sign, verify, encrypt and decryp
An object with keys representing recognized "crit" (Critical) Header Parameter names. The value
for those is either `true` or `false`. `true` when the Header Parameter MUST be integrity
protected, `false` when it's irrelevant.
protected, `false` when it's irrelevant. The JWS extension Header Parameter `b64` is always
recognized and processed properly; no other registered Header Parameters currently receive this
built-in treatment.
This makes the "Extension Header Parameter "..." is not recognized" error go away.
Use this when a given JWS/JWT/JWE profile requires the use of proprietary non-registered "crit"
(Critical) Header Parameters. This will only make sure the Header Parameter is syntactically
correct when provided and that it is optionally integrity protected. It will not process the
Header Parameter in any way or reject the operation if it is missing. You MUST still verify the
Header Parameter was present and process it according to the profile's validation steps after
the operation succeeds.
The JWS extension Header Parameter `b64` is always recognized and processed properly. No other
registered Header Parameters that need this kind of default built-in treatment are currently
available.
> [!WARNING]\
> This only checks that the Header Parameter is syntactically correct when provided and,
> optionally, integrity protected. It does not process the Header Parameter or reject the
> operation when it is missing. You MUST still verify its presence and process it according to
> the profile's validation steps after the operation succeeds.
#### Index Signature
docs/types/interfaces/DecryptOptions.md
+10 -18
View File
@@ -23,20 +23,15 @@ A list of accepted JWE "enc" (Encryption Algorithm) Header Parameter values. By
An object with keys representing recognized "crit" (Critical) Header Parameter names. The value
for those is either `true` or `false`. `true` when the Header Parameter MUST be integrity
protected, `false` when it's irrelevant.
protected, `false` when it's irrelevant. The JWS extension Header Parameter `b64` is always
recognized and processed properly; no other registered Header Parameters currently receive this
built-in treatment.
This makes the "Extension Header Parameter "..." is not recognized" error go away.
Use this when a given JWS/JWT/JWE profile requires the use of proprietary non-registered "crit"
(Critical) Header Parameters. This will only make sure the Header Parameter is syntactically
correct when provided and that it is optionally integrity protected. It will not process the
Header Parameter in any way or reject the operation if it is missing. You MUST still verify the
Header Parameter was present and process it according to the profile's validation steps after
the operation succeeds.
The JWS extension Header Parameter `b64` is always recognized and processed properly. No other
registered Header Parameters that need this kind of default built-in treatment are currently
available.
> [!WARNING]\
> This only checks that the Header Parameter is syntactically correct when provided and,
> optionally, integrity protected. It does not process the Header Parameter or reject the
> operation when it is missing. You MUST still verify its presence and process it according to
> the profile's validation steps after the operation succeeds.
#### Index Signature
@@ -60,11 +55,8 @@ all PBES2 Key Management Algorithms, these need to be explicitly allowed using t
Maximum allowed size (in bytes) of the decompressed plaintext when the JWE `"zip"` (Compression
Algorithm) Header Parameter is present. By default this value is set to 250000 (250 KB). The
value must be `0`, a positive safe integer, or `Infinity`.
Set to `0` to reject all compressed JWEs during decryption.
Set to `Infinity` to disable the decompressed size limit.
value must be `0`, a positive safe integer, or `Infinity`. Set it to `0` to reject all
compressed JWEs during decryption or to `Infinity` to disable the decompressed size limit.
***
docs/types/interfaces/EncryptOptions.md
+8 -13
View File
@@ -14,20 +14,15 @@ JWE Encryption options.
An object with keys representing recognized "crit" (Critical) Header Parameter names. The value
for those is either `true` or `false`. `true` when the Header Parameter MUST be integrity
protected, `false` when it's irrelevant.
protected, `false` when it's irrelevant. The JWS extension Header Parameter `b64` is always
recognized and processed properly; no other registered Header Parameters currently receive this
built-in treatment.
This makes the "Extension Header Parameter "..." is not recognized" error go away.
Use this when a given JWS/JWT/JWE profile requires the use of proprietary non-registered "crit"
(Critical) Header Parameters. This will only make sure the Header Parameter is syntactically
correct when provided and that it is optionally integrity protected. It will not process the
Header Parameter in any way or reject the operation if it is missing. You MUST still verify the
Header Parameter was present and process it according to the profile's validation steps after
the operation succeeds.
The JWS extension Header Parameter `b64` is always recognized and processed properly. No other
registered Header Parameters that need this kind of default built-in treatment are currently
available.
> [!WARNING]\
> This only checks that the Header Parameter is syntactically correct when provided and,
> optionally, integrity protected. It does not process the Header Parameter or reject the
> operation when it is missing. You MUST still verify its presence and process it according to
> the profile's validation steps after the operation succeeds.
#### Index Signature
docs/types/interfaces/GetKeyFunction.md
+1 -3
View File
@@ -17,9 +17,7 @@ Interface for consuming operations dynamic key resolution.
▸ **GetKeyFunction**(`protectedHeader`, `token`): `KeyTypes` \| [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`KeyTypes`\>
Dynamic key resolution function. No token components have been verified at the time of this
function call.
If a suitable key for the token cannot be matched, throw an error instead.
function call. If a suitable key for the token cannot be matched, throw an error instead.
## Parameters
docs/types/interfaces/JWEHeaderParameters.md
+5 -7
View File
@@ -66,9 +66,8 @@ JWE "enc" (Encryption Algorithm) Header Parameter
• `optional` **jwk?**: [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)\<[`JWK`](../type-aliases/JWK.md), `"d"` \| `"p"` \| `"q"` \| `"k"` \| `"dp"` \| `"dq"` \| `"qi"` \| `"priv"` \| `"oth"`\>
"jwk" (JSON Web Key) Header Parameter
Must be a public JSON Web Key; private and symmetric key parameters are not permitted.
"jwk" (JSON Web Key) Header Parameter. This must be a public JSON Web Key; private and
symmetric key parameters are not permitted.
***
@@ -116,10 +115,9 @@ Must be a public JSON Web Key; private and symmetric key parameters are not perm
• `optional` **zip?**: `string`
JWE "zip" (Compression Algorithm) Header Parameter.
The only supported value is `"DEF"` (DEFLATE). Requires the `CompressionStream` /
`DecompressionStream` APIs to be available in the runtime.
JWE "zip" (Compression Algorithm) Header Parameter. The only supported value is `"DEF"`
(DEFLATE), and it requires the `CompressionStream` / `DecompressionStream` APIs to be available
in the runtime.
#### See
docs/types/interfaces/JWSHeaderParameters.md
+2 -3
View File
@@ -63,9 +63,8 @@ JWS "crit" (Critical) Header Parameter
• `optional` **jwk?**: [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)\<[`JWK`](../type-aliases/JWK.md), `"d"` \| `"p"` \| `"q"` \| `"k"` \| `"dp"` \| `"dq"` \| `"qi"` \| `"priv"` \| `"oth"`\>
"jwk" (JSON Web Key) Header Parameter
Must be a public JSON Web Key; private and symmetric key parameters are not permitted.
"jwk" (JSON Web Key) Header Parameter. This must be a public JSON Web Key; private and
symmetric key parameters are not permitted.
***
docs/types/interfaces/JWTClaimVerificationOptions.md
+15 -25
View File
@@ -12,9 +12,8 @@ JWT Claims Set verification options.
• `optional` **audience?**: `string` \| `string`[]
Expected JWT "aud" (Audience) Claim value(s).
This option makes the JWT "aud" (Audience) Claim presence required.
Expected JWT "aud" (Audience) Claim value(s). This option makes the JWT "aud" (Audience) Claim
presence required.
***
@@ -22,13 +21,10 @@ This option makes the JWT "aud" (Audience) Claim presence required.
• `optional` **clockTolerance?**: `string` \| `number`
Clock skew tolerance
- In seconds when number (e.g. 5)
- Resolved into a number of seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
Used when validating the JWT "nbf" (Not Before) and "exp" (Expiration Time) claims, and when
validating the "iat" (Issued At) claim if the [`maxTokenAge` option](#maxtokenage) is set.
Clock skew tolerance in seconds when a number (e.g. 5), or resolved into seconds when a string
(e.g. "5 seconds", "10 minutes", "2 hours"). Used when validating the JWT "nbf" (Not Before)
and "exp" (Expiration Time) claims, and when validating the "iat" (Issued At) claim if the
[`maxTokenAge` option](#maxtokenage) is set.
***
@@ -44,9 +40,8 @@ Date to use when comparing NumericDate claims, defaults to `new Date()`.
• `optional` **issuer?**: `string` \| `string`[]
Expected JWT "iss" (Issuer) Claim value(s).
This option makes the JWT "iss" (Issuer) Claim presence required.
Expected JWT "iss" (Issuer) Claim value(s). This option makes the JWT "iss" (Issuer) Claim
presence required.
***
@@ -54,12 +49,9 @@ This option makes the JWT "iss" (Issuer) Claim presence required.
• `optional` **maxTokenAge?**: `string` \| `number`
Maximum time elapsed (in seconds) from the JWT "iat" (Issued At) Claim value.
- In seconds when number (e.g. 5)
- Resolved into a number of seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
This option makes the JWT "iat" (Issued At) Claim presence required.
Maximum time elapsed from the JWT "iat" (Issued At) Claim value, in seconds when a number (e.g.
5), or resolved into seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours"). This
option makes the JWT "iat" (Issued At) Claim presence required.
***
@@ -80,9 +72,8 @@ present.
• `optional` **subject?**: `string`
Expected JWT "sub" (Subject) Claim value.
This option makes the JWT "sub" (Subject) Claim presence required.
Expected JWT "sub" (Subject) Claim value. This option makes the JWT "sub" (Subject) Claim
presence required.
***
@@ -90,6 +81,5 @@ This option makes the JWT "sub" (Subject) Claim presence required.
• `optional` **typ?**: `string`
Expected JWT "typ" (Type) Header Parameter value.
This option makes the JWT "typ" (Type) Header Parameter presence required.
Expected JWT "typ" (Type) Header Parameter value. This option makes the JWT "typ" (Type) Header
Parameter presence required.
docs/types/interfaces/JWTHeaderParameters.md
+2 -3
View File
@@ -63,9 +63,8 @@ JWS "crit" (Critical) Header Parameter
• `optional` **jwk?**: [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)\<[`JWK`](../type-aliases/JWK.md), `"d"` \| `"p"` \| `"q"` \| `"k"` \| `"dp"` \| `"dq"` \| `"qi"` \| `"priv"` \| `"oth"`\>
"jwk" (JSON Web Key) Header Parameter
Must be a public JSON Web Key; private and symmetric key parameters are not permitted.
"jwk" (JSON Web Key) Header Parameter. This must be a public JSON Web Key; private and
symmetric key parameters are not permitted.
***
docs/types/interfaces/JoseHeaderParameters.md
+2 -3
View File
@@ -28,9 +28,8 @@ Header Parameters common to JWE and JWS
• `optional` **jwk?**: [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)\<[`JWK`](../type-aliases/JWK.md), `"d"` \| `"p"` \| `"q"` \| `"k"` \| `"dp"` \| `"dq"` \| `"qi"` \| `"priv"` \| `"oth"`\>
"jwk" (JSON Web Key) Header Parameter
Must be a public JSON Web Key; private and symmetric key parameters are not permitted.
"jwk" (JSON Web Key) Header Parameter. This must be a public JSON Web Key; private and
symmetric key parameters are not permitted.
***
docs/types/interfaces/ProduceJWT.md
+25 -43
View File
@@ -30,25 +30,19 @@ Set the "aud" (Audience) Claim.
▸ **setExpirationTime**(`input`): `this`
Set the "exp" (Expiration Time) Claim.
- If a `number` is passed as an argument it is used as the claim directly.
- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
claim.
- If a `string` is passed as an argument it is resolved to a time span, and then added to the
current unix timestamp and used as the claim.
Set the "exp" (Expiration Time) Claim. A `number` is used directly, a `Date` is converted to a
Unix timestamp, and a `string` is parsed as a time span relative to the current Unix timestamp.
String units may be seconds, minutes, hours, days, weeks, or years; months are unsupported and
a year is 365.25 days. A leading `-` or trailing `"ago"` subtracts the time span.
Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
day".
Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
alias for a year.
Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
"mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
"year", "years", "yr", "yrs", and "y".
If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
subtracted from the current unix timestamp. A "from now" suffix can also be used for
readability when adding to the current unix timestamp.
A "from now" suffix can be used for readability when adding to the current Unix timestamp.
#### Parameters
@@ -66,26 +60,20 @@ readability when adding to the current unix timestamp.
▸ **setIssuedAt**(`input?`): `this`
Set the "iat" (Issued At) Claim.
- If no argument is used the current unix timestamp is used as the claim.
- If a `number` is passed as an argument it is used as the claim directly.
- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
claim.
- If a `string` is passed as an argument it is resolved to a time span, and then added to the
current unix timestamp and used as the claim.
Set the "iat" (Issued At) Claim. With no argument the current Unix timestamp is used. A
`number` is used directly, a `Date` is converted to a Unix timestamp, and a `string` is parsed
as a time span relative to the current Unix timestamp. String units may be seconds, minutes,
hours, days, weeks, or years; months are unsupported and a year is 365.25 days. A leading `-`
or trailing `"ago"` subtracts the time span.
Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
day".
Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
alias for a year.
Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
"mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
"year", "years", "yr", "yrs", and "y".
If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
subtracted from the current unix timestamp. A "from now" suffix can also be used for
readability when adding to the current unix timestamp.
A "from now" suffix can be used for readability when adding to the current Unix timestamp.
#### Parameters
@@ -139,25 +127,19 @@ Set the "jti" (JWT ID) Claim.
▸ **setNotBefore**(`input`): `this`
Set the "nbf" (Not Before) Claim.
- If a `number` is passed as an argument it is used as the claim directly.
- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
claim.
- If a `string` is passed as an argument it is resolved to a time span, and then added to the
current unix timestamp and used as the claim.
Set the "nbf" (Not Before) Claim. A `number` is used directly, a `Date` is converted to a Unix
timestamp, and a `string` is parsed as a time span relative to the current Unix timestamp.
String units may be seconds, minutes, hours, days, weeks, or years; months are unsupported and
a year is 365.25 days. A leading `-` or trailing `"ago"` subtracts the time span.
Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
day".
Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
alias for a year.
Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
"mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
"year", "years", "yr", "yrs", and "y".
If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
subtracted from the current unix timestamp. A "from now" suffix can also be used for
readability when adding to the current unix timestamp.
A "from now" suffix can be used for readability when adding to the current Unix timestamp.
#### Parameters
docs/types/interfaces/SignOptions.md
+8 -13
View File
@@ -14,20 +14,15 @@ JWS Signing options.
An object with keys representing recognized "crit" (Critical) Header Parameter names. The value
for those is either `true` or `false`. `true` when the Header Parameter MUST be integrity
protected, `false` when it's irrelevant.
protected, `false` when it's irrelevant. The JWS extension Header Parameter `b64` is always
recognized and processed properly; no other registered Header Parameters currently receive this
built-in treatment.
This makes the "Extension Header Parameter "..." is not recognized" error go away.
Use this when a given JWS/JWT/JWE profile requires the use of proprietary non-registered "crit"
(Critical) Header Parameters. This will only make sure the Header Parameter is syntactically
correct when provided and that it is optionally integrity protected. It will not process the
Header Parameter in any way or reject the operation if it is missing. You MUST still verify the
Header Parameter was present and process it according to the profile's validation steps after
the operation succeeds.
The JWS extension Header Parameter `b64` is always recognized and processed properly. No other
registered Header Parameters that need this kind of default built-in treatment are currently
available.
> [!WARNING]\
> This only checks that the Header Parameter is syntactically correct when provided and,
> optionally, integrity protected. It does not process the Header Parameter or reject the
> operation when it is missing. You MUST still verify its presence and process it according to
> the profile's validation steps after the operation succeeds.
#### Index Signature
docs/types/interfaces/VerifyOptions.md
+8 -13
View File
@@ -26,20 +26,15 @@ A list of accepted JWS "alg" (Algorithm) Header Parameter values. By default all
An object with keys representing recognized "crit" (Critical) Header Parameter names. The value
for those is either `true` or `false`. `true` when the Header Parameter MUST be integrity
protected, `false` when it's irrelevant.
protected, `false` when it's irrelevant. The JWS extension Header Parameter `b64` is always
recognized and processed properly; no other registered Header Parameters currently receive this
built-in treatment.
This makes the "Extension Header Parameter "..." is not recognized" error go away.
Use this when a given JWS/JWT/JWE profile requires the use of proprietary non-registered "crit"
(Critical) Header Parameters. This will only make sure the Header Parameter is syntactically
correct when provided and that it is optionally integrity protected. It will not process the
Header Parameter in any way or reject the operation if it is missing. You MUST still verify the
Header Parameter was present and process it according to the profile's validation steps after
the operation succeeds.
The JWS extension Header Parameter `b64` is always recognized and processed properly. No other
registered Header Parameters that need this kind of default built-in treatment are currently
available.
> [!WARNING]\
> This only checks that the Header Parameter is syntactically correct when provided and,
> optionally, integrity protected. It does not process the Header Parameter or reject the
> operation when it is missing. You MUST still verify its presence and process it according to
> the profile's validation steps after the operation succeeds.
#### Index Signature
docs/types/type-aliases/AnyJWK.md
+3 -5
View File
@@ -6,11 +6,9 @@ Support from the community to continue maintaining and improving this module is
• **AnyJWK** = [`JWK_EC_Private`](../interfaces/JWK_EC_Private.md) \| [`JWK_EC_Public`](../interfaces/JWK_EC_Public.md) \| [`JWK_RSA_Private`](../interfaces/JWK_RSA_Private.md) \| [`JWK_RSA_Public`](../interfaces/JWK_RSA_Public.md) \| [`JWK_OKP_Private`](../interfaces/JWK_OKP_Private.md) \| [`JWK_OKP_Public`](../interfaces/JWK_OKP_Public.md) \| [`JWK_AKP_Private`](../interfaces/JWK_AKP_Private.md) \| [`JWK_AKP_Public`](../interfaces/JWK_AKP_Public.md) \| [`JWK_oct`](../interfaces/JWK_oct.md)
Discriminated union of the JSON Web Key shapes supported by this module. Unlike [JWK](JWK.md), this
can be narrowed on the "kty" (Key Type) Parameter.
Each member is the convenience interface for one key type with its "kty" (Key Type) Parameter
required and fixed to that key type, rather than optional as the interface alone leaves it.
Discriminated union of the JSON Web Key shapes supported by this module. Unlike [JWK](JWK.md), each
member requires and fixes the "kty" (Key Type) Parameter to its key type so that the union can be
narrowed on it.
## Example
docs/util/errors/classes/JWKSMultipleMatchingKeys.md
+3 -4
View File
@@ -32,10 +32,9 @@ if (err instanceof jose.errors.JWKSMultipleMatchingKeys) {
Iterates the public keys that matched the JWS JOSE Header, so that verification can be
attempted with each in turn. See the [createRemoteJWKSet](../../../jwks/remote/functions/createRemoteJWKSet.md)
and [createLocalJWKSet](../../../jwks/local/functions/createLocalJWKSet.md) examples.
Instances thrown by this module always iterate the matched keys. An instance constructed by
other code iterates nothing.
and [createLocalJWKSet](../../../jwks/local/functions/createLocalJWKSet.md) examples. Instances thrown by this
module always iterate the matched keys; an instance constructed by other code iterates
nothing.
#### Returns
docs/util/errors/type-aliases/JWTClaimValidationError.md
+3 -5
View File
@@ -6,11 +6,9 @@ Support from the community to continue maintaining and improving this module is
• **JWTClaimValidationError** = [`JWTClaimValidationFailed`](../classes/JWTClaimValidationFailed.md) \| [`JWTExpired`](../classes/JWTExpired.md)
Union of the errors thrown during JWT Claims Set validation.
[JWTExpired](../classes/JWTExpired.md) does not extend [JWTClaimValidationFailed](../classes/JWTClaimValidationFailed.md), so a single `instanceof` check
cannot cover both. Use this type — together with the [code](../classes/JOSEError.md#code) discriminant —
when handling either.
Union of the errors thrown during JWT Claims Set validation. [JWTExpired](../classes/JWTExpired.md) does not extend
[JWTClaimValidationFailed](../classes/JWTClaimValidationFailed.md), so a single `instanceof` check cannot cover both. Use this type
— together with the [code](../classes/JOSEError.md#code) discriminant — when handling either.
## Example
src/jwe/compact/encrypt.ts
+3 -4
View File
@@ -76,10 +76,9 @@ export class CompactEncrypt {
}
/**
* Sets the JWE Key Management parameters to be used when encrypting.
*
* (ECDH-ES) Use of this method is needed for ECDH based algorithms to set the "apu" (Agreement
* PartyUInfo) or "apv" (Agreement PartyVInfo) parameters.
* Sets the JWE Key Management parameters to be used when encrypting. For ECDH based algorithms,
* use this method to set the "apu" (Agreement PartyUInfo) or "apv" (Agreement PartyVInfo)
* parameters.
*
* @param parameters JWE Key Management parameters.
*/
src/jwe/flattened/encrypt.ts
+3 -4
View File
@@ -59,10 +59,9 @@ export class FlattenedEncrypt {
}
/**
* Sets the JWE Key Management parameters to be used when encrypting.
*
* (ECDH-ES) Use of this method is needed for ECDH based algorithms to set the "apu" (Agreement
* PartyUInfo) or "apv" (Agreement PartyVInfo) parameters.
* Sets the JWE Key Management parameters to be used when encrypting. For ECDH based algorithms,
* use this method to set the "apu" (Agreement PartyUInfo) or "apv" (Agreement PartyVInfo)
* parameters.
*
* @param parameters JWE Key Management parameters.
*/
src/jwe/general/encrypt.ts
+3 -4
View File
@@ -27,10 +27,9 @@ export interface Recipient {
setUnprotectedHeader(unprotectedHeader: types.JWEHeaderParameters): Recipient
/**
* Sets the JWE Key Management parameters to be used when encrypting.
*
* (ECDH-ES) Use of this method is needed for ECDH based algorithms to set the "apu" (Agreement
* PartyUInfo) or "apv" (Agreement PartyVInfo) parameters.
* Sets the JWE Key Management parameters to be used when encrypting. For ECDH based algorithms,
* use this method to set the "apu" (Agreement PartyUInfo) or "apv" (Agreement PartyVInfo)
* parameters.
*
* @param parameters JWE Key Management parameters.
*/
src/jwks/local.ts
+4 -1
View File
@@ -162,7 +162,10 @@ export interface LocalJWKSet {
/**
* Returns a function that resolves a JWS JOSE Header to a public key object from a locally stored,
* or otherwise available, JSON Web Key Set.
* or otherwise available, JSON Web Key Set. Selection respects the header's "alg" (Algorithm) and
* "kid" (Key ID) as well as the JWK's "use" (Public Key Use) and "key_ops" (Key Operations).
* Exactly one key must match; if multiple keys match, the thrown `JWKSMultipleMatchingKeys` can be
* iterated.
*
* It uses the "alg" (JWS Algorithm) Header Parameter to determine the right JWK "kty" (Key Type),
* then proceeds to match the JWK "kid" (Key ID) with one found in the JWS Header Parameters (if
src/jwks/remote.ts
+7 -3
View File
@@ -213,8 +213,9 @@ async function fetchJwks(
* > code.
*
* This option is intended for cloud computing runtimes that cannot keep an in memory cache between
* their code's invocations. Use in runtimes where an in memory cache between requests is available
* is not desirable.
* their code's invocations. The supplied writable object seeds the resolver's cache and is updated
* with `jwks` and `uat` after a successful fetch; persist it whenever `uat` changes. Using this in
* runtimes that can keep an in-memory cache between requests is not desirable.
*
* When passed to {@link jwks/remote.createRemoteJWKSet createRemoteJWKSet} this allows the passed in
* object to:
@@ -490,7 +491,10 @@ class RemoteJWKSetImpl {
* Returns a function that resolves a JWS JOSE Header to a public key object downloaded from a
* remote endpoint returning a JSON Web Key Set, that is, for example, an OAuth 2.0 or OIDC
* jwks_uri. The JSON Web Key Set is fetched when no key matches the selection process but only as
* frequently as the `cooldownDuration` option allows to prevent abuse.
* frequently as the `cooldownDuration` option allows to prevent abuse. Selection respects the
* header's "alg" (Algorithm) and "kid" (Key ID) as well as the JWK's "use" (Public Key Use) and
* "key_ops" (Key Operations). Exactly one key must match; if multiple keys match, the thrown
* `JWKSMultipleMatchingKeys` can be iterated.
*
* It uses the "alg" (JWS Algorithm) Header Parameter to determine the right JWK "kty" (Key Type),
* then proceeds to match the JWK "kid" (Key ID) with one found in the JWS Header Parameters (if
src/jwt/encrypt.ts
+3 -4
View File
@@ -104,10 +104,9 @@ export class EncryptJWT implements types.ProduceJWT {
}
/**
* Sets the JWE Key Management parameters to be used when encrypting.
*
* (ECDH-ES) Use of this method is needed for ECDH based algorithms to set the "apu" (Agreement
* PartyUInfo) or "apv" (Agreement PartyVInfo) parameters.
* Sets the JWE Key Management parameters to be used when encrypting. For ECDH based algorithms,
* use this method to set the "apu" (Agreement PartyUInfo) or "apv" (Agreement PartyVInfo)
* parameters.
*
* @param parameters JWE Key Management parameters.
*/
src/key/generate_key_pair.ts
+2 -3
View File
@@ -10,9 +10,8 @@ import { keyAlgorithm } from '../lib/key_algorithm.js'
import type * as types from '../types.d.ts'
/**
* JWA Algorithm Identifiers that {@link generateKeyPair} is able to generate a key pair for.
*
* Support for a given identifier additionally depends on the runtime.
* JWA Algorithm Identifiers that {@link generateKeyPair} is able to generate a key pair for, subject
* to runtime support.
*
* @ignore
*/
src/key/generate_secret.ts
+6 -8
View File
@@ -9,9 +9,8 @@ import { JOSENotSupported } from '../util/errors.js'
import type * as types from '../types.d.ts'
/**
* JWA Algorithm Identifiers that {@link generateSecret} is able to generate a secret for.
*
* Support for a given identifier additionally depends on the runtime.
* JWA Algorithm Identifiers that {@link generateSecret} is able to generate a secret for, subject to
* runtime support.
*
* @ignore
*/
@@ -34,12 +33,11 @@ export type GenerateSecretAlgorithm =
| (string & {})
/**
* Resolves what {@link generateSecret} returns for a given JWA Algorithm Identifier.
*
* The AES_CBC_HMAC_SHA2 content encryption algorithms have no {@link !CryptoKey} representation, so
* they yield a {@link !Uint8Array}; every other supported identifier yields a
* Resolves what {@link generateSecret} returns for a given JWA Algorithm Identifier. The
* AES_CBC_HMAC_SHA2 content encryption algorithms have no {@link !CryptoKey} representation, so they
* yield a {@link !Uint8Array}; every other supported identifier yields a
* {@link types.CryptoKey CryptoKey}. When the identifier is not statically known this resolves to
* the union, as before.
* their union.
*/
export type GeneratedSecret<Alg extends string> = Alg extends
'A128CBC-HS256' | 'A192CBC-HS384' | 'A256CBC-HS512'
src/key/import.ts
+5 -7
View File
@@ -14,13 +14,11 @@ import { isObject } from '../lib/type_checks.js'
import type * as types from '../types.d.ts'
/**
* Resolves what {@link importJWK} returns for a given JWK type.
*
* The "kty" (Key Type) Parameter fully determines the outcome at runtime: `"oct"` yields a
* {@link !Uint8Array} secret, every other supported key type yields a
* {@link types.CryptoKey CryptoKey}. When "kty" is not statically known — the usual case for a JWK
* parsed from JSON, or for a value typed as {@link types.JWK JWK} — this resolves to the union, as
* before.
* Resolves what {@link importJWK} returns for a given JWK type. The "kty" (Key Type) Parameter fully
* determines the outcome at runtime: `"oct"` yields a {@link !Uint8Array} secret, every other
* supported key type yields a {@link types.CryptoKey CryptoKey}. When "kty" is not statically known
* — the usual case for a JWK parsed from JSON, or for a value typed as {@link types.JWK JWK} — this
* resolves to their union.
*/
export type ImportedJWK<JWKType extends types.JWK> = JWKType extends { kty: 'oct' }
? Uint8Array
src/types.d.ts
Vendored
+65 -110
View File
@@ -1,7 +1,6 @@
/**
* JWS "alg" (Algorithm) Header Parameter values supported by this module.
*
* Support for a given identifier additionally depends on the runtime.
* JWS "alg" (Algorithm) Header Parameter values supported by this module. Availability of a given
* identifier additionally depends on the runtime.
*
* @ignore
*
@@ -28,9 +27,8 @@ export type JWSAlgorithm =
| (string & {})
/**
* JWE "alg" (Algorithm) Header Parameter values supported by this module.
*
* Support for a given identifier additionally depends on the runtime.
* JWE "alg" (Algorithm) Header Parameter values supported by this module. Availability of a given
* identifier additionally depends on the runtime.
*
* @ignore
*
@@ -58,9 +56,8 @@ export type JWEKeyManagementAlgorithm =
| (string & {})
/**
* JWE "enc" (Encryption Algorithm) Header Parameter values supported by this module.
*
* Support for a given identifier additionally depends on the runtime.
* JWE "enc" (Encryption Algorithm) Header Parameter values supported by this module. Availability
* of a given identifier additionally depends on the runtime.
*
* @ignore
*/
@@ -289,11 +286,9 @@ export type JWK = {
}
/**
* Discriminated union of the JSON Web Key shapes supported by this module. Unlike {@link JWK}, this
* can be narrowed on the "kty" (Key Type) Parameter.
*
* Each member is the convenience interface for one key type with its "kty" (Key Type) Parameter
* required and fixed to that key type, rather than optional as the interface alone leaves it.
* Discriminated union of the JSON Web Key shapes supported by this module. Unlike {@link JWK}, each
* member requires and fixes the "kty" (Key Type) Parameter to its key type so that the union can be
* narrowed on it.
*
* @example
*
@@ -334,9 +329,7 @@ export type KeyInput = CryptoKey | KeyObject | JWK | Uint8Array
export interface GenericGetKeyFunction<IProtectedHeader, IToken, ReturnKeyTypes> {
/**
* Dynamic key resolution function. No token components have been verified at the time of this
* function call.
*
* If a suitable key for the token cannot be matched, throw an error instead.
* function call. If a suitable key for the token cannot be matched, throw an error instead.
*
* @param protectedHeader JWE or JWS Protected Header.
* @param token The consumed JWE or JWS token.
@@ -443,9 +436,8 @@ export interface JoseHeaderParameters {
jku?: string
/**
* "jwk" (JSON Web Key) Header Parameter
*
* Must be a public JSON Web Key; private and symmetric key parameters are not permitted.
* "jwk" (JSON Web Key) Header Parameter. This must be a public JSON Web Key; private and
* symmetric key parameters are not permitted.
*/
jwk?: Omit<JWK, 'd' | 'dp' | 'dq' | 'k' | 'p' | 'q' | 'qi' | 'priv' | 'oth'>
@@ -592,10 +584,9 @@ export interface JWEHeaderParameters extends JoseHeaderParameters {
crit?: string[]
/**
* JWE "zip" (Compression Algorithm) Header Parameter.
*
* The only supported value is `"DEF"` (DEFLATE). Requires the `CompressionStream` /
* `DecompressionStream` APIs to be available in the runtime.
* JWE "zip" (Compression Algorithm) Header Parameter. The only supported value is `"DEF"`
* (DEFLATE), and it requires the `CompressionStream` / `DecompressionStream` APIs to be available
* in the runtime.
*
* @see {@link https://www.rfc-editor.org/info/rfc7516/#section-4.1.3 JWE "zip" Header Parameter}
*/
@@ -610,20 +601,15 @@ export interface CritOption {
/**
* An object with keys representing recognized "crit" (Critical) Header Parameter names. The value
* for those is either `true` or `false`. `true` when the Header Parameter MUST be integrity
* protected, `false` when it's irrelevant.
* protected, `false` when it's irrelevant. The JWS extension Header Parameter `b64` is always
* recognized and processed properly; no other registered Header Parameters currently receive this
* built-in treatment.
*
* This makes the "Extension Header Parameter "..." is not recognized" error go away.
*
* Use this when a given JWS/JWT/JWE profile requires the use of proprietary non-registered "crit"
* (Critical) Header Parameters. This will only make sure the Header Parameter is syntactically
* correct when provided and that it is optionally integrity protected. It will not process the
* Header Parameter in any way or reject the operation if it is missing. You MUST still verify the
* Header Parameter was present and process it according to the profile's validation steps after
* the operation succeeds.
*
* The JWS extension Header Parameter `b64` is always recognized and processed properly. No other
* registered Header Parameters that need this kind of default built-in treatment are currently
* available.
* > [!WARNING]\
* > This only checks that the Header Parameter is syntactically correct when provided and,
* > optionally, integrity protected. It does not process the Header Parameter or reject the
* > operation when it is missing. You MUST still verify its presence and process it according to
* > the profile's validation steps after the operation succeeds.
*/
crit?: {
[propName: string]: boolean
@@ -655,11 +641,8 @@ export interface DecryptOptions extends CritOption {
/**
* Maximum allowed size (in bytes) of the decompressed plaintext when the JWE `"zip"` (Compression
* Algorithm) Header Parameter is present. By default this value is set to 250000 (250 KB). The
* value must be `0`, a positive safe integer, or `Infinity`.
*
* Set to `0` to reject all compressed JWEs during decryption.
*
* Set to `Infinity` to disable the decompressed size limit.
* value must be `0`, a positive safe integer, or `Infinity`. Set it to `0` to reject all
* compressed JWEs during decryption or to `Infinity` to disable the decompressed size limit.
*/
maxDecompressedLength?: number
}
@@ -670,51 +653,41 @@ export interface EncryptOptions extends CritOption {}
/** JWT Claims Set verification options. */
export interface JWTClaimVerificationOptions {
/**
* Expected JWT "aud" (Audience) Claim value(s).
*
* This option makes the JWT "aud" (Audience) Claim presence required.
* Expected JWT "aud" (Audience) Claim value(s). This option makes the JWT "aud" (Audience) Claim
* presence required.
*/
audience?: string | string[]
/**
* Clock skew tolerance
*
* - In seconds when number (e.g. 5)
* - Resolved into a number of seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
*
* Used when validating the JWT "nbf" (Not Before) and "exp" (Expiration Time) claims, and when
* validating the "iat" (Issued At) claim if the {@link maxTokenAge `maxTokenAge` option} is set.
* Clock skew tolerance in seconds when a number (e.g. 5), or resolved into seconds when a string
* (e.g. "5 seconds", "10 minutes", "2 hours"). Used when validating the JWT "nbf" (Not Before)
* and "exp" (Expiration Time) claims, and when validating the "iat" (Issued At) claim if the
* {@link maxTokenAge `maxTokenAge` option} is set.
*/
clockTolerance?: string | number
/**
* Expected JWT "iss" (Issuer) Claim value(s).
*
* This option makes the JWT "iss" (Issuer) Claim presence required.
* Expected JWT "iss" (Issuer) Claim value(s). This option makes the JWT "iss" (Issuer) Claim
* presence required.
*/
issuer?: string | string[]
/**
* Maximum time elapsed (in seconds) from the JWT "iat" (Issued At) Claim value.
*
* - In seconds when number (e.g. 5)
* - Resolved into a number of seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
*
* This option makes the JWT "iat" (Issued At) Claim presence required.
* Maximum time elapsed from the JWT "iat" (Issued At) Claim value, in seconds when a number (e.g.
* 5), or resolved into seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours"). This
* option makes the JWT "iat" (Issued At) Claim presence required.
*/
maxTokenAge?: string | number
/**
* Expected JWT "sub" (Subject) Claim value.
*
* This option makes the JWT "sub" (Subject) Claim presence required.
* Expected JWT "sub" (Subject) Claim value. This option makes the JWT "sub" (Subject) Claim
* presence required.
*/
subject?: string
/**
* Expected JWT "typ" (Type) Header Parameter value.
*
* This option makes the JWT "typ" (Type) Header Parameter presence required.
* Expected JWT "typ" (Type) Header Parameter value. This option makes the JWT "typ" (Type) Header
* Parameter presence required.
*/
typ?: string
@@ -990,76 +963,58 @@ export interface ProduceJWT {
setJti(jwtId: string): this
/**
* Set the "nbf" (Not Before) Claim.
*
* - If a `number` is passed as an argument it is used as the claim directly.
* - If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
* claim.
* - If a `string` is passed as an argument it is resolved to a time span, and then added to the
* current unix timestamp and used as the claim.
* Set the "nbf" (Not Before) Claim. A `number` is used directly, a `Date` is converted to a Unix
* timestamp, and a `string` is parsed as a time span relative to the current Unix timestamp.
* String units may be seconds, minutes, hours, days, weeks, or years; months are unsupported and
* a year is 365.25 days. A leading `-` or trailing `"ago"` subtracts the time span.
*
* Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
* day".
*
* Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
* "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
* "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
* alias for a year.
* Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
* "mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
* "year", "years", "yr", "yrs", and "y".
*
* If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
* subtracted from the current unix timestamp. A "from now" suffix can also be used for
* readability when adding to the current unix timestamp.
* A "from now" suffix can be used for readability when adding to the current Unix timestamp.
*
* @param input "nbf" (Not Before) Claim value to set on the JWT Claims Set.
*/
setNotBefore(input: number | string | Date): this
/**
* Set the "exp" (Expiration Time) Claim.
*
* - If a `number` is passed as an argument it is used as the claim directly.
* - If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
* claim.
* - If a `string` is passed as an argument it is resolved to a time span, and then added to the
* current unix timestamp and used as the claim.
* Set the "exp" (Expiration Time) Claim. A `number` is used directly, a `Date` is converted to a
* Unix timestamp, and a `string` is parsed as a time span relative to the current Unix timestamp.
* String units may be seconds, minutes, hours, days, weeks, or years; months are unsupported and
* a year is 365.25 days. A leading `-` or trailing `"ago"` subtracts the time span.
*
* Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
* day".
*
* Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
* "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
* "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
* alias for a year.
* Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
* "mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
* "year", "years", "yr", "yrs", and "y".
*
* If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
* subtracted from the current unix timestamp. A "from now" suffix can also be used for
* readability when adding to the current unix timestamp.
* A "from now" suffix can be used for readability when adding to the current Unix timestamp.
*
* @param input "exp" (Expiration Time) Claim value to set on the JWT Claims Set.
*/
setExpirationTime(input: number | string | Date): this
/**
* Set the "iat" (Issued At) Claim.
*
* - If no argument is used the current unix timestamp is used as the claim.
* - If a `number` is passed as an argument it is used as the claim directly.
* - If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
* claim.
* - If a `string` is passed as an argument it is resolved to a time span, and then added to the
* current unix timestamp and used as the claim.
* Set the "iat" (Issued At) Claim. With no argument the current Unix timestamp is used. A
* `number` is used directly, a `Date` is converted to a Unix timestamp, and a `string` is parsed
* as a time span relative to the current Unix timestamp. String units may be seconds, minutes,
* hours, days, weeks, or years; months are unsupported and a year is 365.25 days. A leading `-`
* or trailing `"ago"` subtracts the time span.
*
* Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
* day".
*
* Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
* "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
* "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
* alias for a year.
* Valid unit spellings are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min",
* "mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w",
* "year", "years", "yr", "yrs", and "y".
*
* If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
* subtracted from the current unix timestamp. A "from now" suffix can also be used for
* readability when adding to the current unix timestamp.
* A "from now" suffix can be used for readability when adding to the current Unix timestamp.
*
* @param input "iat" (Issued At) Claim value to set on the JWT Claims Set.
*/
src/util/errors.ts
+6 -9
View File
@@ -551,10 +551,9 @@ export class JWKSMultipleMatchingKeys extends JOSEError {
/**
* Iterates the public keys that matched the JWS JOSE Header, so that verification can be
* attempted with each in turn. See the {@link jwks/remote.createRemoteJWKSet createRemoteJWKSet}
* and {@link jwks/local.createLocalJWKSet createLocalJWKSet} examples.
*
* Instances thrown by this module always iterate the matched keys. An instance constructed by
* other code iterates nothing.
* and {@link jwks/local.createLocalJWKSet createLocalJWKSet} examples. Instances thrown by this
* module always iterate the matched keys; an instance constructed by other code iterates
* nothing.
*/
[Symbol.asyncIterator]: () => AsyncIterableIterator<types.CryptoKey> = async function* () {}
@@ -646,11 +645,9 @@ export class JWSSignatureVerificationFailed extends JOSEError {
}
/**
* Union of the errors thrown during JWT Claims Set validation.
*
* {@link JWTExpired} does not extend {@link JWTClaimValidationFailed}, so a single `instanceof` check
* cannot cover both. Use this type — together with the {@link JOSEError.code code} discriminant —
* when handling either.
* Union of the errors thrown during JWT Claims Set validation. {@link JWTExpired} does not extend
* {@link JWTClaimValidationFailed}, so a single `instanceof` check cannot cover both. Use this type
* — together with the {@link JOSEError.code code} discriminant — when handling either.
*
* @example
*
test/unit/declaration_comments.test.ts
+146
View File
@@ -0,0 +1,146 @@
import test from 'ava'
import { execFileSync } from 'node:child_process'
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { fileURLToPath } from 'node:url'
const processor = fileURLToPath(new URL('../../tools/declaration-comments.js', import.meta.url))
test('tools/declaration-comments.js', (t) => {
const cwd = mkdtempSync(join(tmpdir(), 'jose-declaration-comments-'))
const types = join(cwd, 'dist', 'types')
const declaration = join(types, 'example.d.ts')
t.teardown(() => rmSync(cwd, { recursive: true }))
const input = `/**
* Module documentation.
*
* @module
*/
import type { KeyLike } from './types.d.ts'
/**
* First summary.
*
* Extended documentation only needed on the generated documentation page.
*
* > [!WARNING]\\
* > Do not ignore this.
*
* This function is exported from the main module entry point as well as from its subpath export.
*
* @example
*
* \`\`\`ts
* @deprecated This is example code, not a tag.
* \`\`\`
*
* @typeParam T Type parameter documentation.
* @see https://example.com
* @deprecated Use next instead.
* @param value Input value.
* @returns The result.
* @throws When the input is invalid.
*/
export declare function example<T>(value: T): KeyLike
/**
* > [!NOTE]
* > Alerts can precede a summary.
*
* Summary after the alert.
*/
export interface AlertFirst {}
export interface Options {
/**
* Member summary with contractual behavior.
*
* Extended generated documentation.
*
* @see https://example.com/options
*/
option?: boolean
}
/**
* Internal helper summary.
*
* Additional internal documentation.
*
* @internal
*/
export interface InternalHelper {}
`
mkdirSync(types, { recursive: true })
writeFileSync(declaration, input)
const env = { ...process.env }
delete env.NODE_OPTIONS
const output = execFileSync(process.execPath, [processor], { cwd, env, encoding: 'utf8' })
t.is(output, 'rewrote 5 declaration comment(s) for editor hovers\n')
const expected = `import type { KeyLike } from './types.d.ts'
/**
* First summary.
*
* > Warning: Do not ignore this.
*
* @deprecated Use next instead.
* @param value Input value.
* @returns The result.
* @throws When the input is invalid.
*/
export declare function example<T>(value: T): KeyLike
/**
* > Note: Alerts can precede a summary.
*
* Summary after the alert.
*/
export interface AlertFirst {}
export interface Options {
/** Member summary with contractual behavior. */
option?: boolean
}
/** Internal helper summary. */
export interface InternalHelper {}
`
t.is(readFileSync(declaration, 'utf8'), expected)
t.is(
execFileSync(process.execPath, [processor], { cwd, env, encoding: 'utf8' }),
'rewrote 0 declaration comment(s) for editor hovers\n',
)
t.is(readFileSync(declaration, 'utf8'), expected)
writeFileSync(declaration, input)
const privateTypes = join(types, 'lib')
mkdirSync(privateTypes)
writeFileSync(
join(privateTypes, 'private.d.ts'),
`/**
* Private declaration documentation.
*
* @module
*/
export interface PrivateDeclaration {}
`,
)
const report = execFileSync(process.execPath, [processor], {
cwd,
env: { ...env, JOSE_DEBUG_TYPES: '1' },
encoding: 'utf8',
})
t.true(report.startsWith('stripped published declaration documentation\n\n'))
t.true(report.includes('dist/types/example.d.ts:1\n- Module documentation.'))
t.true(
report.includes('- Extended documentation only needed on the generated documentation page.'),
)
t.true(report.includes('- @example'))
t.true(report.includes('- @typeParam T Type parameter documentation.'))
t.true(report.includes('- @see https://example.com'))
t.true(report.includes('- @internal'))
t.false(report.includes('- @deprecated Use next instead.'))
t.false(report.includes('private.d.ts'))
t.true(report.endsWith('rewrote 6 declaration comment(s) for editor hovers\n'))
t.is(readFileSync(declaration, 'utf8'), expected)
})
tools/declaration-comments.js
+103 -8
View File
@@ -18,19 +18,33 @@
// since typedoc names its folders after source paths and that sentence is
// the only place the real specifier appears; noise in an editor hover.
//
// module documentation - TypeScript attaches it to the first import but does not expose it as
// useful module documentation in an editor.
//
// extended prose - only the first summary paragraph, alerts, signature-help tags, and
// @deprecated are useful in editor hovers. The rest remains in src for
// generated documentation.
//
// @ignore and friends - typedoc acts on them, TypeScript does not, so they reach the reader as
// a bare tag that means nothing to them.
//
// GitHub alerts - `> [!NOTE]` and the rest of the GFM set render as an admonition on
// GitHub and in the docs, and as a literal `[!NOTE]\` in a hover. The
// blockquote itself does carry over, so keep it and label it in words.
import { globSync, readFileSync, writeFileSync } from 'node:fs'
//
// Set JOSE_DEBUG_TYPES=1 to print the documentation stripped from publishable declarations.
import { readdirSync, readFileSync, writeFileSync } from 'node:fs'
import { join, sep } from 'node:path'
const SUBPATH_NOTE = /^(?:This|These)\b[^.]*\bexported\b/
const BLOCK_TAG = /^@(\w+)/
const MARKER_TAG = /^@(?:ignore|internal|private|hidden)\s*$/
const PUBLISHED_TAGS = new Set(['param', 'returns', 'throws', 'deprecated'])
const REPORT_STRIPPED = process.env.JOSE_DEBUG_TYPES === '1'
const PRIVATE_DECLARATIONS = `${join('dist', 'types', 'lib')}${sep}`
/** The five alert types GitHub Flavored Markdown defines. */
const ALERT = /^>\s*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\\?\s*$/
const RELABELLED_ALERT = /^>\s*(?:Note|Tip|Important|Warning|Caution):\s/
/**
* Splits the text lines of a JSDoc body into paragraphs. Fenced code blocks stay whole, so neither
@@ -54,6 +68,24 @@ function paragraphs(lines) {
return out
}
/** Splits adjacent block tags so filtering one tag cannot remove a neighboring retained tag. */
function blockTagSections(paragraph) {
const out = []
let current = []
let fenced = false
for (const line of paragraph) {
if (!fenced && BLOCK_TAG.test(line) && current.length) {
out.push(current)
current = []
}
current.push(line)
if (line.trimStart().startsWith('```')) fenced = !fenced
}
if (current.length) out.push(current)
return out
}
/** Turns `> [!NOTE]\` followed by the quote into a quote that opens with `Note:`. */
function relabelAlert(paragraph) {
const [marker, ...rest] = paragraph
@@ -64,57 +96,117 @@ function relabelAlert(paragraph) {
return [rest[0].replace(/^(\s*>\s*)/, `$1${label}: `), ...rest.slice(1)]
}
function* declarations(directory) {
const entries = readdirSync(directory, { withFileTypes: true }).sort((a, b) =>
a.name.localeCompare(b.name),
)
for (const entry of entries) {
const path = join(directory, entry.name)
if (entry.isDirectory()) {
yield* declarations(path)
} else if (entry.name.endsWith('.d.ts')) {
yield path
}
}
}
function transform(lines) {
const kept = []
const removed = []
let changed = false
let summary = false
// an @example runs until the next block tag that is not itself an @example - its description and
// its code fence are separate paragraphs, and there may be several in a row
let inExample = false
const sections = paragraphs(lines).flatMap(blockTagSections)
for (const paragraph of paragraphs(lines)) {
if (sections.some((paragraph) => paragraph[0].match(BLOCK_TAG)?.[1] === 'module')) {
return { kept, removed: paragraphs(lines), changed: true }
}
for (const paragraph of sections) {
const tag = paragraph[0].match(BLOCK_TAG)?.[1]
if (tag === 'example') {
inExample = true
changed = true
removed.push(paragraph)
continue
}
if (inExample) {
if (!tag) {
changed = true
removed.push(paragraph)
continue
}
inExample = false
}
if (SUBPATH_NOTE.test(paragraph[0]) || MARKER_TAG.test(paragraph[0])) {
changed = true
removed.push(paragraph)
continue
}
const relabelled = relabelAlert(paragraph)
if (relabelled) changed = true
kept.push(relabelled ?? paragraph)
if (relabelled) {
kept.push(relabelled)
changed = true
continue
}
if (RELABELLED_ALERT.test(paragraph[0])) {
kept.push(paragraph)
continue
}
if (tag) {
if (PUBLISHED_TAGS.has(tag)) {
const previous = kept.at(-1)
if (previous && BLOCK_TAG.test(previous[0])) {
previous.push(...paragraph)
} else {
kept.push(paragraph)
}
} else {
changed = true
removed.push(paragraph)
}
continue
}
if (!summary) {
kept.push(paragraph)
summary = true
} else {
changed = true
removed.push(paragraph)
}
}
return { kept, changed }
return { kept, removed, changed }
}
let touched = 0
const reports = []
for (const file of globSync('dist/types/**/*.d.ts')) {
for (const file of declarations('dist/types')) {
const source = readFileSync(file, 'utf8')
// prettier-plugin-jsdoc puts the summary on the `/**` line when it fits, so both shapes occur
const updated = source.replace(
/^([ \t]*)\/\*\*[ \t]?([\s\S]*?)[ \t]*\*\/[ \t]*\n/gm,
(block, indent, body) => {
(block, indent, body, offset) => {
const lines = body.split('\n').map((line) => line.replace(/^[ \t]*\*[ \t]?/, ''))
while (lines.length && lines.at(-1).trim() === '') lines.pop()
const { kept, changed } = transform(lines)
const { kept, removed, changed } = transform(lines)
if (!changed) return block
touched++
if (REPORT_STRIPPED && removed.length && !file.startsWith(PRIVATE_DECLARATIONS)) {
const line = source.slice(0, offset).split('\n').length
const stripped = removed.flatMap((paragraph, index) =>
index ? ['', ...paragraph] : paragraph,
)
reports.push(`${file}:${line}\n${stripped.map((line) => `- ${line}`).join('\n')}`)
}
if (!kept.length) return ''
const flat = kept.flatMap((paragraph, i) => (i ? ['', ...paragraph] : paragraph))
@@ -128,4 +220,7 @@ for (const file of globSync('dist/types/**/*.d.ts')) {
if (updated !== source) writeFileSync(file, updated, 'utf8')
}
if (reports.length) {
console.log(`stripped published declaration documentation\n\n${reports.join('\n\n')}\n`)
}
console.log(`rewrote ${touched} declaration comment(s) for editor hovers`)