Skip to content

Commit 66d69bc

Browse files
polRkpolRk
committed
Add EnvironCredentialsProvider for env-based auth detection
1 parent 0f39a53 commit 66d69bc

File tree

30 files changed

+3880
-2145
lines changed

30 files changed

+3880
-2145
lines changed

‎.changeset/environ-credentials-provider.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@ydbjs/auth': minor
3+
---
4+
5+
Add EnvironCredentialsProvider that auto-detects authentication method from environment variables (YDB_ANONYMOUS_CREDENTIALS, YDB_METADATA_CREDENTIALS, YDB_ACCESS_TOKEN_CREDENTIALS, YDB_STATIC_CREDENTIALS_USER) and TLS configuration (YDB_SSL_ROOT_CERTIFICATES_FILE, YDB_SSL_CERTIFICATE_FILE, YDB_SSL_PRIVATE_KEY_FILE or their PEM string variants). Exported from `@ydbjs/auth/environ`.

‎docs/guide/core.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,39 @@ const driver = new Driver('grpc://localhost:2136/local', {
8686
await driver.ready()
8787
```
8888

89+
### 5) Environment-Based Auto-Detection
90+
91+
`EnvironCredentialsProvider` reads environment variables and picks the right auth strategy automatically. It also detects TLS configuration.
92+
93+
```ts
94+
import { Driver } from '@ydbjs/core'
95+
import { EnvironCredentialsProvider } from '@ydbjs/auth/environ'
96+
97+
let cs = process.env['YDB_CONNECTION_STRING']!
98+
let creds = new EnvironCredentialsProvider(cs)
99+
100+
const driver = new Driver(cs, {
101+
credentialsProvider: creds,
102+
secureOptions: creds.secureOptions,
103+
})
104+
await driver.ready()
105+
```
106+
107+
Detection priority (first match wins):
108+
109+
| Variable | Description |
110+
| ----------------------------------- | ------------------------------------------------------- |
111+
| `YDB_ANONYMOUS_CREDENTIALS=1` | Anonymous |
112+
| `YDB_METADATA_CREDENTIALS=1` | Cloud metadata |
113+
| `YDB_METADATA_CREDENTIALS_ENDPOINT` | Custom metadata endpoint (default: GCE metadata) |
114+
| `YDB_METADATA_CREDENTIALS_FLAVOR` | Custom metadata flavor (default: `Google`) |
115+
| `YDB_ACCESS_TOKEN_CREDENTIALS` | Access token |
116+
| `YDB_STATIC_CREDENTIALS_USER` | Username for static auth |
117+
| `YDB_STATIC_CREDENTIALS_PASSWORD` | Password (default: empty) |
118+
| `YDB_STATIC_CREDENTIALS_ENDPOINT` | Auth endpoint (default: derived from connection string) |
119+
120+
TLS is configured via `YDB_SSL_ROOT_CERTIFICATES_FILE` (or `YDB_SSL_ROOT_CERTIFICATES` for PEM string), `YDB_SSL_CERTIFICATE_FILE` / `YDB_SSL_CERTIFICATE`, `YDB_SSL_PRIVATE_KEY_FILE` / `YDB_SSL_PRIVATE_KEY`.
121+
89122
## TLS and mTLS in Driver
90123

91124
Pass `secureOptions` (Node.js `tls.SecureContextOptions`). For `grpcs://...`, system CA store is used by default; `secureOptions` lets you provide custom roots/certificates.

‎docs/package.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
{
22
"name": "@ydbjs/docs",
3-
"type": "module",
43
"private": true,
4+
"type": "module",
5+
"publishConfig": {
6+
"access": "restricted"
7+
},
58
"scripts": {
69
"dev": "vitepress dev .",
710
"build": "vitepress build .",
@@ -10,8 +13,5 @@
1013
},
1114
"devDependencies": {
1215
"vitepress": "^1.6.4"
13-
},
14-
"publishConfig": {
15-
"access": "restricted"
1616
}
1717
}

‎docs/ru/guide/core.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,39 @@ const driver = new Driver('grpc://localhost:2136/local', {
8686
await driver.ready()
8787
```
8888

89+
### 5) Автоопределение из переменных окружения
90+
91+
`EnvironCredentialsProvider` читает переменные окружения и автоматически выбирает нужный метод аутентификации. Также определяет TLS-конфигурацию.
92+
93+
```ts
94+
import { Driver } from '@ydbjs/core'
95+
import { EnvironCredentialsProvider } from '@ydbjs/auth/environ'
96+
97+
let cs = process.env['YDB_CONNECTION_STRING']!
98+
let creds = new EnvironCredentialsProvider(cs)
99+
100+
const driver = new Driver(cs, {
101+
credentialsProvider: creds,
102+
secureOptions: creds.secureOptions,
103+
})
104+
await driver.ready()
105+
```
106+
107+
Приоритет определения (первое совпадение):
108+
109+
| Переменная | Описание |
110+
| ----------------------------------- | ------------------------------------------------------------- |
111+
| `YDB_ANONYMOUS_CREDENTIALS=1` | Anonymous |
112+
| `YDB_METADATA_CREDENTIALS=1` | Cloud metadata |
113+
| `YDB_METADATA_CREDENTIALS_ENDPOINT` | Кастомный endpoint метадаты (по умолчанию: GCE metadata) |
114+
| `YDB_METADATA_CREDENTIALS_FLAVOR` | Кастомный flavor метадаты (по умолчанию: `Google`) |
115+
| `YDB_ACCESS_TOKEN_CREDENTIALS` | Access token |
116+
| `YDB_STATIC_CREDENTIALS_USER` | Имя пользователя для static auth |
117+
| `YDB_STATIC_CREDENTIALS_PASSWORD` | Пароль (по умолчанию: пустая строка) |
118+
| `YDB_STATIC_CREDENTIALS_ENDPOINT` | Endpoint аутентификации (по умолчанию: из строки подключения) |
119+
120+
TLS настраивается через `YDB_SSL_ROOT_CERTIFICATES_FILE` (или `YDB_SSL_ROOT_CERTIFICATES` для PEM-строки), `YDB_SSL_CERTIFICATE_FILE` / `YDB_SSL_CERTIFICATE`, `YDB_SSL_PRIVATE_KEY_FILE` / `YDB_SSL_PRIVATE_KEY`.
121+
89122
## TLS и mTLS в Driver
90123

91124
Передайте `secureOptions` (Node.js `tls.SecureContextOptions`). Если строка подключения `grpcs://...`, по умолчанию используется системное хранилище CA; `secureOptions` позволяет указать свои корни/сертификаты.

‎e2e/package.json‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,9 @@
33
"version": "0.0.0",
44
"private": true,
55
"type": "module",
6-
"engines": {
7-
"node": ">=20.19.0",
8-
"npm": ">=10"
6+
"publishConfig": {
7+
"access": "restricted"
98
},
10-
"engineStrict": true,
119
"scripts": {
1210
"test": "vitest --run --project e2e",
1311
"test:debug": "FORCE_COLOR=3 DEBUG_COLORS=1 DEBUG=ydbjs:* vitest --project e2e --inspect --no-file-parallelism"
@@ -24,7 +22,9 @@
2422
"@ydbjs/topic": "*",
2523
"@ydbjs/value": "*"
2624
},
27-
"publishConfig": {
28-
"access": "restricted"
29-
}
25+
"engines": {
26+
"node": ">=20.19.0",
27+
"npm": ">=10"
28+
},
29+
"engineStrict": true
3030
}

‎examples/api/package.json‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,9 @@
33
"version": "6.0.0",
44
"private": true,
55
"type": "module",
6-
"engines": {
7-
"node": ">=20.19.0",
8-
"npm": ">=10"
6+
"publishConfig": {
7+
"access": "restricted"
98
},
10-
"engineStrict": true,
119
"scripts": {
1210
"start": "node index.js",
1311
"dev": "DEBUG=ydbjs:* node index.js"
@@ -18,7 +16,9 @@
1816
"@ydbjs/auth": "^6.0.0",
1917
"@ydbjs/core": "^6.0.7"
2018
},
21-
"publishConfig": {
22-
"access": "restricted"
23-
}
19+
"engines": {
20+
"node": ">=20.19.0",
21+
"npm": ">=10"
22+
},
23+
"engineStrict": true
2424
}

‎examples/auth-yandex-cloud/package.json‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,11 @@
22
"name": "@ydbjs/examples-auth-yandex-cloud",
33
"version": "6.0.0",
44
"private": true,
5-
"type": "module",
65
"description": "Example of YDB connection using Yandex Cloud IAM authentication",
7-
"engines": {
8-
"node": ">=20.19.0",
9-
"npm": ">=10"
6+
"type": "module",
7+
"publishConfig": {
8+
"access": "restricted"
109
},
11-
"engineStrict": true,
1210
"scripts": {
1311
"start": "node index.js",
1412
"dev": "DEBUG=ydbjs:* node index.js"
@@ -18,7 +16,9 @@
1816
"@ydbjs/core": "^6.0.7",
1917
"@ydbjs/query": "^6.0.7"
2018
},
21-
"publishConfig": {
22-
"access": "restricted"
23-
}
19+
"engines": {
20+
"node": ">=20.19.0",
21+
"npm": ">=10"
22+
},
23+
"engineStrict": true
2424
}

‎examples/environ/README.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Environment-based Authentication Example
2+
3+
This example demonstrates how to use `EnvironCredentialsProvider` to auto-detect the authentication method and TLS configuration from environment variables.
4+
5+
## Usage
6+
7+
```bash
8+
# Anonymous (local YDB)
9+
YDB_CONNECTION_STRING=grpc://localhost:2136/local npm start
10+
11+
# Static credentials (on-premises)
12+
YDB_CONNECTION_STRING=grpcs://ydb.example.com:2135/mydb \
13+
YDB_STATIC_CREDENTIALS_USER=admin \
14+
YDB_STATIC_CREDENTIALS_PASSWORD=secret \
15+
YDB_SSL_ROOT_CERTIFICATES_FILE=/path/to/ca.pem \
16+
npm start
17+
18+
# Access token
19+
YDB_CONNECTION_STRING=grpcs://ydb.example.com:2135/mydb \
20+
YDB_ACCESS_TOKEN_CREDENTIALS=my-token \
21+
npm start
22+
23+
# Metadata (cloud VM)
24+
YDB_CONNECTION_STRING=grpcs://ydb.example.com:2135/mydb \
25+
YDB_METADATA_CREDENTIALS=1 \
26+
npm start
27+
```
28+
29+
## Environment Variables
30+
31+
### Credentials (first match wins)
32+
33+
| Variable | Description |
34+
| ----------------------------------- | ------------------------------------------------------- |
35+
| `YDB_ANONYMOUS_CREDENTIALS=1` | Anonymous access |
36+
| `YDB_METADATA_CREDENTIALS=1` | Cloud metadata token |
37+
| `YDB_METADATA_CREDENTIALS_ENDPOINT` | Custom metadata endpoint (default: GCE metadata) |
38+
| `YDB_METADATA_CREDENTIALS_FLAVOR` | Custom metadata flavor (default: `Google`) |
39+
| `YDB_ACCESS_TOKEN_CREDENTIALS` | Direct access token |
40+
| `YDB_STATIC_CREDENTIALS_USER` | Username for static auth |
41+
| `YDB_STATIC_CREDENTIALS_PASSWORD` | Password (default: empty) |
42+
| `YDB_STATIC_CREDENTIALS_ENDPOINT` | Auth endpoint (default: derived from connection string) |
43+
44+
### TLS (file path or PEM string)
45+
46+
| File variant | String variant | Description |
47+
| -------------------------------- | --------------------------- | ------------------ |
48+
| `YDB_SSL_ROOT_CERTIFICATES_FILE` | `YDB_SSL_ROOT_CERTIFICATES` | CA certificate |
49+
| `YDB_SSL_CERTIFICATE_FILE` | `YDB_SSL_CERTIFICATE` | Client certificate |
50+
| `YDB_SSL_PRIVATE_KEY_FILE` | `YDB_SSL_PRIVATE_KEY` | Client private key |
51+
52+
`NODE_EXTRA_CA_CERTS` is also supported as a CA file path fallback.

‎examples/environ/index.js‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
import { Driver } from '@ydbjs/core'
2+
import { EnvironCredentialsProvider } from '@ydbjs/auth/environ'
3+
import { DiscoveryServiceDefinition } from '@ydbjs/api/discovery'
4+
5+
let cs = process.env.YDB_CONNECTION_STRING
6+
if (!cs) throw new Error('YDB_CONNECTION_STRING is required')
7+
8+
// Auto-detect auth method and TLS from environment variables.
9+
//
10+
// Credentials (first match wins):
11+
// YDB_ANONYMOUS_CREDENTIALS=1
12+
// YDB_METADATA_CREDENTIALS=1 (+ YDB_METADATA_CREDENTIALS_ENDPOINT, YDB_METADATA_CREDENTIALS_FLAVOR)
13+
// YDB_ACCESS_TOKEN_CREDENTIALS=<token>
14+
// YDB_STATIC_CREDENTIALS_USER=<user> (+ YDB_STATIC_CREDENTIALS_PASSWORD, YDB_STATIC_CREDENTIALS_ENDPOINT)
15+
//
16+
// TLS (file path or PEM string):
17+
// YDB_SSL_ROOT_CERTIFICATES_FILE / YDB_SSL_ROOT_CERTIFICATES
18+
// YDB_SSL_CERTIFICATE_FILE / YDB_SSL_CERTIFICATE
19+
// YDB_SSL_PRIVATE_KEY_FILE / YDB_SSL_PRIVATE_KEY
20+
let creds = new EnvironCredentialsProvider(cs)
21+
22+
let driver = new Driver(cs, {
23+
credentialsProvider: creds,
24+
secureOptions: creds.secureOptions,
25+
})
26+
27+
await driver.ready()
28+
console.log('Connected to', cs)
29+
30+
let discovery = driver.createClient(DiscoveryServiceDefinition)
31+
let resp = await discovery.listEndpoints({ database: driver.database })
32+
console.log('Endpoints status:', resp.status)
33+
34+
driver.close()
35+
console.log('Done')

‎examples/environ/package.json‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"name": "@ydbjs/examples-environ",
3+
"version": "6.0.0",
4+
"private": true,
5+
"type": "module",
6+
"publishConfig": {
7+
"access": "restricted"
8+
},
9+
"scripts": {
10+
"start": "node index.js",
11+
"dev": "DEBUG=ydbjs:* node index.js"
12+
},
13+
"dependencies": {
14+
"@ydbjs/api": "^6.0.0",
15+
"@ydbjs/auth": "^6.0.5",
16+
"@ydbjs/core": "^6.0.7"
17+
},
18+
"engines": {
19+
"node": ">=20.19.0",
20+
"npm": ">=10"
21+
},
22+
"engineStrict": true
23+
}

0 commit comments

Comments
 (0)