@atproto/jwk 0.7.2 → 0.7.3

package/src/jwt.ts

@@ -1,220 +0,0 @@
-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(),
-  })
-  .passthrough()
-
-export type JwtHeader = z.infer<typeof jwtHeaderSchema>
-
-/**
- * @see {@link https://www.rfc-editor.org/rfc/rfc9449.html#section-4.2-4.6}
- * @see {@link https://www.rfc-editor.org/rfc/rfc9110#section-7.1}
- */
-export const htuSchema = z.string().superRefine((value, ctx) => {
-  try {
-    const url = new URL(value)
-    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: 'Only http: and https: protocols are allowed',
-      })
-    }
-
-    if (url.username || url.password) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: 'Credentials not allowed',
-      })
-    }
-
-    if (url.search) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: 'Query string not allowed',
-      })
-    }
-
-    if (url.hash) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: 'Fragment not allowed',
-      })
-    }
-  } catch (err) {
-    ctx.addIssue({
-      code: z.ZodIssueCode.invalid_string,
-      validation: 'url',
-    })
-  }
-
-  return value
-})
-
-// 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: htuSchema.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,3}(-[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(),
-  })
-  .passthrough()
-
-export type JwtPayload = z.infer<typeof jwtPayloadSchema>

package/src/key.ts

@@ -1,211 +0,0 @@
-import { jwkAlgorithms } from './alg.js'
-import {
-  Jwk,
-  KeyUsage,
-  PUBLIC_KEY_USAGE,
-  PrivateJwk,
-  PublicJwk,
-  PublicKeyUsage,
-  hasSharedSecretJwk,
-  isEncKeyUsage,
-  isPrivateJwk,
-  isPublicKeyUsage,
-  isSigKeyUsage,
-  jwkPubSchema,
-  jwkSchema,
-} from './jwk.js'
-import { VerifyOptions, VerifyResult } from './jwt-verify.js'
-import { JwtHeader, JwtPayload, SignedJwt } from './jwt.js'
-import { cachedGetter } from './util.js'
-
-export type KeyMatchOptions = {
-  usage?: KeyUsage
-  kid?: string | string[]
-  alg?: string | string[]
-}
-
-export type ActivityCheckOptions = {
-  allowRevoked?: boolean
-  clockTolerance?: number
-  currentDate?: Date
-}
-
-export abstract class Key<J extends Jwk = Jwk> {
-  constructor(readonly jwk: Readonly<J>) {}
-
-  @cachedGetter
-  get isPrivate(): boolean {
-    return isPrivateJwk(this.jwk)
-  }
-
-  @cachedGetter
-  get isSymetric(): boolean {
-    return hasSharedSecretJwk(this.jwk)
-  }
-
-  get privateJwk(): Readonly<PrivateJwk> | undefined {
-    if (!this.isPrivate) return undefined
-
-    return this.jwk as Readonly<PrivateJwk>
-  }
-
-  @cachedGetter
-  get publicJwk(): Readonly<PublicJwk> | undefined {
-    if (this.isSymetric) return undefined
-    if (!this.isPrivate) return this.jwk as Readonly<PublicJwk>
-
-    const validated = jwkPubSchema.safeParse({
-      ...this.jwk,
-      d: undefined,
-      k: undefined,
-      use: undefined,
-      key_ops: buildPublicKeyOps(this.keyOps) ?? PUBLIC_KEY_USAGE,
-    })
-
-    // One reason why the parsing might fail is if key_ops is empty. This check
-    // also allows to future proof the code (e.g if another type of private key
-    // is added that uses a different property than "d" or "k" to store its
-    // private value).
-    if (!validated.success) return undefined
-
-    return Object.freeze(validated.data)
-  }
-
-  @cachedGetter
-  get bareJwk(): Readonly<Jwk> | undefined {
-    if (this.isSymetric) return undefined
-    const { kty, crv, e, n, x, y } = this.jwk as any
-    return Object.freeze(jwkSchema.parse({ crv, e, kty, n, x, y }))
-  }
-
-  /**
-   * @note Only defined on public keys
-   */
-  get use(): 'sig' | 'enc' | undefined {
-    return this.jwk.use
-  }
-
-  get keyOps(): readonly KeyUsage[] | undefined {
-    return this.jwk.key_ops
-  }
-
-  /**
-   * 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<J, { 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 Object.freeze(Array.from(jwkAlgorithms(this.jwk)))
-  }
-
-  get isRevoked() {
-    return this.jwk.revoked != null
-  }
-
-  isActive(options?: ActivityCheckOptions) {
-    if (!options?.allowRevoked && this.isRevoked) return false
-
-    const tolerance = options?.clockTolerance ?? 0
-    if (tolerance !== Infinity) {
-      const now = options?.currentDate?.getTime() ?? Date.now()
-      const { exp, nbf } = this.jwk
-
-      if (nbf != null && !(now >= nbf * 1e3 - tolerance)) return false
-      if (exp != null && !(now < exp * 1e3 + tolerance)) return false
-    }
-
-    return true
-  }
-
-  matches(opts: KeyMatchOptions): boolean {
-    if (opts.kid != null) {
-      const matchesKid = Array.isArray(opts.kid)
-        ? this.kid != null && opts.kid.includes(this.kid)
-        : this.kid === opts.kid
-      if (!matchesKid) return false
-    }
-
-    if (opts.alg != null) {
-      const matchesAlg = Array.isArray(opts.alg)
-        ? opts.alg.some((a) => this.algorithms.includes(a))
-        : this.algorithms.includes(opts.alg)
-      if (!matchesAlg) return false
-    }
-
-    if (opts.usage != null) {
-      const matchesOps =
-        this.keyOps == null ||
-        this.keyOps.includes(opts.usage) ||
-        // @NOTE Because this.jwk represents the private key (typically used for
-        // private operations), the public counterpart operations are allowed.
-        (opts.usage === 'verify' && this.keyOps.includes('sign')) ||
-        (opts.usage === 'encrypt' && this.keyOps.includes('decrypt')) ||
-        (opts.usage === 'wrapKey' && this.keyOps.includes('unwrapKey'))
-      if (!matchesOps) return false
-
-      const matchesUse =
-        this.use == null ||
-        (this.use === 'sig' && isSigKeyUsage(opts.usage)) ||
-        (this.use === 'enc' && isEncKeyUsage(opts.usage))
-      if (!matchesUse) return false
-
-      // @NOTE This is only relevant when "key_ops" and "use" are undefined.
-      // This line also ensures that when "opts.usage" is a private key usage
-      // (e.g. "sign"), the key is indeed a private key.
-      const matchesKeyType = this.isPrivate || isPublicKeyUsage(opts.usage)
-      if (!matchesKeyType) return false
-    }
-
-    return true
-  }
-
-  /**
-   * 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<C extends string = never>(
-    token: SignedJwt,
-    options?: VerifyOptions<C>,
-  ): Promise<VerifyResult<C>>
-}
-
-function buildPublicKeyOps(
-  keyUsages?: readonly KeyUsage[],
-): PublicKeyUsage[] | undefined {
-  if (keyUsages == null) return undefined
-
-  // https://datatracker.ietf.org/doc/html/rfc7517#section-4.3
-  // > Duplicate key operation values MUST NOT be present in the array.
-  const publicOps = new Set(keyUsages.filter(isPublicKeyUsage))
-
-  // @NOTE Translating private key usage into public key usage
-  if (keyUsages.includes('sign')) publicOps.add('verify')
-  if (keyUsages.includes('decrypt')) publicOps.add('encrypt')
-  if (keyUsages.includes('unwrapKey')) publicOps.add('wrapKey')
-
-  return Array.from(publicOps)
-}

package/src/keyset.ts

@@ -1,254 +0,0 @@
-import {
-  ERR_JWKS_NO_MATCHING_KEY,
-  ERR_JWK_NOT_FOUND,
-  ERR_JWT_INVALID,
-  JwkError,
-  JwtCreateError,
-  JwtVerifyError,
-} from './errors.js'
-import { PrivateKeyUsage } from './jwk.js'
-import { JwksPub } from './jwks.js'
-import { unsafeDecodeJwt } from './jwt-decode.js'
-import { VerifyOptions, VerifyResult } from './jwt-verify.js'
-import { JwtHeader, JwtPayload, SignedJwt } from './jwt.js'
-import { ActivityCheckOptions, Key, KeyMatchOptions } from './key.js'
-import {
-  Override,
-  cachedGetter,
-  isDefined,
-  matchesAny,
-  preferredOrderCmp,
-} from './util.js'
-
-export type { ActivityCheckOptions, KeyMatchOptions }
-export type FindKeyOptions = KeyMatchOptions & ActivityCheckOptions
-
-export type JwtSignHeader = Override<
-  JwtHeader,
-  Pick<FindKeyOptions, 'alg' | 'kid'>
->
-
-export type JwtPayloadGetter<P = JwtPayload> = (
-  header: JwtHeader,
-  key: Key,
-) => P | PromiseLike<P>
-
-const extractPrivateJwk = (key: Key) => key.privateJwk
-const extractPublicJwk = (key: Key) => 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 keyIds = new Set<string>()
-    for (const key of iterable) {
-      if (!key) continue
-
-      keys.push(key)
-
-      if (key.kid) {
-        if (keyIds.has(key.kid)) throw new JwkError(`Duplicate key: ${key.kid}`)
-        else keyIds.add(key.kid)
-      }
-    }
-
-    this.keys = Object.freeze(keys)
-  }
-
-  get size(): number {
-    return this.keys.length
-  }
-
-  @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() {
-    return Object.freeze({
-      keys: Object.freeze(Array.from(this, extractPublicJwk).filter(isDefined)),
-    })
-  }
-
-  @cachedGetter
-  get privateJwks() {
-    return Object.freeze({
-      keys: Object.freeze(
-        Array.from(this, extractPrivateJwk).filter(isDefined),
-      ),
-    })
-  }
-
-  has(kid: string): boolean {
-    return this.keys.some((key) => key.kid === kid)
-  }
-
-  get(options: FindKeyOptions): K {
-    const key = this.find(options)
-    if (key) return key
-
-    throw new JwkError(
-      `Key not found ${options.kid ?? options.alg ?? options.usage ?? '<unknown>'}`,
-      ERR_JWK_NOT_FOUND,
-    )
-  }
-
-  find(options: FindKeyOptions): K | undefined {
-    for (const key of this.list(options)) {
-      return key
-    }
-
-    return undefined
-  }
-
-  *list<O extends FindKeyOptions>(options: O) {
-    for (const key of this) {
-      if (key.isActive(options) && key.matches(options)) {
-        yield key
-      }
-    }
-  }
-
-  findPrivateKey({
-    kid,
-    alg,
-    usage,
-    ...options
-  }: FindKeyOptions & { usage: PrivateKeyUsage }): {
-    key: Key
-    alg: string
-  } {
-    const matchingKeys: Key[] = []
-
-    // Allow the loop bellow to return early when a single "alg" is provided
-    if (Array.isArray(alg) && alg.length === 1) alg = alg[0]
-
-    for (const key of this.list({ ...options, kid, alg, usage })) {
-      // Skip negotiation if a single "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 { key: matchingKey, alg: prefAlg }
-        }
-      }
-    }
-
-    // Return any candidate
-    for (const [matchingKey, matchingAlgs] of candidates) {
-      for (const alg of matchingAlgs) {
-        return { key: matchingKey, alg }
-      }
-    }
-
-    throw new JwkError(
-      `No private key found for ${kid || alg || usage}`,
-      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.findPrivateKey({
-        alg: sAlg,
-        kid: sKid,
-        usage: 'sign',
-        allowRevoked: false, // For explicitness (default value is false)
-      })
-      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<C extends string = never>(
-    token: SignedJwt,
-    options?: ActivityCheckOptions & VerifyOptions<C>,
-  ): Promise<VerifyResult<C> & { key: K }> {
-    const { header } = unsafeDecodeJwt(token)
-    const { kid, alg } = header
-
-    const errors: unknown[] = []
-
-    for (const key of this.list({ ...options, kid, alg, usage: 'verify' })) {
-      try {
-        const result = await key.verifyJwt<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)
-    }
-  }
-
-  toJSON() {
-    // Make a copy to allow mutation of the result
-    return structuredClone(this.publicJwks) as JwksPub
-  }
-}