@civic/auth 0.1.2 → 0.1.3

package/.turbo/turbo-build.log

@@ -1,13 +1,13 @@
 
 
-> @civic/auth@0.1.2-beta.0 build /Users/kevincolgan/code/civic-auth/packages/civic-auth-client
+> @civic/auth@0.1.2 build /Users/kevincolgan/code/civic-auth/packages/civic-auth-client
 > pnpm build:cjs && pnpm build:esm
 
 
-> @civic/auth@0.1.2-beta.0 build:cjs /Users/kevincolgan/code/civic-auth/packages/civic-auth-client
+> @civic/auth@0.1.2 build:cjs /Users/kevincolgan/code/civic-auth/packages/civic-auth-client
 > tsc -p tsconfig.cjs.json --noEmit false && tsc-alias -p tsconfig.cjs.json
 
 
-> @civic/auth@0.1.2-beta.0 build:esm /Users/kevincolgan/code/civic-auth/packages/civic-auth-client
+> @civic/auth@0.1.2 build:esm /Users/kevincolgan/code/civic-auth/packages/civic-auth-client
 > tsc -p tsconfig.esm.json --noEmit false && tsc-alias -p tsconfig.esm.json
 

package/CHANGELOG.md

@@ -1,3 +1,6 @@
+# 0.1.3 Update README
+- Synchronise the README with docs.civic.com
+
 # 0.1.2 Fix AuthConfig defaults
 - Update AuthConfig type to make oauthServer optional
 - Export AuthConfig type from server

package/README.md

@@ -1,198 +1,411 @@
-# Civic Auth Client SDK
+- [Civic Auth Client SDK](#civic-auth-client-sdk)
+  - [Quick Start](#quick-start)
+    - [npm](#npm)
+    - [yarn](#yarn)
+    - [pnpm](#pnpm)
+    - [bun](#bun)
+  - [Integration](#integration)
+- [React](#react)
+  - [Usage](#usage)
+    - [The User Button](#the-user-button)
+    - [Getting User Information on the Frontend](#getting-user-information-on-the-frontend)
+  - [Advanced Configuration](#advanced-configuration)
+    - [Display Mode](#display-mode)
+  - [API](#api)
+    - [User Context](#user-context)
+    - [User](#user)
+      - [Base User Fields](#base-user-fields)
+      - [Token Fields](#token-fields)
+      - [Forwarded Tokens](#forwarded-tokens)
+      - [Embedded Login Iframe](#embedded-login-iframe)
+- [Next.JS](#nextjs)
+  - [Quick Start](#quick-start-1)
+    - [**1. Add the Civic Auth Plugin**](#1-add-the-civic-auth-plugin)
+    - [**2. Create an API Route**](#2-create-an-api-route)
+    - [**3. Middleware**](#3-middleware)
+      - [Middleware Chaining](#middleware-chaining)
+    - [**4. Frontend Integration**](#4-frontend-integration)
+  - [Usage](#usage-1)
+    - [Getting User Information on the Frontend](#getting-user-information-on-the-frontend-1)
+    - [Getting User Information on the Backend](#getting-user-information-on-the-backend)
+  - [Advanced Configuration](#advanced-configuration-1)
 
-The Civic Auth Client SDK is a powerful and flexible authentication library for React and Next.js applications. It provides a seamless way to integrate Civic's authentication services into your web applications.
+# Civic Auth Client SDK
+Civic Auth offers a simple, flexible, and fast way to integrate authentication into your applications.
 
-## Features
+You can find the full, official documentation [here](https://docs.civic.com/auth), with a quick-start version in this README.
 
-- Easy-to-use React hooks and components
-- Support for various authentication flows (iframe, redirect, new tab)
-- Token management and refresh
-- User information retrieval
-- Customizable UI components
-- TypeScript support
+## Quick Start
 
-## Installation
+Sign up for Civic Auth in less than a minute at [auth.civic.com](https://auth.civic.com) to get your Client ID.
 
-Install the package using npm or yarn:
+Install the library in your app using your installer of choice:
 
+### npm
 ```bash
 npm install @civic/auth
 ```
-
-or
-
+### yarn
 ```bash
 yarn add @civic/auth
 ```
+### pnpm
+```bash
+pnpm install @civic/auth
+```
+### bun
+```bash
+bun add @civic/auth
+```
 
-## Usage
+## Integration
+
+Choose your framework for instructions on how to integrate Civic Auth into your application.
+* [ReactJS](#react)
+* [NextJS](#nextjs)
+  
 
-First, import the CSS styles in your main application file (e.g., `_app.tsx` for Next.js):
+For integrating in other environments using any OIDC or OAuth 2.0-compliant client libraries, see [here]([integration/other.md](https://docs.civic.com/auth/integration/other)).
 
-### Setup CivicAuthProvider
 
-To use the Civic Auth Client SDK, wrap your application with the `CivicAuthProvider` component. This will allow the authentication context to be accessible throughout your app.
+# React
 
-```tsx
-import { CivicAuthProvider } from "@civic/auth/react";
+Integrate Civic Auth into your React application with ease, just wrap your app with the Civic Auth provider and add your Client ID (provided after you [sign up](https://auth.civic.com)). A working example is available in our [github examples repo](https://github.com/civicteam/civic-auth-examples/tree/main/packages/civic-auth/reactjs).
+
+```typescript
+import { CivicAuthProvider, UserButton } from "@civic/auth/react";
 
 function App({ children }) {
   return (
-    <CivicAuthProvider clientId="your-client-id" redirectUrl="https://your-app.com/callback">
+    <CivicAuthProvider clientId="YOUR CLIENT ID">
+      <UserButton />
       {children}
     </CivicAuthProvider>
-  );
+  )
 }
 ```
 
-The only required prop for `CivicAuthProvider` is the `clientId`. By default, the SDK uses Civic's endpoints. If you need to use your own endpoints, you can provide them using the `config` prop. See the advanced configuration section below for more details.
+## Usage
 
-### Advanced Configuration
+### The User Button
 
-If you want to use your own endpoints, you can pass a `config` object to the `CivicAuthProvider` as shown below:
+The Civic Auth SDK comes with a multi-purpose styled component called the `UserButton`
 
-```tsx
-import { CivicAuthProvider } from "@civic/auth/react";
+```typescript
+import { UserButton, CivicAuthProvider } from '@civic/auth/react';
+
+export function TitleBar() {
+  return (
+    <div className="flex justify-between items-center">
+      <h1>My App</h1>
+      <UserButton />
+    </div>
+  );
+};
 
 function App({ children }) {
   return (
-    <CivicAuthProvider
-      clientId="your-client-id"
-      redirectUrl="https://your-app.com/callback"
-      config={{
-        endpoints: {
-          auth: "https://your-auth-server.com/oauth/auth",
-          token: "https://your-auth-server.com/oauth/token",
-          userinfo: "https://your-auth-server.com/oauth/userinfo",
-        },
-      }}
-    >
-      {children}
+    <CivicAuthProvider clientId="YOUR CLIENT ID">
+      <TitleBar />
     </CivicAuthProvider>
-  );
+  )
 }
 ```
 
-### Sign In and User Profile
+This component is context-dependent. If the user is logged in, it will show their profile picture and name. If the user is not logged in, it will show a Log In button.
 
-The SDK provides hooks like `useAuth` and `useUser` to manage authentication and user information. Below is an example of a profile component that handles signing in and signing out.
+### Getting User Information on the Frontend
 
-```tsx
-import { useAuth, useUser } from "@civic/auth/react";
+Use the Civic Auth SDK to retrieve user information on the frontend.
 
-function Profile() {
-  const { isAuthenticated, signIn, signOut } = useAuth();
+```typescript
+import { useUser } from '@civic/auth/react';
+
+export function MyComponent() {
   const { user } = useUser();
+  
+  if (!user) return <div>User not logged in</div>
+  
+  return <div>Hello { user.name }!</div>
+}
+```
+
+We use `name` as an example here, but you can call any user object property from the user fields schema, as shown [below](react.md#base-user-fields).
+
+## Advanced Configuration
+
+Civic Auth is a "low-code" solution, so all configuration takes place via the [dashboard](https://auth.civic.com). Changes you make there will be updated automatically in your integration without any code changes. The only required parameter you need to provide is the client ID.
+
+The integration provides additional run-time settings and hooks that you can use to customize the library's integration with your own app. If you need any of these, you can add them to the CivicAuthProvider as follows:
 
-  if (!isAuthenticated) {
-    return <button onClick={() => signIn()}>Sign In</button>;
+```typescript
+<CivicAuthProvider
+  clientId="YOUR CLIENT ID"
+  ...other configuration
+>
+```
+
+See below for the list of all configuration options
+
+<table><thead><tr><th width="115">Field</th><th width="70">Required</th><th width="96">Default</th><th width="251">Example</th><th>Description</th></tr></thead><tbody><tr><td>clientId</td><td>Yes</td><td>-</td><td><code>2cc5633d-2c92-48da-86aa-449634f274b9</code></td><td>The key obtained on signup to <a href="https://auth.civic.com">auth.civic.com</a></td></tr><tr><td>nonce</td><td>No</td><td>-</td><td>1234</td><td>A single-use ID used during login, binding a login token with a given client. Needed in advanced authentication processes only</td></tr><tr><td>onSignIn</td><td>No</td><td>-</td><td><p></p><pre class="language-typescript"><code class="lang-typescript">(error?: Error) => {
+  if (error) { 
+    // handle error
+  } else {
+    // handle successful login
   }
+}
+</code></pre></td><td>A hook that executes after a sign-in attempt, whether successful or not.</td></tr><tr><td>onSignOut</td><td>No</td><td>-</td><td><pre class="language-typescript"><code class="lang-typescript">() => {
+  // handle signout
+}
+</code></pre></td><td>A hook that executes after a user logs out.</td></tr><tr><td>redirectUrl</td><td>No</td><td>currentURL</td><td>/authenticating</td><td>An override for the page that OAuth will redirect to to perform token-exchange. By default Civic will redirect to the current URL and Authentication will be finished by the Civic provider automatically. Only use if you'd like to have some custom display or logic during OAuth token-exchange. The redirect page must have the CivicAuthProvider running in order to finish authentication.</td></tr><tr><td><p></p><p>modalIframe</p></td><td>No</td><td>true</td><td>modalIframe={true}</td><td>Set to <code>true</code> if you want to embed the login iframe in your app rather than opening the iframe in a modal. See <a href="react.md#embedded-login-iframe">Embedded Login Iframe section</a> below.</td></tr></tbody></table>
 
-  return (
-    <div>
-      <h1>Welcome, {user?.name}</h1>
-      <button onClick={() => signOut()}>Sign Out</button>
-    </div>
-  );
+### Display Mode
+
+The display mode indicates where the Civic  login UI will be displayed. The following display modes are supported:
+
+* `iframe` (default): the UI loads in an iframe that shows in an overlay on top of the existing page content
+* `redirect`: the UI redirects the current URL to a Civic login screen, then redirects back to your site when login is complete
+* `new_tab`: the UI opens in a new tab or popup window (depending on browser preferences), and after login is complete, the tab or popup closes to return the user to your site
+
+## API
+
+### User Context
+
+The full user context object (provided by `useUser`) looks like this:
+
+```typescript
+{ 
+  user: User | null;
+  isLoading: boolean;
+  error: Error | null;
+  signIn: (displayMode?: DisplayMode) => Promise&#x3C;void>;
+  signOut: () => Promise&#x3C;void>;
 }
 ```
+### User
+
+The `User` object looks like this:
+
+```typescript
+type BaseUser = {
+  id: string;
+  email?: string;
+  name?: string;
+  picture?: string;
+  given_name?: string;
+  family_name?: string;
+  updated_at?: Date;
+};
+
+type Tokens = {
+  idToken: string;
+  accessToken: string;
+  refreshToken: string;
+  forwardedTokens: ForwardedTokens;
+};
+
+type User = BaseUser &#x26; Tokens
+```
 
-### UserButton Component
+Field descriptions:
 
-The SDK also includes ready-to-use UI components like `UserButton`, which provides an easy way to display user information and authentication controls.
+#### Base User Fields
 
-```tsx
-import { UserButton } from "@civic/auth/react";
+<table><thead><tr><th width="174">Field</th><th></th></tr></thead><tbody><tr><td>id</td><td>The user's unique ID with respect to your app. You can use this to look up the user in the <a href="https://auth.civic.com/dashboard">dashboard</a>.</td></tr><tr><td>email</td><td>The user's email address</td></tr><tr><td>name</td><td>The user's full name</td></tr><tr><td>given_name</td><td>The user's given name</td></tr><tr><td>family_name</td><td>The user's family name</td></tr><tr><td>updated_at</td><td>The time at which the user's profile was most recently updated.</td></tr></tbody></table>
 
-function Header() {
-  return (
-    <header>
-      <h1>My App</h1>
-      <UserButton />
-    </header>
-  );
-}
+#### Token Fields
+
+Typically developers will not need to interact with the token fields, which are used only for advanced use cases.
+
+<table><thead><tr><th width="185">Field</th><th></th></tr></thead><tbody><tr><td>idToken</td><td>The OIDC id token, used to request identity information about the user</td></tr><tr><td>accessToken</td><td>The OAuth 2.0 access token, allowing a client to make API calls to Civic Auth on behalf of the user.</td></tr><tr><td>refreshToken</td><td>The OAuth 2.0 refresh token, allowing a login session to be extended automatically without requiring user interaction. <br>The Civic Auth SDK handles refresh automatically, so you do not need to do this.</td></tr><tr><td>forwardedTokens</td><td>If the user authenticated using SSO (single-sign-on login) with a federated OAuth provider such as Google, this contains the OIDC and OAuth 2.0 tokens from that provider.<br><br></td></tr></tbody></table>
+
+#### Forwarded Tokens
+
+Use forwardedTokens if you need to make requests to the source provider, such as find out provider-specific information.
+
+\
+An example would be, if a user logged in via Google, using the Google forwarded token to query the Google Groups that the user is a member of.
+
+For example:
+
+```typescript
+const googleAccessToken = user.forwardedTokens?.google?.accessToken;
 ```
 
-### Embedding the login iframe in your page
+#### Embedded Login Iframe
 
-The default displayMode for user login is 'iframe' which will show a modal containing the login page for users, when the `signIn` hook is called. If you want to customize where this page is shown and embed it into your page instead i.e. in the case where you have a landing page and don't want users to have to click on a 'sign-in' button, you can embed the login iframe directly inside your page and it will work just like in the modal, as long as it is a child of a <CivicAuthProvider>. In this mode, the iframe auto-loads the login page.
+If you want to have the Login screen open directly on a page without the user having to click on button, you can import the `CivicAuthIframeContainer` component along with the AuthProvider option `modalIframe={false}`&#x20;
 
-To enable this mode, you need to set the parameter 'modalIframe' to `false` (it defaults to `true` in normal operation).
+You just need to ensure that the `CivicAuthIframeContainer` is a child under a `CivicAuthProvider`
 
-The example below shows the iframe centered inside a div embedded on the page:
-```tsx
-import { CivicAuthProvider } from "@civic/auth/react";
+```typescript
+import { CivicAuthIframeContainer } from "@civic/auth/react";
 
-function App({ children }) {
+
+const Login = () => {
   return (
-    <CivicAuthProvider
-      clientId="your-client-id"
-      redirectUrl="https://your-app.com/callback"
-      modalIframe={false}
-    >
-      {children}
-      <div className="flex min-h-[200px] items-center justify-center">
+      <div class="login-container">
         <CivicAuthIframeContainer />
       </div>
-    </CivicAuthProvider>
+  );
+};
+
+const App = () => {
+  return (
+      <CivicAuthProvider
+        clientId={"YOUR CLIENT ID"}
+        modalIframe={false}
+      >
+        <Login />
+      </CivicAuthProvider>
   );
 }
 ```
 
-### Token Management with useToken Hook
 
-The `useToken` hook can be used to access and manage tokens within your application. This hook provides the current access and ID tokens, a refresh function, and token loading/error states.
 
-```tsx
-import { useToken } from "@civic/auth/react";
+# Next.JS
 
-function TokenInfo() {
-  const { accessToken, idToken, refreshToken, isLoading, error } = useToken();
+## Quick Start
 
-  if (isLoading) {
-    return <div>Loading tokens...</div>;
-  }
+Integrate Civic Auth into your Next.js application using the following steps (a working example is available in our [github examples repo](https://github.com/civicteam/civic-auth-examples/tree/main/packages/civic-auth/nextjs)):
 
-  if (error) {
-    return <div>Error: {error.message}</div>;
-  }
+### **1. Add the Civic Auth Plugin**
+
+This is where you give your app the Client ID provided when you sign up at [auth.civic.com](https://auth.civic.com).
+
+The defaults should work out of the box for most customers, but if you want to configure your app, see [below](next.js.md#configuration) for details.
+```typescript
+import { createCivicAuthPlugin } from "@civic/auth/nextjs"
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+const withCivicAuth = createCivicAuthPlugin({
+  clientId: 'YOUR CLIENT ID'
+});
+
+export default withCivicAuth(nextConfig)
+```
+### **2. Create an API Route**
+
+This is where your app will handle login and logout requests.
+
+Create this file at the following path:
+
+`src/app/api/auth/[...civicauth]/route.ts`
+
+```typescript
+import { handler } from '@civic/auth/nextjs'
+
+export const GET = handler()
+```
+
+These steps apply to the [App Router](https://nextjs.org/docs/app). If you are using the Pages Router, please [contact us](https://discord.com/invite/MWmhXauJw8/?referrer=home-discord) for integration steps.
+
+### **3. Middleware**
+
+Middleware is used to protect your backend routes, server components and server actions from unauthenticated requests.&#x20;
+
+Using the Civic Auth middleware ensures that only logged-in users have access to secure parts of your service.
+
+```typescript
+import { authMiddleware } from '@civic/auth/nextjs/middleware'
+
+export default authMiddleware()
+
+export const config = {
+  // include the paths you wish to secure here
+  matcher: [ '/api/:path*', '/admin/:path*'  ] 
+}
+```
+
+#### Middleware Chaining
+
+If you are already using middleware in your Next.js app, then you can chain them with Civic Auth as follows:
+
+```typescript
+import { auth } from '@civic/auth/nextjs'
+import { NextRequest, NextResponse } from "next/server";
+
+const withCivicAuth = auth()
+
+const otherMiddleware = (request: NextRequest) => {
+    console.log('my middleware')
+    return NextResponse.next()
+}
 
+export default withCivicAuth(otherMiddleware)
+```
+
+### **4. Frontend Integration**
+
+Add the Civic Auth context to your app to give your frontend access to the logged-in user.
+
+```typescript
+import { CivicAuthProvider } from "@civic/auth/nextjs";
+
+function Layout({ children }) {
   return (
-    <div>
-      <h2>Access Token: {accessToken}</h2>
-      <h2>ID Token: {idToken}</h2>
-      <button onClick={() => refreshToken()}>Refresh Tokens</button>
-    </div>
-  );
+    // ... the rest of your app layout
+    <CivicAuthProvider>
+      {children}
+    </CivicAuthProvider>
+  )
 }
 ```
 
-## Configuration Options
+Unlike the pure [React](react.md) integration, you do _not_ have to add your client ID again here!
+
+## Usage
+
+### Getting User Information on the Frontend
+
+[Next.JS client components](https://nextjs.org/docs/app/building-your-application/rendering/client-components) can use the Civic Auth React tools to obtain user information as well as display convenient login, and logout buttons. See the [React Usage page](react.md) for details.
+
+### Getting User Information on the Backend
 
-- `clientId`: Your application's client ID provided by Civic.
-- `redirectUrl`: (Optional) The URL to which users will be redirected after authentication.
-- `endpoints`: (Optional) Object containing the URLs for the authentication endpoints (`auth`, `token`, `userinfo`). Use this if you want to point to your own authentication server.
+Retrieve user information on backend code, such as in React Server Components, React Server Actions, or api routes using `getUser`:
 
-## Display modes
+```typescript
+import { getUser } from '@civic/auth/nextjs';
 
-In order to verify a user's credentials, an auth window is loaded in one of three modes:
+const user = await getUser();
+```
+
+For example, in a NextJS Server Component:
 
-### iframe
-an iframe is overlaid onto the page where the AuthProvider lives, and the Civic auth UI is loaded inside the iframe. When authentication is complete the iframe will disappear.
+```typescript
+import { getUser } from '@civic/auth/nextjs';
 
-### redirect
-the current page is redirecting to the Civic auth UI. When authentication is complete, the page redirects back to the original page.
+export async function MyServerComponent() {
+  const user = await getUser();
+  
+  if (!user) return <div>User not logged in</div>
+  
+  return <div>Hello { user.name }!</div>
+}
+```
 
-### new_tab
-the current page remains open and a new tab is open to show the Civic auth UI. When authentication is complete, the tab is closed.
+The `name` property is used as an example here, check out the [React Usage page](react.md) to see the entire basic user object structure.&#x20;
 
-Note that if a user's browser does not allow popups, then the display mode defaults to 'redirect'.
+## Advanced Configuration
 
-## TypeScript Support
+Civic Auth is a "low-code" solution, so most of the configuration takes place via the [dashboard](https://auth.civic.com). Changes you make there will be updated automatically in your integration without any code changes. The only required parameter you need to provide is the client ID.
 
-This SDK is fully written in TypeScript, providing type definitions out of the box for a smooth development experience.
+The integration also offers the ability customize the library according to the needs of your Next.js app. For example, to restrict authentication checks to specific pages and routes in your app. You can do so inside `next.config.js` as follows:
+
+```typescript
+const withCivicAuth = createCivicAuthPlugin({
+  clientId: 'YOUR CLIENT ID'
+  ...other config
+});
+
+export default withCivicAuth(nextConfig) // your next config here
+```
 
-## License
+Here are the available configuration options:
 
-This project is licensed under the MIT License.
+<table><thead><tr><th width="133">Field</th><th width="100">Required</th><th width="171">Default</th><th>Example</th><th>Description</th></tr></thead><tbody><tr><td>clientId</td><td>Yes</td><td>-</td><td><code>2cc5633d-2c92-48da-86aa-449634f274b9</code></td><td>The key obtained on signup to <a href="https://auth.civic.com">auth.civic.com</a></td></tr><tr><td>callbackUrl</td><td>No</td><td>/api/auth/callback</td><td>/api/myroute/callback</td><td>The path to route the browser to after a succesful login. Set this value if you are hosting your civic auth API route somewhere other than the default recommended <a href="next.js.md#create-an-api-route">above</a>.</td></tr><tr><td>loginUrl</td><td>No</td><td>/</td><td>/admin</td><td>The path your user will be sent to if they access a resource that needs them to be logged in. If you have a dedicated login page, you can set it here.</td></tr><tr><td>logoutUrl</td><td>No</td><td>/</td><td>/goodbye</td><td>The path your user will be sent to after a successful log-out.</td></tr><tr><td>include</td><td>No</td><td>['/*']</td><td><p>[</p><p> '/admin/*', '/api/admin/*'</p><p>]</p></td><td>An array of path <a href="https://man7.org/linux/man-pages/man7/glob.7.html">globs</a> that require a user to be logged-in to access. If not set, will include all paths matched by your Next.js <a href="next.js.md#middleware">middleware</a>.</td></tr><tr><td>exclude</td><td>No</td><td>-</td><td>['public/home']</td><td>An array of path <a href="https://man7.org/linux/man-pages/man7/glob.7.html">globs</a> that are excluded from the Civic Auth <a href="next.js.md#middleware">middleware</a>. In some cases, it might be easier and safer to specify exceptions rather than keep an inclusion list up to date.</td></tr></tbody></table>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civic/auth",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "module": "dist/index.js",
   "main": "dist/index.ts",
@@ -89,8 +89,8 @@
     "vite": "^5.4.8",
     "vite-plugin-dts": "^4.2.3",
     "vitest": "^2.1.2",
-    "@repo/typescript-config": "0.0.0",
-    "@repo/eslint-config": "0.0.0"
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
   },
   "optionalDependency": {
     "next": "^14"