feat(jwt): allow custom typ in JwtHeader and createJwt

.changeset/allow-custom-jwt-typ.md

@@ -0,0 +1,5 @@
+---
+"@agentcommercekit/jwt": patch
+---
+
+Allow optional custom `typ` header in `JwtHeader` and `createJwt` to support specialized JWT profiles (such as Skyfire KYA tokens).

demos/skyfire-kya/src/kya-token.ts

@@ -53,7 +53,6 @@ export async function createMockSkyfireKyaToken(
       expiresIn: 3600,
     },
     {
-      // @ts-expect-error - TODO: fix this
       typ: "kya+JWT",
       alg: "ES256",
     },

packages/jwt/src/create-jwt.test.ts

@@ -55,4 +55,22 @@ describe("createJWT", () => {
       "Failed to create JWT",
     )
   })
+
+  it("creates a JWT with custom typ and alg header overrides", async () => {
+    const expectedJwt =
+      "eyJ0eXAiOiJreWErSldUIiwiYWxnIjoiRVMyNTYifQ.eyJpc3MiOiJkaWQ6ZXhhbXBsZTo0NTYifQ.sig"
+
+    vi.mocked(baseCreateJWT).mockResolvedValueOnce(expectedJwt)
+
+    const result = await createJwt(mockPayload, mockOptions, {
+      typ: "kya+JWT",
+      alg: "ES256",
+    })
+
+    expect(result).toBe(expectedJwt)
+    expect(baseCreateJWT).toHaveBeenCalledWith(mockPayload, mockOptions, {
+      typ: "kya+JWT",
+      alg: "ES256",
+    })
+  })
 })

packages/jwt/src/create-jwt.ts

@@ -15,7 +15,7 @@ export type JwtOptions = JWTOptions
  * JWT header that only contains valid JWT algorithms
  */
 export interface JwtHeader extends Omit<JWTHeader, "alg" | "typ"> {
-  typ: "JWT"
+  typ?: string
   alg: JwtAlgorithm
 }
 
@@ -35,10 +35,11 @@ export async function createJwt(
   options: JwtOptions,
   { alg = "ES256K", ...header }: Partial<JwtHeader> = {},
 ): Promise<JwtString> {
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
   const result = await baseCreateJWT(payload, options, {
     ...header,
     alg,
-  })
+  } as Partial<JWTHeader>)
 
   if (!isJwtString(result)) {
     throw new Error("Failed to create JWT")

packages/jwt/src/jwt-algorithm.ts

@@ -3,7 +3,8 @@ import { isKeyCurve, type KeyCurve } from "@agentcommercekit/keys"
 /**
  * JWT signing algorithms supported by the JWT library
  *
- * The did-jwt library also supports non-standard "ES256K-R" for
+ * The did-jwt library also supports non-standard "ES256K-R" for recovery
+ * signatures, which ACK does not support.
  */
 export const jwtAlgorithms = ["ES256", "ES256K", "EdDSA"] as const
 export type JwtAlgorithm = (typeof jwtAlgorithms)[number]

packages/jwt/src/schemas/valibot.ts

@@ -19,10 +19,10 @@ export const jwtPayloadSchema = JwtPayloadSchema
  */
 export const jwtHeaderSchema = v.pipe(
   v.looseObject({
-    typ: v.literal("JWT"),
+    typ: v.optional(v.string()),
     alg: v.picklist(jwtAlgorithms),
   }),
-  v.custom<JwtHeader>(() => true),
+  v.custom<JwtHeader>((_val): _val is JwtHeader => true),
 )
 
 /**

packages/jwt/src/schemas/zod.ts

@@ -22,7 +22,7 @@ export const jwtPayloadSchema = JwtPayloadSchema
  */
 export const jwtHeaderSchema = z
   .looseObject({
-    typ: z.literal("JWT"),
+    typ: z.string().optional(),
     alg: z.enum(jwtAlgorithms),
   })
   .refine((_val): _val is JwtHeader => true)