Improve, extend, fix types, test and code

Author: flevi29

src/token.ts

@@ -1,4 +1,18 @@
-import type { TenantTokenGeneratorOptions } from "./types";
+import type { TenantTokenGeneratorOptions, TokenSearchRules } from "./types";
+
+function getOptionsWithDefaults(options: TenantTokenGeneratorOptions) {
+  const {
+    searchRules = [],
+    algorithm = "HS256",
+    force = false,
+    ...restOfOptions
+  } = options;
+  return { searchRules, algorithm, force, ...restOfOptions };
+}
+
+type TenantTokenGeneratorOptionsWithDefaults = ReturnType<
+  typeof getOptionsWithDefaults
+>;
 
 const UUID_V4_REGEXP = /^[0-9a-f]{8}\b(?:-[0-9a-f]{4}\b){3}-[0-9a-f]{12}$/i;
 function isValidUUIDv4(uuid: string): boolean {
@@ -21,18 +35,21 @@ const textEncoder = new TextEncoder();
 
 /** Create the signature of the token. */
 async function sign(
-  apiKey: string,
+  { apiKey, algorithm }: TenantTokenGeneratorOptionsWithDefaults,
   encodedPayload: string,
   encodedHeader: string,
 ): Promise<string> {
   const crypto = await cryptoPonyfill;
 
   const cryptoKey = await crypto.subtle.importKey(
+    // https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#raw
     "raw",
     textEncoder.encode(apiKey),
-    // TODO: Does alg depend on this too?
-    { name: "HMAC", hash: "SHA-256" },
+    // https://developer.mozilla.org/en-US/docs/Web/API/HmacImportParams#instance_properties
+    { name: "HMAC", hash: `SHA-${algorithm.slice(2)}` },
+    // https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#extractable
     false,
+    // https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#keyusages
     ["sign"],
   );
 
@@ -53,32 +70,39 @@ async function sign(
 
 /** Create the header of the token. */
 function getHeader({
-  algorithm: alg = "HS256",
-}: TenantTokenGeneratorOptions): string {
+  algorithm: alg,
+}: TenantTokenGeneratorOptionsWithDefaults): string {
   const header = { alg, typ: "JWT" };
   return encodeToBase64(header).replace(/=/g, "");
 }
 
+/**
+ * @see {@link https://www.meilisearch.com/docs/learn/security/tenant_token_reference | Tenant token payload reference}
+ * @see {@link https://github.com/meilisearch/meilisearch/blob/b21d7aedf9096539041362d438e973a18170f3fc/crates/meilisearch/src/extractors/authentication/mod.rs#L334-L340 | GitHub source code}
+ */
+type TokenClaims = {
+  searchRules: TokenSearchRules;
+  exp?: number;
+  apiKeyUid: string;
+};
+
 /** Create the payload of the token. */
 function getPayload({
-  searchRules = [],
+  searchRules,
   apiKeyUid,
   expiresAt,
-}: TenantTokenGeneratorOptions): string {
+}: TenantTokenGeneratorOptionsWithDefaults): string {
   if (!isValidUUIDv4(apiKeyUid)) {
     throw new Error("the uid of your key is not a valid UUIDv4");
   }
 
-  const payload = {
-    searchRules,
-    apiKeyUid,
-    exp: expiresAt
-      ? Math.floor(
-          (typeof expiresAt === "number" ? expiresAt : expiresAt.getTime()) /
-            1000,
-        )
-      : undefined,
-  };
+  const payload: TokenClaims = { searchRules, apiKeyUid };
+  if (expiresAt !== undefined) {
+    payload.exp =
+      typeof expiresAt === "number"
+        ? expiresAt
+        : Math.floor(expiresAt.getTime() / 1000);
+  }
 
   return encodeToBase64(payload).replace(/=/g, "");
 }
@@ -87,13 +111,14 @@ function getPayload({
  * Try to detect if the script is running in a server-side runtime.
  *
  * @remarks
- * This is not a silver bullet method for determining the environment.
+ * There is no silver bullet way for determining the environment. Even so, this
+ * is the recommended way according to
+ * {@link https://min-common-api.proposal.wintercg.org/#navigator-useragent-requirements | WinterCG specs}.
  * {@link https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent | User agent }
- * can be spoofed, `process` can be patched. Never the less theoretically it
- * should prevent misuse for the overwhelming majority of cases.
+ * can be spoofed, `process` can be patched. It should prevent misuse for the
+ * overwhelming majority of cases.
  */
 function tryDetectEnvironment(): void {
-  // https://min-common-api.proposal.wintercg.org/#navigator-useragent-requirements
   if (
     typeof navigator !== "undefined" &&
     Object.hasOwn(navigator, "userAgent")
@@ -120,31 +145,40 @@ function tryDetectEnvironment(): void {
     return;
   }
 
-  throw new Error("TODO");
+  throw new Error(
+    "failed to detect a server-side environment; do not generate tokens on the frontend in production!\n" +
+      "use the `force` option to disable environment detection, consult the documentation (Use at your own risk!)",
+  );
 }
 
 /**
  * Generate a tenant token.
  *
  * @remarks
- * TODO: Describe how this should be used safely.
+ * Warning: while this can be used in browsers with
+ * {@link TenantTokenGeneratorOptions.force}, it is only intended for server
+ * side. Don't use this in production on the frontend, unless you really know
+ * what you're doing!
  * @param options - Options object for tenant token generation
  * @returns The token in JWT (JSON Web Token) format
- * @see {@link https://www.meilisearch.com/docs/learn/security/generate_tenant_token_sdk | Using tenant tokens with an official SDK}
- * @see {@link https://www.meilisearch.com/docs/learn/security/tenant_token_reference | Tenant token payload reference}
+ * @see {@link https://www.meilisearch.com/docs/learn/security/basic_security | Securing your project}
  */
 export async function generateTenantToken(
   options: TenantTokenGeneratorOptions,
 ): Promise<string> {
-  const { apiKey, force = false } = options;
+  const optionsWithDefaults = getOptionsWithDefaults(options);
 
-  if (!force) {
+  if (!optionsWithDefaults.force) {
     tryDetectEnvironment();
   }
 
-  const encodedPayload = getPayload(options);
-  const encodedHeader = getHeader(options);
-  const signature = await sign(apiKey, encodedPayload, encodedHeader);
+  const encodedPayload = getPayload(optionsWithDefaults);
+  const encodedHeader = getHeader(optionsWithDefaults);
+  const signature = await sign(
+    optionsWithDefaults,
+    encodedPayload,
+    encodedHeader,
+  );
 
   return `${encodedHeader}.${encodedPayload}.${signature}`;
 }

src/types/types.ts

@@ -1124,16 +1124,20 @@ export type TokenSearchRules =
 
 /** Options object for tenant token generation. */
 export type TenantTokenGeneratorOptions = {
+  /** API key used to sign the token. */
+  apiKey: string;
   /**
    * The uid of the api key used as issuer of the token.
    *
    * @see {@link https://www.meilisearch.com/docs/learn/security/tenant_token_reference#api-key-uid}
    */
   apiKeyUid: string;
-  /** Search rules that are applied to every search. */
+  /**
+   * Search rules that are applied to every search.
+   *
+   * @defaultValue `[]`
+   */
   searchRules?: TokenSearchRules;
-  /** API key used to sign the token. */
-  apiKey: string;
   /**
    * {@link https://en.wikipedia.org/wiki/Unix_time | UNIX timestamp} or
    * {@link Date} object at which the token expires.
@@ -1142,13 +1146,20 @@ export type TenantTokenGeneratorOptions = {
    */
   expiresAt?: number | Date;
   /**
-   * Encryption algorithm used by TODO what. Supported values are HS256, HS384,
-   * HS512.
+   * Encryption algorithm used to sign the JWT. Supported values by Meilisearch
+   * are HS256, HS384, HS512. (HS[number] means HMAC using SHA-[number])
+   *
+   * @defaultValue `"HS256"`
+   * @see {@link https://www.meilisearch.com/docs/learn/security/generate_tenant_token_scratch#prepare-token-header}
    */
   algorithm?: `HS${256 | 384 | 512}`;
   /**
    * By default if a non-safe environment is detected, an error is thrown.
-   * Setting this to `true` skips environment detection.
+   * Setting this to `true` skips environment detection. This is intended for
+   * server-side environments where detection fails or usage in a browser is
+   * intentional (Use at your own risk).
+   *
+   * @defaultValue `false`
    */
   force?: boolean;
 };