@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/internal/Migrations.ts

@@ -0,0 +1,120 @@
+/**
+ * Applies the package's migrations to a Postgres database. It keeps Void's ledger, `_void_migrations`
+ * by file name, so `void db migrate` in `src/app` and `tempo-id admin migrate` each skip what the
+ * other applied.
+ * @module
+ */
+import * as Fs from 'node:fs'
+import * as Path from 'node:path'
+import pg from 'pg'
+
+/**
+ * The advisory lock that serializes concurrent runs. Void's own runner takes none, so it and this
+ * command must not run at once.
+ */
+const lock = 7_105_201_133
+
+/** The package's migrations. The module is `src/internal/` or `dist/internal/`, two folders below the root. */
+export const directory = Path.join(
+  import.meta.dirname,
+  '..',
+  '..',
+  'src',
+  'app',
+  'db',
+  'migrations',
+)
+
+/** A Postgres schema name, which becomes part of SQL identifiers. */
+const schemaPattern = /^[a-z_][a-z0-9_]{0,62}$/
+
+/**
+ * Applies each migration in `directory` that the ledger lacks, in file name order, each in its own
+ * transaction. Connects directly, since the lock needs a session that Hyperdrive does not keep.
+ * Returns the names it applied. A failed migration rolls back, and the error names its file.
+ *
+ * With `schema`, it creates the schema if it is absent, and applies the migrations and keeps the
+ * ledger there. drizzle-kit names `public` in each foreign key, so each file's `"public".` becomes
+ * the schema.
+ */
+export async function apply(options: apply.Options) {
+  const schema =
+    options.schema === 'public' ? undefined : options.schema || undefined
+  if (schema !== undefined && !schemaPattern.test(schema))
+    throw new Error(
+      `Invalid schema: ${JSON.stringify(schema)}. Pass a lowercase Postgres schema name, such as pr_141.`,
+    )
+
+  const client = new pg.Client({ connectionString: options.connectionString })
+  await client.connect()
+
+  try {
+    // Previews share one database, so each schema takes a key of its own, and a stuck run on one
+    // schema never holds up the runs of another.
+    if (schema)
+      await client.query('select pg_advisory_lock(hashtextextended($1, $2))', [
+        schema,
+        lock,
+      ])
+    else await client.query('select pg_advisory_lock($1)', [lock])
+    // The session is direct, so `search_path` holds for each statement that follows.
+    if (schema) {
+      await client.query(`create schema if not exists "${schema}"`)
+      await client.query(`set search_path to "${schema}"`)
+    }
+    await client.query(
+      'create table if not exists _void_migrations (name text primary key, applied_at text not null)',
+    )
+    const ledger = await client.query<{ name: string }>(
+      'select name from _void_migrations',
+    )
+    const done = new Set(ledger.rows.map((row) => row.name))
+
+    const applied: string[] = []
+    const names = Fs.readdirSync(options.directory ?? directory)
+      .filter((name) => name.endsWith('.sql'))
+      .sort()
+    for (const name of names) {
+      if (done.has(name)) continue
+      const text = Fs.readFileSync(
+        Path.join(options.directory ?? directory, name),
+        'utf8',
+      )
+      const sql = schema
+        ? text.replaceAll('REFERENCES "public".', `REFERENCES "${schema}".`)
+        : text
+      try {
+        await client.query('begin')
+        await client.query(sql)
+        await client.query(
+          'insert into _void_migrations (name, applied_at) values ($1, $2)',
+          [name, new Date().toISOString()],
+        )
+        await client.query('commit')
+      } catch (error) {
+        await client.query('rollback')
+        throw new Error(`Migration ${name} failed.`, { cause: error })
+      }
+      applied.push(name)
+    }
+
+    return { applied }
+  } finally {
+    // Ending the session releases the lock.
+    await client.end()
+  }
+}
+
+export declare namespace apply {
+  type Options = {
+    /** A direct Postgres connection string, never a Hyperdrive one. */
+    connectionString: string
+    /** The folder of `.sql` migrations. Defaults to the package's. */
+    directory?: string | undefined
+    /**
+     * The Postgres schema that holds the tables and the ledger, such as a preview's `pr_141`.
+     * Defaults to `public`.
+     */
+    schema?: string | undefined
+  }
+}

package/src/internal/OpenApi.ts

@@ -0,0 +1,300 @@
+/**
+ * Documents the API's Hono routes with `hono-openapi`. Routes stay plain Hono routes: each one adds
+ * `describeRoute` for its documentation and `validate` for each input. The document is generated
+ * from the mounted app.
+ * @module
+ */
+import type { Hono, MiddlewareHandler, ValidationTargets } from 'hono'
+import {
+  generateSpecs,
+  type HandlerUniqueProperty,
+  resolver,
+  type ResponsesWithResolver,
+  uniqueSymbol,
+  validator,
+} from 'hono-openapi'
+import type * as z from 'zod'
+import * as Auth from './Auth.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import * as Validation from './Validation.js'
+
+export { describeRoute, resolver, validator } from 'hono-openapi'
+
+/**
+ * Conversion options for every schema. A hex quantity also accepts a bigint in process, which JSON
+ * Schema cannot express. That branch converts to `{}` and is dropped, which leaves the hex string
+ * that JSON requests send. Zod marks `.readonly()` schemas `readOnly`, which OpenAPI reads as
+ * server-set, so request fields drop it.
+ */
+const options = {
+  options: {
+    override: (context: {
+      jsonSchema: {
+        anyOf?: Record<string, unknown>[] | undefined
+        readOnly?: boolean | undefined
+      }
+    }) => {
+      const { jsonSchema } = context
+      delete jsonSchema.readOnly
+      const anyOf = jsonSchema.anyOf?.filter(
+        (branch) => Object.keys(branch).length > 0,
+      )
+      if (!anyOf || anyOf.length === jsonSchema.anyOf!.length) return
+      if (anyOf.length === 1) {
+        delete jsonSchema.anyOf
+        Object.assign(jsonSchema, anyOf[0])
+      } else jsonSchema.anyOf = anyOf
+    },
+    unrepresentable: 'any',
+  },
+} as const
+
+/**
+ * The Scalar bundle the reference loads: one file, pinned by version and by the SHA-384 digest of
+ * `dist/browser/standalone.js` in the npm tarball of `@scalar/api-reference@1.72.1`.
+ */
+const scalar = {
+  integrity:
+    'sha384-U11tb2XnKvmwt8RlTvnwUnYgrN+ur4Xyh9htLhjajWNR/Oyl5AX5DEz00qRmlrmK',
+  src: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.72.1/dist/browser/standalone.js',
+} as const
+
+/** The OpenAPI document's description of the API. */
+const info = {
+  description:
+    'Tempo ID signs users in to Tempo apps, authorizes apps for them, and signs key authorizations on their Tempo Accounts. Every refusal is an OAuth error response (RFC 6749 §5.2) whose `reason` determines its `error` and status.',
+  title: 'Tempo ID',
+  version: '0.0.0',
+} as const
+
+/**
+ * Returns the OpenAPI document for `app`, generated on the first call. The document is reused for
+ * the life of the isolate, since routes do not change while it runs. Every refusal joins its
+ * components, including those no route declares, such as `unknown_endpoint`.
+ */
+export function document(
+  app: Hono<any, any, any>,
+): ReturnType<typeof generateSpecs> {
+  const cached = documents.get(app)
+  if (cached) return cached
+
+  const generated = generate(app)
+  documents.set(app, generated)
+  // A failed generation is not cached, so the next request tries again.
+  generated.catch(() => documents.delete(app))
+  return generated
+}
+
+/**
+ * The API reference page, which renders `/openapi.json` with Scalar. Scalar mounts from the
+ * `api-reference` element, so the page has no inline script.
+ */
+export const reference = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Tempo ID API</title>
+  </head>
+  <body>
+    <script id="api-reference" type="application/json" data-url="/openapi.json"></script>
+    <script src="${scalar.src}" integrity="${scalar.integrity}" crossorigin="anonymous"></script>
+  </body>
+</html>
+`
+
+/**
+ * The reference page's Content Security Policy. The page shares the session cookie's origin, so it
+ * runs only the pinned Scalar bundle, whose integrity the browser checks, and calls only this origin.
+ */
+export const referencePolicy = [
+  "default-src 'self'",
+  `script-src ${scalar.src}`,
+  // Scalar injects its styles at runtime, and loads its fonts from its own host.
+  "style-src 'self' 'unsafe-inline' https://fonts.scalar.com",
+  'font-src https://fonts.scalar.com',
+  "img-src 'self' data:",
+  "connect-src 'self'",
+  "object-src 'none'",
+  "base-uri 'none'",
+  "form-action 'none'",
+  "frame-ancestors 'none'",
+].join('; ')
+
+/**
+ * The OpenAPI responses for the refusals in `classes`, grouped by the status of each, plus
+ * `unexpected`, which any route can return.
+ */
+export function errors(classes: readonly ErrorResponse.Class[]) {
+  const byStatus = new Map<number, ErrorResponse.Reason[]>()
+  for (const reason of new Set(
+    [...classes, ErrorResponse.UnexpectedError].map((error) => error.reason),
+  ).values()) {
+    const status = ErrorResponse.reasons[reason].status
+    byStatus.set(status, [...(byStatus.get(status) ?? []), reason])
+  }
+  return Object.fromEntries(
+    [...byStatus].map(([status, group]) => [
+      status,
+      {
+        content: {
+          'application/json': {
+            schema: {
+              anyOf: group.map((reason) => ({
+                $ref: `#/components/schemas/ErrorResponse.${reason}`,
+              })),
+            },
+          },
+        },
+        description: group.map((reason) => `\`${reason}\``).join(', '),
+      },
+    ]),
+  )
+}
+
+/**
+ * Documents `target` with `schema` without validating or changing the request, for routes that
+ * fall through to a page or pass the issuer's requests through. A `form` documents a URL-encoded
+ * body.
+ */
+export function input<const target extends keyof ValidationTargets>(
+  target: target,
+  schema: z.ZodType,
+): MiddlewareHandler {
+  // The validator carries the documentation, which the generator reads from this symbol. OAuth
+  // form posts are URL-encoded, where the generator would otherwise document multipart.
+  const documented = validator(target, schema, undefined, {
+    ...options,
+    ...(target === 'form'
+      ? { media: 'application/x-www-form-urlencoded' }
+      : {}),
+  }) as {
+    [uniqueSymbol]?: HandlerUniqueProperty | undefined
+  }
+  return Object.assign<MiddlewareHandler, object>((_c, next) => next(), {
+    [uniqueSymbol]: documented[uniqueSymbol],
+  })
+}
+
+/**
+ * The OpenAPI responses of a JSON route: `success` at its status, and the refusals in `errors`,
+ * grouped by the status of each, plus `unexpected`.
+ */
+export function responses<const schema extends z.ZodType>(
+  options_: responses.Options<schema>,
+): ResponsesWithResolver {
+  const { errors: classes = [], success } = options_
+  return {
+    [success.status ?? 200]: {
+      content: {
+        'application/json': { schema: resolver(success.schema, options) },
+      },
+      description: success.description,
+    },
+    ...errors(classes),
+  }
+}
+
+export declare namespace responses {
+  type Options<schema extends z.ZodType> = {
+    /** The class of every refusal the route returns, thrown ones included. */
+    errors?: readonly ErrorResponse.Class[] | undefined
+    /** The success response. */
+    success: {
+      /** What the response means. */
+      description: string
+      /** The response body's schema. */
+      schema: schema
+      /** The success status. Defaults to 200. */
+      status?: 200 | 201 | undefined
+    }
+  }
+}
+
+/**
+ * Validates `target` against `schema`, documents it, and responds to a failure with an
+ * `invalid_field` error response. Hono refuses an unreadable JSON body as `malformed_body` before
+ * the schema runs.
+ */
+export function validate<
+  const target extends keyof ValidationTargets,
+  const schema extends z.ZodType,
+>(target: target, schema: schema) {
+  return validator(
+    target,
+    schema,
+    (result, c) => {
+      if (!result.success)
+        return ErrorResponse.json(
+          c,
+          new Validation.InvalidFieldError({ issues: result.error }),
+        )
+    },
+    options,
+  )
+}
+
+export namespace validate {
+  /** The refusals validation returns. Hono refuses an unreadable JSON body before the schema runs. */
+  export const errors = [
+    ErrorResponse.MalformedBodyError,
+    Validation.InvalidFieldError,
+  ] as const
+}
+
+/** Each app's document, generated once per isolate. */
+const documents = new WeakMap<
+  Hono<any, any, any>,
+  ReturnType<typeof generate>
+>()
+
+/** Generates the OpenAPI document for `app`. */
+async function generate(app: Hono<any, any, any>) {
+  // Each refusal's schema has an `id`, so converting it yields a reference plus the component.
+  const converted = await Promise.all(
+    (Object.keys(ErrorResponse.reasons) as ErrorResponse.Reason[]).map(
+      async (reason) =>
+        (
+          await resolver(
+            ErrorResponse.schema.of(reason),
+            options,
+          ).toOpenAPISchema()
+        ).components?.schemas,
+    ),
+  )
+  const schemas = Object.assign({}, ...converted)
+  return generateSpecs(app, {
+    defaultValidationErrorResponse: false,
+    // The document's own route ends in `.json`, which the generator would skip as a static file.
+    excludeStaticFile: false,
+    documentation: {
+      components: {
+        schemas,
+        securitySchemes: {
+          accessToken: {
+            bearerFormat: 'JWT',
+            description:
+              'An access token from `/oauth2/token`, as `Authorization: Bearer <token>`.',
+            scheme: 'bearer',
+            type: 'http',
+          },
+          clientBasic: {
+            description:
+              "An OAuth app's client ID and secret, as HTTP Basic `Authorization` (RFC 6749 §2.3.1).",
+            scheme: 'basic',
+            type: 'http',
+          },
+          sessionCookie: {
+            description:
+              "The Tempo ID session, which sign-in sets as an HTTP-only cookie on Tempo ID's origin.",
+            in: 'cookie',
+            name: Auth.sessionCookie,
+            type: 'apiKey',
+          },
+        },
+      },
+      info,
+      openapi: '3.1.0',
+    },
+  })
+}