@_mustachio/openauth 0.6.0

package/src/jwt.ts

@@ -0,0 +1,17 @@
+import { JWTPayload, jwtVerify, KeyLike, SignJWT } from "jose"
+
+export namespace jwt {
+  export function create(
+    payload: JWTPayload,
+    algorithm: string,
+    privateKey: KeyLike,
+  ) {
+    return new SignJWT(payload)
+      .setProtectedHeader({ alg: algorithm, typ: "JWT", kid: "sst" })
+      .sign(privateKey)
+  }
+
+  export function verify<T>(token: string, publicKey: KeyLike) {
+    return jwtVerify<T>(token, publicKey)
+  }
+}

package/src/keys.ts

@@ -0,0 +1,139 @@
+import {
+  exportJWK,
+  exportPKCS8,
+  exportSPKI,
+  generateKeyPair,
+  importPKCS8,
+  importSPKI,
+  JWK,
+  KeyLike,
+} from "jose"
+import { Storage, StorageAdapter } from "./storage/storage.js"
+
+const signingAlg = "ES256"
+const encryptionAlg = "RSA-OAEP-512"
+
+interface SerializedKeyPair {
+  id: string
+  publicKey: string
+  privateKey: string
+  created: number
+  alg: string
+  expired?: number
+}
+
+export interface KeyPair {
+  id: string
+  alg: string
+  public: KeyLike
+  private: KeyLike
+  created: Date
+  expired?: Date
+  jwk: JWK
+}
+
+/**
+ * @deprecated use `signingKeys` instead
+ */
+export async function legacySigningKeys(
+  storage: StorageAdapter,
+): Promise<KeyPair[]> {
+  const alg = "RS512"
+  const results = [] as KeyPair[]
+  const scanner = Storage.scan<SerializedKeyPair>(storage, ["oauth:key"])
+  for await (const [_key, value] of scanner) {
+    const publicKey = await importSPKI(value.publicKey, alg, {
+      extractable: true,
+    })
+    const privateKey = await importPKCS8(value.privateKey, alg)
+    const jwk = await exportJWK(publicKey)
+    jwk.kid = value.id
+    results.push({
+      id: value.id,
+      alg,
+      created: new Date(value.created),
+      public: publicKey,
+      private: privateKey,
+      expired: new Date(1735858114000),
+      jwk,
+    })
+  }
+  return results
+}
+
+export async function signingKeys(storage: StorageAdapter): Promise<KeyPair[]> {
+  const results = [] as KeyPair[]
+  const scanner = Storage.scan<SerializedKeyPair>(storage, ["signing:key"])
+  for await (const [_key, value] of scanner) {
+    const publicKey = await importSPKI(value.publicKey, value.alg, {
+      extractable: true,
+    })
+    const privateKey = await importPKCS8(value.privateKey, value.alg)
+    const jwk = await exportJWK(publicKey)
+    jwk.kid = value.id
+    jwk.use = "sig"
+    results.push({
+      id: value.id,
+      alg: signingAlg,
+      created: new Date(value.created),
+      expired: value.expired ? new Date(value.expired) : undefined,
+      public: publicKey,
+      private: privateKey,
+      jwk,
+    })
+  }
+  results.sort((a, b) => b.created.getTime() - a.created.getTime())
+  if (results.filter((item) => !item.expired).length) return results
+
+  const key = await generateKeyPair(signingAlg, {
+    extractable: true,
+  })
+  const serialized: SerializedKeyPair = {
+    id: crypto.randomUUID(),
+    publicKey: await exportSPKI(key.publicKey),
+    privateKey: await exportPKCS8(key.privateKey),
+    created: Date.now(),
+    alg: signingAlg,
+  }
+  await Storage.set(storage, ["signing:key", serialized.id], serialized)
+  return signingKeys(storage)
+}
+
+export async function encryptionKeys(
+  storage: StorageAdapter,
+): Promise<KeyPair[]> {
+  const results = [] as KeyPair[]
+  const scanner = Storage.scan<SerializedKeyPair>(storage, ["encryption:key"])
+  for await (const [_key, value] of scanner) {
+    const publicKey = await importSPKI(value.publicKey, value.alg, {
+      extractable: true,
+    })
+    const privateKey = await importPKCS8(value.privateKey, value.alg)
+    const jwk = await exportJWK(publicKey)
+    jwk.kid = value.id
+    results.push({
+      id: value.id,
+      alg: encryptionAlg,
+      created: new Date(value.created),
+      expired: value.expired ? new Date(value.expired) : undefined,
+      public: publicKey,
+      private: privateKey,
+      jwk,
+    })
+  }
+  results.sort((a, b) => b.created.getTime() - a.created.getTime())
+  if (results.filter((item) => !item.expired).length) return results
+
+  const key = await generateKeyPair(encryptionAlg, {
+    extractable: true,
+  })
+  const serialized: SerializedKeyPair = {
+    id: crypto.randomUUID(),
+    publicKey: await exportSPKI(key.publicKey),
+    privateKey: await exportPKCS8(key.privateKey),
+    created: Date.now(),
+    alg: encryptionAlg,
+  }
+  await Storage.set(storage, ["encryption:key", serialized.id], serialized)
+  return encryptionKeys(storage)
+}

package/src/pkce.ts

@@ -0,0 +1,40 @@
+import { base64url } from "jose"
+
+function generateVerifier(length: number): string {
+  const buffer = new Uint8Array(length)
+  crypto.getRandomValues(buffer)
+  return base64url.encode(buffer)
+}
+
+async function generateChallenge(verifier: string, method: "S256" | "plain") {
+  if (method === "plain") return verifier
+  const encoder = new TextEncoder()
+  const data = encoder.encode(verifier)
+  const hash = await crypto.subtle.digest("SHA-256", data)
+  return base64url.encode(new Uint8Array(hash))
+}
+
+export async function generatePKCE(length: number = 64) {
+  if (length < 43 || length > 128) {
+    throw new Error(
+      "Code verifier length must be between 43 and 128 characters",
+    )
+  }
+  const verifier = generateVerifier(length)
+  const challenge = await generateChallenge(verifier, "S256")
+  return {
+    verifier,
+    challenge,
+    method: "S256",
+  }
+}
+
+export async function validatePKCE(
+  verifier: string,
+  challenge: string,
+  method: "S256" | "plain" = "S256",
+) {
+  const generatedChallenge = await generateChallenge(verifier, method)
+  // timing safe equals?
+  return generatedChallenge === challenge
+}

package/src/provider/apple.ts

@@ -0,0 +1,127 @@
+/**
+ * Use this provider to authenticate with Apple. Supports both OAuth2 and OIDC.
+ *
+ * #### Using OAuth
+ *
+ * ```ts {5-8}
+ * import { AppleProvider } from "@openauthjs/openauth/provider/apple"
+ *
+ * export default issuer({
+ *   providers: {
+ *     apple: AppleProvider({
+ *       clientID: "1234567890",
+ *       clientSecret: "0987654321"
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * #### Using OAuth with form_post response mode
+ *
+ * When requesting name or email scopes from Apple, you must use form_post response mode:
+ *
+ * ```ts {5-9}
+ * import { AppleProvider } from "@openauthjs/openauth/provider/apple"
+ *
+ * export default issuer({
+ *   providers: {
+ *     apple: AppleProvider({
+ *       clientID: "1234567890",
+ *       clientSecret: "0987654321",
+ *       responseMode: "form_post"
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * #### Using OIDC
+ *
+ * ```ts {5-7}
+ * import { AppleOidcProvider } from "@openauthjs/openauth/provider/apple"
+ *
+ * export default issuer({
+ *   providers: {
+ *     apple: AppleOidcProvider({
+ *       clientID: "1234567890"
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js"
+import { OidcProvider, OidcWrappedConfig } from "./oidc.js"
+
+export interface AppleConfig extends Oauth2WrappedConfig {
+  /**
+   * The response mode to use for the authorization request.
+   * Apple requires 'form_post' response mode when requesting name or email scopes.
+   * @default "query"
+   */
+  responseMode?: "query" | "form_post"
+}
+export interface AppleOidcConfig extends OidcWrappedConfig {}
+
+/**
+ * Create an Apple OAuth2 provider.
+ *
+ * @param config - The config for the provider.
+ * @example
+ * ```ts
+ * // Using default query response mode (GET callback)
+ * AppleProvider({
+ *   clientID: "1234567890",
+ *   clientSecret: "0987654321"
+ * })
+ *
+ * // Using form_post response mode (POST callback)
+ * // Required when requesting name or email scope
+ * AppleProvider({
+ *   clientID: "1234567890",
+ *   clientSecret: "0987654321",
+ *   responseMode: "form_post",
+ *   scopes: ["name", "email"]
+ * })
+ * ```
+ */
+export function AppleProvider(config: AppleConfig) {
+  const { responseMode, ...restConfig } = config
+  const additionalQuery =
+    responseMode === "form_post"
+      ? { response_mode: "form_post", ...config.query }
+      : config.query || {}
+
+  return Oauth2Provider({
+    ...restConfig,
+    type: "apple" as const,
+    endpoint: {
+      authorization: "https://appleid.apple.com/auth/authorize",
+      token: "https://appleid.apple.com/auth/token",
+      jwks: "https://appleid.apple.com/auth/keys",
+    },
+    query: additionalQuery,
+  })
+}
+
+/**
+ * Create an Apple OIDC provider.
+ *
+ * This is useful if you just want to verify the user's email address.
+ *
+ * @param config - The config for the provider.
+ * @example
+ * ```ts
+ * AppleOidcProvider({
+ *   clientID: "1234567890"
+ * })
+ * ```
+ */
+export function AppleOidcProvider(config: AppleOidcConfig) {
+  return OidcProvider({
+    ...config,
+    type: "apple" as const,
+    issuer: "https://appleid.apple.com",
+  })
+}

package/src/provider/arctic.ts

@@ -0,0 +1,66 @@
+import type { OAuth2Tokens } from "arctic"
+import { Context } from "hono"
+import { Provider } from "./provider.js"
+import { OauthError } from "../error.js"
+import { getRelativeUrl } from "../util.js"
+
+export interface ArcticProviderOptions {
+  scopes: string[]
+  clientID: string
+  clientSecret: string
+  query?: Record<string, string>
+}
+
+interface ProviderState {
+  state: string
+}
+
+export function ArcticProvider(
+  provider: new (
+    clientID: string,
+    clientSecret: string,
+    callback: string,
+  ) => {
+    createAuthorizationURL(state: string, scopes: string[]): URL
+    validateAuthorizationCode(code: string): Promise<OAuth2Tokens>
+    refreshAccessToken(refreshToken: string): Promise<OAuth2Tokens>
+  },
+  config: ArcticProviderOptions,
+): Provider<{
+  tokenset: OAuth2Tokens
+}> {
+  function getClient(c: Context) {
+    const callback = new URL(c.req.url)
+    const pathname = callback.pathname.replace(/authorize.*$/, "callback")
+    const url = getRelativeUrl(c, pathname)
+    return new provider(config.clientID, config.clientSecret, url)
+  }
+  return {
+    type: "arctic",
+    init(routes, ctx) {
+      routes.get("/authorize", async (c) => {
+        const client = getClient(c)
+        const state = crypto.randomUUID()
+        await ctx.set(c, "provider", 60 * 10, {
+          state,
+        })
+        return c.redirect(client.createAuthorizationURL(state, config.scopes))
+      })
+
+      routes.get("/callback", async (c) => {
+        const client = getClient(c)
+        const provider = (await ctx.get(c, "provider")) as ProviderState
+        if (!provider) return c.redirect("../authorize")
+        const code = c.req.query("code")
+        const state = c.req.query("state")
+        if (!code) throw new Error("Missing code")
+        if (state !== provider.state)
+          throw new OauthError("invalid_request", "Invalid state")
+        const tokens = await client.validateAuthorizationCode(code)
+        return ctx.success(c, {
+          tokenset: tokens,
+        })
+      })
+    },
+  }
+}

package/src/provider/code.ts

@@ -0,0 +1,227 @@
+/**
+ * Configures a provider that supports pin code authentication. This is usually paired with the
+ * `CodeUI`.
+ *
+ * ```ts
+ * import { CodeUI } from "@openauthjs/openauth/ui/code"
+ * import { CodeProvider } from "@openauthjs/openauth/provider/code"
+ *
+ * export default issuer({
+ *   providers: {
+ *     code: CodeProvider(
+ *       CodeUI({
+ *         copy: {
+ *           code_info: "We'll send a pin code to your email"
+ *         },
+ *         sendCode: (claims, code) => console.log(claims.email, code)
+ *       })
+ *     )
+ *   },
+ *   // ...
+ * })
+ * ```
+ *
+ * You can customize the provider using.
+ *
+ * ```ts {7-9}
+ * const ui = CodeUI({
+ *   // ...
+ * })
+ *
+ * export default issuer({
+ *   providers: {
+ *     code: CodeProvider(
+ *       { ...ui, length: 4 }
+ *     )
+ *   },
+ *   // ...
+ * })
+ * ```
+ *
+ * Behind the scenes, the `CodeProvider` expects callbacks that implements request handlers
+ * that generate the UI for the following.
+ *
+ * ```ts
+ * CodeProvider({
+ *   // ...
+ *   request: (req, state, form, error) => Promise<Response>
+ * })
+ * ```
+ *
+ * This allows you to create your own UI.
+ *
+ * @packageDocumentation
+ */
+import { Context } from "hono"
+import { Provider } from "./provider.js"
+import { generateUnbiasedDigits, timingSafeCompare } from "../random.js"
+
+export interface CodeProviderConfig<
+  Claims extends Record<string, string> = Record<string, string>,
+> {
+  /**
+   * The length of the pin code.
+   *
+   * @default 6
+   */
+  length?: number
+  /**
+   * The request handler to generate the UI for the code flow.
+   *
+   * Takes the standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)
+   * and optionally [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
+   * ojects.
+   *
+   * Also passes in the current `state` of the flow and any `error` that occurred.
+   *
+   * Expects the [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object
+   * in return.
+   */
+  request: (
+    req: Request,
+    state: CodeProviderState,
+    form?: FormData,
+    error?: CodeProviderError,
+  ) => Promise<Response>
+  /**
+   * Callback to send the pin code to the user.
+   *
+   * @example
+   * ```ts
+   * {
+   *   sendCode: async (claims, code) => {
+   *     // Send the code through the email or phone number based on the claims
+   *   }
+   * }
+   * ```
+   */
+  sendCode: (claims: Claims, code: string) => Promise<void | CodeProviderError>
+}
+
+/**
+ * The state of the code flow.
+ *
+ * | State | Description |
+ * | ----- | ----------- |
+ * | `start` | The user is asked to enter their email address or phone number to start the flow. |
+ * | `code` | The user needs to enter the pin code to verify their _claim_. |
+ */
+export type CodeProviderState =
+  | {
+      type: "start"
+    }
+  | {
+      type: "code"
+      resend?: boolean
+      code: string
+      claims: Record<string, string>
+    }
+
+/**
+ * The errors that can happen on the code flow.
+ *
+ * | Error | Description |
+ * | ----- | ----------- |
+ * | `invalid_code` | The code is invalid. |
+ * | `invalid_claim` | The _claim_, email or phone number, is invalid. |
+ */
+export type CodeProviderError =
+  | {
+      type: "invalid_code"
+    }
+  | {
+      type: "invalid_claim"
+      key: string
+      value: string
+    }
+
+export function CodeProvider<
+  Claims extends Record<string, string> = Record<string, string>,
+>(config: CodeProviderConfig<Claims>): Provider<{ claims: Claims }> {
+  const length = config.length || 6
+  function generate() {
+    return generateUnbiasedDigits(length)
+  }
+
+  return {
+    type: "code",
+    init(routes, ctx) {
+      async function transition(
+        c: Context,
+        next: CodeProviderState,
+        fd?: FormData,
+        err?: CodeProviderError,
+      ) {
+        await ctx.set<CodeProviderState>(c, "provider", 60 * 60 * 24, next)
+        const resp = ctx.forward(
+          c,
+          await config.request(c.req.raw, next, fd, err),
+        )
+        return resp
+      }
+      routes.get("/authorize", async (c) => {
+        const resp = await transition(c, {
+          type: "start",
+        })
+        return resp
+      })
+
+      routes.post("/authorize", async (c) => {
+        const code = generate()
+        const fd = await c.req.formData()
+        const state = await ctx.get<CodeProviderState>(c, "provider")
+        const action = fd.get("action")?.toString()
+
+        if (action === "request" || action === "resend") {
+          const claims = Object.fromEntries(fd) as Claims
+          delete claims.action
+          const err = await config.sendCode(claims, code)
+          if (err) return transition(c, { type: "start" }, fd, err)
+          return transition(
+            c,
+            {
+              type: "code",
+              resend: action === "resend",
+              claims,
+              code,
+            },
+            fd,
+          )
+        }
+
+        if (
+          fd.get("action")?.toString() === "verify" &&
+          state.type === "code"
+        ) {
+          const fd = await c.req.formData()
+          const compare = fd.get("code")?.toString()
+          if (
+            !state.code ||
+            !compare ||
+            !timingSafeCompare(state.code, compare)
+          ) {
+            return transition(
+              c,
+              {
+                ...state,
+                resend: false,
+              },
+              fd,
+              { type: "invalid_code" },
+            )
+          }
+          await ctx.unset(c, "provider")
+          return ctx.forward(
+            c,
+            await ctx.success(c, { claims: state.claims as Claims }),
+          )
+        }
+      })
+    },
+  }
+}
+
+/**
+ * @internal
+ */
+export type CodeProviderOptions = Parameters<typeof CodeProvider>[0]

package/src/provider/cognito.ts

@@ -0,0 +1,74 @@
+/**
+ * Use this provider to authenticate with a Cognito OAuth endpoint.
+ *
+ * ```ts {5-10}
+ * import { CognitoProvider } from "@openauthjs/openauth/provider/cognito"
+ *
+ * export default issuer({
+ *   providers: {
+ *     cognito: CognitoProvider({
+ *       domain: "your-domain.auth.us-east-1.amazoncognito.com",
+ *       region: "us-east-1",
+ *       clientID: "1234567890",
+ *       clientSecret: "0987654321"
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js"
+
+export interface CognitoConfig extends Oauth2WrappedConfig {
+  /**
+   * The domain of the Cognito User Pool.
+   *
+   * @example
+   * ```ts
+   * {
+   *   domain: "your-domain.auth.us-east-1.amazoncognito.com"
+   * }
+   * ```
+   */
+  domain: string
+  /**
+   * The region the Cognito User Pool is in.
+   *
+   * @example
+   * ```ts
+   * {
+   *   region: "us-east-1"
+   * }
+   * ```
+   */
+  region: string
+}
+
+/**
+ * Create a Cognito OAuth2 provider.
+ *
+ * @param config - The config for the provider.
+ * @example
+ * ```ts
+ * CognitoProvider({
+ *   domain: "your-domain.auth.us-east-1.amazoncognito.com",
+ *   region: "us-east-1",
+ *   clientID: "1234567890",
+ *   clientSecret: "0987654321"
+ * })
+ * ```
+ */
+export function CognitoProvider(config: CognitoConfig) {
+  const domain = `${config.domain}.auth.${config.region}.amazoncognito.com`
+
+  return Oauth2Provider({
+    type: "cognito",
+    ...config,
+    endpoint: {
+      authorization: `https://${domain}/oauth2/authorize`,
+      token: `https://${domain}/oauth2/token`,
+    },
+  })
+}