@atproto/jwk 0.1.0

package/dist/util.d.ts

@@ -0,0 +1,48 @@
+import { RefinementCtx } 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 declare const isDefined: <T>(i: T | undefined) => i is T;
+export declare const preferredOrderCmp: <T>(order: readonly T[]) => (a: T, b: T) => number;
+export declare function matchesAny<T extends string | number | symbol | boolean>(value: null | undefined | T | readonly T[]): (v: unknown) => v is T;
+/**
+ * Decorator to cache the result of a getter on a class instance.
+ */
+export declare const cachedGetter: <T extends object, V>(target: (this: T) => V, _context: ClassGetterDecoratorContext<T, V>) => (this: T) => V;
+export declare function parseB64uJson(input: string): unknown;
+/**
+ * @example
+ * ```ts
+ * // jwtSchema will only allow base64url chars & "." (dot)
+ * const jwtSchema = z.string().superRefine(jwtCharsRefinement)
+ * ```
+ */
+export declare const jwtCharsRefinement: (data: string, ctx: RefinementCtx) => void;
+/**
+ * @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 declare const segmentedStringRefinementFactory: <C extends number>(count: C, minPartLength?: number) => (data: string, ctx: RefinementCtx) => data is SegmentedString<C, [string]>;
+export {};
+//# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAgB,MAAM,KAAK,CAAA;AAGjD,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,EAAE,CAAA;AACvD,MAAM,MAAM,QAAQ,CAAC,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;AAE3D,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,QAAQ,CACrD,MAAM,SAAS,CAAC,GACZ,CAAC,GACD;KACG,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,CAAC;CACjE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CACnB,CAAA;AAED,eAAO,MAAM,SAAS,SAAU,CAAC,GAAG,SAAS,WAA4B,CAAA;AAEzE,eAAO,MAAM,iBAAiB,aACjB,SAAS,CAAC,EAAE,SACnB,CAAC,KAAK,CAAC,WAOV,CAAA;AAEH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EACrE,KAAK,EAAE,IAAI,GAAG,SAAS,GAAG,CAAC,GAAG,SAAS,CAAC,EAAE,GACzC,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,IAAI,CAAC,CAMxB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,gCACf,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,YACZ,4BAA4B,CAAC,EAAE,CAAC,CAAC,YAEpB,CAAC,MASzB,CAAA;AAGD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAIpD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,SAAU,MAAM,OAAO,aAAa,KAAG,IA2BrE,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,KAAK,eAAe,CAClB,CAAC,SAAS,MAAM,EAChB,GAAG,SAAS,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,IAC7B,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,GACvB,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,GACX,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,EAAE,CAAA;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,4BACpC,CAAC,oCAUM,MAAM,OAAO,aAAa,yCA2CzC,CAAA"}

package/dist/util.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.segmentedStringRefinementFactory = exports.jwtCharsRefinement = exports.parseB64uJson = exports.cachedGetter = exports.matchesAny = exports.preferredOrderCmp = exports.isDefined = void 0;
+const base64_1 = require("multiformats/bases/base64");
+const zod_1 = require("zod");
+const isDefined = (i) => i !== undefined;
+exports.isDefined = isDefined;
+const preferredOrderCmp = (order) => (a, b) => {
+    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;
+};
+exports.preferredOrderCmp = preferredOrderCmp;
+function matchesAny(value) {
+    return value == null
+        ? (v) => true
+        : Array.isArray(value)
+            ? (v) => value.includes(v)
+            : (v) => v === value;
+}
+exports.matchesAny = matchesAny;
+/**
+ * Decorator to cache the result of a getter on a class instance.
+ */
+const cachedGetter = (target, _context) => {
+    return function () {
+        const value = target.call(this);
+        Object.defineProperty(this, target.name, {
+            get: () => value,
+            enumerable: true,
+            configurable: true,
+        });
+        return value;
+    };
+};
+exports.cachedGetter = cachedGetter;
+const decoder = new TextDecoder();
+function parseB64uJson(input) {
+    const inputBytes = base64_1.base64url.baseDecode(input);
+    const json = decoder.decode(inputBytes);
+    return JSON.parse(json);
+}
+exports.parseB64uJson = parseB64uJson;
+/**
+ * @example
+ * ```ts
+ * // jwtSchema will only allow base64url chars & "." (dot)
+ * const jwtSchema = z.string().superRefine(jwtCharsRefinement)
+ * ```
+ */
+const jwtCharsRefinement = (data, ctx) => {
+    // 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: zod_1.ZodIssueCode.custom,
+                message: `Invalid character "${invalidChar}" in JWT at position ${i}`,
+            });
+        }
+    }
+};
+exports.jwtCharsRefinement = jwtCharsRefinement;
+/**
+ * @example
+ * ```ts
+ * const jwtSchema = z.string().superRefine(segmentedStringRefinementFactory(3))
+ * type Jwt = z.infer<typeof jwtSchema> // `${string}.${string}.${string}`
+ * ```
+ */
+const segmentedStringRefinementFactory = (count, 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, ctx) => {
+        if (data.length < minTotalLength) {
+            ctx.addIssue({
+                code: zod_1.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: zod_1.ZodIssueCode.custom,
+                    message: `${errorPrefix}: expected ${count} segments, got ${i + 1}`,
+                });
+                return false;
+            }
+            if (nextDot - currentStart < minPartLength) {
+                ctx.addIssue({
+                    code: zod_1.ZodIssueCode.custom,
+                    message: `${errorPrefix}: segment ${i + 1} is too short`,
+                });
+                return false;
+            }
+            currentStart = nextDot + 1;
+        }
+        if (data.indexOf('.', currentStart) !== -1) {
+            ctx.addIssue({
+                code: zod_1.ZodIssueCode.custom,
+                message: `${errorPrefix}: too many segments`,
+            });
+            return false;
+        }
+        if (data.length - currentStart < minPartLength) {
+            ctx.addIssue({
+                code: zod_1.ZodIssueCode.custom,
+                message: `${errorPrefix}: last segment is too short`,
+            });
+            return false;
+        }
+        return true;
+    };
+};
+exports.segmentedStringRefinementFactory = segmentedStringRefinementFactory;
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@atproto/jwk",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "A library for working with JSON Web Keys (JWKs) in TypeScript. This is meant to be extended by environment-specific libraries like @atproto/jwk-jose.",
+  "keywords": [
+    "atproto",
+    "jwk",
+    "jwks",
+    "jwt",
+    "json web key"
+  ],
+  "homepage": "https://atproto.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bluesky-social/atproto",
+    "directory": "packages/oauth/jwk"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "multiformats": "^9.9.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "build": "tsc --build tsconfig.json"
+  }
+}

package/src/alg.ts

@@ -0,0 +1,98 @@
+import { JwkError } from './errors.js'
+import { Jwk } from './jwk.js'
+
+declare const process: undefined | { versions?: { node?: string } }
+const IS_NODE_RUNTIME =
+  typeof process !== 'undefined' && typeof process?.versions?.node === 'string'
+
+export function* jwkAlgorithms(jwk: Jwk): Generator<string> {
+  // Ed25519, Ed448, and secp256k1 always have "alg"
+  // OKP always has "use"
+  if (jwk.alg) {
+    yield jwk.alg
+    return
+  }
+
+  switch (jwk.kty) {
+    case 'EC': {
+      if (jwk.use === 'enc' || jwk.use === undefined) {
+        yield 'ECDH-ES'
+        yield 'ECDH-ES+A128KW'
+        yield 'ECDH-ES+A192KW'
+        yield 'ECDH-ES+A256KW'
+      }
+
+      if (jwk.use === 'sig' || jwk.use === undefined) {
+        const crv = 'crv' in jwk ? jwk.crv : undefined
+        switch (crv) {
+          case 'P-256':
+          case 'P-384':
+            yield `ES${crv.slice(-3)}`
+            break
+          case 'P-521':
+            yield 'ES512'
+            break
+          case 'secp256k1':
+            if (IS_NODE_RUNTIME) yield 'ES256K'
+            break
+          default:
+            throw new JwkError(`Unsupported crv "${crv}"`)
+        }
+      }
+
+      return
+    }
+
+    case 'OKP': {
+      if (!jwk.use) throw new JwkError('Missing "use" Parameter value')
+      yield 'ECDH-ES'
+      yield 'ECDH-ES+A128KW'
+      yield 'ECDH-ES+A192KW'
+      yield 'ECDH-ES+A256KW'
+      return
+    }
+
+    case 'RSA': {
+      if (jwk.use === 'enc' || jwk.use === undefined) {
+        yield 'RSA-OAEP'
+        yield 'RSA-OAEP-256'
+        yield 'RSA-OAEP-384'
+        yield 'RSA-OAEP-512'
+        if (IS_NODE_RUNTIME) yield 'RSA1_5'
+      }
+
+      if (jwk.use === 'sig' || jwk.use === undefined) {
+        yield 'PS256'
+        yield 'PS384'
+        yield 'PS512'
+        yield 'RS256'
+        yield 'RS384'
+        yield 'RS512'
+      }
+
+      return
+    }
+
+    case 'oct': {
+      if (jwk.use === 'enc' || jwk.use === undefined) {
+        yield 'A128GCMKW'
+        yield 'A192GCMKW'
+        yield 'A256GCMKW'
+        yield 'A128KW'
+        yield 'A192KW'
+        yield 'A256KW'
+      }
+
+      if (jwk.use === 'sig' || jwk.use === undefined) {
+        yield 'HS256'
+        yield 'HS384'
+        yield 'HS512'
+      }
+
+      return
+    }
+
+    default:
+      throw new JwkError(`Unsupported kty "${jwk.kty}"`)
+  }
+}

package/src/errors.ts

@@ -0,0 +1,56 @@
+export type ErrorOptions = { cause?: unknown }
+
+export const ERR_JWKS_NO_MATCHING_KEY = 'ERR_JWKS_NO_MATCHING_KEY'
+export const ERR_JWK_INVALID = 'ERR_JWK_INVALID'
+export const ERR_JWK_NOT_FOUND = 'ERR_JWK_NOT_FOUND'
+export const ERR_JWT_INVALID = 'ERR_JWT_INVALID'
+export const ERR_JWT_CREATE = 'ERR_JWT_CREATE'
+export const ERR_JWT_VERIFY = 'ERR_JWT_VERIFY'
+
+export class JwkError extends TypeError {
+  constructor(
+    message = 'JWK error',
+    public readonly code = ERR_JWK_INVALID,
+    options?: ErrorOptions,
+  ) {
+    super(message, options)
+  }
+}
+
+export class JwtCreateError extends Error {
+  constructor(
+    message = 'Unable to create JWT',
+    public readonly code = ERR_JWT_CREATE,
+    options?: ErrorOptions,
+  ) {
+    super(message, options)
+  }
+
+  static from(cause: unknown, code?: string, message?: string): JwtCreateError {
+    if (cause instanceof JwtCreateError) return cause
+    if (cause instanceof JwkError) {
+      return new JwtCreateError(message, cause.code, { cause })
+    }
+
+    return new JwtCreateError(message, code, { cause })
+  }
+}
+
+export class JwtVerifyError extends Error {
+  constructor(
+    message = 'Invalid JWT',
+    public readonly code = ERR_JWT_VERIFY,
+    options?: ErrorOptions,
+  ) {
+    super(message, options)
+  }
+
+  static from(cause: unknown, code?: string, message?: string): JwtVerifyError {
+    if (cause instanceof JwtVerifyError) return cause
+    if (cause instanceof JwkError) {
+      return new JwtVerifyError(message, cause.code, { cause })
+    }
+
+    return new JwtVerifyError(message, code, { cause })
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './alg.js'
+export * from './errors.js'
+export * from './jwk.js'
+export * from './jwks.js'
+export * from './jwt-decode.js'
+export * from './jwt-verify.js'
+export * from './jwt.js'
+export * from './key.js'
+export * from './keyset.js'
+export * from './util.js'

package/src/jwk.ts

@@ -0,0 +1,141 @@
+import { z } from 'zod'
+
+export const keyUsageSchema = z.enum([
+  'sign',
+  'verify',
+  'encrypt',
+  'decrypt',
+  'wrapKey',
+  'unwrapKey',
+  'deriveKey',
+  'deriveBits',
+])
+
+export type KeyUsage = z.infer<typeof keyUsageSchema>
+
+/**
+ * The "use" and "key_ops" JWK members SHOULD NOT be used together;
+ * however, if both are used, the information they convey MUST be
+ * consistent.  Applications should specify which of these members they
+ * use, if either is to be used by the application.
+ *
+ * @todo Actually check that "use" and "key_ops" are consistent when both are present.
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7517#section-4.3}
+ */
+export const jwkBaseSchema = z.object({
+  kty: z.string().min(1),
+  alg: z.string().min(1).optional(),
+  kid: z.string().min(1).optional(),
+  ext: z.boolean().optional(),
+  use: z.enum(['sig', 'enc']).optional(),
+  key_ops: z.array(keyUsageSchema).optional(),
+
+  x5c: z.array(z.string()).optional(), // X.509 Certificate Chain
+  x5t: z.string().min(1).optional(), // X.509 Certificate SHA-1 Thumbprint
+  'x5t#S256': z.string().min(1).optional(), // X.509 Certificate SHA-256 Thumbprint
+  x5u: z.string().url().optional(), // X.509 URL
+})
+
+/**
+ * @todo: properly implement this
+ */
+export const jwkRsaKeySchema = jwkBaseSchema.extend({
+  kty: z.literal('RSA'),
+  alg: z
+    .enum(['RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512'])
+    .optional(),
+
+  n: z.string().min(1), // Modulus
+  e: z.string().min(1), // Exponent
+
+  d: z.string().min(1).optional(), // Private Exponent
+  p: z.string().min(1).optional(), // First Prime Factor
+  q: z.string().min(1).optional(), // Second Prime Factor
+  dp: z.string().min(1).optional(), // First Factor CRT Exponent
+  dq: z.string().min(1).optional(), // Second Factor CRT Exponent
+  qi: z.string().min(1).optional(), // First CRT Coefficient
+  oth: z
+    .array(
+      z.object({
+        r: z.string().optional(),
+        d: z.string().optional(),
+        t: z.string().optional(),
+      }),
+    )
+    .nonempty()
+
+    .optional(), // Other Primes Info
+})
+
+export const jwkEcKeySchema = jwkBaseSchema.extend({
+  kty: z.literal('EC'),
+  alg: z.enum(['ES256', 'ES384', 'ES512']).optional(),
+  crv: z.enum(['P-256', 'P-384', 'P-521']),
+
+  x: z.string().min(1),
+  y: z.string().min(1),
+
+  d: z.string().min(1).optional(), // ECC Private Key
+})
+
+export const jwkEcSecp256k1KeySchema = jwkBaseSchema.extend({
+  kty: z.literal('EC'),
+  alg: z.enum(['ES256K']).optional(),
+  crv: z.enum(['secp256k1']),
+
+  x: z.string().min(1),
+  y: z.string().min(1),
+
+  d: z.string().min(1).optional(), // ECC Private Key
+})
+
+export const jwkOkpKeySchema = jwkBaseSchema.extend({
+  kty: z.literal('OKP'),
+  alg: z.enum(['EdDSA']).optional(),
+  crv: z.enum(['Ed25519', 'Ed448']),
+
+  x: z.string().min(1),
+  d: z.string().min(1).optional(), // ECC Private Key
+})
+
+export const jwkSymKeySchema = jwkBaseSchema.extend({
+  kty: z.literal('oct'), // Octet Sequence (used to represent symmetric keys)
+  alg: z.enum(['HS256', 'HS384', 'HS512']).optional(),
+
+  k: z.string(), // Key Value (base64url encoded)
+})
+
+export const jwkUnknownKeySchema = jwkBaseSchema.extend({
+  kty: z
+    .string()
+    .refine((v) => v !== 'RSA' && v !== 'EC' && v !== 'OKP' && v !== 'oct'),
+})
+
+export const jwkSchema = z.union([
+  jwkUnknownKeySchema,
+  jwkRsaKeySchema,
+  jwkEcKeySchema,
+  jwkEcSecp256k1KeySchema,
+  jwkOkpKeySchema,
+  jwkSymKeySchema,
+])
+
+export type Jwk = z.infer<typeof jwkSchema>
+
+export const jwkValidator = jwkSchema
+  .refine((k) => k.use != null || k.key_ops != null, 'use or key_ops required')
+  .refine(
+    (k) =>
+      !k.use ||
+      !k.key_ops ||
+      k.key_ops.every((o) =>
+        k.use === 'sig'
+          ? o === 'sign' || o === 'verify'
+          : o === 'encrypt' || o === 'decrypt',
+      ),
+    'use and key_ops must be consistent',
+  )
+
+export const jwkPubSchema = jwkValidator
+  .refine((k) => k.kid != null, 'kid is required')
+  .refine((k) => !('k' in k) && !('d' in k), 'private key not allowed')

package/src/jwks.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+
+import { jwkPubSchema, jwkSchema } from './jwk.js'
+
+export const jwksSchema = z.object({
+  keys: z.array(jwkSchema),
+})
+
+export type Jwks = z.infer<typeof jwksSchema>
+
+export const jwksPubSchema = z.object({
+  keys: z.array(jwkPubSchema),
+})
+
+export type JwksPub = z.infer<typeof jwksPubSchema>

package/src/jwt-decode.ts

@@ -0,0 +1,27 @@
+import { ERR_JWT_INVALID, JwtVerifyError } from './errors.js'
+import {
+  JwtHeader,
+  JwtPayload,
+  jwtHeaderSchema,
+  jwtPayloadSchema,
+} from './jwt.js'
+import { parseB64uJson } from './util.js'
+
+export function unsafeDecodeJwt(jwt: string): {
+  header: JwtHeader
+  payload: JwtPayload
+} {
+  const { 0: headerEnc, 1: payloadEnc, length } = jwt.split('.')
+  if (length > 3 || length < 2) {
+    throw new JwtVerifyError(undefined, ERR_JWT_INVALID)
+  }
+
+  const header = jwtHeaderSchema.parse(parseB64uJson(headerEnc!))
+  if (length === 2 && header?.alg !== 'none') {
+    throw new JwtVerifyError(undefined, ERR_JWT_INVALID)
+  }
+
+  const payload = jwtPayloadSchema.parse(parseB64uJson(payloadEnc!))
+
+  return { header, payload }
+}

package/src/jwt-verify.ts

@@ -0,0 +1,22 @@
+import { JwtHeader, JwtPayload } from './jwt.js'
+import { RequiredKey } from './util.js'
+
+export type VerifyOptions<C extends string = string> = {
+  audience?: string | readonly string[]
+  /** in seconds */
+  clockTolerance?: number
+  issuer?: string | readonly string[]
+  /** in seconds */
+  maxTokenAge?: number
+  subject?: string
+  typ?: string
+  currentDate?: Date
+  requiredClaims?: readonly C[]
+}
+
+export type VerifyPayload = Record<string, unknown>
+
+export type VerifyResult<P extends VerifyPayload, C extends string> = {
+  payload: RequiredKey<P & JwtPayload, C>
+  protectedHeader: JwtHeader
+}