@ocenkamobi/om-oidc-client 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# @ocenkamobi/om-oidc-client
+
+Клиент сервисных аккаунтов auth.ocenka.mobi для серверов на Node 20+. Делает
+две вещи: аутентифицирует запрос к `/token` через `client_secret_basic` и
+кэширует ответ — одинаковый запрос получает тот же токен, пока тот не начнёт
+истекать.
+
+Библиотека отвечает за авторизацию сервисных аккаунтов — про реализацию грантов
+в [auth.ocenka.mobi](https://gitlab.com/ocenkamobi/auth.ocenka.mobi/-/blob/main/docs/README.md)
+ничего не знает.
+
+Для CommonJS и Node 12 —
+[`@ocenkamobi/om-oidc-client-cjs`](https://gitlab.com/om-misc/om-oidc-client-cjs).
+
+## Подключение
+
+```sh
+npm i @ocenkamobi/om-oidc-client
+```
+
+```ts
+import { createOmOidcClient } from '@ocenkamobi/om-oidc-client'
+
+export const oidc = createOmOidcClient({
+  authority: 'https://auth.ocenka.mobi',
+  clientId: process.env.CLIENT_ID!,
+  clientSecret: process.env.CLIENT_SECRET!,
+})
+
+const { access_token } = 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`.
+- Одновременные одинаковые запросы делают один сетевой вызов.
+- Из кэша вытесняются токены, которыми не пользуются: каждое чтение токена из
+  кэша поднимает его.
+- Ошибки не кэшируются.
+
+```ts
+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 секунд.
+
+## axios
+
+```ts
+import axios from 'axios'
+import { attachToken } from '@ocenkamobi/om-oidc-client/axios'
+
+const api = axios.create()
+attachToken(api, oidc)
+
+await api.get('https://express.ocenka.mobi/api/reports', {
+  oidc: { grant_type: 'client_credentials', resource: 'https://express.ocenka.mobi' },
+})
+```
+
+Токен ставится только запросам с `oidc` — без него заголовок не появится.
+
+При необходимости параметры можно задать один раз: axios сливает конфиг инстанса
+с конфигом запроса, включая `oidc`.
+
+```ts
+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` возвращает функцию, снимающую интерцептор.
+
+## got
+
+```ts
+import got from 'got'
+import { tokenHooks, withToken } from '@ocenkamobi/om-oidc-client/got'
+
+const api = got.extend(tokenHooks(oidc))
+
+await api.get('https://express.ocenka.mobi/api/reports', withToken({
+  grant_type: 'client_credentials',
+  resource: 'https://express.ocenka.mobi',
+}))
+```
+
+`withToken()` кладёт параметры в `context` запроса. Без него токен не ставится.
+
+Дефолт для инстанса задаётся тем же `withToken()` вторым аргументом `extend`, а
+снимается `withToken(false)`:
+
+```ts
+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))
+```

package/dist/axios.d.ts

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

package/dist/axios.js

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

package/dist/cache.d.ts

@@ -0,0 +1,11 @@
+interface TokenCache<T> {
+    key(request: Record<string, string | undefined>): string;
+    get(key: string, minTtl: number): T | undefined;
+    issue(key: string, load: () => Promise<T>): Promise<T>;
+    delete(key: string): void;
+    clear(): void;
+}
+export declare function createTokenCache<T extends {
+    expires_in: number;
+}>(maxEntries?: number): TokenCache<T>;
+export {};

package/dist/cache.js

@@ -0,0 +1,53 @@
+import { createHash } from 'node:crypto';
+const DEFAULT_MAX_ENTRIES = 500;
+export function createTokenCache(maxEntries = DEFAULT_MAX_ENTRIES) {
+    const entries = new Map();
+    const pending = new Map();
+    return {
+        key(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 createHash('sha256').update(JSON.stringify(canonical)).digest('hex');
+        },
+        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();
+        },
+    };
+}

package/dist/got.d.ts

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

package/dist/got.js

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

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import type { LiteralUnion } from 'type-fest';
+export interface OmOidcClientOptions {
+    /** Сервер авторизации, токены запрашиваются у `${authority}/token` */
+    authority: string;
+    clientId: string;
+    clientSecret: string;
+    /** Минимальное время жизни токена для использования из кэша, в секундах. По умолчанию 60 */
+    minTtl?: number;
+    /** Максимально количество записей в кэше. По умолчанию 500 */
+    maxEntries?: number;
+}
+/** Гранты сервисных аккаунтов auth.ocenka.mobi; значение свободное — сервер знает и другие */
+export type OmOidcGrantType = LiteralUnion<'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', string>;
+/** Идентификаторы типов токенов по RFC 8693 §3; значение свободное */
+export type OmOidcTokenType = LiteralUnion<'urn:ietf:params:oauth:token-type:access_token' | 'urn:ocenkamobi:params:oauth:token-type:deferred_token', string>;
+/** Тело запроса к `/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 | undefined;
+    constructor(status: number, error: string, error_description?: string | undefined);
+}
+export declare function createOmOidcClient({ authority, clientId, clientSecret, minTtl, maxEntries }: OmOidcClientOptions): OmOidcClient;

package/dist/index.js

@@ -0,0 +1,46 @@
+import { createTokenCache } from './cache.js';
+export class OmOidcTokenError extends Error {
+    status;
+    error;
+    error_description;
+    constructor(status, error, error_description) {
+        super(error_description ? `${error}: ${error_description}` : error);
+        this.status = status;
+        this.error = error;
+        this.error_description = error_description;
+        this.name = 'OmOidcTokenError';
+    }
+}
+const TIMEOUT = 10_000;
+export 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 headers = {
+        authorization: `Basic ${credentials.toString('base64')}`,
+        'content-type': 'application/x-www-form-urlencoded',
+    };
+    const cache = createTokenCache(maxEntries);
+    async function request(req) {
+        const body = new URLSearchParams(Object.entries(req).filter((entry) => !!entry[1]));
+        const res = await fetch(endpoint, { method: 'POST', headers, body, signal: AbortSignal.timeout(TIMEOUT) });
+        const data = (await res.json().catch(() => ({})));
+        if (!res.ok || !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 cached = options.force ? undefined : cache.get(key, options.minTtl ?? minTtl);
+            return cached ?? cache.issue(key, () => request(req));
+        },
+        invalidate(req) {
+            cache.delete(cache.key(req));
+        },
+        clear() {
+            cache.clear();
+        },
+    };
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@ocenkamobi/om-oidc-client",
+  "version": "0.1.0",
+  "description": "Клиент сервисных аккаунтов auth.ocenka.mobi с кэшем токенов",
+  "homepage": "https://gitlab.com/om-misc/om-oidc-client#readme",
+  "bugs": {
+    "url": "https://gitlab.com/om-misc/om-oidc-client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.com/om-misc/om-oidc-client.git"
+  },
+  "license": "UNLICENSED",
+  "author": {
+    "name": "@isjs",
+    "email": "stas@isjs.ru"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./axios": {
+      "types": "./dist/axios.d.ts",
+      "import": "./dist/axios.js"
+    },
+    "./got": {
+      "types": "./dist/got.d.ts",
+      "import": "./dist/got.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "ts": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "axios": "^1",
+    "got": ">=12"
+  },
+  "peerDependenciesMeta": {
+    "axios": {
+      "optional": true
+    },
+    "got": {
+      "optional": true
+    }
+  },
+  "packageManager": "pnpm@11.11.0",
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "axios": "^1.20.0",
+    "got": "^14.6.6",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
+  },
+  "dependencies": {
+    "type-fest": "^5.9.0"
+  }
+}