@marinoscar/vault-contract 0.0.0-stage → 0.1.0-next.3
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.
- package/CHANGELOG.md +23 -0
- package/LICENSE +21 -0
- package/README.md +71 -2
- package/dist/cjs/agent/index.d.ts +391 -0
- package/dist/cjs/agent/index.js +270 -0
- package/dist/cjs/backups/backup-contents.d.ts +80 -0
- package/dist/cjs/backups/backup-contents.js +121 -0
- package/dist/cjs/backups/index.d.ts +130 -0
- package/dist/cjs/backups/index.js +270 -0
- package/dist/cjs/backups/responses.d.ts +76 -0
- package/dist/cjs/backups/responses.js +2 -0
- package/dist/cjs/common/index.d.ts +21 -0
- package/dist/cjs/common/index.js +27 -0
- package/dist/cjs/errors/index.d.ts +54 -0
- package/dist/cjs/errors/index.js +65 -0
- package/dist/cjs/index.d.ts +12 -0
- package/dist/cjs/index.js +15 -0
- package/dist/cjs/media/index.d.ts +55 -0
- package/dist/cjs/media/index.js +42 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/secret-types/index.d.ts +132 -0
- package/dist/cjs/secret-types/index.js +215 -0
- package/dist/cjs/secrets/index.d.ts +199 -0
- package/dist/cjs/secrets/index.js +172 -0
- package/dist/cjs/secrets/origins.d.ts +44 -0
- package/dist/cjs/secrets/origins.js +103 -0
- package/dist/cjs/secrets/totp.d.ts +41 -0
- package/dist/cjs/secrets/totp.js +139 -0
- package/dist/esm/agent/index.d.ts +391 -0
- package/dist/esm/agent/index.js +267 -0
- package/dist/esm/backups/backup-contents.d.ts +80 -0
- package/dist/esm/backups/backup-contents.js +114 -0
- package/dist/esm/backups/index.d.ts +130 -0
- package/dist/esm/backups/index.js +251 -0
- package/dist/esm/backups/responses.d.ts +76 -0
- package/dist/esm/backups/responses.js +1 -0
- package/dist/esm/common/index.d.ts +21 -0
- package/dist/esm/common/index.js +23 -0
- package/dist/esm/errors/index.d.ts +54 -0
- package/dist/esm/errors/index.js +61 -0
- package/dist/esm/index.d.ts +12 -0
- package/dist/esm/index.js +12 -0
- package/dist/esm/media/index.d.ts +55 -0
- package/dist/esm/media/index.js +39 -0
- package/dist/esm/package.json +1 -0
- package/dist/esm/secret-types/index.d.ts +132 -0
- package/dist/esm/secret-types/index.js +212 -0
- package/dist/esm/secrets/index.d.ts +199 -0
- package/dist/esm/secrets/index.js +155 -0
- package/dist/esm/secrets/origins.d.ts +44 -0
- package/dist/esm/secrets/origins.js +96 -0
- package/dist/esm/secrets/totp.d.ts +41 -0
- package/dist/esm/secrets/totp.js +134 -0
- package/package.json +130 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# @marinoscar/vault-contract
|
|
2
|
+
|
|
3
|
+
## 0.1.0-next.3
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- d16fe7b: The package READMEs say how to install from npm (the `next` dist-tag, the peers, provenance) for the first published release (#192). No code change.
|
|
8
|
+
|
|
9
|
+
## 0.1.0-next.2
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- 14f844c: Add the owner's agent trail and agent notifications (E14.7). `GET /api/agent-activity` (`secrets:read`, session or PAT; an OAuth token is refused with the new `403 AGENT_ACTIVITY_FORBIDDEN`) lists the caller's own agent events (`lookup`, `fill`, `totp`, `create`, `rotate` and the `agent_access` toggle), filterable by action, secret, app and date, paginated, never carrying a value. New `agentActivity*` schemas and `AGENT_ACTIVITY_PATH` in `@marinoscar/vault-contract/agent`. New notification events `vault.agent_credential_changed` (email + bell), `vault.agent_new_app` (email + bell) and `vault.agent_credential_used` (bell only, counted), raised by `AgentNotifier` after the audit row is written; `VaultNotifyPort` now includes `notifyCounted` and `RecordingNotify` records it.
|
|
14
|
+
- a9726a7: Add the agent credential API on the `agent` OAuth resource (`/api/agent/v1`, accepts `oat_` and `pat_` credentials): `GET /credentials?origin=`, `POST /credentials/:id/fill` (one field per call, exact origin only), `POST /credentials/:id/totp`, `POST /credentials` (with a CSPRNG-generated password returned once) and `POST /credentials/:id/password` (rotation as a new version). Kill switch `agentAccess.enabled` (default off) and per-minute limits in the `agentAccess` system settings namespace, an in-memory `AgentRateLimiter`, audit rows `agent.credential.lookup|fill|totp|create|rotate`, and `Cache-Control: no-store` on every response. New `@marinoscar/vault-contract/agent` subpath (experimental provider contract: request and response schemas, `AGENT_ERROR_CODES`, `AGENT_AUDIT_ACTIONS`, settings schema) and error codes `ORIGIN_MISMATCH`, `AGENT_ACCESS_DISABLED`, `AGENT_CREDENTIAL_REQUIRED` (403) and `RATE_LIMITED` (429).
|
|
15
|
+
- 60b975f: Add per-secret agent access: `PATCH /api/secrets/:id/agent-access` (`secrets:write`, refused for an OAuth credential, only a `Credential` may be `fill`, audited `secrets.agent_access.update`), the `agentAccess` list filter, `agentAccess` and `agentAccessChangedAt` on secret responses, the `AGENT_ACCESS_UNSUPPORTED_TYPE` (422) error code, and `SecretsService.findAgentAccessibleSecret` / `assertAgentAccessible` for the agent API.
|
|
16
|
+
- 9a5a86d: vault-contract: `Credential` gains the optional `additional_urls` field, and `normalizeOrigin`, `originsFromCredential`, `matchOrigin` and `registrableDomainOfOrigin` (exact or same-site matching via the Public Suffix List). vault-api: `secrets.origins` is recomputed on every new Credential version, `SecretsService.findCredentialsByOrigin(userId, origin)` and the server-only `vault.secrets.origins.backfill` job.
|
|
17
|
+
- d85c2f9: Add TOTP on Credential secrets: an optional sensitive `totp` field (Authenticator key) normalized on save to a canonical `otpauth://totp` URI (`parseTotpSecret`, `toCanonicalOtpauthUri`, `normalizeTotpSecret` in `@marinoscar/vault-contract/secrets`; an invalid value is a 400 field error), `generateTotp` (RFC 6238) and `POST /api/secrets/:id/totp` (`secrets:read`, `Cache-Control: no-store`, audited `secret.totp.read`, the seed is never returned), plus `SecretsService.generateTotpForSecret` and `hasTotp` for the agent API.
|
|
18
|
+
|
|
19
|
+
## 0.1.0-next.1
|
|
20
|
+
|
|
21
|
+
## 0.1.0-next.0
|
|
22
|
+
|
|
23
|
+
- Initial version (E12.1, issue 102). Moved out of `apps/api` and `apps/web` without changing behaviour or a field; see the README.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Oscar Marin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,72 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @marinoscar/vault-contract
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The wire contract of the Vault domain: the Zod schemas of the requests and queries, the response shapes of the backups API, the domain error codes and the system secret-type definitions that the API, the web app and any other host share. Dual CommonJS and ESM, `sideEffects: false`, free of any framework or Node built-in, so it loads in the browser too.
|
|
4
|
+
|
|
5
|
+
## Purpose and scope
|
|
6
|
+
|
|
7
|
+
The package holds the shape of the domain's HTTP traffic and nothing that behaves: no service, no controller, no component and no database access. The API wraps the schemas in `createZodDto` classes, the web types its requests with them, and a second host gets the same contract by installing one package. It does not hold the platform's shapes (they come from `@marinoscar/platform-contract`), the scheduling math of `computeNextRunAt`, or anything server-only.
|
|
8
|
+
|
|
9
|
+
Status: experimental. Introduced in E12.1 (issue 102) by moving the schemas out of the API's `dto/` files with no change to a field name, a limit or a message; the API's DTO files re-export them under their old names.
|
|
10
|
+
|
|
11
|
+
Entry points (every schema and constant is in a slice; the root exports only `VAULT_CONTRACT_PACKAGE`):
|
|
12
|
+
|
|
13
|
+
- `@marinoscar/vault-contract/secrets`: create, update, list, renew, attachment and card-summary bodies and queries, `attachmentRoleSchema`, the attachment response.
|
|
14
|
+
- `@marinoscar/vault-contract/secret-types`: field definitions, create/update/query bodies, `CARD_NETWORKS`, `CARD_KINDS`, `SYSTEM_SECRET_TYPES` (the built-in types, append-only).
|
|
15
|
+
- `@marinoscar/vault-contract/backups`: content-selection rules (`BACKUP_CONTENT_*`, `contentSelectionIssues`, `resolveContentSelection`), the schedule vocabulary and validators, the user export, system export and schedule schemas, the run list query, and the backups API response types.
|
|
16
|
+
- `@marinoscar/vault-contract/media`: folder and file bodies and queries.
|
|
17
|
+
- `@marinoscar/vault-contract/agent`: the provider contract of the agent credential API (`/api/agent/v1`, experimental): lookup, fill, totp, create and rotate request and response schemas, `agentPurposeSchema`, the generated-password options, `AGENT_ERROR_CODES` (`ORIGIN_MISMATCH`, `AGENT_ACCESS_DISABLED`, `AGENT_CREDENTIAL_REQUIRED`, `RATE_LIMITED`), `AGENT_AUDIT_ACTIONS`, `AGENT_SCOPES` and the `agentAccess` settings schema and defaults.
|
|
18
|
+
- `@marinoscar/vault-contract/errors`: `VAULT_ERROR_CODES` (code, status, description), `AI_ERROR_CODES`, `isVaultErrorCode`.
|
|
19
|
+
- `@marinoscar/vault-contract/common`: `typeErrors`, the Zod 4 replacement for `required_error` / `invalid_type_error`.
|
|
20
|
+
|
|
21
|
+
## Install and peer dependencies
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm install @marinoscar/vault-contract@next zod@^4.4.3
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Published to npm under the `next` dist-tag until 1.0, with a provenance attestation; the install, the dist-tag policy and the current publication status are in [docs/PACKAGES.md](../../docs/PACKAGES.md#installing-from-npm). The package works from CommonJS (`require`) and ESM (`import`), and its types resolve under `moduleResolution` `node16`, `nodenext` and `bundler`.
|
|
28
|
+
|
|
29
|
+
The package never bundles Zod, because a second copy breaks `instanceof ZodError` checks:
|
|
30
|
+
|
|
31
|
+
| Package | Range | Needed by |
|
|
32
|
+
|---|---|---|
|
|
33
|
+
| `zod` | `^4.4.3` | every slice (required) |
|
|
34
|
+
|
|
35
|
+
## Quick start
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
import { createSecretSchema } from '@marinoscar/vault-contract/secrets';
|
|
39
|
+
import { VAULT_ERROR_CODES } from '@marinoscar/vault-contract/errors';
|
|
40
|
+
// CommonJS: const { createSecretSchema } = require('@marinoscar/vault-contract/secrets');
|
|
41
|
+
|
|
42
|
+
const body = createSecretSchema.parse(input);
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
In the API, import the DTO class from the module's `dto/` file as before; the schema behind it is the one above. The error codes are data: `app-registrations/error-codes.ts` registers them with the platform. Keep the `.js` extension on every relative import inside the package; the ESM build fails at run time without it.
|
|
46
|
+
|
|
47
|
+
## Configuration
|
|
48
|
+
|
|
49
|
+
None. The package reads no environment variable and takes no option.
|
|
50
|
+
|
|
51
|
+
## Extension-point catalog
|
|
52
|
+
|
|
53
|
+
None. A new code, schema or constant is added here, in the slice that owns it, with a test; a host never extends the package at run time.
|
|
54
|
+
|
|
55
|
+
## Build and test
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npm run build -w @marinoscar/vault-contract # dist/cjs and dist/esm, with a package.json stub in each
|
|
59
|
+
npm run test:run -w @marinoscar/vault-contract # Vitest
|
|
60
|
+
npm run typecheck -w @marinoscar/vault-contract
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The apps import the built output, so build the packages after `npm ci` and before the app's typecheck or tests (`npm run build:packages` at the root).
|
|
64
|
+
|
|
65
|
+
## Security notes
|
|
66
|
+
|
|
67
|
+
Schemas validate shape and size only. Every message is static text and never echoes a submitted value; the export and schedule schemas are written so a validation error can be logged without leaking a backup password. No schema or constant holds a secret.
|
|
68
|
+
|
|
69
|
+
## Links
|
|
70
|
+
|
|
71
|
+
- [The Vault packages](../../docs/PACKAGES.md)
|
|
72
|
+
- [ADR-0001: packages first](../../docs/decisions/0001-packages-first.md)
|
|
@@ -0,0 +1,391 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
/**
|
|
3
|
+
* The agent credential API (`/api/agent/v1`, the `agent` OAuth protected resource): the provider
|
|
4
|
+
* contract an external agent runtime (a browser fabric, an MCP host) codes against. A runtime finds
|
|
5
|
+
* the login for the site on screen, asks for exactly ONE field at a time so it can type it without
|
|
6
|
+
* showing it to a model, reads a one-time code, saves a new login with a generated password and
|
|
7
|
+
* rotates a password.
|
|
8
|
+
*
|
|
9
|
+
* Request and response shapes only. Behaviour (origin binding, the kill switch, rate limits, audit)
|
|
10
|
+
* is the API's; the error codes are in {@link AGENT_ERROR_CODES}. The path carries the version: an
|
|
11
|
+
* incompatible change is `/api/agent/v2`.
|
|
12
|
+
*
|
|
13
|
+
* @packageDocumentation
|
|
14
|
+
*/
|
|
15
|
+
/** The API's base path (the `agent` protected resource). @stability experimental */
|
|
16
|
+
export declare const AGENT_API_BASE_PATH: "/api/agent/v1";
|
|
17
|
+
/**
|
|
18
|
+
* The OAuth scope ids of the agent resource (permanent: clients persist them). The platform's scope
|
|
19
|
+
* id pattern rules out dots, so they are `vault:items_*`.
|
|
20
|
+
*
|
|
21
|
+
* @stability experimental
|
|
22
|
+
*/
|
|
23
|
+
export declare const AGENT_SCOPES: {
|
|
24
|
+
readonly ITEMS_READ: "vault:items_read";
|
|
25
|
+
readonly ITEMS_FILL: "vault:items_fill";
|
|
26
|
+
readonly ITEMS_WRITE: "vault:items_write";
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* Error codes of the agent API, as they appear in `{ code }`. They are also in
|
|
30
|
+
* `VAULT_ERROR_CODES` (`@marinoscar/vault-contract/errors`) with their statuses.
|
|
31
|
+
*
|
|
32
|
+
* @stability experimental
|
|
33
|
+
*/
|
|
34
|
+
export declare const AGENT_ERROR_CODES: {
|
|
35
|
+
/** 403: the `origin` is not exactly one of the credential's origins. */
|
|
36
|
+
readonly ORIGIN_MISMATCH: "ORIGIN_MISMATCH";
|
|
37
|
+
/** 403: the deployment's `agentAccess.enabled` switch is off. */
|
|
38
|
+
readonly AGENT_ACCESS_DISABLED: "AGENT_ACCESS_DISABLED";
|
|
39
|
+
/** 403: the request authenticated with something other than an `oat_` or `pat_` token (a browser session). */
|
|
40
|
+
readonly AGENT_CREDENTIAL_REQUIRED: "AGENT_CREDENTIAL_REQUIRED";
|
|
41
|
+
/** 429: the per-minute limit of the call's bucket was reached; see `Retry-After`. */
|
|
42
|
+
readonly RATE_LIMITED: "RATE_LIMITED";
|
|
43
|
+
/** 403: `GET /api/agent-activity` was called with an OAuth access token; an agent cannot read its own trail. */
|
|
44
|
+
readonly AGENT_ACTIVITY_FORBIDDEN: "AGENT_ACTIVITY_FORBIDDEN";
|
|
45
|
+
};
|
|
46
|
+
/** @stability experimental */
|
|
47
|
+
export type AgentErrorCode = (typeof AGENT_ERROR_CODES)[keyof typeof AGENT_ERROR_CODES];
|
|
48
|
+
/**
|
|
49
|
+
* Why the agent is asking: stored in the audit row of fill, totp, create and rotate.
|
|
50
|
+
*
|
|
51
|
+
* @stability experimental
|
|
52
|
+
*/
|
|
53
|
+
export declare const agentPurposeSchema: z.ZodEnum<{
|
|
54
|
+
login: "login";
|
|
55
|
+
signup: "signup";
|
|
56
|
+
password_change: "password_change";
|
|
57
|
+
mfa: "mfa";
|
|
58
|
+
}>;
|
|
59
|
+
/** @stability experimental */
|
|
60
|
+
export type AgentPurpose = z.infer<typeof agentPurposeSchema>;
|
|
61
|
+
/** The one field a fill call returns. @stability experimental */
|
|
62
|
+
export declare const agentFillFieldSchema: z.ZodEnum<{
|
|
63
|
+
username: "username";
|
|
64
|
+
password: "password";
|
|
65
|
+
}>;
|
|
66
|
+
/** @stability experimental */
|
|
67
|
+
export type AgentFillField = z.infer<typeof agentFillFieldSchema>;
|
|
68
|
+
/** An origin as the agent sees it: a URL or bare host, normalized by the API. @stability experimental */
|
|
69
|
+
export declare const agentOriginSchema: z.ZodString;
|
|
70
|
+
/** Query of `GET /api/agent/v1/credentials`. @stability experimental */
|
|
71
|
+
export declare const agentLookupQuerySchema: z.ZodObject<{
|
|
72
|
+
origin: z.ZodString;
|
|
73
|
+
}, z.core.$strip>;
|
|
74
|
+
/** @stability experimental */
|
|
75
|
+
export type AgentLookupQuery = z.infer<typeof agentLookupQuerySchema>;
|
|
76
|
+
/** One credential found for an origin. Never carries a sensitive value. @stability experimental */
|
|
77
|
+
export declare const agentCredentialSummarySchema: z.ZodObject<{
|
|
78
|
+
id: z.ZodString;
|
|
79
|
+
name: z.ZodString;
|
|
80
|
+
username: z.ZodNullable<z.ZodString>;
|
|
81
|
+
origins: z.ZodArray<z.ZodString>;
|
|
82
|
+
matchKind: z.ZodEnum<{
|
|
83
|
+
exact: "exact";
|
|
84
|
+
site: "site";
|
|
85
|
+
}>;
|
|
86
|
+
hasTotp: z.ZodBoolean;
|
|
87
|
+
updatedAt: z.ZodString;
|
|
88
|
+
}, z.core.$strip>;
|
|
89
|
+
/** @stability experimental */
|
|
90
|
+
export type AgentCredentialSummary = z.infer<typeof agentCredentialSummarySchema>;
|
|
91
|
+
/** Response of `GET /api/agent/v1/credentials`. Exact matches first. @stability experimental */
|
|
92
|
+
export declare const agentLookupResponseSchema: z.ZodObject<{
|
|
93
|
+
data: z.ZodArray<z.ZodObject<{
|
|
94
|
+
id: z.ZodString;
|
|
95
|
+
name: z.ZodString;
|
|
96
|
+
username: z.ZodNullable<z.ZodString>;
|
|
97
|
+
origins: z.ZodArray<z.ZodString>;
|
|
98
|
+
matchKind: z.ZodEnum<{
|
|
99
|
+
exact: "exact";
|
|
100
|
+
site: "site";
|
|
101
|
+
}>;
|
|
102
|
+
hasTotp: z.ZodBoolean;
|
|
103
|
+
updatedAt: z.ZodString;
|
|
104
|
+
}, z.core.$strip>>;
|
|
105
|
+
}, z.core.$strip>;
|
|
106
|
+
/** Body of `POST /api/agent/v1/credentials/:id/fill`. @stability experimental */
|
|
107
|
+
export declare const agentFillRequestSchema: z.ZodObject<{
|
|
108
|
+
field: z.ZodEnum<{
|
|
109
|
+
username: "username";
|
|
110
|
+
password: "password";
|
|
111
|
+
}>;
|
|
112
|
+
origin: z.ZodString;
|
|
113
|
+
purpose: z.ZodEnum<{
|
|
114
|
+
login: "login";
|
|
115
|
+
signup: "signup";
|
|
116
|
+
password_change: "password_change";
|
|
117
|
+
mfa: "mfa";
|
|
118
|
+
}>;
|
|
119
|
+
}, z.core.$strip>;
|
|
120
|
+
/** @stability experimental */
|
|
121
|
+
export type AgentFillRequest = z.infer<typeof agentFillRequestSchema>;
|
|
122
|
+
/** Response of the fill route: one value. Type it, never show it to a model. @stability experimental */
|
|
123
|
+
export declare const agentFillResponseSchema: z.ZodObject<{
|
|
124
|
+
data: z.ZodObject<{
|
|
125
|
+
value: z.ZodString;
|
|
126
|
+
}, z.core.$strip>;
|
|
127
|
+
}, z.core.$strip>;
|
|
128
|
+
/** Body of `POST /api/agent/v1/credentials/:id/totp`. @stability experimental */
|
|
129
|
+
export declare const agentTotpRequestSchema: z.ZodObject<{
|
|
130
|
+
origin: z.ZodString;
|
|
131
|
+
purpose: z.ZodEnum<{
|
|
132
|
+
login: "login";
|
|
133
|
+
signup: "signup";
|
|
134
|
+
password_change: "password_change";
|
|
135
|
+
mfa: "mfa";
|
|
136
|
+
}>;
|
|
137
|
+
}, z.core.$strip>;
|
|
138
|
+
/** @stability experimental */
|
|
139
|
+
export type AgentTotpRequest = z.infer<typeof agentTotpRequestSchema>;
|
|
140
|
+
/** Response of the totp route. `expiresAt` is an ISO timestamp. @stability experimental */
|
|
141
|
+
export declare const agentTotpResponseSchema: z.ZodObject<{
|
|
142
|
+
data: z.ZodObject<{
|
|
143
|
+
code: z.ZodString;
|
|
144
|
+
expiresAt: z.ZodString;
|
|
145
|
+
}, z.core.$strip>;
|
|
146
|
+
}, z.core.$strip>;
|
|
147
|
+
/** Smallest and largest generated password length. @stability experimental */
|
|
148
|
+
export declare const AGENT_GENERATED_PASSWORD_MIN_LENGTH = 12;
|
|
149
|
+
/** @stability experimental */
|
|
150
|
+
export declare const AGENT_GENERATED_PASSWORD_MAX_LENGTH = 128;
|
|
151
|
+
/** Length of a generated password when `generate.length` is omitted. @stability experimental */
|
|
152
|
+
export declare const AGENT_GENERATED_PASSWORD_DEFAULT_LENGTH = 24;
|
|
153
|
+
/**
|
|
154
|
+
* Ask Vault to generate the password: `length` 12 to 128 (default 24), `symbols` (default true).
|
|
155
|
+
* The result has at least one lower-case letter, upper-case letter and digit, and one symbol when
|
|
156
|
+
* `symbols` is on.
|
|
157
|
+
*
|
|
158
|
+
* @stability experimental
|
|
159
|
+
*/
|
|
160
|
+
export declare const agentGeneratePasswordSchema: z.ZodObject<{
|
|
161
|
+
length: z.ZodDefault<z.ZodNumber>;
|
|
162
|
+
symbols: z.ZodDefault<z.ZodBoolean>;
|
|
163
|
+
}, z.core.$strip>;
|
|
164
|
+
/** @stability experimental */
|
|
165
|
+
export type AgentGeneratePassword = z.infer<typeof agentGeneratePasswordSchema>;
|
|
166
|
+
/** Body of `POST /api/agent/v1/credentials`: exactly one of `password` and `generate`. @stability experimental */
|
|
167
|
+
export declare const agentCreateCredentialRequestSchema: z.ZodObject<{
|
|
168
|
+
name: z.ZodString;
|
|
169
|
+
username: z.ZodString;
|
|
170
|
+
origin: z.ZodString;
|
|
171
|
+
additionalUrls: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
172
|
+
password: z.ZodOptional<z.ZodString>;
|
|
173
|
+
generate: z.ZodOptional<z.ZodObject<{
|
|
174
|
+
length: z.ZodDefault<z.ZodNumber>;
|
|
175
|
+
symbols: z.ZodDefault<z.ZodBoolean>;
|
|
176
|
+
}, z.core.$strip>>;
|
|
177
|
+
purpose: z.ZodEnum<{
|
|
178
|
+
login: "login";
|
|
179
|
+
signup: "signup";
|
|
180
|
+
password_change: "password_change";
|
|
181
|
+
mfa: "mfa";
|
|
182
|
+
}>;
|
|
183
|
+
}, z.core.$strip>;
|
|
184
|
+
/** @stability experimental */
|
|
185
|
+
export type AgentCreateCredentialRequest = z.infer<typeof agentCreateCredentialRequestSchema>;
|
|
186
|
+
/**
|
|
187
|
+
* Response of the create route. `generatedPassword` is present only when `generate` was sent, and
|
|
188
|
+
* only in this response: Vault never returns it again.
|
|
189
|
+
*
|
|
190
|
+
* @stability experimental
|
|
191
|
+
*/
|
|
192
|
+
export declare const agentCreateCredentialResponseSchema: z.ZodObject<{
|
|
193
|
+
data: z.ZodObject<{
|
|
194
|
+
id: z.ZodString;
|
|
195
|
+
name: z.ZodString;
|
|
196
|
+
username: z.ZodString;
|
|
197
|
+
origins: z.ZodArray<z.ZodString>;
|
|
198
|
+
generatedPassword: z.ZodOptional<z.ZodString>;
|
|
199
|
+
}, z.core.$strip>;
|
|
200
|
+
}, z.core.$strip>;
|
|
201
|
+
/** Body of `POST /api/agent/v1/credentials/:id/password`: exactly one of `password` and `generate`. @stability experimental */
|
|
202
|
+
export declare const agentRotatePasswordRequestSchema: z.ZodObject<{
|
|
203
|
+
origin: z.ZodString;
|
|
204
|
+
password: z.ZodOptional<z.ZodString>;
|
|
205
|
+
generate: z.ZodOptional<z.ZodObject<{
|
|
206
|
+
length: z.ZodDefault<z.ZodNumber>;
|
|
207
|
+
symbols: z.ZodDefault<z.ZodBoolean>;
|
|
208
|
+
}, z.core.$strip>>;
|
|
209
|
+
purpose: z.ZodEnum<{
|
|
210
|
+
login: "login";
|
|
211
|
+
signup: "signup";
|
|
212
|
+
password_change: "password_change";
|
|
213
|
+
mfa: "mfa";
|
|
214
|
+
}>;
|
|
215
|
+
}, z.core.$strip>;
|
|
216
|
+
/** @stability experimental */
|
|
217
|
+
export type AgentRotatePasswordRequest = z.infer<typeof agentRotatePasswordRequestSchema>;
|
|
218
|
+
/** Response of the rotate route: the new version number, and the generated value once. @stability experimental */
|
|
219
|
+
export declare const agentRotatePasswordResponseSchema: z.ZodObject<{
|
|
220
|
+
data: z.ZodObject<{
|
|
221
|
+
id: z.ZodString;
|
|
222
|
+
version: z.ZodNumber;
|
|
223
|
+
generatedPassword: z.ZodOptional<z.ZodString>;
|
|
224
|
+
}, z.core.$strip>;
|
|
225
|
+
}, z.core.$strip>;
|
|
226
|
+
/** Response of `GET /api/agent/v1/whoami`. @stability experimental */
|
|
227
|
+
export declare const agentWhoamiResponseSchema: z.ZodObject<{
|
|
228
|
+
data: z.ZodObject<{
|
|
229
|
+
userId: z.ZodString;
|
|
230
|
+
scopes: z.ZodArray<z.ZodString>;
|
|
231
|
+
clientId: z.ZodNullable<z.ZodString>;
|
|
232
|
+
}, z.core.$strip>;
|
|
233
|
+
}, z.core.$strip>;
|
|
234
|
+
/**
|
|
235
|
+
* The audit actions the agent API writes (`audit_events.action`), one per route. The `result` of
|
|
236
|
+
* the row's meta is `ok` or `denied:<reason>`.
|
|
237
|
+
*
|
|
238
|
+
* @stability experimental
|
|
239
|
+
*/
|
|
240
|
+
export declare const AGENT_AUDIT_ACTIONS: {
|
|
241
|
+
readonly LOOKUP: "agent.credential.lookup";
|
|
242
|
+
readonly FILL: "agent.credential.fill";
|
|
243
|
+
readonly TOTP: "agent.credential.totp";
|
|
244
|
+
readonly CREATE: "agent.credential.create";
|
|
245
|
+
readonly ROTATE: "agent.credential.rotate";
|
|
246
|
+
};
|
|
247
|
+
/** @stability experimental */
|
|
248
|
+
export type AgentAuditAction = (typeof AGENT_AUDIT_ACTIONS)[keyof typeof AGENT_AUDIT_ACTIONS];
|
|
249
|
+
/**
|
|
250
|
+
* The `agentAccess` system settings namespace: the kill switch and the per-minute limits of the
|
|
251
|
+
* agent API. `enabled` defaults to `false`: until an administrator switches it on, every agent
|
|
252
|
+
* route answers `403 AGENT_ACCESS_DISABLED`. Each limit counts per token (or OAuth grant) and user.
|
|
253
|
+
*
|
|
254
|
+
* @stability experimental
|
|
255
|
+
*/
|
|
256
|
+
export declare const agentAccessSettingsSchema: z.ZodObject<{
|
|
257
|
+
enabled: z.ZodBoolean;
|
|
258
|
+
lookupPerMinute: z.ZodNumber;
|
|
259
|
+
fillPerMinute: z.ZodNumber;
|
|
260
|
+
totpPerMinute: z.ZodNumber;
|
|
261
|
+
writePerMinute: z.ZodNumber;
|
|
262
|
+
}, z.core.$strip>;
|
|
263
|
+
/** @stability experimental */
|
|
264
|
+
export type AgentAccessSettings = z.infer<typeof agentAccessSettingsSchema>;
|
|
265
|
+
/** Defaults of {@link agentAccessSettingsSchema}: off, lookup 60, fill 30, totp 10, write 10 per minute. @stability experimental */
|
|
266
|
+
export declare const AGENT_ACCESS_SETTINGS_DEFAULTS: AgentAccessSettings;
|
|
267
|
+
/** The path of the owner's agent activity list (session or PAT, never an OAuth token). @stability experimental */
|
|
268
|
+
export declare const AGENT_ACTIVITY_PATH: "/api/agent-activity";
|
|
269
|
+
/** The audit action of the per-secret agent access toggle (`secret.agent_access.update`). @stability experimental */
|
|
270
|
+
export declare const AGENT_ACCESS_TOGGLE_AUDIT_ACTION: "secret.agent_access.update";
|
|
271
|
+
/** The actions an activity item carries: the five agent routes and the owner's toggle. @stability experimental */
|
|
272
|
+
export declare const agentActivityActionSchema: z.ZodEnum<{
|
|
273
|
+
lookup: "lookup";
|
|
274
|
+
fill: "fill";
|
|
275
|
+
totp: "totp";
|
|
276
|
+
create: "create";
|
|
277
|
+
rotate: "rotate";
|
|
278
|
+
agent_access: "agent_access";
|
|
279
|
+
}>;
|
|
280
|
+
/** @stability experimental */
|
|
281
|
+
export type AgentActivityAction = z.infer<typeof agentActivityActionSchema>;
|
|
282
|
+
/** The kind of credential a call authenticated with. @stability experimental */
|
|
283
|
+
export declare const agentActivityCredentialKindSchema: z.ZodEnum<{
|
|
284
|
+
oauth: "oauth";
|
|
285
|
+
pat: "pat";
|
|
286
|
+
session: "session";
|
|
287
|
+
}>;
|
|
288
|
+
/** @stability experimental */
|
|
289
|
+
export type AgentActivityCredentialKind = z.infer<typeof agentActivityCredentialKindSchema>;
|
|
290
|
+
/** The largest `pageSize` of the activity list. @stability experimental */
|
|
291
|
+
export declare const AGENT_ACTIVITY_MAX_PAGE_SIZE = 100;
|
|
292
|
+
/**
|
|
293
|
+
* Query of `GET /api/agent-activity`. `action` is one of {@link agentActivityActionSchema};
|
|
294
|
+
* `from` and `to` are ISO 8601 instants (inclusive); `clientId` is the OAuth client's id as on its grants (`OAuthGrant.clientId`, not the public client_id string).
|
|
295
|
+
*
|
|
296
|
+
* @stability experimental
|
|
297
|
+
*/
|
|
298
|
+
export declare const agentActivityQuerySchema: z.ZodObject<{
|
|
299
|
+
page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
300
|
+
pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
301
|
+
action: z.ZodOptional<z.ZodEnum<{
|
|
302
|
+
lookup: "lookup";
|
|
303
|
+
fill: "fill";
|
|
304
|
+
totp: "totp";
|
|
305
|
+
create: "create";
|
|
306
|
+
rotate: "rotate";
|
|
307
|
+
agent_access: "agent_access";
|
|
308
|
+
}>>;
|
|
309
|
+
secretId: z.ZodOptional<z.ZodString>;
|
|
310
|
+
clientId: z.ZodOptional<z.ZodString>;
|
|
311
|
+
from: z.ZodOptional<z.ZodString>;
|
|
312
|
+
to: z.ZodOptional<z.ZodString>;
|
|
313
|
+
}, z.core.$strip>;
|
|
314
|
+
/** @stability experimental */
|
|
315
|
+
export type AgentActivityQuery = z.infer<typeof agentActivityQuerySchema>;
|
|
316
|
+
/**
|
|
317
|
+
* One event of the owner's agent trail. Never carries a value, a code, a seed or a password.
|
|
318
|
+
* `reason` is present on a denial (`origin_mismatch`, `rate_limited`, `not_found`, ...).
|
|
319
|
+
*
|
|
320
|
+
* @stability experimental
|
|
321
|
+
*/
|
|
322
|
+
export declare const agentActivityItemSchema: z.ZodObject<{
|
|
323
|
+
id: z.ZodString;
|
|
324
|
+
at: z.ZodString;
|
|
325
|
+
action: z.ZodEnum<{
|
|
326
|
+
lookup: "lookup";
|
|
327
|
+
fill: "fill";
|
|
328
|
+
totp: "totp";
|
|
329
|
+
create: "create";
|
|
330
|
+
rotate: "rotate";
|
|
331
|
+
agent_access: "agent_access";
|
|
332
|
+
}>;
|
|
333
|
+
result: z.ZodEnum<{
|
|
334
|
+
ok: "ok";
|
|
335
|
+
denied: "denied";
|
|
336
|
+
}>;
|
|
337
|
+
reason: z.ZodOptional<z.ZodString>;
|
|
338
|
+
secretId: z.ZodNullable<z.ZodString>;
|
|
339
|
+
secretName: z.ZodNullable<z.ZodString>;
|
|
340
|
+
field: z.ZodNullable<z.ZodString>;
|
|
341
|
+
origin: z.ZodNullable<z.ZodString>;
|
|
342
|
+
purpose: z.ZodNullable<z.ZodString>;
|
|
343
|
+
credentialKind: z.ZodNullable<z.ZodEnum<{
|
|
344
|
+
oauth: "oauth";
|
|
345
|
+
pat: "pat";
|
|
346
|
+
session: "session";
|
|
347
|
+
}>>;
|
|
348
|
+
clientId: z.ZodNullable<z.ZodString>;
|
|
349
|
+
clientName: z.ZodNullable<z.ZodString>;
|
|
350
|
+
}, z.core.$strip>;
|
|
351
|
+
/** @stability experimental */
|
|
352
|
+
export type AgentActivityItem = z.infer<typeof agentActivityItemSchema>;
|
|
353
|
+
/** Response of `GET /api/agent-activity`. @stability experimental */
|
|
354
|
+
export declare const agentActivityResponseSchema: z.ZodObject<{
|
|
355
|
+
data: z.ZodArray<z.ZodObject<{
|
|
356
|
+
id: z.ZodString;
|
|
357
|
+
at: z.ZodString;
|
|
358
|
+
action: z.ZodEnum<{
|
|
359
|
+
lookup: "lookup";
|
|
360
|
+
fill: "fill";
|
|
361
|
+
totp: "totp";
|
|
362
|
+
create: "create";
|
|
363
|
+
rotate: "rotate";
|
|
364
|
+
agent_access: "agent_access";
|
|
365
|
+
}>;
|
|
366
|
+
result: z.ZodEnum<{
|
|
367
|
+
ok: "ok";
|
|
368
|
+
denied: "denied";
|
|
369
|
+
}>;
|
|
370
|
+
reason: z.ZodOptional<z.ZodString>;
|
|
371
|
+
secretId: z.ZodNullable<z.ZodString>;
|
|
372
|
+
secretName: z.ZodNullable<z.ZodString>;
|
|
373
|
+
field: z.ZodNullable<z.ZodString>;
|
|
374
|
+
origin: z.ZodNullable<z.ZodString>;
|
|
375
|
+
purpose: z.ZodNullable<z.ZodString>;
|
|
376
|
+
credentialKind: z.ZodNullable<z.ZodEnum<{
|
|
377
|
+
oauth: "oauth";
|
|
378
|
+
pat: "pat";
|
|
379
|
+
session: "session";
|
|
380
|
+
}>>;
|
|
381
|
+
clientId: z.ZodNullable<z.ZodString>;
|
|
382
|
+
clientName: z.ZodNullable<z.ZodString>;
|
|
383
|
+
}, z.core.$strip>>;
|
|
384
|
+
meta: z.ZodObject<{
|
|
385
|
+
page: z.ZodNumber;
|
|
386
|
+
pageSize: z.ZodNumber;
|
|
387
|
+
total: z.ZodNumber;
|
|
388
|
+
}, z.core.$strip>;
|
|
389
|
+
}, z.core.$strip>;
|
|
390
|
+
/** @stability experimental */
|
|
391
|
+
export type AgentActivityResponse = z.infer<typeof agentActivityResponseSchema>;
|