@agenticprimitives/agent-profile 1.0.0-alpha.4 → 1.0.0-alpha.40
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/README.md +91 -37
- package/dist/a2a/binding.d.ts +99 -0
- package/dist/a2a/binding.d.ts.map +1 -0
- package/dist/a2a/binding.js +142 -0
- package/dist/a2a/binding.js.map +1 -0
- package/dist/a2a/canonical.d.ts +31 -0
- package/dist/a2a/canonical.d.ts.map +1 -0
- package/dist/a2a/canonical.js +43 -0
- package/dist/a2a/canonical.js.map +1 -0
- package/dist/a2a/field-binding.d.ts +125 -0
- package/dist/a2a/field-binding.d.ts.map +1 -0
- package/dist/a2a/field-binding.js +242 -0
- package/dist/a2a/field-binding.js.map +1 -0
- package/dist/a2a/import.d.ts +39 -0
- package/dist/a2a/import.d.ts.map +1 -0
- package/dist/a2a/import.js +134 -0
- package/dist/a2a/import.js.map +1 -0
- package/dist/a2a/index.d.ts +13 -0
- package/dist/a2a/index.d.ts.map +1 -0
- package/dist/a2a/index.js +24 -0
- package/dist/a2a/index.js.map +1 -0
- package/dist/a2a/jws.d.ts +76 -0
- package/dist/a2a/jws.d.ts.map +1 -0
- package/dist/a2a/jws.js +186 -0
- package/dist/a2a/jws.js.map +1 -0
- package/dist/a2a/playbook-binding.d.ts +29 -0
- package/dist/a2a/playbook-binding.d.ts.map +1 -0
- package/dist/a2a/playbook-binding.js +65 -0
- package/dist/a2a/playbook-binding.js.map +1 -0
- package/dist/a2a/pointer.d.ts +13 -0
- package/dist/a2a/pointer.d.ts.map +1 -0
- package/dist/a2a/pointer.js +78 -0
- package/dist/a2a/pointer.js.map +1 -0
- package/dist/a2a/release.d.ts +77 -0
- package/dist/a2a/release.d.ts.map +1 -0
- package/dist/a2a/release.js +197 -0
- package/dist/a2a/release.js.map +1 -0
- package/dist/a2a/types.d.ts +327 -0
- package/dist/a2a/types.d.ts.map +1 -0
- package/dist/a2a/types.js +49 -0
- package/dist/a2a/types.js.map +1 -0
- package/dist/a2a/validation.d.ts +81 -0
- package/dist/a2a/validation.d.ts.map +1 -0
- package/dist/a2a/validation.js +506 -0
- package/dist/a2a/validation.js.map +1 -0
- package/dist/caip10.d.ts +4 -3
- package/dist/caip10.d.ts.map +1 -1
- package/dist/caip10.js +8 -5
- package/dist/caip10.js.map +1 -1
- package/dist/calls.d.ts +23 -0
- package/dist/calls.d.ts.map +1 -1
- package/dist/calls.js +31 -1
- package/dist/calls.js.map +1 -1
- package/dist/card.d.ts +70 -0
- package/dist/card.d.ts.map +1 -0
- package/dist/card.js +130 -0
- package/dist/card.js.map +1 -0
- package/dist/client-key-binding.d.ts +196 -0
- package/dist/client-key-binding.d.ts.map +1 -0
- package/dist/client-key-binding.js +282 -0
- package/dist/client-key-binding.js.map +1 -0
- package/dist/client.d.ts +6 -4
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +79 -8
- package/dist/client.js.map +1 -1
- package/dist/constants.d.ts +31 -1
- package/dist/constants.d.ts.map +1 -1
- package/dist/constants.js +38 -1
- package/dist/constants.js.map +1 -1
- package/dist/derived-type.d.ts +14 -0
- package/dist/derived-type.d.ts.map +1 -0
- package/dist/derived-type.js +56 -0
- package/dist/derived-type.js.map +1 -0
- package/dist/distribution.d.ts +32 -0
- package/dist/distribution.d.ts.map +1 -0
- package/dist/distribution.js +167 -0
- package/dist/distribution.js.map +1 -0
- package/dist/errors.d.ts +6 -0
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +11 -0
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +12 -8
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +19 -7
- package/dist/index.js.map +1 -1
- package/dist/profile.d.ts +4 -4
- package/dist/profile.d.ts.map +1 -1
- package/dist/profile.js +25 -3
- package/dist/profile.js.map +1 -1
- package/dist/types.d.ts +135 -9
- package/dist/types.d.ts.map +1 -1
- package/package.json +32 -12
- package/spec.md +5 -1
package/README.md
CHANGED
|
@@ -1,34 +1,43 @@
|
|
|
1
1
|
# @agenticprimitives/agent-profile
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
and endpoint-verification methods.
|
|
3
|
+
> Part of **[Agentic Primitives](https://agenticprimitives.dev)** — the open-source trust substrate for agentic applications: identity that can sign, authority checked at act time, evidence the owner carries. [Developer kit](https://github.com/agentictrustlabs/agentic-primitives) · [All packages](https://agenticprimitives.dev/developers)
|
|
5
4
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
5
|
+
**A profile describes the identity; it never becomes the identity.** Agent discovery is consolidating right now — on-chain registries, DNS/PKI agent naming, Hedera-style profiles, A2A cards, and MCP registries. Each standard wants to be the place an agent "lives." This package takes the other position: every agent already lives at one canonical ERC-4337 Smart Agent address, and a profile is an AP-native, typed, content-hashed manifest *about* that address ([ADR-0010](../../docs/architecture/decisions/0010-smart-agent-canonical-identifier.md)). Registry entries in any standard are external projections/facets that back-link to the same anchor — so one identity serves all of them, and no registry can quietly fork who the agent is.
|
|
6
|
+
|
|
7
|
+
Part of [agenticprimitives](../../README.md) — the trust substrate for the agent economy: one canonical Smart Agent identity with custody, delegation, naming, credentials, and audit evidence designed as one system.
|
|
8
|
+
|
|
9
|
+
Where [`agent-naming`](../agent-naming) maps names → addresses, this package maps addresses → typed profiles and optional endpoint-control proofs: the `CanonicalAgentProfileV1` schema, deterministic content hashing for on-chain anchoring, and CAIP-10 `nativeId` helpers for cross-registry back-links. Since spec 347 it also owns the **A2A 1.0 Agent Card model** (`./a2a`) — a different object, see below.
|
|
10
10
|
|
|
11
11
|
> **Layer:** Discover — a profile **facet** (not login — that is `connect-auth`; not canonical identity — that is `agent-account`).
|
|
12
|
-
> **Canonical key:** the Smart Agent address the
|
|
12
|
+
> **Canonical key:** the Smart Agent address the profile describes.
|
|
13
|
+
|
|
14
|
+
## Profile ≠ A2A card
|
|
13
15
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
+
| | `CanonicalAgentProfileV1` (root) | `A2AAgentCardV1` (`./a2a`) |
|
|
17
|
+
| --- | --- | --- |
|
|
18
|
+
| Answers | what is this agent, who operates it, what does it claim | what does THIS A2A server do and how do I talk to it |
|
|
19
|
+
| Shape | AP-native, discriminated on `type` | A2A 1.0 Agent Card (`supportedInterfaces`, `capabilities`, `skills`, `securitySchemes`, `signatures`) |
|
|
20
|
+
| Canonical bytes | sorted-key canonical JSON → keccak (`profileContentHash`, on-chain `metadata-hash`) | RFC 8785 JCS minus `signatures` → sha256 (`cardContentDigest`) |
|
|
21
|
+
| Proof | `SignedCanonicalProfileBundleV1` (ERC-1271 by the SA) | ES256 JWS (any A2A client verifies) **plus** `SmartAgentCardBindingV1` (EIP-712, ERC-1271 — AP verifiers) |
|
|
16
22
|
|
|
17
|
-
|
|
23
|
+
`AgentCard`, `SignedAgentCardBundleV1`, `hashAgentCard`, `buildSignedAgentCardBundle`, `verifySignedAgentCardBundle` still compile as **deprecated aliases** for one release ([spec 347 §0.3](../../specs/347-a2a-agent-card-and-projection-studio.md), [ADR-0062](../../docs/architecture/decisions/0062-agent-card-projection-publication-binding.md)).
|
|
18
24
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
- You
|
|
22
|
-
- You
|
|
25
|
+
## Use this when
|
|
26
|
+
|
|
27
|
+
- You author or validate a `CanonicalAgentProfileV1` (person, org, service, treasury, MCP server, multisig).
|
|
28
|
+
- You inherit, curate, validate, sign, release or import an **A2A Agent Card** (`./a2a`) with field-level provenance and a Smart Agent binding.
|
|
29
|
+
- You need a deterministic `profileContentHash` for the on-chain `metadata-hash` anchor — so a tampered profile is detectable by anyone holding the hash.
|
|
30
|
+
- You need CAIP-10 `nativeId` encode/decode (strict encode, permissive decode) as a portable back-link to the canonical SA ([ADR-0008](../../docs/architecture/decisions/0008-caip10-nativeid-record-predicate.md)).
|
|
31
|
+
- You need endpoint-verification methods (DNS TXT, signed URL, HTTP challenge, verifiable presentation) — Phase 2+.
|
|
23
32
|
- You build encoded calls to register or update on-chain profile anchors.
|
|
24
33
|
|
|
25
|
-
## Do
|
|
34
|
+
## Do not use this for
|
|
26
35
|
|
|
27
|
-
- `.agent` names or namehash
|
|
28
|
-
- Smart Agent deploy / UserOps
|
|
29
|
-
- Passkey / SIWE / JWT
|
|
30
|
-
- Trust-fabric edges
|
|
31
|
-
- UAID string generation
|
|
36
|
+
- `.agent` names or namehash — `agent-naming`.
|
|
37
|
+
- Smart Agent deploy / UserOps — `agent-account`.
|
|
38
|
+
- Passkey / SIWE / JWT — `connect-auth`.
|
|
39
|
+
- Trust-fabric edges — `agent-relationships`.
|
|
40
|
+
- UAID string generation — refused by design ([ADR-0008](../../docs/architecture/decisions/0008-caip10-nativeid-record-predicate.md)); we expose `nativeId` and consumers derive UAIDs locally.
|
|
32
41
|
|
|
33
42
|
## Install
|
|
34
43
|
|
|
@@ -38,19 +47,19 @@ Workspace-internal; not yet published.
|
|
|
38
47
|
pnpm add @agenticprimitives/agent-profile
|
|
39
48
|
```
|
|
40
49
|
|
|
41
|
-
## 60-
|
|
50
|
+
## 60-second quickstart
|
|
42
51
|
|
|
43
52
|
```ts
|
|
44
53
|
import {
|
|
45
54
|
canonicalProfileJson,
|
|
46
55
|
profileContentHash,
|
|
47
56
|
buildCaip10Address,
|
|
48
|
-
type
|
|
57
|
+
type CanonicalAgentProfileV1,
|
|
49
58
|
} from '@agenticprimitives/agent-profile';
|
|
50
59
|
|
|
51
60
|
const canonicalAddr = '0x0000000000000000000000000000000000000003' as const;
|
|
52
61
|
|
|
53
|
-
const profile:
|
|
62
|
+
const profile: CanonicalAgentProfileV1 = {
|
|
54
63
|
type: 'person',
|
|
55
64
|
displayName: 'Alice',
|
|
56
65
|
};
|
|
@@ -64,34 +73,75 @@ const nativeId = buildCaip10Address({
|
|
|
64
73
|
// Anchor hash + nativeId on chain via agent-naming records or profile resolver.
|
|
65
74
|
```
|
|
66
75
|
|
|
67
|
-
|
|
76
|
+
### A2A card in 60 seconds
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
import {
|
|
80
|
+
inheritCardBase, draftFromBase, applyOverride, createRelease, transition, attachSignature,
|
|
81
|
+
generateA2ACardSigningKey, signA2ACard, verifyA2ACardSignatures, importA2ACard,
|
|
82
|
+
} from '@agenticprimitives/agent-profile/a2a';
|
|
83
|
+
|
|
84
|
+
const now = new Date().toISOString();
|
|
85
|
+
const base = inheritCardBase({
|
|
86
|
+
profile, names: { primary: 'alice.svc.agent' },
|
|
87
|
+
surfaceCards: toCardProjectionSet(catalog), // surface-catalog — the only source of inherited skills
|
|
88
|
+
runtimeCapabilities: { streaming: false, pushNotifications: false },
|
|
89
|
+
deployment: { host: 'https://alice.agent.example', a2aUrl: 'https://alice.agent.example/api/a2a' },
|
|
90
|
+
agentVersion: '2.0.0', now,
|
|
91
|
+
});
|
|
92
|
+
let draft = draftFromBase(base, { cardResourceId: 'card_01', now });
|
|
93
|
+
draft = applyOverride(draft, '/description', 'Curated copy.', { now }); // recorded, reviewable
|
|
94
|
+
let release = createRelease(draft, { releaseNumber: 1, agentVersion: '2.0.0', now,
|
|
95
|
+
validation: { environment: 'production', catalogSkills: base.card.skills, runtimeCapabilities: {} } });
|
|
96
|
+
release = transition(release, 'approvalPending', { now });
|
|
97
|
+
release = transition(release, 'approved', { now, approval }); // ApprovalRefV1 names the exact digest
|
|
98
|
+
const key = await generateA2ACardSigningKey(); // ES256, kid = RFC 7638 thumbprint
|
|
99
|
+
const signed = await signA2ACard(release.unsignedCard, { privateKey: key.privateKey, kid: key.kid });
|
|
100
|
+
release = attachSignature(release, { signedCard: signed.card, signature: signed.signature });
|
|
101
|
+
// A non-AP client:
|
|
102
|
+
await verifyA2ACardSignatures(signed.card, { keys: (kid) => (kid === key.kid ? key.publicJwk : undefined) });
|
|
103
|
+
// Importing someone else's card: bytes kept, signatures verified BEFORE normalizing, unknown fields flagged.
|
|
104
|
+
const { imported, diagnostics } = await importA2ACard(bytes, { verifyKeys });
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## How it's different
|
|
68
108
|
|
|
69
|
-
|
|
109
|
+
The reference points are registry and agent-card ecosystems, but this package defines the AP-native primitive:
|
|
110
|
+
|
|
111
|
+
- **Anchor, not authority.** In registry-first designs, the registry entry *is* the agent, and each registry mints its own notion of identity. Here the `AgentCard` is AP-native typed JSON discriminated on `type`, and every external registry facet must back-link to the canonical Smart Agent via CAIP-10 `nativeId` ([spec 220 §4](../../specs/220-agent-identity-bootstrap.md)). One agent, many registries, zero identity forks.
|
|
112
|
+
- **Tamper evidence built in.** `profileContentHash` is deterministic canonical JSON — sorted keys, fixed numeric format — matching the on-chain `metadata-hash` predicate. Two semantically equal profiles hash identically; a mutated profile cannot pass against its anchor.
|
|
113
|
+
- **Endpoint claims are not endpoint proof.** A profile may *claim* an MCP or A2A URL; `VerificationMethod` is the explicit, caller-selected proof that the Smart Agent controls it. We never silently pick a verification method — you always know what "verified" meant.
|
|
114
|
+
- **CAIP-10 done strictly.** Encoders reject unknown namespaces (Phase 1: eip155, hedera, solana); decoders accept any grammar-valid CAIP-10 string for forward compatibility.
|
|
115
|
+
|
|
116
|
+
## Main concepts
|
|
117
|
+
|
|
118
|
+
- **CanonicalAgentProfileV1**: AP-native typed JSON discriminated by `type`, with type-specific sub-objects (`AiAgentProfile`, `McpServerProfile`, `MultisigProfile`, `ServiceProfile`).
|
|
119
|
+
- **A2A Agent Card** (`./a2a`): `A2AAgentCardV1` + draft / release / `FieldBindingV1` provenance (`inherit | override | computed | manual`), pure `validateA2ACard` (stable `DIAGNOSTIC_CODES`, incl. `CATALOG_DIVERGENCE` and `CAPABILITY_UNVERIFIED`), lifecycle `draft → validated → approvalPending → approved → signed → published → superseded | deprecated | revoked`.
|
|
120
|
+
- **Distribution** (`AgentDistributionV1`, spec 347 §8.5): how to OBTAIN AND RUN the agent's software — `acp?` (ACP conformance, the eligibility flag for a hosted ACP `registry.json`), `version?` (implementation semver), `npx` / `uvx` `{ package, args?, env? }`, `binary[<ACP_PLATFORMS>] { archive (https, no .dmg/.pkg/.deb/.rpm), cmd, sha256?, args?, env? }` — field names verbatim from the ACP registry `agent.schema.json`. Stored as the SA-keyed `DISTRIBUTION` (`atl:distribution`) string property in JCS form: `validateDistribution` (pure, `string[]` issues) · `encodeDistribution` (throws on invalid) · `decodeDistribution` (fail-closed → `null`) · `buildSetDistributionCall`. Public on-chain data by construction — never put a secret in `env`.
|
|
70
121
|
- **Profile facet**: `metadata-uri` + `metadata-hash` pointing at the canonical SA.
|
|
71
|
-
- **CAIP-10 `nativeId`**: cross-registry back-link; must match SA on EVM chains.
|
|
72
|
-
- **Verification**: proves an MCP/A2A URL is controlled by the SA (
|
|
122
|
+
- **CAIP-10 `nativeId`**: the cross-registry back-link; must match the SA on EVM chains.
|
|
123
|
+
- **Verification**: proves an MCP/A2A URL is controlled by the SA (distinct from naming).
|
|
73
124
|
|
|
74
125
|
See [`docs/concepts.md`](docs/concepts.md).
|
|
75
126
|
|
|
76
|
-
## Subpath
|
|
127
|
+
## Subpath exports
|
|
77
128
|
|
|
78
|
-
- `@agenticprimitives/agent-profile/caip10` — CAIP-10 helpers only.
|
|
129
|
+
- `@agenticprimitives/agent-profile/caip10` — CAIP-10 helpers only (no client baggage).
|
|
79
130
|
- `@agenticprimitives/agent-profile/profile` — canonical JSON + content hash.
|
|
131
|
+
- `@agenticprimitives/agent-profile/card` — signed canonical-profile bundle.
|
|
132
|
+
- `@agenticprimitives/agent-profile/a2a` — A2A 1.0 Agent Card model: JCS canonical bytes, ES256 JWS, EIP-712 Smart Agent binding, field provenance, validation, import, release lifecycle.
|
|
80
133
|
|
|
81
|
-
##
|
|
82
|
-
|
|
83
|
-
Phase 1 — pure helpers + client skeleton. `AgentIdentityClient` reads throw
|
|
84
|
-
`I Phase 2`; writes throw `I Phase 4`. Shape is locked for demo authoring.
|
|
85
|
-
|
|
86
|
-
## Security Invariants
|
|
134
|
+
## Security invariants
|
|
87
135
|
|
|
88
136
|
- Profile content-hash is deterministic (canonical JSON).
|
|
89
|
-
-
|
|
137
|
+
- Card canonical bytes are RFC 8785 JCS (never the sorted-key `canonicalizeJson`); signature and binding verification are fail-closed; import verifies before it normalizes; validation refuses secret material, private URLs and vault references in a card.
|
|
138
|
+
- No raw passkey material in profiles — only `credentialIdDigest`.
|
|
90
139
|
- Verification methods are explicit, not auto-selected.
|
|
140
|
+
- No UAID generation ([ADR-0008](../../docs/architecture/decisions/0008-caip10-nativeid-record-predicate.md)).
|
|
91
141
|
|
|
92
142
|
See [`docs/security.md`](docs/security.md) and [`AUDIT.md`](AUDIT.md).
|
|
93
143
|
|
|
94
|
-
## Documentation
|
|
144
|
+
## Documentation map
|
|
95
145
|
|
|
96
146
|
- [`docs/concepts.md`](docs/concepts.md) — profile facet vs canonical SA.
|
|
97
147
|
- [`docs/api.md`](docs/api.md) — public API guide.
|
|
@@ -108,6 +158,10 @@ pnpm check:agent-profile
|
|
|
108
158
|
pnpm check:forbidden-terms
|
|
109
159
|
```
|
|
110
160
|
|
|
161
|
+
## Status
|
|
162
|
+
|
|
163
|
+
**Phase 1 — pure helpers + client skeleton.** The schema, CAIP-10 helpers, and content hashing are real and tested; `AgentIdentityClient` reads throw `I Phase 2` and writes throw `I Phase 4` — they are stubs by design, and the shape is locked for authoring today. Beyond that: testnet/pilot-ready; production launch is gated on the public checklist in the root [`README.md`](../../README.md#status--honest-version), including third-party contract audit and governance key rotation. Track every security finding live in [`docs/audits/findings.yaml`](../../docs/audits/findings.yaml).
|
|
164
|
+
|
|
111
165
|
## License
|
|
112
166
|
|
|
113
167
|
UNLICENSED.
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `SmartAgentCardBindingV1` — the Smart Agent's EIP-712 statement that a specific released card (by
|
|
3
|
+
* resource, release, URI and BOTH digests) is its card, signed by the SA and validated through ERC-1271
|
|
4
|
+
* (spec 347 §4.2; ADR-0062 §2).
|
|
5
|
+
*
|
|
6
|
+
* Separate from the JWS on purpose: a non-AP A2A client verifies the JWS and never needs this; an AP
|
|
7
|
+
* verifier checks JWS → key thumbprint authorized → binding. The binding carries NO authority to act — it
|
|
8
|
+
* is descriptive evidence that the SA stands behind these exact bytes.
|
|
9
|
+
*
|
|
10
|
+
* Domain: `{ name:'AgenticPrimitivesAgentCard', version:'1', chainId, verifyingContract: <SA> }`.
|
|
11
|
+
* The ERC-1271 read is INJECTED (`Erc1271Verifier`, same port as `card.ts`) so this stays network-free.
|
|
12
|
+
*/
|
|
13
|
+
import { type Address, type Hex } from 'viem';
|
|
14
|
+
import type { Erc1271Verifier } from '../card.js';
|
|
15
|
+
import type { Sha256 } from '../types.js';
|
|
16
|
+
import type { SignedSmartAgentCardBindingV1, SmartAgentCardBindingV1 } from './types.js';
|
|
17
|
+
export declare const SMART_AGENT_CARD_BINDING_DOMAIN_NAME = "AgenticPrimitivesAgentCard";
|
|
18
|
+
export declare const SMART_AGENT_CARD_BINDING_DOMAIN_VERSION = "1";
|
|
19
|
+
export declare const SMART_AGENT_CARD_BINDING_TYPES: {
|
|
20
|
+
readonly SmartAgentCardBinding: readonly [{
|
|
21
|
+
readonly name: "canonicalAgentId";
|
|
22
|
+
readonly type: "string";
|
|
23
|
+
}, {
|
|
24
|
+
readonly name: "cardResourceId";
|
|
25
|
+
readonly type: "string";
|
|
26
|
+
}, {
|
|
27
|
+
readonly name: "cardReleaseId";
|
|
28
|
+
readonly type: "string";
|
|
29
|
+
}, {
|
|
30
|
+
readonly name: "cardUri";
|
|
31
|
+
readonly type: "string";
|
|
32
|
+
}, {
|
|
33
|
+
readonly name: "unsignedCardDigest";
|
|
34
|
+
readonly type: "bytes32";
|
|
35
|
+
}, {
|
|
36
|
+
readonly name: "signedCardDigest";
|
|
37
|
+
readonly type: "bytes32";
|
|
38
|
+
}, {
|
|
39
|
+
readonly name: "signerKeyThumbprint";
|
|
40
|
+
readonly type: "bytes32";
|
|
41
|
+
}, {
|
|
42
|
+
readonly name: "validFrom";
|
|
43
|
+
readonly type: "uint64";
|
|
44
|
+
}, {
|
|
45
|
+
readonly name: "validUntil";
|
|
46
|
+
readonly type: "uint64";
|
|
47
|
+
}];
|
|
48
|
+
};
|
|
49
|
+
/** The EIP-712 type string (for on-chain `TYPEHASH` parity checks). */
|
|
50
|
+
export declare const SMART_AGENT_CARD_BINDING_TYPE_STRING = "SmartAgentCardBinding(string canonicalAgentId,string cardResourceId,string cardReleaseId,string cardUri,bytes32 unsignedCardDigest,bytes32 signedCardDigest,bytes32 signerKeyThumbprint,uint64 validFrom,uint64 validUntil)";
|
|
51
|
+
export declare function smartAgentCardBindingDomain(chainId: number, smartAgent: Address): {
|
|
52
|
+
readonly name: "AgenticPrimitivesAgentCard";
|
|
53
|
+
readonly version: "1";
|
|
54
|
+
readonly chainId: number;
|
|
55
|
+
readonly verifyingContract: `0x${string}`;
|
|
56
|
+
};
|
|
57
|
+
export declare function sha256ToBytes32(digest: Sha256 | string): Hex;
|
|
58
|
+
export declare function bytes32ToSha256(h: Hex): Sha256;
|
|
59
|
+
/** RFC 7638 thumbprint (base64url of a sha256) ↔ bytes32. */
|
|
60
|
+
export declare function thumbprintToBytes32(thumbprint: string): Hex;
|
|
61
|
+
export declare function bytes32ToThumbprint(h: Hex): string;
|
|
62
|
+
/** The EIP-712 message as signed: digests + thumbprint as bytes32, times as uint64. */
|
|
63
|
+
export declare function smartAgentCardBindingMessage(b: SmartAgentCardBindingV1): {
|
|
64
|
+
canonicalAgentId: string;
|
|
65
|
+
cardResourceId: string;
|
|
66
|
+
cardReleaseId: string;
|
|
67
|
+
cardUri: string;
|
|
68
|
+
unsignedCardDigest: `0x${string}`;
|
|
69
|
+
signedCardDigest: `0x${string}`;
|
|
70
|
+
signerKeyThumbprint: `0x${string}`;
|
|
71
|
+
validFrom: bigint;
|
|
72
|
+
validUntil: bigint;
|
|
73
|
+
};
|
|
74
|
+
/** The 32-byte EIP-712 digest the SA signs and ERC-1271 validates. */
|
|
75
|
+
export declare function smartAgentCardBindingDigest(binding: SmartAgentCardBindingV1, chainId: number, smartAgent: Address): Hex;
|
|
76
|
+
export type VerifySmartAgentCardBindingResult = {
|
|
77
|
+
ok: true;
|
|
78
|
+
smartAgent: Address;
|
|
79
|
+
digest: Hex;
|
|
80
|
+
} | {
|
|
81
|
+
ok: false;
|
|
82
|
+
reason: 'bad_shape' | 'agent_mismatch' | 'digest_mismatch' | 'not_yet_valid' | 'expired' | 'signature_invalid';
|
|
83
|
+
};
|
|
84
|
+
export interface VerifySmartAgentCardBindingOptions {
|
|
85
|
+
erc1271Verifier: Erc1271Verifier;
|
|
86
|
+
/** Unix seconds; defaults to now. */
|
|
87
|
+
now?: number;
|
|
88
|
+
/** When given, the binding's digests MUST equal these (the release actually being verified). */
|
|
89
|
+
expect?: {
|
|
90
|
+
unsignedCardDigest?: Sha256;
|
|
91
|
+
signedCardDigest?: Sha256;
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Fail-closed verification: shape → `canonicalAgentId` names this SA on this chain → expected digests →
|
|
96
|
+
* validity window → ERC-1271 over the EIP-712 digest. Any anomaly ⇒ `ok:false`.
|
|
97
|
+
*/
|
|
98
|
+
export declare function verifySmartAgentCardBinding(signed: SignedSmartAgentCardBindingV1, opts: VerifySmartAgentCardBindingOptions): Promise<VerifySmartAgentCardBindingResult>;
|
|
99
|
+
//# sourceMappingURL=binding.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/a2a/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAiB,KAAK,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,6BAA6B,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEzF,eAAO,MAAM,oCAAoC,+BAA+B,CAAC;AACjF,eAAO,MAAM,uCAAuC,MAAM,CAAC;AAE3D,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAYjC,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,oCAAoC,gOAC8K,CAAC;AAEhO,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO;;;;;EAO/E;AAMD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,GAAG,CAI5D;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,CAG9C;AAED,6DAA6D;AAC7D,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAI3D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,CAKlD;AAID,uFAAuF;AACvF,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,uBAAuB;;;;;;;;;;EAetE;AAED,sEAAsE;AACtE,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,GAAG,CAOvH;AAID,MAAM,MAAM,iCAAiC,GACzC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GAC9C;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EACF,WAAW,GACX,gBAAgB,GAChB,iBAAiB,GACjB,eAAe,GACf,SAAS,GACT,mBAAmB,CAAC;CACzB,CAAC;AAEN,MAAM,WAAW,kCAAkC;IACjD,eAAe,EAAE,eAAe,CAAC;IACjC,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,MAAM,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAID;;;GAGG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,kCAAkC,GACvC,OAAO,CAAC,iCAAiC,CAAC,CAuC5C"}
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `SmartAgentCardBindingV1` — the Smart Agent's EIP-712 statement that a specific released card (by
|
|
3
|
+
* resource, release, URI and BOTH digests) is its card, signed by the SA and validated through ERC-1271
|
|
4
|
+
* (spec 347 §4.2; ADR-0062 §2).
|
|
5
|
+
*
|
|
6
|
+
* Separate from the JWS on purpose: a non-AP A2A client verifies the JWS and never needs this; an AP
|
|
7
|
+
* verifier checks JWS → key thumbprint authorized → binding. The binding carries NO authority to act — it
|
|
8
|
+
* is descriptive evidence that the SA stands behind these exact bytes.
|
|
9
|
+
*
|
|
10
|
+
* Domain: `{ name:'AgenticPrimitivesAgentCard', version:'1', chainId, verifyingContract: <SA> }`.
|
|
11
|
+
* The ERC-1271 read is INJECTED (`Erc1271Verifier`, same port as `card.ts`) so this stays network-free.
|
|
12
|
+
*/
|
|
13
|
+
import { hashTypedData } from 'viem';
|
|
14
|
+
import { base64UrlDecode, base64UrlEncode } from './jws.js';
|
|
15
|
+
export const SMART_AGENT_CARD_BINDING_DOMAIN_NAME = 'AgenticPrimitivesAgentCard';
|
|
16
|
+
export const SMART_AGENT_CARD_BINDING_DOMAIN_VERSION = '1';
|
|
17
|
+
export const SMART_AGENT_CARD_BINDING_TYPES = {
|
|
18
|
+
SmartAgentCardBinding: [
|
|
19
|
+
{ name: 'canonicalAgentId', type: 'string' },
|
|
20
|
+
{ name: 'cardResourceId', type: 'string' },
|
|
21
|
+
{ name: 'cardReleaseId', type: 'string' },
|
|
22
|
+
{ name: 'cardUri', type: 'string' },
|
|
23
|
+
{ name: 'unsignedCardDigest', type: 'bytes32' },
|
|
24
|
+
{ name: 'signedCardDigest', type: 'bytes32' },
|
|
25
|
+
{ name: 'signerKeyThumbprint', type: 'bytes32' },
|
|
26
|
+
{ name: 'validFrom', type: 'uint64' },
|
|
27
|
+
{ name: 'validUntil', type: 'uint64' },
|
|
28
|
+
],
|
|
29
|
+
};
|
|
30
|
+
/** The EIP-712 type string (for on-chain `TYPEHASH` parity checks). */
|
|
31
|
+
export const SMART_AGENT_CARD_BINDING_TYPE_STRING = 'SmartAgentCardBinding(string canonicalAgentId,string cardResourceId,string cardReleaseId,string cardUri,bytes32 unsignedCardDigest,bytes32 signedCardDigest,bytes32 signerKeyThumbprint,uint64 validFrom,uint64 validUntil)';
|
|
32
|
+
export function smartAgentCardBindingDomain(chainId, smartAgent) {
|
|
33
|
+
return {
|
|
34
|
+
name: SMART_AGENT_CARD_BINDING_DOMAIN_NAME,
|
|
35
|
+
version: SMART_AGENT_CARD_BINDING_DOMAIN_VERSION,
|
|
36
|
+
chainId,
|
|
37
|
+
verifyingContract: smartAgent,
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
// ─── digest ↔ bytes32 ────────────────────────────────────────────────────────────────────────────────
|
|
41
|
+
const SHA256_RE = /^sha256:([0-9a-f]{64})$/;
|
|
42
|
+
export function sha256ToBytes32(digest) {
|
|
43
|
+
const m = SHA256_RE.exec(digest.toLowerCase());
|
|
44
|
+
if (!m)
|
|
45
|
+
throw new Error(`not a sha256 digest: "${digest}"`);
|
|
46
|
+
return `0x${m[1]}`;
|
|
47
|
+
}
|
|
48
|
+
export function bytes32ToSha256(h) {
|
|
49
|
+
if (!/^0x[0-9a-fA-F]{64}$/.test(h))
|
|
50
|
+
throw new Error(`not a bytes32: "${h}"`);
|
|
51
|
+
return `sha256:${h.slice(2).toLowerCase()}`;
|
|
52
|
+
}
|
|
53
|
+
/** RFC 7638 thumbprint (base64url of a sha256) ↔ bytes32. */
|
|
54
|
+
export function thumbprintToBytes32(thumbprint) {
|
|
55
|
+
const bytes = base64UrlDecode(thumbprint);
|
|
56
|
+
if (bytes.length !== 32)
|
|
57
|
+
throw new Error('signerKeyThumbprint must be a base64url sha256 (32 bytes)');
|
|
58
|
+
return `0x${Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')}`;
|
|
59
|
+
}
|
|
60
|
+
export function bytes32ToThumbprint(h) {
|
|
61
|
+
if (!/^0x[0-9a-fA-F]{64}$/.test(h))
|
|
62
|
+
throw new Error(`not a bytes32: "${h}"`);
|
|
63
|
+
const bytes = new Uint8Array(32);
|
|
64
|
+
for (let i = 0; i < 32; i++)
|
|
65
|
+
bytes[i] = parseInt(h.slice(2 + i * 2, 4 + i * 2), 16);
|
|
66
|
+
return base64UrlEncode(bytes);
|
|
67
|
+
}
|
|
68
|
+
// ─── digest ──────────────────────────────────────────────────────────────────────────────────────────
|
|
69
|
+
/** The EIP-712 message as signed: digests + thumbprint as bytes32, times as uint64. */
|
|
70
|
+
export function smartAgentCardBindingMessage(b) {
|
|
71
|
+
if (!Number.isInteger(b.validFrom) || b.validFrom < 0 || !Number.isInteger(b.validUntil) || b.validUntil < 0) {
|
|
72
|
+
throw new Error('validFrom/validUntil must be non-negative integer unix seconds');
|
|
73
|
+
}
|
|
74
|
+
return {
|
|
75
|
+
canonicalAgentId: b.canonicalAgentId,
|
|
76
|
+
cardResourceId: b.cardResourceId,
|
|
77
|
+
cardReleaseId: b.cardReleaseId,
|
|
78
|
+
cardUri: b.cardUri,
|
|
79
|
+
unsignedCardDigest: sha256ToBytes32(b.unsignedCardDigest),
|
|
80
|
+
signedCardDigest: sha256ToBytes32(b.signedCardDigest),
|
|
81
|
+
signerKeyThumbprint: thumbprintToBytes32(b.signerKeyThumbprint),
|
|
82
|
+
validFrom: BigInt(b.validFrom),
|
|
83
|
+
validUntil: BigInt(b.validUntil),
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
/** The 32-byte EIP-712 digest the SA signs and ERC-1271 validates. */
|
|
87
|
+
export function smartAgentCardBindingDigest(binding, chainId, smartAgent) {
|
|
88
|
+
return hashTypedData({
|
|
89
|
+
domain: smartAgentCardBindingDomain(chainId, smartAgent),
|
|
90
|
+
types: SMART_AGENT_CARD_BINDING_TYPES,
|
|
91
|
+
primaryType: 'SmartAgentCardBinding',
|
|
92
|
+
message: smartAgentCardBindingMessage(binding),
|
|
93
|
+
});
|
|
94
|
+
}
|
|
95
|
+
const CAIP10_EVM = /^eip155:(\d+):(0x[0-9a-fA-F]{40})$/;
|
|
96
|
+
/**
|
|
97
|
+
* Fail-closed verification: shape → `canonicalAgentId` names this SA on this chain → expected digests →
|
|
98
|
+
* validity window → ERC-1271 over the EIP-712 digest. Any anomaly ⇒ `ok:false`.
|
|
99
|
+
*/
|
|
100
|
+
export async function verifySmartAgentCardBinding(signed, opts) {
|
|
101
|
+
const b = signed?.binding;
|
|
102
|
+
if (!b ||
|
|
103
|
+
typeof signed.chainId !== 'number' ||
|
|
104
|
+
typeof signed.verifyingContract !== 'string' ||
|
|
105
|
+
typeof signed.signature !== 'string' ||
|
|
106
|
+
typeof b.canonicalAgentId !== 'string') {
|
|
107
|
+
return { ok: false, reason: 'bad_shape' };
|
|
108
|
+
}
|
|
109
|
+
const m = CAIP10_EVM.exec(b.canonicalAgentId);
|
|
110
|
+
if (!m || Number(m[1]) !== signed.chainId || m[2].toLowerCase() !== signed.verifyingContract.toLowerCase()) {
|
|
111
|
+
return { ok: false, reason: 'agent_mismatch' };
|
|
112
|
+
}
|
|
113
|
+
if (opts.expect?.unsignedCardDigest && opts.expect.unsignedCardDigest !== b.unsignedCardDigest) {
|
|
114
|
+
return { ok: false, reason: 'digest_mismatch' };
|
|
115
|
+
}
|
|
116
|
+
if (opts.expect?.signedCardDigest && opts.expect.signedCardDigest !== b.signedCardDigest) {
|
|
117
|
+
return { ok: false, reason: 'digest_mismatch' };
|
|
118
|
+
}
|
|
119
|
+
const now = opts.now ?? Math.floor(Date.now() / 1000);
|
|
120
|
+
if (now < b.validFrom)
|
|
121
|
+
return { ok: false, reason: 'not_yet_valid' };
|
|
122
|
+
if (b.validUntil !== 0 && now > b.validUntil)
|
|
123
|
+
return { ok: false, reason: 'expired' };
|
|
124
|
+
let digest;
|
|
125
|
+
try {
|
|
126
|
+
digest = smartAgentCardBindingDigest(b, signed.chainId, signed.verifyingContract);
|
|
127
|
+
}
|
|
128
|
+
catch {
|
|
129
|
+
return { ok: false, reason: 'bad_shape' };
|
|
130
|
+
}
|
|
131
|
+
let valid;
|
|
132
|
+
try {
|
|
133
|
+
valid = await opts.erc1271Verifier.verifyHash({ address: signed.verifyingContract, hash: digest, signature: signed.signature });
|
|
134
|
+
}
|
|
135
|
+
catch {
|
|
136
|
+
return { ok: false, reason: 'signature_invalid' };
|
|
137
|
+
}
|
|
138
|
+
if (!valid)
|
|
139
|
+
return { ok: false, reason: 'signature_invalid' };
|
|
140
|
+
return { ok: true, smartAgent: signed.verifyingContract, digest };
|
|
141
|
+
}
|
|
142
|
+
//# sourceMappingURL=binding.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"binding.js","sourceRoot":"","sources":["../../src/a2a/binding.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Canonical form of an A2A Agent Card (spec 347 §4.2).
|
|
3
|
+
*
|
|
4
|
+
* remove `signatures` → RFC 8785 JCS → UTF-8 bytes → `sha256:<hex>`
|
|
5
|
+
*
|
|
6
|
+
* Uses `types.jcsCanonicalize` (RFC 8785: number formatting, escaping, UTF-16 code-unit key order) and
|
|
7
|
+
* NOT the sorted-key `canonicalizeJson` — those produce different bytes for the same document, and these
|
|
8
|
+
* bytes are what every JWS signs and every Smart Agent binding names. Presence is preserved: an omitted
|
|
9
|
+
* optional and an explicit default are different bytes, on purpose.
|
|
10
|
+
*/
|
|
11
|
+
import type { Sha256 } from '../types.js';
|
|
12
|
+
/** Anything card-shaped: the typed card, or a raw imported object (unknown fields included — they are
|
|
13
|
+
* part of what an existing signature covers). */
|
|
14
|
+
export type CardLike = {
|
|
15
|
+
signatures?: unknown;
|
|
16
|
+
};
|
|
17
|
+
/** The card without `signatures` — the exact object every signature is computed over. */
|
|
18
|
+
export declare function unsignedCard<T extends CardLike>(card: T): Omit<T, 'signatures'>;
|
|
19
|
+
/** JCS string of the unsigned card. Throws (`JcsError`) on non-JSON values — never silently drops. */
|
|
20
|
+
export declare function canonicalCardJson(card: CardLike): string;
|
|
21
|
+
/** UTF-8 bytes of {@link canonicalCardJson}. */
|
|
22
|
+
export declare function canonicalCardBytes(card: CardLike): Uint8Array;
|
|
23
|
+
/** `sha256:<hex>` of arbitrary bytes. */
|
|
24
|
+
export declare function sha256Digest(bytes: Uint8Array): Sha256;
|
|
25
|
+
/** `sha256:<hex>` of a JCS-canonicalized value (used for field digests + etags). */
|
|
26
|
+
export declare function jcsDigest(value: unknown): Sha256;
|
|
27
|
+
/** `unsignedContentDigest`: sha256 of the canonical (unsigned) card bytes. */
|
|
28
|
+
export declare function cardContentDigest(card: CardLike): Sha256;
|
|
29
|
+
/** `signedContentDigest`: sha256 over JCS of the WHOLE card, signatures included. */
|
|
30
|
+
export declare function signedCardContentDigest(card: CardLike): Sha256;
|
|
31
|
+
//# sourceMappingURL=canonical.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/a2a/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;kDACkD;AAClD,MAAM,MAAM,QAAQ,GAAG;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhD,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,YAAY,CAAC,CAG/E;AAED,sGAAsG;AACtG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAExD;AAID,gDAAgD;AAChD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAE7D;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEtD;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAExD;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAE9D"}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Canonical form of an A2A Agent Card (spec 347 §4.2).
|
|
3
|
+
*
|
|
4
|
+
* remove `signatures` → RFC 8785 JCS → UTF-8 bytes → `sha256:<hex>`
|
|
5
|
+
*
|
|
6
|
+
* Uses `types.jcsCanonicalize` (RFC 8785: number formatting, escaping, UTF-16 code-unit key order) and
|
|
7
|
+
* NOT the sorted-key `canonicalizeJson` — those produce different bytes for the same document, and these
|
|
8
|
+
* bytes are what every JWS signs and every Smart Agent binding names. Presence is preserved: an omitted
|
|
9
|
+
* optional and an explicit default are different bytes, on purpose.
|
|
10
|
+
*/
|
|
11
|
+
import { jcsCanonicalize } from '@agenticprimitives/types';
|
|
12
|
+
import { sha256 as viemSha256 } from 'viem';
|
|
13
|
+
/** The card without `signatures` — the exact object every signature is computed over. */
|
|
14
|
+
export function unsignedCard(card) {
|
|
15
|
+
const { signatures: _drop, ...rest } = card;
|
|
16
|
+
return rest;
|
|
17
|
+
}
|
|
18
|
+
/** JCS string of the unsigned card. Throws (`JcsError`) on non-JSON values — never silently drops. */
|
|
19
|
+
export function canonicalCardJson(card) {
|
|
20
|
+
return jcsCanonicalize(unsignedCard(card));
|
|
21
|
+
}
|
|
22
|
+
const utf8 = new TextEncoder();
|
|
23
|
+
/** UTF-8 bytes of {@link canonicalCardJson}. */
|
|
24
|
+
export function canonicalCardBytes(card) {
|
|
25
|
+
return utf8.encode(canonicalCardJson(card));
|
|
26
|
+
}
|
|
27
|
+
/** `sha256:<hex>` of arbitrary bytes. */
|
|
28
|
+
export function sha256Digest(bytes) {
|
|
29
|
+
return `sha256:${viemSha256(bytes).slice(2)}`;
|
|
30
|
+
}
|
|
31
|
+
/** `sha256:<hex>` of a JCS-canonicalized value (used for field digests + etags). */
|
|
32
|
+
export function jcsDigest(value) {
|
|
33
|
+
return sha256Digest(utf8.encode(jcsCanonicalize(value)));
|
|
34
|
+
}
|
|
35
|
+
/** `unsignedContentDigest`: sha256 of the canonical (unsigned) card bytes. */
|
|
36
|
+
export function cardContentDigest(card) {
|
|
37
|
+
return sha256Digest(canonicalCardBytes(card));
|
|
38
|
+
}
|
|
39
|
+
/** `signedContentDigest`: sha256 over JCS of the WHOLE card, signatures included. */
|
|
40
|
+
export function signedCardContentDigest(card) {
|
|
41
|
+
return jcsDigest(card);
|
|
42
|
+
}
|
|
43
|
+
//# sourceMappingURL=canonical.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../src/a2a/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AAO5C,yFAAyF;AACzF,MAAM,UAAU,YAAY,CAAqB,IAAO;IACtD,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC5C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,OAAO,eAAe,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;AAE/B,gDAAgD;AAChD,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC/C,OAAO,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,YAAY,CAAC,KAAiB;IAC5C,OAAO,UAAU,UAAU,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAY,CAAC;AAC1D,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,OAAO,YAAY,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,uBAAuB,CAAC,IAAc;IACpD,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC"}
|