@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
@@ -0,0 +1,272 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.CARD_GRANT_AUDIT_ACTIONS = exports.cardGrantRequestListResponseSchema = exports.cardGrantRequestSchema = exports.cardGrantRequestListQuerySchema = exports.cardGrantListResponseSchema = exports.cardGrantSchema = exports.cardGrantStatusSchema = exports.createCardGrantSchema = exports.MAX_CARD_GRANT_FRAME_ORIGINS = exports.cardGrantPeriodLimitSchema = exports.agentIdentityFillRequestSchema = exports.agentIdentityLookupResponseSchema = exports.agentIdentitySummarySchema = exports.agentIdentityFieldSummarySchema = exports.agentIdentityLookupQuerySchema = exports.agentIdentityFieldSchema = exports.AGENT_IDENTITY_FIELDS = exports.agentCardGrantRequestResponseSchema = exports.cardGrantRequestStatusSchema = exports.agentCardGrantRequestCreateSchema = exports.agentValueResponseSchema = exports.agentCardFillRequestSchema = exports.agentCardsLookupResponseSchema = exports.agentCardSummarySchema = exports.agentCardGrantSummarySchema = exports.agentCardsLookupQuerySchema = exports.AGENT_CARD_FIELD_MAP = exports.agentCardFillFieldSchema = exports.agentCurrencySchema = exports.agentAmountSchema = exports.AGENT_MAX_AMOUNT = void 0;
4
+ exports.amountToMinor = amountToMinor;
5
+ exports.minorToAmount = minorToAmount;
6
+ exports.formatMinorAmount = formatMinorAmount;
7
+ const zod_1 = require("zod");
8
+ /**
9
+ * Agent release of payment cards and identity fields (ADR-0003 of the Vault repository):
10
+ * the agent routes under `/api/agent/v1/cards` and `/api/agent/v1/identity`, and the owner's
11
+ * merchant grants and grant requests under `/api/secrets/:id/card-grants` and
12
+ * `/api/secrets/:id/card-grant-requests`.
13
+ *
14
+ * Request and response shapes only. Behaviour (the grant rules, the kill switches, rate limits,
15
+ * audit) is the API's. Never a value in a schema here except the one `{ value }` a fill returns.
16
+ *
17
+ * @packageDocumentation
18
+ */
19
+ // -----------------------------------------------------------------------------
20
+ // Money
21
+ // -----------------------------------------------------------------------------
22
+ /** The largest amount a grant or a call may carry: 10,000,000.00. @stability beta */
23
+ exports.AGENT_MAX_AMOUNT = 10_000_000;
24
+ /**
25
+ * An amount in major units with at most two decimal places, greater than zero and at most
26
+ * {@link AGENT_MAX_AMOUNT}. The API stores it in hundredths.
27
+ *
28
+ * @stability beta
29
+ */
30
+ exports.agentAmountSchema = zod_1.z
31
+ .number()
32
+ .positive()
33
+ .max(exports.AGENT_MAX_AMOUNT)
34
+ .refine((value) => Math.abs(Math.round(value * 100) - value * 100) < 1e-6, {
35
+ message: 'Use at most two decimal places',
36
+ });
37
+ /** An ISO 4217 currency code, upper case (`USD`, `EUR`). Lower case is accepted and upper-cased. @stability beta */
38
+ exports.agentCurrencySchema = zod_1.z
39
+ .string()
40
+ .trim()
41
+ .transform((value) => value.toUpperCase())
42
+ .pipe(zod_1.z.string().regex(/^[A-Z]{3}$/, 'Use a three-letter ISO 4217 currency code'));
43
+ /** An amount in hundredths (the stored form). @stability beta */
44
+ function amountToMinor(amount) {
45
+ return Math.round(amount * 100);
46
+ }
47
+ /** Hundredths back to a major-unit number. @stability beta */
48
+ function minorToAmount(minor) {
49
+ return Math.round(minor) / 100;
50
+ }
51
+ /** Hundredths as a two-decimal string (`4250` is `"42.50"`), for the activity trail. @stability beta */
52
+ function formatMinorAmount(minor) {
53
+ return (Math.round(minor) / 100).toFixed(2);
54
+ }
55
+ const originSchema = zod_1.z.string().trim().min(1).max(2048);
56
+ // -----------------------------------------------------------------------------
57
+ // Cards: the agent routes
58
+ // -----------------------------------------------------------------------------
59
+ /**
60
+ * The one card field a fill returns. Stored field of the `Card` type each maps to:
61
+ * `number` (number), `expMonth` (exp_month), `expYear` (exp_year), `holderName` (cardholder_name),
62
+ * `securityCode` (cvv), `postalCode` (billing_postal_code).
63
+ *
64
+ * @stability beta
65
+ */
66
+ exports.agentCardFillFieldSchema = zod_1.z.enum(['number', 'expMonth', 'expYear', 'holderName', 'securityCode', 'postalCode']);
67
+ /** The stored `Card` type field behind each {@link AgentCardFillField}. @stability beta */
68
+ exports.AGENT_CARD_FIELD_MAP = Object.freeze({
69
+ number: 'number',
70
+ expMonth: 'exp_month',
71
+ expYear: 'exp_year',
72
+ holderName: 'cardholder_name',
73
+ securityCode: 'cvv',
74
+ postalCode: 'billing_postal_code',
75
+ });
76
+ /** Query of `GET /api/agent/v1/cards`: the top-level page's origin (the merchant). @stability beta */
77
+ exports.agentCardsLookupQuerySchema = zod_1.z.object({ origin: originSchema });
78
+ /** The grant a card is listed under. @stability beta */
79
+ exports.agentCardGrantSummarySchema = zod_1.z.object({
80
+ maxAmount: zod_1.z.number(),
81
+ currency: zod_1.z.string(),
82
+ includesSecurityCode: zod_1.z.boolean(),
83
+ /** ISO 8601, or null for no expiry. */
84
+ expiresAt: zod_1.z.string().nullable(),
85
+ });
86
+ /**
87
+ * One opened card with a live grant for the asked merchant. Never a number or a code:
88
+ * `last4` is the only part of the number, and `brand` is the stored network.
89
+ *
90
+ * @stability beta
91
+ */
92
+ exports.agentCardSummarySchema = zod_1.z.object({
93
+ id: zod_1.z.string().uuid(),
94
+ name: zod_1.z.string(),
95
+ brand: zod_1.z.string().nullable(),
96
+ last4: zod_1.z.string().nullable(),
97
+ expMonth: zod_1.z.string().nullable(),
98
+ expYear: zod_1.z.string().nullable(),
99
+ grant: exports.agentCardGrantSummarySchema,
100
+ });
101
+ /** Response of `GET /api/agent/v1/cards`. @stability beta */
102
+ exports.agentCardsLookupResponseSchema = zod_1.z.object({ data: zod_1.z.array(exports.agentCardSummarySchema) });
103
+ /**
104
+ * Body of `POST /api/agent/v1/cards/:id/fill`: ONE field, the merchant's top-level origin, the
105
+ * embedded payment frame's origin when the field is typed into one, and the purchase's amount and
106
+ * currency (checked against the grant and recorded).
107
+ *
108
+ * @stability beta
109
+ */
110
+ exports.agentCardFillRequestSchema = zod_1.z.object({
111
+ field: exports.agentCardFillFieldSchema,
112
+ origin: originSchema,
113
+ frameOrigin: originSchema.optional(),
114
+ amount: exports.agentAmountSchema,
115
+ currency: exports.agentCurrencySchema,
116
+ purpose: zod_1.z.literal('purchase'),
117
+ });
118
+ /** Response of a card or identity fill: one value. Type it, never show it to a model or put it in a screenshot. @stability beta */
119
+ exports.agentValueResponseSchema = zod_1.z.object({ data: zod_1.z.object({ value: zod_1.z.string() }) });
120
+ /** Body of `POST /api/agent/v1/cards/:id/grant-requests`. @stability beta */
121
+ exports.agentCardGrantRequestCreateSchema = zod_1.z.object({
122
+ origin: originSchema,
123
+ amount: exports.agentAmountSchema,
124
+ currency: exports.agentCurrencySchema,
125
+ /** Shown to the owner. Plain text, no card data. */
126
+ reason: zod_1.z.string().trim().min(1).max(500),
127
+ });
128
+ /** The status of a grant request. @stability beta */
129
+ exports.cardGrantRequestStatusSchema = zod_1.z.enum(['pending', 'approved', 'declined']);
130
+ /** Response of the grant-request route: an id and a status, never card data. @stability beta */
131
+ exports.agentCardGrantRequestResponseSchema = zod_1.z.object({
132
+ data: zod_1.z.object({ id: zod_1.z.string().uuid(), status: exports.cardGrantRequestStatusSchema }),
133
+ });
134
+ // -----------------------------------------------------------------------------
135
+ // Identity: the agent routes
136
+ // -----------------------------------------------------------------------------
137
+ /**
138
+ * The fields of the `Identity` system type an agent may ask for (every field but `notes`).
139
+ * `date_of_birth` and `id_number` are sensitive: released only to an origin on the item's
140
+ * allowed origins.
141
+ *
142
+ * @stability beta
143
+ */
144
+ exports.AGENT_IDENTITY_FIELDS = [
145
+ 'full_name',
146
+ 'date_of_birth',
147
+ 'id_type',
148
+ 'id_number',
149
+ 'id_issuing_country',
150
+ 'address_line1',
151
+ 'address_line2',
152
+ 'city',
153
+ 'region',
154
+ 'postal_code',
155
+ 'country',
156
+ 'phone',
157
+ 'email',
158
+ ];
159
+ /** @stability beta */
160
+ exports.agentIdentityFieldSchema = zod_1.z.enum(exports.AGENT_IDENTITY_FIELDS);
161
+ /** Query of `GET /api/agent/v1/identity`: the origin of the form. @stability beta */
162
+ exports.agentIdentityLookupQuerySchema = zod_1.z.object({ origin: originSchema });
163
+ /** One field of an identity item as the lookup lists it: a label, never a value. @stability beta */
164
+ exports.agentIdentityFieldSummarySchema = zod_1.z.object({
165
+ field: exports.agentIdentityFieldSchema,
166
+ label: zod_1.z.string(),
167
+ sensitive: zod_1.z.boolean(),
168
+ /** Whether a fill of this field on the asked origin would be allowed (non-sensitive, or the origin is allowed). */
169
+ fillable: zod_1.z.boolean(),
170
+ });
171
+ /** One opened identity item. @stability beta */
172
+ exports.agentIdentitySummarySchema = zod_1.z.object({
173
+ id: zod_1.z.string().uuid(),
174
+ name: zod_1.z.string(),
175
+ /** Whether the asked origin is on the item's allowed origins (sensitive fields are fillable there). */
176
+ originAllowed: zod_1.z.boolean(),
177
+ fields: zod_1.z.array(exports.agentIdentityFieldSummarySchema),
178
+ });
179
+ /** Response of `GET /api/agent/v1/identity`. @stability beta */
180
+ exports.agentIdentityLookupResponseSchema = zod_1.z.object({ data: zod_1.z.array(exports.agentIdentitySummarySchema) });
181
+ /** Body of `POST /api/agent/v1/identity/:id/fill`. @stability beta */
182
+ exports.agentIdentityFillRequestSchema = zod_1.z.object({
183
+ field: exports.agentIdentityFieldSchema,
184
+ origin: originSchema,
185
+ purpose: zod_1.z.literal('form'),
186
+ });
187
+ // -----------------------------------------------------------------------------
188
+ // Owner: merchant grants and grant requests (browser session only)
189
+ // -----------------------------------------------------------------------------
190
+ /** A grant's optional period limit: at most `maxReleases` and/or `maxAmount` per UTC day or month. @stability beta */
191
+ exports.cardGrantPeriodLimitSchema = zod_1.z
192
+ .object({
193
+ period: zod_1.z.enum(['day', 'month']),
194
+ maxReleases: zod_1.z.number().int().min(1).max(1_000).optional(),
195
+ maxAmount: exports.agentAmountSchema.optional(),
196
+ })
197
+ .refine((limit) => limit.maxReleases !== undefined || limit.maxAmount !== undefined, {
198
+ message: 'Set maxReleases, maxAmount or both',
199
+ path: ['maxReleases'],
200
+ });
201
+ /** Most payment frame origins one grant may list. @stability beta */
202
+ exports.MAX_CARD_GRANT_FRAME_ORIGINS = 10;
203
+ /** Body of `POST /api/secrets/:id/card-grants` (owner, browser session). @stability beta */
204
+ exports.createCardGrantSchema = zod_1.z.object({
205
+ merchantOrigin: originSchema,
206
+ frameOrigins: zod_1.z.array(originSchema).max(exports.MAX_CARD_GRANT_FRAME_ORIGINS).default([]),
207
+ maxAmount: exports.agentAmountSchema,
208
+ currency: exports.agentCurrencySchema,
209
+ periodLimit: exports.cardGrantPeriodLimitSchema.nullable().optional(),
210
+ /** ISO 8601 with an offset; must be in the future. */
211
+ expiresAt: zod_1.z.string().datetime({ offset: true }).nullable().optional(),
212
+ includeSecurityCode: zod_1.z.boolean().default(false),
213
+ });
214
+ /** A grant's state: live, past its expiry, or revoked by the owner. @stability beta */
215
+ exports.cardGrantStatusSchema = zod_1.z.enum(['active', 'expired', 'revoked']);
216
+ /** One merchant grant as the owner sees it, with its use. @stability beta */
217
+ exports.cardGrantSchema = zod_1.z.object({
218
+ id: zod_1.z.string().uuid(),
219
+ secretId: zod_1.z.string().uuid(),
220
+ merchantOrigin: zod_1.z.string(),
221
+ /** The registrable domain requests are matched on. */
222
+ merchantSite: zod_1.z.string(),
223
+ frameOrigins: zod_1.z.array(zod_1.z.string()),
224
+ maxAmount: zod_1.z.number(),
225
+ currency: zod_1.z.string(),
226
+ periodLimit: zod_1.z
227
+ .object({ period: zod_1.z.enum(['day', 'month']), maxReleases: zod_1.z.number().nullable(), maxAmount: zod_1.z.number().nullable() })
228
+ .nullable(),
229
+ expiresAt: zod_1.z.string().nullable(),
230
+ includeSecurityCode: zod_1.z.boolean(),
231
+ status: exports.cardGrantStatusSchema,
232
+ createdAt: zod_1.z.string(),
233
+ revokedAt: zod_1.z.string().nullable(),
234
+ usage: zod_1.z.object({
235
+ /** Releases (`number` fills) in the current period (UTC day, or month when the limit is monthly). */
236
+ periodReleases: zod_1.z.number().int(),
237
+ /** Their total amount. */
238
+ periodAmount: zod_1.z.number(),
239
+ totalReleases: zod_1.z.number().int(),
240
+ lastReleasedAt: zod_1.z.string().nullable(),
241
+ }),
242
+ });
243
+ /** Response of `GET /api/secrets/:id/card-grants`: active first, then expired and revoked. @stability beta */
244
+ exports.cardGrantListResponseSchema = zod_1.z.object({ data: zod_1.z.array(exports.cardGrantSchema) });
245
+ /** Query of `GET /api/secrets/:id/card-grant-requests`. @stability beta */
246
+ exports.cardGrantRequestListQuerySchema = zod_1.z.object({ status: exports.cardGrantRequestStatusSchema.optional() });
247
+ /** One grant request as the owner sees it. @stability beta */
248
+ exports.cardGrantRequestSchema = zod_1.z.object({
249
+ id: zod_1.z.string().uuid(),
250
+ secretId: zod_1.z.string().uuid(),
251
+ origin: zod_1.z.string(),
252
+ merchantSite: zod_1.z.string(),
253
+ amount: zod_1.z.number(),
254
+ currency: zod_1.z.string(),
255
+ reason: zod_1.z.string(),
256
+ status: exports.cardGrantRequestStatusSchema,
257
+ /** The asking app: an OAuth client's name, an in-process host's label, or `Personal access token`. */
258
+ clientName: zod_1.z.string().nullable(),
259
+ createdAt: zod_1.z.string(),
260
+ decidedAt: zod_1.z.string().nullable(),
261
+ /** The grant an approval created. */
262
+ grantId: zod_1.z.string().nullable(),
263
+ });
264
+ /** Response of the grant-request list, newest first. @stability beta */
265
+ exports.cardGrantRequestListResponseSchema = zod_1.z.object({ data: zod_1.z.array(exports.cardGrantRequestSchema) });
266
+ /** The owner's audit actions on grants (`audit_events.action`). @stability beta */
267
+ exports.CARD_GRANT_AUDIT_ACTIONS = {
268
+ CREATE: 'secret.card_grant.create',
269
+ REVOKE: 'secret.card_grant.revoke',
270
+ APPROVE: 'secret.card_grant_request.approve',
271
+ DECLINE: 'secret.card_grant_request.decline',
272
+ };
@@ -0,0 +1,58 @@
1
+ import { z } from 'zod';
2
+ /**
3
+ * The version of the agent contract (issue #196): `<path major>.<minor>`. The major is the `v` of
4
+ * the base path (`/api/agent/v1` is major 1) and changes only with a new path; the minor grows
5
+ * with every additive change listed under "Changes" in `docs/agent-credential-api.md`.
6
+ *
7
+ * - `1.0`: logins (lookup, fill, totp, create, rotate) and `whoami`.
8
+ * - `1.1`: cards and identity (ADR-0003).
9
+ * - `1.2`: `whoami.contract`, the stability promise, the conformance kit.
10
+ *
11
+ * @stability beta
12
+ */
13
+ export declare const AGENT_CONTRACT_VERSION: "1.2";
14
+ /**
15
+ * The feature ids `whoami` can report in `contract.features`. A runtime must ignore an id it does
16
+ * not know: a newer Vault may report more.
17
+ *
18
+ * - `logins`: the login routes (`/credentials`, fill, create, rotate).
19
+ * - `totp`: one-time codes of logins (`/credentials/:id/totp`).
20
+ * - `cards`: card release (`/cards`); only while `agentAccess.cards.enabled` is on.
21
+ * - `identity`: identity release (`/identity`); only while `agentAccess.identity.enabled` is on.
22
+ *
23
+ * @stability beta
24
+ */
25
+ export declare const AGENT_CONTRACT_FEATURES: {
26
+ readonly LOGINS: "logins";
27
+ readonly TOTP: "totp";
28
+ readonly CARDS: "cards";
29
+ readonly IDENTITY: "identity";
30
+ };
31
+ /** @stability beta */
32
+ export type AgentContractFeature = (typeof AGENT_CONTRACT_FEATURES)[keyof typeof AGENT_CONTRACT_FEATURES];
33
+ /**
34
+ * `whoami`'s `contract` block: the contract version this Vault speaks and the features it offers
35
+ * now. `features` is plain strings, not an enum, so a runtime keeps parsing a newer Vault's answer.
36
+ *
37
+ * @stability beta
38
+ */
39
+ export declare const agentContractInfoSchema: z.ZodObject<{
40
+ version: z.ZodString;
41
+ features: z.ZodArray<z.ZodString>;
42
+ }, z.core.$strip>;
43
+ /** @stability beta */
44
+ export type AgentContractInfo = z.infer<typeof agentContractInfoSchema>;
45
+ /**
46
+ * The `contract` block a Vault with these switches reports. Logins and codes are on whenever the
47
+ * agent API answers at all; cards and identity follow their own switches.
48
+ *
49
+ * @stability beta
50
+ */
51
+ export declare function agentContractInfoFor(switches: {
52
+ cards: {
53
+ enabled: boolean;
54
+ };
55
+ identity: {
56
+ enabled: boolean;
57
+ };
58
+ }): AgentContractInfo;
@@ -0,0 +1,58 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.agentContractInfoSchema = exports.AGENT_CONTRACT_FEATURES = exports.AGENT_CONTRACT_VERSION = void 0;
4
+ exports.agentContractInfoFor = agentContractInfoFor;
5
+ const zod_1 = require("zod");
6
+ /**
7
+ * The version of the agent contract (issue #196): `<path major>.<minor>`. The major is the `v` of
8
+ * the base path (`/api/agent/v1` is major 1) and changes only with a new path; the minor grows
9
+ * with every additive change listed under "Changes" in `docs/agent-credential-api.md`.
10
+ *
11
+ * - `1.0`: logins (lookup, fill, totp, create, rotate) and `whoami`.
12
+ * - `1.1`: cards and identity (ADR-0003).
13
+ * - `1.2`: `whoami.contract`, the stability promise, the conformance kit.
14
+ *
15
+ * @stability beta
16
+ */
17
+ exports.AGENT_CONTRACT_VERSION = '1.2';
18
+ /**
19
+ * The feature ids `whoami` can report in `contract.features`. A runtime must ignore an id it does
20
+ * not know: a newer Vault may report more.
21
+ *
22
+ * - `logins`: the login routes (`/credentials`, fill, create, rotate).
23
+ * - `totp`: one-time codes of logins (`/credentials/:id/totp`).
24
+ * - `cards`: card release (`/cards`); only while `agentAccess.cards.enabled` is on.
25
+ * - `identity`: identity release (`/identity`); only while `agentAccess.identity.enabled` is on.
26
+ *
27
+ * @stability beta
28
+ */
29
+ exports.AGENT_CONTRACT_FEATURES = {
30
+ LOGINS: 'logins',
31
+ TOTP: 'totp',
32
+ CARDS: 'cards',
33
+ IDENTITY: 'identity',
34
+ };
35
+ /**
36
+ * `whoami`'s `contract` block: the contract version this Vault speaks and the features it offers
37
+ * now. `features` is plain strings, not an enum, so a runtime keeps parsing a newer Vault's answer.
38
+ *
39
+ * @stability beta
40
+ */
41
+ exports.agentContractInfoSchema = zod_1.z.object({
42
+ version: zod_1.z.string(),
43
+ features: zod_1.z.array(zod_1.z.string()),
44
+ });
45
+ /**
46
+ * The `contract` block a Vault with these switches reports. Logins and codes are on whenever the
47
+ * agent API answers at all; cards and identity follow their own switches.
48
+ *
49
+ * @stability beta
50
+ */
51
+ function agentContractInfoFor(switches) {
52
+ const features = [exports.AGENT_CONTRACT_FEATURES.LOGINS, exports.AGENT_CONTRACT_FEATURES.TOTP];
53
+ if (switches.cards.enabled)
54
+ features.push(exports.AGENT_CONTRACT_FEATURES.CARDS);
55
+ if (switches.identity.enabled)
56
+ features.push(exports.AGENT_CONTRACT_FEATURES.IDENTITY);
57
+ return { version: exports.AGENT_CONTRACT_VERSION, features };
58
+ }