@tempoxyz/id 0.0.0-pr-187.sha-eed04d3

package/src/internal/Apps.ts

@@ -0,0 +1,718 @@
+/**
+ * OAuth apps: the Better Auth plugins that serve them, and the operations of `tempo-id admin apps`
+ * on the `oauth_client` table. Better Auth registers clients only for a signed-in owner, so the
+ * operations write the rows that it reads, with its client ID format and its secret hash. A client
+ * secret is stored only as its hash.
+ * @module
+ */
+import { isLoopbackHost } from '@better-auth/core/utils/host'
+import { isNativePrivateUseRedirectUri } from '@better-auth/core/utils/redirect-uri'
+import {
+  getOAuthProviderState,
+  oauthProvider,
+} from '@better-auth/oauth-provider'
+import { generateRandomString } from 'better-auth/crypto'
+import { jwt } from 'better-auth/plugins/jwt'
+import { and, asc, eq, isNull, or } from 'drizzle-orm'
+import { Base64 } from 'ox'
+import * as Schema from '../app/db/schema.js'
+import type * as PendingKey from './PendingKey.js'
+import type * as Realm from './Realm.js'
+import * as SigningKey from './SigningKey.js'
+
+/** Another app already has the client ID. */
+export class ExistsError extends Error {
+  override readonly name = 'Apps.ExistsError'
+
+  constructor(options: { clientId: string }) {
+    super(
+      `App ${options.clientId} already exists. Update it, or choose another client ID.`,
+    )
+  }
+}
+
+/** A name, a redirect URI, or another value of an app is not valid. */
+export class InvalidError extends Error {
+  override readonly name = 'Apps.InvalidError'
+}
+
+/** No OAuth app has the client ID. */
+export class NotFoundError extends Error {
+  override readonly name = 'Apps.NotFoundError'
+
+  constructor(options: { clientId: string }) {
+    super(`Unknown app ${options.clientId}. Name a registered OAuth app.`)
+  }
+}
+
+/** The app redeems codes with PKCE alone, so it has no client secret to rotate. */
+export class PublicError extends Error {
+  override readonly name = 'Apps.PublicError'
+
+  constructor(options: { clientId: string }) {
+    super(
+      `App ${options.clientId} has no client secret. Rotate the secret of an app with a backend.`,
+    )
+  }
+}
+
+/** An OAuth app, as `tempo-id admin apps` returns it. */
+export type App = {
+  /** The client ID, which the app sends as `client_id`. */
+  clientId: string
+  /** When the app was created. */
+  createdAt: Date | null
+  /** Whether the app signs in through the device grant, in place of a redirect, as a CLI does. */
+  device: boolean
+  /** The display name, which the approval page shows. */
+  name: string | null
+  /** Every URI that `GET /oauth2/end-session` may return to after it ends the session. */
+  postLogoutRedirectUris: readonly string[]
+  /** Every URI that the app returns to. */
+  redirectUris: readonly string[]
+  /** Whether the app holds a client secret, which its backend sends to the token endpoint. */
+  secret: boolean
+  /** Whether the app holds the `tempo-id:sign` scope, which permits a challenge. */
+  sign: boolean
+  /** Whether a request without a key skips the approval page. */
+  skipConsent: boolean
+  /** `web` for a browser app or an app with a backend, and `native` for a mobile app. */
+  type: 'native' | 'web'
+}
+
+/** The grant type of the device grant (RFC 8628 §3.4). */
+export const deviceGrant = 'urn:ietf:params:oauth:grant-type:device_code'
+
+/** The scope that lets an app bind its own challenge into a key authorization. */
+export const signScope = 'tempo-id:sign'
+
+/** The scopes that every app may request. */
+const scopes = ['openid', 'profile', 'email', 'offline_access'] as const
+
+/**
+ * Returns whether `clientSecret` is the client secret of the enabled app with `clientId`. An
+ * unknown app, a disabled app, and an app without a client secret return `false`. Better Auth still
+ * authenticates the request itself, so a match only decides which app a rate limit counts.
+ */
+export async function authenticate(
+  db: Realm.Database,
+  options: authenticate.Options,
+) {
+  const [row] = await db
+    .select({
+      clientSecret: Schema.oauthClient.clientSecret,
+      disabled: Schema.oauthClient.disabled,
+    })
+    .from(Schema.oauthClient)
+    .where(eq(Schema.oauthClient.clientId, options.clientId))
+    .limit(1)
+  if (!row?.clientSecret || row.disabled) return false
+  return equal(await hashSecret(options.clientSecret), row.clientSecret)
+}
+
+export declare namespace authenticate {
+  type Options = {
+    /** The client ID that the request names. */
+    clientId: string
+    /** The client secret that the request sends. */
+    clientSecret: string
+  }
+}
+
+/**
+ * Registers an app, and returns it with its client secret. The secret appears only in this result,
+ * since the row holds only its hash. A `clientId` or `clientSecret` keeps the values of an app that
+ * another deployment registered.
+ *
+ * Throws `InvalidError` for an invalid name, redirect URI, client ID, or client secret, or a device
+ * app with a secret, and `ExistsError` when another app has the client ID.
+ */
+export async function create(db: Realm.Database, options: create.Options) {
+  const type = options.type ?? 'web'
+  const name = parseName(options.name)
+  const postLogoutRedirectUris = parsePostLogoutRedirectUris(
+    options.postLogoutRedirectUris ?? [],
+    { type },
+  )
+  const device = options.device ?? false
+  // A CLI cannot keep a secret, and the device grant's poll sends none, so a device app is public.
+  if (device && (options.secret || options.clientSecret !== undefined))
+    throw new InvalidError(
+      'Invalid app: a device app has no client secret, since a CLI cannot keep one. Leave out the secret.',
+    )
+  // A device app redirects nowhere, so it needs no redirect URI.
+  const redirectUris =
+    device && (options.redirectUris ?? []).length === 0
+      ? []
+      : parseRedirectUris(options.redirectUris ?? [], { type })
+  const clientId =
+    options.clientId === undefined
+      ? // Better Auth's format: 32 random letters.
+        generateRandomString(32, 'a-z', 'A-Z')
+      : parseClientId(options.clientId)
+  const clientSecret = (() => {
+    if (options.clientSecret !== undefined)
+      return parseClientSecret(options.clientSecret)
+    return options.secret ? secret() : undefined
+  })()
+
+  const now = new Date()
+  const [row] = await db
+    .insert(Schema.oauthClient)
+    .values({
+      applicationType: type,
+      clientId,
+      clientSecret: clientSecret ? await hashSecret(clientSecret) : null,
+      createdAt: now,
+      // Lets the app end the session at `GET /oauth2/end-session`, and puts `sid` in its ID tokens.
+      enableEndSession: true,
+      // A device app has no authorization code grant, so `/oauth2/authorize` refuses it.
+      grantTypes: device
+        ? [deviceGrant, 'refresh_token']
+        : ['authorization_code', 'refresh_token'],
+      id: crypto.randomUUID(),
+      name,
+      postLogoutRedirectUris: [...postLogoutRedirectUris],
+      redirectUris: [...redirectUris],
+      responseTypes: ['code'],
+      scopes: scopesOf({ sign: options.sign ?? false }),
+      skipConsent: options.skipConsent ?? false,
+      // The client package sends the secret in the form body.
+      tokenEndpointAuthMethod: clientSecret ? 'client_secret_post' : 'none',
+      updatedAt: now,
+    })
+    .onConflictDoNothing({ target: Schema.oauthClient.clientId })
+    .returning()
+  if (!row) throw new ExistsError({ clientId })
+
+  return { app: toApp(row), ...(clientSecret ? { clientSecret } : {}) }
+}
+
+export declare namespace create {
+  type Options = {
+    /**
+     * The client ID, such as the one that another deployment issued. Defaults to 32 random letters,
+     * as Better Auth issues.
+     */
+    clientId?: string | undefined
+    /**
+     * The client secret, such as the one that another deployment issued. It gives the app a secret
+     * without `secret`. Defaults to a new secret when `secret` is set.
+     */
+    clientSecret?: string | undefined
+    /**
+     * Whether the app signs in through the device grant, in place of a redirect, as a CLI does.
+     * Defaults to `false`.
+     */
+    device?: boolean | undefined
+    /** The display name, which the approval page shows. */
+    name: string
+    /** Every URI that `GET /oauth2/end-session` may return to. Defaults to none. */
+    postLogoutRedirectUris?: readonly string[] | undefined
+    /** Every URI that the app returns to, in each environment. A device app may have none. */
+    redirectUris?: readonly string[] | undefined
+    /** Whether the app receives a client secret, for its backend. Defaults to `false`. */
+    secret?: boolean | undefined
+    /** Whether the app holds the `tempo-id:sign` scope. Defaults to `false`. */
+    sign?: boolean | undefined
+    /** Whether a request without a key skips the approval page. Defaults to `false`. */
+    skipConsent?: boolean | undefined
+    /** The application type. Defaults to `web`. */
+    type?: App['type'] | undefined
+  }
+}
+
+/**
+ * Returns whether `origin` is the origin of a redirect URI of an enabled first-party app, one that
+ * skips consent. Pages on such an origin call the API with the session cookie. A disabled app,
+ * which Better Auth refuses, gives no origin. The registration rules keep production redirect URIs
+ * on `https`, so the check filters no scheme.
+ */
+export async function firstPartyOrigin(
+  db: Realm.Database,
+  options: firstPartyOrigin.Options,
+) {
+  const rows = await db
+    .select({ redirectUris: Schema.oauthClient.redirectUris })
+    .from(Schema.oauthClient)
+    .where(
+      and(
+        eq(Schema.oauthClient.skipConsent, true),
+        or(
+          isNull(Schema.oauthClient.disabled),
+          eq(Schema.oauthClient.disabled, false),
+        ),
+      ),
+    )
+  return rows.some((row) =>
+    row.redirectUris.some((uri) => {
+      const url = URL.parse(uri)
+      return (
+        (url?.protocol === 'https:' || url?.protocol === 'http:') &&
+        url.origin === options.origin
+      )
+    }),
+  )
+}
+
+export declare namespace firstPartyOrigin {
+  type Options = {
+    /** The request's `Origin`. */
+    origin: string
+  }
+}
+
+/**
+ * Returns the app with `clientId`. Throws `NotFoundError` when no app has it, or with `enabled`,
+ * when the app is disabled.
+ */
+export async function get(db: Realm.Database, options: get.Options) {
+  const row = await find(db, options)
+  if (options.enabled && row.disabled)
+    throw new NotFoundError({ clientId: options.clientId })
+  return toApp(row)
+}
+
+export declare namespace get {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+    /** Whether a disabled app counts as no app. Defaults to `false`. */
+    enabled?: boolean | undefined
+  }
+}
+
+/**
+ * Returns the SHA-256 hash of a client secret, as base64url without padding, which the row holds.
+ * Better Auth verifies a client secret against it.
+ */
+export async function hashSecret(secret: string) {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(secret),
+  )
+  return Base64.fromBytes(new Uint8Array(digest), { pad: false, url: true })
+}
+
+/**
+ * Compares two hashes from `hashSecret` in constant time. Node's `crypto.subtle` has no
+ * `timingSafeEqual`, and the CLI runs this module in Node, so the loop reads every byte of both.
+ */
+function equal(a: string, b: string) {
+  const left = Base64.toBytes(a)
+  const right = Base64.toBytes(b)
+  if (left.length !== right.length) return false
+  let difference = 0
+  for (let index = 0; index < left.length; index++)
+    difference |= left[index]! ^ right[index]!
+  return difference === 0
+}
+
+/** Returns every app, oldest first. */
+export async function list(db: Realm.Database): Promise<readonly App[]> {
+  const rows = await db
+    .select()
+    .from(Schema.oauthClient)
+    .orderBy(
+      asc(Schema.oauthClient.createdAt),
+      asc(Schema.oauthClient.clientId),
+    )
+  return rows.map(toApp)
+}
+
+/**
+ * Returns the Better Auth plugins that serve OAuth apps: the JWT plugin, which signs tokens with
+ * RS256, and the OAuth provider. `baseURL` is Tempo ID's origin, which is `iss` and the one resource.
+ */
+export function plugins(options: plugins.Options) {
+  const { accountStep, baseURL, pendingKey } = options
+  return [
+    // `iss` is the configured origin, never the request's host.
+    jwt({
+      adapter: SigningKey.adapter,
+      jwks: SigningKey.jwks,
+      jwt: { issuer: baseURL },
+    }),
+    oauthProvider({
+      allowDynamicClientRegistration: false,
+      consentPage: '/authorize',
+      // Apps read the user's address from the ID token, so a grant of `email` puts it there as well
+      // as in userinfo, as OIDC Core §5.4 allows.
+      customIdTokenClaims: (info) =>
+        info.scopes.includes('email')
+          ? {
+              email: info.user.email,
+              email_verified: info.user.emailVerified,
+            }
+          : {},
+      // Every app may request the one resource.
+      enforcePerClientResources: false,
+      loginPage: '/login',
+      // The account step runs after sign-in and before consent, and `oauth2Continue` resumes the
+      // authorization with `postLogin`, which checks again.
+      ...(accountStep
+        ? {
+            postLogin: {
+              consentReferenceId: () => undefined,
+              page: '/choose-account',
+              shouldRedirect: async (context: {
+                headers: Headers
+                session: { id: string }
+                user: { id: string }
+              }) => {
+                // The authorization stores its query before it checks, so the hook reads the app.
+                const query = (await getOAuthProviderState())?.query
+                const clientId = query
+                  ? new URLSearchParams(query).get('client_id')
+                  : null
+                if (!clientId) return false
+                return await accountStep({
+                  clientId,
+                  headers: context.headers,
+                  sessionId: context.session.id,
+                  userId: context.user.id,
+                })
+              },
+            },
+          }
+        : {}),
+      // A code's redemption returns the key that its approval signed, once. Better Auth calls this
+      // after it checks the verifier against the code's challenge.
+      ...(pendingKey
+        ? {
+            customTokenResponseFields: async (info: {
+              grantType: string
+              user?: { id: string } | null | undefined
+              verificationValue?: {
+                query: {
+                  client_id: string
+                  code_challenge?: string | undefined
+                  key_authorization?: unknown
+                }
+              }
+            }) => {
+              const query = info.verificationValue?.query
+              if (
+                info.grantType !== 'authorization_code' ||
+                !query?.code_challenge ||
+                // Only a code whose request carried the key takes it, so a keyless code for a reused
+                // challenge leaves it for the keyed one.
+                query.key_authorization === undefined ||
+                !info.user
+              )
+                return {}
+              const key = await pendingKey({
+                clientId: query.client_id,
+                codeChallenge: query.code_challenge,
+                userId: info.user.id,
+              })
+              if (!key) return {}
+              return {
+                account: key.account,
+                key_authorization: key.keyAuthorization,
+              }
+            },
+          }
+        : {}),
+      // Every access token names one audience, so each API verifies tokens for every app the same way.
+      resources: [
+        { accessTokenTtl: 300, identifier: baseURL, name: 'Tempo ID' },
+      ],
+      // Better Auth checks a registered app's scopes against its own row, so `tempo-id:sign` stays out
+      // of this list. A row without scopes falls back to this list, and never receives the scope.
+      scopes: [...scopes],
+      // `create` and `rotateSecret` store each secret with the same hash.
+      storeClientSecret: { hash: hashSecret },
+    }),
+  ]
+}
+
+export declare namespace plugins {
+  type Options = {
+    /**
+     * Returns whether the authorization of the app with `clientId` needs the account step, which
+     * the `/choose-account` page shows. Absent, no authorization shows it.
+     */
+    accountStep?:
+      | ((options: {
+          clientId: string
+          headers: Headers
+          sessionId: string
+          userId: string
+        }) => Promise<boolean>)
+      | undefined
+    /** Tempo ID's origin, such as `https://id.tempo.xyz`. */
+    baseURL: string
+    /**
+     * Takes the key authorization held for the app with `clientId`, the PKCE challenge
+     * `codeChallenge`, and the code's user, as `PendingKey.take` does. Absent, a code's redemption returns no key.
+     */
+    pendingKey?:
+      | ((options: {
+          clientId: string
+          codeChallenge: string
+          userId: string
+        }) => Promise<PendingKey.PendingKey | undefined>)
+      | undefined
+  }
+}
+
+/**
+ * Removes the app with `clientId`, with its consents, tokens, and realms. Throws `NotFoundError`
+ * when no app has it.
+ */
+export async function remove(db: Realm.Database, options: remove.Options) {
+  const removed = await db
+    .delete(Schema.oauthClient)
+    .where(eq(Schema.oauthClient.clientId, options.clientId))
+    .returning()
+  const [row] = removed
+  if (!row) throw new NotFoundError({ clientId: options.clientId })
+  return toApp(row)
+}
+
+export declare namespace remove {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+  }
+}
+
+/**
+ * Replaces the client secret of the app with `clientId`, and returns the app with the new secret.
+ * The earlier secret stops working at once.
+ *
+ * Throws `NotFoundError` when no app has the client ID, `PublicError` when the app has no client
+ * secret, and `InvalidError` for an invalid `clientSecret` or one that matches the current secret.
+ */
+export async function rotateSecret(
+  db: Realm.Database,
+  options: rotateSecret.Options,
+) {
+  const clientSecret =
+    options.clientSecret === undefined
+      ? secret()
+      : parseClientSecret(options.clientSecret)
+  const current = await find(db, options)
+  if (!current.clientSecret) throw new PublicError(options)
+  // A rotation to the same secret would leave a leaked secret working while it reports success.
+  if (equal(current.clientSecret, await hashSecret(clientSecret)))
+    throw new InvalidError(
+      'Invalid client secret: it matches the current secret. Use a new secret.',
+    )
+
+  const [row] = await db
+    .update(Schema.oauthClient)
+    .set({
+      clientSecret: await hashSecret(clientSecret),
+      updatedAt: new Date(),
+    })
+    .where(eq(Schema.oauthClient.clientId, options.clientId))
+    .returning()
+  // A concurrent `remove` deleted the app after the read.
+  if (!row) throw new NotFoundError(options)
+  // The row, not the earlier read, since a concurrent `update` can change the app between them.
+  return { app: toApp(row), clientSecret }
+}
+
+export declare namespace rotateSecret {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+    /** The new client secret, such as the one that another deployment issued. Defaults to a new secret. */
+    clientSecret?: string | undefined
+  }
+}
+
+/**
+ * Updates the app with `clientId`, and returns it. A value left out stays.
+ *
+ * Throws `NotFoundError` when no app has the client ID, and `InvalidError` for an invalid name or
+ * redirect URI.
+ */
+export async function update(db: Realm.Database, options: update.Options) {
+  const current = await find(db, options)
+  const app = toApp(current)
+  const name = options.name === undefined ? undefined : parseName(options.name)
+  const postLogoutRedirectUris =
+    options.postLogoutRedirectUris === undefined
+      ? undefined
+      : parsePostLogoutRedirectUris(options.postLogoutRedirectUris, {
+          type: app.type,
+        })
+  const redirectUris =
+    options.redirectUris === undefined
+      ? undefined
+      : parseRedirectUris(options.redirectUris, { type: app.type })
+
+  const [row] = await db
+    .update(Schema.oauthClient)
+    .set({
+      ...(name === undefined ? {} : { name }),
+      ...(postLogoutRedirectUris === undefined
+        ? {}
+        : { postLogoutRedirectUris: [...postLogoutRedirectUris] }),
+      // An app registered before logout existed gains it with its post-logout redirect URIs.
+      ...(postLogoutRedirectUris?.length ? { enableEndSession: true } : {}),
+      ...(redirectUris === undefined
+        ? {}
+        : { redirectUris: [...redirectUris] }),
+      ...(options.sign === undefined
+        ? {}
+        : {
+            scopes: scopesOf({
+              scopes: current.scopes ?? undefined,
+              sign: options.sign,
+            }),
+          }),
+      ...(options.skipConsent === undefined
+        ? {}
+        : { skipConsent: options.skipConsent }),
+      updatedAt: new Date(),
+    })
+    .where(eq(Schema.oauthClient.clientId, options.clientId))
+    .returning()
+  // A concurrent `remove` deleted the app after the read.
+  if (!row) throw new NotFoundError(options)
+  return toApp(row)
+}
+
+export declare namespace update {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+    /** The display name. */
+    name?: string | undefined
+    /** Every URI that `GET /oauth2/end-session` may return to. They replace the earlier ones, and none clears them. */
+    postLogoutRedirectUris?: readonly string[] | undefined
+    /** Every URI that the app returns to. They replace the earlier ones. */
+    redirectUris?: readonly string[] | undefined
+    /** Whether the app holds the `tempo-id:sign` scope. */
+    sign?: boolean | undefined
+    /** Whether a request without a key skips the approval page. */
+    skipConsent?: boolean | undefined
+  }
+}
+
+/** Returns the `oauth_client` row with `clientId`. Throws `NotFoundError` when no app has it. */
+async function find(db: Realm.Database, options: { clientId: string }) {
+  const [row] = await db
+    .select()
+    .from(Schema.oauthClient)
+    .where(eq(Schema.oauthClient.clientId, options.clientId))
+  if (!row) throw new NotFoundError({ clientId: options.clientId })
+  return row
+}
+
+/**
+ * Returns `clientId`. Throws `InvalidError` unless it holds 8 to 64 letters, digits, `-`, or `_`,
+ * which every URL and form carries unescaped.
+ */
+function parseClientId(clientId: string) {
+  if (!/^[A-Za-z0-9_-]{8,64}$/.test(clientId))
+    throw new InvalidError(
+      `Invalid client ID: ${clientId}. Use 8 to 64 letters, digits, -, or _.`,
+    )
+  return clientId
+}
+
+/** Returns `clientSecret`. Throws `InvalidError` when it holds fewer than 32 characters. */
+function parseClientSecret(clientSecret: string) {
+  // The message leaves the secret out, since errors never hold one.
+  if (clientSecret.length < 32)
+    throw new InvalidError(
+      'Invalid client secret: fewer than 32 characters. Use a longer secret.',
+    )
+  return clientSecret
+}
+
+/** Returns `name` trimmed. Throws `InvalidError` when it is empty. */
+function parseName(name: string) {
+  const trimmed = name.trim()
+  if (!trimmed)
+    throw new InvalidError('Invalid app: the name is empty. Set a name.')
+  return trimmed
+}
+
+/**
+ * Returns the post-logout redirect URIs `uris`, each named once. They follow the rules of
+ * `parseRedirectUris`, and may be empty. Throws `InvalidError` for an invalid URI.
+ */
+function parsePostLogoutRedirectUris(
+  uris: readonly string[],
+  options: { type: App['type'] },
+): readonly string[] {
+  if (uris.length === 0) return []
+  return parseRedirectUris(uris, options)
+}
+
+/**
+ * Returns `uris`, each named once. A web app returns to `https` URIs, and a native app to `https` or
+ * a custom scheme, such as `com.example.app:/callback`. Loopback and other `http` redirects are
+ * refused, so a CLI uses the device grant. Throws `InvalidError` for an invalid URI.
+ */
+function parseRedirectUris(
+  uris: readonly string[],
+  options: { type: App['type'] },
+): readonly string[] {
+  if (uris.length === 0)
+    throw new InvalidError(
+      'Invalid app: no redirect URI. Set at least one redirect URI.',
+    )
+
+  for (const uri of uris) {
+    const url = URL.parse(uri)
+    const reason = (() => {
+      if (!url) return 'is not an absolute URI'
+      // RFC 6749 §3.1.2 bars a fragment from a redirect URI.
+      if (url.hash || uri.includes('#')) return 'has a fragment'
+      if (url.username || url.password) return 'holds credentials'
+      if (url.protocol === 'https:')
+        return isLoopbackHost(url.hostname) ? 'has a loopback host' : undefined
+      if (url.protocol === 'http:') return 'uses http'
+      if (options.type === 'web') return 'is not https'
+      // Refuses reserved schemes, such as `javascript:` and `file:`, as Better Auth's registration does.
+      if (!isNativePrivateUseRedirectUri(url))
+        return 'is not a valid custom scheme'
+      return undefined
+    })()
+    if (reason)
+      throw new InvalidError(
+        `Invalid redirect URI: ${uri} ${reason}. Use an https URI${options.type === 'native' ? ', or a custom scheme such as com.example.app:/callback' : ''}.`,
+      )
+  }
+  return [...new Set(uris)]
+}
+
+/**
+ * Returns `scopes`, or the scopes that every app may request, with `tempo-id:sign` only when `sign`
+ * is set. Every other scope stays as it is.
+ */
+function scopesOf(options: {
+  scopes?: readonly string[] | undefined
+  sign: boolean
+}): string[] {
+  const kept = (options.scopes ?? scopes).filter((scope) => scope !== signScope)
+  return [...kept, ...(options.sign ? [signScope] : [])]
+}
+
+/** Returns a new client secret: 32 random letters, as Better Auth creates by default. */
+function secret() {
+  return generateRandomString(32, 'a-z', 'A-Z')
+}
+
+/** Returns the app of an `oauth_client` row. */
+function toApp(row: typeof Schema.oauthClient.$inferSelect): App {
+  return {
+    clientId: row.clientId,
+    createdAt: row.createdAt,
+    device: (row.grantTypes ?? []).includes(deviceGrant),
+    name: row.name,
+    postLogoutRedirectUris: row.postLogoutRedirectUris ?? [],
+    redirectUris: row.redirectUris,
+    secret: Boolean(row.clientSecret),
+    sign: (row.scopes ?? []).includes(signScope),
+    skipConsent: row.skipConsent ?? false,
+    type: row.applicationType === 'native' ? 'native' : 'web',
+  }
+}