@atproto/jwk 0.4.0 → 0.6.0

package/src/key.ts

@@ -1,57 +1,92 @@
 import { jwkAlgorithms } from './alg.js'
-import { JwkError } from './errors.js'
-import { Jwk, jwkSchema } from './jwk.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'
 
-const jwkSchemaReadonly = jwkSchema.readonly()
+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(protected readonly jwk: Readonly<J>) {
-    // A key should always be used either for signing or encryption.
-    if (!jwk.use) throw new JwkError('Missing "use" Parameter value')
-  }
+  constructor(readonly jwk: Readonly<J>) {}
 
+  @cachedGetter
   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
+    return isPrivateJwk(this.jwk)
   }
 
+  @cachedGetter
   get isSymetric(): boolean {
-    const { jwk } = this
-    if ('k' in jwk && jwk.k !== undefined) return true
-    return false
+    return hasSharedSecretJwk(this.jwk)
   }
 
-  get privateJwk(): Readonly<J> | undefined {
-    return this.isPrivate ? this.jwk : undefined
+  get privateJwk(): Readonly<PrivateJwk> | undefined {
+    if (!this.isPrivate) return undefined
+
+    return this.jwk as Readonly<PrivateJwk>
   }
 
   @cachedGetter
-  get publicJwk():
-    | Readonly<Exclude<J, { kty: 'oct' }> & { d?: never }>
-    | undefined {
+  get publicJwk(): Readonly<PublicJwk> | undefined {
     if (this.isSymetric) return undefined
+    if (!this.isPrivate) return this.jwk as Readonly<PublicJwk>
 
-    return jwkSchemaReadonly.parse({
+    const validated = jwkPubSchema.safeParse({
       ...this.jwk,
       d: undefined,
       k: undefined,
-    }) as Exclude<J, { kty: 'oct' }> & { d?: never }
+      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 jwkSchemaReadonly.parse({ crv, e, kty, n, x, y })
+    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 use() {
-    return this.jwk.use!
+  get keyOps(): readonly KeyUsage[] | undefined {
+    return this.jwk.key_ops
   }
 
   /**
@@ -81,6 +116,67 @@ export abstract class Key<J extends Jwk = Jwk> {
     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
    */
@@ -96,3 +192,20 @@ export abstract class Key<J extends Jwk = Jwk> {
     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

@@ -6,37 +6,35 @@ import {
   JwtCreateError,
   JwtVerifyError,
 } from './errors.js'
-import { Jwk } from './jwk.js'
-import { Jwks, JwksPub } from './jwks.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 { Key } from './key.js'
+import { ActivityCheckOptions, Key, KeyMatchOptions } from './key.js'
 import {
-  DeepReadonly,
   Override,
-  UnReadonly,
   cachedGetter,
   isDefined,
   matchesAny,
   preferredOrderCmp,
 } from './util.js'
 
-export type JwtSignHeader = Override<JwtHeader, Pick<KeySearch, 'alg' | 'kid'>>
+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>
 
-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
+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[]
@@ -67,15 +65,15 @@ export class Keyset<K extends Key = Key> implements Iterable<K> {
   ) {
     const keys: K[] = []
 
-    const kids = new Set<string>()
+    const keyIds = 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)
+        if (keyIds.has(key.kid)) throw new JwkError(`Duplicate key: ${key.kid}`)
+        else keyIds.add(key.kid)
       }
     }
 
@@ -101,66 +99,67 @@ export class Keyset<K extends Key = Key> implements Iterable<K> {
   }
 
   @cachedGetter
-  get publicJwks(): DeepReadonly<JwksPub> {
-    return {
-      keys: Array.from(this, extractPublicJwk).filter(isDefined),
-    }
+  get publicJwks() {
+    return Object.freeze({
+      keys: Object.freeze(Array.from(this, extractPublicJwk).filter(isDefined)),
+    })
   }
 
   @cachedGetter
-  get privateJwks(): DeepReadonly<Jwks> {
-    return {
-      keys: Array.from(this, extractPrivateJwk).filter(isDefined),
-    }
+  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(search: KeySearch): K {
-    for (const key of this.list(search)) {
-      return key
-    }
+  get(options: FindKeyOptions): K {
+    const key = this.find(options)
+    if (key) return key
 
     throw new JwkError(
-      `Key not found ${search.kid || search.alg || '<unknown>'}`,
+      `Key not found ${options.kid ?? options.alg ?? options.usage ?? '<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
+  find(options: FindKeyOptions): K | undefined {
+    for (const key of this.list(options)) {
+      return key
+    }
 
-      if (Array.isArray(search.kid)) {
-        if (!key.kid || !search.kid.includes(key.kid)) continue
-      } else if (search.kid) {
-        if (key.kid !== search.kid) continue
-      }
+    return undefined
+  }
 
-      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
+  *list<O extends FindKeyOptions>(options: O) {
+    for (const key of this) {
+      if (key.isActive(options) && key.matches(options)) {
+        yield key
       }
-
-      yield key
     }
   }
 
-  findPrivateKey({ kid, alg, use }: KeySearch): { key: Key; alg: string } {
+  findPrivateKey({
+    kid,
+    alg,
+    usage,
+    ...options
+  }: FindKeyOptions & { usage: PrivateKeyUsage }): {
+    key: Key
+    alg: string
+  } {
     const matchingKeys: Key[] = []
 
-    for (const key of this.list({ kid, alg, use })) {
-      // Not a private key
-      if (!key.isPrivate) continue
+    // Allow the loop bellow to return early when a single "alg" is provided
+    if (Array.isArray(alg) && alg.length === 1) alg = alg[0]
 
-      // Skip negotiation if a specific "alg" was provided
+    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)
@@ -188,7 +187,7 @@ export class Keyset<K extends Key = Key> implements Iterable<K> {
     }
 
     throw new JwkError(
-      `No private key found for ${kid || alg || use || '<unknown>'}`,
+      `No private key found for ${kid || alg || usage}`,
       ERR_JWK_NOT_FOUND,
     )
   }
@@ -205,7 +204,8 @@ export class Keyset<K extends Key = Key> implements Iterable<K> {
       const { key, alg } = this.findPrivateKey({
         alg: sAlg,
         kid: sKid,
-        use: 'sig',
+        usage: 'sign',
+        allowRevoked: false, // For explicitness (default value is false)
       })
       const protectedHeader = { ...header, alg, kid: key.kid }
 
@@ -221,14 +221,14 @@ export class Keyset<K extends Key = Key> implements Iterable<K> {
 
   async verifyJwt<C extends string = never>(
     token: SignedJwt,
-    options?: VerifyOptions<C>,
+    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({ kid, alg })) {
+    for (const key of this.list({ ...options, kid, alg, usage: 'verify' })) {
       try {
         const result = await key.verifyJwt<C>(token, options)
         return { ...result, key }
@@ -247,8 +247,8 @@ export class Keyset<K extends Key = Key> implements Iterable<K> {
     }
   }
 
-  toJSON(): JwksPub {
-    // Make a copy to prevent mutation of the original keyset
-    return structuredClone(this.publicJwks) as UnReadonly<JwksPub>
+  toJSON() {
+    // Make a copy to allow mutation of the result
+    return structuredClone(this.publicJwks) as JwksPub
   }
 }

package/src/util.ts

@@ -13,24 +13,6 @@ export type RequiredKey<T, K extends keyof T = never> = Simplify<
   }
 >
 
-// eslint-disable-next-line @typescript-eslint/ban-types
-export type DeepReadonly<T> = T extends Function
-  ? T
-  : T extends object
-    ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
-    : T extends readonly (infer U)[]
-      ? readonly DeepReadonly<U>[]
-      : T
-
-// eslint-disable-next-line @typescript-eslint/ban-types
-export type UnReadonly<T> = T extends Function
-  ? T
-  : T extends object
-    ? { -readonly [K in keyof T]: UnReadonly<T[K]> }
-    : T extends readonly (infer U)[]
-      ? UnReadonly<U>[]
-      : T
-
 export const isDefined = <T>(i: T | undefined): i is T => i !== undefined
 
 export const preferredOrderCmp =
@@ -197,3 +179,9 @@ export const segmentedStringRefinementFactory = <C extends number>(
     return true
   }
 }
+
+export function isLastOccurrence<
+  T extends number | boolean | string | null | undefined | symbol | bigint,
+>(v: T, i: number, arr: readonly T[]): boolean {
+  return arr.indexOf(v, i + 1) === -1
+}