@ocenkamobi/om-oidc-client-cjs 0.1.0

package/README.md

@@ -0,0 +1,148 @@
+# @ocenkamobi/om-oidc-client-cjs
+
+Клиент сервисных аккаунтов auth.ocenka.mobi для легаси-серверов: CommonJS,
+Node 12+, без зависимостей. Делает две вещи: аутентифицирует запрос к `/token`
+через `client_secret_basic` и кэширует ответ — одинаковый запрос получает тот же
+токен, пока тот не начнёт истекать.
+
+Библиотека отвечает за авторизацию сервисных аккаунтов — про реализацию грантов
+в [auth.ocenka.mobi](https://gitlab.com/ocenkamobi/auth.ocenka.mobi/-/blob/main/docs/README.md)
+ничего не знает.
+
+Для ESM и Node 20+ —
+[`@ocenkamobi/om-oidc-client`](https://gitlab.com/om-misc/om-oidc-client).
+
+## Подключение
+
+```sh
+npm i @ocenkamobi/om-oidc-client-cjs
+```
+
+```js
+// oidc.js
+const { createOmOidcClient } = require('@ocenkamobi/om-oidc-client-cjs')
+
+module.exports = createOmOidcClient({
+  authority: 'https://auth.ocenka.mobi',
+  clientId: process.env.CLIENT_ID,
+  clientSecret: process.env.CLIENT_SECRET
+})
+```
+
+```js
+const oidc = require('./oidc')
+
+const { access_token: accessToken } = await oidc.token({
+  grant_type: 'client_credentials',
+  resource: 'https://express.ocenka.mobi',
+  scope: 'openid profile org express'
+})
+```
+
+Клиент создаётся один на каждый сервисный аккаунт и держит отдельный кэш.
+
+| опция          | по умолчанию | значение                                                        |
+| -------------- | ------------ | --------------------------------------------------------------- |
+| `authority`    | —            | сервер авторизации, токены запрашиваются у `${authority}/token` |
+| `clientId`     | —            | `client_id` сервисного аккаунта                                 |
+| `clientSecret` | —            | `client_secret` сервисного аккаунта                             |
+| `minTtl`       | `60`         | сколько секунд осталось в токене, чтобы его взяли из кэша       |
+| `maxEntries`   | `500`        | сколько записей помещается в кэш                                |
+
+## Кэш
+
+- Ключ — тело запроса. Порядок полей и скоупов в `scope` значения не имеет,
+  пустые поля не учитываются.
+- Токен отдаётся из кэша, пока ему осталось жить не меньше `minTtl` секунд.
+  Срок берётся из `expires_in`.
+- Одновременные одинаковые запросы делают один сетевой вызов.
+- Из кэша вытесняются токены, которыми не пользуются: каждое чтение токена из
+  кэша поднимает его.
+- Ошибки не кэшируются.
+
+```js
+await oidc.token(body, { minTtl: 300 }) // токен нужен на долгую операцию
+await oidc.token(body, { force: true }) // мимо кэша
+oidc.invalidate(body)
+oidc.clear()
+```
+
+Всё тело вызова `await oidc.token(body)` — это ключ для кэша. Все ключи
+хэшируются.
+
+[Отложенный токен](https://gitlab.com/ocenkamobi/auth.ocenka.mobi/-/blob/main/docs/deferred-token.md)
+(`requested_token_type`) выдаётся как любой другой ответ и кэшируется на свои
+7 суток, но bearer-токеном не является: плагины его в заголовок не поставят, а
+кинут ошибку. Обменивать его на access-токен нужно самому — обычным запросом.
+
+## Ошибки
+
+Отказ сервера — `OmOidcTokenError` с полями `status`, `error`,
+`error_description`. Ретраев нет. Запрос к `/token` прерывается через 10 секунд.
+
+## got 11
+
+```js
+const got = require('got')
+const { tokenHooks, withToken } = require('@ocenkamobi/om-oidc-client-cjs/got')
+
+const api = got.extend(tokenHooks(oidc))
+
+await api.get('https://express.ocenka.mobi/api/orders', withToken({
+  grant_type: 'client_credentials',
+  resource: 'https://express.ocenka.mobi'
+})).json()
+```
+
+`withToken()` кладёт параметры в `context` запроса. Без него токен не ставится.
+
+Дефолт для инстанса задаётся тем же `withToken()` вторым аргументом `extend`, а
+снимается `withToken(false)`:
+
+```js
+const express = got.extend(
+  tokenHooks(oidc),
+  withToken({ grant_type: 'client_credentials', resource: 'https://express.ocenka.mobi' })
+)
+
+await express.get('https://express.ocenka.mobi/api/orders')
+await express.get('https://express.ocenka.mobi/api/health', withToken(false))
+```
+
+## axios
+
+```js
+const axios = require('axios')
+const { attachToken } = require('@ocenkamobi/om-oidc-client-cjs/axios')
+
+const api = axios.create()
+attachToken(api, oidc)
+
+await api.get('https://express.ocenka.mobi/api/orders', {
+  oidc: { grant_type: 'client_credentials', resource: 'https://express.ocenka.mobi' }
+})
+```
+
+Токен ставится только запросам с `oidc` — без него заголовок не появится.
+
+При необходимости параметры можно задать один раз: axios сливает конфиг инстанса
+с конфигом запроса, включая `oidc`.
+
+```js
+const express = axios.create({
+  oidc: { grant_type: 'client_credentials', resource: 'https://express.ocenka.mobi' }
+})
+attachToken(express, oidc)
+
+await express.get('https://express.ocenka.mobi/api/orders') // с токеном
+await express.get('https://express.ocenka.mobi/api/health', { oidc: false }) // без токена
+```
+
+`attachToken` возвращает функцию, снимающую интерцептор.
+
+## Тесты
+
+```sh
+pnpm test        # vitest на текущей ноде
+pnpm test:node12 # смоук в node:12-alpine, нужен Docker
+```

package/axios.d.ts

@@ -0,0 +1,12 @@
+import type { AxiosInstance } from 'axios'
+import type { OmOidcClient, OmOidcTokenRequest } from './index'
+
+declare module 'axios' {
+  interface AxiosRequestConfig {
+    /** Параметры запроса токена: с ними запрос уходит с `Authorization: Bearer …` */
+    oidc?: OmOidcTokenRequest | false
+  }
+}
+
+/** Возвращает функцию, снимающую интерцептор */
+export declare function attachToken(instance: AxiosInstance, client: OmOidcClient): () => void

package/axios.js

@@ -0,0 +1,16 @@
+'use strict'
+
+function attachToken (instance, client) {
+  const id = instance.interceptors.request.use(async (config) => {
+    if (config.oidc) {
+      const { access_token: accessToken, token_type: tokenType } = await client.token(config.oidc)
+      if (tokenType !== 'Bearer') throw new Error(`Not Bearer token, token_type: ${tokenType}`)
+      config.headers.Authorization = `Bearer ${accessToken}`
+    }
+    return config
+  })
+  /** Возвращает функцию, убирающую интерцептор */
+  return () => instance.interceptors.request.eject(id)
+}
+
+module.exports = { attachToken }

package/cache.js

@@ -0,0 +1,69 @@
+'use strict'
+
+const crypto = require('crypto')
+
+const DEFAULT_MAX_ENTRIES = 500
+
+/**
+ * Хранит ответы `/token` до истечения их `expires_in`. Вытесняется то, чем дольше всех не
+ * пользовались: одноразовые токены обменов не должны выбивать из кэша тот, что нужен всем.
+ */
+function createTokenCache (maxEntries = DEFAULT_MAX_ENTRIES) {
+  const entries = new Map()
+  const pending = new Map()
+
+  return {
+    key: cacheKey,
+
+    get (key, minTtl) {
+      const entry = entries.get(key)
+      if (!entry) return undefined
+
+      const remaining = entry.expiresAt - Date.now()
+      if (remaining <= 0) {
+        entries.delete(key)
+        return undefined
+      }
+      if (remaining < minTtl * 1000) return undefined
+
+      // Обращение возвращает запись в конец очереди
+      entries.delete(key)
+      entries.set(key, entry)
+      return entry.value
+    },
+
+    issue (key, load) {
+      let promise = pending.get(key)
+      if (!promise) {
+        promise = load()
+          .then((value) => {
+            entries.delete(key)
+            if (entries.size >= maxEntries) entries.delete(entries.keys().next().value)
+            entries.set(key, { value, expiresAt: Date.now() + value.expires_in * 1000 })
+            return value
+          })
+          .finally(() => pending.delete(key))
+        pending.set(key, promise)
+      }
+      return promise
+    },
+
+    delete (key) {
+      entries.delete(key)
+    },
+
+    clear () {
+      entries.clear()
+    }
+  }
+}
+
+function cacheKey (request) {
+  const canonical = Object.entries(request)
+    .filter((entry) => entry[1])
+    .sort(([a], [b]) => (a < b ? -1 : 1))
+    .map(([name, value]) => [name, name === 'scope' ? value.split(/\s+/).filter(Boolean).sort().join(' ') : value])
+  return crypto.createHash('sha256').update(JSON.stringify(canonical)).digest('hex')
+}
+
+module.exports = { createTokenCache }

package/got.d.ts

@@ -0,0 +1,8 @@
+import type { ExtendOptions } from 'got'
+import type { OmOidcClient, OmOidcTokenRequest } from './index'
+
+/** Хуки для `got.extend()` */
+export declare function tokenHooks(client: OmOidcClient): ExtendOptions
+
+/** Опции запроса got с параметрами токена */
+export declare function withToken(request: OmOidcTokenRequest | false): { context: { oidc: OmOidcTokenRequest | false } }

package/got.js

@@ -0,0 +1,26 @@
+'use strict'
+
+/** Хуки для `got.extend()` */
+function tokenHooks (client) {
+  return {
+    hooks: {
+      beforeRequest: [
+        async (options) => {
+          const request = options.context.oidc
+          if (request) {
+            const { access_token: accessToken, token_type: tokenType } = await client.token(request)
+            if (tokenType !== 'Bearer') throw new Error(`Not Bearer token, token_type: ${tokenType}`)
+            options.headers.authorization = `Bearer ${accessToken}`
+          }
+        }
+      ]
+    }
+  }
+}
+
+/** Опции запроса got с параметрами токена */
+function withToken (request) {
+  return { context: { oidc: request } }
+}
+
+module.exports = { tokenHooks, withToken }

package/index.d.ts

@@ -0,0 +1,72 @@
+/** Автодополнение известных значений, но принимается любая строка (аналог LiteralUnion из type-fest) */
+type Known<T extends string> = T | (string & Record<never, never>)
+
+export interface OmOidcClientOptions {
+  /** Сервер авторизации, токены запрашиваются у `${authority}/token` */
+  authority: string
+  clientId: string
+  clientSecret: string
+  /** Минимальное время жизни токена для использования из кэша, в секундах. По умолчанию 60 */
+  minTtl?: number
+  /** Максимально количество записей в кэше. По умолчанию 500 */
+  maxEntries?: number
+}
+
+/** Гранты сервисных аккаунтов auth.ocenka.mobi; значение свободное — сервер знает и другие */
+export type OmOidcGrantType = Known<
+  | 'client_credentials'
+  | 'urn:ietf:params:oauth:grant-type:token-exchange'
+  | 'urn:ocenkamobi:params:oauth:grant-type:client-credentials-act'
+  | 'urn:ocenkamobi:params:oauth:grant-type:impersonation'
+>
+
+/** Идентификаторы типов токенов по RFC 8693 §3; значение свободное */
+export type OmOidcTokenType = Known<
+  | 'urn:ietf:params:oauth:token-type:access_token'
+  | 'urn:ocenkamobi:params:oauth:token-type:deferred_token'
+>
+
+/** Тело запроса к `/token` как есть: грант и параметры задаёт вызывающий */
+export interface OmOidcTokenRequest {
+  grant_type: OmOidcGrantType
+  resource?: string
+  audience?: string
+  scope?: string
+  subject?: string
+  subject_token?: string
+  subject_token_type?: OmOidcTokenType
+  actor_token?: string
+  actor_token_type?: OmOidcTokenType
+  requested_token_type?: OmOidcTokenType
+  [param: string]: string | undefined
+}
+
+export interface OmOidcTokenResponse {
+  access_token: string
+  token_type: string
+  expires_in: number
+  scope?: string
+  issued_token_type?: string
+}
+
+export interface OmOidcTokenOptions {
+  /** Переопределяет `minTtl` клиента для этого вызова */
+  minTtl?: number
+  /** Запросить новый токен, минуя кэш */
+  force?: boolean
+}
+
+export interface OmOidcClient {
+  token(request: OmOidcTokenRequest, options?: OmOidcTokenOptions): Promise<OmOidcTokenResponse>
+  invalidate(request: OmOidcTokenRequest): void
+  clear(): void
+}
+
+export declare class OmOidcTokenError extends Error {
+  readonly status: number
+  readonly error: string
+  readonly error_description?: string
+  constructor(status: number, error: string, error_description?: string)
+}
+
+export declare function createOmOidcClient(options: OmOidcClientOptions): OmOidcClient

package/index.js

@@ -0,0 +1,75 @@
+'use strict'
+
+const http = require('http')
+const https = require('https')
+const { createTokenCache } = require('./cache.js')
+
+const TIMEOUT = 10000
+
+class OmOidcTokenError extends Error {
+  constructor (status, error, errorDescription) {
+    super(errorDescription ? `${error}: ${errorDescription}` : error)
+    this.name = 'OmOidcTokenError'
+    this.status = status
+    this.error = error
+    this.error_description = errorDescription
+  }
+}
+
+function createOmOidcClient ({ authority, clientId, clientSecret, minTtl = 60, maxEntries }) {
+  const endpoint = `${authority.replace(/\/+$/, '')}/token`
+  // RFC 6749 §2.3.1: части кодируются как form-urlencoded до base64
+  const credentials = Buffer.from(`${encodeURIComponent(clientId)}:${encodeURIComponent(clientSecret)}`)
+  const authorization = `Basic ${credentials.toString('base64')}`
+  const cache = createTokenCache(maxEntries)
+
+  async function request (req) {
+    const body = new URLSearchParams(Object.entries(req).filter((entry) => entry[1])).toString()
+    const res = await post(endpoint, {
+      authorization,
+      'content-type': 'application/x-www-form-urlencoded',
+      'content-length': Buffer.byteLength(body)
+    }, body)
+    let data = {}
+    try {
+      data = JSON.parse(res.text)
+    } catch (e) {}
+    if (res.status !== 200 || !data.access_token) {
+      throw new OmOidcTokenError(res.status, data.error || 'invalid_response', data.error_description)
+    }
+    return data
+  }
+
+  return {
+    async token (req, options = {}) {
+      const key = cache.key(req)
+      const ttl = options.minTtl != null ? options.minTtl : minTtl
+      const cached = options.force ? undefined : cache.get(key, ttl)
+      return cached || cache.issue(key, () => request(req))
+    },
+    invalidate (req) {
+      cache.delete(cache.key(req))
+    },
+    clear () {
+      cache.clear()
+    }
+  }
+}
+
+function post (url, headers, body) {
+  return new Promise((resolve, reject) => {
+    const client = url.startsWith('http:') ? http : https
+    const req = client.request(url, { method: 'POST', headers }, (res) => {
+      let text = ''
+      res.setEncoding('utf8')
+      res.on('data', (chunk) => { text += chunk })
+      res.on('end', () => resolve({ status: res.statusCode, text }))
+      res.on('error', reject)
+    })
+    req.setTimeout(TIMEOUT, () => req.destroy(new Error(`Таймаут запроса к ${url}`)))
+    req.on('error', reject)
+    req.end(body)
+  })
+}
+
+module.exports = { createOmOidcClient, OmOidcTokenError }

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@ocenkamobi/om-oidc-client-cjs",
+  "version": "0.1.0",
+  "description": "Клиент сервисных аккаунтов auth.ocenka.mobi с кэшем токенов — CommonJS для Node 12",
+  "homepage": "https://gitlab.com/om-misc/om-oidc-client-cjs#readme",
+  "bugs": {
+    "url": "https://gitlab.com/om-misc/om-oidc-client-cjs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.com/om-misc/om-oidc-client-cjs.git"
+  },
+  "license": "UNLICENSED",
+  "author": {
+    "name": "@isjs",
+    "email": "stas@isjs.ru"
+  },
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "engines": {
+    "node": ">=12"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./axios": {
+      "types": "./axios.d.ts",
+      "default": "./axios.js"
+    },
+    "./got": {
+      "types": "./got.d.ts",
+      "default": "./got.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "cache.js",
+    "axios.js",
+    "axios.d.ts",
+    "got.js",
+    "got.d.ts"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:node12": "docker run --rm -v \"$PWD\":/app -w /app node:12-alpine node test/node12.js"
+  },
+  "peerDependencies": {
+    "axios": ">=0.21",
+    "got": "11"
+  },
+  "peerDependenciesMeta": {
+    "axios": {
+      "optional": true
+    },
+    "got": {
+      "optional": true
+    }
+  },
+  "packageManager": "pnpm@11.11.0",
+  "devDependencies": {
+    "axios": "^1.20.0",
+    "got": "^11.8.6",
+    "vitest": "^4.1.11"
+  }
+}