@tempoxyz/id 0.0.0-stage → 0.0.0

package/src/internal/Auth.ts

@@ -0,0 +1,203 @@
+/**
+ * Builds the Better Auth options that every Tempo ID app shares, and declares the sign-in refusals.
+ * Callers pass the database, secret, and origin, so the options read no environment of their own.
+ * @module
+ */
+import type { betterAuth, BetterAuthOptions } from 'better-auth'
+import type * as BetterCall from 'better-call'
+import { oauthDeviceAuthorization } from '@better-auth/oauth-provider'
+import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { emailOTP } from 'better-auth/plugins/email-otp'
+import * as Schema from '../app/db/schema.js'
+import * as Apps from './Apps.js'
+import * as Device from './Device.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import * as Id from './Id.js'
+import * as Passkey from './Passkey.js'
+
+/**
+ * The app's authorization request that a sign-in or the approval page continues, its signed
+ * `oauth_query`, is forged or expired. The sign-in did not run, so the code stays unspent.
+ */
+export class AuthorizationExpiredError extends ErrorResponse.define(
+  'authorization_expired',
+) {
+  override readonly name = 'Auth.AuthorizationExpiredError'
+
+  constructor() {
+    super({
+      error_description:
+        'Expired authorization request: the request from the app is no longer valid. Return to the app, and start again.',
+      field: 'oauth_query',
+    })
+  }
+}
+
+/** The emailed code is wrong or expired. The refusal never reveals whether the account exists. */
+export class InvalidCodeError extends ErrorResponse.define('invalid_code') {
+  override readonly name = 'Auth.InvalidCodeError'
+
+  constructor() {
+    super({
+      error_description: 'Invalid or expired code. Request a new one.',
+      field: 'code',
+    })
+  }
+}
+
+/**
+ * The signed-in session differs from the one that the approval page showed, such as after a sign-in
+ * to another account in another tab. The approval page stored no consent.
+ */
+export class SessionChangedError extends ErrorResponse.define(
+  'session_changed',
+) {
+  override readonly name = 'Auth.SessionChangedError'
+
+  constructor() {
+    super({
+      error_description:
+        'Changed session: the signed-in account differs from the one that this page showed. Reload the page, and check the account before the decision.',
+      field: 'session_id',
+    })
+  }
+}
+
+/** The request needs a signed-in session, and has none. */
+export class SessionRequiredError extends ErrorResponse.define(
+  'session_required',
+) {
+  override readonly name = 'Auth.SessionRequiredError'
+
+  constructor() {
+    super({ error_description: 'Sign in first.' })
+  }
+}
+
+/**
+ * A request validation issue from the device plugin's types. Declarations name it through this alias,
+ * since TypeScript cannot reach it from `better-call`'s exports alone.
+ */
+export type Issue = BetterCall.StandardSchemaV1.Issue
+
+/** A Better Auth instance with Tempo ID's options, which each request creates. */
+export type Instance = ReturnType<typeof betterAuth<ReturnType<typeof options>>>
+
+/** The session cookie, which every app on the same site shares. */
+export const sessionCookie = 'tempo-id-session'
+
+/** Returns the Better Auth options for `options`. */
+export function options(options: options.Options) {
+  const {
+    accountStep,
+    baseURL,
+    db,
+    google,
+    pendingKey,
+    secret,
+    sendCode,
+    waitUntil,
+  } = options
+  return {
+    // A sign-in writes no provider tokens to the account, since Tempo ID holds tokens only in transit.
+    account: { updateAccountOnSignIn: false },
+    advanced: {
+      // A Worker cancels unawaited work once the response returns, so background sends join the request.
+      backgroundTasks: { handler: waitUntil },
+      cookies: { session_token: { name: sessionCookie } },
+      database: {
+        // User IDs keep WorkOS's format, since each is a token's `sub`.
+        generateId: (id) =>
+          id.model === 'user' ? Id.user() : crypto.randomUUID(),
+      },
+      ipAddress: { ipAddressHeaders: ['cf-connecting-ip'] },
+    },
+    // Every endpoint sits at the root, so discovery advertises `/oauth2/*`.
+    basePath: '/',
+    baseURL,
+    database: drizzleAdapter(db, { provider: 'pg', schema: Schema }),
+    databaseHooks: {
+      account: {
+        create: {
+          // A provider's account keeps its binding to the user and none of the provider's tokens.
+          before: () =>
+            Promise.resolve({
+              data: {
+                accessToken: null,
+                accessTokenExpiresAt: null,
+                idToken: null,
+                refreshToken: null,
+                refreshTokenExpiresAt: null,
+              },
+            }),
+        },
+      },
+      user: {
+        create: {
+          // Every user's address is verified. A Google account whose address Google has not verified
+          // could otherwise hold an address before its owner signs in with an emailed code.
+          before: (user) => Promise.resolve(user.emailVerified === true),
+        },
+      },
+    },
+    // A failed provider sign-in without its own error page returns to the sign-in page, which reads
+    // `error`.
+    onAPIError: { errorURL: `${baseURL}/login` },
+    plugins: [
+      emailOTP({
+        // Each code takes three guesses, counted in its `verification` row. A fourth refuses even the
+        // right code, so the address requests a new one.
+        allowedAttempts: 3,
+        expiresIn: 600,
+        otpLength: 6,
+        sendVerificationOTP: (data) =>
+          sendCode({ code: data.otp, email: data.email }),
+        storeOTP: 'hashed',
+      }),
+      Passkey.plugin(),
+      ...Apps.plugins({ accountStep, baseURL, pendingKey }),
+      // The old device grant's lifetime, interval, and user codes, which CLIs already expect.
+      oauthDeviceAuthorization({
+        expiresIn: `${Device.lifetime}s`,
+        generateUserCode: Id.userCode,
+        interval: `${Device.interval}s`,
+        verificationUri: Device.page,
+      }),
+    ],
+    // Better Auth's limiter runs only in `auth.handler` and keys on the IP address and path, so the
+    // Workers rate-limit bindings in `RateLimit` count requests instead, and every 429 is an API error.
+    rateLimit: { enabled: false },
+    secret,
+    socialProviders: google
+      ? {
+          google: {
+            clientId: google.clientId,
+            clientSecret: google.clientSecret,
+            // Google asks which account to use, so a browser signed in to several accounts can pick.
+            prompt: 'select_account',
+          },
+        }
+      : {},
+  } satisfies BetterAuthOptions
+}
+
+export declare namespace options {
+  type Options = {
+    /** Decides whether an authorization needs the account step, as `Apps.plugins` describes. */
+    accountStep?: Apps.plugins.Options['accountStep']
+    /** Tempo ID's origin, such as `https://id.tempo.xyz`. */
+    baseURL: string
+    /** The Drizzle database that holds Tempo ID's tables. */
+    db: Parameters<typeof drizzleAdapter>[0]
+    /** Google's OAuth client. Absent, Tempo ID offers no Google sign-in. */
+    google?: { clientId: string; clientSecret: string } | undefined
+    /** Takes the key authorization that a code's redemption returns, as `Apps.plugins` describes. */
+    pendingKey?: Apps.plugins.Options['pendingKey']
+    /** The secret that signs cookies and encrypts the signing keys. */
+    secret: string
+    /** Emails a sign-in code to an address. */
+    sendCode: (options: { code: string; email: string }) => Promise<void>
+    /** Keeps work alive after the response, such as `c.executionCtx.waitUntil`. */
+    waitUntil: (promise: Promise<unknown>) => void
+  }
+}

package/src/internal/Authorize.ts

@@ -0,0 +1,424 @@
+/**
+ * Authorization requests that carry a key authorization. In a headless request, a first-party web
+ * app's page asks Tempo ID to authorize it for the signed-in user without a redirect. The request
+ * names the app's redirect URI, and its key must fit the headless ceiling. Any other app, native apps
+ * included, authorizes through a redirect, whose `/authorize` query carries the key to the approval
+ * page.
+ * @module
+ */
+import { Base64 } from 'ox'
+import { z } from 'zod'
+import type * as Apps from './Apps.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import * as KeyAuthorization from './KeyAuthorization.js'
+import * as Validation from './Validation.js'
+
+/** A headless request came from an origin that its redirect URI does not allow. */
+export class InvalidOriginError extends ErrorResponse.define('invalid_origin') {
+  override readonly name = 'Authorize.InvalidOriginError'
+}
+
+/**
+ * The request names no registered app or redirect URI, the app is not a first-party app, or the app
+ * cannot receive tokens headlessly.
+ */
+export class RejectedError extends ErrorResponse.define('rejected') {
+  override readonly name = 'Authorize.RejectedError'
+
+  constructor(options: RejectedError.Options = {}) {
+    super({
+      error_description:
+        options.description ??
+        "Authorization request rejected. Check `client_id`, `redirect_uri`, and `scope` against the app's registration.",
+    })
+  }
+}
+
+export declare namespace RejectedError {
+  type Options = {
+    /** The refusal's description, in place of the default that names the fields to check. */
+    description?: string | undefined
+  }
+}
+
+/** Zod schemas for headless authorization requests and their responses. */
+export namespace schema {
+  /** The tokens that a public app receives. */
+  export const tokens = z
+    .object({
+      access_token: z.string().meta({
+        description:
+          "The access token, a JWT that Tempo ID signs. APIs verify it against Tempo ID's JSON Web Key Set.",
+        examples: ['eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyIn0.c2lnbmF0dXJl'],
+      }),
+      expires_in: z.number().meta({
+        description: 'Seconds until the access token expires.',
+        examples: [300],
+      }),
+      id_token: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'The OIDC ID token, a JWT about the user. Absent when the request did not ask for the `openid` scope.',
+          examples: ['eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJhcHAifQ.c2lnbmF0dXJl'],
+        }),
+      refresh_token: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'The refresh token, which the app redeems at `/oauth2/token` for new tokens. Absent without the `offline_access` scope.',
+          examples: ['yAjhKk7QnRZ3vD9pLm2Xc8Ws5Tf1Ub4N'],
+        }),
+      token_type: z.string().meta({
+        description: 'The type of the access token (RFC 6749 §7.1).',
+        examples: ['Bearer'],
+      }),
+    })
+    .meta({ description: 'OAuth tokens for a public app.', id: 'Tokens' })
+
+  /** A message whose EIP-191 hash becomes a key authorization's witness. */
+  export const challenge = z
+    .string()
+    .min(1)
+    .max(1024)
+    .optional()
+    .meta({
+      description:
+        "A message, such as a sign-in challenge from the app's backend, whose EIP-191 hash becomes the key authorization's `witness` (TIP-1053). Requires `key_authorization`, and the app's `tempo-id:sign` scope.",
+      examples: ['Sign in to app.example.com\nNonce: 7f3a9c2e5b1d4f60'],
+    })
+
+  /** An app's headless authorization request. */
+  export const request = z
+    .object({
+      challenge,
+      client_id: z
+        .string()
+        .min(1)
+        .max(255)
+        .meta({
+          description: "The app's client ID.",
+          examples: ['Qk3vT9xZbLmN2pRw8YcHjF6sDaE4uGtK'],
+        }),
+      code_challenge: z
+        .string()
+        .regex(/^[\w-]{43}$/)
+        .optional()
+        .meta({
+          description:
+            "The S256 PKCE challenge of a verifier that the app's backend holds (RFC 7636). With one, the app receives a code. Without one, a public app receives tokens.",
+          examples: ['E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM'],
+        }),
+      key_authorization: KeyAuthorization.schema.request,
+      // Schemes that run script or read files are refused.
+      redirect_uri: z
+        .url({
+          protocol:
+            /^(?!(?:blob|data|file|javascript|vbscript)$)[a-z][a-z\d+.-]*$/,
+        })
+        .meta({
+          description:
+            'A registered redirect URI of a web app, whose origin the page calls from.',
+          examples: ['https://app.example.com/callback'],
+        }),
+      scope: z
+        .string()
+        .regex(/^[\w:.-]+( [\w:.-]+)*$/)
+        .max(256)
+        .optional()
+        .meta({
+          description: 'Space-separated OAuth scopes. Defaults to `openid`.',
+          examples: ['openid email offline_access'],
+        }),
+      state: z
+        .string()
+        .min(1)
+        .max(256)
+        .optional()
+        .meta({
+          description:
+            'An opaque value that the response returns unchanged, to bind it to the request (RFC 6749 §4.1.1).',
+          examples: ['af0ifjsldkj'],
+        }),
+    })
+    .refine((request) => !request.challenge || request.key_authorization, {
+      message:
+        'A challenge requires `key_authorization`, whose witness binds it',
+      path: ['challenge'],
+    })
+    // The key carries the challenge as its witness, so the owner's signature binds it.
+    .transform((request) =>
+      request.key_authorization
+        ? {
+            ...request,
+            key_authorization: KeyAuthorization.bind(
+              request.key_authorization,
+              { challenge: request.challenge },
+            ),
+          }
+        : request,
+    )
+    .meta({
+      description: "An app's headless authorization request.",
+      id: 'AuthorizationRequest',
+    })
+
+  /**
+   * The key of a redirect's authorization request: the `challenge` and the decoded
+   * `key_authorization` of its `/authorize` query, with the challenge bound as the key's witness.
+   */
+  export const redirect = z
+    .object({ challenge, key_authorization: KeyAuthorization.schema.request })
+    .refine((request) => !request.challenge || request.key_authorization, {
+      message:
+        'A challenge requires `key_authorization`, whose witness binds it',
+      path: ['challenge'],
+    })
+    .transform((request) =>
+      request.key_authorization
+        ? KeyAuthorization.bind(request.key_authorization, {
+            challenge: request.challenge,
+          })
+        : undefined,
+    )
+
+  /** What a headless authorization returns: a code or tokens, with any signed key. */
+  export const response = z
+    .object({
+      account: KeyAuthorization.schema.account.optional(),
+      code: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            "The authorization code, when the request sent a `code_challenge`. The app's backend redeems it at `/oauth2/token`.",
+          examples: ['Vb7mQ2xLkP9sTzR4'],
+        }),
+      key_authorization: KeyAuthorization.schema.rpc.optional(),
+      state: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            "The request's `state`, unchanged. Absent when the request sent none.",
+          examples: ['af0ifjsldkj'],
+        }),
+      tokens: tokens.optional().meta({
+        description: 'The tokens, when the request sent no `code_challenge`.',
+      }),
+    })
+    .meta({
+      description:
+        'An authorization: a code or tokens, with the signed key authorization when the request asks for one.',
+      id: 'Authorization',
+    })
+}
+
+/** An app's headless authorization request. */
+export type Request = z.output<typeof schema.request>
+
+/**
+ * Returns why Tempo ID refuses a headless `request`, or `undefined` when the caller may make it:
+ *
+ * - The app must exist, register `redirect_uri`, and be a first-party app, which skips consent.
+ * - The app must be a web app, and its page must call from its redirect URI's origin. A native app
+ *   authorizes through an authentication sheet.
+ * - A key must come from a page of an app without a client secret, fit the headless ceiling, and
+ *   carry a challenge only for an app with the `tempo-id:sign` scope. Any other app authorizes a key
+ *   through a redirect or the device grant.
+ */
+export function check(
+  request: Request,
+  options: check.Options,
+): ErrorResponse.Instance<typeof check.errors> | undefined {
+  const { app, origin } = options
+  if (!app || !app.redirectUris.includes(request.redirect_uri))
+    return new RejectedError()
+  // A public app proves nothing about its caller, so a program that impersonates it receives what
+  // the response carries. Only first-party apps, which skip consent, authorize headlessly. Any other
+  // app's code goes to its redirect URI, after the user approves the request.
+  if (!app.skipConsent)
+    return new RejectedError({
+      description:
+        'Headless authorization refused: the app is not a first-party app. Send the user to `/oauth2/authorize`, and receive the code at the redirect URI.',
+    })
+
+  // A native app's request proves no app, since any program can send one, with or without its
+  // redirect URI's `Origin`. Its code goes to its redirect URI, through an authentication sheet.
+  if (app.type === 'native')
+    return new RejectedError({
+      description:
+        "Headless authorization refused: a native app's request does not prove which app sends it. Open `/oauth2/authorize` in an authentication sheet, and receive the code at the redirect URI.",
+    })
+
+  // A browser sets `Origin` itself, so a page calls from its redirect URI's origin.
+  const redirectUri = new URL(request.redirect_uri)
+  if (origin !== redirectUri.origin)
+    return new InvalidOriginError({
+      error_description: `Invalid \`Origin\`: ${origin ?? 'none'}. Requests for this redirect URI must come from ${redirectUri.origin}.`,
+      field: 'Origin',
+      meta: { expected: redirectUri.origin, ...(origin ? { origin } : {}) },
+    })
+
+  const key = request.key_authorization
+  if (!key) return undefined
+  // A confidential app proves itself only with its secret, which a page never holds, and the code
+  // redemption that checks it returns no key.
+  if (app.secret)
+    return new RejectedError({
+      description:
+        'Key authorization refused: the app holds a client secret, which a headless request does not prove. Authorize the key through a redirect or the device grant.',
+    })
+  return (
+    KeyAuthorization.checkHeadless(key) ??
+    KeyAuthorization.checkChallenge({ app, clientId: request.client_id, key })
+  )
+}
+
+export namespace check {
+  export type Options = {
+    /** The app that `client_id` names, or `undefined` when no app has it. */
+    app:
+      | Pick<
+          Apps.App,
+          'redirectUris' | 'secret' | 'sign' | 'skipConsent' | 'type'
+        >
+      | undefined
+    /** The request's `Origin`, if any. */
+    origin: string | undefined
+  }
+
+  /** The refusals `check` returns. Its return type admits no other. */
+  export const errors = [
+    ...KeyAuthorization.checkHeadless.errors,
+    ...KeyAuthorization.checkChallenge.errors,
+    InvalidOriginError,
+    RejectedError,
+  ] as const
+}
+
+/**
+ * Returns why Tempo ID refuses `key` in a redirect's authorization request, or `undefined` when the
+ * owner may sign it once the user approves it. The approval page shows the key, so it applies the
+ * rules of `KeyAuthorization.check` and no headless ceiling. A challenge needs the app's
+ * `tempo-id:sign` scope, and the request needs a PKCE challenge, whose verifier receives the key.
+ */
+export function checkKey(
+  options: checkKey.Options,
+): ErrorResponse.Instance<typeof checkKey.errors> | undefined {
+  const { app, clientId, codeChallenge, key } = options
+  if (!codeChallenge)
+    return new RejectedError({
+      description:
+        'Key authorization refused: the request names no `code_challenge`, whose verifier receives the key. Send an S256 `code_challenge`.',
+    })
+  return (
+    KeyAuthorization.check(key) ??
+    KeyAuthorization.checkChallenge({ app, clientId, key })
+  )
+}
+
+export namespace checkKey {
+  export type Options = {
+    /** The app that `clientId` names, or `undefined` when no app has it. */
+    app: Pick<Apps.App, 'sign'> | undefined
+    /** The client ID of the app that requests the key. */
+    clientId: string
+    /** The request's `code_challenge`, if any. */
+    codeChallenge: string | null | undefined
+    /** The key that the request carries. */
+    key: KeyAuthorization.Key
+  }
+
+  /** The refusals `checkKey` returns. Its return type admits no other. */
+  export const errors = [
+    ...KeyAuthorization.check.errors,
+    ...KeyAuthorization.checkChallenge.errors,
+    RejectedError,
+  ] as const
+}
+
+/**
+ * Returns the key that a redirect's authorization `query` carries: its `key_authorization`,
+ * base64url JSON, with its `challenge` bound as the witness. Returns `undefined` for a query without
+ * a key, and `Validation.InvalidFieldError` for a key that does not parse, a challenge without a
+ * key, or a repeated parameter, so a page cannot show one value and approve another.
+ */
+export function fromQuery(
+  query: URLSearchParams,
+): KeyAuthorization.Key | Validation.InvalidFieldError | undefined {
+  const repeated = keyParameters.find((name) => query.getAll(name).length > 1)
+  if (repeated)
+    return new Validation.InvalidFieldError({
+      issues: [
+        {
+          message: 'Repeated parameter. Send it once',
+          path: [repeated],
+        },
+      ],
+    })
+
+  const encoded = query.get('key_authorization')
+  const parsed = schema.redirect.safeParse({
+    challenge: query.get('challenge') ?? undefined,
+    key_authorization: encoded === null ? undefined : decode(encoded),
+  })
+  if (!parsed.success)
+    return new Validation.InvalidFieldError({ issues: parsed.error.issues })
+  return parsed.data
+}
+
+/**
+ * Returns the parameters of an authorization request that carries `key_authorization` with
+ * `consent` added to `prompt`, so the approval page shows the key, also for an app that skips
+ * consent. A key that names no expiry gains the default, so approval signs the expiry that the page
+ * shows. Returns other parameters unchanged.
+ */
+export function prepare(parameters: URLSearchParams) {
+  if (!parameters.has('key_authorization')) return parameters
+
+  const prepared = new URLSearchParams(parameters)
+  const prompt = new Set(
+    (prepared.get('prompt') ?? '').split(' ').filter(Boolean),
+  )
+  prompt.add('consent')
+  prepared.set('prompt', [...prompt].join(' '))
+
+  // A repeated key stays as it is, so the page refuses it.
+  const [encoded, ...rest] = prepared.getAll('key_authorization')
+  const key = encoded && !rest.length ? decode(encoded) : undefined
+  if (
+    typeof key === 'object' &&
+    key !== null &&
+    !Array.isArray(key) &&
+    !('expiry' in key)
+  )
+    prepared.set(
+      'key_authorization',
+      Base64.fromString(
+        JSON.stringify({
+          ...key,
+          expiry: Math.floor(Date.now() / 1000) + KeyAuthorization.lifetime,
+        }),
+        base64url,
+      ),
+    )
+  return prepared
+}
+
+/** Unpadded URL-safe Base64, as the client encodes `key_authorization`. */
+const base64url = { pad: false, url: true } as const
+
+/** The query parameters that carry a redirect's key. */
+const keyParameters = ['challenge', 'key_authorization'] as const
+
+/** Decodes base64url JSON, or returns `null`, which fails validation. */
+function decode(value: string): unknown {
+  try {
+    return JSON.parse(Base64.toString(value))
+  } catch {
+    return null
+  }
+}