@atproto/jwk 0.1.0 → 0.1.2

package/src/jwt.ts

@@ -24,150 +24,154 @@ export const isUnsignedJwt = (data: unknown): data is UnsignedJwt =>
 /**
  * @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 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>
 
 // 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 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(),
+  })
+  .passthrough()
 
 export type JwtPayload = z.infer<typeof jwtPayloadSchema>

package/src/key.ts

@@ -1,12 +1,14 @@
 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 { VerifyOptions, 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>) {
+const jwkSchemaReadonly = jwkSchema.readonly()
+
+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')
   }
@@ -24,25 +26,28 @@ export abstract class Key {
     return false
   }
 
-  get privateJwk(): Jwk | undefined {
+  get privateJwk(): Readonly<J> | undefined {
     return this.isPrivate ? this.jwk : undefined
   }
 
   @cachedGetter
-  get publicJwk(): Jwk | undefined {
+  get publicJwk():
+    | Readonly<Exclude<J, { kty: 'oct' }> & { d?: never }>
+    | undefined {
     if (this.isSymetric) return undefined
-    if (this.isPrivate) {
-      const { d: _, ...jwk } = this.jwk as any
-      return jwk
-    }
-    return this.jwk
+
+    return jwkSchemaReadonly.parse({
+      ...this.jwk,
+      d: undefined,
+      k: undefined,
+    }) as Exclude<J, { kty: 'oct' }> & { d?: never }
   }
 
   @cachedGetter
-  get bareJwk(): Jwk | undefined {
+  get bareJwk(): Readonly<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 })
+    return jwkSchemaReadonly.parse({ crv, e, kty, n, x, y })
   }
 
   get use() {
@@ -64,7 +69,7 @@ export abstract class Key {
   }
 
   get crv() {
-    return (this.jwk as { crv: undefined } | Extract<Jwk, { crv: unknown }>).crv
+    return (this.jwk as { crv: undefined } | Extract<J, { crv: unknown }>).crv
   }
 
   /**
@@ -73,7 +78,7 @@ export abstract class Key {
    */
   @cachedGetter
   get algorithms(): readonly string[] {
-    return Array.from(jwkAlgorithms(this.jwk))
+    return Object.freeze(Array.from(jwkAlgorithms(this.jwk)))
   }
 
   /**
@@ -86,8 +91,8 @@ export abstract class Key {
    *
    * @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>>
+  abstract verifyJwt<C extends string = never>(
+    token: SignedJwt,
+    options?: VerifyOptions<C>,
+  ): Promise<VerifyResult<C>>
 }

package/src/keyset.ts

@@ -7,13 +7,15 @@ import {
   JwtVerifyError,
 } from './errors.js'
 import { Jwk } from './jwk.js'
-import { Jwks } from './jwks.js'
+import { Jwks, 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 {
+  DeepReadonly,
   Override,
+  UnReadonly,
   cachedGetter,
   isDefined,
   matchesAny,
@@ -80,6 +82,10 @@ export class Keyset<K extends Key = Key> implements Iterable<K> {
     this.keys = Object.freeze(keys)
   }
 
+  get size(): number {
+    return this.keys.length
+  }
+
   @cachedGetter
   get signAlgorithms(): readonly string[] {
     const algorithms = new Set<string>()
@@ -95,14 +101,14 @@ export class Keyset<K extends Key = Key> implements Iterable<K> {
   }
 
   @cachedGetter
-  get publicJwks(): Jwks {
+  get publicJwks(): DeepReadonly<JwksPub> {
     return {
       keys: Array.from(this, extractPublicJwk).filter(isDefined),
     }
   }
 
   @cachedGetter
-  get privateJwks(): Jwks {
+  get privateJwks(): DeepReadonly<Jwks> {
     return {
       keys: Array.from(this, extractPrivateJwk).filter(isDefined),
     }
@@ -207,13 +213,10 @@ export class Keyset<K extends Key = Key> implements Iterable<K> {
     }
   }
 
-  async verifyJwt<
-    P extends Record<string, unknown> = JwtPayload,
-    C extends string = string,
-  >(
+  async verifyJwt<C extends string = never>(
     token: SignedJwt,
     options?: VerifyOptions<C>,
-  ): Promise<VerifyResult<P, C> & { key: K }> {
+  ): Promise<VerifyResult<C> & { key: K }> {
     const { header } = unsafeDecodeJwt(token)
     const { kid, alg } = header
 
@@ -221,7 +224,7 @@ export class Keyset<K extends Key = Key> implements Iterable<K> {
 
     for (const key of this.list({ kid, alg })) {
       try {
-        const result = await key.verifyJwt<P, C>(token, options)
+        const result = await key.verifyJwt<C>(token, options)
         return { ...result, key }
       } catch (err) {
         errors.push(err)
@@ -237,4 +240,9 @@ export class Keyset<K extends Key = Key> implements Iterable<K> {
         throw JwtVerifyError.from(errors, ERR_JWT_INVALID)
     }
   }
+
+  toJSON(): JwksPub {
+    // Make a copy to prevent mutation of the original keyset
+    return structuredClone(this.publicJwks) as UnReadonly<JwksPub>
+  }
 }

package/src/util.ts

@@ -5,14 +5,32 @@ import { RefinementCtx, ZodIssueCode } from 'zod'
 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 type RequiredKey<T, K extends keyof T = never> = Simplify<
+  T & {
+    [L in K]-?: unknown extends T[L]
+      ? NonNullable<unknown> | null
+      : Exclude<T[L], undefined>
+  }
 >
 
+// 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 =

package/tsconfig.build.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/alg.ts","./src/errors.ts","./src/index.ts","./src/jwk.ts","./src/jwks.ts","./src/jwt-decode.ts","./src/jwt-verify.ts","./src/jwt.ts","./src/key.ts","./src/keyset.ts","./src/util.ts"],"version":"5.6.3"}