@canva/cli 0.0.1-beta.1

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@canva/cli",
+  "version": "0.0.1-beta.1",
+  "description": "The official Canva CLI.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "Canva Pty Ltd.",
+  "type": "module",
+  "bin": {
+    "canva": "./cli.js"
+  },
+  "files": [
+    "templates",
+    "cli.js",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "dependencies": {
+    "ink": "5.0.1",
+    "react": "18.3.1"
+  },
+  "keywords": [
+    "apps sdk",
+    "canva",
+    "cli",
+    "starter kit"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}

package/templates/base/backend/database/database.ts

@@ -0,0 +1,42 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+
+/**
+ * This file creates a "database" out of a JSON file. It's only for
+ * demonstration purposes. A real app should use a real database.
+ */
+const DATABASE_FILE_PATH = path.join(__dirname, "db.json");
+
+interface Database<T> {
+  read(): Promise<T>;
+  write(data: T): Promise<void>;
+}
+
+export class JSONFileDatabase<T> implements Database<T> {
+  constructor(private readonly seedData: T) {}
+
+  // Creates a database file if one doesn't already exist
+  private async init(): Promise<void> {
+    try {
+      // Do nothing, since the database is initialized
+      await fs.stat(DATABASE_FILE_PATH);
+    } catch {
+      const file = JSON.stringify(this.seedData);
+      await fs.writeFile(DATABASE_FILE_PATH, file);
+    }
+  }
+
+  // Loads and parses the database file
+  async read(): Promise<T> {
+    await this.init();
+    const file = await fs.readFile(DATABASE_FILE_PATH, "utf8");
+    return JSON.parse(file);
+  }
+
+  // Overwrites the database file with provided data
+  async write(data: T): Promise<void> {
+    await this.init();
+    const file = JSON.stringify(data);
+    await fs.writeFile(DATABASE_FILE_PATH, file);
+  }
+}

package/templates/base/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/base/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;

package/templates/base/eslint.config.mjs

@@ -0,0 +1,309 @@
+import typescriptEslint from "@typescript-eslint/eslint-plugin";
+import jest from "eslint-plugin-jest";
+import react from "eslint-plugin-react";
+import globals from "globals";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import js from "@eslint/js";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended,
+  allConfig: js.configs.all,
+});
+
+export default [
+  {
+    ignores: [
+      "**/node_modules/",
+      "**/dist",
+      "**/*.d.ts",
+      "**/*.d.tsx",
+      "**/sdk",
+      "**/internal",
+      "**/*.config.*",
+    ],
+  },
+  ...compat.extends(
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/strict",
+    "plugin:@typescript-eslint/stylistic",
+    "plugin:react/recommended",
+    "plugin:jest/recommended"
+  ),
+  {
+    plugins: {
+      "@typescript-eslint": typescriptEslint,
+      jest,
+      react,
+    },
+    languageOptions: {
+      globals: {
+        ...globals.serviceworker,
+        ...globals.browser,
+      },
+    },
+    settings: {
+      react: {
+        version: "detect",
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-non-null-assertion": "warn",
+      "@typescript-eslint/no-empty-function": "off",
+      "@typescript-eslint/consistent-type-imports": "error",
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@typescript-eslint/no-empty-interface": "warn",
+      "@typescript-eslint/consistent-type-definitions": "off",
+      "@typescript-eslint/explicit-member-accessibility": [
+        "error",
+        {
+          accessibility: "no-public",
+          overrides: {
+            parameterProperties: "off",
+          },
+        },
+      ],
+      "@typescript-eslint/naming-convention": [
+        "error",
+        {
+          selector: "typeLike",
+          format: ["PascalCase"],
+          leadingUnderscore: "allow",
+        },
+      ],
+      "no-invalid-this": "off",
+      "@typescript-eslint/no-invalid-this": "error",
+      "@typescript-eslint/no-unused-expressions": [
+        "error",
+        {
+          allowShortCircuit: true,
+          allowTernary: true,
+        },
+      ],
+      "no-unused-vars": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          vars: "all",
+          varsIgnorePattern: "^_",
+          args: "none",
+          ignoreRestSiblings: true,
+        },
+      ],
+      "@typescript-eslint/no-require-imports": "error",
+      "jest/no-restricted-matchers": [
+        "error",
+        {
+          toContainElement:
+            "toContainElement is not recommended as it encourages testing the internals of the components",
+          toContainHTML:
+            "toContainHTML is not recommended as it encourages testing the internals of the components",
+          toHaveAttribute:
+            "toHaveAttribute is not recommended as it encourages testing the internals of the components",
+          toHaveClass:
+            "toHaveClass is not recommended as it encourages testing the internals of the components",
+          toHaveStyle:
+            "toHaveStyle is not recommended as it encourages testing the internals of the components",
+        },
+      ],
+      "react/jsx-curly-brace-presence": [
+        "error",
+        {
+          props: "never",
+          children: "never",
+        },
+      ],
+      "react/jsx-tag-spacing": [
+        "error",
+        {
+          closingSlash: "never",
+          beforeSelfClosing: "allow",
+          afterOpening: "never",
+          beforeClosing: "allow",
+        },
+      ],
+      "react/self-closing-comp": "error",
+      "react/no-unescaped-entities": "off",
+      "react/jsx-uses-react": "off",
+      "react/react-in-jsx-scope": "off",
+      "default-case": "error",
+      eqeqeq: [
+        "error",
+        "always",
+        {
+          null: "never",
+        },
+      ],
+      "no-caller": "error",
+      "no-console": "error",
+      "no-eval": "error",
+      "no-inner-declarations": "error",
+      "no-new-wrappers": "error",
+      "no-restricted-globals": [
+        "error",
+        {
+          name: "fit",
+          message: "Don't focus tests",
+        },
+        {
+          name: "fdescribe",
+          message: "Don't focus tests",
+        },
+        {
+          name: "length",
+          message:
+            "Undefined length - Did you mean to use window.length instead?",
+        },
+        {
+          name: "name",
+          message: "Undefined name - Did you mean to use window.name instead?",
+        },
+        {
+          name: "status",
+          message:
+            "Undefined status - Did you mean to use window.status instead?",
+        },
+        {
+          name: "spyOn",
+          message: "Don't use spyOn directly, use jest.spyOn",
+        },
+      ],
+      "no-restricted-properties": [
+        "error",
+        {
+          property: "bind",
+          message: "Don't o.f.bind(o, ...), use () => o.f(...)",
+        },
+        {
+          object: "ReactDOM",
+          property: "findDOMNode",
+          message: "Don't use ReactDOM.findDOMNode() as it is deprecated",
+        },
+      ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector: "AccessorProperty, TSAbstractAccessorProperty",
+          message:
+            "Accessor property syntax is not allowed, use getter and setters.",
+        },
+        {
+          selector: "PrivateIdentifier",
+          message:
+            "Private identifiers are not allowed, use TypeScript private fields.",
+        },
+        {
+          selector:
+            "JSXOpeningElement[name.name = /^[A-Z]/] > JSXAttribute[name.name = /-/]",
+          message:
+            "Passing hyphenated props to custom components is not type-safe. Prefer a camelCased equivalent if available. (See https://github.com/microsoft/TypeScript/issues/55182)",
+        },
+        {
+          selector:
+            "CallExpression[callee.object.name='window'][callee.property.name='open']",
+          message:
+            "Apps are currently not allowed to open popups, or new tabs via browser APIs. Please use `requestOpenExternalUrl` from `@canva/platform` to link to external URLs. To learn more, see https://www.canva.dev/docs/apps/api/platform-request-open-external-url/",
+        },
+      ],
+      "no-return-await": "error",
+      "no-throw-literal": "error",
+      "no-undef-init": "error",
+      "no-var": "error",
+      "object-shorthand": "error",
+      "prefer-const": [
+        "error",
+        {
+          destructuring: "all",
+        },
+      ],
+      "prefer-object-spread": "error",
+      "prefer-rest-params": "error",
+      "prefer-spread": "error",
+      radix: "error",
+    },
+  },
+  {
+    files: ["**/*.tsx"],
+    rules: {
+      "react/no-deprecated": "error",
+      "react/forbid-elements": [
+        "error",
+        {
+          forbid: [
+            {
+              element: "video",
+              message:
+                "Don't use HTML video directly. Instead, use the App UI Kit <VideoCard /> as this respects users' auto-playing preferences",
+            },
+            {
+              element: "em",
+              message:
+                "Don't use <em> to italicize text. Canva's UI fonts don't support italic font style.",
+            },
+            {
+              element: "i",
+              message:
+                "Don't use <i> to italicize text. Canva's UI fonts don't support italic font style.",
+            },
+            {
+              element: "iframe",
+              message:
+                "Canva Apps aren't allowed to contain iframes. You should either recreate the UI you want to show in the iframe in the app directly, or link to your page via a `<Link>` tag.  For more info see https://www.canva.dev/docs/apps/content-security-policy/#what-is-and-isnt-allowed",
+            },
+            {
+              element: "script",
+              message:
+                "Script tags are not allowed in Canva SDK Apps. You should import JavaScript modules instead. For more info see https://www.canva.dev/docs/apps/content-security-policy/#what-is-and-isnt-allowed",
+            },
+            {
+              element: "a",
+              message:
+                "Don't use <a> tags. Instead, use the <Link> component from the App UI Kit, and remember to open the url via the requestOpenExternalUrl method from @canva/platform.",
+            },
+            {
+              element: "img",
+              message:
+                "Have you considered using <ImageCard /> from the App UI Kit instead?",
+            },
+            {
+              element: "embed",
+              message:
+                "Have you considered using <EmbedCard /> from the App UI Kit instead?",
+            },
+            {
+              element: "audio",
+              message:
+                "Have you considered using <AudioCard /> from the App UI Kit instead?",
+            },
+            {
+              element: "button",
+              message:
+                "Rather than using the native HTML <button> element, use the <Button> component from the App UI Kit for consistency and accessibility.",
+            },
+            {
+              element: "input",
+              message:
+                "Wherever possible, prefer using the form inputs from the App UI Kit for consistency and accessibility (TextInput, Checkbox, FileInput, etc).",
+            },
+            {
+              element: "base",
+              message:
+                "The <base> tag is not supported in Canva Apps. We recommend using hash-based routing. For more on what is and isn't allowed in Canva Apps see https://www.canva.dev/docs/apps/content-security-policy/#what-is-and-isnt-allowed",
+            },
+            {
+              element: "link",
+              message:
+                "If you're trying to include a css stylesheet, we recommend importing css using React, or using embedded stylesheets. For more on what is and isn't allowed in Canva Apps see https://www.canva.dev/docs/apps/content-security-policy/#what-is-and-isnt-allowed",
+            },
+          ],
+        },
+      ],
+    },
+  },
+];