@canva/cli 0.0.1-beta.1

package/templates/dam/backend/routers/auth.ts

@@ -0,0 +1,285 @@
+import * as chalk from "chalk";
+import * as crypto from "crypto";
+import "dotenv/config";
+import * as express from "express";
+import * as cookieParser from "cookie-parser";
+import * as basicAuth from "express-basic-auth";
+import { JSONFileDatabase } from "../database/database";
+import { getTokenFromQueryString } from "../../utils/backend/jwt_middleware/jwt_middleware";
+import { createJwtMiddleware } from "../../utils/backend/jwt_middleware";
+
+/**
+ * These are the hard-coded credentials for logging in to this template.
+ */
+const USERNAME = "username";
+const PASSWORD = "password";
+
+const COOKIE_EXPIRY_MS = 5 * 60 * 1000; // 5 minutes
+
+const CANVA_BASE_URL = "https://canva.com";
+
+interface Data {
+  users: string[];
+}
+
+/**
+ * For more information on Authentication, refer to our documentation: {@link https://www.canva.dev/docs/apps/authenticating-users/#types-of-authentication}.
+ */
+export const createAuthRouter = () => {
+  const APP_ID = getAppId();
+
+  /**
+   * Set up a database with a "users" table. In this example code, the
+   * database is simply a JSON file.
+   */
+  const db = new JSONFileDatabase<Data>({ users: [] });
+
+  const router = express.Router();
+
+  /**
+   * The `cookieParser` middleware allows the routes to read and write cookies.
+   *
+   * By passing a value into the middleware, we enable the "signed cookies" feature of Express.js. The
+   * value should be static and cryptographically generated. If it's dynamic (as shown below), cookies
+   * won't persist between server restarts.
+   *
+   * TODO: Replace `crypto.randomUUID()` with a static value, loaded via an environment variable.
+   */
+  router.use(cookieParser(crypto.randomUUID()));
+
+  /**
+   * This endpoint is hit at the start of the authentication flow. It contains a state which must
+   * be passed back to canva so that Canva can verify the response. It must also set a nonce in the
+   * user's browser cookies and send the nonce back to Canva as a url parameter.
+   *
+   * If Canva can validate the state, it will then redirect back to the chosen redirect url.
+   */
+  router.get("/configuration/start", async (req, res) => {
+    /**
+     * Generate a unique nonce for each request. A nonce is a random, single-use value
+     * that's impossible to guess or enumerate. We recommended using a Version 4 UUID that
+     * is cryptographically secure, such as one generated by the `randomUUID` method.
+     */
+    const nonce = crypto.randomUUID();
+    // Set the expiry time for the nonce. We recommend 5 minutes.
+    const expiry = Date.now() + COOKIE_EXPIRY_MS;
+
+    // Create a JSON string that contains the nonce and an expiry time
+    const nonceWithExpiry = JSON.stringify([nonce, expiry]);
+
+    // Set a cookie that contains the nonce and the expiry time
+    res.cookie("nonce", nonceWithExpiry, {
+      secure: true,
+      httpOnly: true,
+      maxAge: COOKIE_EXPIRY_MS,
+      signed: true,
+    });
+
+    // Create the query parameters that Canva requires
+    const params = new URLSearchParams({
+      nonce,
+      state: req?.query?.state?.toString() || "",
+    });
+
+    // Redirect to Canva with required parameters
+    res.redirect(302, `${CANVA_BASE_URL}/apps/configure/link?${params}`);
+  });
+
+  /**
+   * This endpoint renders a login page. Once the user logs in, they're
+   * redirected back to Canva, which completes the authentication flow.
+   */
+  router.get(
+    "/redirect-url",
+    /**
+     * Use a JSON Web Token (JWT) to verify incoming requests. The JWT is
+     * extracted from the `canva_user_token` parameter.
+     */
+    createJwtMiddleware(APP_ID, getTokenFromQueryString),
+    /**
+     * Warning: For demonstration purposes, we're using basic authentication and
+     * hard- coding a username and password. This is not a production-ready
+     * solution!
+     */
+    basicAuth({
+      users: { [USERNAME]: PASSWORD },
+      challenge: true,
+    }),
+    async (req, res) => {
+      const failureResponse = () => {
+        const params = new URLSearchParams({
+          success: "false",
+          state: req.query.state?.toString() || "",
+        });
+        res.redirect(302, `${CANVA_BASE_URL}/apps/configured?${params}`);
+      };
+
+      // Get the nonce and expiry time stored in the cookie.
+      const cookieNonceAndExpiry = req.signedCookies.nonce;
+
+      // Get the nonce from the query parameter.
+      const queryNonce = req.query.nonce?.toString();
+
+      // After reading the cookie, clear it. This forces abandoned auth flows to be restarted.
+      res.clearCookie("nonce");
+
+      let cookieNonce = "";
+      let expiry = 0;
+
+      try {
+        [cookieNonce, expiry] = JSON.parse(cookieNonceAndExpiry);
+      } catch {
+        // If the nonce can't be parsed, assume something has been compromised and exit.
+        return failureResponse();
+      }
+
+      // If the nonces are empty, exit the authentication flow.
+      if (
+        isEmpty(cookieNonceAndExpiry) ||
+        isEmpty(queryNonce) ||
+        isEmpty(cookieNonce)
+      ) {
+        return failureResponse();
+      }
+
+      /**
+       * Check that:
+       *
+       * - The nonce in the cookie and query parameter contain the same value
+       * - The nonce has not expired
+       *
+       * **Note:** We could rely on the cookie expiry, but that is vulnerable to tampering
+       * with the browser's time. This allows us to double-check based on server time.
+       */
+      if (expiry < Date.now() || cookieNonce !== queryNonce) {
+        return failureResponse();
+      }
+
+      // Get the userId from JWT middleware
+      const { userId } = req.canva;
+
+      // Load the database
+      const data = await db.read();
+
+      // Add the user to the database
+      if (!data.users.includes(userId)) {
+        data.users.push(userId);
+        await db.write(data);
+      }
+
+      // Create query parameters for redirecting back to Canva
+      const params = new URLSearchParams({
+        success: "true",
+        state: req?.query?.state?.toString() || "",
+      });
+
+      // Redirect the user back to Canva
+      res.redirect(302, `${CANVA_BASE_URL}/apps/configured?${params}`);
+    },
+  );
+
+  /**
+   * TODO: Add this middleware to all routes that will receive requests from
+   * your app.
+   */
+  const jwtMiddleware = createJwtMiddleware(APP_ID);
+
+  /**
+   * This endpoint is called when a user disconnects an app from their account.
+   * The app is expected to de-authenticate the user on its backend, so if the
+   * user reconnects the app, they'll need to re-authenticate.
+   *
+   * Note: The name of the endpoint is *not* configurable.
+   *
+   * Note: This endpoint is called by Canva's backend directly and must be
+   * exposed via a public URL. To test this endpoint, add a proxy URL, such as
+   * one generated by nGrok, to the 'Add authentication' section in the
+   * Developer Portal. Localhost addresses will not work to test this endpoint.
+   */
+  router.post("/configuration/delete", jwtMiddleware, async (req, res) => {
+    // Get the userId from JWT middleware
+    const { userId } = req.canva;
+
+    // Load the database
+    const data = await db.read();
+
+    // Remove the user from the database
+    await db.write({
+      users: data.users.filter((user) => user !== userId),
+    });
+
+    // Confirm that the user was removed
+    res.send({
+      type: "SUCCESS",
+    });
+  });
+
+  /**
+   * All routes that start with /api will be protected by JWT authentication
+   */
+  router.use("/api", jwtMiddleware);
+
+  /**
+   * This endpoint checks if a user is authenticated.
+   */
+  router.post("/api/authentication/status", async (req, res) => {
+    // Load the database
+    const data = await db.read();
+
+    // Check if the user is authenticated
+    const isAuthenticated = data.users.includes(req.canva.userId);
+
+    // Return the authentication status
+    res.send({
+      isAuthenticated,
+    });
+  });
+
+  return router;
+};
+
+/**
+ * Checks if a given param is nullish or an empty string
+ *
+ * @param str The string to check
+ * @returns true if the string is nullish or empty, false otherwise
+ */
+function isEmpty(str?: string): boolean {
+  return str == null || str.length === 0;
+}
+
+/**
+ * Retrieves the CANVA_APP_ID from the environment variables.
+ * Throws an error if the CANVA_APP_ID environment variable is undefined or set to a default value.
+ *
+ * @returns {string} The Canva App ID
+ * @throws {Error} If CANVA_APP_ID environment variable is undefined or set to a default value
+ */
+function getAppId(): string {
+  // TODO: Set the CANVA_APP_ID environment variable in the project's .env file
+  const appId = process.env.CANVA_APP_ID;
+
+  if (!appId) {
+    throw new Error(
+      `The CANVA_APP_ID environment variable is undefined. Set the variable in the project's .env file.`,
+    );
+  }
+
+  if (appId === "YOUR_APP_ID_HERE") {
+    // eslint-disable-next-line no-console
+    console.log(
+      chalk.bgRedBright(
+        "Default 'CANVA_APP_ID' environment variable detected.",
+      ),
+    );
+    // eslint-disable-next-line no-console
+    console.log(
+      "Please update the 'CANVA_APP_ID' environment variable in your project's `.env` file " +
+        `with the App ID obtained from the Canva Developer Portal: ${chalk.greenBright(
+          "https://www.canva.com/developers/apps",
+        )}\n`,
+    );
+  }
+
+  return appId;
+}

package/templates/dam/backend/routers/dam.ts

@@ -0,0 +1,86 @@
+import * as express from "express";
+import * as crypto from "crypto";
+import type {
+  Container,
+  FindResourcesRequest,
+  Resource,
+} from "@canva/app-components";
+
+/**
+ * Generates a unique hash for a url.
+ * Handy for uniquely identifying an image and creating an image id
+ */
+export async function generateHash(message: string) {
+  const msgUint8 = new TextEncoder().encode(message);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", msgUint8);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hashHex = hashArray
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  return hashHex;
+}
+
+const imageUrls = [
+  "https://cdn.pixabay.com/photo/2023/09/16/18/26/hummingbird-8257355_1280.jpg",
+  "https://cdn.pixabay.com/photo/2023/12/10/03/00/peacock-8440548_1280.jpg",
+  "https://cdn.pixabay.com/photo/2023/12/20/07/04/mountains-8459056_1280.jpg",
+  "https://cdn.pixabay.com/photo/2023/11/26/07/29/sparrow-8413000_1280.jpg",
+  "https://cdn.pixabay.com/photo/2023/12/12/16/11/mountain-8445543_1280.jpg",
+];
+
+export const createDamRouter = () => {
+  const router = express.Router();
+
+  /**
+   * This endpoint returns the data for your app.
+   *
+   * TODO: you must change this path to `/api/resources/find` before
+   * submitting to ensure a user is authenticated
+   */
+  router.post("/resources/find", async (req, res) => {
+    // You should modify these lines to return data from your
+    // digital asset manager (DAM) based on the findResourcesRequest
+    const findResourcesRequest: FindResourcesRequest = req.body;
+    const { types } = findResourcesRequest;
+
+    let resources: Resource[] = [];
+    if (types.includes("IMAGE")) {
+      resources = await Promise.all(
+        Array.from({ length: 40 }, async (_, i) => ({
+          id: await generateHash(imageUrls[i % imageUrls.length]),
+          mimeType: "image/jpeg",
+          name: "My new thing",
+          type: "IMAGE",
+          thumbnail: {
+            url: imageUrls[i % imageUrls.length],
+          },
+          url: imageUrls[i % imageUrls.length],
+        })),
+      );
+    }
+
+    if (types.includes("CONTAINER")) {
+      const containers = await Promise.all(
+        Array.from(
+          { length: 10 },
+          async (_, i) =>
+            ({
+              id: await generateHash(i + ""),
+              containerType: "folder",
+              name: `My folder ${i}`,
+              type: "CONTAINER",
+            }) satisfies Container,
+        ),
+      );
+
+      resources = resources.concat(containers);
+    }
+
+    res.send({
+      resources,
+      continuation: +(findResourcesRequest.continuation || 0) + 1,
+    });
+  });
+
+  return router;
+};

package/templates/dam/backend/server.ts

@@ -0,0 +1,65 @@
+import * as express from "express";
+import * as cors from "cors";
+import { createBaseServer } from "../utils/backend/base_backend/create";
+import { createDamRouter } from "./routers/dam";
+import { createAuthRouter } from "./routers/auth";
+
+async function main() {
+  // TODO: Set the CANVA_APP_ID environment variable in the project's .env file
+  const APP_ID = process.env.CANVA_APP_ID;
+
+  if (!APP_ID) {
+    throw new Error(
+      `The CANVA_APP_ID environment variable is undefined. Set the variable in the project's .env file.`,
+    );
+  }
+
+  const router = express.Router();
+
+  /**
+   * TODO: Configure your CORS Policy
+   *
+   * Cross-Origin Resource Sharing
+   * ([CORS](https://developer.mozilla.org/en-US/docs/Glossary/CORS)) is an
+   * [HTTP](https://developer.mozilla.org/en-US/docs/Glossary/HTTP)-header based
+   * mechanism that allows a server to indicate any
+   * [origins](https://developer.mozilla.org/en-US/docs/Glossary/Origin)
+   * (domain, scheme, or port) other than its own from which a browser should
+   * permit loading resources.
+   *
+   * A basic CORS configuration would include the origin of your app in the
+   * following example:
+   * const corsOptions = {
+   *   origin: 'https://app-abcdefg.canva-apps.com',
+   *   optionsSuccessStatus: 200
+   * }
+   *
+   * The origin of your app is https://app-${APP_ID}.canva-apps.com, and note
+   * that the APP_ID should to be converted to lowercase.
+   *
+   * https://www.npmjs.com/package/cors#configuring-cors
+   *
+   * You may need to include multiple permissible origins, or dynamic origins
+   * based on the environment in which the server is running. Further
+   * information can be found
+   * [here](https://www.npmjs.com/package/cors#configuring-cors-w-dynamic-origin).
+   */
+  router.use(cors());
+
+  /**
+   * Add routes for authorisation.
+   */
+  const authRouter = createAuthRouter();
+  router.use(authRouter);
+
+  /**
+   * Add routes for digital asset management.
+   */
+  const damRouter = createDamRouter();
+  router.use(damRouter);
+
+  const server = createBaseServer(router);
+  server.start(process.env.CANVA_BACKEND_PORT);
+}
+
+main();

package/templates/dam/declarations/declarations.d.ts

@@ -0,0 +1,29 @@
+declare module "*.css" {
+  const styles: { [className: string]: string };
+  export = styles;
+}
+
+declare module "*.jpg" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.jpeg" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.png" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.svg" {
+  const content: React.FunctionComponent<{
+    size?: "tiny" | "small" | "medium" | "large";
+    className?: string;
+  }>;
+  export default content;
+}
+
+declare const BACKEND_HOST: string;