@marinoscar/vault-contract 0.0.0-stage → 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 (98) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/LICENSE +21 -0
  3. package/README.md +83 -2
  4. package/dist/cjs/agent/cards-identity.d.ts +456 -0
  5. package/dist/cjs/agent/cards-identity.js +272 -0
  6. package/dist/cjs/agent/contract-version.d.ts +58 -0
  7. package/dist/cjs/agent/contract-version.js +58 -0
  8. package/dist/cjs/agent/index.d.ts +533 -0
  9. package/dist/cjs/agent/index.js +409 -0
  10. package/dist/cjs/agent-testing/canary.d.ts +57 -0
  11. package/dist/cjs/agent-testing/canary.js +165 -0
  12. package/dist/cjs/agent-testing/fake-vault.d.ts +111 -0
  13. package/dist/cjs/agent-testing/fake-vault.js +707 -0
  14. package/dist/cjs/agent-testing/guard.d.ts +16 -0
  15. package/dist/cjs/agent-testing/guard.js +28 -0
  16. package/dist/cjs/agent-testing/index.d.ts +28 -0
  17. package/dist/cjs/agent-testing/index.js +43 -0
  18. package/dist/cjs/agent-testing/recorder.d.ts +70 -0
  19. package/dist/cjs/agent-testing/recorder.js +127 -0
  20. package/dist/cjs/agent-testing/reference-runtime.d.ts +8 -0
  21. package/dist/cjs/agent-testing/reference-runtime.js +112 -0
  22. package/dist/cjs/agent-testing/scenarios.d.ts +128 -0
  23. package/dist/cjs/agent-testing/scenarios.js +566 -0
  24. package/dist/cjs/agent-testing/seed.d.ts +84 -0
  25. package/dist/cjs/agent-testing/seed.js +89 -0
  26. package/dist/cjs/agent-testing/totp.d.ts +10 -0
  27. package/dist/cjs/agent-testing/totp.js +45 -0
  28. package/dist/cjs/backups/backup-contents.d.ts +80 -0
  29. package/dist/cjs/backups/backup-contents.js +121 -0
  30. package/dist/cjs/backups/index.d.ts +130 -0
  31. package/dist/cjs/backups/index.js +270 -0
  32. package/dist/cjs/backups/responses.d.ts +76 -0
  33. package/dist/cjs/backups/responses.js +2 -0
  34. package/dist/cjs/common/index.d.ts +21 -0
  35. package/dist/cjs/common/index.js +27 -0
  36. package/dist/cjs/errors/index.d.ts +54 -0
  37. package/dist/cjs/errors/index.js +77 -0
  38. package/dist/cjs/index.d.ts +12 -0
  39. package/dist/cjs/index.js +15 -0
  40. package/dist/cjs/media/index.d.ts +55 -0
  41. package/dist/cjs/media/index.js +42 -0
  42. package/dist/cjs/package.json +1 -0
  43. package/dist/cjs/secret-types/index.d.ts +136 -0
  44. package/dist/cjs/secret-types/index.js +243 -0
  45. package/dist/cjs/secrets/index.d.ts +209 -0
  46. package/dist/cjs/secrets/index.js +183 -0
  47. package/dist/cjs/secrets/origins.d.ts +44 -0
  48. package/dist/cjs/secrets/origins.js +103 -0
  49. package/dist/cjs/secrets/totp.d.ts +41 -0
  50. package/dist/cjs/secrets/totp.js +139 -0
  51. package/dist/esm/agent/cards-identity.d.ts +456 -0
  52. package/dist/esm/agent/cards-identity.js +266 -0
  53. package/dist/esm/agent/contract-version.d.ts +58 -0
  54. package/dist/esm/agent/contract-version.js +54 -0
  55. package/dist/esm/agent/index.d.ts +533 -0
  56. package/dist/esm/agent/index.js +391 -0
  57. package/dist/esm/agent-testing/canary.d.ts +57 -0
  58. package/dist/esm/agent-testing/canary.js +157 -0
  59. package/dist/esm/agent-testing/fake-vault.d.ts +111 -0
  60. package/dist/esm/agent-testing/fake-vault.js +704 -0
  61. package/dist/esm/agent-testing/guard.d.ts +16 -0
  62. package/dist/esm/agent-testing/guard.js +23 -0
  63. package/dist/esm/agent-testing/index.d.ts +28 -0
  64. package/dist/esm/agent-testing/index.js +27 -0
  65. package/dist/esm/agent-testing/recorder.d.ts +70 -0
  66. package/dist/esm/agent-testing/recorder.js +122 -0
  67. package/dist/esm/agent-testing/reference-runtime.d.ts +8 -0
  68. package/dist/esm/agent-testing/reference-runtime.js +109 -0
  69. package/dist/esm/agent-testing/scenarios.d.ts +128 -0
  70. package/dist/esm/agent-testing/scenarios.js +560 -0
  71. package/dist/esm/agent-testing/seed.d.ts +84 -0
  72. package/dist/esm/agent-testing/seed.js +85 -0
  73. package/dist/esm/agent-testing/totp.d.ts +10 -0
  74. package/dist/esm/agent-testing/totp.js +42 -0
  75. package/dist/esm/backups/backup-contents.d.ts +80 -0
  76. package/dist/esm/backups/backup-contents.js +114 -0
  77. package/dist/esm/backups/index.d.ts +130 -0
  78. package/dist/esm/backups/index.js +251 -0
  79. package/dist/esm/backups/responses.d.ts +76 -0
  80. package/dist/esm/backups/responses.js +1 -0
  81. package/dist/esm/common/index.d.ts +21 -0
  82. package/dist/esm/common/index.js +23 -0
  83. package/dist/esm/errors/index.d.ts +54 -0
  84. package/dist/esm/errors/index.js +73 -0
  85. package/dist/esm/index.d.ts +12 -0
  86. package/dist/esm/index.js +12 -0
  87. package/dist/esm/media/index.d.ts +55 -0
  88. package/dist/esm/media/index.js +39 -0
  89. package/dist/esm/package.json +1 -0
  90. package/dist/esm/secret-types/index.d.ts +136 -0
  91. package/dist/esm/secret-types/index.js +240 -0
  92. package/dist/esm/secrets/index.d.ts +209 -0
  93. package/dist/esm/secrets/index.js +166 -0
  94. package/dist/esm/secrets/origins.d.ts +44 -0
  95. package/dist/esm/secrets/origins.js +96 -0
  96. package/dist/esm/secrets/totp.d.ts +41 -0
  97. package/dist/esm/secrets/totp.js +134 -0
  98. package/package.json +140 -4
package/CHANGELOG.md ADDED
@@ -0,0 +1,39 @@
1
+ # @marinoscar/vault-contract
2
+
3
+ ## 0.1.0-next.4
4
+
5
+ ### Minor Changes
6
+
7
+ - ffd128f: Agent release of payment cards and identity fields, with per-merchant rules (ADR-0003, #195).
8
+
9
+ - `@marinoscar/vault-contract`: card and identity agent schemas (`agentCardFillRequestSchema`, `agentCardSummarySchema`, `agentCardGrantRequestCreateSchema`, `agentIdentityFillRequestSchema`, `agentIdentitySummarySchema`), the owner's merchant grant and grant request shapes (`createCardGrantSchema`, `cardGrantSchema`, `cardGrantRequestSchema`), amount and currency schemas and helpers, scopes `vault:cards_read|fill` and `vault:identity_read|fill`, new error codes, the `cards` and `identity` blocks of the `agentAccess` settings (both off by default) with `resolveAgentAccessSettings`, the `Identity` system secret type and the Card's optional `billing_postal_code`.
10
+ - `@marinoscar/vault-db`: migration `add_agent_card_grants` (tables `agent_card_grants`, `agent_card_grant_requests`, `agent_card_releases`; column `secrets.agent_origins`).
11
+ - `@marinoscar/vault-api`: `AgentReleasePort` / `AGENT_RELEASE_PORT` / `AgentReleaseService`, the in-process port an embedding host calls, shared with the HTTP controllers; `AgentCallPipeline`; card routes (`GET /api/agent/v1/cards`, `POST /cards/:id/fill`, `POST /cards/:id/grant-requests`) and identity routes (`GET /identity`, `POST /identity/:id/fill`) with merchant grants (registrable-domain match, payment frames, amount and currency, period limit, per-card daily cap, security code flag), their own rate-limit buckets and kill switches; the owner's grant routes under `/api/secrets/:id/card-grants` and `/card-grant-requests` (browser session only); a Card or Identity can be opened to agents (browser session only) and an Identity takes allowed origins; card notifications and activity; permissions `agent_cards:*` and `agent_identity:*`.
12
+ - `@marinoscar/vault-web`: the card's Agent access panel (open or closed, merchant grants with limits and use, pending requests with Approve and Decline, the allow-a-shop form), the identity panel (open or closed, allowed websites), card and identity switches and limits on the Agent access settings page, and the new activity actions with amounts.
13
+
14
+ - 80fa35b: The agent contract is beta, with a versioning promise and a conformance kit for agent runtimes (#196).
15
+
16
+ - `@marinoscar/vault-contract`: `./agent` is `@stability beta`. `AGENT_CONTRACT_VERSION` (`1.2`), `AGENT_CONTRACT_FEATURES`, `agentContractInfoSchema`, `agentContractInfoFor`, and an optional `contract` block on `agentWhoamiResponseSchema`. New subpath `./agent-testing` (Node only, CommonJS and ESM): `createFakeVault` (an in-memory `/api/agent/v1` with exact origin binding, the identical 404, scopes, kill switches, rate limits with `Retry-After`, refresh-token rotation and replay revocation; invented data only; refuses `NODE_ENV=production`), the canary helpers `seedCanaries`, `createCanary`, `findCanaries`, `assertNoCanary`, the scenario list `AGENT_CONFORMANCE_SCENARIOS` with `runAgentConformance` / `assertAgentConformance`, `createConformanceSeed` and `createReferenceSignIn`. A shape snapshot test holds the promise: additive changes pass, breaking ones need `/api/agent/v2` and an `ACCEPT_BREAKING` changelog entry. `v1` stays for two minor releases after `v2` ships.
17
+ - `@marinoscar/vault-api`: `GET /api/agent/v1/whoami` adds `contract: { version, features }` (`logins`, `totp`, and `cards` / `identity` while their switches are on); `AgentCredentialsService.contractInfo()`. Additive.
18
+
19
+ ## 0.1.0-next.3
20
+
21
+ ### Patch Changes
22
+
23
+ - d16fe7b: The package READMEs say how to install from npm (the `next` dist-tag, the peers, provenance) for the first published release (#192). No code change.
24
+
25
+ ## 0.1.0-next.2
26
+
27
+ ### Minor Changes
28
+
29
+ - 14f844c: Add the owner's agent trail and agent notifications (E14.7). `GET /api/agent-activity` (`secrets:read`, session or PAT; an OAuth token is refused with the new `403 AGENT_ACTIVITY_FORBIDDEN`) lists the caller's own agent events (`lookup`, `fill`, `totp`, `create`, `rotate` and the `agent_access` toggle), filterable by action, secret, app and date, paginated, never carrying a value. New `agentActivity*` schemas and `AGENT_ACTIVITY_PATH` in `@marinoscar/vault-contract/agent`. New notification events `vault.agent_credential_changed` (email + bell), `vault.agent_new_app` (email + bell) and `vault.agent_credential_used` (bell only, counted), raised by `AgentNotifier` after the audit row is written; `VaultNotifyPort` now includes `notifyCounted` and `RecordingNotify` records it.
30
+ - a9726a7: Add the agent credential API on the `agent` OAuth resource (`/api/agent/v1`, accepts `oat_` and `pat_` credentials): `GET /credentials?origin=`, `POST /credentials/:id/fill` (one field per call, exact origin only), `POST /credentials/:id/totp`, `POST /credentials` (with a CSPRNG-generated password returned once) and `POST /credentials/:id/password` (rotation as a new version). Kill switch `agentAccess.enabled` (default off) and per-minute limits in the `agentAccess` system settings namespace, an in-memory `AgentRateLimiter`, audit rows `agent.credential.lookup|fill|totp|create|rotate`, and `Cache-Control: no-store` on every response. New `@marinoscar/vault-contract/agent` subpath (experimental provider contract: request and response schemas, `AGENT_ERROR_CODES`, `AGENT_AUDIT_ACTIONS`, settings schema) and error codes `ORIGIN_MISMATCH`, `AGENT_ACCESS_DISABLED`, `AGENT_CREDENTIAL_REQUIRED` (403) and `RATE_LIMITED` (429).
31
+ - 60b975f: Add per-secret agent access: `PATCH /api/secrets/:id/agent-access` (`secrets:write`, refused for an OAuth credential, only a `Credential` may be `fill`, audited `secrets.agent_access.update`), the `agentAccess` list filter, `agentAccess` and `agentAccessChangedAt` on secret responses, the `AGENT_ACCESS_UNSUPPORTED_TYPE` (422) error code, and `SecretsService.findAgentAccessibleSecret` / `assertAgentAccessible` for the agent API.
32
+ - 9a5a86d: vault-contract: `Credential` gains the optional `additional_urls` field, and `normalizeOrigin`, `originsFromCredential`, `matchOrigin` and `registrableDomainOfOrigin` (exact or same-site matching via the Public Suffix List). vault-api: `secrets.origins` is recomputed on every new Credential version, `SecretsService.findCredentialsByOrigin(userId, origin)` and the server-only `vault.secrets.origins.backfill` job.
33
+ - d85c2f9: Add TOTP on Credential secrets: an optional sensitive `totp` field (Authenticator key) normalized on save to a canonical `otpauth://totp` URI (`parseTotpSecret`, `toCanonicalOtpauthUri`, `normalizeTotpSecret` in `@marinoscar/vault-contract/secrets`; an invalid value is a 400 field error), `generateTotp` (RFC 6238) and `POST /api/secrets/:id/totp` (`secrets:read`, `Cache-Control: no-store`, audited `secret.totp.read`, the seed is never returned), plus `SecretsService.generateTotpForSecret` and `hasTotp` for the agent API.
34
+
35
+ ## 0.1.0-next.1
36
+
37
+ ## 0.1.0-next.0
38
+
39
+ - Initial version (E12.1, issue 102). Moved out of `apps/api` and `apps/web` without changing behaviour or a field; see the README.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Oscar Marin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,84 @@
1
- # Temporary Holding Version
1
+ # @marinoscar/vault-contract
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The wire contract of the Vault domain: the Zod schemas of the requests and queries, the response shapes of the backups API, the domain error codes and the system secret-type definitions that the API, the web app and any other host share. Dual CommonJS and ESM, `sideEffects: false`, free of any framework or Node built-in, so it loads in the browser too; the one exception is the test kit `./agent-testing`, which is Node only.
4
+
5
+ ## Purpose and scope
6
+
7
+ The package holds the shape of the domain's HTTP traffic and nothing that behaves (no service, no controller, no component and no database access), plus one test kit for agent runtimes (`./agent-testing`). The API wraps the schemas in `createZodDto` classes, the web types its requests with them, and a second host gets the same contract by installing one package. It does not hold the platform's shapes (they come from `@marinoscar/platform-contract`), the scheduling math of `computeNextRunAt`, or anything server-only.
8
+
9
+ Status: experimental, except the agent contract (`./agent` and `./agent-testing`), which is **beta** since issue 196 (see "Stability of the agent contract" below). Introduced in E12.1 (issue 102) by moving the schemas out of the API's `dto/` files with no change to a field name, a limit or a message; the API's DTO files re-export them under their old names.
10
+
11
+ Entry points (every schema and constant is in a slice; the root exports only `VAULT_CONTRACT_PACKAGE`):
12
+
13
+ - `@marinoscar/vault-contract/secrets`: create, update, list, renew, attachment and card-summary bodies and queries, `attachmentRoleSchema`, the attachment response.
14
+ - `@marinoscar/vault-contract/secret-types`: field definitions, create/update/query bodies, `CARD_NETWORKS`, `CARD_KINDS`, `SYSTEM_SECRET_TYPES` (the built-in types, append-only).
15
+ - `@marinoscar/vault-contract/backups`: content-selection rules (`BACKUP_CONTENT_*`, `contentSelectionIssues`, `resolveContentSelection`), the schedule vocabulary and validators, the user export, system export and schedule schemas, the run list query, and the backups API response types.
16
+ - `@marinoscar/vault-contract/media`: folder and file bodies and queries.
17
+ - `@marinoscar/vault-contract/agent`: the provider contract of the agent credential API (`/api/agent/v1`, **beta**; contract version `AGENT_CONTRACT_VERSION`, 1.2): lookup, fill, totp, create and rotate request and response schemas, `agentPurposeSchema`, the generated-password options, `AGENT_ERROR_CODES` (`ORIGIN_MISMATCH`, `AGENT_ACCESS_DISABLED`, `AGENT_CREDENTIAL_REQUIRED`, `RATE_LIMITED`), `AGENT_AUDIT_ACTIONS`, `AGENT_SCOPES` and the `agentAccess` settings schema and defaults. Since ADR-0003 also cards and identity: `agentCardFillRequestSchema`, `agentCardSummarySchema`, `agentCardGrantRequestCreateSchema`, `agentIdentityFillRequestSchema`, `agentIdentitySummarySchema`, `AGENT_IDENTITY_FIELDS`, `AGENT_CARD_FIELD_MAP`, the amount and currency schemas and helpers (`amountToMinor`, `minorToAmount`, `formatMinorAmount`), the owner's `createCardGrantSchema`, `cardGrantSchema`, `cardGrantRequestSchema` and `CARD_GRANT_AUDIT_ACTIONS`, the `cards` and `identity` settings blocks (both off) with `resolveAgentAccessSettings`, the scopes `vault:cards_*` and `vault:identity_*` and the card error codes (`CARD_ACCESS_DISABLED`, `IDENTITY_ACCESS_DISABLED`, `SECURITY_CODE_NOT_GRANTED`, `CARD_AMOUNT_EXCEEDED`, `CARD_CURRENCY_MISMATCH`, `CARD_PERIOD_LIMIT_REACHED`, `CARD_DAILY_CAP_REACHED`, `CARD_GRANT_EXPIRED`, `CARD_GRANT_EXISTS`, `CARD_GRANT_REQUEST_NOT_PENDING`, `OWNER_SESSION_REQUIRED`). `@marinoscar/vault-contract/secret-types` adds the `Identity` system type and the Card's `billing_postal_code`. Since contract 1.2: `AGENT_CONTRACT_VERSION`, `AGENT_CONTRACT_FEATURES`, `agentContractInfoSchema`, `agentContractInfoFor` and the optional `contract` block of `agentWhoamiResponseSchema`.
18
+ - `@marinoscar/vault-contract/agent-testing`: the conformance kit for an agent runtime's tests (Node only, beta): `createFakeVault` (an in-memory `/api/agent/v1` built from the schemas above, seeded with invented data, refusing to start with `NODE_ENV=production`; not a secrets store), the canary helpers `seedCanaries`, `createCanary`, `findCanaries` and `assertNoCanary`, the scenario list `AGENT_CONFORMANCE_SCENARIOS` with the runner `runAgentConformance` / `assertAgentConformance` (plain functions, no test framework), `createConformanceSeed` and `createReferenceSignIn`. What passing proves and does not prove: [the guide, section 10](../../docs/agent-credential-api.md#10-conformance-kit).
19
+ - `@marinoscar/vault-contract/errors`: `VAULT_ERROR_CODES` (code, status, description), `AI_ERROR_CODES`, `isVaultErrorCode`.
20
+ - `@marinoscar/vault-contract/common`: `typeErrors`, the Zod 4 replacement for `required_error` / `invalid_type_error`.
21
+
22
+ ## Install and peer dependencies
23
+
24
+ ```bash
25
+ npm install @marinoscar/vault-contract@next zod@^4.4.3
26
+ ```
27
+
28
+ Published to npm under the `next` dist-tag until 1.0, with a provenance attestation; the install, the dist-tag policy and the current publication status are in [docs/PACKAGES.md](../../docs/PACKAGES.md#installing-from-npm). The package works from CommonJS (`require`) and ESM (`import`), and its types resolve under `moduleResolution` `node16`, `nodenext` and `bundler`.
29
+
30
+ The package never bundles Zod, because a second copy breaks `instanceof ZodError` checks:
31
+
32
+ | Package | Range | Needed by |
33
+ |---|---|---|
34
+ | `zod` | `^4.4.3` | every slice (required) |
35
+
36
+ ## Quick start
37
+
38
+ ```ts
39
+ import { createSecretSchema } from '@marinoscar/vault-contract/secrets';
40
+ import { VAULT_ERROR_CODES } from '@marinoscar/vault-contract/errors';
41
+ // CommonJS: const { createSecretSchema } = require('@marinoscar/vault-contract/secrets');
42
+
43
+ const body = createSecretSchema.parse(input);
44
+ ```
45
+
46
+ In the API, import the DTO class from the module's `dto/` file as before; the schema behind it is the one above. The error codes are data: `app-registrations/error-codes.ts` registers them with the platform. Keep the `.js` extension on every relative import inside the package; the ESM build fails at run time without it.
47
+
48
+ ## Configuration
49
+
50
+ None. The package reads no environment variable and takes no option.
51
+
52
+ ## Extension-point catalog
53
+
54
+ None. A new code, schema or constant is added here, in the slice that owns it, with a test; a host never extends the package at run time.
55
+
56
+ ## Build and test
57
+
58
+ ```bash
59
+ npm run build -w @marinoscar/vault-contract # dist/cjs and dist/esm, with a package.json stub in each
60
+ npm run test:run -w @marinoscar/vault-contract # Vitest
61
+ npm run typecheck -w @marinoscar/vault-contract
62
+ ```
63
+
64
+ The apps import the built output, so build the packages after `npm ci` and before the app's typecheck or tests (`npm run build:packages` at the root).
65
+
66
+ ## Stability of the agent contract
67
+
68
+ `./agent` is tagged `@stability beta` (issue 196); it becomes `stable` at 1.0. The promise, in full in [the guide, section 9](../../docs/agent-credential-api.md#9-stability):
69
+
70
+ - **Does not change inside `/api/agent/v1`:** route paths, required request fields, the meaning of each code in `AGENT_ERROR_CODES`, the scope names in `AGENT_SCOPES`, and the rule that a response carries at most one secret field.
71
+ - **May change without a new version:** new optional request fields, new response fields and response enum values, new error codes and scopes for new routes, new `whoami` feature ids, stricter rate-limit defaults. A runtime ignores what it does not know and never branches on `message`.
72
+ - **Anything else is `/api/agent/v2`.** `v1` keeps working for two minor releases of the packages after the release that ships `v2`.
73
+
74
+ `test/agent-contract-snapshot.test.ts` holds it: a committed snapshot of every public schema of `./agent` (field names, requiredness, enums) and of `AGENT_SCOPES` and `AGENT_ERROR_CODES`; an additive difference passes, a breaking one fails until the path version, `AGENT_CONTRACT_VERSION`, an `ACCEPT_BREAKING` entry in [the changelog](../../docs/agent-credential-api.md#8-changes) and the snapshot all say so. Refresh the snapshot with `UPDATE_AGENT_CONTRACT_SNAPSHOT=1 npx vitest run test/agent-contract-snapshot.test.ts`.
75
+
76
+ ## Security notes
77
+
78
+ Schemas validate shape and size only. Every message is static text and never echoes a submitted value; the export and schedule schemas are written so a validation error can be logged without leaking a backup password. No schema or constant holds a secret. `./agent-testing` holds only invented data (`Person A`, `*.example.test`, the published test card number `4242424242424242`, random canaries), keeps it in memory, binds to `127.0.0.1` and refuses to run with `NODE_ENV=production`; its errors and reports name where a canary was found, never the value.
79
+
80
+ ## Links
81
+
82
+ - [The Vault packages](../../docs/PACKAGES.md)
83
+ - [ADR-0001: packages first](../../docs/decisions/0001-packages-first.md)
84
+ - [Agent credential API guide (stability, changes, conformance kit)](../../docs/agent-credential-api.md)
@@ -0,0 +1,456 @@
1
+ import { z } from 'zod';
2
+ /**
3
+ * Agent release of payment cards and identity fields (ADR-0003 of the Vault repository):
4
+ * the agent routes under `/api/agent/v1/cards` and `/api/agent/v1/identity`, and the owner's
5
+ * merchant grants and grant requests under `/api/secrets/:id/card-grants` and
6
+ * `/api/secrets/:id/card-grant-requests`.
7
+ *
8
+ * Request and response shapes only. Behaviour (the grant rules, the kill switches, rate limits,
9
+ * audit) is the API's. Never a value in a schema here except the one `{ value }` a fill returns.
10
+ *
11
+ * @packageDocumentation
12
+ */
13
+ /** The largest amount a grant or a call may carry: 10,000,000.00. @stability beta */
14
+ export declare const AGENT_MAX_AMOUNT = 10000000;
15
+ /**
16
+ * An amount in major units with at most two decimal places, greater than zero and at most
17
+ * {@link AGENT_MAX_AMOUNT}. The API stores it in hundredths.
18
+ *
19
+ * @stability beta
20
+ */
21
+ export declare const agentAmountSchema: z.ZodNumber;
22
+ /** An ISO 4217 currency code, upper case (`USD`, `EUR`). Lower case is accepted and upper-cased. @stability beta */
23
+ export declare const agentCurrencySchema: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
24
+ /** An amount in hundredths (the stored form). @stability beta */
25
+ export declare function amountToMinor(amount: number): number;
26
+ /** Hundredths back to a major-unit number. @stability beta */
27
+ export declare function minorToAmount(minor: number): number;
28
+ /** Hundredths as a two-decimal string (`4250` is `"42.50"`), for the activity trail. @stability beta */
29
+ export declare function formatMinorAmount(minor: number): string;
30
+ /**
31
+ * The one card field a fill returns. Stored field of the `Card` type each maps to:
32
+ * `number` (number), `expMonth` (exp_month), `expYear` (exp_year), `holderName` (cardholder_name),
33
+ * `securityCode` (cvv), `postalCode` (billing_postal_code).
34
+ *
35
+ * @stability beta
36
+ */
37
+ export declare const agentCardFillFieldSchema: z.ZodEnum<{
38
+ number: "number";
39
+ expMonth: "expMonth";
40
+ expYear: "expYear";
41
+ holderName: "holderName";
42
+ securityCode: "securityCode";
43
+ postalCode: "postalCode";
44
+ }>;
45
+ /** @stability beta */
46
+ export type AgentCardFillField = z.infer<typeof agentCardFillFieldSchema>;
47
+ /** The stored `Card` type field behind each {@link AgentCardFillField}. @stability beta */
48
+ export declare const AGENT_CARD_FIELD_MAP: Readonly<Record<AgentCardFillField, string>>;
49
+ /** Query of `GET /api/agent/v1/cards`: the top-level page's origin (the merchant). @stability beta */
50
+ export declare const agentCardsLookupQuerySchema: z.ZodObject<{
51
+ origin: z.ZodString;
52
+ }, z.core.$strip>;
53
+ /** @stability beta */
54
+ export type AgentCardsLookupQuery = z.infer<typeof agentCardsLookupQuerySchema>;
55
+ /** The grant a card is listed under. @stability beta */
56
+ export declare const agentCardGrantSummarySchema: z.ZodObject<{
57
+ maxAmount: z.ZodNumber;
58
+ currency: z.ZodString;
59
+ includesSecurityCode: z.ZodBoolean;
60
+ expiresAt: z.ZodNullable<z.ZodString>;
61
+ }, z.core.$strip>;
62
+ /**
63
+ * One opened card with a live grant for the asked merchant. Never a number or a code:
64
+ * `last4` is the only part of the number, and `brand` is the stored network.
65
+ *
66
+ * @stability beta
67
+ */
68
+ export declare const agentCardSummarySchema: z.ZodObject<{
69
+ id: z.ZodString;
70
+ name: z.ZodString;
71
+ brand: z.ZodNullable<z.ZodString>;
72
+ last4: z.ZodNullable<z.ZodString>;
73
+ expMonth: z.ZodNullable<z.ZodString>;
74
+ expYear: z.ZodNullable<z.ZodString>;
75
+ grant: z.ZodObject<{
76
+ maxAmount: z.ZodNumber;
77
+ currency: z.ZodString;
78
+ includesSecurityCode: z.ZodBoolean;
79
+ expiresAt: z.ZodNullable<z.ZodString>;
80
+ }, z.core.$strip>;
81
+ }, z.core.$strip>;
82
+ /** @stability beta */
83
+ export type AgentCardSummary = z.infer<typeof agentCardSummarySchema>;
84
+ /** Response of `GET /api/agent/v1/cards`. @stability beta */
85
+ export declare const agentCardsLookupResponseSchema: z.ZodObject<{
86
+ data: z.ZodArray<z.ZodObject<{
87
+ id: z.ZodString;
88
+ name: z.ZodString;
89
+ brand: z.ZodNullable<z.ZodString>;
90
+ last4: z.ZodNullable<z.ZodString>;
91
+ expMonth: z.ZodNullable<z.ZodString>;
92
+ expYear: z.ZodNullable<z.ZodString>;
93
+ grant: z.ZodObject<{
94
+ maxAmount: z.ZodNumber;
95
+ currency: z.ZodString;
96
+ includesSecurityCode: z.ZodBoolean;
97
+ expiresAt: z.ZodNullable<z.ZodString>;
98
+ }, z.core.$strip>;
99
+ }, z.core.$strip>>;
100
+ }, z.core.$strip>;
101
+ /**
102
+ * Body of `POST /api/agent/v1/cards/:id/fill`: ONE field, the merchant's top-level origin, the
103
+ * embedded payment frame's origin when the field is typed into one, and the purchase's amount and
104
+ * currency (checked against the grant and recorded).
105
+ *
106
+ * @stability beta
107
+ */
108
+ export declare const agentCardFillRequestSchema: z.ZodObject<{
109
+ field: z.ZodEnum<{
110
+ number: "number";
111
+ expMonth: "expMonth";
112
+ expYear: "expYear";
113
+ holderName: "holderName";
114
+ securityCode: "securityCode";
115
+ postalCode: "postalCode";
116
+ }>;
117
+ origin: z.ZodString;
118
+ frameOrigin: z.ZodOptional<z.ZodString>;
119
+ amount: z.ZodNumber;
120
+ currency: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
121
+ purpose: z.ZodLiteral<"purchase">;
122
+ }, z.core.$strip>;
123
+ /** @stability beta */
124
+ export type AgentCardFillRequest = z.infer<typeof agentCardFillRequestSchema>;
125
+ /** 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 */
126
+ export declare const agentValueResponseSchema: z.ZodObject<{
127
+ data: z.ZodObject<{
128
+ value: z.ZodString;
129
+ }, z.core.$strip>;
130
+ }, z.core.$strip>;
131
+ /** Body of `POST /api/agent/v1/cards/:id/grant-requests`. @stability beta */
132
+ export declare const agentCardGrantRequestCreateSchema: z.ZodObject<{
133
+ origin: z.ZodString;
134
+ amount: z.ZodNumber;
135
+ currency: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
136
+ reason: z.ZodString;
137
+ }, z.core.$strip>;
138
+ /** @stability beta */
139
+ export type AgentCardGrantRequestCreate = z.infer<typeof agentCardGrantRequestCreateSchema>;
140
+ /** The status of a grant request. @stability beta */
141
+ export declare const cardGrantRequestStatusSchema: z.ZodEnum<{
142
+ pending: "pending";
143
+ approved: "approved";
144
+ declined: "declined";
145
+ }>;
146
+ /** @stability beta */
147
+ export type CardGrantRequestStatus = z.infer<typeof cardGrantRequestStatusSchema>;
148
+ /** Response of the grant-request route: an id and a status, never card data. @stability beta */
149
+ export declare const agentCardGrantRequestResponseSchema: z.ZodObject<{
150
+ data: z.ZodObject<{
151
+ id: z.ZodString;
152
+ status: z.ZodEnum<{
153
+ pending: "pending";
154
+ approved: "approved";
155
+ declined: "declined";
156
+ }>;
157
+ }, z.core.$strip>;
158
+ }, z.core.$strip>;
159
+ /**
160
+ * The fields of the `Identity` system type an agent may ask for (every field but `notes`).
161
+ * `date_of_birth` and `id_number` are sensitive: released only to an origin on the item's
162
+ * allowed origins.
163
+ *
164
+ * @stability beta
165
+ */
166
+ export declare const AGENT_IDENTITY_FIELDS: readonly ["full_name", "date_of_birth", "id_type", "id_number", "id_issuing_country", "address_line1", "address_line2", "city", "region", "postal_code", "country", "phone", "email"];
167
+ /** @stability beta */
168
+ export declare const agentIdentityFieldSchema: z.ZodEnum<{
169
+ full_name: "full_name";
170
+ date_of_birth: "date_of_birth";
171
+ id_type: "id_type";
172
+ id_number: "id_number";
173
+ id_issuing_country: "id_issuing_country";
174
+ address_line1: "address_line1";
175
+ address_line2: "address_line2";
176
+ city: "city";
177
+ region: "region";
178
+ postal_code: "postal_code";
179
+ country: "country";
180
+ phone: "phone";
181
+ email: "email";
182
+ }>;
183
+ /** @stability beta */
184
+ export type AgentIdentityField = z.infer<typeof agentIdentityFieldSchema>;
185
+ /** Query of `GET /api/agent/v1/identity`: the origin of the form. @stability beta */
186
+ export declare const agentIdentityLookupQuerySchema: z.ZodObject<{
187
+ origin: z.ZodString;
188
+ }, z.core.$strip>;
189
+ /** One field of an identity item as the lookup lists it: a label, never a value. @stability beta */
190
+ export declare const agentIdentityFieldSummarySchema: z.ZodObject<{
191
+ field: z.ZodEnum<{
192
+ full_name: "full_name";
193
+ date_of_birth: "date_of_birth";
194
+ id_type: "id_type";
195
+ id_number: "id_number";
196
+ id_issuing_country: "id_issuing_country";
197
+ address_line1: "address_line1";
198
+ address_line2: "address_line2";
199
+ city: "city";
200
+ region: "region";
201
+ postal_code: "postal_code";
202
+ country: "country";
203
+ phone: "phone";
204
+ email: "email";
205
+ }>;
206
+ label: z.ZodString;
207
+ sensitive: z.ZodBoolean;
208
+ fillable: z.ZodBoolean;
209
+ }, z.core.$strip>;
210
+ /** One opened identity item. @stability beta */
211
+ export declare const agentIdentitySummarySchema: z.ZodObject<{
212
+ id: z.ZodString;
213
+ name: z.ZodString;
214
+ originAllowed: z.ZodBoolean;
215
+ fields: z.ZodArray<z.ZodObject<{
216
+ field: z.ZodEnum<{
217
+ full_name: "full_name";
218
+ date_of_birth: "date_of_birth";
219
+ id_type: "id_type";
220
+ id_number: "id_number";
221
+ id_issuing_country: "id_issuing_country";
222
+ address_line1: "address_line1";
223
+ address_line2: "address_line2";
224
+ city: "city";
225
+ region: "region";
226
+ postal_code: "postal_code";
227
+ country: "country";
228
+ phone: "phone";
229
+ email: "email";
230
+ }>;
231
+ label: z.ZodString;
232
+ sensitive: z.ZodBoolean;
233
+ fillable: z.ZodBoolean;
234
+ }, z.core.$strip>>;
235
+ }, z.core.$strip>;
236
+ /** @stability beta */
237
+ export type AgentIdentitySummary = z.infer<typeof agentIdentitySummarySchema>;
238
+ /** Response of `GET /api/agent/v1/identity`. @stability beta */
239
+ export declare const agentIdentityLookupResponseSchema: z.ZodObject<{
240
+ data: z.ZodArray<z.ZodObject<{
241
+ id: z.ZodString;
242
+ name: z.ZodString;
243
+ originAllowed: z.ZodBoolean;
244
+ fields: z.ZodArray<z.ZodObject<{
245
+ field: z.ZodEnum<{
246
+ full_name: "full_name";
247
+ date_of_birth: "date_of_birth";
248
+ id_type: "id_type";
249
+ id_number: "id_number";
250
+ id_issuing_country: "id_issuing_country";
251
+ address_line1: "address_line1";
252
+ address_line2: "address_line2";
253
+ city: "city";
254
+ region: "region";
255
+ postal_code: "postal_code";
256
+ country: "country";
257
+ phone: "phone";
258
+ email: "email";
259
+ }>;
260
+ label: z.ZodString;
261
+ sensitive: z.ZodBoolean;
262
+ fillable: z.ZodBoolean;
263
+ }, z.core.$strip>>;
264
+ }, z.core.$strip>>;
265
+ }, z.core.$strip>;
266
+ /** Body of `POST /api/agent/v1/identity/:id/fill`. @stability beta */
267
+ export declare const agentIdentityFillRequestSchema: z.ZodObject<{
268
+ field: z.ZodEnum<{
269
+ full_name: "full_name";
270
+ date_of_birth: "date_of_birth";
271
+ id_type: "id_type";
272
+ id_number: "id_number";
273
+ id_issuing_country: "id_issuing_country";
274
+ address_line1: "address_line1";
275
+ address_line2: "address_line2";
276
+ city: "city";
277
+ region: "region";
278
+ postal_code: "postal_code";
279
+ country: "country";
280
+ phone: "phone";
281
+ email: "email";
282
+ }>;
283
+ origin: z.ZodString;
284
+ purpose: z.ZodLiteral<"form">;
285
+ }, z.core.$strip>;
286
+ /** @stability beta */
287
+ export type AgentIdentityFillRequest = z.infer<typeof agentIdentityFillRequestSchema>;
288
+ /** A grant's optional period limit: at most `maxReleases` and/or `maxAmount` per UTC day or month. @stability beta */
289
+ export declare const cardGrantPeriodLimitSchema: z.ZodObject<{
290
+ period: z.ZodEnum<{
291
+ day: "day";
292
+ month: "month";
293
+ }>;
294
+ maxReleases: z.ZodOptional<z.ZodNumber>;
295
+ maxAmount: z.ZodOptional<z.ZodNumber>;
296
+ }, z.core.$strip>;
297
+ /** @stability beta */
298
+ export type CardGrantPeriodLimit = z.infer<typeof cardGrantPeriodLimitSchema>;
299
+ /** Most payment frame origins one grant may list. @stability beta */
300
+ export declare const MAX_CARD_GRANT_FRAME_ORIGINS = 10;
301
+ /** Body of `POST /api/secrets/:id/card-grants` (owner, browser session). @stability beta */
302
+ export declare const createCardGrantSchema: z.ZodObject<{
303
+ merchantOrigin: z.ZodString;
304
+ frameOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
305
+ maxAmount: z.ZodNumber;
306
+ currency: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
307
+ periodLimit: z.ZodOptional<z.ZodNullable<z.ZodObject<{
308
+ period: z.ZodEnum<{
309
+ day: "day";
310
+ month: "month";
311
+ }>;
312
+ maxReleases: z.ZodOptional<z.ZodNumber>;
313
+ maxAmount: z.ZodOptional<z.ZodNumber>;
314
+ }, z.core.$strip>>>;
315
+ expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
316
+ includeSecurityCode: z.ZodDefault<z.ZodBoolean>;
317
+ }, z.core.$strip>;
318
+ /** @stability beta */
319
+ export type CreateCardGrant = z.input<typeof createCardGrantSchema>;
320
+ /** A grant's state: live, past its expiry, or revoked by the owner. @stability beta */
321
+ export declare const cardGrantStatusSchema: z.ZodEnum<{
322
+ active: "active";
323
+ expired: "expired";
324
+ revoked: "revoked";
325
+ }>;
326
+ /** @stability beta */
327
+ export type CardGrantStatus = z.infer<typeof cardGrantStatusSchema>;
328
+ /** One merchant grant as the owner sees it, with its use. @stability beta */
329
+ export declare const cardGrantSchema: z.ZodObject<{
330
+ id: z.ZodString;
331
+ secretId: z.ZodString;
332
+ merchantOrigin: z.ZodString;
333
+ merchantSite: z.ZodString;
334
+ frameOrigins: z.ZodArray<z.ZodString>;
335
+ maxAmount: z.ZodNumber;
336
+ currency: z.ZodString;
337
+ periodLimit: z.ZodNullable<z.ZodObject<{
338
+ period: z.ZodEnum<{
339
+ day: "day";
340
+ month: "month";
341
+ }>;
342
+ maxReleases: z.ZodNullable<z.ZodNumber>;
343
+ maxAmount: z.ZodNullable<z.ZodNumber>;
344
+ }, z.core.$strip>>;
345
+ expiresAt: z.ZodNullable<z.ZodString>;
346
+ includeSecurityCode: z.ZodBoolean;
347
+ status: z.ZodEnum<{
348
+ active: "active";
349
+ expired: "expired";
350
+ revoked: "revoked";
351
+ }>;
352
+ createdAt: z.ZodString;
353
+ revokedAt: z.ZodNullable<z.ZodString>;
354
+ usage: z.ZodObject<{
355
+ periodReleases: z.ZodNumber;
356
+ periodAmount: z.ZodNumber;
357
+ totalReleases: z.ZodNumber;
358
+ lastReleasedAt: z.ZodNullable<z.ZodString>;
359
+ }, z.core.$strip>;
360
+ }, z.core.$strip>;
361
+ /** @stability beta */
362
+ export type CardGrant = z.infer<typeof cardGrantSchema>;
363
+ /** Response of `GET /api/secrets/:id/card-grants`: active first, then expired and revoked. @stability beta */
364
+ export declare const cardGrantListResponseSchema: z.ZodObject<{
365
+ data: z.ZodArray<z.ZodObject<{
366
+ id: z.ZodString;
367
+ secretId: z.ZodString;
368
+ merchantOrigin: z.ZodString;
369
+ merchantSite: z.ZodString;
370
+ frameOrigins: z.ZodArray<z.ZodString>;
371
+ maxAmount: z.ZodNumber;
372
+ currency: z.ZodString;
373
+ periodLimit: z.ZodNullable<z.ZodObject<{
374
+ period: z.ZodEnum<{
375
+ day: "day";
376
+ month: "month";
377
+ }>;
378
+ maxReleases: z.ZodNullable<z.ZodNumber>;
379
+ maxAmount: z.ZodNullable<z.ZodNumber>;
380
+ }, z.core.$strip>>;
381
+ expiresAt: z.ZodNullable<z.ZodString>;
382
+ includeSecurityCode: z.ZodBoolean;
383
+ status: z.ZodEnum<{
384
+ active: "active";
385
+ expired: "expired";
386
+ revoked: "revoked";
387
+ }>;
388
+ createdAt: z.ZodString;
389
+ revokedAt: z.ZodNullable<z.ZodString>;
390
+ usage: z.ZodObject<{
391
+ periodReleases: z.ZodNumber;
392
+ periodAmount: z.ZodNumber;
393
+ totalReleases: z.ZodNumber;
394
+ lastReleasedAt: z.ZodNullable<z.ZodString>;
395
+ }, z.core.$strip>;
396
+ }, z.core.$strip>>;
397
+ }, z.core.$strip>;
398
+ /** Query of `GET /api/secrets/:id/card-grant-requests`. @stability beta */
399
+ export declare const cardGrantRequestListQuerySchema: z.ZodObject<{
400
+ status: z.ZodOptional<z.ZodEnum<{
401
+ pending: "pending";
402
+ approved: "approved";
403
+ declined: "declined";
404
+ }>>;
405
+ }, z.core.$strip>;
406
+ /** One grant request as the owner sees it. @stability beta */
407
+ export declare const cardGrantRequestSchema: z.ZodObject<{
408
+ id: z.ZodString;
409
+ secretId: z.ZodString;
410
+ origin: z.ZodString;
411
+ merchantSite: z.ZodString;
412
+ amount: z.ZodNumber;
413
+ currency: z.ZodString;
414
+ reason: z.ZodString;
415
+ status: z.ZodEnum<{
416
+ pending: "pending";
417
+ approved: "approved";
418
+ declined: "declined";
419
+ }>;
420
+ clientName: z.ZodNullable<z.ZodString>;
421
+ createdAt: z.ZodString;
422
+ decidedAt: z.ZodNullable<z.ZodString>;
423
+ grantId: z.ZodNullable<z.ZodString>;
424
+ }, z.core.$strip>;
425
+ /** @stability beta */
426
+ export type CardGrantRequest = z.infer<typeof cardGrantRequestSchema>;
427
+ /** Response of the grant-request list, newest first. @stability beta */
428
+ export declare const cardGrantRequestListResponseSchema: z.ZodObject<{
429
+ data: z.ZodArray<z.ZodObject<{
430
+ id: z.ZodString;
431
+ secretId: z.ZodString;
432
+ origin: z.ZodString;
433
+ merchantSite: z.ZodString;
434
+ amount: z.ZodNumber;
435
+ currency: z.ZodString;
436
+ reason: z.ZodString;
437
+ status: z.ZodEnum<{
438
+ pending: "pending";
439
+ approved: "approved";
440
+ declined: "declined";
441
+ }>;
442
+ clientName: z.ZodNullable<z.ZodString>;
443
+ createdAt: z.ZodString;
444
+ decidedAt: z.ZodNullable<z.ZodString>;
445
+ grantId: z.ZodNullable<z.ZodString>;
446
+ }, z.core.$strip>>;
447
+ }, z.core.$strip>;
448
+ /** The owner's audit actions on grants (`audit_events.action`). @stability beta */
449
+ export declare const CARD_GRANT_AUDIT_ACTIONS: {
450
+ readonly CREATE: "secret.card_grant.create";
451
+ readonly REVOKE: "secret.card_grant.revoke";
452
+ readonly APPROVE: "secret.card_grant_request.approve";
453
+ readonly DECLINE: "secret.card_grant_request.decline";
454
+ };
455
+ /** @stability beta */
456
+ export type CardGrantAuditAction = (typeof CARD_GRANT_AUDIT_ACTIONS)[keyof typeof CARD_GRANT_AUDIT_ACTIONS];