@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.
- package/CHANGELOG.md +16 -0
- package/README.md +17 -5
- package/dist/cjs/agent/cards-identity.d.ts +456 -0
- package/dist/cjs/agent/cards-identity.js +272 -0
- package/dist/cjs/agent/contract-version.d.ts +58 -0
- package/dist/cjs/agent/contract-version.js +58 -0
- package/dist/cjs/agent/index.d.ts +196 -54
- package/dist/cjs/agent/index.js +176 -37
- package/dist/cjs/agent-testing/canary.d.ts +57 -0
- package/dist/cjs/agent-testing/canary.js +165 -0
- package/dist/cjs/agent-testing/fake-vault.d.ts +111 -0
- package/dist/cjs/agent-testing/fake-vault.js +707 -0
- package/dist/cjs/agent-testing/guard.d.ts +16 -0
- package/dist/cjs/agent-testing/guard.js +28 -0
- package/dist/cjs/agent-testing/index.d.ts +28 -0
- package/dist/cjs/agent-testing/index.js +43 -0
- package/dist/cjs/agent-testing/recorder.d.ts +70 -0
- package/dist/cjs/agent-testing/recorder.js +127 -0
- package/dist/cjs/agent-testing/reference-runtime.d.ts +8 -0
- package/dist/cjs/agent-testing/reference-runtime.js +112 -0
- package/dist/cjs/agent-testing/scenarios.d.ts +128 -0
- package/dist/cjs/agent-testing/scenarios.js +566 -0
- package/dist/cjs/agent-testing/seed.d.ts +84 -0
- package/dist/cjs/agent-testing/seed.js +89 -0
- package/dist/cjs/agent-testing/totp.d.ts +10 -0
- package/dist/cjs/agent-testing/totp.js +45 -0
- package/dist/cjs/errors/index.js +13 -1
- package/dist/cjs/media/index.d.ts +2 -2
- package/dist/cjs/secret-types/index.d.ts +4 -0
- package/dist/cjs/secret-types/index.js +29 -1
- package/dist/cjs/secrets/index.d.ts +13 -3
- package/dist/cjs/secrets/index.js +14 -3
- package/dist/esm/agent/cards-identity.d.ts +456 -0
- package/dist/esm/agent/cards-identity.js +266 -0
- package/dist/esm/agent/contract-version.d.ts +58 -0
- package/dist/esm/agent/contract-version.js +54 -0
- package/dist/esm/agent/index.d.ts +196 -54
- package/dist/esm/agent/index.js +160 -36
- package/dist/esm/agent-testing/canary.d.ts +57 -0
- package/dist/esm/agent-testing/canary.js +157 -0
- package/dist/esm/agent-testing/fake-vault.d.ts +111 -0
- package/dist/esm/agent-testing/fake-vault.js +704 -0
- package/dist/esm/agent-testing/guard.d.ts +16 -0
- package/dist/esm/agent-testing/guard.js +23 -0
- package/dist/esm/agent-testing/index.d.ts +28 -0
- package/dist/esm/agent-testing/index.js +27 -0
- package/dist/esm/agent-testing/recorder.d.ts +70 -0
- package/dist/esm/agent-testing/recorder.js +122 -0
- package/dist/esm/agent-testing/reference-runtime.d.ts +8 -0
- package/dist/esm/agent-testing/reference-runtime.js +109 -0
- package/dist/esm/agent-testing/scenarios.d.ts +128 -0
- package/dist/esm/agent-testing/scenarios.js +560 -0
- package/dist/esm/agent-testing/seed.d.ts +84 -0
- package/dist/esm/agent-testing/seed.js +85 -0
- package/dist/esm/agent-testing/totp.d.ts +10 -0
- package/dist/esm/agent-testing/totp.js +42 -0
- package/dist/esm/errors/index.js +13 -1
- package/dist/esm/media/index.d.ts +2 -2
- package/dist/esm/secret-types/index.d.ts +4 -0
- package/dist/esm/secret-types/index.js +28 -0
- package/dist/esm/secrets/index.d.ts +13 -3
- package/dist/esm/secrets/index.js +13 -2
- package/package.json +11 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,21 @@
|
|
|
1
1
|
# @marinoscar/vault-contract
|
|
2
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
|
+
|
|
3
19
|
## 0.1.0-next.3
|
|
4
20
|
|
|
5
21
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# @marinoscar/vault-contract
|
|
2
2
|
|
|
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.
|
|
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
4
|
|
|
5
5
|
## Purpose and scope
|
|
6
6
|
|
|
7
|
-
The package holds the shape of the domain's HTTP traffic and nothing that behaves
|
|
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
8
|
|
|
9
|
-
Status: experimental. Introduced in E12.1 (issue 102) by moving the schemas out of the API's `dto/` files with no change to a field name, a limit or a message; the API's DTO files re-export them under their old names.
|
|
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
10
|
|
|
11
11
|
Entry points (every schema and constant is in a slice; the root exports only `VAULT_CONTRACT_PACKAGE`):
|
|
12
12
|
|
|
@@ -14,7 +14,8 @@ Entry points (every schema and constant is in a slice; the root exports only `VA
|
|
|
14
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
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
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`,
|
|
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).
|
|
18
19
|
- `@marinoscar/vault-contract/errors`: `VAULT_ERROR_CODES` (code, status, description), `AI_ERROR_CODES`, `isVaultErrorCode`.
|
|
19
20
|
- `@marinoscar/vault-contract/common`: `typeErrors`, the Zod 4 replacement for `required_error` / `invalid_type_error`.
|
|
20
21
|
|
|
@@ -62,11 +63,22 @@ npm run typecheck -w @marinoscar/vault-contract
|
|
|
62
63
|
|
|
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).
|
|
64
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
|
+
|
|
65
76
|
## Security notes
|
|
66
77
|
|
|
67
|
-
Schemas validate shape and size only. Every message is static text and never echoes a submitted value; the export and schedule schemas are written so a validation error can be logged without leaking a backup password. No schema or constant holds a secret.
|
|
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.
|
|
68
79
|
|
|
69
80
|
## Links
|
|
70
81
|
|
|
71
82
|
- [The Vault packages](../../docs/PACKAGES.md)
|
|
72
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];
|