@tempoxyz/id 0.0.0-stage → 0.0.0

package/src/api/provider.ts

@@ -0,0 +1,441 @@
+/**
+ * Sign-in with an OAuth provider, such as Google: the providers Tempo ID offers, the redirect to a
+ * provider, and the provider's callback, which Better Auth's social sign-in serves.
+ * @module
+ */
+import { isAPIError } from 'better-auth/api'
+import { Hono } from 'hono'
+import { deleteCookie, getCookie, setCookie } from 'hono/cookie'
+import { serialize } from 'hono/utils/cookie'
+import { env } from 'void/env'
+import * as z from 'zod'
+import * as core_Auth from '../internal/Auth.js'
+import type { Env } from '../internal/Env.js'
+import * as ErrorResponse from '../internal/ErrorResponse.js'
+import * as Log from '../internal/Log.js'
+import * as OpenApi from '../internal/OpenApi.js'
+import * as Provider from '../internal/Provider.js'
+import * as RateLimit from '../internal/RateLimit.js'
+import * as SignInGrant from '../internal/SignInGrant.js'
+import * as Timing from '../internal/Timing.js'
+import * as Auth from './lib/Auth.js'
+import { db } from './lib/Database.js'
+import * as FirstAccount from './lib/FirstAccount.js'
+import * as SignInConsent from './lib/SignInConsent.js'
+
+/**
+ * The cookie that marks the app's authorization request whose provider sign-in the sign-in page
+ * started. The `__Host-` prefix pins it to the host that set it with `Path=/`.
+ */
+const grantCookie = 'tempo-id-grant'
+
+/**
+ * The cookie that names the app whose authorization the provider sign-in continues, so the callback
+ * creates the user's first account in that app's realm. Better Auth keeps `oauth_query` in its own
+ * state, which the callback cannot read. The `__Host-` prefix pins it to the host that set it.
+ */
+const appCookie = 'tempo-id-sign-in-app'
+
+/** How long the provider sign-in has to return before its grant lapses, in seconds. */
+const grantLifetime = 10 * 60
+
+namespace schema {
+  export namespace providers {
+    export const response = z.object({
+      providers: z
+        .array(
+          z
+            .object({
+              id: z.enum(['google']).meta({
+                description:
+                  "The provider's ID, which `GET /v1/auth/oauth/{provider}` takes.",
+                examples: ['google'],
+              }),
+              name: z.string().meta({
+                description: 'The name to show, such as `Google`.',
+                examples: ['Google'],
+              }),
+            })
+            .meta({ description: 'One provider Tempo ID offers.' }),
+        )
+        .readonly()
+        .meta({
+          description:
+            'The providers Tempo ID offers, in the order a page shows them. Empty when the deployment configures none.',
+        }),
+    })
+  }
+
+  export namespace signIn {
+    export const param = z.object({
+      provider: z
+        .string()
+        .min(1)
+        .max(64)
+        .meta({
+          description: 'The ID of the provider, from `GET /v1/auth/providers`.',
+          examples: ['google'],
+        }),
+    })
+
+    export const query = z.object({
+      client_id: z
+        .string()
+        .min(1)
+        .max(255)
+        .optional()
+        .meta({
+          description:
+            "The app's client ID. A `return_to` on an origin of the app's redirect URIs requires it.",
+          examples: ['client_01JZ8Q6W3N1R5B4V7C2X9K0M3T'],
+        }),
+      oauth_query: z
+        .string()
+        .min(1)
+        .max(8192)
+        .optional()
+        .meta({
+          description:
+            "The signed authorization request in the sign-in page's query. The callback continues it, and redirects to the app.",
+          examples: [
+            'client_id=tempo-cli&response_type=code&exp=1767225600&sig=4mLx2Wq9cH8t',
+          ],
+        }),
+      return_to: z
+        .string()
+        .min(1)
+        // Holds the sign-in page's path with the whole `oauth_query`, which `/login` passes back.
+        .max(8448)
+        // A path resolves against Tempo ID's origin, so any origin parses it the same way.
+        .refine((value) => URL.canParse(value, 'https://id.invalid'), {
+          message: 'Set an absolute URL, or a path on Tempo ID',
+        })
+        .optional()
+        .meta({
+          description:
+            "The page that the browser returns to, signed in, on Tempo ID's origin or an origin of the app's redirect URIs. Defaults to the account page. A failed sign-in returns there with `error=access_denied`.",
+          examples: ['https://app.example.com/welcome'],
+        }),
+    })
+  }
+
+  export namespace failed {
+    export const param = signIn.param
+
+    export const query = signIn.query.pick({
+      client_id: true,
+      return_to: true,
+    })
+  }
+
+  export namespace callback {
+    export const param = signIn.param
+
+    export const query = z.object({
+      code: z
+        .string()
+        .optional()
+        .meta({
+          description: "The provider's authorization code.",
+          examples: ['4/0AVMBsJh7c2X9K0M3T'],
+        }),
+      error: z
+        .string()
+        .optional()
+        .meta({
+          description: "The provider's error code, for a refused sign-in.",
+          examples: ['access_denied'],
+        }),
+      state: z
+        .string()
+        .optional()
+        .meta({
+          description: 'The state that the redirect to the provider sent.',
+          examples: ['Qm7rXcJ2bWv9Tk4LsN8pHd3F'],
+        }),
+    })
+  }
+}
+
+/** The provider sign-in routes. */
+export const provider = new Hono<Env>()
+  .get(
+    '/v1/auth/providers',
+    OpenApi.describeRoute({
+      description:
+        'Lists the OAuth providers Tempo ID offers, for an app that shows its own sign-in buttons.',
+      responses: OpenApi.responses({
+        success: {
+          description: 'The providers.',
+          schema: schema.providers.response,
+        },
+      }),
+      tags: ['Authenticate'],
+    }),
+    (c) => c.json({ providers: Provider.list({ google: Auth.google() }) }, 200),
+  )
+  .get(
+    '/v1/auth/oauth/:provider',
+    OpenApi.describeRoute({
+      description:
+        "Redirects the browser to the provider. The provider returns it to `/callback/{provider}`, which sets the session cookie, then continues `oauth_query` or redirects to `return_to`. The callback grants the key of `oauth_query` only when Tempo ID's own sign-in page sent the browser here.",
+      responses: {
+        302: { description: 'Redirects the browser to the provider.' },
+        ...OpenApi.errors([
+          ...OpenApi.validate.errors,
+          ...Provider.returnTo.errors,
+          ...RateLimit.check.errors,
+          core_Auth.AuthorizationExpiredError,
+          Provider.UnknownError,
+        ]),
+      },
+      tags: ['Authenticate'],
+    }),
+    OpenApi.validate('param', schema.signIn.param),
+    OpenApi.validate('query', schema.signIn.query),
+    async (c) => {
+      const query = c.req.valid('query')
+      const offered = Provider.list({ google: Auth.google() }).find(
+        (entry) => entry.id === c.req.valid('param').provider,
+      )
+      if (!offered)
+        return ErrorResponse.json(
+          c,
+          new Provider.UnknownError({
+            provider: c.req.valid('param').provider,
+          }),
+        )
+
+      // Each redirect stores its state in a `verification` row until the callback spends it. Any site
+      // can send a browser here with a GET, so the redirects count on their own key, and spend none
+      // of the address's quota for email and passkey sign-in.
+      const ip = RateLimit.ip(c)
+      const refused = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [
+            {
+              binding: 'SIGN_IN_IP_LIMIT',
+              key: ip ? `provider:${ip}` : undefined,
+            },
+          ],
+        }),
+        'RateLimit.check',
+      )
+      if (refused) return refused
+
+      const returnTo = await Timing.measure(
+        c,
+        Provider.returnTo(db, {
+          clientId: query.client_id,
+          own: new URL(env.URL).origin,
+          returnTo: query.return_to ?? '/',
+        }),
+        'Provider.returnTo',
+      )
+      if (returnTo instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, returnTo)
+
+      const failed = new URL(`/v1/auth/oauth/${offered.id}/failed`, env.URL)
+      // The failed route checks the page again, so it takes the page as sent, which its length limit
+      // holds. The resolved URL is longer by Tempo ID's origin.
+      failed.searchParams.set('return_to', query.return_to ?? '/')
+      if (query.client_id) failed.searchParams.set('client_id', query.client_id)
+
+      const result = await Timing.measure(
+        c,
+        c.var.auth.api.signInSocial({
+          body: {
+            callbackURL: returnTo,
+            disableRedirect: true,
+            // Better Auth's codes can reveal whether an account exists, so its errors pass through
+            // the `failed` route, which returns one code.
+            errorCallbackURL: failed.href,
+            provider: offered.id,
+            ...(query.oauth_query ? { oauth_query: query.oauth_query } : {}),
+          },
+          headers: new Headers(c.req.raw.headers),
+          returnHeaders: true,
+        }),
+        'auth.signInSocial',
+      ).catch((error: unknown) => {
+        if (isAPIError(error) && error.body?.error === 'invalid_signature')
+          return new core_Auth.AuthorizationExpiredError()
+        throw error
+      })
+      if (result instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, result)
+
+      for (const cookie of result.headers.getSetCookie())
+        c.header('set-cookie', cookie, { append: true })
+      // Any site can send a browser here, so the callback grants the request's key only for a start
+      // from Tempo ID's own page, which shows the key. The browser sets `sec-fetch-site`, and no page
+      // can forge it.
+      if (query.oauth_query && c.req.header('sec-fetch-site') === 'same-origin')
+        setCookie(
+          c,
+          grantCookie,
+          SignInGrant.identity(new URLSearchParams(query.oauth_query)),
+          {
+            httpOnly: true,
+            maxAge: grantLifetime,
+            path: '/',
+            prefix: 'host',
+            sameSite: 'Lax',
+            secure: true,
+          },
+        )
+      else
+        deleteCookie(c, grantCookie, {
+          path: '/',
+          prefix: 'host',
+          secure: true,
+        })
+      // Better Auth checked the signature of `oauth_query` above, so its client ID is the app's.
+      const app = query.oauth_query
+        ? new URLSearchParams(query.oauth_query).get('client_id')
+        : null
+      if (app)
+        setCookie(c, appCookie, app, {
+          httpOnly: true,
+          maxAge: grantLifetime,
+          path: '/',
+          prefix: 'host',
+          sameSite: 'Lax',
+          secure: true,
+        })
+      else
+        deleteCookie(c, appCookie, { path: '/', prefix: 'host', secure: true })
+      c.header('cache-control', 'private, no-store')
+      return c.redirect(result.response.url ?? '/', 302)
+    },
+  )
+  .get(
+    '/v1/auth/oauth/:provider/failed',
+    OpenApi.describeRoute({
+      description:
+        'Redirects the browser from a failed provider sign-in to `return_to`, with `error=access_denied`. The code is the same for every cause, so it reveals neither the cause nor whether an account exists.',
+      responses: {
+        302: { description: 'Redirects the browser to `return_to`.' },
+        ...OpenApi.errors([
+          ...OpenApi.validate.errors,
+          ...Provider.returnTo.errors,
+        ]),
+      },
+      tags: ['Authenticate'],
+    }),
+    OpenApi.validate('param', schema.failed.param),
+    OpenApi.validate('query', schema.failed.query),
+    async (c) => {
+      const query = c.req.valid('query')
+      // Anyone can send a browser here, so the page is checked again.
+      const returnTo = await Timing.measure(
+        c,
+        Provider.returnTo(db, {
+          clientId: query.client_id,
+          own: new URL(env.URL).origin,
+          returnTo: query.return_to ?? '/login',
+        }),
+        'Provider.returnTo',
+      )
+      if (returnTo instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, returnTo)
+
+      const url = new URL(returnTo)
+      url.searchParams.set('error', 'access_denied')
+      return c.redirect(url.href, 302)
+    },
+  )
+  .get(
+    '/callback/:provider',
+    OpenApi.describeRoute({
+      description:
+        "Receives the provider's redirect, sets the session cookie, and redirects the browser to `return_to`, or continues the app's authorization. For a user with no Tempo Account in the realm of the sign-in, it creates one, as `POST /v1/auth/code/verify` does. Every failure redirects to the failed route or to the sign-in page.",
+      responses: {
+        302: {
+          description:
+            "Redirects the browser to `return_to`, to the app's redirect URI, or to the failed route.",
+        },
+        ...OpenApi.errors([]),
+      },
+      tags: ['Authenticate'],
+    }),
+    OpenApi.input('param', schema.callback.param),
+    OpenApi.input('query', schema.callback.query),
+    async (c) => {
+      const response = await Timing.measure(
+        c,
+        c.var.auth.handler(c.req.raw),
+        'auth.handler',
+      )
+      const location = response.headers.get('location')
+      if (response.status !== 302 || !location) return response
+
+      // A sign-in sets the session cookie on the response, so the session names its user. A failed
+      // sign-in sets none. Each start sets or clears the app's cookie, so it names this sign-in's app.
+      const cookie = response.headers
+        .getSetCookie()
+        .map((entry) => entry.split(';', 1)[0])
+        .join('; ')
+      // A failed read skips the creation, so the sign-in still returns Better Auth's redirect.
+      const session = cookie
+        ? await Timing.measure(
+            c,
+            c.var.auth.api.getSession({ headers: new Headers({ cookie }) }),
+            'auth.getSession',
+          ).catch((error: unknown) => {
+            Log.warn(c, {
+              error,
+              message:
+                'The provider sign-in created no first account, since its session failed to load.',
+            })
+            return null
+          })
+        : null
+      if (session)
+        await Timing.measure(
+          c,
+          FirstAccount.create(c, {
+            clientId: getCookie(c, appCookie, 'host') ?? null,
+            userId: session.user.id,
+          }),
+          'FirstAccount.create',
+        )
+
+      // Only a sign-in that the sign-in page started, for this request, grants its key. Any other
+      // keeps Better Auth's redirect to the approval page, which shows the key.
+      const started = getCookie(c, grantCookie, 'host')
+      const continued = URL.parse(location, env.URL)
+      const redirect =
+        started &&
+        continued &&
+        SignInGrant.identity(continued.searchParams) === started
+          ? await Timing.measure(
+              c,
+              SignInConsent.afterSignIn(c, {
+                redirect: location,
+                setCookie: response.headers.getSetCookie(),
+              }),
+              'SignInConsent.afterSignIn',
+            )
+          : location
+      if (!started && redirect === location) return response
+
+      // The handler's headers are immutable, so the redirect goes on a copy that keeps its cookies.
+      const headers = new Headers(response.headers)
+      headers.set('location', redirect)
+      // The grant applies once, so the callback clears its cookie.
+      if (started)
+        headers.append(
+          'set-cookie',
+          serialize(`__Host-${grantCookie}`, '', {
+            httpOnly: true,
+            maxAge: 0,
+            path: '/',
+            sameSite: 'Lax',
+            secure: true,
+          }),
+        )
+      return new Response(null, { headers, status: 302 })
+    },
+  )

package/src/app/components/Button.tsx

@@ -0,0 +1,128 @@
+/** Renders a button as a `<button>` or, given `to`, a router link styled as one. @module */
+import { Link, type LinkComponentProps } from '@tanstack/react-router'
+import type { ButtonHTMLAttributes, ReactNode } from 'react'
+import type { Props } from 'zyzz'
+import Spinner from '~icons/lucide/loader-circle'
+import type { FileRouteTypes } from '../routeTree.gen.js'
+import { style, variants } from '../zyzz.config.js'
+
+/**
+ * A button in the `default`, `secondary`, or `tertiary` variant and the `medium` or `large`
+ * size. `loading` disables a `<button>` and shows a spinner in place of `prefix`.
+ */
+export function Button(props: Button.Props): ReactNode {
+  const { children, loading, prefix, size, variant, ...rest } = props
+  const selection = styles.button({ size, variant })
+  const content = (
+    <>
+      {loading ? <Spinner {...styles.spinner()} aria-hidden /> : prefix}
+      <span {...styles.label()}>{children}</span>
+    </>
+  )
+
+  if ('to' in rest)
+    return (
+      <Link {...rest} {...selection}>
+        {content}
+      </Link>
+    )
+
+  return (
+    <button
+      type="button"
+      {...rest}
+      {...selection}
+      aria-busy={loading || undefined}
+      disabled={rest.disabled || loading}
+    >
+      {content}
+    </button>
+  )
+}
+
+export declare namespace Button {
+  /** The variant, size, and content, with a `<button>`'s attributes, or a link's when `to` is set. */
+  type Props = Props.Variants<typeof styles.button> & {
+    /** Button content, usually its label. */
+    children: ReactNode
+    /** Disables a `<button>` and replaces `prefix` with a spinner while an action runs. */
+    loading?: boolean | undefined
+    /** An icon shown before the label. */
+    prefix?: ReactNode | undefined
+  } & (
+      | Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'prefix'>
+      | (Omit<LinkComponentProps, 'children' | 'prefix' | 'to'> & {
+          /** The page that the link opens. Renders a router link instead of a `<button>`. */
+          to: FileRouteTypes['to']
+        })
+    )
+}
+
+namespace styles {
+  export const button = variants({
+    base: {
+      alignItems: 'center',
+      border: '1px solid',
+      borderColor: 'transparent',
+      borderRadius: 'full',
+      cursor: 'pointer',
+      display: 'inline-flex',
+      gap: 2,
+      justifyContent: 'center',
+      outline: 'none',
+      textDecoration: 'none',
+      transitionDuration: '150ms',
+      transitionProperty: 'background-color, border-color, color',
+      transitionTimingFunction: 'in-out',
+      userSelect: 'none',
+      whiteSpace: 'nowrap',
+      ':disabled': { cursor: 'not-allowed' },
+      // The focus ring: a 2px gap, then 2px of blue.
+      ':focus-visible': {
+        outline: '2px solid',
+        outlineColor: 'blue.700',
+        outlineOffset: '2px',
+      },
+    },
+    defaultVariants: { size: 'large', variant: 'default' },
+    variants: {
+      size: {
+        large: { height: 12, paddingInline: 6, typography: 'button.16' },
+        medium: { height: 9, paddingInline: 4, typography: 'button.14' },
+      },
+      // A disabled button keeps its fill and dims its label. A loading one keeps its label, since
+      // the spinner shows its state.
+      variant: {
+        default: {
+          backgroundColor: 'foreground',
+          backgroundImage: 'sheen',
+          color: 'background.surface',
+          ':disabled:not([aria-busy="true"])': { color: 'gray.700' },
+          ':hover:not(:disabled)': { backgroundColor: 'gray.950' },
+        },
+        secondary: {
+          backgroundColor: 'background.surface',
+          borderColor: 'gray.400',
+          color: 'foreground',
+          ':disabled:not([aria-busy="true"])': { color: 'gray.700' },
+          ':hover:not(:disabled)': { backgroundColor: 'gray.100' },
+        },
+        tertiary: {
+          backgroundColor: 'transparent',
+          color: 'foreground',
+          ':disabled:not([aria-busy="true"])': { color: 'gray.700' },
+          ':hover:not(:disabled)': { backgroundColor: 'gray.100' },
+        },
+      },
+    },
+  })
+
+  export const label = style({ overflow: 'hidden', textOverflow: 'ellipsis' })
+
+  export const spinner = style({
+    flexShrink: 0,
+    height: 4,
+    width: 4,
+    '@media (prefers-reduced-motion: no-preference)': { animation: 'spin' },
+  })
+}