shelving 1.159.5 → 1.160.0

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.159.5",
+	"version": "1.160.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/util/jwt.d.ts

@@ -1,13 +1,36 @@
 import { type Bytes, type PossibleBytes } from "./bytes.js";
 import type { Data } from "./data.js";
+import { type PossibleDate } from "./date.js";
 import type { AnyCaller } from "./function.js";
+export interface TokenClaims extends Data {
+    /**
+     * "Issued at" date (defaults to "now").
+     * - Not used for validation, but always set in the token payload.
+     * - Can be used to determine when the token was issued, and possibly revoke tokens issued before a certain date.
+     */
+    readonly iat?: PossibleDate;
+    /**
+     * "Not before" date.
+     * - When validating the token, tokens before this date will be rejected
+     */
+    readonly nbf?: PossibleDate;
+    /**
+     * Expiry in milliseconds (defaults to "30 days").
+     * - When validating the token, tokens after this date will be rejected
+     */
+    readonly exp?: number;
+}
 /**
  * Encode a JWT and return the string token.
  * - Currently only supports HMAC SHA-512 signing.
  *
+ * @param claims The payload claims to include in the JWT.
+ * @param secret The secret key to sign the JWT with.
+ * @param expiry The expiry time in milliseconds (defaults to 30 days).
+ *
  * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
  */
-export declare function encodeToken(claims: Data, secret: PossibleBytes): Promise<string>;
+export declare function encodeToken({ nbf, iat, exp, ...claims }: TokenClaims, secret: PossibleBytes): Promise<string>;
 /** Parts that make up a JSON Web Token. */
 export type TokenData = {
     header: string;

package/util/jwt.js

@@ -3,11 +3,11 @@ import { ValueError } from "../error/ValueError.js";
 import { decodeBase64URLBytes, decodeBase64URLString, encodeBase64URL } from "./base64.js";
 import { getBytes, requireBytes } from "./bytes.js";
 import { DAY, MINUTE, SECOND } from "./constants.js";
+import { requireDate } from "./date.js";
 // Constants.
 const HASH = "SHA-512";
 const ALGORITHM = { name: "HMAC", hash: HASH };
 const HEADER = { alg: "HS512", typ: "JWT" };
-const EXPIRY_MS = DAY * 10;
 const SKEW_MS = MINUTE; // Allow 1 minute clock skew.
 const SECRET_BYTES = 64; // Minimum 64 bytes / 512 bits
 function _getKey(caller, secret, ...usages) {
@@ -23,15 +23,22 @@ function _getKey(caller, secret, ...usages) {
  * Encode a JWT and return the string token.
  * - Currently only supports HMAC SHA-512 signing.
  *
+ * @param claims The payload claims to include in the JWT.
+ * @param secret The secret key to sign the JWT with.
+ * @param expiry The expiry time in milliseconds (defaults to 30 days).
+ *
  * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
  */
-export async function encodeToken(claims, secret) {
+export async function encodeToken({ nbf = "now", iat = "now", exp = DAY * 30, ...claims }, secret) {
     // Encode header.
     const header = encodeBase64URL(JSON.stringify(HEADER));
     // Encode payload.
-    const now = Math.floor(Date.now() / 1000);
-    const exp = Math.floor(now + EXPIRY_MS / 1000);
-    const payload = encodeBase64URL(JSON.stringify({ nbf: now, iat: now, exp, ...claims }));
+    const payload = encodeBase64URL(JSON.stringify({
+        nbf: requireDate(nbf).getTime() / 1000, // By JWT convention, times are in seconds.
+        iat: requireDate(iat).getTime() / 1000, // By JWT convention, times are in seconds.
+        exp: (Date.now() + exp) / 1000, // By JWT convention, times are in seconds.
+        ...claims,
+    }));
     // Create signature.
     const key = await _getKey(encodeToken, secret, "sign");
     const signature = encodeBase64URL(await crypto.subtle.sign("HMAC", key, requireBytes(`${header}.${payload}`)));
@@ -93,12 +100,10 @@ export async function verifyToken(token, secret, caller = verifyToken) {
     if (!isValid)
         throw new UnauthorizedError("JWT signature does not match", { received: token, caller });
     // Validate payload.
-    const { nbf, iat, exp } = payloadData;
+    const { nbf, exp } = payloadData;
     const now = Date.now();
     if (typeof nbf === "number" && now < nbf * SECOND - SKEW_MS)
         throw new UnauthorizedError("JWT cannot be used yet", { received: payloadData, expected: now, caller });
-    if (typeof iat === "number" && now < iat * SECOND - SKEW_MS)
-        throw new UnauthorizedError("JWT not issued yet", { received: payloadData, expected: now, caller });
     if (typeof exp === "number" && now > exp * SECOND + SKEW_MS)
         throw new UnauthorizedError("JWT has expired", { received: payloadData, expected: now, caller });
     return payloadData;