@sourceregistry/openbao-js 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1740 @@
1
+ /** HTTP methods understood by OpenBao. `LIST` and `SCAN` are OpenBao-specific verbs. */
2
+ type HttpMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'LIST' | 'SCAN';
3
+ /** A duration accepted by OpenBao: seconds as a number, or a Go duration string such as `"1h30m"`. */
4
+ type Duration = string | number;
5
+ /** Query-string values. Arrays are serialized as repeated keys; `undefined` values are dropped. */
6
+ type QueryValue = string | number | boolean | undefined | null | ReadonlyArray<string | number>;
7
+ type Query = Record<string, QueryValue>;
8
+ /** Response-wrapping information returned when a request was made with a wrap TTL. */
9
+ interface WrapInfo {
10
+ token: string;
11
+ accessor: string;
12
+ ttl: number;
13
+ creation_time: string;
14
+ creation_path: string;
15
+ wrapped_accessor?: string;
16
+ }
17
+ /** The `auth` block returned by login endpoints and token creation. */
18
+ interface AuthInfo {
19
+ client_token: string;
20
+ accessor: string;
21
+ policies: string[];
22
+ token_policies: string[];
23
+ identity_policies?: string[];
24
+ metadata: Record<string, string> | null;
25
+ lease_duration: number;
26
+ renewable: boolean;
27
+ entity_id: string;
28
+ token_type: 'service' | 'batch' | (string & {});
29
+ orphan: boolean;
30
+ num_uses?: number;
31
+ mfa_requirement?: unknown;
32
+ }
33
+ /** The standard OpenBao response envelope. */
34
+ interface ApiResponse<T = Record<string, unknown>> {
35
+ request_id: string;
36
+ lease_id: string;
37
+ renewable: boolean;
38
+ lease_duration: number;
39
+ data: T;
40
+ wrap_info: WrapInfo | null;
41
+ warnings: string[] | null;
42
+ auth: AuthInfo | null;
43
+ mount_type?: string;
44
+ }
45
+ /** Shape of `data` returned by LIST / SCAN operations. */
46
+ interface ListData<Info = unknown> {
47
+ keys: string[];
48
+ key_info?: Record<string, Info>;
49
+ }
50
+ /** Pagination options supported by OpenBao LIST endpoints. */
51
+ interface ListOptions {
52
+ /** Return keys lexicographically after this one. */
53
+ after?: string;
54
+ /** Maximum number of keys to return (0 = all). */
55
+ limit?: number;
56
+ }
57
+ /** Options shared by every request helper. */
58
+ interface CallOptions {
59
+ /** Override the client namespace for this call (`null` sends no namespace header). */
60
+ namespace?: string | null;
61
+ /** Override the client token for this call (`null` sends no token). */
62
+ token?: string | null;
63
+ /** Ask OpenBao to wrap the response in a cubbyhole token with this TTL. */
64
+ wrapTTL?: Duration;
65
+ /** Abort signal for this call. */
66
+ signal?: AbortSignal;
67
+ /** Extra headers for this call. */
68
+ headers?: Record<string, string>;
69
+ }
70
+ /** Options accepted by login helpers. */
71
+ interface LoginOptions extends Pick<CallOptions, 'namespace' | 'signal' | 'headers'> {
72
+ /**
73
+ * Store the returned client token on the client so subsequent calls are authenticated.
74
+ * @default true
75
+ */
76
+ setToken?: boolean;
77
+ }
78
+ /** Common token-related tunables used by most auth-method role definitions. */
79
+ interface TokenFields {
80
+ token_ttl?: Duration;
81
+ token_max_ttl?: Duration;
82
+ token_policies?: string[];
83
+ token_bound_cidrs?: string[];
84
+ token_explicit_max_ttl?: Duration;
85
+ token_no_default_policy?: boolean;
86
+ token_num_uses?: number;
87
+ token_period?: Duration;
88
+ token_type?: 'service' | 'batch' | 'default' | 'default-service' | 'default-batch';
89
+ }
90
+
91
+ type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
92
+ interface RetryOptions {
93
+ /** Maximum retry attempts after the first try. @default 2 */
94
+ retries?: number;
95
+ /** Initial backoff in milliseconds (doubled each attempt, with jitter). @default 250 */
96
+ minDelay?: number;
97
+ /** Upper bound for backoff in milliseconds. @default 5000 */
98
+ maxDelay?: number;
99
+ /**
100
+ * Status codes retried for every method. 412 is returned by performance
101
+ * standbys that have not caught up yet; 429/503 mean the request was rejected
102
+ * before processing. @default [412, 429, 503]
103
+ */
104
+ statusCodes?: number[];
105
+ }
106
+ interface OpenBaoOptions {
107
+ /** Server address, e.g. `https://bao.example.com:8200`. Falls back to `BAO_ADDR` / `VAULT_ADDR`, then `http://127.0.0.1:8200`. */
108
+ address?: string;
109
+ /** Client token. Falls back to `BAO_TOKEN` / `VAULT_TOKEN`. */
110
+ token?: string;
111
+ /** Namespace sent as `X-Vault-Namespace`. Falls back to `BAO_NAMESPACE` / `VAULT_NAMESPACE`. */
112
+ namespace?: string;
113
+ /** Extra headers sent with every request. */
114
+ headers?: Record<string, string>;
115
+ /** Per-request timeout in milliseconds (0 disables). @default 60000 */
116
+ timeout?: number;
117
+ /** Retry policy, or `false` to disable retries. */
118
+ retry?: RetryOptions | false;
119
+ /** Custom fetch implementation (defaults to global `fetch`). */
120
+ fetch?: FetchLike;
121
+ /**
122
+ * Extra `RequestInit` fields merged into every request. Use this to pass an
123
+ * undici `dispatcher` for custom TLS (CA bundle, client certificates):
124
+ *
125
+ * ```ts
126
+ * import { Agent } from 'undici';
127
+ * new OpenBao({ requestInit: { dispatcher: new Agent({ connect: { ca } }) } });
128
+ * ```
129
+ */
130
+ requestInit?: RequestInit & Record<string, unknown>;
131
+ /** Send `X-Vault-Request: true` (required by proxies with `require_request_header`). @default true */
132
+ requestHeader?: boolean;
133
+ /** Read address/token/namespace from environment variables when not given. @default true */
134
+ useEnv?: boolean;
135
+ }
136
+ interface RequestOptions extends CallOptions {
137
+ method: HttpMethod;
138
+ /** API path relative to `/v1/`, e.g. `secret/data/foo`. */
139
+ path: string;
140
+ query?: Query;
141
+ body?: unknown;
142
+ /** Override the request content type (defaults to `application/json` when a body is present). */
143
+ contentType?: string;
144
+ /** Extra non-2xx statuses that should be treated as success (e.g. for `sys/health`). */
145
+ acceptStatus?: number[];
146
+ /** How to decode the response body. @default 'json' */
147
+ responseType?: 'json' | 'text';
148
+ }
149
+ interface ResolvedConfig {
150
+ address: string;
151
+ token: string | undefined;
152
+ namespace: string | undefined;
153
+ headers: Record<string, string>;
154
+ timeout: number;
155
+ retry: Required<RetryOptions> | false;
156
+ fetch: FetchLike;
157
+ requestInit: (RequestInit & Record<string, unknown>) | undefined;
158
+ requestHeader: boolean;
159
+ }
160
+ /**
161
+ * Low-level HTTP client. Handles auth headers, namespaces, response wrapping,
162
+ * timeouts, retries and error decoding. {@link OpenBao} builds the typed API on top.
163
+ */
164
+ declare class OpenBaoCore {
165
+ /** @internal */
166
+ protected readonly config: ResolvedConfig;
167
+ constructor(options?: OpenBaoOptions);
168
+ /** Base server address (without `/v1`). */
169
+ get address(): string;
170
+ /** Current client token. Login helpers update this automatically. */
171
+ get token(): string | undefined;
172
+ set token(value: string | undefined);
173
+ /** Current namespace. */
174
+ get namespace(): string | undefined;
175
+ set namespace(value: string | undefined);
176
+ /** Sends a request and returns the decoded body (`undefined` for 204 No Content). */
177
+ request<T = unknown>(opts: RequestOptions): Promise<T>;
178
+ /** `GET` a path and return the full response envelope. Throws {@link OpenBaoError} (404) when missing. */
179
+ read<T = Record<string, unknown>>(path: string, opts?: CallOptions & {
180
+ query?: Query;
181
+ }): Promise<ApiResponse<T>>;
182
+ /** `POST` data to a path. Resolves to `undefined` when the server answers 204. */
183
+ write<T = Record<string, unknown>>(path: string, data?: Record<string, unknown> | object, opts?: CallOptions & {
184
+ query?: Query;
185
+ }): Promise<ApiResponse<T> | undefined>;
186
+ /** JSON merge-patch a path (`PATCH` with `application/merge-patch+json`). */
187
+ patch<T = Record<string, unknown>>(path: string, data: Record<string, unknown> | object, opts?: CallOptions): Promise<ApiResponse<T> | undefined>;
188
+ /** `DELETE` a path. */
189
+ delete<T = Record<string, unknown>>(path: string, opts?: CallOptions & {
190
+ query?: Query;
191
+ }): Promise<ApiResponse<T> | undefined>;
192
+ /**
193
+ * `LIST` a path. Returns `{ keys: [] }` when nothing exists (OpenBao answers 404 for empty lists).
194
+ */
195
+ list<Info = unknown>(path: string, opts?: CallOptions & ListOptions): Promise<ListData<Info>>;
196
+ /** Recursive `SCAN` of a path (OpenBao-specific). Returns `{ keys: [] }` when nothing exists. */
197
+ scan<Info = unknown>(path: string, opts?: CallOptions & ListOptions): Promise<ListData<Info>>;
198
+ private listLike;
199
+ private buildHeaders;
200
+ private parseBody;
201
+ private createSignal;
202
+ private backoff;
203
+ }
204
+
205
+ /**
206
+ * Many `sys/*` endpoints return their payload both at the top level and in
207
+ * `data`; others only at the top level. This picks whichever is present.
208
+ */
209
+ declare function unwrapData<T>(res: unknown): T;
210
+ /** Base for engines and auth methods that live at a configurable mount path. */
211
+ declare abstract class MountedApi {
212
+ protected readonly client: OpenBaoCore;
213
+ /** Mount path without surrounding slashes, e.g. `secret` or `auth/approle`. */
214
+ readonly mount: string;
215
+ constructor(client: OpenBaoCore, mount: string);
216
+ /** Builds `<mount>/<...segments>` with each segment URL-encoded. */
217
+ protected path(...segments: Array<string | number | undefined>): string;
218
+ }
219
+ /** Base for auth methods: performs a login and (by default) stores the token on the client. */
220
+ declare abstract class AuthMethodApi extends MountedApi {
221
+ constructor(client: OpenBaoCore, mount: string);
222
+ /** @internal */
223
+ protected doLogin(path: string, body: Record<string, unknown>, opts?: LoginOptions): Promise<AuthInfo>;
224
+ }
225
+ /**
226
+ * A named collection of configuration objects under one base path — e.g.
227
+ * `pki/roles/:name`, `database/static-roles/:name`, `auth/approle/role/:name`.
228
+ */
229
+ declare class Resource<TRead = Record<string, unknown>, TWrite extends object = Partial<TRead> & Record<string, unknown>> {
230
+ protected readonly client: OpenBaoCore;
231
+ /** Base path of the collection, e.g. `pki/roles`. */
232
+ readonly basePath: string;
233
+ constructor(client: OpenBaoCore,
234
+ /** Base path of the collection, e.g. `pki/roles`. */
235
+ basePath: string);
236
+ /** Lists item names. Returns `[]` when the collection is empty. */
237
+ list(opts?: CallOptions & ListOptions): Promise<string[]>;
238
+ /** Reads an item. Throws `OpenBaoError` (404) when it does not exist. */
239
+ read(name: string, opts?: CallOptions): Promise<TRead>;
240
+ /** Creates or updates an item. */
241
+ write(name: string, data: TWrite, opts?: CallOptions): Promise<void>;
242
+ delete(name: string, opts?: CallOptions): Promise<void>;
243
+ /** `true` when the item exists. */
244
+ exists(name: string, opts?: CallOptions): Promise<boolean>;
245
+ }
246
+
247
+ interface CreateTokenOptions {
248
+ id?: string;
249
+ role_name?: string;
250
+ policies?: string[];
251
+ meta?: Record<string, string>;
252
+ no_parent?: boolean;
253
+ no_default_policy?: boolean;
254
+ renewable?: boolean;
255
+ ttl?: Duration;
256
+ type?: 'service' | 'batch';
257
+ explicit_max_ttl?: Duration;
258
+ display_name?: string;
259
+ num_uses?: number;
260
+ period?: Duration;
261
+ entity_alias?: string;
262
+ }
263
+ interface TokenLookup {
264
+ accessor: string;
265
+ creation_time: number;
266
+ creation_ttl: number;
267
+ display_name: string;
268
+ entity_id: string;
269
+ expire_time: string | null;
270
+ explicit_max_ttl: number;
271
+ id: string;
272
+ issue_time?: string;
273
+ meta: Record<string, string> | null;
274
+ num_uses: number;
275
+ orphan: boolean;
276
+ path: string;
277
+ policies: string[];
278
+ identity_policies?: string[];
279
+ renewable: boolean;
280
+ ttl: number;
281
+ type: 'service' | 'batch';
282
+ [key: string]: unknown;
283
+ }
284
+ interface TokenRole {
285
+ allowed_policies?: string[];
286
+ disallowed_policies?: string[];
287
+ allowed_policies_glob?: string[];
288
+ disallowed_policies_glob?: string[];
289
+ orphan?: boolean;
290
+ renewable?: boolean;
291
+ path_suffix?: string;
292
+ allowed_entity_aliases?: string[];
293
+ token_period?: Duration;
294
+ [key: string]: unknown;
295
+ }
296
+ /** Token auth method (`auth/token`). Always mounted, cannot be moved. */
297
+ declare class TokenAuth extends MountedApi {
298
+ /** Token roles (`auth/token/roles/:name`). */
299
+ readonly roles: Resource<TokenRole & TokenFields, TokenRole & TokenFields>;
300
+ constructor(client: OpenBaoCore);
301
+ /**
302
+ * Creates a token. Does **not** change the client's token — use
303
+ * `bao.withToken(auth.client_token)` to act as it.
304
+ */
305
+ create(options?: CreateTokenOptions, opts?: CallOptions): Promise<AuthInfo>;
306
+ /** Creates an orphan token (no parent). */
307
+ createOrphan(options?: Omit<CreateTokenOptions, 'role_name' | 'no_parent'>, opts?: CallOptions): Promise<AuthInfo>;
308
+ /** Looks up the client's own token. */
309
+ lookupSelf(opts?: CallOptions): Promise<TokenLookup>;
310
+ lookup(token: string, opts?: CallOptions): Promise<TokenLookup>;
311
+ lookupAccessor(accessor: string, opts?: CallOptions): Promise<TokenLookup>;
312
+ /** Renews the client's own token. */
313
+ renewSelf(increment?: Duration, opts?: CallOptions): Promise<AuthInfo>;
314
+ renew(token: string, increment?: Duration, opts?: CallOptions): Promise<AuthInfo>;
315
+ renewAccessor(accessor: string, increment?: Duration, opts?: CallOptions): Promise<AuthInfo>;
316
+ /** Revokes the client's own token and clears it from the client. */
317
+ revokeSelf(opts?: CallOptions): Promise<void>;
318
+ revoke(token: string, opts?: CallOptions): Promise<void>;
319
+ revokeAccessor(accessor: string, opts?: CallOptions): Promise<void>;
320
+ /** Revokes a token but leaves its children as orphans. Requires `sudo`. */
321
+ revokeOrphan(token: string, opts?: CallOptions): Promise<void>;
322
+ /** Lists token accessors. Requires `sudo`. */
323
+ listAccessors(opts?: CallOptions & ListOptions): Promise<string[]>;
324
+ tidy(opts?: CallOptions): Promise<void>;
325
+ /**
326
+ * Keeps the client's token alive by renewing it at ~2/3 of its TTL.
327
+ * Returns a handle with `stop()`. Timers are `unref`'d so they never keep a
328
+ * Node.js process alive. Stops automatically when the token is not renewable
329
+ * or reaches its max TTL.
330
+ */
331
+ keepAlive(options?: {
332
+ increment?: Duration;
333
+ onRenew?: (auth: AuthInfo) => void;
334
+ onError?: (err: unknown) => void;
335
+ }): {
336
+ stop: () => void;
337
+ };
338
+ private authOf;
339
+ }
340
+ interface AppRoleRole extends TokenFields {
341
+ bind_secret_id?: boolean;
342
+ secret_id_bound_cidrs?: string[];
343
+ secret_id_num_uses?: number;
344
+ secret_id_ttl?: Duration;
345
+ local_secret_ids?: boolean;
346
+ [key: string]: unknown;
347
+ }
348
+ interface SecretIdOptions {
349
+ metadata?: Record<string, string>;
350
+ cidr_list?: string[];
351
+ token_bound_cidrs?: string[];
352
+ num_uses?: number;
353
+ ttl?: Duration;
354
+ }
355
+ interface GeneratedSecretId {
356
+ secret_id: string;
357
+ secret_id_accessor: string;
358
+ secret_id_ttl: number;
359
+ secret_id_num_uses: number;
360
+ }
361
+ /** AppRole auth method — machine authentication with `role_id` + `secret_id`. */
362
+ declare class AppRoleAuth extends AuthMethodApi {
363
+ /** Role definitions (`auth/<mount>/role/:name`). */
364
+ readonly roles: Resource<AppRoleRole, AppRoleRole>;
365
+ constructor(client: OpenBaoCore, mount?: string);
366
+ /** Logs in. The returned token is stored on the client unless `setToken: false`. */
367
+ login(roleId: string, secretId?: string, opts?: LoginOptions): Promise<AuthInfo>;
368
+ readRoleId(role: string, opts?: CallOptions): Promise<string>;
369
+ setRoleId(role: string, roleId: string, opts?: CallOptions): Promise<void>;
370
+ /** Generates a new secret-id. */
371
+ generateSecretId(role: string, options?: SecretIdOptions, opts?: CallOptions): Promise<GeneratedSecretId>;
372
+ /**
373
+ * Generates a secret-id wrapped in a single-use response-wrapping token —
374
+ * the recommended way to hand secret-ids to workloads.
375
+ */
376
+ generateWrappedSecretId(role: string, wrapTTL?: Duration, options?: SecretIdOptions, opts?: Omit<CallOptions, 'wrapTTL'>): Promise<WrapInfo>;
377
+ /** Lists secret-id accessors for a role. */
378
+ listSecretIdAccessors(role: string, opts?: CallOptions & ListOptions): Promise<string[]>;
379
+ lookupSecretId(role: string, secretId: string, opts?: CallOptions): Promise<Record<string, unknown> | undefined>;
380
+ destroySecretId(role: string, secretId: string, opts?: CallOptions): Promise<void>;
381
+ lookupSecretIdAccessor(role: string, accessor: string, opts?: CallOptions): Promise<Record<string, unknown> | undefined>;
382
+ destroySecretIdAccessor(role: string, accessor: string, opts?: CallOptions): Promise<void>;
383
+ tidySecretIds(opts?: CallOptions): Promise<void>;
384
+ private secretIdBody;
385
+ }
386
+ interface UserpassUser extends TokenFields {
387
+ password?: string;
388
+ [key: string]: unknown;
389
+ }
390
+ /** Username & password auth method. */
391
+ declare class UserpassAuth extends AuthMethodApi {
392
+ readonly users: Resource<UserpassUser, UserpassUser>;
393
+ constructor(client: OpenBaoCore, mount?: string);
394
+ login(username: string, password: string, opts?: LoginOptions): Promise<AuthInfo>;
395
+ setPassword(username: string, password: string, opts?: CallOptions): Promise<void>;
396
+ setPolicies(username: string, policies: string[], opts?: CallOptions): Promise<void>;
397
+ }
398
+ /** LDAP auth method. */
399
+ declare class LdapAuth extends AuthMethodApi {
400
+ readonly users: Resource<{
401
+ policies?: string[];
402
+ groups?: string[];
403
+ }, {
404
+ policies?: string[];
405
+ groups?: string[];
406
+ }>;
407
+ readonly groups: Resource<{
408
+ policies?: string[];
409
+ }, {
410
+ policies?: string[];
411
+ }>;
412
+ constructor(client: OpenBaoCore, mount?: string);
413
+ login(username: string, password: string, opts?: LoginOptions): Promise<AuthInfo>;
414
+ readConfig(opts?: CallOptions): Promise<Record<string, unknown>>;
415
+ writeConfig(config: Record<string, unknown>, opts?: CallOptions): Promise<void>;
416
+ }
417
+ interface JwtConfig {
418
+ oidc_discovery_url?: string;
419
+ oidc_discovery_ca_pem?: string;
420
+ oidc_client_id?: string;
421
+ oidc_client_secret?: string;
422
+ oidc_response_mode?: 'query' | 'form_post';
423
+ oidc_response_types?: string[];
424
+ jwks_url?: string;
425
+ jwks_ca_pem?: string;
426
+ jwt_validation_pubkeys?: string[];
427
+ bound_issuer?: string;
428
+ jwt_supported_algs?: string[];
429
+ default_role?: string;
430
+ provider_config?: Record<string, unknown>;
431
+ [key: string]: unknown;
432
+ }
433
+ interface JwtRole extends TokenFields {
434
+ role_type?: 'jwt' | 'oidc';
435
+ user_claim: string;
436
+ bound_audiences?: string[];
437
+ bound_subject?: string;
438
+ bound_claims?: Record<string, string | string[]>;
439
+ bound_claims_type?: 'string' | 'glob';
440
+ groups_claim?: string;
441
+ claim_mappings?: Record<string, string>;
442
+ allowed_redirect_uris?: string[];
443
+ oidc_scopes?: string[];
444
+ verbose_oidc_logging?: boolean;
445
+ [key: string]: unknown;
446
+ }
447
+ /** JWT / OIDC auth method. The same class serves `jwt` and `oidc` mounts. */
448
+ declare class JwtAuth extends AuthMethodApi {
449
+ readonly roles: Resource<JwtRole, Partial<JwtRole>>;
450
+ constructor(client: OpenBaoCore, mount?: string);
451
+ /** Logs in with a signed JWT (e.g. a GitHub Actions / Kubernetes / CI token). */
452
+ login(jwt: string, role?: string, opts?: LoginOptions): Promise<AuthInfo>;
453
+ readConfig(opts?: CallOptions): Promise<JwtConfig>;
454
+ writeConfig(config: JwtConfig, opts?: CallOptions): Promise<void>;
455
+ /** Step 1 of the OIDC browser flow: obtain the provider authorization URL. */
456
+ oidcAuthUrl(redirectUri: string, options?: {
457
+ role?: string;
458
+ client_nonce?: string;
459
+ } & CallOptions): Promise<string>;
460
+ /** Step 2 of the OIDC browser flow: exchange the callback parameters for a token. */
461
+ oidcCallback(params: {
462
+ state: string;
463
+ code: string;
464
+ nonce?: string;
465
+ client_nonce?: string;
466
+ }, opts?: LoginOptions): Promise<AuthInfo>;
467
+ }
468
+ interface KubernetesRole extends TokenFields {
469
+ bound_service_account_names: string[];
470
+ bound_service_account_namespaces: string[];
471
+ audience?: string;
472
+ alias_name_source?: 'serviceaccount_uid' | 'serviceaccount_name';
473
+ [key: string]: unknown;
474
+ }
475
+ /** Kubernetes auth method. */
476
+ declare class KubernetesAuth extends AuthMethodApi {
477
+ readonly roles: Resource<KubernetesRole, Partial<KubernetesRole>>;
478
+ constructor(client: OpenBaoCore, mount?: string);
479
+ login(role: string, jwt: string, opts?: LoginOptions): Promise<AuthInfo>;
480
+ /**
481
+ * Logs in with the pod's projected service-account token (Node.js only).
482
+ * @param tokenPath defaults to `/var/run/secrets/kubernetes.io/serviceaccount/token`
483
+ */
484
+ loginWithServiceAccount(role: string, tokenPath?: string, opts?: LoginOptions): Promise<AuthInfo>;
485
+ readConfig(opts?: CallOptions): Promise<Record<string, unknown>>;
486
+ writeConfig(config: {
487
+ kubernetes_host: string;
488
+ kubernetes_ca_cert?: string;
489
+ token_reviewer_jwt?: string;
490
+ pem_keys?: string[];
491
+ disable_local_ca_jwt?: boolean;
492
+ [key: string]: unknown;
493
+ }, opts?: CallOptions): Promise<void>;
494
+ }
495
+ /** TLS certificate auth method. The client certificate must be supplied via `requestInit.dispatcher` (undici Agent). */
496
+ declare class CertAuth extends AuthMethodApi {
497
+ readonly certs: Resource<Record<string, unknown>, {
498
+ certificate?: string;
499
+ allowed_common_names?: string[];
500
+ display_name?: string;
501
+ } & TokenFields & Record<string, unknown>>;
502
+ constructor(client: OpenBaoCore, mount?: string);
503
+ login(name?: string, opts?: LoginOptions): Promise<AuthInfo>;
504
+ }
505
+ declare class RadiusAuth extends AuthMethodApi {
506
+ readonly users: Resource<{
507
+ policies?: string[];
508
+ }, {
509
+ policies?: string[];
510
+ }>;
511
+ constructor(client: OpenBaoCore, mount?: string);
512
+ login(username: string, password: string, opts?: LoginOptions): Promise<AuthInfo>;
513
+ writeConfig(config: {
514
+ host: string;
515
+ secret: string;
516
+ port?: number;
517
+ [key: string]: unknown;
518
+ }, opts?: CallOptions): Promise<void>;
519
+ }
520
+ declare class KerberosAuth extends AuthMethodApi {
521
+ constructor(client: OpenBaoCore, mount?: string);
522
+ /** Logs in with a base64 SPNEGO token (sent as `Authorization: Negotiate <token>`). */
523
+ login(spnegoToken: string, opts?: LoginOptions): Promise<AuthInfo>;
524
+ }
525
+ /** Any auth method not covered above: `bao.auth.method('github').login({ token })`. */
526
+ declare class GenericAuth extends AuthMethodApi {
527
+ login(body: Record<string, unknown>, options?: LoginOptions & {
528
+ path?: string;
529
+ }): Promise<AuthInfo>;
530
+ }
531
+ /** Entry point for all auth methods. Factories accept a custom mount path. */
532
+ declare class Auth {
533
+ private readonly client;
534
+ readonly token: TokenAuth;
535
+ constructor(client: OpenBaoCore);
536
+ approle(mount?: string): AppRoleAuth;
537
+ userpass(mount?: string): UserpassAuth;
538
+ ldap(mount?: string): LdapAuth;
539
+ jwt(mount?: string): JwtAuth;
540
+ oidc(mount?: string): JwtAuth;
541
+ kubernetes(mount?: string): KubernetesAuth;
542
+ cert(mount?: string): CertAuth;
543
+ radius(mount?: string): RadiusAuth;
544
+ kerberos(mount?: string): KerberosAuth;
545
+ /** Generic accessor for any mounted auth method. */
546
+ method(mount: string): GenericAuth;
547
+ }
548
+
549
+ interface DatabaseConnectionConfig {
550
+ /** Plugin, e.g. `postgresql-database-plugin`, `mysql-database-plugin`. */
551
+ plugin_name: string;
552
+ connection_url?: string;
553
+ username?: string;
554
+ password?: string;
555
+ verify_connection?: boolean;
556
+ allowed_roles?: string[];
557
+ root_rotation_statements?: string[];
558
+ password_policy?: string;
559
+ plugin_version?: string;
560
+ [key: string]: unknown;
561
+ }
562
+ interface DatabaseRole {
563
+ db_name: string;
564
+ default_ttl?: Duration;
565
+ max_ttl?: Duration;
566
+ creation_statements?: string[];
567
+ revocation_statements?: string[];
568
+ rollback_statements?: string[];
569
+ renew_statements?: string[];
570
+ credential_type?: 'password' | 'rsa_private_key' | 'client_certificate';
571
+ credential_config?: Record<string, unknown>;
572
+ [key: string]: unknown;
573
+ }
574
+ interface DatabaseStaticRole {
575
+ db_name: string;
576
+ username: string;
577
+ rotation_period?: Duration;
578
+ rotation_statements?: string[];
579
+ credential_type?: string;
580
+ credential_config?: Record<string, unknown>;
581
+ [key: string]: unknown;
582
+ }
583
+ interface DatabaseCredentials {
584
+ username: string;
585
+ password?: string;
586
+ rsa_private_key?: string;
587
+ [key: string]: unknown;
588
+ }
589
+ interface StaticCredentials extends DatabaseCredentials {
590
+ last_vault_rotation: string;
591
+ rotation_period: number;
592
+ ttl: number;
593
+ }
594
+ /** Database secrets engine — dynamic and static database credentials. */
595
+ declare class Database extends MountedApi {
596
+ /** Connection configurations (`<mount>/config/:name`). */
597
+ readonly connections: Resource<DatabaseConnectionConfig, DatabaseConnectionConfig>;
598
+ /** Dynamic roles (`<mount>/roles/:name`). */
599
+ readonly roles: Resource<DatabaseRole, DatabaseRole>;
600
+ /** Static roles (`<mount>/static-roles/:name`). */
601
+ readonly staticRoles: Resource<DatabaseStaticRole, DatabaseStaticRole>;
602
+ constructor(client: OpenBaoCore, mount?: string);
603
+ /**
604
+ * Generates dynamic credentials. Returns the full envelope so you can manage
605
+ * the lease (`lease_id`, `lease_duration`) via `sys.leases`.
606
+ */
607
+ creds<T extends DatabaseCredentials = DatabaseCredentials>(role: string, opts?: CallOptions): Promise<ApiResponse<T>>;
608
+ /** Reads the current password of a static role. */
609
+ staticCreds(role: string, opts?: CallOptions): Promise<StaticCredentials>;
610
+ rotateRoot(connection: string, opts?: CallOptions): Promise<void>;
611
+ rotateStaticRole(role: string, opts?: CallOptions): Promise<void>;
612
+ /** Closes and reloads a connection (`<mount>/reset/:name`). */
613
+ resetConnection(connection: string, opts?: CallOptions): Promise<void>;
614
+ }
615
+
616
+ type SecretData = Record<string, unknown>;
617
+ /** KV version 1 secrets engine (also usable for any unversioned key/value mount). */
618
+ declare class KvV1 extends MountedApi {
619
+ constructor(client: OpenBaoCore, mount?: string);
620
+ /** Reads a secret. Throws `OpenBaoError` (404) if it does not exist. */
621
+ get<T extends SecretData = SecretData>(path: string, opts?: CallOptions): Promise<T>;
622
+ /** Creates or replaces a secret. */
623
+ set(path: string, data: SecretData, opts?: CallOptions): Promise<void>;
624
+ delete(path: string, opts?: CallOptions): Promise<void>;
625
+ /** Lists keys under a folder. Folders end with `/`. */
626
+ list(path?: string, opts?: CallOptions & ListOptions): Promise<string[]>;
627
+ }
628
+ interface KvV2VersionMetadata {
629
+ created_time: string;
630
+ deletion_time: string;
631
+ destroyed: boolean;
632
+ version: number;
633
+ custom_metadata: Record<string, string> | null;
634
+ }
635
+ interface KvV2Secret<T extends SecretData = SecretData> {
636
+ data: T;
637
+ metadata: KvV2VersionMetadata;
638
+ }
639
+ interface KvV2Metadata {
640
+ cas_required: boolean;
641
+ created_time: string;
642
+ current_version: number;
643
+ delete_version_after: string;
644
+ max_versions: number;
645
+ oldest_version: number;
646
+ updated_time: string;
647
+ custom_metadata: Record<string, string> | null;
648
+ versions: Record<string, {
649
+ created_time: string;
650
+ deletion_time: string;
651
+ destroyed: boolean;
652
+ }>;
653
+ }
654
+ interface KvV2MetadataInput {
655
+ max_versions?: number;
656
+ cas_required?: boolean;
657
+ delete_version_after?: Duration;
658
+ custom_metadata?: Record<string, string>;
659
+ }
660
+ interface KvV2Config {
661
+ max_versions?: number;
662
+ cas_required?: boolean;
663
+ delete_version_after?: Duration;
664
+ }
665
+ /** KV version 2 (versioned) secrets engine. Paths are logical — `data/` & `metadata/` are added for you. */
666
+ declare class KvV2 extends MountedApi {
667
+ constructor(client: OpenBaoCore, mount?: string);
668
+ /** Reads the latest (or a specific) version of a secret with its metadata. */
669
+ read<T extends SecretData = SecretData>(path: string, options?: {
670
+ version?: number;
671
+ } & CallOptions): Promise<KvV2Secret<T>>;
672
+ /** Reads just the secret payload. Throws `OpenBaoError` (404) when missing or deleted. */
673
+ get<T extends SecretData = SecretData>(path: string, options?: {
674
+ version?: number;
675
+ } & CallOptions): Promise<T>;
676
+ /**
677
+ * Writes a new version. Pass `cas` for check-and-set (`0` = only create if absent).
678
+ * Returns metadata for the new version.
679
+ */
680
+ write(path: string, data: SecretData, options?: {
681
+ cas?: number;
682
+ } & CallOptions): Promise<KvV2VersionMetadata>;
683
+ /** Alias of {@link write}. */
684
+ set(path: string, data: SecretData, options?: {
685
+ cas?: number;
686
+ } & CallOptions): Promise<KvV2VersionMetadata>;
687
+ /**
688
+ * JSON merge-patches the latest version (keys set to `null` are removed).
689
+ * Requires the `patch` capability.
690
+ */
691
+ patch(path: string, data: Record<string, unknown>, options?: {
692
+ cas?: number;
693
+ } & CallOptions): Promise<KvV2VersionMetadata>;
694
+ /** Returns the key structure of a secret (values replaced by `null`). */
695
+ subkeys(path: string, options?: {
696
+ version?: number;
697
+ depth?: number;
698
+ } & CallOptions): Promise<{
699
+ subkeys: Record<string, unknown>;
700
+ metadata: KvV2VersionMetadata;
701
+ }>;
702
+ /** Soft-deletes the latest version (recoverable with {@link undelete}). */
703
+ delete(path: string, opts?: CallOptions): Promise<void>;
704
+ /** Soft-deletes specific versions. */
705
+ deleteVersions(path: string, versions: number[], opts?: CallOptions): Promise<void>;
706
+ undelete(path: string, versions: number[], opts?: CallOptions): Promise<void>;
707
+ /** Permanently destroys versions' data. */
708
+ destroy(path: string, versions: number[], opts?: CallOptions): Promise<void>;
709
+ /** Lists keys under a folder (folders end with `/`). Returns `[]` for empty/missing folders. */
710
+ list(path?: string, opts?: CallOptions & ListOptions): Promise<string[]>;
711
+ /** Recursively lists every key under a folder (OpenBao `SCAN`). */
712
+ scan(path?: string, opts?: CallOptions & ListOptions): Promise<string[]>;
713
+ /** Lists keys together with their full metadata (OpenBao `detailed-metadata`). */
714
+ listDetailed(path?: string, opts?: CallOptions & ListOptions): Promise<ListData<KvV2Metadata>>;
715
+ readMetadata(path: string, opts?: CallOptions): Promise<KvV2Metadata>;
716
+ writeMetadata(path: string, metadata: KvV2MetadataInput, opts?: CallOptions): Promise<void>;
717
+ patchMetadata(path: string, metadata: KvV2MetadataInput, opts?: CallOptions): Promise<void>;
718
+ /** Permanently deletes the key, all versions and metadata. */
719
+ deleteMetadata(path: string, opts?: CallOptions): Promise<void>;
720
+ readConfig(opts?: CallOptions): Promise<Required<KvV2Config>>;
721
+ writeConfig(config: KvV2Config, opts?: CallOptions): Promise<void>;
722
+ }
723
+ /** Per-token private storage at `cubbyhole/`. */
724
+ declare class Cubbyhole extends KvV1 {
725
+ constructor(client: OpenBaoCore);
726
+ }
727
+
728
+ interface TotpKeyOptions {
729
+ /** Generate a key server-side (`true`) or import one via `url`/`key` (`false`). */
730
+ generate?: boolean;
731
+ exported?: boolean;
732
+ key_size?: number;
733
+ url?: string;
734
+ key?: string;
735
+ issuer?: string;
736
+ account_name?: string;
737
+ period?: Duration;
738
+ algorithm?: 'SHA1' | 'SHA256' | 'SHA512';
739
+ digits?: 6 | 8;
740
+ skew?: 0 | 1;
741
+ qr_size?: number;
742
+ }
743
+ interface TotpKey {
744
+ account_name: string;
745
+ algorithm: string;
746
+ digits: number;
747
+ issuer: string;
748
+ period: number;
749
+ }
750
+ /** TOTP secrets engine — generate and validate time-based one-time passwords. */
751
+ declare class Totp extends MountedApi {
752
+ constructor(client: OpenBaoCore, mount?: string);
753
+ /** Creates a key. When `generate` and `exported` are set, returns the provisioning `url` and base64 PNG `barcode`. */
754
+ createKey(name: string, options: TotpKeyOptions, opts?: CallOptions): Promise<{
755
+ url?: string;
756
+ barcode?: string;
757
+ }>;
758
+ readKey(name: string, opts?: CallOptions): Promise<TotpKey>;
759
+ listKeys(opts?: CallOptions): Promise<string[]>;
760
+ deleteKey(name: string, opts?: CallOptions): Promise<void>;
761
+ /** Generates the current code (only for keys created with `generate: true`). */
762
+ code(name: string, opts?: CallOptions): Promise<string>;
763
+ validate(name: string, code: string, opts?: CallOptions): Promise<boolean>;
764
+ }
765
+ interface SshRole {
766
+ key_type: 'otp' | 'ca';
767
+ default_user?: string;
768
+ allowed_users?: string;
769
+ allowed_domains?: string;
770
+ ttl?: Duration;
771
+ max_ttl?: Duration;
772
+ allow_user_certificates?: boolean;
773
+ allow_host_certificates?: boolean;
774
+ allowed_extensions?: string;
775
+ default_extensions?: Record<string, string>;
776
+ allowed_critical_options?: string;
777
+ cidr_list?: string;
778
+ [key: string]: unknown;
779
+ }
780
+ interface SshSignOptions {
781
+ valid_principals?: string | string[];
782
+ ttl?: Duration;
783
+ cert_type?: 'user' | 'host';
784
+ key_id?: string;
785
+ critical_options?: Record<string, string>;
786
+ extensions?: Record<string, string>;
787
+ [key: string]: unknown;
788
+ }
789
+ /** SSH secrets engine — signed certificates and one-time passwords. */
790
+ declare class Ssh extends MountedApi {
791
+ readonly roles: Resource<SshRole, SshRole>;
792
+ constructor(client: OpenBaoCore, mount?: string);
793
+ /** Configures the signing CA. With no keys given, one is generated. Returns the CA public key. */
794
+ configureCa(options?: {
795
+ private_key?: string;
796
+ public_key?: string;
797
+ generate_signing_key?: boolean;
798
+ key_type?: string;
799
+ key_bits?: number;
800
+ }, opts?: CallOptions): Promise<string | undefined>;
801
+ readCaPublicKey(opts?: CallOptions): Promise<string>;
802
+ deleteCa(opts?: CallOptions): Promise<void>;
803
+ /** Signs an SSH public key. */
804
+ sign(role: string, publicKey: string, options?: SshSignOptions, opts?: CallOptions): Promise<{
805
+ serial_number: string;
806
+ signed_key: string;
807
+ }>;
808
+ /** Generates a key pair and signs it. */
809
+ issue(role: string, options?: SshSignOptions & {
810
+ key_type?: string;
811
+ key_bits?: number;
812
+ }, opts?: CallOptions): Promise<{
813
+ serial_number: string;
814
+ signed_key: string;
815
+ private_key: string;
816
+ private_key_type: string;
817
+ }>;
818
+ /** Creates an OTP credential for an OTP role. */
819
+ otp(role: string, ip: string, username?: string, opts?: CallOptions): Promise<{
820
+ key: string;
821
+ key_type: string;
822
+ username: string;
823
+ ip: string;
824
+ port: number;
825
+ }>;
826
+ verifyOtp(otp: string, opts?: CallOptions): Promise<{
827
+ ip: string;
828
+ username: string;
829
+ role_name: string;
830
+ }>;
831
+ }
832
+ interface Entity {
833
+ id: string;
834
+ name: string;
835
+ metadata: Record<string, string> | null;
836
+ policies: string[] | null;
837
+ disabled: boolean;
838
+ aliases: EntityAlias[];
839
+ group_ids?: string[];
840
+ direct_group_ids?: string[];
841
+ inherited_group_ids?: string[];
842
+ creation_time?: string;
843
+ last_update_time?: string;
844
+ [key: string]: unknown;
845
+ }
846
+ interface EntityAlias {
847
+ id: string;
848
+ name: string;
849
+ canonical_id: string;
850
+ mount_accessor: string;
851
+ mount_path?: string;
852
+ mount_type?: string;
853
+ custom_metadata?: Record<string, string> | null;
854
+ [key: string]: unknown;
855
+ }
856
+ interface EntityInput {
857
+ name?: string;
858
+ metadata?: Record<string, string>;
859
+ policies?: string[];
860
+ disabled?: boolean;
861
+ }
862
+ interface Group {
863
+ id: string;
864
+ name: string;
865
+ type: 'internal' | 'external';
866
+ metadata: Record<string, string> | null;
867
+ policies: string[] | null;
868
+ member_entity_ids: string[] | null;
869
+ member_group_ids: string[] | null;
870
+ alias?: Record<string, unknown>;
871
+ [key: string]: unknown;
872
+ }
873
+ interface GroupInput {
874
+ name?: string;
875
+ type?: 'internal' | 'external';
876
+ metadata?: Record<string, string>;
877
+ policies?: string[];
878
+ member_entity_ids?: string[];
879
+ member_group_ids?: string[];
880
+ }
881
+ /** CRUD for entity-like identity objects that are addressable by `id/` and `name/`. */
882
+ declare class IdentityCollection<T, Input extends object> {
883
+ private readonly client;
884
+ private readonly kind;
885
+ /** Access by name (`identity/<kind>/name/:name`). */
886
+ readonly byName: Resource<T, Input>;
887
+ /** Access by id (`identity/<kind>/id/:id`). */
888
+ readonly byId: Resource<T, Input>;
889
+ constructor(client: OpenBaoCore, kind: string);
890
+ /** Creates (or updates, when `id` is given) and returns `{ id, name }`. */
891
+ create(input: Input & {
892
+ id?: string;
893
+ }, opts?: CallOptions): Promise<{
894
+ id: string;
895
+ name: string;
896
+ } | undefined>;
897
+ }
898
+ /** Identity secrets engine — entities, aliases, groups and identity tokens. */
899
+ declare class Identity {
900
+ private readonly client;
901
+ readonly entities: IdentityCollection<Entity, EntityInput>;
902
+ readonly groups: IdentityCollection<Group, GroupInput>;
903
+ /** Entity aliases (`identity/entity-alias/id/:id`). */
904
+ readonly entityAliases: Resource<EntityAlias, {
905
+ name?: string;
906
+ canonical_id?: string;
907
+ mount_accessor?: string;
908
+ custom_metadata?: Record<string, string>;
909
+ }>;
910
+ /** Group aliases (`identity/group-alias/id/:id`). */
911
+ readonly groupAliases: Resource<Record<string, unknown>, {
912
+ name?: string;
913
+ canonical_id?: string;
914
+ mount_accessor?: string;
915
+ }>;
916
+ constructor(client: OpenBaoCore);
917
+ /** Creates an entity alias linking an auth-method identity to an entity. */
918
+ createEntityAlias(input: {
919
+ name: string;
920
+ canonical_id: string;
921
+ mount_accessor: string;
922
+ custom_metadata?: Record<string, string>;
923
+ }, opts?: CallOptions): Promise<{
924
+ id: string;
925
+ canonical_id: string;
926
+ } | undefined>;
927
+ createGroupAlias(input: {
928
+ name: string;
929
+ canonical_id?: string;
930
+ mount_accessor: string;
931
+ }, opts?: CallOptions): Promise<{
932
+ id: string;
933
+ canonical_id: string;
934
+ } | undefined>;
935
+ /** Merges entities into `toEntityId`. */
936
+ mergeEntities(fromEntityIds: string[], toEntityId: string, options?: {
937
+ force?: boolean;
938
+ }, opts?: CallOptions): Promise<void>;
939
+ /** Looks up an entity by `name`, `id`, `alias_id`, or `alias_name` + `alias_mount_accessor`. Returns `undefined` when not found. */
940
+ lookupEntity(criteria: {
941
+ name?: string;
942
+ id?: string;
943
+ alias_id?: string;
944
+ alias_name?: string;
945
+ alias_mount_accessor?: string;
946
+ }, opts?: CallOptions): Promise<Entity | undefined>;
947
+ lookupGroup(criteria: {
948
+ name?: string;
949
+ id?: string;
950
+ alias_id?: string;
951
+ alias_name?: string;
952
+ alias_mount_accessor?: string;
953
+ }, opts?: CallOptions): Promise<Group | undefined>;
954
+ /** Generates a signed OIDC identity token for the calling entity. */
955
+ oidcToken(role: string, opts?: CallOptions): Promise<{
956
+ token: string;
957
+ client_id: string;
958
+ ttl: number;
959
+ }>;
960
+ introspectOidcToken(token: string, clientId?: string, opts?: CallOptions): Promise<{
961
+ active: boolean;
962
+ [key: string]: unknown;
963
+ }>;
964
+ }
965
+
966
+ interface CertificateRequest {
967
+ common_name?: string;
968
+ alt_names?: string | string[];
969
+ ip_sans?: string | string[];
970
+ uri_sans?: string | string[];
971
+ other_sans?: string | string[];
972
+ ttl?: Duration;
973
+ not_after?: string;
974
+ format?: 'pem' | 'der' | 'pem_bundle';
975
+ private_key_format?: 'der' | 'pkcs8' | '';
976
+ exclude_cn_from_sans?: boolean;
977
+ issuer_ref?: string;
978
+ [key: string]: unknown;
979
+ }
980
+ interface IssuedCertificate {
981
+ certificate: string;
982
+ issuing_ca: string;
983
+ ca_chain: string[];
984
+ private_key?: string;
985
+ private_key_type?: string;
986
+ serial_number: string;
987
+ expiration: number;
988
+ }
989
+ interface GenerateRootOptions {
990
+ common_name: string;
991
+ alt_names?: string;
992
+ ttl?: Duration;
993
+ key_type?: 'rsa' | 'ec' | 'ed25519';
994
+ key_bits?: number;
995
+ issuer_name?: string;
996
+ key_name?: string;
997
+ max_path_length?: number;
998
+ organization?: string;
999
+ ou?: string;
1000
+ country?: string;
1001
+ [key: string]: unknown;
1002
+ }
1003
+ interface PkiRole {
1004
+ ttl?: Duration;
1005
+ max_ttl?: Duration;
1006
+ allow_localhost?: boolean;
1007
+ allowed_domains?: string[];
1008
+ allow_bare_domains?: boolean;
1009
+ allow_subdomains?: boolean;
1010
+ allow_glob_domains?: boolean;
1011
+ allow_any_name?: boolean;
1012
+ enforce_hostnames?: boolean;
1013
+ allow_ip_sans?: boolean;
1014
+ allowed_uri_sans?: string[];
1015
+ server_flag?: boolean;
1016
+ client_flag?: boolean;
1017
+ key_type?: 'rsa' | 'ec' | 'ed25519' | 'any';
1018
+ key_bits?: number;
1019
+ issuer_ref?: string;
1020
+ no_store?: boolean;
1021
+ generate_lease?: boolean;
1022
+ [key: string]: unknown;
1023
+ }
1024
+ /** PKI secrets engine — X.509 certificate authority. */
1025
+ declare class Pki extends MountedApi {
1026
+ /** Role definitions (`<mount>/roles/:name`). */
1027
+ readonly roles: Resource<PkiRole, PkiRole>;
1028
+ constructor(client: OpenBaoCore, mount?: string);
1029
+ /** Issues a certificate (and private key) against a role. */
1030
+ issue(role: string, request: CertificateRequest, opts?: CallOptions): Promise<IssuedCertificate>;
1031
+ /** Signs a CSR against a role. */
1032
+ sign(role: string, csr: string, request?: CertificateRequest, opts?: CallOptions): Promise<IssuedCertificate>;
1033
+ /** Signs a CSR verbatim (bypasses role restrictions; requires sudo-like policy). */
1034
+ signVerbatim(csr: string, request?: CertificateRequest & {
1035
+ role?: string;
1036
+ }, opts?: CallOptions): Promise<IssuedCertificate>;
1037
+ revoke(serialNumber: string, opts?: CallOptions): Promise<{
1038
+ revocation_time: number;
1039
+ revocation_time_rfc3339?: string;
1040
+ }>;
1041
+ /** Reads a certificate by serial (`ca`, `crl`, `ca_chain` are also accepted). */
1042
+ readCert(serial: string, opts?: CallOptions): Promise<{
1043
+ certificate: string;
1044
+ revocation_time: number;
1045
+ [key: string]: unknown;
1046
+ }>;
1047
+ listCerts(opts?: CallOptions & ListOptions): Promise<string[]>;
1048
+ listRevokedCerts(opts?: CallOptions & ListOptions): Promise<string[]>;
1049
+ /** Default issuer's CA certificate as PEM. Unauthenticated. */
1050
+ caPem(opts?: CallOptions): Promise<string>;
1051
+ /** Default issuer's CA chain as PEM. Unauthenticated. */
1052
+ caChainPem(opts?: CallOptions): Promise<string>;
1053
+ /** Current CRL as PEM. Unauthenticated. */
1054
+ crlPem(opts?: CallOptions): Promise<string>;
1055
+ /** Generates a self-signed root. `type: 'exported'` returns the private key. */
1056
+ generateRoot(options: GenerateRootOptions & {
1057
+ type?: 'internal' | 'exported' | 'existing' | 'kms';
1058
+ }, opts?: CallOptions): Promise<{
1059
+ certificate: string;
1060
+ issuing_ca: string;
1061
+ serial_number: string;
1062
+ issuer_id?: string;
1063
+ key_id?: string;
1064
+ private_key?: string;
1065
+ expiration: number;
1066
+ }>;
1067
+ /** Generates an intermediate CSR. */
1068
+ generateIntermediate(options: GenerateRootOptions & {
1069
+ type?: 'internal' | 'exported' | 'existing' | 'kms';
1070
+ }, opts?: CallOptions): Promise<{
1071
+ csr: string;
1072
+ key_id?: string;
1073
+ private_key?: string;
1074
+ }>;
1075
+ /** Signs an intermediate CSR with this mount's root. */
1076
+ signIntermediate(csr: string, options?: Partial<GenerateRootOptions> & {
1077
+ use_csr_values?: boolean;
1078
+ format?: string;
1079
+ }, opts?: CallOptions): Promise<IssuedCertificate>;
1080
+ /** Imports the signed intermediate certificate. */
1081
+ setSignedIntermediate(certificate: string, opts?: CallOptions): Promise<void>;
1082
+ /** Imports a PEM bundle (certificate and/or key). */
1083
+ importBundle(pemBundle: string, opts?: CallOptions): Promise<Record<string, unknown> | undefined>;
1084
+ deleteRoot(opts?: CallOptions): Promise<void>;
1085
+ listIssuers(opts?: CallOptions & ListOptions): Promise<ListData<{
1086
+ issuer_name: string;
1087
+ is_default: boolean;
1088
+ key_id: string;
1089
+ }>>;
1090
+ readIssuer(ref?: string, opts?: CallOptions): Promise<Record<string, unknown>>;
1091
+ updateIssuer(ref: string, config: Record<string, unknown>, opts?: CallOptions): Promise<void>;
1092
+ setUrls(urls: {
1093
+ issuing_certificates?: string[];
1094
+ crl_distribution_points?: string[];
1095
+ ocsp_servers?: string[];
1096
+ enable_templating?: boolean;
1097
+ }, opts?: CallOptions): Promise<void>;
1098
+ readUrls(opts?: CallOptions): Promise<{
1099
+ issuing_certificates: string[];
1100
+ crl_distribution_points: string[];
1101
+ ocsp_servers: string[];
1102
+ }>;
1103
+ rotateCrl(opts?: CallOptions): Promise<void>;
1104
+ tidy(options?: {
1105
+ tidy_cert_store?: boolean;
1106
+ tidy_revoked_certs?: boolean;
1107
+ tidy_expired_issuers?: boolean;
1108
+ safety_buffer?: Duration;
1109
+ [key: string]: unknown;
1110
+ }, opts?: CallOptions): Promise<void>;
1111
+ }
1112
+
1113
+ /** Plaintext input: strings are UTF-8 encoded, bytes are used as-is. Base64 encoding is handled for you. */
1114
+ type BinaryLike = string | Uint8Array;
1115
+ type TransitKeyType = 'aes128-gcm96' | 'aes256-gcm96' | 'chacha20-poly1305' | 'xchacha20-poly1305' | 'ed25519' | 'ecdsa-p256' | 'ecdsa-p384' | 'ecdsa-p521' | 'rsa-2048' | 'rsa-3072' | 'rsa-4096' | 'hmac' | (string & {});
1116
+ type HashAlgorithm = 'sha1' | 'sha2-224' | 'sha2-256' | 'sha2-384' | 'sha2-512' | 'sha3-224' | 'sha3-256' | 'sha3-384' | 'sha3-512' | 'none';
1117
+ interface CreateTransitKeyOptions {
1118
+ type?: TransitKeyType;
1119
+ derived?: boolean;
1120
+ convergent_encryption?: boolean;
1121
+ exportable?: boolean;
1122
+ allow_plaintext_backup?: boolean;
1123
+ auto_rotate_period?: Duration;
1124
+ key_size?: number;
1125
+ [key: string]: unknown;
1126
+ }
1127
+ interface TransitKeyConfig {
1128
+ min_decryption_version?: number;
1129
+ min_encryption_version?: number;
1130
+ deletion_allowed?: boolean;
1131
+ exportable?: boolean;
1132
+ allow_plaintext_backup?: boolean;
1133
+ auto_rotate_period?: Duration;
1134
+ }
1135
+ interface TransitKey {
1136
+ name: string;
1137
+ type: string;
1138
+ derived: boolean;
1139
+ deletion_allowed: boolean;
1140
+ exportable: boolean;
1141
+ allow_plaintext_backup: boolean;
1142
+ supports_encryption: boolean;
1143
+ supports_decryption: boolean;
1144
+ supports_derivation: boolean;
1145
+ supports_signing: boolean;
1146
+ latest_version: number;
1147
+ min_available_version: number;
1148
+ min_decryption_version: number;
1149
+ min_encryption_version: number;
1150
+ auto_rotate_period: number;
1151
+ /** Version → creation timestamp (symmetric) or public key info (asymmetric). */
1152
+ keys: Record<string, number | {
1153
+ creation_time: string;
1154
+ name: string;
1155
+ public_key: string;
1156
+ }>;
1157
+ [key: string]: unknown;
1158
+ }
1159
+ interface EncryptOptions extends CallOptions {
1160
+ /** Key-derivation context (required for derived keys). */
1161
+ context?: BinaryLike;
1162
+ keyVersion?: number;
1163
+ nonce?: string;
1164
+ associatedData?: BinaryLike;
1165
+ }
1166
+ interface DecryptOptions extends CallOptions {
1167
+ context?: BinaryLike;
1168
+ nonce?: string;
1169
+ associatedData?: BinaryLike;
1170
+ }
1171
+ interface BatchEncryptItem {
1172
+ plaintext: BinaryLike;
1173
+ context?: BinaryLike;
1174
+ reference?: string;
1175
+ }
1176
+ interface BatchDecryptItem {
1177
+ ciphertext: string;
1178
+ context?: BinaryLike;
1179
+ reference?: string;
1180
+ }
1181
+ interface BatchResult {
1182
+ ciphertext?: string;
1183
+ plaintext?: string;
1184
+ key_version?: number;
1185
+ reference?: string;
1186
+ error?: string;
1187
+ }
1188
+ interface SignOptions extends CallOptions {
1189
+ hashAlgorithm?: HashAlgorithm;
1190
+ keyVersion?: number;
1191
+ context?: BinaryLike;
1192
+ prehashed?: boolean;
1193
+ signatureAlgorithm?: 'pss' | 'pkcs1v15';
1194
+ marshalingAlgorithm?: 'asn1' | 'jws';
1195
+ saltLength?: 'auto' | 'hash' | number;
1196
+ }
1197
+ /** Transit — encryption as a service. */
1198
+ declare class Transit extends MountedApi {
1199
+ constructor(client: OpenBaoCore, mount?: string);
1200
+ createKey(name: string, options?: CreateTransitKeyOptions, opts?: CallOptions): Promise<void>;
1201
+ readKey(name: string, opts?: CallOptions): Promise<TransitKey>;
1202
+ listKeys(opts?: CallOptions & ListOptions): Promise<string[]>;
1203
+ /** Deletes a key. The key must have `deletion_allowed: true` (see {@link configureKey}). */
1204
+ deleteKey(name: string, opts?: CallOptions): Promise<void>;
1205
+ configureKey(name: string, config: TransitKeyConfig, opts?: CallOptions): Promise<void>;
1206
+ rotateKey(name: string, opts?: CallOptions): Promise<void>;
1207
+ trimKey(name: string, minAvailableVersion: number, opts?: CallOptions): Promise<void>;
1208
+ exportKey(name: string, type: 'encryption-key' | 'signing-key' | 'hmac-key' | 'public-key', version?: number | 'latest', opts?: CallOptions): Promise<{
1209
+ name: string;
1210
+ type: string;
1211
+ keys: Record<string, string>;
1212
+ }>;
1213
+ backupKey(name: string, opts?: CallOptions): Promise<string>;
1214
+ restoreKey(backup: string, options?: {
1215
+ name?: string;
1216
+ force?: boolean;
1217
+ } & CallOptions): Promise<void>;
1218
+ /** Encrypts `plaintext` and returns the `bao:v1:...` ciphertext. */
1219
+ encrypt(key: string, plaintext: BinaryLike, options?: EncryptOptions): Promise<string>;
1220
+ /** Decrypts to a UTF-8 string. Use {@link decryptBytes} for binary data. */
1221
+ decrypt(key: string, ciphertext: string, options?: DecryptOptions): Promise<string>;
1222
+ /** Decrypts to raw bytes. */
1223
+ decryptBytes(key: string, ciphertext: string, options?: DecryptOptions): Promise<Uint8Array>;
1224
+ /** Re-encrypts ciphertext with the latest (or given) key version without exposing plaintext. */
1225
+ rewrap(key: string, ciphertext: string, options?: {
1226
+ context?: BinaryLike;
1227
+ keyVersion?: number;
1228
+ nonce?: string;
1229
+ } & CallOptions): Promise<string>;
1230
+ /** Encrypts many items in one request. Per-item failures are reported in `error`. */
1231
+ encryptBatch(key: string, items: BatchEncryptItem[], options?: {
1232
+ keyVersion?: number;
1233
+ } & CallOptions): Promise<BatchResult[]>;
1234
+ /** Decrypts many items in one request. `plaintext` in results is decoded to UTF-8. */
1235
+ decryptBatch(key: string, items: BatchDecryptItem[], opts?: CallOptions): Promise<BatchResult[]>;
1236
+ /**
1237
+ * Generates a data key for envelope encryption. `plaintext` (base64) is only
1238
+ * returned for `type: 'plaintext'`.
1239
+ */
1240
+ generateDataKey(key: string, options?: {
1241
+ type?: 'plaintext' | 'wrapped';
1242
+ bits?: 128 | 256 | 512;
1243
+ context?: BinaryLike;
1244
+ nonce?: string;
1245
+ } & CallOptions): Promise<{
1246
+ ciphertext: string;
1247
+ plaintext?: string;
1248
+ key_version: number;
1249
+ }>;
1250
+ sign(key: string, input: BinaryLike, options?: SignOptions): Promise<string>;
1251
+ verify(key: string, input: BinaryLike, signature: string, options?: Omit<SignOptions, 'keyVersion'>): Promise<boolean>;
1252
+ hmac(key: string, input: BinaryLike, options?: {
1253
+ algorithm?: HashAlgorithm;
1254
+ keyVersion?: number;
1255
+ } & CallOptions): Promise<string>;
1256
+ verifyHmac(key: string, input: BinaryLike, hmac: string, options?: {
1257
+ algorithm?: HashAlgorithm;
1258
+ } & CallOptions): Promise<boolean>;
1259
+ random(bytes?: number, options?: {
1260
+ format?: 'base64' | 'hex';
1261
+ source?: 'platform' | 'seal' | 'all';
1262
+ } & CallOptions): Promise<string>;
1263
+ hash(input: BinaryLike, options?: {
1264
+ algorithm?: Exclude<HashAlgorithm, 'none'>;
1265
+ format?: 'hex' | 'base64';
1266
+ } & CallOptions): Promise<string>;
1267
+ private decryptRaw;
1268
+ }
1269
+
1270
+ interface HealthStatus {
1271
+ initialized: boolean;
1272
+ sealed: boolean;
1273
+ standby: boolean;
1274
+ performance_standby?: boolean;
1275
+ replication_performance_mode?: string;
1276
+ replication_dr_mode?: string;
1277
+ server_time_utc: number;
1278
+ version: string;
1279
+ cluster_name?: string;
1280
+ cluster_id?: string;
1281
+ enterprise?: boolean;
1282
+ echo_duration_ms?: number;
1283
+ clock_skew_ms?: number;
1284
+ }
1285
+ interface HealthOptions extends Pick<CallOptions, 'signal'> {
1286
+ standbyok?: boolean;
1287
+ perfstandbyok?: boolean;
1288
+ activecode?: number;
1289
+ standbycode?: number;
1290
+ sealedcode?: number;
1291
+ uninitcode?: number;
1292
+ perfstandbycode?: number;
1293
+ }
1294
+ interface SealStatus {
1295
+ type: string;
1296
+ initialized: boolean;
1297
+ sealed: boolean;
1298
+ t: number;
1299
+ n: number;
1300
+ progress: number;
1301
+ nonce: string;
1302
+ version?: string;
1303
+ build_date?: string;
1304
+ migration?: boolean;
1305
+ cluster_name?: string;
1306
+ cluster_id?: string;
1307
+ recovery_seal?: boolean;
1308
+ storage_type?: string;
1309
+ }
1310
+ interface InitOptions {
1311
+ secret_shares?: number;
1312
+ secret_threshold?: number;
1313
+ pgp_keys?: string[];
1314
+ root_token_pgp_key?: string;
1315
+ recovery_shares?: number;
1316
+ recovery_threshold?: number;
1317
+ recovery_pgp_keys?: string[];
1318
+ stored_shares?: number;
1319
+ }
1320
+ interface InitResult {
1321
+ keys: string[];
1322
+ keys_base64: string[];
1323
+ recovery_keys?: string[];
1324
+ recovery_keys_base64?: string[];
1325
+ root_token: string;
1326
+ }
1327
+ interface LeaderStatus {
1328
+ ha_enabled: boolean;
1329
+ is_self: boolean;
1330
+ active_time?: string;
1331
+ leader_address: string;
1332
+ leader_cluster_address: string;
1333
+ performance_standby?: boolean;
1334
+ performance_standby_last_remote_wal?: number;
1335
+ raft_committed_index?: number;
1336
+ raft_applied_index?: number;
1337
+ }
1338
+ interface MountConfig {
1339
+ default_lease_ttl?: Duration;
1340
+ max_lease_ttl?: Duration;
1341
+ force_no_cache?: boolean;
1342
+ audit_non_hmac_request_keys?: string[];
1343
+ audit_non_hmac_response_keys?: string[];
1344
+ listing_visibility?: 'unauth' | 'hidden' | '';
1345
+ passthrough_request_headers?: string[];
1346
+ allowed_response_headers?: string[];
1347
+ plugin_version?: string;
1348
+ [key: string]: unknown;
1349
+ }
1350
+ interface MountInfo {
1351
+ type: string;
1352
+ description: string;
1353
+ accessor: string;
1354
+ uuid?: string;
1355
+ config: MountConfig;
1356
+ options: Record<string, string> | null;
1357
+ local: boolean;
1358
+ seal_wrap: boolean;
1359
+ external_entropy_access?: boolean;
1360
+ plugin_version?: string;
1361
+ running_plugin_version?: string;
1362
+ running_sha256?: string;
1363
+ }
1364
+ interface EnableMountOptions {
1365
+ /** Engine type, e.g. `kv`, `transit`, `pki`, `database`. */
1366
+ type: string;
1367
+ description?: string;
1368
+ config?: MountConfig;
1369
+ /** Engine options, e.g. `{ version: '2' }` for KV v2. */
1370
+ options?: Record<string, string>;
1371
+ local?: boolean;
1372
+ seal_wrap?: boolean;
1373
+ external_entropy_access?: boolean;
1374
+ plugin_version?: string;
1375
+ }
1376
+ interface EnableAuthOptions {
1377
+ /** Auth method type, e.g. `approle`, `userpass`, `jwt`, `kubernetes`. */
1378
+ type: string;
1379
+ description?: string;
1380
+ config?: MountConfig & {
1381
+ token_type?: string;
1382
+ };
1383
+ options?: Record<string, string>;
1384
+ local?: boolean;
1385
+ seal_wrap?: boolean;
1386
+ plugin_version?: string;
1387
+ }
1388
+ interface LeaseInfo {
1389
+ id: string;
1390
+ issue_time: string;
1391
+ expire_time: string | null;
1392
+ last_renewal: string | null;
1393
+ renewable: boolean;
1394
+ ttl: number;
1395
+ }
1396
+ interface AuditDevice {
1397
+ type: string;
1398
+ description: string;
1399
+ options: Record<string, string>;
1400
+ local: boolean;
1401
+ path: string;
1402
+ }
1403
+ interface NamespaceInfo {
1404
+ id: string;
1405
+ path: string;
1406
+ custom_metadata: Record<string, string>;
1407
+ [key: string]: unknown;
1408
+ }
1409
+ /** `sys/mounts` — secrets engine management. */
1410
+ declare class SysMounts {
1411
+ private readonly client;
1412
+ constructor(client: OpenBaoCore);
1413
+ /** Lists all mounted secrets engines keyed by path (`secret/`, `transit/`, ...). */
1414
+ list(opts?: CallOptions): Promise<Record<string, MountInfo>>;
1415
+ /** Reads one mount's configuration. */
1416
+ read(path: string, opts?: CallOptions): Promise<MountInfo>;
1417
+ /** Mounts a secrets engine at `path`. */
1418
+ enable(path: string, options: EnableMountOptions, opts?: CallOptions): Promise<void>;
1419
+ /** Unmounts a secrets engine (destroys all its data). */
1420
+ disable(path: string, opts?: CallOptions): Promise<void>;
1421
+ readTune(path: string, opts?: CallOptions): Promise<MountConfig>;
1422
+ tune(path: string, config: MountConfig & {
1423
+ description?: string;
1424
+ options?: Record<string, string>;
1425
+ }, opts?: CallOptions): Promise<void>;
1426
+ /** Moves a mount (`sys/remount`). Returns the migration id. */
1427
+ remount(from: string, to: string, opts?: CallOptions): Promise<{
1428
+ migration_id: string;
1429
+ } | undefined>;
1430
+ }
1431
+ /** `sys/auth` — auth method management. */
1432
+ declare class SysAuth {
1433
+ private readonly client;
1434
+ constructor(client: OpenBaoCore);
1435
+ list(opts?: CallOptions): Promise<Record<string, MountInfo>>;
1436
+ read(path: string, opts?: CallOptions): Promise<MountInfo>;
1437
+ enable(path: string, options: EnableAuthOptions, opts?: CallOptions): Promise<void>;
1438
+ disable(path: string, opts?: CallOptions): Promise<void>;
1439
+ readTune(path: string, opts?: CallOptions): Promise<MountConfig>;
1440
+ tune(path: string, config: MountConfig & {
1441
+ description?: string;
1442
+ token_type?: string;
1443
+ }, opts?: CallOptions): Promise<void>;
1444
+ }
1445
+ /** `sys/policies/acl` — ACL policies. */
1446
+ declare class SysAclPolicies {
1447
+ private readonly client;
1448
+ constructor(client: OpenBaoCore);
1449
+ list(opts?: CallOptions & ListOptions): Promise<string[]>;
1450
+ /** Returns the policy HCL text. */
1451
+ read(name: string, opts?: CallOptions): Promise<string>;
1452
+ /** Creates or replaces a policy from HCL/JSON text. */
1453
+ write(name: string, policy: string, opts?: CallOptions): Promise<void>;
1454
+ delete(name: string, opts?: CallOptions): Promise<void>;
1455
+ }
1456
+ /** `sys/policies/password` — password generation policies. */
1457
+ declare class SysPasswordPolicies {
1458
+ private readonly client;
1459
+ constructor(client: OpenBaoCore);
1460
+ list(opts?: CallOptions & ListOptions): Promise<string[]>;
1461
+ read(name: string, opts?: CallOptions): Promise<string>;
1462
+ write(name: string, policy: string, opts?: CallOptions): Promise<void>;
1463
+ delete(name: string, opts?: CallOptions): Promise<void>;
1464
+ /** Generates a password from the named policy. */
1465
+ generate(name: string, opts?: CallOptions): Promise<string>;
1466
+ }
1467
+ /** `sys/leases` — lease lookup, renewal and revocation. */
1468
+ declare class SysLeases {
1469
+ private readonly client;
1470
+ constructor(client: OpenBaoCore);
1471
+ lookup(leaseId: string, opts?: CallOptions): Promise<LeaseInfo>;
1472
+ /** Lists lease ids under a prefix, e.g. `database/creds/readonly/`. */
1473
+ list(prefix: string, opts?: CallOptions & ListOptions): Promise<string[]>;
1474
+ /** Renews a lease. Returns the new response envelope (with updated `lease_duration`). */
1475
+ renew(leaseId: string, increment?: Duration, opts?: CallOptions): Promise<ApiResponse<unknown>>;
1476
+ revoke(leaseId: string, options?: {
1477
+ sync?: boolean;
1478
+ } & CallOptions): Promise<void>;
1479
+ revokePrefix(prefix: string, options?: {
1480
+ sync?: boolean;
1481
+ } & CallOptions): Promise<void>;
1482
+ /** Revokes all leases under prefix ignoring backend errors. Requires `sudo`. */
1483
+ revokeForce(prefix: string, opts?: CallOptions): Promise<void>;
1484
+ tidy(opts?: CallOptions): Promise<void>;
1485
+ }
1486
+ /** `sys/wrapping/*` — response wrapping. */
1487
+ declare class SysWrapping {
1488
+ private readonly client;
1489
+ constructor(client: OpenBaoCore);
1490
+ /** Wraps arbitrary data in a single-use token. Returns the wrap info (use `.token`). */
1491
+ wrap(data: Record<string, unknown>, ttl?: Duration, opts?: Omit<CallOptions, 'wrapTTL'>): Promise<WrapInfo>;
1492
+ /**
1493
+ * Unwraps a wrapping token. Returns the original response envelope, so both
1494
+ * wrapped secrets (`.data`) and wrapped logins (`.auth`) are available.
1495
+ */
1496
+ unwrap<T = Record<string, unknown>>(wrappingToken?: string, opts?: CallOptions): Promise<ApiResponse<T>>;
1497
+ lookup(wrappingToken: string, opts?: CallOptions): Promise<{
1498
+ creation_ttl: number;
1499
+ creation_time: string;
1500
+ creation_path: string;
1501
+ }>;
1502
+ rewrap(wrappingToken: string, opts?: CallOptions): Promise<WrapInfo>;
1503
+ }
1504
+ /** `sys/tools/*` — random bytes and hashing. */
1505
+ declare class SysTools {
1506
+ private readonly client;
1507
+ constructor(client: OpenBaoCore);
1508
+ random(bytes?: number, options?: {
1509
+ format?: 'base64' | 'hex';
1510
+ source?: 'platform' | 'seal' | 'all';
1511
+ } & CallOptions): Promise<string>;
1512
+ /** Hashes input (string or bytes; base64-encoded automatically). */
1513
+ hash(input: string | Uint8Array, options?: {
1514
+ algorithm?: 'sha2-224' | 'sha2-256' | 'sha2-384' | 'sha2-512' | 'sha3-224' | 'sha3-256' | 'sha3-384' | 'sha3-512';
1515
+ format?: 'hex' | 'base64';
1516
+ } & CallOptions): Promise<string>;
1517
+ }
1518
+ /** `sys/audit` — audit devices. */
1519
+ declare class SysAudit {
1520
+ private readonly client;
1521
+ constructor(client: OpenBaoCore);
1522
+ list(opts?: CallOptions): Promise<Record<string, AuditDevice>>;
1523
+ /**
1524
+ * Enables an audit device. Note: recent OpenBao releases may require audit
1525
+ * devices to be declared in server configuration instead of via the API.
1526
+ */
1527
+ enable(path: string, options: {
1528
+ type: string;
1529
+ description?: string;
1530
+ options?: Record<string, string>;
1531
+ local?: boolean;
1532
+ }, opts?: CallOptions): Promise<void>;
1533
+ disable(path: string, opts?: CallOptions): Promise<void>;
1534
+ /** Hashes `input` with the audit device's HMAC key (`sys/audit-hash`). */
1535
+ hash(path: string, input: string, opts?: CallOptions): Promise<string>;
1536
+ }
1537
+ /** `sys/namespaces` — namespace management. */
1538
+ declare class SysNamespaces {
1539
+ private readonly client;
1540
+ constructor(client: OpenBaoCore);
1541
+ /** Lists child namespaces of the current namespace. */
1542
+ list(opts?: CallOptions & ListOptions): Promise<{
1543
+ keys: string[];
1544
+ key_info: Record<string, NamespaceInfo>;
1545
+ }>;
1546
+ read(path: string, opts?: CallOptions): Promise<NamespaceInfo>;
1547
+ create(path: string, options?: {
1548
+ custom_metadata?: Record<string, string>;
1549
+ seal?: unknown;
1550
+ } & CallOptions): Promise<NamespaceInfo>;
1551
+ /** Merge-patches a namespace's custom metadata. */
1552
+ patch(path: string, custom_metadata: Record<string, string | null>, opts?: CallOptions): Promise<NamespaceInfo>;
1553
+ delete(path: string, opts?: CallOptions): Promise<void>;
1554
+ sealStatus(path: string, opts?: CallOptions): Promise<SealStatus>;
1555
+ seal(path: string, opts?: CallOptions): Promise<void>;
1556
+ unseal(path: string, key: string, options?: {
1557
+ reset?: boolean;
1558
+ } & CallOptions): Promise<SealStatus>;
1559
+ }
1560
+ /** System backend (`/v1/sys/*`). */
1561
+ declare class Sys {
1562
+ private readonly client;
1563
+ readonly mounts: SysMounts;
1564
+ readonly auth: SysAuth;
1565
+ readonly policies: {
1566
+ acl: SysAclPolicies;
1567
+ password: SysPasswordPolicies;
1568
+ };
1569
+ readonly leases: SysLeases;
1570
+ readonly wrapping: SysWrapping;
1571
+ readonly tools: SysTools;
1572
+ readonly audit: SysAudit;
1573
+ readonly namespaces: SysNamespaces;
1574
+ constructor(client: OpenBaoCore);
1575
+ /**
1576
+ * Node health. Never throws for sealed / standby / uninitialized states —
1577
+ * inspect the returned flags instead. Unauthenticated.
1578
+ */
1579
+ health(options?: HealthOptions): Promise<HealthStatus>;
1580
+ sealStatus(opts?: CallOptions): Promise<SealStatus>;
1581
+ seal(opts?: CallOptions): Promise<void>;
1582
+ /** Submits one unseal key share. */
1583
+ unseal(key: string, options?: {
1584
+ reset?: boolean;
1585
+ migrate?: boolean;
1586
+ } & CallOptions): Promise<SealStatus>;
1587
+ /** Resets unseal progress. */
1588
+ unsealReset(opts?: CallOptions): Promise<SealStatus>;
1589
+ initStatus(opts?: CallOptions): Promise<boolean>;
1590
+ /** Initializes a new server. Returns unseal keys and the initial root token. */
1591
+ init(options?: InitOptions, opts?: CallOptions): Promise<InitResult>;
1592
+ leader(opts?: CallOptions): Promise<LeaderStatus>;
1593
+ haStatus(opts?: CallOptions): Promise<{
1594
+ nodes: Array<Record<string, unknown>>;
1595
+ }>;
1596
+ stepDown(opts?: CallOptions): Promise<void>;
1597
+ keyStatus(opts?: CallOptions): Promise<{
1598
+ term: number;
1599
+ install_time: string;
1600
+ encryptions?: number;
1601
+ }>;
1602
+ /** Rotates the backend encryption key. */
1603
+ rotate(opts?: CallOptions): Promise<void>;
1604
+ hostInfo(opts?: CallOptions): Promise<Record<string, unknown>>;
1605
+ /** Versions this cluster has run, keyed by version string. */
1606
+ versionHistory(opts?: CallOptions): Promise<{
1607
+ keys: string[];
1608
+ key_info: Record<string, {
1609
+ build_date: string;
1610
+ previous_version: string | null;
1611
+ timestamp_installed: string;
1612
+ }>;
1613
+ }>;
1614
+ /** Returns `{ [path]: capabilities[] }` for the given token (or the client token via `capabilitiesSelf`). */
1615
+ capabilities(token: string, paths: string[], opts?: CallOptions): Promise<Record<string, string[]>>;
1616
+ capabilitiesSelf(paths: string[], opts?: CallOptions): Promise<Record<string, string[]>>;
1617
+ capabilitiesAccessor(accessor: string, paths: string[], opts?: CallOptions): Promise<Record<string, string[]>>;
1618
+ /** Prometheus-format metrics (text) or JSON metrics. */
1619
+ metrics(format?: 'prometheus' | 'json', opts?: CallOptions): Promise<string | Record<string, unknown>>;
1620
+ }
1621
+
1622
+ /**
1623
+ * OpenBao API client.
1624
+ *
1625
+ * ```ts
1626
+ * const bao = new OpenBao({ address: 'https://bao.example.com', token: process.env.BAO_TOKEN });
1627
+ *
1628
+ * await bao.kv2('secret').write('app/db', { password: 's3cr3t' });
1629
+ * const { password } = await bao.kv2('secret').get('app/db');
1630
+ *
1631
+ * const ct = await bao.transit().encrypt('my-key', 'hello');
1632
+ * ```
1633
+ *
1634
+ * Mount-based engines are created by factory methods that take the mount path
1635
+ * (with sensible defaults), so any number of mounts can be used side by side.
1636
+ */
1637
+ declare class OpenBao extends OpenBaoCore {
1638
+ private _sys?;
1639
+ private _auth?;
1640
+ private _identity?;
1641
+ private _cubbyhole?;
1642
+ constructor(options?: OpenBaoOptions);
1643
+ /** System backend: health, seal, mounts, policies, leases, wrapping, namespaces, ... */
1644
+ get sys(): Sys;
1645
+ /** Auth methods: `auth.token`, `auth.approle()`, `auth.userpass()`, `auth.jwt()`, ... */
1646
+ get auth(): Auth;
1647
+ /** Identity secrets engine: entities, groups, aliases, OIDC identity tokens. */
1648
+ get identity(): Identity;
1649
+ /** The token's private cubbyhole. */
1650
+ get cubbyhole(): Cubbyhole;
1651
+ /** KV version 2 engine mounted at `mount` (default `secret`). */
1652
+ kv2(mount?: string): KvV2;
1653
+ /** Alias of {@link kv2} — KV v2 is the default KV engine. */
1654
+ kv(mount?: string): KvV2;
1655
+ /** KV version 1 engine mounted at `mount` (default `kv`). */
1656
+ kv1(mount?: string): KvV1;
1657
+ /** Transit engine mounted at `mount` (default `transit`). */
1658
+ transit(mount?: string): Transit;
1659
+ /** PKI engine mounted at `mount` (default `pki`). */
1660
+ pki(mount?: string): Pki;
1661
+ /** Database engine mounted at `mount` (default `database`). */
1662
+ database(mount?: string): Database;
1663
+ /** TOTP engine mounted at `mount` (default `totp`). */
1664
+ totp(mount?: string): Totp;
1665
+ /** SSH engine mounted at `mount` (default `ssh`). */
1666
+ ssh(mount?: string): Ssh;
1667
+ /**
1668
+ * Returns an independent client bound to another namespace. Token changes on
1669
+ * the returned client do not affect this one.
1670
+ */
1671
+ withNamespace(namespace: string | undefined): OpenBao;
1672
+ /** Returns an independent client that authenticates with `token`. */
1673
+ withToken(token: string | undefined): OpenBao;
1674
+ /** Returns an independent copy of this client with some settings overridden. */
1675
+ clone(overrides?: Partial<Pick<OpenBaoOptions, 'token' | 'namespace' | 'headers' | 'timeout' | 'retry'>>): OpenBao;
1676
+ }
1677
+
1678
+ /**
1679
+ * Thrown when OpenBao answers with a non-success HTTP status.
1680
+ *
1681
+ * OpenBao reports failures as `{ "errors": ["message", ...] }`; those messages
1682
+ * are exposed on {@link OpenBaoError.errors} and joined into `message`.
1683
+ */
1684
+ declare class OpenBaoError extends Error {
1685
+ readonly name: string;
1686
+ /** HTTP status code returned by the server. */
1687
+ readonly status: number;
1688
+ /** Error messages from the response body's `errors` array. */
1689
+ readonly errors: string[];
1690
+ /** Warnings returned alongside the error, if any. */
1691
+ readonly warnings: string[];
1692
+ /** HTTP method of the failed request. */
1693
+ readonly method: string;
1694
+ /** API path of the failed request (relative to `/v1/`). */
1695
+ readonly path: string;
1696
+ /** Parsed response body (or raw text when it was not JSON). */
1697
+ readonly body: unknown;
1698
+ constructor(init: {
1699
+ status: number;
1700
+ method: string;
1701
+ path: string;
1702
+ errors?: string[];
1703
+ warnings?: string[];
1704
+ body?: unknown;
1705
+ });
1706
+ /** `true` for 404 Not Found — e.g. reading a secret that does not exist. */
1707
+ get isNotFound(): boolean;
1708
+ /** `true` for 403 Forbidden — missing/invalid token or insufficient policy. */
1709
+ get isForbidden(): boolean;
1710
+ /** `true` when the server reports it is sealed (503 + "sealed" message). */
1711
+ get isSealed(): boolean;
1712
+ }
1713
+ /** Thrown when a request could not be completed (network failure, timeout, abort). */
1714
+ declare class OpenBaoConnectionError extends Error {
1715
+ readonly name: string;
1716
+ readonly method: string;
1717
+ readonly path: string;
1718
+ /** `true` when the request was aborted because the configured timeout elapsed. */
1719
+ readonly timedOut: boolean;
1720
+ constructor(init: {
1721
+ method: string;
1722
+ path: string;
1723
+ cause: unknown;
1724
+ timedOut?: boolean;
1725
+ });
1726
+ }
1727
+ /** Type guard for {@link OpenBaoError}. */
1728
+ declare function isOpenBaoError(err: unknown): err is OpenBaoError;
1729
+ /** `true` when `err` is an {@link OpenBaoError} with status 404. */
1730
+ declare function isNotFound(err: unknown): boolean;
1731
+
1732
+ /** Base64-encodes a UTF-8 string or raw bytes (works in Node, Deno, Bun and browsers). */
1733
+ declare function toBase64(input: string | Uint8Array): string;
1734
+ /** Decodes base64 into bytes. */
1735
+ declare function fromBase64(b64: string): Uint8Array;
1736
+ /** Decodes base64 into a UTF-8 string. */
1737
+ declare function fromBase64String(b64: string): string;
1738
+
1739
+ export { AppRoleAuth, Auth, AuthMethodApi, CertAuth, Cubbyhole, Database, GenericAuth, Identity, IdentityCollection, JwtAuth, KerberosAuth, KubernetesAuth, KvV1, KvV2, LdapAuth, MountedApi, OpenBao, OpenBaoConnectionError, OpenBaoCore, OpenBaoError, Pki, RadiusAuth, Resource, Ssh, Sys, SysAclPolicies, SysAudit, SysAuth, SysLeases, SysMounts, SysNamespaces, SysPasswordPolicies, SysTools, SysWrapping, TokenAuth, Totp, Transit, UserpassAuth, fromBase64, fromBase64String, isNotFound, isOpenBaoError, toBase64, unwrapData };
1740
+ export type { ApiResponse, AppRoleRole, AuditDevice, AuthInfo, BatchDecryptItem, BatchEncryptItem, BatchResult, BinaryLike, CallOptions, CertificateRequest, CreateTokenOptions, CreateTransitKeyOptions, DatabaseConnectionConfig, DatabaseCredentials, DatabaseRole, DatabaseStaticRole, DecryptOptions, Duration, EnableAuthOptions, EnableMountOptions, EncryptOptions, Entity, EntityAlias, EntityInput, FetchLike, GenerateRootOptions, GeneratedSecretId, Group, GroupInput, HashAlgorithm, HealthOptions, HealthStatus, HttpMethod, InitOptions, InitResult, IssuedCertificate, JwtConfig, JwtRole, KubernetesRole, KvV2Config, KvV2Metadata, KvV2MetadataInput, KvV2Secret, KvV2VersionMetadata, LeaderStatus, LeaseInfo, ListData, ListOptions, LoginOptions, MountConfig, MountInfo, NamespaceInfo, OpenBaoOptions, PkiRole, Query, QueryValue, RequestOptions, RetryOptions, SealStatus, SecretData, SecretIdOptions, SignOptions, SshRole, SshSignOptions, StaticCredentials, TokenFields, TokenLookup, TokenRole, TotpKey, TotpKeyOptions, TransitKey, TransitKeyConfig, TransitKeyType, UserpassUser, WrapInfo };