@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.
Files changed (54) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE +21 -0
  3. package/README.md +71 -2
  4. package/dist/cjs/agent/index.d.ts +391 -0
  5. package/dist/cjs/agent/index.js +270 -0
  6. package/dist/cjs/backups/backup-contents.d.ts +80 -0
  7. package/dist/cjs/backups/backup-contents.js +121 -0
  8. package/dist/cjs/backups/index.d.ts +130 -0
  9. package/dist/cjs/backups/index.js +270 -0
  10. package/dist/cjs/backups/responses.d.ts +76 -0
  11. package/dist/cjs/backups/responses.js +2 -0
  12. package/dist/cjs/common/index.d.ts +21 -0
  13. package/dist/cjs/common/index.js +27 -0
  14. package/dist/cjs/errors/index.d.ts +54 -0
  15. package/dist/cjs/errors/index.js +65 -0
  16. package/dist/cjs/index.d.ts +12 -0
  17. package/dist/cjs/index.js +15 -0
  18. package/dist/cjs/media/index.d.ts +55 -0
  19. package/dist/cjs/media/index.js +42 -0
  20. package/dist/cjs/package.json +1 -0
  21. package/dist/cjs/secret-types/index.d.ts +132 -0
  22. package/dist/cjs/secret-types/index.js +215 -0
  23. package/dist/cjs/secrets/index.d.ts +199 -0
  24. package/dist/cjs/secrets/index.js +172 -0
  25. package/dist/cjs/secrets/origins.d.ts +44 -0
  26. package/dist/cjs/secrets/origins.js +103 -0
  27. package/dist/cjs/secrets/totp.d.ts +41 -0
  28. package/dist/cjs/secrets/totp.js +139 -0
  29. package/dist/esm/agent/index.d.ts +391 -0
  30. package/dist/esm/agent/index.js +267 -0
  31. package/dist/esm/backups/backup-contents.d.ts +80 -0
  32. package/dist/esm/backups/backup-contents.js +114 -0
  33. package/dist/esm/backups/index.d.ts +130 -0
  34. package/dist/esm/backups/index.js +251 -0
  35. package/dist/esm/backups/responses.d.ts +76 -0
  36. package/dist/esm/backups/responses.js +1 -0
  37. package/dist/esm/common/index.d.ts +21 -0
  38. package/dist/esm/common/index.js +23 -0
  39. package/dist/esm/errors/index.d.ts +54 -0
  40. package/dist/esm/errors/index.js +61 -0
  41. package/dist/esm/index.d.ts +12 -0
  42. package/dist/esm/index.js +12 -0
  43. package/dist/esm/media/index.d.ts +55 -0
  44. package/dist/esm/media/index.js +39 -0
  45. package/dist/esm/package.json +1 -0
  46. package/dist/esm/secret-types/index.d.ts +132 -0
  47. package/dist/esm/secret-types/index.js +212 -0
  48. package/dist/esm/secrets/index.d.ts +199 -0
  49. package/dist/esm/secrets/index.js +155 -0
  50. package/dist/esm/secrets/origins.d.ts +44 -0
  51. package/dist/esm/secrets/origins.js +96 -0
  52. package/dist/esm/secrets/totp.d.ts +41 -0
  53. package/dist/esm/secrets/totp.js +134 -0
  54. package/package.json +130 -4
@@ -0,0 +1,270 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.agentActivityResponseSchema = exports.agentActivityItemSchema = exports.agentActivityQuerySchema = exports.AGENT_ACTIVITY_MAX_PAGE_SIZE = exports.agentActivityCredentialKindSchema = exports.agentActivityActionSchema = exports.AGENT_ACCESS_TOGGLE_AUDIT_ACTION = exports.AGENT_ACTIVITY_PATH = exports.AGENT_ACCESS_SETTINGS_DEFAULTS = exports.agentAccessSettingsSchema = exports.AGENT_AUDIT_ACTIONS = exports.agentWhoamiResponseSchema = exports.agentRotatePasswordResponseSchema = exports.agentRotatePasswordRequestSchema = exports.agentCreateCredentialResponseSchema = exports.agentCreateCredentialRequestSchema = exports.agentGeneratePasswordSchema = exports.AGENT_GENERATED_PASSWORD_DEFAULT_LENGTH = exports.AGENT_GENERATED_PASSWORD_MAX_LENGTH = exports.AGENT_GENERATED_PASSWORD_MIN_LENGTH = exports.agentTotpResponseSchema = exports.agentTotpRequestSchema = exports.agentFillResponseSchema = exports.agentFillRequestSchema = exports.agentLookupResponseSchema = exports.agentCredentialSummarySchema = exports.agentLookupQuerySchema = exports.agentOriginSchema = exports.agentFillFieldSchema = exports.agentPurposeSchema = exports.AGENT_ERROR_CODES = exports.AGENT_SCOPES = exports.AGENT_API_BASE_PATH = void 0;
4
+ const zod_1 = require("zod");
5
+ /**
6
+ * The agent credential API (`/api/agent/v1`, the `agent` OAuth protected resource): the provider
7
+ * contract an external agent runtime (a browser fabric, an MCP host) codes against. A runtime finds
8
+ * the login for the site on screen, asks for exactly ONE field at a time so it can type it without
9
+ * showing it to a model, reads a one-time code, saves a new login with a generated password and
10
+ * rotates a password.
11
+ *
12
+ * Request and response shapes only. Behaviour (origin binding, the kill switch, rate limits, audit)
13
+ * is the API's; the error codes are in {@link AGENT_ERROR_CODES}. The path carries the version: an
14
+ * incompatible change is `/api/agent/v2`.
15
+ *
16
+ * @packageDocumentation
17
+ */
18
+ /** The API's base path (the `agent` protected resource). @stability experimental */
19
+ exports.AGENT_API_BASE_PATH = '/api/agent/v1';
20
+ /**
21
+ * The OAuth scope ids of the agent resource (permanent: clients persist them). The platform's scope
22
+ * id pattern rules out dots, so they are `vault:items_*`.
23
+ *
24
+ * @stability experimental
25
+ */
26
+ exports.AGENT_SCOPES = {
27
+ ITEMS_READ: 'vault:items_read',
28
+ ITEMS_FILL: 'vault:items_fill',
29
+ ITEMS_WRITE: 'vault:items_write',
30
+ };
31
+ /**
32
+ * Error codes of the agent API, as they appear in `{ code }`. They are also in
33
+ * `VAULT_ERROR_CODES` (`@marinoscar/vault-contract/errors`) with their statuses.
34
+ *
35
+ * @stability experimental
36
+ */
37
+ exports.AGENT_ERROR_CODES = {
38
+ /** 403: the `origin` is not exactly one of the credential's origins. */
39
+ ORIGIN_MISMATCH: 'ORIGIN_MISMATCH',
40
+ /** 403: the deployment's `agentAccess.enabled` switch is off. */
41
+ AGENT_ACCESS_DISABLED: 'AGENT_ACCESS_DISABLED',
42
+ /** 403: the request authenticated with something other than an `oat_` or `pat_` token (a browser session). */
43
+ AGENT_CREDENTIAL_REQUIRED: 'AGENT_CREDENTIAL_REQUIRED',
44
+ /** 429: the per-minute limit of the call's bucket was reached; see `Retry-After`. */
45
+ RATE_LIMITED: 'RATE_LIMITED',
46
+ /** 403: `GET /api/agent-activity` was called with an OAuth access token; an agent cannot read its own trail. */
47
+ AGENT_ACTIVITY_FORBIDDEN: 'AGENT_ACTIVITY_FORBIDDEN',
48
+ };
49
+ /**
50
+ * Why the agent is asking: stored in the audit row of fill, totp, create and rotate.
51
+ *
52
+ * @stability experimental
53
+ */
54
+ exports.agentPurposeSchema = zod_1.z.enum(['login', 'signup', 'password_change', 'mfa']);
55
+ /** The one field a fill call returns. @stability experimental */
56
+ exports.agentFillFieldSchema = zod_1.z.enum(['username', 'password']);
57
+ /** An origin as the agent sees it: a URL or bare host, normalized by the API. @stability experimental */
58
+ exports.agentOriginSchema = zod_1.z.string().trim().min(1).max(2048);
59
+ /** Query of `GET /api/agent/v1/credentials`. @stability experimental */
60
+ exports.agentLookupQuerySchema = zod_1.z.object({
61
+ origin: exports.agentOriginSchema,
62
+ });
63
+ /** One credential found for an origin. Never carries a sensitive value. @stability experimental */
64
+ exports.agentCredentialSummarySchema = zod_1.z.object({
65
+ id: zod_1.z.string().uuid(),
66
+ name: zod_1.z.string(),
67
+ /** The username (a non-sensitive field), or null when the credential has none. */
68
+ username: zod_1.z.string().nullable(),
69
+ origins: zod_1.z.array(zod_1.z.string()),
70
+ /** `exact`: the asked origin is one of the credential's. `site`: same registrable domain only (never fillable). */
71
+ matchKind: zod_1.z.enum(['exact', 'site']),
72
+ hasTotp: zod_1.z.boolean(),
73
+ updatedAt: zod_1.z.string(),
74
+ });
75
+ /** Response of `GET /api/agent/v1/credentials`. Exact matches first. @stability experimental */
76
+ exports.agentLookupResponseSchema = zod_1.z.object({ data: zod_1.z.array(exports.agentCredentialSummarySchema) });
77
+ /** Body of `POST /api/agent/v1/credentials/:id/fill`. @stability experimental */
78
+ exports.agentFillRequestSchema = zod_1.z.object({
79
+ field: exports.agentFillFieldSchema,
80
+ origin: exports.agentOriginSchema,
81
+ purpose: exports.agentPurposeSchema,
82
+ });
83
+ /** Response of the fill route: one value. Type it, never show it to a model. @stability experimental */
84
+ exports.agentFillResponseSchema = zod_1.z.object({ data: zod_1.z.object({ value: zod_1.z.string() }) });
85
+ /** Body of `POST /api/agent/v1/credentials/:id/totp`. @stability experimental */
86
+ exports.agentTotpRequestSchema = zod_1.z.object({
87
+ origin: exports.agentOriginSchema,
88
+ purpose: exports.agentPurposeSchema,
89
+ });
90
+ /** Response of the totp route. `expiresAt` is an ISO timestamp. @stability experimental */
91
+ exports.agentTotpResponseSchema = zod_1.z.object({
92
+ data: zod_1.z.object({ code: zod_1.z.string(), expiresAt: zod_1.z.string() }),
93
+ });
94
+ /** Smallest and largest generated password length. @stability experimental */
95
+ exports.AGENT_GENERATED_PASSWORD_MIN_LENGTH = 12;
96
+ /** @stability experimental */
97
+ exports.AGENT_GENERATED_PASSWORD_MAX_LENGTH = 128;
98
+ /** Length of a generated password when `generate.length` is omitted. @stability experimental */
99
+ exports.AGENT_GENERATED_PASSWORD_DEFAULT_LENGTH = 24;
100
+ /**
101
+ * Ask Vault to generate the password: `length` 12 to 128 (default 24), `symbols` (default true).
102
+ * The result has at least one lower-case letter, upper-case letter and digit, and one symbol when
103
+ * `symbols` is on.
104
+ *
105
+ * @stability experimental
106
+ */
107
+ exports.agentGeneratePasswordSchema = zod_1.z.object({
108
+ length: zod_1.z
109
+ .number()
110
+ .int()
111
+ .min(exports.AGENT_GENERATED_PASSWORD_MIN_LENGTH)
112
+ .max(exports.AGENT_GENERATED_PASSWORD_MAX_LENGTH)
113
+ .default(exports.AGENT_GENERATED_PASSWORD_DEFAULT_LENGTH),
114
+ symbols: zod_1.z.boolean().default(true),
115
+ });
116
+ const passwordValueSchema = zod_1.z.string().min(1).max(1024);
117
+ /** Body of `POST /api/agent/v1/credentials`: exactly one of `password` and `generate`. @stability experimental */
118
+ exports.agentCreateCredentialRequestSchema = zod_1.z
119
+ .object({
120
+ name: zod_1.z.string().trim().min(1).max(255),
121
+ username: zod_1.z.string().trim().min(1).max(512),
122
+ origin: exports.agentOriginSchema,
123
+ additionalUrls: zod_1.z.array(exports.agentOriginSchema).max(19).optional(),
124
+ password: passwordValueSchema.optional(),
125
+ generate: exports.agentGeneratePasswordSchema.optional(),
126
+ purpose: exports.agentPurposeSchema,
127
+ })
128
+ .refine((body) => (body.password === undefined) !== (body.generate === undefined), {
129
+ message: 'Send exactly one of password and generate',
130
+ path: ['password'],
131
+ });
132
+ /**
133
+ * Response of the create route. `generatedPassword` is present only when `generate` was sent, and
134
+ * only in this response: Vault never returns it again.
135
+ *
136
+ * @stability experimental
137
+ */
138
+ exports.agentCreateCredentialResponseSchema = zod_1.z.object({
139
+ data: zod_1.z.object({
140
+ id: zod_1.z.string().uuid(),
141
+ name: zod_1.z.string(),
142
+ username: zod_1.z.string(),
143
+ origins: zod_1.z.array(zod_1.z.string()),
144
+ generatedPassword: zod_1.z.string().optional(),
145
+ }),
146
+ });
147
+ /** Body of `POST /api/agent/v1/credentials/:id/password`: exactly one of `password` and `generate`. @stability experimental */
148
+ exports.agentRotatePasswordRequestSchema = zod_1.z
149
+ .object({
150
+ origin: exports.agentOriginSchema,
151
+ password: passwordValueSchema.optional(),
152
+ generate: exports.agentGeneratePasswordSchema.optional(),
153
+ purpose: exports.agentPurposeSchema,
154
+ })
155
+ .refine((body) => (body.password === undefined) !== (body.generate === undefined), {
156
+ message: 'Send exactly one of password and generate',
157
+ path: ['password'],
158
+ });
159
+ /** Response of the rotate route: the new version number, and the generated value once. @stability experimental */
160
+ exports.agentRotatePasswordResponseSchema = zod_1.z.object({
161
+ data: zod_1.z.object({
162
+ id: zod_1.z.string().uuid(),
163
+ version: zod_1.z.number().int(),
164
+ generatedPassword: zod_1.z.string().optional(),
165
+ }),
166
+ });
167
+ /** Response of `GET /api/agent/v1/whoami`. @stability experimental */
168
+ exports.agentWhoamiResponseSchema = zod_1.z.object({
169
+ data: zod_1.z.object({
170
+ userId: zod_1.z.string(),
171
+ scopes: zod_1.z.array(zod_1.z.string()),
172
+ clientId: zod_1.z.string().nullable(),
173
+ }),
174
+ });
175
+ /**
176
+ * The audit actions the agent API writes (`audit_events.action`), one per route. The `result` of
177
+ * the row's meta is `ok` or `denied:<reason>`.
178
+ *
179
+ * @stability experimental
180
+ */
181
+ exports.AGENT_AUDIT_ACTIONS = {
182
+ LOOKUP: 'agent.credential.lookup',
183
+ FILL: 'agent.credential.fill',
184
+ TOTP: 'agent.credential.totp',
185
+ CREATE: 'agent.credential.create',
186
+ ROTATE: 'agent.credential.rotate',
187
+ };
188
+ /**
189
+ * The `agentAccess` system settings namespace: the kill switch and the per-minute limits of the
190
+ * agent API. `enabled` defaults to `false`: until an administrator switches it on, every agent
191
+ * route answers `403 AGENT_ACCESS_DISABLED`. Each limit counts per token (or OAuth grant) and user.
192
+ *
193
+ * @stability experimental
194
+ */
195
+ exports.agentAccessSettingsSchema = zod_1.z.object({
196
+ enabled: zod_1.z.boolean(),
197
+ lookupPerMinute: zod_1.z.number().int().min(1).max(10_000),
198
+ fillPerMinute: zod_1.z.number().int().min(1).max(10_000),
199
+ totpPerMinute: zod_1.z.number().int().min(1).max(10_000),
200
+ writePerMinute: zod_1.z.number().int().min(1).max(10_000),
201
+ });
202
+ /** Defaults of {@link agentAccessSettingsSchema}: off, lookup 60, fill 30, totp 10, write 10 per minute. @stability experimental */
203
+ exports.AGENT_ACCESS_SETTINGS_DEFAULTS = Object.freeze({
204
+ enabled: false,
205
+ lookupPerMinute: 60,
206
+ fillPerMinute: 30,
207
+ totpPerMinute: 10,
208
+ writePerMinute: 10,
209
+ });
210
+ // -----------------------------------------------------------------------------
211
+ // Agent activity (`GET /api/agent-activity`, E14.7)
212
+ // -----------------------------------------------------------------------------
213
+ /** The path of the owner's agent activity list (session or PAT, never an OAuth token). @stability experimental */
214
+ exports.AGENT_ACTIVITY_PATH = '/api/agent-activity';
215
+ /** The audit action of the per-secret agent access toggle (`secret.agent_access.update`). @stability experimental */
216
+ exports.AGENT_ACCESS_TOGGLE_AUDIT_ACTION = 'secret.agent_access.update';
217
+ /** The actions an activity item carries: the five agent routes and the owner's toggle. @stability experimental */
218
+ exports.agentActivityActionSchema = zod_1.z.enum(['lookup', 'fill', 'totp', 'create', 'rotate', 'agent_access']);
219
+ /** The kind of credential a call authenticated with. @stability experimental */
220
+ exports.agentActivityCredentialKindSchema = zod_1.z.enum(['oauth', 'pat', 'session']);
221
+ /** The largest `pageSize` of the activity list. @stability experimental */
222
+ exports.AGENT_ACTIVITY_MAX_PAGE_SIZE = 100;
223
+ /**
224
+ * Query of `GET /api/agent-activity`. `action` is one of {@link agentActivityActionSchema};
225
+ * `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).
226
+ *
227
+ * @stability experimental
228
+ */
229
+ exports.agentActivityQuerySchema = zod_1.z.object({
230
+ page: zod_1.z.coerce.number().int().min(1).default(1),
231
+ pageSize: zod_1.z.coerce.number().int().min(1).max(exports.AGENT_ACTIVITY_MAX_PAGE_SIZE).default(25),
232
+ action: exports.agentActivityActionSchema.optional(),
233
+ secretId: zod_1.z.string().uuid().optional(),
234
+ clientId: zod_1.z.string().trim().min(1).max(512).optional(),
235
+ from: zod_1.z.string().datetime({ offset: true }).optional(),
236
+ to: zod_1.z.string().datetime({ offset: true }).optional(),
237
+ });
238
+ /**
239
+ * One event of the owner's agent trail. Never carries a value, a code, a seed or a password.
240
+ * `reason` is present on a denial (`origin_mismatch`, `rate_limited`, `not_found`, ...).
241
+ *
242
+ * @stability experimental
243
+ */
244
+ exports.agentActivityItemSchema = zod_1.z.object({
245
+ id: zod_1.z.string(),
246
+ /** ISO 8601. */
247
+ at: zod_1.z.string(),
248
+ action: exports.agentActivityActionSchema,
249
+ result: zod_1.z.enum(['ok', 'denied']),
250
+ reason: zod_1.z.string().optional(),
251
+ secretId: zod_1.z.string().nullable(),
252
+ /** The secret's current name; null when it was deleted or the event names no secret. */
253
+ secretName: zod_1.z.string().nullable(),
254
+ field: zod_1.z.string().nullable(),
255
+ origin: zod_1.z.string().nullable(),
256
+ purpose: zod_1.z.string().nullable(),
257
+ credentialKind: exports.agentActivityCredentialKindSchema.nullable(),
258
+ clientId: zod_1.z.string().nullable(),
259
+ /** The OAuth client's registered name; null for a PAT, a session or an unknown client. */
260
+ clientName: zod_1.z.string().nullable(),
261
+ });
262
+ /** Response of `GET /api/agent-activity`. @stability experimental */
263
+ exports.agentActivityResponseSchema = zod_1.z.object({
264
+ data: zod_1.z.array(exports.agentActivityItemSchema),
265
+ meta: zod_1.z.object({
266
+ page: zod_1.z.number().int(),
267
+ pageSize: zod_1.z.number().int(),
268
+ total: zod_1.z.number().int(),
269
+ }),
270
+ });
@@ -0,0 +1,80 @@
1
+ /**
2
+ * What a backup contains: the content sections a user (or an administrator,
3
+ * for the scheduled system backup) picks.
4
+ *
5
+ * | Key | User export | System backup | Default |
6
+ * |---------------|-------------|---------------|---------|
7
+ * | `secrets` | own | every user | on |
8
+ * | `attachments` | own | every user | on (requires secrets) |
9
+ * | `versions` | own | every user | off (requires secrets) |
10
+ * | `media` | own folders | every user | off |
11
+ * | `system` | not offered | yes | off |
12
+ *
13
+ * Shared by the user export DTO and the backup schedule DTO so both apply
14
+ * exactly the same rules and messages. Every message is static text.
15
+ */
16
+ /** Content keys, in the order they are listed (e.g. on a run's `contents`). */
17
+ export declare const BACKUP_CONTENT_KEYS: readonly ["secrets", "attachments", "versions", "media", "system"];
18
+ export type BackupContentKey = (typeof BACKUP_CONTENT_KEYS)[number];
19
+ export declare const BACKUP_CONTENT_DEFAULTS: {
20
+ readonly includeSecrets: true;
21
+ readonly includeAttachments: true;
22
+ readonly includeVersions: false;
23
+ readonly includeMedia: false;
24
+ readonly includeSystem: false;
25
+ };
26
+ export declare const BACKUP_CONTENT_MESSAGES: {
27
+ readonly nothingSelected: "Choose at least one thing to back up";
28
+ readonly attachmentsWithoutSecrets: "Attachments can only be backed up together with secrets";
29
+ readonly versionsWithoutSecrets: "Old versions can only be backed up together with secrets";
30
+ readonly systemNotOffered: "System configuration can only be included in a scheduled system backup";
31
+ };
32
+ /** The flags as received; `undefined` means "not sent". */
33
+ export interface RawContentSelection {
34
+ includeSecrets?: boolean;
35
+ includeAttachments?: boolean;
36
+ includeVersions?: boolean;
37
+ includeMedia?: boolean;
38
+ includeSystem?: unknown;
39
+ }
40
+ /** What a user export can contain. */
41
+ export interface UserContentSelection {
42
+ includeSecrets: boolean;
43
+ includeAttachments: boolean;
44
+ includeVersions: boolean;
45
+ includeMedia: boolean;
46
+ }
47
+ /** What a system backup can contain. */
48
+ export interface BackupContentSelection extends UserContentSelection {
49
+ includeSystem: boolean;
50
+ }
51
+ export interface ContentSelectionIssue {
52
+ path: keyof RawContentSelection;
53
+ message: string;
54
+ }
55
+ /**
56
+ * Validation rules of a content selection.
57
+ *
58
+ * - `system` is offered only by the system backup; at the user level sending
59
+ * `includeSystem` at all (even `false`) is an error.
60
+ * - Attachments and old versions are part of a secret: asking for them
61
+ * explicitly (`true`) while secrets are off is an error. Left out, they are
62
+ * simply off when secrets are off.
63
+ * - At least one of secrets, media and system must be selected.
64
+ *
65
+ * @returns the issues, in a fixed order; empty when the selection is valid.
66
+ */
67
+ export declare function contentSelectionIssues(raw: RawContentSelection, level: 'user' | 'system'): ContentSelectionIssue[];
68
+ /**
69
+ * Apply the defaults to a (valid, or stored) selection. Attachments and
70
+ * versions are always off when secrets are off.
71
+ */
72
+ export declare function resolveContentSelection(raw: RawContentSelection): BackupContentSelection;
73
+ /** The selected keys, in {@link BACKUP_CONTENT_KEYS} order. */
74
+ export declare function selectedContentKeys(selection: UserContentSelection & {
75
+ includeSystem?: boolean;
76
+ }): BackupContentKey[];
77
+ /** Human summary for a README, e.g. `secrets (with attachments), media library`. */
78
+ export declare function describeContents(selection: UserContentSelection & {
79
+ includeSystem?: boolean;
80
+ }): string;
@@ -0,0 +1,121 @@
1
+ "use strict";
2
+ /**
3
+ * What a backup contains: the content sections a user (or an administrator,
4
+ * for the scheduled system backup) picks.
5
+ *
6
+ * | Key | User export | System backup | Default |
7
+ * |---------------|-------------|---------------|---------|
8
+ * | `secrets` | own | every user | on |
9
+ * | `attachments` | own | every user | on (requires secrets) |
10
+ * | `versions` | own | every user | off (requires secrets) |
11
+ * | `media` | own folders | every user | off |
12
+ * | `system` | not offered | yes | off |
13
+ *
14
+ * Shared by the user export DTO and the backup schedule DTO so both apply
15
+ * exactly the same rules and messages. Every message is static text.
16
+ */
17
+ Object.defineProperty(exports, "__esModule", { value: true });
18
+ exports.BACKUP_CONTENT_MESSAGES = exports.BACKUP_CONTENT_DEFAULTS = exports.BACKUP_CONTENT_KEYS = void 0;
19
+ exports.contentSelectionIssues = contentSelectionIssues;
20
+ exports.resolveContentSelection = resolveContentSelection;
21
+ exports.selectedContentKeys = selectedContentKeys;
22
+ exports.describeContents = describeContents;
23
+ /** Content keys, in the order they are listed (e.g. on a run's `contents`). */
24
+ exports.BACKUP_CONTENT_KEYS = ['secrets', 'attachments', 'versions', 'media', 'system'];
25
+ exports.BACKUP_CONTENT_DEFAULTS = {
26
+ includeSecrets: true,
27
+ includeAttachments: true,
28
+ includeVersions: false,
29
+ includeMedia: false,
30
+ includeSystem: false,
31
+ };
32
+ exports.BACKUP_CONTENT_MESSAGES = {
33
+ nothingSelected: 'Choose at least one thing to back up',
34
+ attachmentsWithoutSecrets: 'Attachments can only be backed up together with secrets',
35
+ versionsWithoutSecrets: 'Old versions can only be backed up together with secrets',
36
+ systemNotOffered: 'System configuration can only be included in a scheduled system backup',
37
+ };
38
+ /**
39
+ * Validation rules of a content selection.
40
+ *
41
+ * - `system` is offered only by the system backup; at the user level sending
42
+ * `includeSystem` at all (even `false`) is an error.
43
+ * - Attachments and old versions are part of a secret: asking for them
44
+ * explicitly (`true`) while secrets are off is an error. Left out, they are
45
+ * simply off when secrets are off.
46
+ * - At least one of secrets, media and system must be selected.
47
+ *
48
+ * @returns the issues, in a fixed order; empty when the selection is valid.
49
+ */
50
+ function contentSelectionIssues(raw, level) {
51
+ const issues = [];
52
+ if (level === 'user' && raw.includeSystem !== undefined) {
53
+ issues.push({ path: 'includeSystem', message: exports.BACKUP_CONTENT_MESSAGES.systemNotOffered });
54
+ return issues;
55
+ }
56
+ const secrets = raw.includeSecrets ?? exports.BACKUP_CONTENT_DEFAULTS.includeSecrets;
57
+ const media = raw.includeMedia ?? exports.BACKUP_CONTENT_DEFAULTS.includeMedia;
58
+ const system = level === 'system' && raw.includeSystem === true;
59
+ if (!secrets && !media && !system) {
60
+ issues.push({ path: 'includeSecrets', message: exports.BACKUP_CONTENT_MESSAGES.nothingSelected });
61
+ }
62
+ if (!secrets && raw.includeAttachments === true) {
63
+ issues.push({
64
+ path: 'includeAttachments',
65
+ message: exports.BACKUP_CONTENT_MESSAGES.attachmentsWithoutSecrets,
66
+ });
67
+ }
68
+ if (!secrets && raw.includeVersions === true) {
69
+ issues.push({
70
+ path: 'includeVersions',
71
+ message: exports.BACKUP_CONTENT_MESSAGES.versionsWithoutSecrets,
72
+ });
73
+ }
74
+ return issues;
75
+ }
76
+ /**
77
+ * Apply the defaults to a (valid, or stored) selection. Attachments and
78
+ * versions are always off when secrets are off.
79
+ */
80
+ function resolveContentSelection(raw) {
81
+ const includeSecrets = raw.includeSecrets ?? exports.BACKUP_CONTENT_DEFAULTS.includeSecrets;
82
+ return {
83
+ includeSecrets,
84
+ includeAttachments: includeSecrets && (raw.includeAttachments ?? exports.BACKUP_CONTENT_DEFAULTS.includeAttachments),
85
+ includeVersions: includeSecrets && (raw.includeVersions ?? exports.BACKUP_CONTENT_DEFAULTS.includeVersions),
86
+ includeMedia: raw.includeMedia ?? exports.BACKUP_CONTENT_DEFAULTS.includeMedia,
87
+ includeSystem: raw.includeSystem === true,
88
+ };
89
+ }
90
+ /** The selected keys, in {@link BACKUP_CONTENT_KEYS} order. */
91
+ function selectedContentKeys(selection) {
92
+ const keys = [];
93
+ if (selection.includeSecrets)
94
+ keys.push('secrets');
95
+ if (selection.includeSecrets && selection.includeAttachments)
96
+ keys.push('attachments');
97
+ if (selection.includeSecrets && selection.includeVersions)
98
+ keys.push('versions');
99
+ if (selection.includeMedia)
100
+ keys.push('media');
101
+ if (selection.includeSystem)
102
+ keys.push('system');
103
+ return keys;
104
+ }
105
+ /** Human summary for a README, e.g. `secrets (with attachments), media library`. */
106
+ function describeContents(selection) {
107
+ const parts = [];
108
+ if (selection.includeSecrets) {
109
+ const extras = [];
110
+ if (selection.includeAttachments)
111
+ extras.push('attachments');
112
+ if (selection.includeVersions)
113
+ extras.push('old versions');
114
+ parts.push(extras.length ? `secrets (with ${extras.join(' and ')})` : 'secrets');
115
+ }
116
+ if (selection.includeMedia)
117
+ parts.push('media library');
118
+ if (selection.includeSystem)
119
+ parts.push('system configuration');
120
+ return parts.length ? parts.join(', ') : 'nothing';
121
+ }
@@ -0,0 +1,130 @@
1
+ import { z } from 'zod';
2
+ /**
3
+ * Backups: the content selection rules, the schedule vocabulary and validators,
4
+ * and the request schemas of the user export, the system export, the schedule
5
+ * and the run list. Every message is static text and never echoes a submitted
6
+ * value, so a validation error is safe to log.
7
+ *
8
+ * @packageDocumentation
9
+ */
10
+ export * from './backup-contents.js';
11
+ export * from './responses.js';
12
+ /** Allowed backup frequencies. @stability experimental */
13
+ export declare const BACKUP_FREQUENCIES: readonly ["hourly", "daily", "weekly", "monthly"];
14
+ /** @stability experimental */
15
+ export type BackupFrequency = (typeof BACKUP_FREQUENCIES)[number];
16
+ /** Allowed `intervalHours` for `hourly`: each divides 24, so slots repeat every day. */
17
+ export declare const BACKUP_INTERVAL_HOURS: readonly [1, 2, 3, 4, 6, 8, 12];
18
+ /** True when `value` is a valid `HH:mm` (00:00 to 23:59). */
19
+ export declare function isValidTimeOfDay(value: string): boolean;
20
+ /** True when `Intl` accepts `timeZone` as an IANA zone. */
21
+ export declare function isValidTimeZone(timeZone: string): boolean;
22
+ export declare const EXPORT_PASSWORD_MIN_LENGTH = 6;
23
+ export declare const EXPORT_PASSWORD_MAX_LENGTH = 256;
24
+ /**
25
+ * Body of `POST /api/secrets/export`.
26
+ *
27
+ * The password is deliberately free-form: the product decision is "any
28
+ * password of at least 6 characters", with no complexity rules. It is not
29
+ * trimmed either, because a user who typed a trailing space has to type the
30
+ * same trailing space into 7-Zip to open the file.
31
+ *
32
+ * Content flags (see `backup-contents.ts`): `includeSecrets` (default true),
33
+ * `includeAttachments` (default true) and `includeVersions` (default false),
34
+ * both of which require secrets, and `includeMedia` (default false). At least
35
+ * one of secrets / media is required. `includeSystem` belongs to the
36
+ * scheduled system backup only and is rejected here.
37
+ *
38
+ * Every message below is static text. None of them echoes the submitted value,
39
+ * so a validation error can be logged by the exception filter without leaking
40
+ * the password.
41
+ */
42
+ export declare const exportSecretsSchema: z.ZodPipe<z.ZodObject<{
43
+ password: z.ZodString;
44
+ includeSecrets: z.ZodOptional<z.ZodBoolean>;
45
+ includeAttachments: z.ZodOptional<z.ZodBoolean>;
46
+ includeVersions: z.ZodOptional<z.ZodBoolean>;
47
+ includeMedia: z.ZodOptional<z.ZodBoolean>;
48
+ includeSystem: z.ZodOptional<z.ZodUnknown>;
49
+ }, z.core.$strip>, z.ZodTransform<{
50
+ password: string;
51
+ includeSecrets: boolean;
52
+ includeAttachments: boolean;
53
+ includeVersions: boolean;
54
+ includeMedia: boolean;
55
+ }, {
56
+ password: string;
57
+ includeSecrets?: boolean | undefined;
58
+ includeAttachments?: boolean | undefined;
59
+ includeVersions?: boolean | undefined;
60
+ includeMedia?: boolean | undefined;
61
+ includeSystem?: unknown;
62
+ }>>;
63
+ export type ExportSecretsOptions = z.infer<typeof exportSecretsSchema>;
64
+ export declare const EXPORT_PASSWORD_CHOICE_MESSAGES: {
65
+ readonly missing: "Enter a password, or use the scheduled backup password";
66
+ readonly both: "Use either a password or the scheduled backup password, not both";
67
+ };
68
+ /**
69
+ * Body of `POST /api/admin/backups/export`: download a system backup now.
70
+ *
71
+ * Exactly one password source: `password` (6-256 characters, not trimmed,
72
+ * same rules as the user export) or `useScheduledPassword: true` (the stored
73
+ * schedule password, decrypted only for the stream). Content flags follow the
74
+ * system-level rules of `backup-contents.ts`; a flag left out takes its
75
+ * default. Every message is static and never echoes the password.
76
+ */
77
+ export declare const exportSystemBackupSchema: z.ZodObject<{
78
+ password: z.ZodOptional<z.ZodString>;
79
+ useScheduledPassword: z.ZodOptional<z.ZodBoolean>;
80
+ includeSecrets: z.ZodOptional<z.ZodBoolean>;
81
+ includeAttachments: z.ZodOptional<z.ZodBoolean>;
82
+ includeVersions: z.ZodOptional<z.ZodBoolean>;
83
+ includeMedia: z.ZodOptional<z.ZodBoolean>;
84
+ includeSystem: z.ZodOptional<z.ZodBoolean>;
85
+ }, z.core.$strip>;
86
+ export declare const BACKUP_KEEP_COUNT_MIN = 1;
87
+ export declare const BACKUP_KEEP_COUNT_MAX = 365;
88
+ /**
89
+ * Body of `PUT /api/admin/backups/schedule`.
90
+ *
91
+ * Every editable field is required (a full replace), except the content
92
+ * flags added later (`includeSecrets` default true, `includeMedia` and
93
+ * `includeSystem` default false), so an older client keeps working.
94
+ * `includeAttachments` / `includeVersions` true require `includeSecrets`, and
95
+ * at least one of secrets / media / system must be selected (see
96
+ * `backup-contents.ts`). `password` is write-only: omitted keeps the stored
97
+ * one, a string replaces it. As with the user export the password is
98
+ * free-form (6-256 characters, not trimmed).
99
+ *
100
+ * Every message is static text and never echoes the submitted value, so a
101
+ * validation error is safe to log.
102
+ */
103
+ export declare const updateBackupScheduleSchema: z.ZodObject<{
104
+ enabled: z.ZodBoolean;
105
+ frequency: z.ZodEnum<{
106
+ hourly: "hourly";
107
+ daily: "daily";
108
+ weekly: "weekly";
109
+ monthly: "monthly";
110
+ }>;
111
+ intervalHours: z.ZodNullable<z.ZodNumber>;
112
+ timeOfDay: z.ZodString;
113
+ dayOfWeek: z.ZodNullable<z.ZodNumber>;
114
+ dayOfMonth: z.ZodNullable<z.ZodNumber>;
115
+ timezone: z.ZodString;
116
+ keepCount: z.ZodNumber;
117
+ includeAttachments: z.ZodBoolean;
118
+ includeVersions: z.ZodBoolean;
119
+ includeSecrets: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
120
+ includeMedia: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
121
+ includeSystem: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
122
+ password: z.ZodOptional<z.ZodString>;
123
+ }, z.core.$strip>;
124
+ export type UpdateBackupScheduleInput = z.infer<typeof updateBackupScheduleSchema>;
125
+ /** Query of `GET /api/admin/backups` (same paging fields as the users list). */
126
+ export declare const backupRunListQuerySchema: z.ZodObject<{
127
+ page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
128
+ pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
129
+ }, z.core.$strip>;
130
+ export type BackupRunListQuery = z.infer<typeof backupRunListQuerySchema>;