@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/api/device.ts

@@ -0,0 +1,516 @@
+/**
+ * The device page's side of the device grant (RFC 8628) under `/v1/device`. A CLI requests a code
+ * at `/device/code` and polls `/oauth2/token`. A signed-in user reads the code's request here, and
+ * approves or denies it from any browser. Approval signs any key authorization that the request
+ * carries, which the first redemption returns beside the tokens. Approval and denial accept requests
+ * only from Tempo ID's own page, so no app's page decides a code for the user.
+ * @module
+ */
+import type { Context } from 'hono'
+import { Hono } from 'hono'
+import { env } from 'void/env'
+import * as z from 'zod'
+import * as core_Auth from '../internal/Auth.js'
+import * as BodyLimit from '../internal/BodyLimit.js'
+import * as Chain from '../internal/Chain.js'
+import * as Device from '../internal/Device.js'
+import type { Env } from '../internal/Env.js'
+import * as ErrorResponse from '../internal/ErrorResponse.js'
+import * as KeyAuthorization from '../internal/KeyAuthorization.js'
+import * as OpenApi from '../internal/OpenApi.js'
+import * as Passkey from '../internal/Passkey.js'
+import * as RateLimit from '../internal/RateLimit.js'
+import * as TempoAccount from '../internal/TempoAccount.js'
+import * as Timing from '../internal/Timing.js'
+import * as Cors from './lib/Cors.js'
+import { db } from './lib/Database.js'
+import * as DeviceRequest from './lib/DeviceRequest.js'
+import * as KeySigner from './lib/KeySigner.js'
+import * as Session from './lib/Session.js'
+
+namespace schema {
+  export namespace requests {
+    export const param = z.object({
+      code: z
+        .string()
+        .meta({ description: 'The user code.', examples: ['WDJB-MJHT'] }),
+    })
+
+    export const response = z.object({
+      request: z
+        .object({
+          app: z
+            .object({
+              name: z.string().meta({
+                description: "The app's display name.",
+                examples: ['Tempo CLI'],
+              }),
+            })
+            .optional()
+            .meta({
+              description:
+                'The app that requested the code. Absent when the app has no display name.',
+            }),
+          challenge: z
+            .string()
+            .optional()
+            .meta({
+              description:
+                "The message whose EIP-191 hash is the key's witness, which approval signs. Absent when the CLI sent none.",
+              examples: ['Sign in to app.example.com\nNonce: 7f3a9c2e5b1d4f60'],
+            }),
+          created_at: z.number().meta({
+            description: 'When the CLI requested the code, in Unix seconds.',
+            examples: [1792075800],
+          }),
+          device: z
+            .string()
+            .optional()
+            .meta({
+              description:
+                'The name that the CLI reported, such as its hostname. Absent for a code from `POST /device/code`.',
+              examples: ['ada-macbook'],
+            }),
+          ip: z
+            .string()
+            .optional()
+            .meta({
+              description: "The CLI's IP address. Absent when it is unknown.",
+              examples: ['203.0.113.7'],
+            }),
+          key_authorization: KeyAuthorization.schema.description
+            .extend({
+              account: KeyAuthorization.schema.description.shape.account.meta({
+                description:
+                  'The Tempo Account that approval signs for: the one the request names, else the one the user selected for the app, else the oldest. Absent when the request names none and the accounts cannot be read, or the user holds none.',
+                examples: ['0x9a073914db0d149375ac2b7fbb72c68c0780fb5f'],
+              }),
+              chain: z
+                .object({
+                  id: z
+                    .number()
+                    .int()
+                    .meta({
+                      description: 'The ID of the chain that the key acts on.',
+                      examples: [42431],
+                    }),
+                  name: Chain.schema.optional().meta({
+                    description:
+                      'The name that `GET /v1/chains` lists for the chain. Absent for a chain that no name lists.',
+                    examples: ['testnet'],
+                  }),
+                })
+                .optional()
+                .meta({
+                  description:
+                    'The chain that the key acts on. Absent once the user decides.',
+                }),
+              refusal: KeySigner.schema.refusal.optional(),
+            })
+            .optional()
+            .meta({
+              description:
+                'What the key that the CLI requested may do. Absent when the CLI requested no key.',
+            }),
+          location: z
+            .string()
+            .optional()
+            .meta({
+              description:
+                "The CLI's city and country, from its IP address. Absent when they are unknown.",
+              examples: ['Berlin, DE'],
+            }),
+          status: z.enum(['approved', 'denied', 'pending']).meta({
+            description:
+              'Whether the user approved or denied the code. `pending` until the user decides.',
+            examples: ['pending'],
+          }),
+          user_code: z
+            .string()
+            .meta({ description: 'The user code.', examples: ['WDJB-MJHT'] }),
+        })
+        .meta({ description: 'The request that the CLI made with the code.' }),
+    })
+  }
+
+  export namespace approve {
+    export const json = z.object({
+      account: TempoAccount.schema.tempoAccount.shape.address.optional().meta({
+        description:
+          "The Tempo Account that the device page showed for the request's key authorization, one of the user's accounts in the app's realms. Ignored when the key names its account, and absent for a request without a key.",
+        examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+      }),
+      code: z
+        .string()
+        .max(32)
+        .meta({ description: 'The user code.', examples: ['WDJB-MJHT'] }),
+      passkey: z
+        .object({ assertion: Passkey.schema.assertion })
+        .optional()
+        .meta({
+          description:
+            "The passkey's assertion over the options of the passkey step, which a passkey-owned account's approval returns. The repeated approval signs the key with it.",
+        }),
+    })
+
+    export const step = Passkey.schema.step
+
+    export const response = z.union([
+      z
+        .object({
+          status: z.literal('approved').meta({
+            description:
+              'The user approved the code. The CLI receives its tokens, and any signed key, on its next poll.',
+          }),
+        })
+        .meta({ description: 'A stored approval.' }),
+      step,
+    ])
+  }
+
+  export namespace deny {
+    export const json = z.object({ code: approve.json.shape.code })
+
+    export const response = z.object({
+      status: z.literal('denied').meta({
+        description:
+          'The user denied the code. The next poll returns `access_denied`.',
+      }),
+    })
+  }
+}
+
+/**
+ * Records the signed-in user's decision on the live user code `code`, from Tempo ID's own page.
+ * The code first binds to the user, so no other user can sign its key or decide it after. An
+ * approval of a request with a key then signs the key and holds it for the code's redemption, so a
+ * refused key approves nothing, and a failed approval releases it. For a passkey-owned account, it
+ * returns the options of the passkey step, and the repeated approval with the assertion signs the
+ * key. Returns `undefined` once the decision is stored, the passkey step, the rate limit's
+ * response, or a refusal.
+ */
+async function decide(
+  c: Context<Env>,
+  options: decide.Options,
+): Promise<
+  | ErrorResponse.Instance<typeof decide.errors>
+  | NonNullable<Awaited<ReturnType<typeof RateLimit.check>>>
+  | { options: Awaited<ReturnType<typeof KeySigner.challenge>> }
+  | undefined
+> {
+  if (Cors.appOrigin(c)) return new ErrorResponse.CrossSiteRequestError()
+
+  const session = await Timing.measure(c, Session.get(c), 'Session.get')
+  if (!session) return new core_Auth.SessionRequiredError()
+
+  // Counted per user, as the approval page's decisions are, since each decision reads the database.
+  const limited = await Timing.measure(
+    c,
+    RateLimit.check(c, {
+      limits: [{ binding: 'AUTHORIZE_LIMIT', key: session.user.id }],
+    }),
+    'RateLimit.check',
+  )
+  if (limited) return limited
+
+  const userCode = Device.normalize(options.code)
+  const found = userCode
+    ? await Timing.measure(c, Device.get(db, { userCode }), 'Device.get')
+    : undefined
+  // A code that another user holds is unknown to this one, as `DeviceRequest.read` returns it.
+  if (!userCode || !found || (found.userId && found.userId !== session.user.id))
+    return new Device.UnknownCodeError()
+  // A decided code refuses before the binding, and before any passkey step.
+  if (found.status !== 'pending') return new Device.AlreadyDecidedError()
+
+  // The code binds to this user first, in one conditional update, so of concurrent decisions by
+  // several users only the bound user's signs a key or decides.
+  const bound = await (async () => {
+    if (found.userId) return found
+    const stored = await Timing.measure(
+      c,
+      Device.bind(db, { id: found.id, userId: session.user.id }),
+      'Device.bind',
+    )
+    if (stored) return { ...found, userId: session.user.id }
+    return await Timing.measure(c, Device.get(db, { userCode }), 'Device.get')
+  })()
+  // A code that another user bound in the meantime stays unknown to this one.
+  if (!bound || bound.userId !== session.user.id)
+    return new Device.UnknownCodeError()
+  if (bound.status !== 'pending') return new Device.AlreadyDecidedError()
+
+  // An approval of a request with a key signs the key and holds it first, so a refused key
+  // approves nothing.
+  const held = await (async () => {
+    if (options.decision !== 'approve' || !bound.key) return undefined
+    const signed = await Timing.measure(
+      c,
+      DeviceRequest.sign(c, {
+        account: options.account,
+        assertion: options.assertion,
+        request: bound,
+        session,
+      }),
+      'DeviceRequest.sign',
+    )
+    if (signed instanceof ErrorResponse.ResponseError) return signed
+    // A passkey signs only in this browser, so the page signs the digest and repeats the approval.
+    if (signed.options) return { options: signed.options }
+    const key = {
+      account: signed.account,
+      keyAuthorization: signed.keyAuthorization,
+    }
+    const stored = await Timing.measure(
+      c,
+      Device.hold(db, { id: bound.id, key, userId: session.user.id }),
+      'Device.hold',
+    )
+    // Another decision, the key of a concurrent approval, or the code's expiry came first.
+    if (!stored) return await refusal()
+    return { key }
+  })()
+  if (held instanceof ErrorResponse.ResponseError) return held
+  if (held && 'options' in held) return { options: held.options }
+
+  // A failed approval releases its key while the code is pending, so the user can approve again.
+  const release = async () => {
+    if (held)
+      await Timing.measure(
+        c,
+        Device.release(db, { id: bound.id, key: held.key }),
+        'Device.release',
+      )
+  }
+
+  // The decision is one conditional update on the bound, pending code, so of concurrent decisions
+  // only one records its status.
+  const decided = await Timing.measure(
+    c,
+    Device.decide(db, {
+      id: bound.id,
+      status: options.decision === 'approve' ? 'approved' : 'denied',
+      userId: session.user.id,
+    }).catch(async (error: unknown) => {
+      await release()
+      throw error
+    }),
+    'Device.decide',
+  )
+  if (decided) return undefined
+  // Another decision, by this user, or the code's expiry, came between the read and the update.
+  await release()
+  return await refusal()
+
+  /** Returns the refusal of a code that changed after the read: unknown when it expired. */
+  async function refusal() {
+    const current = await Timing.measure(
+      c,
+      Device.get(db, { userCode: userCode! }),
+      'Device.get',
+    )
+    if (!current) return new Device.UnknownCodeError()
+    return new Device.AlreadyDecidedError()
+  }
+}
+
+declare namespace decide {
+  type Options = {
+    /** The account that the device page showed for the request's key, if any. */
+    account?: `0x${string}` | undefined
+    /** The passkey's assertion over the options of the passkey step, if any. */
+    assertion?: Passkey.Assertion | undefined
+    /** The user code, as the user typed it. */
+    code: string
+    /** Whether the user approves or denies the code. */
+    decision: 'approve' | 'deny'
+  }
+}
+
+namespace decide {
+  /** The refusals `decide` returns. Its return type admits no other. */
+  export const errors = [
+    ...DeviceRequest.sign.errors,
+    core_Auth.SessionRequiredError,
+    Device.AlreadyDecidedError,
+    Device.UnknownCodeError,
+    ErrorResponse.CrossSiteRequestError,
+  ] as const
+}
+
+/** The device page's reads and decisions of device codes. */
+export const device = new Hono<Env>()
+  .get(
+    '/v1/device/requests/:code',
+    OpenApi.describeRoute({
+      description:
+        'Reads the request of a device code for the device page, by its user code. The first signed-in user to read a pending code binds it, so no other user can decide it.',
+      responses: OpenApi.responses({
+        errors: [
+          ...OpenApi.validate.errors,
+          ...DeviceRequest.read.errors,
+          ...RateLimit.check.errors,
+          core_Auth.SessionRequiredError,
+          ErrorResponse.CrossSiteRequestError,
+        ],
+        success: {
+          description: 'What the CLI requested.',
+          schema: schema.requests.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Device grant'],
+    }),
+    OpenApi.validate('param', schema.requests.param),
+    async (c) => {
+      // The session cookie is `Lax`, so a top-level navigation from another site carries it. The read
+      // binds a pending code and spends the user's limits, so no other site's page starts one.
+      if (c.req.header('sec-fetch-site') === 'cross-site')
+        return ErrorResponse.json(c, new ErrorResponse.CrossSiteRequestError())
+
+      const session = await Timing.measure(c, Session.get(c), 'Session.get')
+      if (!session)
+        return ErrorResponse.json(c, new core_Auth.SessionRequiredError())
+
+      // A user code holds about 34 bits, so each user's lookups count, which keeps a guess of a live
+      // code out of reach (RFC 8628 §5.1). They count apart from the user's authorizations, so a
+      // page that sends the user's lookups spends none of that quota.
+      const limited = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [
+            { binding: 'AUTHORIZE_LIMIT', key: `${session.user.id}:device` },
+          ],
+        }),
+        'RateLimit.check',
+      )
+      if (limited) return limited
+
+      const found = await Timing.measure(
+        c,
+        DeviceRequest.read(c, {
+          code: c.req.valid('param').code,
+          userId: session.user.id,
+        }),
+        'DeviceRequest.read',
+      )
+      c.header('cache-control', 'private, no-store')
+      if (found instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, found)
+
+      // The key's account resolves in the realms of the app that requested the code.
+      const { chainId, clientId, request } = found
+      const { key_authorization, ...rest } = request
+      if (!key_authorization || request.status !== 'pending')
+        return c.json({ request }, 200)
+      const preview = await Timing.measure(
+        c,
+        KeySigner.preview(c, {
+          account: key_authorization.account,
+          chainId,
+          clientId,
+          email: session.user.email,
+          sessionId: session.session.id,
+          userId: session.user.id,
+        }),
+        'KeySigner.preview',
+      )
+      const id = Number(chainId)
+      const name = Chain.name({ chainId: id, rpcUrls: env.RPC_URLS })
+      return c.json(
+        {
+          request: {
+            ...rest,
+            key_authorization: {
+              ...key_authorization,
+              ...(preview.account ? { account: preview.account } : {}),
+              chain: { id, ...(name ? { name } : {}) },
+              ...(preview.refusal ? { refusal: preview.refusal } : {}),
+            },
+          },
+        },
+        200,
+      )
+    },
+  )
+  .post(
+    '/v1/device/approve',
+    OpenApi.describeRoute({
+      description:
+        "Approves a device code for the signed-in user, and the CLI's next poll returns its tokens and any signed key. If the key names no account and the user holds none, the approval first creates an account. Only Tempo ID's device page sends the request.",
+      responses: OpenApi.responses({
+        errors: [
+          ...BodyLimit.errors,
+          ...OpenApi.validate.errors,
+          ...RateLimit.check.errors,
+          ...decide.errors,
+        ],
+        success: {
+          description: 'The code is approved, or the passkey step.',
+          schema: schema.approve.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Device grant'],
+    }),
+    OpenApi.validate('json', schema.approve.json),
+    async (c) => {
+      const { account, code, passkey } = c.req.valid('json')
+      const result = await Timing.measure(
+        c,
+        decide(c, {
+          account,
+          assertion: passkey?.assertion,
+          code,
+          decision: 'approve',
+        }),
+        'device.decide',
+      )
+      if (result instanceof Response) return result
+      if (result instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, result)
+      if (result) {
+        c.header('cache-control', 'private, no-store')
+        return c.json(
+          schema.approve.step.parse({
+            step: { options: result.options, type: 'passkey' },
+          }),
+          200,
+        )
+      }
+      return c.json({ status: 'approved' as const }, 200)
+    },
+  )
+  .post(
+    '/v1/device/deny',
+    OpenApi.describeRoute({
+      description:
+        "Denies a device code for the signed-in user, and the CLI's next poll returns `access_denied`. Only Tempo ID's device page sends the request.",
+      responses: OpenApi.responses({
+        errors: [
+          ...BodyLimit.errors,
+          ...OpenApi.validate.errors,
+          ...RateLimit.check.errors,
+          ...decide.errors,
+        ],
+        success: {
+          description: 'The code is denied.',
+          schema: schema.deny.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Device grant'],
+    }),
+    OpenApi.validate('json', schema.deny.json),
+    async (c) => {
+      const result = await Timing.measure(
+        c,
+        decide(c, { code: c.req.valid('json').code, decision: 'deny' }),
+        'device.decide',
+      )
+      if (result instanceof Response) return result
+      if (result instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, result)
+      return c.json({ status: 'denied' as const }, 200)
+    },
+  )

package/src/api/health.ts

@@ -0,0 +1,72 @@
+/** The health probe, which reports the Worker version that responded. @module */
+import { Hono } from 'hono'
+import * as z from 'zod'
+import type { Env } from '../internal/Env.js'
+import * as OpenApi from '../internal/OpenApi.js'
+
+/** The Worker version that Cloudflare's version metadata binding reports. */
+type Version = {
+  /** The version's ID, as `wrangler deploy` prints it. */
+  id: string
+  /** The version's tag, or empty when it has none. */
+  tag: string
+}
+
+// Void types `c.env` from this global interface. `void.config.ts` declares the binding.
+declare global {
+  interface VoidGeneratedEnvBindings {
+    /** The Worker version that serves the request. */
+    readonly CF_VERSION_METADATA: Version
+  }
+}
+
+namespace schema {
+  export namespace health {
+    export const response = z.object({
+      ok: z.literal(true).meta({ description: 'Always `true`.' }),
+      version: z
+        .object({
+          id: z.string().meta({
+            description: "The version's ID, as `wrangler deploy` prints it.",
+            examples: ['a5f3c2e1-7b4d-4e8a-9c6f-2d1b0e3a4c5f'],
+          }),
+          tag: z.string().meta({
+            description: "The version's tag, or empty when it has none.",
+            examples: ['v1.4.0'],
+          }),
+        })
+        .meta({
+          description: 'The deployed Worker version that served the request.',
+        }),
+    })
+  }
+}
+
+/** The health probe. */
+export const health = new Hono<
+  Env & {
+    /** The bindings the probe reads. */
+    Bindings: Pick<VoidGeneratedEnvBindings, 'CF_VERSION_METADATA'>
+  }
+>()
+  // Infrastructure probes call an unversioned path, which no app calls. It returns the version that
+  // served the request, so a deploy can be verified by its ID or tag.
+  .get(
+    '/health',
+    OpenApi.describeRoute({
+      description:
+        'Responds while the Worker is up, with the version that served the request.',
+      responses: OpenApi.responses({
+        success: {
+          description: 'The Worker is up.',
+          schema: schema.health.response,
+        },
+      }),
+      tags: ['Health'],
+    }),
+    (c) => {
+      const { id, tag } = c.env.CF_VERSION_METADATA
+      c.header('cache-control', 'no-store')
+      return c.json({ ok: true as const, version: { id, tag } }, 200)
+    },
+  )