@marinoscar/vault-contract 0.1.0-next.3 → 0.1.0-next.4

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 (63) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +17 -5
  3. package/dist/cjs/agent/cards-identity.d.ts +456 -0
  4. package/dist/cjs/agent/cards-identity.js +272 -0
  5. package/dist/cjs/agent/contract-version.d.ts +58 -0
  6. package/dist/cjs/agent/contract-version.js +58 -0
  7. package/dist/cjs/agent/index.d.ts +196 -54
  8. package/dist/cjs/agent/index.js +176 -37
  9. package/dist/cjs/agent-testing/canary.d.ts +57 -0
  10. package/dist/cjs/agent-testing/canary.js +165 -0
  11. package/dist/cjs/agent-testing/fake-vault.d.ts +111 -0
  12. package/dist/cjs/agent-testing/fake-vault.js +707 -0
  13. package/dist/cjs/agent-testing/guard.d.ts +16 -0
  14. package/dist/cjs/agent-testing/guard.js +28 -0
  15. package/dist/cjs/agent-testing/index.d.ts +28 -0
  16. package/dist/cjs/agent-testing/index.js +43 -0
  17. package/dist/cjs/agent-testing/recorder.d.ts +70 -0
  18. package/dist/cjs/agent-testing/recorder.js +127 -0
  19. package/dist/cjs/agent-testing/reference-runtime.d.ts +8 -0
  20. package/dist/cjs/agent-testing/reference-runtime.js +112 -0
  21. package/dist/cjs/agent-testing/scenarios.d.ts +128 -0
  22. package/dist/cjs/agent-testing/scenarios.js +566 -0
  23. package/dist/cjs/agent-testing/seed.d.ts +84 -0
  24. package/dist/cjs/agent-testing/seed.js +89 -0
  25. package/dist/cjs/agent-testing/totp.d.ts +10 -0
  26. package/dist/cjs/agent-testing/totp.js +45 -0
  27. package/dist/cjs/errors/index.js +13 -1
  28. package/dist/cjs/media/index.d.ts +2 -2
  29. package/dist/cjs/secret-types/index.d.ts +4 -0
  30. package/dist/cjs/secret-types/index.js +29 -1
  31. package/dist/cjs/secrets/index.d.ts +13 -3
  32. package/dist/cjs/secrets/index.js +14 -3
  33. package/dist/esm/agent/cards-identity.d.ts +456 -0
  34. package/dist/esm/agent/cards-identity.js +266 -0
  35. package/dist/esm/agent/contract-version.d.ts +58 -0
  36. package/dist/esm/agent/contract-version.js +54 -0
  37. package/dist/esm/agent/index.d.ts +196 -54
  38. package/dist/esm/agent/index.js +160 -36
  39. package/dist/esm/agent-testing/canary.d.ts +57 -0
  40. package/dist/esm/agent-testing/canary.js +157 -0
  41. package/dist/esm/agent-testing/fake-vault.d.ts +111 -0
  42. package/dist/esm/agent-testing/fake-vault.js +704 -0
  43. package/dist/esm/agent-testing/guard.d.ts +16 -0
  44. package/dist/esm/agent-testing/guard.js +23 -0
  45. package/dist/esm/agent-testing/index.d.ts +28 -0
  46. package/dist/esm/agent-testing/index.js +27 -0
  47. package/dist/esm/agent-testing/recorder.d.ts +70 -0
  48. package/dist/esm/agent-testing/recorder.js +122 -0
  49. package/dist/esm/agent-testing/reference-runtime.d.ts +8 -0
  50. package/dist/esm/agent-testing/reference-runtime.js +109 -0
  51. package/dist/esm/agent-testing/scenarios.d.ts +128 -0
  52. package/dist/esm/agent-testing/scenarios.js +560 -0
  53. package/dist/esm/agent-testing/seed.d.ts +84 -0
  54. package/dist/esm/agent-testing/seed.js +85 -0
  55. package/dist/esm/agent-testing/totp.d.ts +10 -0
  56. package/dist/esm/agent-testing/totp.js +42 -0
  57. package/dist/esm/errors/index.js +13 -1
  58. package/dist/esm/media/index.d.ts +2 -2
  59. package/dist/esm/secret-types/index.d.ts +4 -0
  60. package/dist/esm/secret-types/index.js +28 -0
  61. package/dist/esm/secrets/index.d.ts +13 -3
  62. package/dist/esm/secrets/index.js +13 -2
  63. package/package.json +11 -1
@@ -1,7 +1,23 @@
1
1
  "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
+ for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
+ };
2
16
  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;
17
+ 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.agentIdentityAccessSettingsSchema = exports.agentCardAccessSettingsSchema = 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;
18
+ exports.resolveAgentAccessSettings = resolveAgentAccessSettings;
4
19
  const zod_1 = require("zod");
20
+ const contract_version_js_1 = require("./contract-version.js");
5
21
  /**
6
22
  * The agent credential API (`/api/agent/v1`, the `agent` OAuth protected resource): the provider
7
23
  * contract an external agent runtime (a browser fabric, an MCP host) codes against. A runtime finds
@@ -13,26 +29,43 @@ const zod_1 = require("zod");
13
29
  * is the API's; the error codes are in {@link AGENT_ERROR_CODES}. The path carries the version: an
14
30
  * incompatible change is `/api/agent/v2`.
15
31
  *
32
+ * Stability: **beta** (issue #196). Inside `/api/agent/v1` the route paths, the required request
33
+ * fields, the meaning of each error code, the scope names and the one-secret-field-per-response rule
34
+ * do not change. New optional request fields, new response fields, new error codes and scopes for
35
+ * new routes and stricter rate-limit defaults may arrive without a new version: ignore unknown
36
+ * response fields and unknown enum values, and never branch on `message`. Anything else is
37
+ * `/api/agent/v2`, and `v1` keeps working for two minor releases of the packages after `v2` ships.
38
+ * The tag becomes `stable` at 1.0. Changes are listed under "Changes" in
39
+ * `docs/agent-credential-api.md`; {@link AGENT_CONTRACT_VERSION} is the current version.
40
+ *
16
41
  * @packageDocumentation
17
42
  */
18
- /** The API's base path (the `agent` protected resource). @stability experimental */
43
+ /** The API's base path (the `agent` protected resource). @stability beta */
19
44
  exports.AGENT_API_BASE_PATH = '/api/agent/v1';
20
45
  /**
21
46
  * The OAuth scope ids of the agent resource (permanent: clients persist them). The platform's scope
22
47
  * id pattern rules out dots, so they are `vault:items_*`.
23
48
  *
24
- * @stability experimental
49
+ * @stability beta
25
50
  */
26
51
  exports.AGENT_SCOPES = {
27
52
  ITEMS_READ: 'vault:items_read',
28
53
  ITEMS_FILL: 'vault:items_fill',
29
54
  ITEMS_WRITE: 'vault:items_write',
55
+ /** List the opened cards that have a live grant for a merchant (ADR-0003). */
56
+ CARDS_READ: 'vault:cards_read',
57
+ /** Fill one field of a granted card, and ask the owner for a grant. */
58
+ CARDS_FILL: 'vault:cards_fill',
59
+ /** List the opened identity items and the labels of their fields. */
60
+ IDENTITY_READ: 'vault:identity_read',
61
+ /** Fill one field of an opened identity item. */
62
+ IDENTITY_FILL: 'vault:identity_fill',
30
63
  };
31
64
  /**
32
65
  * Error codes of the agent API, as they appear in `{ code }`. They are also in
33
66
  * `VAULT_ERROR_CODES` (`@marinoscar/vault-contract/errors`) with their statuses.
34
67
  *
35
- * @stability experimental
68
+ * @stability beta
36
69
  */
37
70
  exports.AGENT_ERROR_CODES = {
38
71
  /** 403: the `origin` is not exactly one of the credential's origins. */
@@ -45,22 +78,44 @@ exports.AGENT_ERROR_CODES = {
45
78
  RATE_LIMITED: 'RATE_LIMITED',
46
79
  /** 403: `GET /api/agent-activity` was called with an OAuth access token; an agent cannot read its own trail. */
47
80
  AGENT_ACTIVITY_FORBIDDEN: 'AGENT_ACTIVITY_FORBIDDEN',
81
+ /** 403: the deployment's `agentAccess.cards.enabled` switch is off (ADR-0003). */
82
+ CARD_ACCESS_DISABLED: 'CARD_ACCESS_DISABLED',
83
+ /** 403: the deployment's `agentAccess.identity.enabled` switch is off (ADR-0003). */
84
+ IDENTITY_ACCESS_DISABLED: 'IDENTITY_ACCESS_DISABLED',
85
+ /** 403: `securityCode` was asked for under a grant that does not include it. */
86
+ SECURITY_CODE_NOT_GRANTED: 'SECURITY_CODE_NOT_GRANTED',
87
+ /** 403: the amount is above the grant's maximum. */
88
+ CARD_AMOUNT_EXCEEDED: 'CARD_AMOUNT_EXCEEDED',
89
+ /** 403: the currency is not the grant's. */
90
+ CARD_CURRENCY_MISMATCH: 'CARD_CURRENCY_MISMATCH',
91
+ /** 403: the grant's period limit (releases or total amount per day or month) was reached. */
92
+ CARD_PERIOD_LIMIT_REACHED: 'CARD_PERIOD_LIMIT_REACHED',
93
+ /** 403: the deployment's per-card daily cap of releases was reached. */
94
+ CARD_DAILY_CAP_REACHED: 'CARD_DAILY_CAP_REACHED',
95
+ /** 403: the card's grant for this merchant has expired. */
96
+ CARD_GRANT_EXPIRED: 'CARD_GRANT_EXPIRED',
97
+ /** 409: the card already has a live grant for this merchant site. */
98
+ CARD_GRANT_EXISTS: 'CARD_GRANT_EXISTS',
99
+ /** 409: the grant request was already approved or declined. */
100
+ CARD_GRANT_REQUEST_NOT_PENDING: 'CARD_GRANT_REQUEST_NOT_PENDING',
101
+ /** 403: the route changes what agents may do and needs the owner's browser session, never a token. */
102
+ OWNER_SESSION_REQUIRED: 'OWNER_SESSION_REQUIRED',
48
103
  };
49
104
  /**
50
105
  * Why the agent is asking: stored in the audit row of fill, totp, create and rotate.
51
106
  *
52
- * @stability experimental
107
+ * @stability beta
53
108
  */
54
109
  exports.agentPurposeSchema = zod_1.z.enum(['login', 'signup', 'password_change', 'mfa']);
55
- /** The one field a fill call returns. @stability experimental */
110
+ /** The one field a fill call returns. @stability beta */
56
111
  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 */
112
+ /** An origin as the agent sees it: a URL or bare host, normalized by the API. @stability beta */
58
113
  exports.agentOriginSchema = zod_1.z.string().trim().min(1).max(2048);
59
- /** Query of `GET /api/agent/v1/credentials`. @stability experimental */
114
+ /** Query of `GET /api/agent/v1/credentials`. @stability beta */
60
115
  exports.agentLookupQuerySchema = zod_1.z.object({
61
116
  origin: exports.agentOriginSchema,
62
117
  });
63
- /** One credential found for an origin. Never carries a sensitive value. @stability experimental */
118
+ /** One credential found for an origin. Never carries a sensitive value. @stability beta */
64
119
  exports.agentCredentialSummarySchema = zod_1.z.object({
65
120
  id: zod_1.z.string().uuid(),
66
121
  name: zod_1.z.string(),
@@ -72,37 +127,37 @@ exports.agentCredentialSummarySchema = zod_1.z.object({
72
127
  hasTotp: zod_1.z.boolean(),
73
128
  updatedAt: zod_1.z.string(),
74
129
  });
75
- /** Response of `GET /api/agent/v1/credentials`. Exact matches first. @stability experimental */
130
+ /** Response of `GET /api/agent/v1/credentials`. Exact matches first. @stability beta */
76
131
  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 */
132
+ /** Body of `POST /api/agent/v1/credentials/:id/fill`. @stability beta */
78
133
  exports.agentFillRequestSchema = zod_1.z.object({
79
134
  field: exports.agentFillFieldSchema,
80
135
  origin: exports.agentOriginSchema,
81
136
  purpose: exports.agentPurposeSchema,
82
137
  });
83
- /** Response of the fill route: one value. Type it, never show it to a model. @stability experimental */
138
+ /** Response of the fill route: one value. Type it, never show it to a model. @stability beta */
84
139
  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 */
140
+ /** Body of `POST /api/agent/v1/credentials/:id/totp`. @stability beta */
86
141
  exports.agentTotpRequestSchema = zod_1.z.object({
87
142
  origin: exports.agentOriginSchema,
88
143
  purpose: exports.agentPurposeSchema,
89
144
  });
90
- /** Response of the totp route. `expiresAt` is an ISO timestamp. @stability experimental */
145
+ /** Response of the totp route. `expiresAt` is an ISO timestamp. @stability beta */
91
146
  exports.agentTotpResponseSchema = zod_1.z.object({
92
147
  data: zod_1.z.object({ code: zod_1.z.string(), expiresAt: zod_1.z.string() }),
93
148
  });
94
- /** Smallest and largest generated password length. @stability experimental */
149
+ /** Smallest and largest generated password length. @stability beta */
95
150
  exports.AGENT_GENERATED_PASSWORD_MIN_LENGTH = 12;
96
- /** @stability experimental */
151
+ /** @stability beta */
97
152
  exports.AGENT_GENERATED_PASSWORD_MAX_LENGTH = 128;
98
- /** Length of a generated password when `generate.length` is omitted. @stability experimental */
153
+ /** Length of a generated password when `generate.length` is omitted. @stability beta */
99
154
  exports.AGENT_GENERATED_PASSWORD_DEFAULT_LENGTH = 24;
100
155
  /**
101
156
  * Ask Vault to generate the password: `length` 12 to 128 (default 24), `symbols` (default true).
102
157
  * The result has at least one lower-case letter, upper-case letter and digit, and one symbol when
103
158
  * `symbols` is on.
104
159
  *
105
- * @stability experimental
160
+ * @stability beta
106
161
  */
107
162
  exports.agentGeneratePasswordSchema = zod_1.z.object({
108
163
  length: zod_1.z
@@ -114,7 +169,7 @@ exports.agentGeneratePasswordSchema = zod_1.z.object({
114
169
  symbols: zod_1.z.boolean().default(true),
115
170
  });
116
171
  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 */
172
+ /** Body of `POST /api/agent/v1/credentials`: exactly one of `password` and `generate`. @stability beta */
118
173
  exports.agentCreateCredentialRequestSchema = zod_1.z
119
174
  .object({
120
175
  name: zod_1.z.string().trim().min(1).max(255),
@@ -133,7 +188,7 @@ exports.agentCreateCredentialRequestSchema = zod_1.z
133
188
  * Response of the create route. `generatedPassword` is present only when `generate` was sent, and
134
189
  * only in this response: Vault never returns it again.
135
190
  *
136
- * @stability experimental
191
+ * @stability beta
137
192
  */
138
193
  exports.agentCreateCredentialResponseSchema = zod_1.z.object({
139
194
  data: zod_1.z.object({
@@ -144,7 +199,7 @@ exports.agentCreateCredentialResponseSchema = zod_1.z.object({
144
199
  generatedPassword: zod_1.z.string().optional(),
145
200
  }),
146
201
  });
147
- /** Body of `POST /api/agent/v1/credentials/:id/password`: exactly one of `password` and `generate`. @stability experimental */
202
+ /** Body of `POST /api/agent/v1/credentials/:id/password`: exactly one of `password` and `generate`. @stability beta */
148
203
  exports.agentRotatePasswordRequestSchema = zod_1.z
149
204
  .object({
150
205
  origin: exports.agentOriginSchema,
@@ -156,7 +211,7 @@ exports.agentRotatePasswordRequestSchema = zod_1.z
156
211
  message: 'Send exactly one of password and generate',
157
212
  path: ['password'],
158
213
  });
159
- /** Response of the rotate route: the new version number, and the generated value once. @stability experimental */
214
+ /** Response of the rotate route: the new version number, and the generated value once. @stability beta */
160
215
  exports.agentRotatePasswordResponseSchema = zod_1.z.object({
161
216
  data: zod_1.z.object({
162
217
  id: zod_1.z.string().uuid(),
@@ -164,19 +219,26 @@ exports.agentRotatePasswordResponseSchema = zod_1.z.object({
164
219
  generatedPassword: zod_1.z.string().optional(),
165
220
  }),
166
221
  });
167
- /** Response of `GET /api/agent/v1/whoami`. @stability experimental */
222
+ /**
223
+ * Response of `GET /api/agent/v1/whoami`. `contract` (since contract 1.2) is the contract version
224
+ * and the features this Vault offers now; it is absent on an older Vault, so treat a missing block
225
+ * as version `1.0` with `logins` and `totp`.
226
+ *
227
+ * @stability beta
228
+ */
168
229
  exports.agentWhoamiResponseSchema = zod_1.z.object({
169
230
  data: zod_1.z.object({
170
231
  userId: zod_1.z.string(),
171
232
  scopes: zod_1.z.array(zod_1.z.string()),
172
233
  clientId: zod_1.z.string().nullable(),
234
+ contract: contract_version_js_1.agentContractInfoSchema.optional(),
173
235
  }),
174
236
  });
175
237
  /**
176
238
  * The audit actions the agent API writes (`audit_events.action`), one per route. The `result` of
177
239
  * the row's meta is `ok` or `denied:<reason>`.
178
240
  *
179
- * @stability experimental
241
+ * @stability beta
180
242
  */
181
243
  exports.AGENT_AUDIT_ACTIONS = {
182
244
  LOOKUP: 'agent.credential.lookup',
@@ -184,13 +246,40 @@ exports.AGENT_AUDIT_ACTIONS = {
184
246
  TOTP: 'agent.credential.totp',
185
247
  CREATE: 'agent.credential.create',
186
248
  ROTATE: 'agent.credential.rotate',
249
+ CARD_LOOKUP: 'agent.card.lookup',
250
+ CARD_FILL: 'agent.card.fill',
251
+ CARD_GRANT_REQUEST: 'agent.card.grant_request',
252
+ IDENTITY_LOOKUP: 'agent.identity.lookup',
253
+ IDENTITY_FILL: 'agent.identity.fill',
187
254
  };
255
+ /**
256
+ * The card part of the `agentAccess` settings (ADR-0003): the card kill switch (default off), the
257
+ * `card_fill` bucket's per-minute limit and the per-card daily cap of releases (`number` fills).
258
+ *
259
+ * @stability beta
260
+ */
261
+ exports.agentCardAccessSettingsSchema = zod_1.z.object({
262
+ enabled: zod_1.z.boolean(),
263
+ fillPerMinute: zod_1.z.number().int().min(1).max(10_000),
264
+ releasesPerCardPerDay: zod_1.z.number().int().min(1).max(1_000),
265
+ });
266
+ /**
267
+ * The identity part of the `agentAccess` settings (ADR-0003): the identity kill switch (default off)
268
+ * and the `identity_fill` bucket's per-minute limit.
269
+ *
270
+ * @stability beta
271
+ */
272
+ exports.agentIdentityAccessSettingsSchema = zod_1.z.object({
273
+ enabled: zod_1.z.boolean(),
274
+ fillPerMinute: zod_1.z.number().int().min(1).max(10_000),
275
+ });
188
276
  /**
189
277
  * The `agentAccess` system settings namespace: the kill switch and the per-minute limits of the
190
278
  * agent API. `enabled` defaults to `false`: until an administrator switches it on, every agent
191
279
  * route answers `403 AGENT_ACCESS_DISABLED`. Each limit counts per token (or OAuth grant) and user.
280
+ * `cards` and `identity` are separate switches (default off) for card and identity release.
192
281
  *
193
- * @stability experimental
282
+ * @stability beta
194
283
  */
195
284
  exports.agentAccessSettingsSchema = zod_1.z.object({
196
285
  enabled: zod_1.z.boolean(),
@@ -198,33 +287,77 @@ exports.agentAccessSettingsSchema = zod_1.z.object({
198
287
  fillPerMinute: zod_1.z.number().int().min(1).max(10_000),
199
288
  totpPerMinute: zod_1.z.number().int().min(1).max(10_000),
200
289
  writePerMinute: zod_1.z.number().int().min(1).max(10_000),
290
+ cards: exports.agentCardAccessSettingsSchema,
291
+ identity: exports.agentIdentityAccessSettingsSchema,
201
292
  });
202
- /** Defaults of {@link agentAccessSettingsSchema}: off, lookup 60, fill 30, totp 10, write 10 per minute. @stability experimental */
293
+ /**
294
+ * Defaults of {@link agentAccessSettingsSchema}: off, lookup 60, fill 30, totp 10, write 10 per
295
+ * minute; cards off, 10 card fills per minute, 5 releases per card per day; identity off, 20
296
+ * identity fills per minute.
297
+ *
298
+ * @stability beta
299
+ */
203
300
  exports.AGENT_ACCESS_SETTINGS_DEFAULTS = Object.freeze({
204
301
  enabled: false,
205
302
  lookupPerMinute: 60,
206
303
  fillPerMinute: 30,
207
304
  totpPerMinute: 10,
208
305
  writePerMinute: 10,
306
+ cards: Object.freeze({ enabled: false, fillPerMinute: 10, releasesPerCardPerDay: 5 }),
307
+ identity: Object.freeze({ enabled: false, fillPerMinute: 20 }),
209
308
  });
309
+ /**
310
+ * A stored (possibly older, partial) `agentAccess` value merged over the defaults, nested blocks
311
+ * included. A row written before ADR-0003 has no `cards` or `identity`: both stay off.
312
+ *
313
+ * @stability beta
314
+ */
315
+ function resolveAgentAccessSettings(stored) {
316
+ const source = stored && typeof stored === 'object' && !Array.isArray(stored) ? stored : {};
317
+ const block = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
318
+ return {
319
+ ...exports.AGENT_ACCESS_SETTINGS_DEFAULTS,
320
+ ...source,
321
+ cards: { ...exports.AGENT_ACCESS_SETTINGS_DEFAULTS.cards, ...block(source.cards) },
322
+ identity: { ...exports.AGENT_ACCESS_SETTINGS_DEFAULTS.identity, ...block(source.identity) },
323
+ };
324
+ }
210
325
  // -----------------------------------------------------------------------------
211
326
  // Agent activity (`GET /api/agent-activity`, E14.7)
212
327
  // -----------------------------------------------------------------------------
213
- /** The path of the owner's agent activity list (session or PAT, never an OAuth token). @stability experimental */
328
+ /** The path of the owner's agent activity list (session or PAT, never an OAuth token). @stability beta */
214
329
  exports.AGENT_ACTIVITY_PATH = '/api/agent-activity';
215
- /** The audit action of the per-secret agent access toggle (`secret.agent_access.update`). @stability experimental */
330
+ /** The audit action of the per-secret agent access toggle (`secret.agent_access.update`). @stability beta */
216
331
  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 */
332
+ /**
333
+ * The actions an activity item carries: the agent routes (logins, cards, identity), the owner's
334
+ * toggle and the owner's grant decisions (`card_grant`: created, revoked, approved, declined).
335
+ *
336
+ * @stability beta
337
+ */
338
+ exports.agentActivityActionSchema = zod_1.z.enum([
339
+ 'lookup',
340
+ 'fill',
341
+ 'totp',
342
+ 'create',
343
+ 'rotate',
344
+ 'agent_access',
345
+ 'card_lookup',
346
+ 'card_fill',
347
+ 'card_grant_request',
348
+ 'identity_lookup',
349
+ 'identity_fill',
350
+ 'card_grant',
351
+ ]);
352
+ /** The kind of credential a call authenticated with. @stability beta */
353
+ exports.agentActivityCredentialKindSchema = zod_1.z.enum(['oauth', 'pat', 'session', 'embedded']);
354
+ /** The largest `pageSize` of the activity list. @stability beta */
222
355
  exports.AGENT_ACTIVITY_MAX_PAGE_SIZE = 100;
223
356
  /**
224
357
  * Query of `GET /api/agent-activity`. `action` is one of {@link agentActivityActionSchema};
225
358
  * `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
359
  *
227
- * @stability experimental
360
+ * @stability beta
228
361
  */
229
362
  exports.agentActivityQuerySchema = zod_1.z.object({
230
363
  page: zod_1.z.coerce.number().int().min(1).default(1),
@@ -239,7 +372,7 @@ exports.agentActivityQuerySchema = zod_1.z.object({
239
372
  * One event of the owner's agent trail. Never carries a value, a code, a seed or a password.
240
373
  * `reason` is present on a denial (`origin_mismatch`, `rate_limited`, `not_found`, ...).
241
374
  *
242
- * @stability experimental
375
+ * @stability beta
243
376
  */
244
377
  exports.agentActivityItemSchema = zod_1.z.object({
245
378
  id: zod_1.z.string(),
@@ -256,10 +389,14 @@ exports.agentActivityItemSchema = zod_1.z.object({
256
389
  purpose: zod_1.z.string().nullable(),
257
390
  credentialKind: exports.agentActivityCredentialKindSchema.nullable(),
258
391
  clientId: zod_1.z.string().nullable(),
259
- /** The OAuth client's registered name; null for a PAT, a session or an unknown client. */
392
+ /** The OAuth client's registered name, or an in-process host's label; null for a PAT, a session or an unknown client. */
260
393
  clientName: zod_1.z.string().nullable(),
394
+ /** A card call's stated amount, as a decimal string (`"42.50"`); absent otherwise. */
395
+ amount: zod_1.z.string().nullable().optional(),
396
+ /** A card call's currency (ISO 4217); absent otherwise. */
397
+ currency: zod_1.z.string().nullable().optional(),
261
398
  });
262
- /** Response of `GET /api/agent-activity`. @stability experimental */
399
+ /** Response of `GET /api/agent-activity`. @stability beta */
263
400
  exports.agentActivityResponseSchema = zod_1.z.object({
264
401
  data: zod_1.z.array(exports.agentActivityItemSchema),
265
402
  meta: zod_1.z.object({
@@ -268,3 +405,5 @@ exports.agentActivityResponseSchema = zod_1.z.object({
268
405
  total: zod_1.z.number().int(),
269
406
  }),
270
407
  });
408
+ __exportStar(require("./cards-identity.js"), exports);
409
+ __exportStar(require("./contract-version.js"), exports);
@@ -0,0 +1,57 @@
1
+ /**
2
+ * Canary values: distinctive invented strings seeded as secret values, then searched for in
3
+ * everything a runtime writes (logs, traces, screenshots' metadata, model transcripts, files). A hit
4
+ * means a value leaked. Vault runs the same kind of scan over its own logs, audit and notifications.
5
+ */
6
+ /** Shortest canary {@link findCanaries} accepts: shorter strings match by chance. @stability beta */
7
+ export declare const MIN_CANARY_LENGTH = 12;
8
+ /**
9
+ * A new canary: `cnry-<label>-<20 random hex>`, unique per call and invented.
10
+ *
11
+ * @stability beta
12
+ */
13
+ export declare function createCanary(label?: string): string;
14
+ /**
15
+ * Canaries for each label (or `count` canaries labelled `value1`, `value2`, ...), to seed as
16
+ * passwords, codes or card security codes in a fake Vault and to scan for afterwards.
17
+ *
18
+ * @stability beta
19
+ */
20
+ export declare function seedCanaries(labels: readonly string[] | number): string[];
21
+ /** One place to scan. A bare string or bytes is content; `{ file }` / `{ files }` are paths (a folder is walked). @stability beta */
22
+ export type CanarySource = string | Uint8Array | ArrayBuffer | {
23
+ label: string;
24
+ content: string | Uint8Array;
25
+ } | {
26
+ file: string;
27
+ } | {
28
+ files: readonly string[];
29
+ } | readonly CanarySource[];
30
+ /** A canary found in a source. `canaryIndex` points into the list passed; the value is never repeated here. @stability beta */
31
+ export interface CanaryHit {
32
+ canaryIndex: number;
33
+ /** `text #n`, `bytes #n`, the label or the file path. */
34
+ where: string;
35
+ /** How it was written: `raw`, `json`, `url`, `base64`, `base64url`, `hex`, `utf16le`. */
36
+ encoding: string;
37
+ }
38
+ /** Thrown by {@link assertNoCanary}. Its message names where and how, never the canary itself. @stability beta */
39
+ export declare class CanaryLeakError extends Error {
40
+ readonly hits: readonly CanaryHit[];
41
+ constructor(hits: readonly CanaryHit[]);
42
+ }
43
+ /**
44
+ * Every place a canary appears in the sources, in any of the encodings a value usually takes on
45
+ * its way into a log or an artifact (raw, JSON-escaped, URL-encoded, hex, UTF-16LE, base64 and
46
+ * base64url at any alignment). Lower-case and upper-case variants of hex are both matched.
47
+ *
48
+ * @stability beta
49
+ */
50
+ export declare function findCanaries(canaries: readonly string[], ...sources: CanarySource[]): CanaryHit[];
51
+ /**
52
+ * Throws {@link CanaryLeakError} when any canary appears in any source (see {@link findCanaries}).
53
+ * Pass a runtime's log text, trace exports, model transcripts, screenshot bytes or `{ files }`.
54
+ *
55
+ * @stability beta
56
+ */
57
+ export declare function assertNoCanary(canaries: readonly string[], ...sources: CanarySource[]): void;
@@ -0,0 +1,165 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.CanaryLeakError = exports.MIN_CANARY_LENGTH = void 0;
4
+ exports.createCanary = createCanary;
5
+ exports.seedCanaries = seedCanaries;
6
+ exports.findCanaries = findCanaries;
7
+ exports.assertNoCanary = assertNoCanary;
8
+ const node_crypto_1 = require("node:crypto");
9
+ const node_fs_1 = require("node:fs");
10
+ const node_path_1 = require("node:path");
11
+ /**
12
+ * Canary values: distinctive invented strings seeded as secret values, then searched for in
13
+ * everything a runtime writes (logs, traces, screenshots' metadata, model transcripts, files). A hit
14
+ * means a value leaked. Vault runs the same kind of scan over its own logs, audit and notifications.
15
+ */
16
+ /** Shortest canary {@link findCanaries} accepts: shorter strings match by chance. @stability beta */
17
+ exports.MIN_CANARY_LENGTH = 12;
18
+ /**
19
+ * A new canary: `cnry-<label>-<20 random hex>`, unique per call and invented.
20
+ *
21
+ * @stability beta
22
+ */
23
+ function createCanary(label = 'value') {
24
+ const clean = label.replace(/[^A-Za-z0-9]/g, '').slice(0, 16) || 'value';
25
+ return `cnry-${clean}-${(0, node_crypto_1.randomBytes)(10).toString('hex')}`;
26
+ }
27
+ /**
28
+ * Canaries for each label (or `count` canaries labelled `value1`, `value2`, ...), to seed as
29
+ * passwords, codes or card security codes in a fake Vault and to scan for afterwards.
30
+ *
31
+ * @stability beta
32
+ */
33
+ function seedCanaries(labels) {
34
+ const list = typeof labels === 'number' ? Array.from({ length: labels }, (_, i) => `value${i + 1}`) : labels;
35
+ return list.map((label) => createCanary(label));
36
+ }
37
+ /** Thrown by {@link assertNoCanary}. Its message names where and how, never the canary itself. @stability beta */
38
+ class CanaryLeakError extends Error {
39
+ hits;
40
+ constructor(hits) {
41
+ super(`A canary value leaked: ${hits
42
+ .slice(0, 10)
43
+ .map((h) => `canary #${h.canaryIndex} in ${h.where} (${h.encoding})`)
44
+ .join('; ')}${hits.length > 10 ? `; and ${hits.length - 10} more` : ''}`);
45
+ this.hits = hits;
46
+ this.name = 'CanaryLeakError';
47
+ }
48
+ }
49
+ exports.CanaryLeakError = CanaryLeakError;
50
+ /** The base64 text that encodes `bytes` wherever they sit in a longer stream (three alignments). */
51
+ function base64Needles(bytes) {
52
+ const out = [];
53
+ for (let k = 0; k < 3; k += 1) {
54
+ const encoded = Buffer.concat([Buffer.alloc(k), bytes]).toString('base64');
55
+ const start = Math.ceil((8 * k) / 6);
56
+ const end = Math.floor((8 * (k + bytes.length)) / 6);
57
+ if (end - start >= 8)
58
+ out.push(encoded.slice(start, end));
59
+ }
60
+ return out;
61
+ }
62
+ function needlesFor(canaries) {
63
+ const needles = [];
64
+ canaries.forEach((canary, canaryIndex) => {
65
+ if (typeof canary !== 'string' || canary.length < exports.MIN_CANARY_LENGTH) {
66
+ throw new RangeError(`Canary #${canaryIndex} is shorter than ${exports.MIN_CANARY_LENGTH} characters`);
67
+ }
68
+ const raw = Buffer.from(canary, 'utf8');
69
+ const add = (encoding, text) => needles.push({ canaryIndex, encoding, bytes: typeof text === 'string' ? Buffer.from(text, 'utf8') : text });
70
+ add('raw', raw);
71
+ const json = JSON.stringify(canary).slice(1, -1);
72
+ if (json !== canary)
73
+ add('json', json);
74
+ const url = encodeURIComponent(canary);
75
+ if (url !== canary)
76
+ add('url', url);
77
+ add('hex', raw.toString('hex'));
78
+ add('utf16le', Buffer.from(canary, 'utf16le'));
79
+ for (const b64 of base64Needles(raw)) {
80
+ add('base64', b64);
81
+ const b64url = b64.replace(/\+/g, '-').replace(/\//g, '_');
82
+ if (b64url !== b64)
83
+ add('base64url', b64url);
84
+ }
85
+ });
86
+ return needles;
87
+ }
88
+ function walk(path, out) {
89
+ const stat = (0, node_fs_1.statSync)(path);
90
+ if (stat.isDirectory()) {
91
+ for (const entry of (0, node_fs_1.readdirSync)(path))
92
+ walk((0, node_path_1.join)(path, entry), out);
93
+ }
94
+ else if (stat.isFile()) {
95
+ out.push(path);
96
+ }
97
+ }
98
+ function collect(source, out, counter) {
99
+ if (typeof source === 'string') {
100
+ counter.text += 1;
101
+ out.push({ where: `text #${counter.text}`, bytes: Buffer.from(source, 'utf8') });
102
+ }
103
+ else if (source instanceof Uint8Array) {
104
+ counter.bytes += 1;
105
+ out.push({ where: `bytes #${counter.bytes}`, bytes: Buffer.from(source.buffer, source.byteOffset, source.byteLength) });
106
+ }
107
+ else if (source instanceof ArrayBuffer) {
108
+ counter.bytes += 1;
109
+ out.push({ where: `bytes #${counter.bytes}`, bytes: Buffer.from(source) });
110
+ }
111
+ else if (Array.isArray(source)) {
112
+ for (const item of source)
113
+ collect(item, out, counter);
114
+ }
115
+ else if ('content' in source) {
116
+ out.push({ where: source.label, bytes: typeof source.content === 'string' ? Buffer.from(source.content, 'utf8') : Buffer.from(source.content) });
117
+ }
118
+ else {
119
+ const paths = [];
120
+ const list = 'file' in source ? [source.file] : source.files;
121
+ for (const path of list)
122
+ walk(path, paths);
123
+ for (const path of paths)
124
+ out.push({ where: path, bytes: (0, node_fs_1.readFileSync)(path) });
125
+ }
126
+ }
127
+ /**
128
+ * Every place a canary appears in the sources, in any of the encodings a value usually takes on
129
+ * its way into a log or an artifact (raw, JSON-escaped, URL-encoded, hex, UTF-16LE, base64 and
130
+ * base64url at any alignment). Lower-case and upper-case variants of hex are both matched.
131
+ *
132
+ * @stability beta
133
+ */
134
+ function findCanaries(canaries, ...sources) {
135
+ const needles = needlesFor(canaries);
136
+ const haystacks = [];
137
+ const counter = { text: 0, bytes: 0 };
138
+ for (const source of sources)
139
+ collect(source, haystacks, counter);
140
+ const hits = [];
141
+ for (const { where, bytes } of haystacks) {
142
+ const lowered = Buffer.from(bytes.toString('latin1').toLowerCase(), 'latin1');
143
+ const seen = new Set();
144
+ for (const needle of needles) {
145
+ const found = needle.encoding === 'hex' ? lowered.includes(needle.bytes) : bytes.includes(needle.bytes);
146
+ const key = `${needle.canaryIndex}:${needle.encoding}`;
147
+ if (found && !seen.has(key)) {
148
+ seen.add(key);
149
+ hits.push({ canaryIndex: needle.canaryIndex, where, encoding: needle.encoding });
150
+ }
151
+ }
152
+ }
153
+ return hits;
154
+ }
155
+ /**
156
+ * Throws {@link CanaryLeakError} when any canary appears in any source (see {@link findCanaries}).
157
+ * Pass a runtime's log text, trace exports, model transcripts, screenshot bytes or `{ files }`.
158
+ *
159
+ * @stability beta
160
+ */
161
+ function assertNoCanary(canaries, ...sources) {
162
+ const hits = findCanaries(canaries, ...sources);
163
+ if (hits.length > 0)
164
+ throw new CanaryLeakError(hits);
165
+ }