Merge pull request #417 from openformation/remix-logto

feat(remix): remix SDK

packages/remix/README.md

@@ -0,0 +1,132 @@
+# Logto Remix SDK
+[![Version](https://img.shields.io/npm/v/@logto/remix)](https://www.npmjs.com/package/@logto/remix)
+[![Build Status](https://github.com/logto-io/js/actions/workflows/main.yml/badge.svg)](https://github.com/logto-io/js/actions/workflows/main.yml)
+[![Codecov](https://img.shields.io/codecov/c/github/logto-io/js)](https://app.codecov.io/gh/logto-io/js?branch=master)
+
+The Logto Remix SDK written in TypeScript.
+
+## Installation
+
+### Using npm
+
+```bash
+npm install @logto/remix
+```
+
+### Using yarn
+
+```bash
+yarn add @logto/remix
+```
+
+### Using pnpm
+
+```bash
+pnpm add @logto/remix
+```
+
+## Usage
+
+Before initializing the SDK, we have to create a `SessionStorage` instance which takes care of the session persistence. In our case, we want to use a cookie-based session:
+
+```ts
+// services/authentication.ts
+import { createCookieSessionStorage } from "@remix-run/node";
+
+const sessionStorage = createCookieSessionStorage({
+  cookie: {
+    name: "logto-session",
+    maxAge: 14 * 24 * 60 * 60,
+    secrets: ["s3cret1"],
+  },
+});
+```
+
+Afterwards, we can initialize the SDK via:
+
+```ts
+// app/services/authentication.ts
+
+import { makeLogtoRemix } from "@logto/remix";
+
+export const logto = makeLogtoRemix(
+  {
+    endpoint: process.env.LOGTO_ENDPOINT!,
+    appId: process.env.LOGTO_APP_ID!,
+    appSecret: process.env.LOGTO_APP_SECRET!,
+    baseUrl: process.env.LOGTO_BASE_URL!,
+  },
+  { sessionStorage }
+);
+```
+
+Whereas the environment variables reflect the respective configuration of the application in Logto.
+
+### Mounting the authentication route handlers
+
+The SDK ships with a convenient function that mounts the authentication routes: sign-in, sign-in callback and the sign-out route:
+
+```ts
+// app/routes/api/logto/$action.ts
+
+import { logto } from "../../../services/authentication";
+
+export const loader = logto.handleAuthRoutes({
+  "sign-in": {
+    path: "/api/logto/sign-in",
+    redirectBackTo: "/api/logto/callback",
+  },
+  "sign-in-callback": {
+    path: "/api/logto/callback",
+    redirectBackTo: "/",
+  },
+  "sign-out": {
+    path: "/api/logto/sign-out",
+    redirectBackTo: "/",
+  },
+});
+```
+
+As you can see, the mount process is configurable and you can adjust it for your particular route structure. The whole URL path structure can be customized via the passed configuration object.
+
+When mounting the routes as described above, you can navigate your browser to `/api/logto/sign-in` and you should be redirected to your Logto instance where you have to authenticate then.
+
+### Get the authentication context
+
+A typical use case is to fetch the _authentication context_ which contains information about the respective user. With that information, it is possible to decide if the user is authenticated or not. The SDK exposes a function that can be used in a Remix `loader` function:
+
+```ts
+// app/routes/index.tsx
+import type { LogtoContext } from "@openformation/logto-remix";
+import { LoaderFunction, json } from "@remix-run/node";
+import { useLoaderData } from "@remix-run/react";
+
+import { logto } from "~/services/authentication";
+
+type LoaderResponse = {
+  readonly context: LogtoContext;
+};
+
+export const loader: LoaderFunction = async ({ request }) => {
+  const context = await logto.getContext({ includeAccessToken: false })(
+    request
+  );
+
+  if (!context.isAuthenticated) {
+    return redirect("/api/logto/sign-in");
+  }
+
+  return json<LoaderResponse>({ context });
+};
+
+const Home = () => {
+  const data = useLoaderData<LoaderResponse>();
+
+  return <div>Protected Route.</div>;
+};
+```
+
+## Resources
+
+[![Website](https://img.shields.io/badge/website-logto.io-8262F8.svg)](https://logto.io/)
+[![Discord](https://img.shields.io/discord/965845662535147551?logo=discord&logoColor=ffffff&color=7389D8&cacheSeconds=600)](https://discord.gg/UEPaF3j5e6)

packages/remix/jest.config.ts

@@ -0,0 +1,16 @@
+import type { Config } from '@jest/types';
+
+const config: Config.InitialOptions = {
+  roots: ["<rootDir>/src"],
+  collectCoverage: Boolean(process.env.CI),
+  transform: {
+    "^.+\\.(t|j)sx?$": [
+      "@swc/jest",
+      {
+        sourceMaps: true,
+      },
+    ],
+  }
+};
+
+export default config;

packages/remix/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@logto/remix",
+  "version": "1.0.0-beta.8",
+  "source": "./src/index.ts",
+  "main": "./lib/index.js",
+  "exports": {
+    "require": "./lib/index.js",
+    "import": "./lib/module.js"
+  },
+  "module": "./lib/module.js",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/logto-io/js.git",
+    "directory": "packages/remix"
+  },
+  "scripts": {
+    "dev:tsc": "tsc -p tsconfig.build.json -w --preserveWatchOutput",
+    "precommit": "lint-staged",
+    "check": "tsc --noEmit",
+    "build": "rm -rf lib/ && pnpm check && parcel build",
+    "lint": "eslint --ext .ts src",
+    "test": "jest",
+    "test:coverage": "jest --silent --coverage",
+    "prepack": "pnpm test"
+  },
+  "dependencies": {
+    "@logto/node": "^1.0.0-beta.8"
+  },
+  "devDependencies": {
+    "@jest/types": "^27.5.1",
+    "@parcel/core": "^2.7.0",
+    "@parcel/packager-ts": "^2.7.0",
+    "@parcel/transformer-typescript-types": "^2.7.0",
+    "@silverhand/eslint-config": "^1.0.0",
+    "@silverhand/ts-config": "^1.0.0",
+    "@silverhand/ts-config-react": "^1.0.0",
+    "eslint": "^8.23.0",
+    "jest-location-mock": "^1.0.9",
+    "jest-matcher-specific-error": "^1.0.0",
+    "parcel": "^2.7.0",
+    "@commitlint/cli": "^17.1.2",
+    "@commitlint/config-conventional": "^17.1.0",
+    "@tsconfig/recommended": "^1.0.1",
+    "@types/jest": "^29.1.2",
+    "@types/node": "^18.8.3",
+    "@remix-run/node": "^1.7.2",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
+    "jest": "^29.1.2",
+    "lint-staged": "^13.0.3",
+    "prettier": "^2.7.1",
+    "@swc/core": "^1.3.5",
+    "@swc/jest": "^0.2.23",
+    "typescript": "^4.8.4"
+  },
+  "peerDependencies": {
+    "@remix-run/node": ">=1"
+  },
+  "eslintConfig": {
+    "extends": "@silverhand"
+  },
+  "prettier": "@silverhand/eslint-config/.prettierrc",
+  "publishConfig": {
+    "access": "public"
+  },
+  "targets": {
+    "main": {
+      "context": "node",
+      "engines": {
+        "node": "^16"
+      }
+    }
+  }
+}

packages/remix/src/framework/get-cookie-header-from-request.ts

@@ -0,0 +1 @@
+export const getCookieHeaderFromRequest = (request: Request) => request.headers.get('Cookie');

packages/remix/src/framework/mocks.ts

@@ -0,0 +1,56 @@
+import { createSession, Session, SessionStorage } from '@remix-run/node';
+
+import { CreateLogtoAdapter, LogtoContext } from '../infrastructure/logto';
+import { createStorage } from '../infrastructure/logto/create-storage';
+
+const context: LogtoContext = {
+  isAuthenticated: true,
+  claims: {
+    email: 'test@test.io',
+    aud: '',
+    exp: 1_665_684_317,
+    iat: 1_665_684_318,
+    iss: '',
+    sub: '',
+  },
+};
+
+export const getContext = jest.fn(async () => ({
+  context,
+}));
+
+const session = createSession();
+export const storage = createStorage(session);
+
+export const handleSignIn = jest.fn(async () => ({
+  session,
+  navigateToUrl: '/success-handle-sign-in',
+}));
+
+export const handleSignInCallback = jest.fn(async () => ({
+  session,
+}));
+
+export const handleSignOut = jest.fn(async () => ({
+  navigateToUrl: '/success-handle-sign-out',
+}));
+
+export const createLogtoAdapter: CreateLogtoAdapter = jest.fn((session: Session) => {
+  return {
+    handleSignIn,
+    handleSignInCallback,
+    handleSignOut,
+    getContext,
+  };
+});
+
+// eslint-disable-next-line no-restricted-syntax
+export const commitSession = jest.fn(async (session: Session) => session.data as unknown as string);
+export const destroySession = jest.fn();
+export const getSession = jest.fn();
+
+export const sessionStorage: SessionStorage = {
+  commitSession,
+  destroySession,
+  getSession,
+};

packages/remix/src/index.ts

@@ -0,0 +1,39 @@
+import { LogtoConfig } from '@logto/node';
+import { SessionStorage } from '@remix-run/node';
+
+import { makeLogtoAdapter } from './infrastructure/logto';
+import { makeGetContext } from './useCases/getContext';
+import { makeHandleAuthRoutes } from './useCases/handleAuthRoutes';
+
+type Config = Readonly<LogtoConfig> & {
+  readonly baseUrl: string;
+};
+
+export const makeLogtoRemix = (
+  config: Config,
+  deps: {
+    sessionStorage: SessionStorage;
+  }
+) => {
+  const { sessionStorage } = deps;
+
+  const { baseUrl } = config;
+
+  const createLogtoAdapter = makeLogtoAdapter(config);
+
+  return Object.freeze({
+    handleAuthRoutes: makeHandleAuthRoutes({
+      baseUrl,
+      createLogtoAdapter,
+      sessionStorage,
+    }),
+
+    getContext: (dto: { includeAccessToken: boolean }) =>
+      makeGetContext(dto, {
+        createLogtoAdapter,
+        sessionStorage,
+      }),
+  });
+};
+
+export { type LogtoContext } from '@logto/node';

packages/remix/src/infrastructure/logto/create-client.spec.ts

@@ -0,0 +1,22 @@
+import { createSession } from '@remix-run/node';
+
+import { makeLogtoClient } from './create-client';
+import type { LogtoConfig } from './create-client';
+import { createStorage } from './create-storage';
+
+const config: LogtoConfig = {
+  appId: 'app_id_value',
+  endpoint: 'https://logto.dev',
+};
+
+describe('infrastructure:logto:createClient', () => {
+  it('creates an instance without crash', () => {
+    expect(() => {
+      const storage = createStorage(createSession());
+
+      const createLogtoClient = makeLogtoClient(config, storage);
+
+      createLogtoClient();
+    }).not.toThrow();
+  });
+});

packages/remix/src/infrastructure/logto/create-client.ts

@@ -0,0 +1,16 @@
+import LogtoClient, { LogtoConfig } from '@logto/node';
+
+import { LogtoStorage } from './create-storage';
+
+export const makeLogtoClient =
+  (config: LogtoConfig, storage: LogtoStorage) =>
+  // Have to deactivate the eslint rule here as the `LogtoClient`
+  // awaits a `navigate` function.
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  (navigate: (url: string) => void = () => {}) => {
+    return new LogtoClient(config, { storage, navigate });
+  };
+
+export type CreateLogtoClient = ReturnType<typeof makeLogtoClient>;
+
+export { type LogtoConfig } from '@logto/node';