@knocklabs/node 0.4.15 → 0.4.17

package/README.md

@@ -16,13 +16,16 @@ npm install @knocklabs/node
 
 To use the library you must provide a secret API key, provided in the Knock dashboard.
 
-You can set it as an environment variable:
+If you are using [enhanced security mode](https://docs.knock.app/client-integration/authenticating-users) you will also need to provide your signing key.
+
+You can set both as environment variables:
 
 ```bash
 KNOCK_API_KEY="sk_12345"
+KNOCK_SIGNING_KEY="S25vY2sga25vY2sh..."
 ```
 
-Or, you can set it before your application starts:
+You can also pass the Knock API key in the constructor. The signing key is passed separately to the `signUserToken` method (see below):
 
 ```javascript
 const { Knock } = require("@knocklabs/node");
@@ -135,27 +138,24 @@ await knockClient.users.getChannelData("jhammond", KNOCK_APNS_CHANNEL_ID);
 
 ### Signing JWTs
 
-You can use the `jsonwebtoken` package to [sign JWTs easily](https://www.npmjs.com/package/jsonwebtoken#jwtsignpayload-secretorprivatekey-options-callback).
-You will need to generate an environment specific signing key, which you can find in the Knock dashboard.
+When using [enhanced security mode](https://docs.knock.app/client-integration/authenticating-users) (recommended in production), you will need to sign JWTs server-side to authenticate your users.
 
-If you're using a signing token you will need to pass this to your client to perform authentication.
-You can read more about [client-side authentication here](https://docs.knock.app/client-integration/authenticating-users).
+You will need to generate an environment specific signing key in the Knock dashboard under "API Keys", and then enable enhanced security mode for your environment.
 
 ```javascript
-const jwt = require("jsonwebtoken");
-
-const currentTime = Math.floor(Date.now() / 1000);
-
-const token = jwt.sign(
-  {
-    // The user id to sign this key for
-    sub: "jhammond",
-    // When the token was issued
-    iat: currentTime,
-    // When the token expires (1 hour)
-    exp: currentTime + 60 * 60,
-  },
-  process.env.KNOCK_SIGNING_KEY,
-  { algorithm: "RS256" },
-);
+const { Knock } = require("@knocklabs/node");
+
+// When signing user tokens, you do not need to instantiate a Knock client.
+
+// jhammond is the user id for which to sign this token
+const token = Knock.signUserToken("jhammond", {
+  // The signing key from the Knock Dashboard in base-64 or PEM-encoded format.
+  // If not provided, the key will be read from the KNOCK_SIGNING_KEY environment variable.
+  signingKey: "S25vY2sga25vY2sh...",
+  // Optional: How long the token should be valid for, in seconds (default 1 hour)
+  // For long-lived connections, you will need to refresh the token before it expires.
+  expiresIn: 60 * 60,
+});
+
+// This token can now be safely passed to your client e.g. in a cookie or API response.
 ```

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@knocklabs/node",
-    "version": "0.4.15",
+    "version": "0.4.17",
     "description": "Library for interacting with the Knock API",
     "homepage": "https://github.com/knocklabs/knock-node",
     "author": "@knocklabs",
@@ -32,6 +32,7 @@
     },
     "devDependencies": {
         "@types/jest": "26.0.23",
+        "@types/jsonwebtoken": "^9.0.1",
         "@types/node": "^15.0.1",
         "@types/pluralize": "0.0.29",
         "axios-mock-adapter": "1.19.0",
@@ -43,6 +44,7 @@
         "typescript": "4.2.4"
     },
     "dependencies": {
-        "axios": "^0.21.1"
+        "axios": "^0.21.1",
+        "jsonwebtoken": "^9.0.0"
     }
 }

package/dist/src/common/exceptions.d.ts

@@ -4,6 +4,11 @@ export declare class NoApiKeyProvidedException extends Error {
     readonly name: string;
     readonly message: string;
 }
+export declare class NoSigningKeyProvidedException extends Error {
+    readonly status: number;
+    readonly name: string;
+    readonly message: string;
+}
 export declare class GenericServerException implements HttpException {
     readonly status: number;
     readonly requestID: string;

package/dist/src/common/exceptions.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BadRequestException = exports.UnprocessableEntityException = exports.NotFoundException = exports.UnauthorizedException = exports.GenericServerException = exports.NoApiKeyProvidedException = void 0;
+exports.BadRequestException = exports.UnprocessableEntityException = exports.NotFoundException = exports.UnauthorizedException = exports.GenericServerException = exports.NoSigningKeyProvidedException = exports.NoApiKeyProvidedException = void 0;
 class NoApiKeyProvidedException extends Error {
     constructor() {
         super(...arguments);
@@ -11,6 +11,17 @@ class NoApiKeyProvidedException extends Error {
     }
 }
 exports.NoApiKeyProvidedException = NoApiKeyProvidedException;
+class NoSigningKeyProvidedException extends Error {
+    constructor() {
+        super(...arguments);
+        this.status = 500;
+        this.name = "NoSigningKeyProvidedException";
+        this.message = `Missing or invalid signing key key. Pass it as an option to Knock.signUserToken(userId, {signingKey: "S25vY2sga25vY2sh..."}) ` +
+            `or define it in the KNOCK_SIGNING_KEY environment variable. The signing key can either be a Base-64 encoded string ` +
+            `or a PEM-encoded certificate. For more information, see https://docs.knock.app/in-app-ui/security-and-authentication#authentication-with-enhanced-security-enabled`;
+    }
+}
+exports.NoSigningKeyProvidedException = NoSigningKeyProvidedException;
 class GenericServerException {
     constructor(status, message, requestID) {
         this.status = status;

package/dist/src/common/interfaces.d.ts

@@ -28,11 +28,11 @@ declare type PageInfo = {
     after: string;
     page_size: number;
 };
-export interface PaginatedFeedResponse<T> {
+export interface PaginatedEntriesResponse<T> {
     entries: T[];
     page_info: PageInfo;
 }
-export interface PaginatedResponse<T> {
+export interface PaginatedItemsResponse<T> {
     items: T[];
     page_info: PageInfo;
 }
@@ -46,4 +46,12 @@ export interface Condition {
     variable: string;
     operator: string;
 }
+export interface SignUserTokenOptions {
+    /**
+     * The signing key to use to sign the token. If not provided, the KNOCK_SIGNING_KEY environment variable will be used.
+     */
+    signingKey?: string;
+    /** The expiration time of the token in seconds. Defaults to 1 hour. */
+    expiresInSeconds?: number;
+}
 export {};

package/dist/src/knock.d.ts

@@ -1,5 +1,5 @@
 import { AxiosResponse } from "axios";
-import { KnockOptions, PostAndPutOptions } from "./common/interfaces";
+import { KnockOptions, PostAndPutOptions, SignUserTokenOptions } from "./common/interfaces";
 import { Users } from "./resources/users";
 import { Preferences } from "./resources/preferences";
 import { Workflows } from "./resources/workflows";
@@ -22,6 +22,15 @@ declare class Knock {
     readonly tenants: Tenants;
     constructor(key?: string | undefined, options?: KnockOptions);
     notify(workflowKey: string, properties: TriggerWorkflowProperties): Promise<import("./resources/workflows/interfaces").WorkflowRun>;
+    /**
+     * Generate JWT for authenticating client-side requests (e.g. in-app feeds)
+     * For more information, visit https://docs.knock.app/in-app-ui/security-and-authentication#authentication-with-enhanced-security-enabled
+     *
+     * @param userId {string} The ID of the user that needs a token, e.g. the user viewing an in-app feed.
+     * @param options Optionally specify the signing key to use (in PEM or base-64 encoded format), and how long the token should be valid for in seconds
+     * @returns {string} A JWT token that can be used to authenticate requests to the Knock API (e.g. by passing into the <KnockFeedProvider /> component)
+     */
+    static signUserToken(userId: string, options: SignUserTokenOptions): string;
     post(path: string, entity: any, options?: PostAndPutOptions): Promise<AxiosResponse>;
     put(path: string, entity: any, options?: PostAndPutOptions): Promise<AxiosResponse>;
     delete(path: string, entity?: any): Promise<AxiosResponse>;

package/dist/src/knock.js

@@ -14,6 +14,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Knock = void 0;
 const axios_1 = __importDefault(require("axios"));
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const package_json_1 = require("../package.json");
 const exceptions_1 = require("./common/exceptions");
 const users_1 = require("./resources/users");
@@ -57,6 +58,29 @@ class Knock {
             return this.workflows.trigger(workflowKey, properties);
         });
     }
+    /**
+     * Generate JWT for authenticating client-side requests (e.g. in-app feeds)
+     * For more information, visit https://docs.knock.app/in-app-ui/security-and-authentication#authentication-with-enhanced-security-enabled
+     *
+     * @param userId {string} The ID of the user that needs a token, e.g. the user viewing an in-app feed.
+     * @param options Optionally specify the signing key to use (in PEM or base-64 encoded format), and how long the token should be valid for in seconds
+     * @returns {string} A JWT token that can be used to authenticate requests to the Knock API (e.g. by passing into the <KnockFeedProvider /> component)
+     */
+    static signUserToken(userId, options) {
+        var _a;
+        const signingKey = prepareSigningKey(options.signingKey);
+        // JWT NumericDates specified in seconds:
+        const currentTime = Math.floor(Date.now() / 1000);
+        // Default to 1 hour from now
+        const expireInSeconds = (_a = options.expiresInSeconds) !== null && _a !== void 0 ? _a : 60 * 60;
+        return jsonwebtoken_1.default.sign({
+            sub: userId,
+            iat: currentTime,
+            exp: currentTime + expireInSeconds,
+        }, signingKey, {
+            algorithm: "RS256",
+        });
+    }
     post(path, entity, options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
@@ -144,3 +168,14 @@ class Knock {
     }
 }
 exports.Knock = Knock;
+function prepareSigningKey(key) {
+    const maybeSigningKey = key !== null && key !== void 0 ? key : process.env.KNOCK_SIGNING_KEY;
+    if (!maybeSigningKey)
+        throw new exceptions_1.NoSigningKeyProvidedException();
+    if (maybeSigningKey.startsWith("-----BEGIN"))
+        return maybeSigningKey;
+    // LS0tLS1CRUdJTi is the base64 encoded version of "-----BEGIN"
+    if (maybeSigningKey.startsWith("LS0tLS1CRUdJTi"))
+        return Buffer.from(maybeSigningKey, "base64").toString("utf-8");
+    throw new exceptions_1.NoSigningKeyProvidedException();
+}

package/dist/src/resources/messages/index.d.ts

@@ -1,15 +1,15 @@
-import { PaginatedResponse, PaginationOptions } from "../../common/interfaces";
+import { PaginatedItemsResponse, PaginationOptions } from "../../common/interfaces";
 import { Message, MessageContent, MessageEvent, ListMessageActivitiesOptions, ListMessagesOptions, MessageEngagementStatus } from "./interfaces";
 import { Activity } from "../activities/interfaces";
 import { Knock } from "../../knock";
 export declare class Messages {
     readonly knock: Knock;
     constructor(knock: Knock);
-    list(filteringOptions?: ListMessagesOptions): Promise<PaginatedResponse<Message>>;
+    list(filteringOptions?: ListMessagesOptions): Promise<PaginatedItemsResponse<Message>>;
     get(messageId: string): Promise<Message>;
     getContent(messageId: string): Promise<MessageContent>;
-    getEvents(messageId: string, paginationOptions?: PaginationOptions): Promise<PaginatedResponse<MessageEvent>>;
-    getActivities(messageId: string, filteringOptions?: ListMessageActivitiesOptions): Promise<PaginatedResponse<Activity>>;
+    getEvents(messageId: string, paginationOptions?: PaginationOptions): Promise<PaginatedItemsResponse<MessageEvent>>;
+    getActivities(messageId: string, filteringOptions?: ListMessageActivitiesOptions): Promise<PaginatedItemsResponse<Activity>>;
     setStatus(messageId: string, status: MessageEngagementStatus): Promise<Message>;
     deleteStatus(messageId: string, status: MessageEngagementStatus): Promise<Message>;
     batchSetStatus(messageIds: string[], status: MessageEngagementStatus | "unseen" | "unread" | "unarchived"): Promise<Message[]>;

package/dist/src/resources/objects/index.d.ts

@@ -1,4 +1,4 @@
-import { ChannelData, CommonMetadata, SetChannelDataProperties, PaginatedResponse, ChannelType } from "../../common/interfaces";
+import { ChannelData, CommonMetadata, SetChannelDataProperties, PaginatedEntriesResponse, ChannelType, PaginatedItemsResponse } from "../../common/interfaces";
 import { Knock } from "../../knock";
 import { AddObjectSubscriptionProperties, BulkSetObjectOption, DeleteObjectSubscriptionProperties, ListObjectOptions, ListObjectSubscriptionsOptions, Object, ObjectSubscription, SetObjectProperties } from "./interfaces";
 import { BulkOperation } from "../bulk_operations/interfaces";
@@ -9,14 +9,14 @@ export declare class Objects {
     constructor(knock: Knock);
     get<T = CommonMetadata>(collection: string, id: string): Promise<Object<T>>;
     set<T = CommonMetadata>(collection: string, id: string, properties: SetObjectProperties): Promise<Object<T>>;
-    list<T = CommonMetadata>(collection: string, filteringOptions?: ListObjectOptions): Promise<PaginatedResponse<Object<T>>>;
+    list<T = CommonMetadata>(collection: string, filteringOptions?: ListObjectOptions): Promise<PaginatedEntriesResponse<Object<T>>>;
     bulkSet(collection: string, objects: BulkSetObjectOption[]): Promise<BulkOperation>;
     delete(collection: string, id: string): Promise<null>;
     bulkDelete(collection: string, objectIds: string[]): Promise<BulkOperation>;
     getChannelData<T = CommonMetadata>(collection: string, id: string, channelId: string): Promise<ChannelData<T>>;
     setChannelData<T = CommonMetadata>(collection: string, id: string, channelId: string, channelData: SetChannelDataProperties): Promise<ChannelData<T>>;
     unsetChannelData(collection: string, id: string, channelId: string): Promise<any>;
-    getMessages(collection: string, objectId: string, filteringOptions?: ListMessagesOptions): Promise<PaginatedResponse<Message>>;
+    getMessages(collection: string, objectId: string, filteringOptions?: ListMessagesOptions): Promise<PaginatedItemsResponse<Message>>;
     getAllPreferences(collection: string, objectId: string): Promise<PreferenceSet[]>;
     /**
      * @deprecated Use `objects.getPreferences` instead
@@ -30,7 +30,7 @@ export declare class Objects {
     setWorkflowPreferences(collection: string, objectId: string, workflowKey: string, setting: WorkflowPreferenceSetting, options?: PreferenceOptions): Promise<PreferenceSet>;
     setCategoriesPreferences(collection: string, objectId: string, categoryPreferences: WorkflowPreferences, options?: PreferenceOptions): Promise<PreferenceSet>;
     setCategoryPreferences(collection: string, objectId: string, categoryKey: string, setting: WorkflowPreferenceSetting, options?: PreferenceOptions): Promise<PreferenceSet>;
-    listSubscriptions(collection: string, objectId: string, options?: ListObjectSubscriptionsOptions): Promise<PaginatedResponse<ObjectSubscription>>;
+    listSubscriptions(collection: string, objectId: string, options?: ListObjectSubscriptionsOptions): Promise<PaginatedEntriesResponse<ObjectSubscription>>;
     addSubscriptions(collection: string, objectId: string, properties?: AddObjectSubscriptionProperties): Promise<ObjectSubscription[]>;
     deleteSubscriptions(collection: string, objectId: string, properties?: DeleteObjectSubscriptionProperties): Promise<ObjectSubscription[]>;
 }

package/dist/src/resources/tenants/index.d.ts

@@ -1,10 +1,10 @@
-import { CommonMetadata, PaginatedResponse } from "../../common/interfaces";
+import { CommonMetadata, PaginatedEntriesResponse } from "../../common/interfaces";
 import { Knock } from "../../knock";
 import { Tenant, SetTenant, ListTenantsOptions } from "./interfaces";
 export declare class Tenants {
     readonly knock: Knock;
     constructor(knock: Knock);
-    list(filteringOptions?: ListTenantsOptions): Promise<PaginatedResponse<Tenant>>;
+    list(filteringOptions?: ListTenantsOptions): Promise<PaginatedEntriesResponse<Tenant>>;
     get<T = CommonMetadata>(id: string): Promise<Tenant<T>>;
     set<T = CommonMetadata>(id: string, tenantData: SetTenant): Promise<Tenant<T>>;
     delete(id: string): Promise<null>;

package/dist/src/resources/users/index.d.ts

@@ -1,4 +1,4 @@
-import { ChannelData, ChannelType, CommonMetadata, PaginatedFeedResponse, PaginatedResponse } from "../../common/interfaces";
+import { ChannelData, ChannelType, CommonMetadata, PaginatedItemsResponse, PaginatedEntriesResponse } from "../../common/interfaces";
 import { BulkOperation } from "../bulk_operations/interfaces";
 import { ChannelTypePreferences, PreferenceOptions, PreferenceSet, SetPreferencesProperties, WorkflowPreferences, WorkflowPreferenceSetting } from "../preferences/interfaces";
 import { ListMessagesOptions, Message } from "../messages/interfaces";
@@ -10,11 +10,11 @@ export declare class Users {
     identify(userId: string, properties?: IdentifyProperties): Promise<User>;
     bulkIdentify(users: BulkIdentifyUser[]): Promise<BulkOperation>;
     get(userId: string): Promise<User>;
-    list(filteringOptions?: ListUserOptions): Promise<PaginatedResponse<User>>;
+    list(filteringOptions?: ListUserOptions): Promise<PaginatedEntriesResponse<User>>;
     delete(userId: string): Promise<null>;
     bulkDelete(userIds: string[]): Promise<BulkOperation>;
     merge(toUserId: string, fromUserId: string): Promise<User>;
-    getFeed(userId: string, channelId: string, feedOptions?: UserFeedOptions): Promise<PaginatedFeedResponse<any>>;
+    getFeed(userId: string, channelId: string, feedOptions?: UserFeedOptions): Promise<PaginatedEntriesResponse<any>>;
     getAllPreferences(userId: string): Promise<any>;
     /**
      * @deprecated Use `users.getPreferences` instead
@@ -32,5 +32,5 @@ export declare class Users {
     getChannelData<T = CommonMetadata>(userId: string, channelId: string): Promise<ChannelData<T>>;
     setChannelData<T = CommonMetadata>(userId: string, channelId: string, channelData: Record<string, any>): Promise<ChannelData<T>>;
     unsetChannelData(userId: string, channelId: string): Promise<any>;
-    getMessages(userId: string, filteringOptions?: ListMessagesOptions): Promise<PaginatedResponse<Message>>;
+    getMessages(userId: string, filteringOptions?: ListMessagesOptions): Promise<PaginatedItemsResponse<Message>>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knocklabs/node",
-  "version": "0.4.15",
+  "version": "0.4.17",
   "description": "Library for interacting with the Knock API",
   "homepage": "https://github.com/knocklabs/knock-node",
   "author": "@knocklabs",
@@ -32,6 +32,7 @@
   },
   "devDependencies": {
     "@types/jest": "26.0.23",
+    "@types/jsonwebtoken": "^9.0.1",
     "@types/node": "^15.0.1",
     "@types/pluralize": "0.0.29",
     "axios-mock-adapter": "1.19.0",
@@ -43,6 +44,7 @@
     "typescript": "4.2.4"
   },
   "dependencies": {
-    "axios": "^0.21.1"
+    "axios": "^0.21.1",
+    "jsonwebtoken": "^9.0.0"
   }
 }