@_mustachio/openauth 0.6.0

package/src/storage/memory.ts

@@ -0,0 +1,135 @@
+/**
+ * Configure OpenAuth to use a simple in-memory store.
+ *
+ * :::caution
+ * This is not meant to be used in production.
+ * :::
+ *
+ * This is useful for testing and development. It's not meant to be used in production.
+ *
+ * ```ts
+ * import { MemoryStorage } from "@openauthjs/openauth/storage/memory"
+ *
+ * const storage = MemoryStorage()
+ *
+ * export default issuer({
+ *   storage,
+ *   // ...
+ * })
+ * ```
+ *
+ * Optionally, you can persist the store to a file.
+ *
+ * ```ts
+ * MemoryStorage({
+ *   persist: "./persist.json"
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { joinKey, splitKey, StorageAdapter } from "./storage.js"
+import { existsSync, readFileSync } from "node:fs"
+import { writeFile } from "node:fs/promises"
+
+/**
+ * Configure the memory store.
+ */
+export interface MemoryStorageOptions {
+  /**
+   * Optionally, backup the store to a file. So it'll be persisted when the issuer restarts.
+   *
+   * @example
+   * ```ts
+   * {
+   *   persist: "./persist.json"
+   * }
+   * ```
+   */
+  persist?: string
+}
+export function MemoryStorage(input?: MemoryStorageOptions): StorageAdapter {
+  const store = [] as [
+    string,
+    { value: Record<string, any>; expiry?: number },
+  ][]
+
+  if (input?.persist) {
+    if (existsSync(input.persist)) {
+      const file = readFileSync(input?.persist)
+      store.push(...JSON.parse(file.toString()))
+    }
+  }
+
+  async function save() {
+    if (!input?.persist) return
+    const file = JSON.stringify(store)
+    await writeFile(input.persist, file)
+  }
+
+  function search(key: string) {
+    let left = 0
+    let right = store.length - 1
+    while (left <= right) {
+      const mid = Math.floor((left + right) / 2)
+      const comparison = key.localeCompare(store[mid][0])
+
+      if (comparison === 0) {
+        return { found: true, index: mid }
+      } else if (comparison < 0) {
+        right = mid - 1
+      } else {
+        left = mid + 1
+      }
+    }
+    return { found: false, index: left }
+  }
+  return {
+    async get(key: string[]) {
+      const match = search(joinKey(key))
+      if (!match.found) return undefined
+      const entry = store[match.index][1]
+      if (entry.expiry && Date.now() >= entry.expiry) {
+        store.splice(match.index, 1)
+        await save()
+        return undefined
+      }
+      return entry.value
+    },
+    async set(key: string[], value: any, expiry?: Date) {
+      const joined = joinKey(key)
+      const match = search(joined)
+      // Handle both Date objects and TTL numbers while maintaining Date type in signature
+      const entry = [
+        joined,
+        {
+          value,
+          expiry: expiry ? expiry.getTime() : expiry,
+        },
+      ] as (typeof store)[number]
+      if (!match.found) {
+        store.splice(match.index, 0, entry)
+      } else {
+        store[match.index] = entry
+      }
+      await save()
+    },
+    async remove(key: string[]) {
+      const joined = joinKey(key)
+      const match = search(joined)
+      if (match.found) {
+        store.splice(match.index, 1)
+        await save()
+      }
+    },
+    async *scan(prefix: string[]) {
+      const now = Date.now()
+      const prefixStr = joinKey(prefix)
+      for (const [key, entry] of store) {
+        if (!key.startsWith(prefixStr)) continue
+        if (entry.expiry && now >= entry.expiry) continue
+        yield [splitKey(key), entry.value]
+      }
+    },
+  }
+}

package/src/storage/storage.ts

@@ -0,0 +1,46 @@
+export interface StorageAdapter {
+  get(key: string[]): Promise<Record<string, any> | undefined>
+  remove(key: string[]): Promise<void>
+  set(key: string[], value: any, expiry?: Date): Promise<void>
+  scan(prefix: string[]): AsyncIterable<[string[], any]>
+}
+
+const SEPERATOR = String.fromCharCode(0x1f)
+
+export function joinKey(key: string[]) {
+  return key.join(SEPERATOR)
+}
+
+export function splitKey(key: string) {
+  return key.split(SEPERATOR)
+}
+
+export namespace Storage {
+  function encode(key: string[]) {
+    return key.map((k) => k.replaceAll(SEPERATOR, ""))
+  }
+  export function get<T>(adapter: StorageAdapter, key: string[]) {
+    return adapter.get(encode(key)) as Promise<T | null>
+  }
+
+  export function set(
+    adapter: StorageAdapter,
+    key: string[],
+    value: any,
+    ttl?: number,
+  ) {
+    const expiry = ttl ? new Date(Date.now() + ttl * 1000) : undefined
+    return adapter.set(encode(key), value, expiry)
+  }
+
+  export function remove(adapter: StorageAdapter, key: string[]) {
+    return adapter.remove(encode(key))
+  }
+
+  export function scan<T>(
+    adapter: StorageAdapter,
+    key: string[],
+  ): AsyncIterable<[string[], T]> {
+    return adapter.scan(encode(key))
+  }
+}

package/src/subject.ts

@@ -0,0 +1,130 @@
+/**
+ * Subjects are what the access token generated at the end of the auth flow will map to. Under
+ * the hood, the access token is a JWT that contains this data.
+ *
+ * #### Define subjects
+ *
+ * ```ts title="subjects.ts"
+ * import { object, string } from "valibot"
+ *
+ * const subjects = createSubjects({
+ *   user: object({
+ *     userID: string()
+ *   })
+ * })
+ * ```
+ *
+ * We are using [valibot](https://github.com/fabian-hiller/valibot) here. You can use any
+ * validation library that's following the
+ * [standard-schema specification](https://github.com/standard-schema/standard-schema).
+ *
+ * :::tip
+ * You typically want to place subjects in its own file so it can be imported by all of your apps.
+ * :::
+ *
+ * You can start with one subject. Later you can add more for different types of users.
+ *
+ * #### Set the subjects
+ *
+ * Then you can pass it to the `issuer`.
+ *
+ * ```ts title="issuer.ts"
+ * import { subjects } from "./subjects"
+ *
+ * const app = issuer({
+ *   providers: { ... },
+ *   subjects,
+ *   // ...
+ * })
+ * ```
+ *
+ * #### Add the subject payload
+ *
+ * When your user completes the flow, you can add the subject payload in the `success` callback.
+ *
+ * ```ts title="issuer.ts"
+ * const app = issuer({
+ *   providers: { ... },
+ *   subjects,
+ *   async success(ctx, value) {
+ *     let userID
+ *     if (value.provider === "password") {
+ *       console.log(value.email)
+ *       userID = ... // lookup user or create them
+ *     }
+ *     return ctx.subject("user", {
+ *       userID
+ *     })
+ *   },
+ *   // ...
+ * })
+ * ```
+ *
+ * Here we are looking up the userID from our database and adding it to the subject payload.
+ *
+ * :::caution
+ * You should only store properties that won't change for the lifetime of the user.
+ * :::
+ *
+ * Since these will be stored in the access token, you should avoid storing information
+ * that'll change often. For example, if you store the user's username, you'll need to
+ * revoke the access token when the user changes their username.
+ *
+ * #### Decode the subject
+ *
+ * Now when your user logs in, you can use the OpenAuth client to decode the subject. For
+ * example, in our SSR app we can do the following.
+ *
+ * ```ts title="app/page.tsx"
+ * import { subjects } from "../subjects"
+ *
+ * const verified = await client.verify(subjects, cookies.get("access_token")!)
+ * console.log(verified.subject.properties.userID)
+ * ```
+ *
+ * All this is typesafe based on the shape of the subjects you defined.
+ *
+ * @packageDocumentation
+ */
+import type { v1 } from "@standard-schema/spec"
+import { Prettify } from "./util.js"
+
+/**
+ * Subject schema is a map of types that are used to define the subjects.
+ */
+export type SubjectSchema = Record<string, v1.StandardSchema>
+
+/** @internal */
+export type SubjectPayload<T extends SubjectSchema> = Prettify<
+  {
+    [type in keyof T & string]: {
+      type: type
+      properties: v1.InferOutput<T[type]>
+    }
+  }[keyof T & string]
+>
+
+/**
+ * Create a subject schema.
+ *
+ * @example
+ * ```ts
+ * const subjects = createSubjects({
+ *   user: object({
+ *     userID: string()
+ *   }),
+ *   admin: object({
+ *     workspaceID: string()
+ *   })
+ * })
+ * ```
+ *
+ * This is using [valibot](https://github.com/fabian-hiller/valibot) to define the shape of the
+ * subjects. You can use any validation library that's following the
+ * [standard-schema specification](https://github.com/standard-schema/standard-schema).
+ */
+export function createSubjects<Schema extends SubjectSchema = {}>(
+  types: Schema,
+): Schema {
+  return { ...types }
+}

package/src/ui/base.tsx

@@ -0,0 +1,118 @@
+import { PropsWithChildren } from "hono/jsx"
+import css from "./ui.css" assert { type: "text" }
+import { getTheme } from "./theme.js"
+
+export function Layout(
+  props: PropsWithChildren<{
+    size?: "small"
+  }>,
+) {
+  const theme = getTheme()
+  function get(key: "primary" | "background" | "logo", mode: "light" | "dark") {
+    if (!theme) return
+    if (!theme[key]) return
+    if (typeof theme[key] === "string") return theme[key]
+
+    return theme[key][mode] as string | undefined
+  }
+
+  const radius = (() => {
+    if (theme?.radius === "none") return "0"
+    if (theme?.radius === "sm") return "1"
+    if (theme?.radius === "md") return "1.25"
+    if (theme?.radius === "lg") return "1.5"
+    if (theme?.radius === "full") return "1000000000001"
+    return "1"
+  })()
+
+  const hasLogo = get("logo", "light") && get("logo", "dark")
+
+  return (
+    <html
+      style={{
+        "--color-background-light": get("background", "light"),
+        "--color-background-dark": get("background", "dark"),
+        "--color-primary-light": get("primary", "light"),
+        "--color-primary-dark": get("primary", "dark"),
+        "--font-family": theme?.font?.family,
+        "--font-scale": theme?.font?.scale,
+        "--border-radius": radius,
+      }}
+    >
+      <head>
+        <title>{theme?.title || "OpenAuthJS"}</title>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        {theme?.favicon ? (
+          <link rel="icon" href={theme?.favicon} />
+        ) : (
+          <>
+            <link
+              rel="icon"
+              href="https://openauth.js.org/favicon.ico"
+              sizes="48x48"
+            />
+            <link
+              rel="icon"
+              href="https://openauth.js.org/favicon.svg"
+              media="(prefers-color-scheme: light)"
+            />
+            <link
+              rel="icon"
+              href="https://openauth.js.org/favicon-dark.svg"
+              media="(prefers-color-scheme: dark)"
+            />
+            <link
+              rel="shortcut icon"
+              href="https://openauth.js.org/favicon.svg"
+              type="image/svg+xml"
+            />
+          </>
+        )}
+        <style dangerouslySetInnerHTML={{ __html: css }} />
+        {theme?.css && (
+          <style dangerouslySetInnerHTML={{ __html: theme.css }} />
+        )}
+      </head>
+      <body>
+        <div data-component="root">
+          <div data-component="center" data-size={props.size}>
+            {hasLogo ? (
+              <>
+                <img
+                  data-component="logo"
+                  src={get("logo", "light")}
+                  data-mode="light"
+                />
+                <img
+                  data-component="logo"
+                  src={get("logo", "dark")}
+                  data-mode="dark"
+                />
+              </>
+            ) : (
+              ICON_OPENAUTH
+            )}
+            {props.children}
+          </div>
+        </div>
+      </body>
+    </html>
+  )
+}
+
+const ICON_OPENAUTH = (
+  <svg
+    data-component="logo-default"
+    width="51"
+    height="51"
+    viewBox="0 0 51 51"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path
+      d="M0 50.2303V0.12854H50.1017V50.2303H0ZM3.08002 11.8326H11.7041V3.20856H3.08002V11.8326ZM14.8526 11.8326H23.4766V3.20856H14.8526V11.8326ZM26.5566 11.8326H35.1807V3.20856H26.5566V11.8326ZM38.3292 11.8326H47.0217V3.20856H38.3292V11.8326ZM3.08002 23.6052H11.7041V14.9811H3.08002V23.6052ZM14.8526 23.6052H23.4766V14.9811H14.8526V23.6052ZM26.5566 23.6052H35.1807V14.9811H26.5566V23.6052ZM38.3292 23.6052H47.0217V14.9811H38.3292V23.6052ZM3.08002 35.3092H11.7041V26.6852H3.08002V35.3092ZM14.8526 35.3092H23.4766V26.6852H14.8526V35.3092ZM26.5566 35.3092H35.1807V26.6852H26.5566V35.3092ZM38.3292 35.3092H47.0217V26.6852H38.3292V35.3092ZM3.08002 47.1502H11.7041V38.3893H3.08002V47.1502ZM14.8526 47.1502H23.4766V38.3893H14.8526V47.1502ZM26.5566 47.1502H35.1807V38.3893H26.5566V47.1502ZM38.3292 47.1502H47.0217V38.3893H38.3292V47.1502Z"
+      fill="currentColor"
+    />
+  </svg>
+)

package/src/ui/code.tsx

@@ -0,0 +1,215 @@
+/**
+ * Configure the UI that's used by the Code provider.
+ *
+ * ```ts {1,7-12}
+ * import { CodeUI } from "@openauthjs/openauth/ui/code"
+ * import { CodeProvider } from "@openauthjs/openauth/provider/code"
+ *
+ * export default issuer({
+ *   providers: {
+ *     code: CodeAdapter(
+ *       CodeUI({
+ *         copy: {
+ *           code_info: "We'll send a pin code to your email"
+ *         },
+ *         sendCode: (claims, code) => console.log(claims.email, code)
+ *       })
+ *     )
+ *   },
+ *   // ...
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+/** @jsxImportSource hono/jsx */
+
+import { CodeProviderOptions, CodeProviderError } from "../provider/code.js"
+import { UnknownStateError } from "../error.js"
+import { Layout } from "./base.js"
+import { FormAlert } from "./form.js"
+
+const DEFAULT_COPY = {
+  /**
+   * Copy for the email input.
+   */
+  email_placeholder: "Email",
+  /**
+   * Error message when the email is invalid.
+   */
+  email_invalid: "Email address is not valid",
+  /**
+   * Copy for the continue button.
+   */
+  button_continue: "Continue",
+  /**
+   * Copy informing that the pin code will be emailed.
+   */
+  code_info: "We'll send a pin code to your email.",
+  /**
+   * Copy for the pin code input.
+   */
+  code_placeholder: "Code",
+  /**
+   * Error message when the code is invalid.
+   */
+  code_invalid: "Invalid code",
+  /**
+   * Copy for when the code was sent.
+   */
+  code_sent: "Code sent to ",
+  /**
+   * Copy for when the code was resent.
+   */
+  code_resent: "Code resent to ",
+  /**
+   * Copy for the link to resend the code.
+   */
+  code_didnt_get: "Didn't get code?",
+  /**
+   * Copy for the resend button.
+   */
+  code_resend: "Resend",
+}
+
+export type CodeUICopy = typeof DEFAULT_COPY
+
+/**
+ * Configure the password UI.
+ */
+export interface CodeUIOptions {
+  /**
+   * Callback to send the pin code to the user.
+   *
+   * The `claims` object contains the email or phone number of the user. You can send the code
+   * using this.
+   *
+   * @example
+   * ```ts
+   * async (claims, code) => {
+   *   // Send the code via the claim
+   * }
+   * ```
+   */
+  sendCode: (
+    claims: Record<string, string>,
+    code: string,
+  ) => Promise<void | CodeProviderError>
+  /**
+   * Custom copy for the UI.
+   */
+  copy?: Partial<CodeUICopy>
+  /**
+   * The mode to use for the input.
+   * @default "email"
+   */
+  mode?: "email" | "phone"
+}
+
+/**
+ * Creates a UI for the Code provider flow.
+ * @param props - Configure the UI.
+ */
+export function CodeUI(props: CodeUIOptions): CodeProviderOptions {
+  const copy = {
+    ...DEFAULT_COPY,
+    ...props.copy,
+  }
+
+  const mode = props.mode ?? "email"
+
+  return {
+    sendCode: props.sendCode,
+    length: 6,
+    request: async (_req, state, _form, error): Promise<Response> => {
+      if (state.type === "start") {
+        const jsx = (
+          <Layout>
+            <form data-component="form" method="post">
+              {error?.type === "invalid_claim" && (
+                <FormAlert message={copy.email_invalid} />
+              )}
+              <input type="hidden" name="action" value="request" />
+              <input
+                data-component="input"
+                autofocus
+                type={mode === "email" ? "email" : "tel"}
+                name={mode === "email" ? "email" : "phone"}
+                inputmode={mode === "email" ? "email" : "numeric"}
+                required
+                placeholder={copy.email_placeholder}
+              />
+              <button data-component="button">{copy.button_continue}</button>
+            </form>
+            <p data-component="form-footer">{copy.code_info}</p>
+          </Layout>
+        )
+        return new Response(jsx.toString(), {
+          headers: {
+            "Content-Type": "text/html",
+          },
+        })
+      }
+
+      if (state.type === "code") {
+        const jsx = (
+          <Layout>
+            <form data-component="form" class="form" method="post">
+              {error?.type === "invalid_code" && (
+                <FormAlert message={copy.code_invalid} />
+              )}
+              {state.type === "code" && (
+                <FormAlert
+                  message={
+                    (state.resend ? copy.code_resent : copy.code_sent) +
+                    state.claims.email
+                  }
+                  color="success"
+                />
+              )}
+              <input type="hidden" name="action" value="verify" />
+              <input
+                data-component="input"
+                autofocus
+                minLength={6}
+                maxLength={6}
+                type="text"
+                name="code"
+                required
+                inputmode="numeric"
+                autocomplete="one-time-code"
+                placeholder={copy.code_placeholder}
+              />
+              <button data-component="button">{copy.button_continue}</button>
+            </form>
+            <form method="post">
+              {Object.entries(state.claims).map(([key, value]) => (
+                <input
+                  key={key}
+                  type="hidden"
+                  name={key}
+                  value={value}
+                  className="hidden"
+                />
+              ))}
+              <input type="hidden" name="action" value="resend" />
+              <div data-component="form-footer">
+                <span>
+                  {copy.code_didnt_get}{" "}
+                  <button data-component="link">{copy.code_resend}</button>
+                </span>
+              </div>
+            </form>
+          </Layout>
+        )
+        return new Response(jsx.toString(), {
+          headers: {
+            "Content-Type": "text/html",
+          },
+        })
+      }
+
+      throw new UnknownStateError()
+    },
+  }
+}

package/src/ui/form.tsx

@@ -0,0 +1,40 @@
+/** @jsxImportSource hono/jsx */
+
+export function FormAlert(props: {
+  message?: string
+  color?: "danger" | "success"
+}) {
+  return (
+    <div data-component="form-alert" data-color={props.color}>
+      <svg
+        data-slot="icon-success"
+        xmlns="http://www.w3.org/2000/svg"
+        fill="none"
+        viewBox="0 0 24 24"
+        stroke-width="1.5"
+        stroke="currentColor"
+      >
+        <path
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          d="M9 12.75 11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z"
+        />
+      </svg>
+      <svg
+        data-slot="icon-danger"
+        xmlns="http://www.w3.org/2000/svg"
+        fill="none"
+        viewBox="0 0 24 24"
+        stroke-width="1.5"
+        stroke="currentColor"
+      >
+        <path
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          d="M12 9v3.75m9-.75a9 9 0 1 1-18 0 9 9 0 0 1 18 0Zm-9 3.75h.008v.008H12v-.008Z"
+        />
+      </svg>
+      <span data-slot="message">{props.message}</span>
+    </div>
+  )
+}