@atproto/jwk 0.1.0

package/src/jwt.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod'
+
+import { jwkPubSchema } from './jwk.js'
+import { jwtCharsRefinement, segmentedStringRefinementFactory } from './util.js'
+
+export const signedJwtSchema = z
+  .string()
+  .superRefine(jwtCharsRefinement)
+  .superRefine(segmentedStringRefinementFactory(3))
+
+export type SignedJwt = z.infer<typeof signedJwtSchema>
+export const isSignedJwt = (data: unknown): data is SignedJwt =>
+  signedJwtSchema.safeParse(data).success
+
+export const unsignedJwtSchema = z
+  .string()
+  .superRefine(jwtCharsRefinement)
+  .superRefine(segmentedStringRefinementFactory(2))
+
+export type UnsignedJwt = z.infer<typeof unsignedJwtSchema>
+export const isUnsignedJwt = (data: unknown): data is UnsignedJwt =>
+  unsignedJwtSchema.safeParse(data).success
+
+/**
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7515.html#section-4}
+ */
+export const jwtHeaderSchema = z.object({
+  /** "alg" (Algorithm) Header Parameter */
+  alg: z.string(),
+  /** "jku" (JWK Set URL) Header Parameter */
+  jku: z.string().url().optional(),
+  /** "jwk" (JSON Web Key) Header Parameter */
+  jwk: z
+    .object({
+      kty: z.string(),
+      crv: z.string().optional(),
+      x: z.string().optional(),
+      y: z.string().optional(),
+      e: z.string().optional(),
+      n: z.string().optional(),
+    })
+    .optional(),
+  /** "kid" (Key ID) Header Parameter */
+  kid: z.string().optional(),
+  /** "x5u" (X.509 URL) Header Parameter */
+  x5u: z.string().optional(),
+  /** "x5c" (X.509 Certificate Chain) Header Parameter */
+  x5c: z.array(z.string()).optional(),
+  /** "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter */
+  x5t: z.string().optional(),
+  /** "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header Parameter */
+  'x5t#S256': z.string().optional(),
+  /** "typ" (Type) Header Parameter */
+  typ: z.string().optional(),
+  /** "cty" (Content Type) Header Parameter */
+  cty: z.string().optional(),
+  /** "crit" (Critical) Header Parameter */
+  crit: z.array(z.string()).optional(),
+})
+
+export type JwtHeader = z.infer<typeof jwtHeaderSchema>
+
+// https://www.iana.org/assignments/jwt/jwt.xhtml
+export const jwtPayloadSchema = z.object({
+  iss: z.string().optional(),
+  aud: z.union([z.string(), z.array(z.string()).nonempty()]).optional(),
+  sub: z.string().optional(),
+  exp: z.number().int().optional(),
+  nbf: z.number().int().optional(),
+  iat: z.number().int().optional(),
+  jti: z.string().optional(),
+  htm: z.string().optional(),
+  htu: z.string().optional(),
+  ath: z.string().optional(),
+  acr: z.string().optional(),
+  azp: z.string().optional(),
+  amr: z.array(z.string()).optional(),
+  // https://datatracker.ietf.org/doc/html/rfc7800
+  cnf: z
+    .object({
+      kid: z.string().optional(), // Key ID
+      jwk: jwkPubSchema.optional(), // JWK
+      jwe: z.string().optional(), // Encrypted key
+      jku: z.string().url().optional(), // JWK Set URI ("kid" should also be provided)
+
+      // https://datatracker.ietf.org/doc/html/rfc9449#section-6.1
+      jkt: z.string().optional(),
+
+      // https://datatracker.ietf.org/doc/html/rfc8705
+      'x5t#S256': z.string().optional(), // X.509 Certificate SHA-256 Thumbprint
+
+      // https://datatracker.ietf.org/doc/html/rfc9203
+      osc: z.string().optional(), // OSCORE_Input_Material carrying the parameters for using OSCORE per-message security with implicit key confirmation
+    })
+    .optional(),
+
+  client_id: z.string().optional(),
+
+  scope: z.string().optional(),
+  nonce: z.string().optional(),
+
+  at_hash: z.string().optional(),
+  c_hash: z.string().optional(),
+  s_hash: z.string().optional(),
+  auth_time: z.number().int().optional(),
+
+  // https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
+
+  // OpenID: "profile" scope
+  name: z.string().optional(),
+  family_name: z.string().optional(),
+  given_name: z.string().optional(),
+  middle_name: z.string().optional(),
+  nickname: z.string().optional(),
+  preferred_username: z.string().optional(),
+  gender: z.string().optional(), // OpenID only defines "male" and "female" without forbidding other values
+  picture: z.string().url().optional(),
+  profile: z.string().url().optional(),
+  website: z.string().url().optional(),
+  birthdate: z
+    .string()
+    .regex(/\d{4}-\d{2}-\d{2}/) // YYYY-MM-DD
+    .optional(),
+  zoneinfo: z
+    .string()
+    .regex(/^[A-Za-z0-9_/]+$/)
+    .optional(),
+  locale: z
+    .string()
+    .regex(/^[a-z]{2}(-[A-Z]{2})?$/)
+    .optional(),
+  updated_at: z.number().int().optional(),
+
+  // OpenID: "email" scope
+  email: z.string().optional(),
+  email_verified: z.boolean().optional(),
+
+  // OpenID: "phone" scope
+  phone_number: z.string().optional(),
+  phone_number_verified: z.boolean().optional(),
+
+  // OpenID: "address" scope
+  // https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim
+  address: z
+    .object({
+      formatted: z.string().optional(),
+      street_address: z.string().optional(),
+      locality: z.string().optional(),
+      region: z.string().optional(),
+      postal_code: z.string().optional(),
+      country: z.string().optional(),
+    })
+    .optional(),
+
+  // https://datatracker.ietf.org/doc/html/rfc9396#section-14.2
+  authorization_details: z
+    .array(
+      z
+        .object({
+          type: z.string(),
+          // https://datatracker.ietf.org/doc/html/rfc9396#section-2.2
+          locations: z.array(z.string()).optional(),
+          actions: z.array(z.string()).optional(),
+          datatypes: z.array(z.string()).optional(),
+          identifier: z.string().optional(),
+          privileges: z.array(z.string()).optional(),
+        })
+        .passthrough(),
+    )
+    .optional(),
+})
+
+export type JwtPayload = z.infer<typeof jwtPayloadSchema>

package/src/key.ts

@@ -0,0 +1,93 @@
+import { jwkAlgorithms } from './alg.js'
+import { JwkError } from './errors.js'
+import { Jwk, jwkSchema } from './jwk.js'
+import { VerifyOptions, VerifyPayload, VerifyResult } from './jwt-verify.js'
+import { JwtHeader, JwtPayload, SignedJwt } from './jwt.js'
+import { cachedGetter } from './util.js'
+
+export abstract class Key {
+  constructor(protected readonly jwk: Readonly<Jwk>) {
+    // A key should always be used either for signing or encryption.
+    if (!jwk.use) throw new JwkError('Missing "use" Parameter value')
+  }
+
+  get isPrivate(): boolean {
+    const { jwk } = this
+    if ('d' in jwk && jwk.d !== undefined) return true
+    if ('k' in jwk && jwk.k !== undefined) return true
+    return false
+  }
+
+  get isSymetric(): boolean {
+    const { jwk } = this
+    if ('k' in jwk && jwk.k !== undefined) return true
+    return false
+  }
+
+  get privateJwk(): Jwk | undefined {
+    return this.isPrivate ? this.jwk : undefined
+  }
+
+  @cachedGetter
+  get publicJwk(): Jwk | undefined {
+    if (this.isSymetric) return undefined
+    if (this.isPrivate) {
+      const { d: _, ...jwk } = this.jwk as any
+      return jwk
+    }
+    return this.jwk
+  }
+
+  @cachedGetter
+  get bareJwk(): Jwk | undefined {
+    if (this.isSymetric) return undefined
+    const { kty, crv, e, n, x, y } = this.jwk as any
+    return jwkSchema.parse({ crv, e, kty, n, x, y })
+  }
+
+  get use() {
+    return this.jwk.use!
+  }
+
+  /**
+   * The (forced) algorithm to use. If not provided, the key will be usable with
+   * any of the algorithms in {@link algorithms}.
+   *
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc7518#section-3.1 | "alg" (Algorithm) Header Parameter Values for JWS}
+   */
+  get alg() {
+    return this.jwk.alg
+  }
+
+  get kid() {
+    return this.jwk.kid
+  }
+
+  get crv() {
+    return (this.jwk as { crv: undefined } | Extract<Jwk, { crv: unknown }>).crv
+  }
+
+  /**
+   * All the algorithms that this key can be used with. If `alg` is provided,
+   * this set will only contain that algorithm.
+   */
+  @cachedGetter
+  get algorithms(): readonly string[] {
+    return Array.from(jwkAlgorithms(this.jwk))
+  }
+
+  /**
+   * Create a signed JWT
+   */
+  abstract createJwt(header: JwtHeader, payload: JwtPayload): Promise<SignedJwt>
+
+  /**
+   * Verify the signature, headers and payload of a JWT
+   *
+   * @throws {JwtVerifyError} if the JWT is invalid
+   */
+  abstract verifyJwt<
+    P extends VerifyPayload = JwtPayload,
+    C extends string = string,
+  >(token: SignedJwt, options?: VerifyOptions<C>): Promise<VerifyResult<P, C>>
+}

package/src/keyset.ts

@@ -0,0 +1,240 @@
+import {
+  ERR_JWKS_NO_MATCHING_KEY,
+  ERR_JWK_NOT_FOUND,
+  ERR_JWT_INVALID,
+  JwkError,
+  JwtCreateError,
+  JwtVerifyError,
+} from './errors.js'
+import { Jwk } from './jwk.js'
+import { Jwks } from './jwks.js'
+import { unsafeDecodeJwt } from './jwt-decode.js'
+import { VerifyOptions, VerifyResult } from './jwt-verify.js'
+import { JwtHeader, JwtPayload, SignedJwt } from './jwt.js'
+import { Key } from './key.js'
+import {
+  Override,
+  cachedGetter,
+  isDefined,
+  matchesAny,
+  preferredOrderCmp,
+} from './util.js'
+
+export type JwtSignHeader = Override<JwtHeader, Pick<KeySearch, 'alg' | 'kid'>>
+
+export type JwtPayloadGetter<P = JwtPayload> = (
+  header: JwtHeader,
+  key: Key,
+) => P | PromiseLike<P>
+
+export type KeySearch = {
+  use?: 'sig' | 'enc'
+  kid?: string | string[]
+  alg?: string | string[]
+}
+
+const extractPrivateJwk = (key: Key): Jwk | undefined => key.privateJwk
+const extractPublicJwk = (key: Key): Jwk | undefined => key.publicJwk
+
+export class Keyset<K extends Key = Key> implements Iterable<K> {
+  private readonly keys: readonly K[]
+
+  constructor(
+    iterable: Iterable<K | null | undefined | false>,
+    /**
+     * The preferred algorithms to use when signing a JWT using this keyset.
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7518#section-3.1}
+     */
+    public readonly preferredSigningAlgorithms: readonly string[] = iterable instanceof
+    Keyset
+      ? [...iterable.preferredSigningAlgorithms]
+      : [
+          // Prefer elliptic curve algorithms
+          'EdDSA',
+          'ES256K',
+          'ES256',
+          // https://datatracker.ietf.org/doc/html/rfc7518#section-3.5
+          'PS256',
+          'PS384',
+          'PS512',
+          'HS256',
+          'HS384',
+          'HS512',
+        ],
+  ) {
+    const keys: K[] = []
+
+    const kids = new Set<string>()
+    for (const key of iterable) {
+      if (!key) continue
+
+      keys.push(key)
+
+      if (key.kid) {
+        if (kids.has(key.kid)) throw new JwkError(`Duplicate key: ${key.kid}`)
+        else kids.add(key.kid)
+      }
+    }
+
+    this.keys = Object.freeze(keys)
+  }
+
+  @cachedGetter
+  get signAlgorithms(): readonly string[] {
+    const algorithms = new Set<string>()
+    for (const key of this) {
+      if (key.use !== 'sig') continue
+      for (const alg of key.algorithms) {
+        algorithms.add(alg)
+      }
+    }
+    return Object.freeze(
+      [...algorithms].sort(preferredOrderCmp(this.preferredSigningAlgorithms)),
+    )
+  }
+
+  @cachedGetter
+  get publicJwks(): Jwks {
+    return {
+      keys: Array.from(this, extractPublicJwk).filter(isDefined),
+    }
+  }
+
+  @cachedGetter
+  get privateJwks(): Jwks {
+    return {
+      keys: Array.from(this, extractPrivateJwk).filter(isDefined),
+    }
+  }
+
+  has(kid: string): boolean {
+    return this.keys.some((key) => key.kid === kid)
+  }
+
+  get(search: KeySearch): K {
+    for (const key of this.list(search)) {
+      return key
+    }
+
+    throw new JwkError(
+      `Key not found ${search.kid || search.alg || '<unknown>'}`,
+      ERR_JWK_NOT_FOUND,
+    )
+  }
+
+  *list(search: KeySearch): Generator<K> {
+    // Optimization: Empty string or empty array will not match any key
+    if (search.kid?.length === 0) return
+    if (search.alg?.length === 0) return
+
+    for (const key of this) {
+      if (search.use && key.use !== search.use) continue
+
+      if (Array.isArray(search.kid)) {
+        if (!key.kid || !search.kid.includes(key.kid)) continue
+      } else if (search.kid) {
+        if (key.kid !== search.kid) continue
+      }
+
+      if (Array.isArray(search.alg)) {
+        if (!search.alg.some((a) => key.algorithms.includes(a))) continue
+      } else if (typeof search.alg === 'string') {
+        if (!key.algorithms.includes(search.alg)) continue
+      }
+
+      yield key
+    }
+  }
+
+  findKey({ kid, alg, use }: KeySearch): [key: Key, alg: string] {
+    const matchingKeys: Key[] = []
+
+    for (const key of this.list({ kid, alg, use })) {
+      // Not a signing key
+      if (!key.isPrivate) continue
+
+      // Skip negotiation if a specific "alg" was provided
+      if (typeof alg === 'string') return [key, alg]
+
+      matchingKeys.push(key)
+    }
+
+    const isAllowedAlg = matchesAny(alg)
+    const candidates = matchingKeys.map(
+      (key) => [key, key.algorithms.filter(isAllowedAlg)] as const,
+    )
+
+    // Return the first candidates that matches the preferred algorithms
+    for (const prefAlg of this.preferredSigningAlgorithms) {
+      for (const [matchingKey, matchingAlgs] of candidates) {
+        if (matchingAlgs.includes(prefAlg)) return [matchingKey, prefAlg]
+      }
+    }
+
+    // Return any candidate
+    for (const [matchingKey, matchingAlgs] of candidates) {
+      for (const alg of matchingAlgs) {
+        return [matchingKey, alg]
+      }
+    }
+
+    throw new JwkError(
+      `No singing key found for ${kid || alg || use || '<unknown>'}`,
+      ERR_JWK_NOT_FOUND,
+    )
+  }
+
+  [Symbol.iterator](): IterableIterator<K> {
+    return this.keys.values()
+  }
+
+  async createJwt(
+    { alg: sAlg, kid: sKid, ...header }: JwtSignHeader,
+    payload: JwtPayload | JwtPayloadGetter,
+  ): Promise<SignedJwt> {
+    try {
+      const [key, alg] = this.findKey({ alg: sAlg, kid: sKid, use: 'sig' })
+      const protectedHeader = { ...header, alg, kid: key.kid }
+
+      if (typeof payload === 'function') {
+        payload = await payload(protectedHeader, key)
+      }
+
+      return await key.createJwt(protectedHeader, payload)
+    } catch (err) {
+      throw JwtCreateError.from(err)
+    }
+  }
+
+  async verifyJwt<
+    P extends Record<string, unknown> = JwtPayload,
+    C extends string = string,
+  >(
+    token: SignedJwt,
+    options?: VerifyOptions<C>,
+  ): Promise<VerifyResult<P, C> & { key: K }> {
+    const { header } = unsafeDecodeJwt(token)
+    const { kid, alg } = header
+
+    const errors: unknown[] = []
+
+    for (const key of this.list({ kid, alg })) {
+      try {
+        const result = await key.verifyJwt<P, C>(token, options)
+        return { ...result, key }
+      } catch (err) {
+        errors.push(err)
+      }
+    }
+
+    switch (errors.length) {
+      case 0:
+        throw new JwtVerifyError('No key matched', ERR_JWKS_NO_MATCHING_KEY)
+      case 1:
+        throw JwtVerifyError.from(errors[0], ERR_JWT_INVALID)
+      default:
+        throw JwtVerifyError.from(errors, ERR_JWT_INVALID)
+    }
+  }
+}

package/src/util.ts

@@ -0,0 +1,181 @@
+import { base64url } from 'multiformats/bases/base64'
+import { RefinementCtx, ZodIssueCode } from 'zod'
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type Simplify<T> = { [K in keyof T]: T[K] } & {}
+export type Override<T, V> = Simplify<V & Omit<T, keyof V>>
+
+export type RequiredKey<T, K extends string> = Simplify<
+  string extends K
+    ? T
+    : {
+        [L in K]: Exclude<L extends keyof T ? T[L] : unknown, undefined>
+      } & Omit<T, K>
+>
+
+export const isDefined = <T>(i: T | undefined): i is T => i !== undefined
+
+export const preferredOrderCmp =
+  <T>(order: readonly T[]) =>
+  (a: T, b: T) => {
+    const aIdx = order.indexOf(a)
+    const bIdx = order.indexOf(b)
+    if (aIdx === bIdx) return 0
+    if (aIdx === -1) return 1
+    if (bIdx === -1) return -1
+    return aIdx - bIdx
+  }
+
+export function matchesAny<T extends string | number | symbol | boolean>(
+  value: null | undefined | T | readonly T[],
+): (v: unknown) => v is T {
+  return value == null
+    ? (v): v is T => true
+    : Array.isArray(value)
+      ? (v): v is T => value.includes(v)
+      : (v): v is T => v === value
+}
+
+/**
+ * Decorator to cache the result of a getter on a class instance.
+ */
+export const cachedGetter = <T extends object, V>(
+  target: (this: T) => V,
+  _context: ClassGetterDecoratorContext<T, V>,
+) => {
+  return function (this: T) {
+    const value = target.call(this)
+    Object.defineProperty(this, target.name, {
+      get: () => value,
+      enumerable: true,
+      configurable: true,
+    })
+    return value
+  }
+}
+
+const decoder = new TextDecoder()
+export function parseB64uJson(input: string): unknown {
+  const inputBytes = base64url.baseDecode(input)
+  const json = decoder.decode(inputBytes)
+  return JSON.parse(json)
+}
+
+/**
+ * @example
+ * ```ts
+ * // jwtSchema will only allow base64url chars & "." (dot)
+ * const jwtSchema = z.string().superRefine(jwtCharsRefinement)
+ * ```
+ */
+export const jwtCharsRefinement = (data: string, ctx: RefinementCtx): void => {
+  // Note: this is a hot path, let's avoid using a RegExp
+  let char
+
+  for (let i = 0; i < data.length; i++) {
+    char = data.charCodeAt(i)
+
+    if (
+      // Base64 URL encoding (most frequent)
+      (65 <= char && char <= 90) || // A-Z
+      (97 <= char && char <= 122) || // a-z
+      (48 <= char && char <= 57) || // 0-9
+      char === 45 || // -
+      char === 95 || // _
+      // Boundary (least frequent, check last)
+      char === 46 // .
+    ) {
+      // continue
+    } else {
+      // Invalid char might be a surrogate pair
+      const invalidChar = String.fromCodePoint(data.codePointAt(i)!)
+      return ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message: `Invalid character "${invalidChar}" in JWT at position ${i}`,
+      })
+    }
+  }
+}
+
+/**
+ * @example
+ * ```ts
+ * type SegmentedString3 = SegmentedString<3> // `${string}.${string}.${string}`
+ * type SegmentedString4 = SegmentedString<4> // `${string}.${string}.${string}.${string}`
+ * ```
+ *
+ * @note
+ * This utility only provides one way type safety (A SegmentedString<4> can be
+ * assigned to SegmentedString<3> but not vice versa). The purpose of this
+ * utility is to improve DX by avoiding as many potential errors as build time.
+ * DO NOT rely on this to enforce security or data integrity.
+ */
+type SegmentedString<
+  C extends number,
+  Acc extends string[] = [string],
+> = Acc['length'] extends C
+  ? `${Acc[0]}`
+  : `${Acc[0]}.${SegmentedString<C, [string, ...Acc]>}`
+
+/**
+ * @example
+ * ```ts
+ * const jwtSchema = z.string().superRefine(segmentedStringRefinementFactory(3))
+ * type Jwt = z.infer<typeof jwtSchema> // `${string}.${string}.${string}`
+ * ```
+ */
+export const segmentedStringRefinementFactory = <C extends number>(
+  count: C,
+  minPartLength = 2,
+) => {
+  if (!Number.isFinite(count) || count < 1 || (count | 0) !== count) {
+    throw new TypeError(`Count must be a natural number (got ${count})`)
+  }
+
+  const minTotalLength = count * minPartLength + (count - 1)
+  const errorPrefix = `Invalid JWT format`
+
+  return (data: string, ctx: RefinementCtx): data is SegmentedString<C> => {
+    if (data.length < minTotalLength) {
+      ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message: `${errorPrefix}: too short`,
+      })
+      return false
+    }
+    let currentStart = 0
+    for (let i = 0; i < count - 1; i++) {
+      const nextDot = data.indexOf('.', currentStart)
+      if (nextDot === -1) {
+        ctx.addIssue({
+          code: ZodIssueCode.custom,
+          message: `${errorPrefix}: expected ${count} segments, got ${i + 1}`,
+        })
+        return false
+      }
+      if (nextDot - currentStart < minPartLength) {
+        ctx.addIssue({
+          code: ZodIssueCode.custom,
+          message: `${errorPrefix}: segment ${i + 1} is too short`,
+        })
+        return false
+      }
+      currentStart = nextDot + 1
+    }
+    if (data.indexOf('.', currentStart) !== -1) {
+      ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message: `${errorPrefix}: too many segments`,
+      })
+      return false
+    }
+    if (data.length - currentStart < minPartLength) {
+      ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message: `${errorPrefix}: last segment is too short`,
+      })
+      return false
+    }
+    return true
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": ["../../../tsconfig/isomorphic.json"],
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "include": [],
+  "references": [{ "path": "./tsconfig.build.json" }]
+}