acrylblends 0.3.0 → 0.4.0

package/plugins/acryl-router/src/core/utils/jwt/jwt.ts

@@ -0,0 +1,292 @@
+/**
+ * @module
+ * JSON Web Token (JWT)
+ * https://datatracker.ietf.org/doc/html/rfc7519
+ */
+
+import { decodeBase64Url, encodeBase64Url } from '../encode.ts'
+import { AlgorithmTypes } from './jwa.ts'
+import type { AsymmetricAlgorithm, SignatureAlgorithm, SymmetricAlgorithm } from './jwa.ts'
+import { signing, verifying } from './jws.ts'
+import type { AppJsonWebKey, SignatureKey } from './jws.ts'
+import {
+  JwtAlgorithmMismatch,
+  JwtAlgorithmNotAllowed,
+  JwtAlgorithmRequired,
+  JwtHeaderInvalid,
+  JwtHeaderRequiresKid,
+  JwtPayloadRequiresAud,
+  JwtSymmetricAlgorithmNotAllowed,
+  JwtTokenAudience,
+  JwtTokenExpired,
+  JwtTokenInvalid,
+  JwtTokenIssuedAt,
+  JwtTokenIssuer,
+  JwtTokenNotBefore,
+  JwtTokenSignatureMismatched,
+} from './types.ts'
+import type { JWTPayload } from './types.ts'
+import { utf8Decoder, utf8Encoder } from './utf8.ts'
+
+const encodeJwtPart = (part: unknown): string =>
+  encodeBase64Url(utf8Encoder.encode(JSON.stringify(part)).buffer).replace(/=/g, '')
+const encodeSignaturePart = (buf: ArrayBufferLike): string => encodeBase64Url(buf).replace(/=/g, '')
+
+const decodeJwtPart = (part: string): TokenHeader | JWTPayload | undefined =>
+  JSON.parse(utf8Decoder.decode(decodeBase64Url(part)))
+
+export interface TokenHeader {
+  alg: SignatureAlgorithm
+  typ?: 'JWT'
+  kid?: string
+}
+
+export function isTokenHeader(obj: unknown): obj is TokenHeader {
+  if (typeof obj === 'object' && obj !== null) {
+    const objWithAlg = obj as { [key: string]: unknown }
+    return (
+      'alg' in objWithAlg &&
+      Object.values(AlgorithmTypes).includes(objWithAlg.alg as AlgorithmTypes) &&
+      (!('typ' in objWithAlg) || objWithAlg.typ === 'JWT')
+    )
+  }
+  return false
+}
+
+export const sign = async (
+  payload: JWTPayload,
+  privateKey: SignatureKey,
+  alg: SignatureAlgorithm = 'HS256'
+): Promise<string> => {
+  const encodedPayload = encodeJwtPart(payload)
+  let encodedHeader
+  if (typeof privateKey === 'object' && 'alg' in privateKey) {
+    alg = privateKey.alg as SignatureAlgorithm
+    encodedHeader = encodeJwtPart({ alg, typ: 'JWT', kid: privateKey.kid })
+  } else {
+    encodedHeader = encodeJwtPart({ alg, typ: 'JWT' })
+  }
+
+  const partialToken = `${encodedHeader}.${encodedPayload}`
+
+  const signaturePart = await signing(privateKey, alg, utf8Encoder.encode(partialToken))
+  const signature = encodeSignaturePart(signaturePart)
+
+  return `${partialToken}.${signature}`
+}
+
+export type VerifyOptions = {
+  /** The expected issuer used for verifying the token */
+  iss?: string | RegExp
+  /** Verify the `nbf` claim (default: `true`) */
+  nbf?: boolean
+  /** Verify the `exp` claim (default: `true`) */
+  exp?: boolean
+  /** Verify the `iat` claim (default: `true`) */
+  iat?: boolean
+  /** Acceptable audience(s) for the token */
+  aud?: string | string[] | RegExp
+}
+
+export type VerifyOptionsWithAlg = {
+  /** The algorithm used for decoding the token */
+  alg: SignatureAlgorithm
+} & VerifyOptions
+
+export const verify = async (
+  token: string,
+  publicKey: SignatureKey,
+  algOrOptions: SignatureAlgorithm | VerifyOptionsWithAlg
+): Promise<JWTPayload> => {
+  if (!algOrOptions) {
+    throw new JwtAlgorithmRequired()
+  }
+
+  const {
+    alg,
+    iss,
+    nbf = true,
+    exp = true,
+    iat = true,
+    aud,
+  } = typeof algOrOptions === 'string' ? { alg: algOrOptions } : algOrOptions
+
+  if (!alg) {
+    throw new JwtAlgorithmRequired()
+  }
+
+  const tokenParts = token.split('.')
+  if (tokenParts.length !== 3) {
+    throw new JwtTokenInvalid(token)
+  }
+
+  const { header, payload } = decode(token)
+  if (!isTokenHeader(header)) {
+    throw new JwtHeaderInvalid(header)
+  }
+  if (header.alg !== alg) {
+    throw new JwtAlgorithmMismatch(alg, header.alg)
+  }
+  const now = Math.floor(Date.now() / 1000)
+  if (nbf && payload.nbf !== undefined) {
+    if (typeof payload.nbf !== 'number' || !Number.isFinite(payload.nbf) || payload.nbf > now) {
+      throw new JwtTokenNotBefore(token)
+    }
+  }
+  if (exp && payload.exp !== undefined) {
+    if (typeof payload.exp !== 'number' || !Number.isFinite(payload.exp) || payload.exp <= now) {
+      throw new JwtTokenExpired(token)
+    }
+  }
+  if (iat && payload.iat !== undefined) {
+    if (typeof payload.iat !== 'number' || !Number.isFinite(payload.iat) || now < payload.iat) {
+      throw new JwtTokenIssuedAt(now, payload.iat)
+    }
+  }
+  if (iss) {
+    if (!payload.iss) {
+      throw new JwtTokenIssuer(iss, null)
+    }
+    if (typeof iss === 'string' && payload.iss !== iss) {
+      throw new JwtTokenIssuer(iss, payload.iss)
+    }
+    if (iss instanceof RegExp && !iss.test(payload.iss)) {
+      throw new JwtTokenIssuer(iss, payload.iss)
+    }
+  }
+
+  if (aud) {
+    if (!payload.aud) {
+      throw new JwtPayloadRequiresAud(payload)
+    }
+
+    const audiences = Array.isArray(payload.aud) ? payload.aud : [payload.aud]
+    const matched = audiences.some((payloadAud): boolean =>
+      aud instanceof RegExp
+        ? aud.test(payloadAud)
+        : typeof aud === 'string'
+          ? payloadAud === aud
+          : Array.isArray(aud) && aud.includes(payloadAud)
+    )
+    if (!matched) {
+      throw new JwtTokenAudience(aud, payload.aud)
+    }
+  }
+
+  const headerPayload = token.substring(0, token.lastIndexOf('.'))
+  let signature: Uint8Array<ArrayBuffer>
+  try {
+    signature = decodeBase64Url(tokenParts[2])
+  } catch {
+    throw new JwtTokenInvalid(token)
+  }
+  const verified = await verifying(publicKey, alg, signature, utf8Encoder.encode(headerPayload))
+  if (!verified) {
+    throw new JwtTokenSignatureMismatched(token)
+  }
+
+  return payload
+}
+
+// Symmetric algorithms that are not allowed for JWK verification
+const symmetricAlgorithms: SymmetricAlgorithm[] = [
+  AlgorithmTypes.HS256,
+  AlgorithmTypes.HS384,
+  AlgorithmTypes.HS512,
+]
+
+export const verifyWithJwks = async (
+  token: string,
+  options: {
+    keys?: AppJsonWebKey[]
+    jwks_uri?: string
+    verification?: VerifyOptions
+    allowedAlgorithms: readonly AsymmetricAlgorithm[]
+  },
+  init?: RequestInit
+): Promise<JWTPayload> => {
+  const verifyOpts = options.verification || {}
+
+  const header = decodeHeader(token)
+
+  if (!isTokenHeader(header)) {
+    throw new JwtHeaderInvalid(header)
+  }
+  if (!header.kid) {
+    throw new JwtHeaderRequiresKid(header)
+  }
+
+  // Reject symmetric algorithms (HS256, HS384, HS512) to prevent algorithm confusion attacks
+  if (symmetricAlgorithms.includes(header.alg as SymmetricAlgorithm)) {
+    throw new JwtSymmetricAlgorithmNotAllowed(header.alg)
+  }
+
+  // Validate against allowed algorithms
+  if (!options.allowedAlgorithms.includes(header.alg as AsymmetricAlgorithm)) {
+    throw new JwtAlgorithmNotAllowed(header.alg, options.allowedAlgorithms)
+  }
+
+  let verifyKeys = options.keys ? [...options.keys] : undefined
+
+  if (options.jwks_uri) {
+    const response = await fetch(options.jwks_uri, init)
+    if (!response.ok) {
+      throw new Error(`failed to fetch JWKS from ${options.jwks_uri}`)
+    }
+    const data = (await response.json()) as { keys?: JsonWebKey[] }
+    if (!data.keys) {
+      throw new Error('invalid JWKS response. "keys" field is missing')
+    }
+    if (!Array.isArray(data.keys)) {
+      throw new Error('invalid JWKS response. "keys" field is not an array')
+    }
+    verifyKeys ??= []
+    verifyKeys.push(...(data.keys as AppJsonWebKey[]))
+  } else if (!verifyKeys) {
+    throw new Error('verifyWithJwks requires options for either "keys" or "jwks_uri" or both')
+  }
+
+  const matchingKey = verifyKeys.find((key) => key.kid === header.kid)
+  if (!matchingKey) {
+    throw new JwtTokenInvalid(token)
+  }
+
+  // Verify that JWK's alg matches JWT header's alg when JWK has alg field
+  if (matchingKey.alg && matchingKey.alg !== header.alg) {
+    throw new JwtAlgorithmMismatch(matchingKey.alg, header.alg)
+  }
+
+  return await verify(token, matchingKey, {
+    alg: header.alg,
+    ...verifyOpts,
+  })
+}
+
+export const decode = (token: string): { header: TokenHeader; payload: JWTPayload } => {
+  const parts = token.split('.')
+  if (parts.length !== 3) {
+    throw new JwtTokenInvalid(token)
+  }
+  try {
+    const header = decodeJwtPart(parts[0]) as TokenHeader
+    const payload = decodeJwtPart(parts[1]) as JWTPayload
+    return {
+      header,
+      payload,
+    }
+  } catch {
+    throw new JwtTokenInvalid(token)
+  }
+}
+
+export const decodeHeader = (token: string): TokenHeader => {
+  const parts = token.split('.')
+  if (parts.length !== 3) {
+    throw new JwtTokenInvalid(token)
+  }
+  try {
+    return decodeJwtPart(parts[0]) as TokenHeader
+  } catch {
+    throw new JwtTokenInvalid(token)
+  }
+}

package/plugins/acryl-router/src/core/utils/jwt/types.ts

@@ -0,0 +1,157 @@
+/**
+ * @module
+ * Type definitions for JWT utilities.
+ */
+
+export class JwtAlgorithmNotImplemented extends Error {
+  constructor(alg: string) {
+    super(`${alg} is not an implemented algorithm`)
+    this.name = 'JwtAlgorithmNotImplemented'
+  }
+}
+
+export class JwtAlgorithmRequired extends Error {
+  constructor() {
+    super('JWT verification requires "alg" option to be specified')
+    this.name = 'JwtAlgorithmRequired'
+  }
+}
+
+export class JwtAlgorithmMismatch extends Error {
+  constructor(expected: string, actual: string) {
+    super(`JWT algorithm mismatch: expected "${expected}", got "${actual}"`)
+    this.name = 'JwtAlgorithmMismatch'
+  }
+}
+
+export class JwtTokenInvalid extends Error {
+  constructor(token: string) {
+    super(`invalid JWT token: ${token}`)
+    this.name = 'JwtTokenInvalid'
+  }
+}
+
+export class JwtTokenNotBefore extends Error {
+  constructor(token: string) {
+    super(`token (${token}) is being used before it's valid`)
+    this.name = 'JwtTokenNotBefore'
+  }
+}
+
+export class JwtTokenExpired extends Error {
+  constructor(token: string) {
+    super(`token (${token}) expired`)
+    this.name = 'JwtTokenExpired'
+  }
+}
+
+export class JwtTokenIssuedAt extends Error {
+  constructor(currentTimestamp: number, iat: number) {
+    super(
+      `Invalid "iat" claim, must be a valid number lower than "${currentTimestamp}" (iat: "${iat}")`
+    )
+    this.name = 'JwtTokenIssuedAt'
+  }
+}
+
+export class JwtTokenIssuer extends Error {
+  constructor(expected: string | RegExp, iss: string | null) {
+    super(`expected issuer "${expected}", got ${iss ? `"${iss}"` : 'none'} `)
+    this.name = 'JwtTokenIssuer'
+  }
+}
+
+export class JwtHeaderInvalid extends Error {
+  constructor(header: object) {
+    super(`jwt header is invalid: ${JSON.stringify(header)}`)
+    this.name = 'JwtHeaderInvalid'
+  }
+}
+
+export class JwtHeaderRequiresKid extends Error {
+  constructor(header: object) {
+    super(`required "kid" in jwt header: ${JSON.stringify(header)}`)
+    this.name = 'JwtHeaderRequiresKid'
+  }
+}
+
+export class JwtSymmetricAlgorithmNotAllowed extends Error {
+  constructor(alg: string) {
+    super(`symmetric algorithm "${alg}" is not allowed for JWK verification`)
+    this.name = 'JwtSymmetricAlgorithmNotAllowed'
+  }
+}
+
+export class JwtAlgorithmNotAllowed extends Error {
+  constructor(alg: string, allowedAlgorithms: readonly string[]) {
+    super(`algorithm "${alg}" is not in the allowed list: [${allowedAlgorithms.join(', ')}]`)
+    this.name = 'JwtAlgorithmNotAllowed'
+  }
+}
+
+export class JwtTokenSignatureMismatched extends Error {
+  constructor(token: string) {
+    super(`token(${token}) signature mismatched`)
+    this.name = 'JwtTokenSignatureMismatched'
+  }
+}
+
+export class JwtPayloadRequiresAud extends Error {
+  constructor(payload: object) {
+    super(`required "aud" in jwt payload: ${JSON.stringify(payload)}`)
+    this.name = 'JwtPayloadRequiresAud'
+  }
+}
+
+export class JwtTokenAudience extends Error {
+  constructor(expected: string | string[] | RegExp, aud: string | string[]) {
+    super(
+      `expected audience "${
+        Array.isArray(expected) ? expected.join(', ') : expected
+      }", got "${aud}"`
+    )
+    this.name = 'JwtTokenAudience'
+  }
+}
+
+export const CryptoKeyUsage = {
+  Encrypt: 'encrypt',
+  Decrypt: 'decrypt',
+  Sign: 'sign',
+  Verify: 'verify',
+  DeriveKey: 'deriveKey',
+  DeriveBits: 'deriveBits',
+  WrapKey: 'wrapKey',
+  UnwrapKey: 'unwrapKey',
+} as const
+export type CryptoKeyUsage = (typeof CryptoKeyUsage)[keyof typeof CryptoKeyUsage]
+
+/**
+ * JWT Payload
+ */
+export type JWTPayload = {
+  [key: string]: unknown
+  /**
+   * The token is checked to ensure it has not expired.
+   */
+  exp?: number
+  /**
+   * The token is checked to ensure it is not being used before a specified time.
+   */
+  nbf?: number
+  /**
+   * The token is checked to ensure it is not issued in the future.
+   */
+  iat?: number
+  /**
+   * The token is checked to ensure it has been issued by a trusted issuer.
+   */
+  iss?: string
+
+  /**
+   * The token is checked to ensure it is intended for a specific audience.
+   */
+  aud?: string | string[]
+}
+
+export type { AppJsonWebKey } from './jws.ts'

package/plugins/acryl-router/src/core/utils/jwt/utf8.ts

@@ -0,0 +1,7 @@
+/**
+ * @module
+ * Functions for encoding/decoding UTF8.
+ */
+
+export const utf8Encoder: TextEncoder = new TextEncoder()
+export const utf8Decoder: TextDecoder = new TextDecoder()

package/plugins/acryl-router/src/core/utils/mime.test.ts

@@ -0,0 +1,64 @@
+import { getExtension, getMimeType } from './mime.ts'
+
+const mime = {
+  m3u8: 'application/vnd.apple.mpegurl',
+  ts: 'video/mp2t',
+}
+
+describe('mime', () => {
+  it('getMimeType', () => {
+    expect(getMimeType('hello.txt')).toBe('text/plain; charset=utf-8')
+    expect(getMimeType('hello.html')).toBe('text/html; charset=utf-8')
+    expect(getMimeType('hello.json')).toBe('application/json')
+    expect(getMimeType('favicon.ico')).toBe('image/x-icon')
+    expect(getMimeType('good.morning.hello.gif')).toBe('image/gif')
+    expect(getMimeType('site.webmanifest')).toBe('application/manifest+json')
+    expect(getMimeType('goodmorninghellogif')).toBeUndefined()
+    expect(getMimeType('indexjs.abcd')).toBeUndefined()
+    expect(getMimeType('IMAGE.JPG')).toBe('image/jpeg')
+  })
+
+  it('getMimeType returns charset parameter for text and XML-based formats', () => {
+    expect(getMimeType('icon.svg')).toBe('image/svg+xml; charset=utf-8')
+    expect(getMimeType('page.xhtml')).toBe('application/xhtml+xml; charset=utf-8')
+    expect(getMimeType('feed.xml')).toBe('application/xml; charset=utf-8')
+    expect(getMimeType('events.ics')).toBe('text/calendar; charset=utf-8')
+    expect(getMimeType('script.mjs')).toBe('text/javascript; charset=utf-8')
+    expect(getMimeType('style.css')).toBe('text/css; charset=utf-8')
+    expect(getMimeType('data.csv')).toBe('text/csv; charset=utf-8')
+  })
+
+  it('getMimeType with custom mime', () => {
+    expect(getMimeType('morning-routine.m3u8', mime)).toBe('application/vnd.apple.mpegurl')
+    expect(getMimeType('morning-routine1.ts', mime)).toBe('video/mp2t')
+    expect(getMimeType('readme.txt', mime)).toBeUndefined()
+  })
+
+  it('getExtension', () => {
+    expect(getExtension('audio/aac')).toBe('aac')
+    expect(getExtension('video/x-msvideo')).toBe('avi')
+    expect(getExtension('image/avif')).toBe('avif')
+    expect(getExtension('text/css')).toBe('css')
+    expect(getExtension('text/html')).toBe('htm')
+    expect(getExtension('image/jpeg')).toBe('jpeg')
+    expect(getExtension('text/javascript')).toBe('js')
+    expect(getExtension('application/json')).toBe('json')
+    expect(getExtension('audio/mpeg')).toBe('mp3')
+    expect(getExtension('video/mp4')).toBe('mp4')
+    expect(getExtension('application/pdf')).toBe('pdf')
+    expect(getExtension('image/png')).toBe('png')
+    expect(getExtension('application/zip')).toBe('zip')
+    expect(getExtension('non/existent')).toBeUndefined()
+  })
+
+  it('getExtension matches MIME types regardless of charset/parameters', () => {
+    expect(getExtension('text/html; charset=utf-8')).toBe('htm')
+    expect(getExtension('text/plain; charset=utf-8')).toBe('txt')
+    expect(getExtension('image/svg+xml; charset=utf-8')).toBe('svg')
+    expect(getExtension('application/xml; charset=utf-8')).toBe('xml')
+    expect(getExtension('application/xhtml+xml; charset=utf-8')).toBe('xhtml')
+    expect(getExtension('text/css; charset=utf-16')).toBe('css')
+    expect(getExtension('image/svg+xml')).toBe('svg')
+    expect(getExtension('application/xml')).toBe('xml')
+  })
+})

package/plugins/acryl-router/src/core/utils/mime.ts

@@ -0,0 +1,94 @@
+/**
+ * @module
+ * MIME utility.
+ */
+
+export const getMimeType = (
+  filename: string,
+  mimes: Record<string, string> = baseMimes
+): string | undefined => {
+  const regexp = /\.([a-zA-Z0-9]+?)$/
+  const match = filename.match(regexp)
+  if (!match) {
+    return
+  }
+  return mimes[match[1].toLowerCase()]
+}
+
+export const getExtension = (mimeType: string): string | undefined => {
+  const baseType = mimeType.split(';', 1)[0].trim()
+  for (const ext in baseMimes) {
+    const stored = baseMimes[ext]
+    if (stored === mimeType || stored.split(';', 1)[0].trim() === baseType) {
+      return ext
+    }
+  }
+}
+
+export { baseMimes as mimes }
+
+/**
+ * Union types for BaseMime
+ */
+export type BaseMime = (typeof _baseMimes)[keyof typeof _baseMimes]
+
+const _baseMimes = {
+  aac: 'audio/aac',
+  avi: 'video/x-msvideo',
+  avif: 'image/avif',
+  av1: 'video/av1',
+  bin: 'application/octet-stream',
+  bmp: 'image/bmp',
+  css: 'text/css; charset=utf-8',
+  csv: 'text/csv; charset=utf-8',
+  eot: 'application/vnd.ms-fontobject',
+  epub: 'application/epub+zip',
+  gif: 'image/gif',
+  gz: 'application/gzip',
+  htm: 'text/html; charset=utf-8',
+  html: 'text/html; charset=utf-8',
+  ico: 'image/x-icon',
+  ics: 'text/calendar; charset=utf-8',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  js: 'text/javascript; charset=utf-8',
+  json: 'application/json',
+  jsonld: 'application/ld+json',
+  map: 'application/json',
+  mid: 'audio/x-midi',
+  midi: 'audio/x-midi',
+  mjs: 'text/javascript; charset=utf-8',
+  mp3: 'audio/mpeg',
+  mp4: 'video/mp4',
+  mpeg: 'video/mpeg',
+  oga: 'audio/ogg',
+  ogv: 'video/ogg',
+  ogx: 'application/ogg',
+  opus: 'audio/opus',
+  otf: 'font/otf',
+  pdf: 'application/pdf',
+  png: 'image/png',
+  rtf: 'application/rtf',
+  svg: 'image/svg+xml; charset=utf-8',
+  tif: 'image/tiff',
+  tiff: 'image/tiff',
+  ts: 'video/mp2t',
+  ttf: 'font/ttf',
+  txt: 'text/plain; charset=utf-8',
+  wasm: 'application/wasm',
+  webm: 'video/webm',
+  weba: 'audio/webm',
+  webmanifest: 'application/manifest+json',
+  webp: 'image/webp',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  xhtml: 'application/xhtml+xml; charset=utf-8',
+  xml: 'application/xml; charset=utf-8',
+  zip: 'application/zip',
+  '3gp': 'video/3gpp',
+  '3g2': 'video/3gpp2',
+  gltf: 'model/gltf+json',
+  glb: 'model/gltf-binary',
+} as const
+
+const baseMimes: Record<string, BaseMime> = _baseMimes