@atrib/verify 0.7.10 → 0.8.1
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/LICENSE +1 -1
- package/README.md +72 -5
- package/dist/anchor-plurality.d.ts +142 -0
- package/dist/anchor-plurality.d.ts.map +1 -0
- package/dist/anchor-plurality.js +473 -0
- package/dist/anchor-plurality.js.map +1 -0
- package/dist/authorization-evidence.d.ts +6 -2
- package/dist/authorization-evidence.d.ts.map +1 -1
- package/dist/authorization-evidence.js +21 -0
- package/dist/authorization-evidence.js.map +1 -1
- package/dist/delegation.d.ts +186 -0
- package/dist/delegation.d.ts.map +1 -0
- package/dist/delegation.js +319 -0
- package/dist/delegation.js.map +1 -0
- package/dist/evidence-envelope.d.ts +205 -0
- package/dist/evidence-envelope.d.ts.map +1 -0
- package/dist/evidence-envelope.js +378 -0
- package/dist/evidence-envelope.js.map +1 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +16 -0
- package/dist/index.js.map +1 -1
- package/dist/session-checkpoint.d.ts +200 -0
- package/dist/session-checkpoint.d.ts.map +1 -0
- package/dist/session-checkpoint.js +421 -0
- package/dist/session-checkpoint.js.map +1 -0
- package/dist/verify-record.d.ts +43 -0
- package/dist/verify-record.d.ts.map +1 -1
- package/dist/verify-record.js +25 -1
- package/dist/verify-record.js.map +1 -1
- package/dist/x401-evidence.d.ts +94 -0
- package/dist/x401-evidence.d.ts.map +1 -0
- package/dist/x401-evidence.js +560 -0
- package/dist/x401-evidence.js.map +1 -0
- package/package.json +6 -3
package/LICENSE
CHANGED
|
@@ -201,7 +201,7 @@
|
|
|
201
201
|
See the License for the specific language governing permissions and
|
|
202
202
|
limitations under the License.
|
|
203
203
|
|
|
204
|
-
Copyright 2025-2026
|
|
204
|
+
Copyright 2025-2026 atrib contributors
|
|
205
205
|
|
|
206
206
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
207
207
|
you may not use this file except in compliance with the License.
|
package/README.md
CHANGED
|
@@ -1,8 +1,16 @@
|
|
|
1
1
|
# `@atrib/verify`
|
|
2
2
|
|
|
3
|
-
**Independent verification
|
|
3
|
+
**Independent verification for atrib's verifiable action layer. Checks signed records, evidence blocks, handoff packets, and settlement documents. Re-runs the spec [§4.6](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#46-the-calculation-algorithm) calculation algorithm locally and checks the result against what a recommendation document claims. No trust in any intermediary required.**
|
|
4
4
|
|
|
5
|
-
This is the **verifier half** of the atrib protocol, used by merchants closing transactions, auditors checking agent activity, regulators querying historical state, and any party that needs to validate atrib data independently. The agent and tool servers produce signed attribution records. The Merkle log stores them. This package answers the questions any verifier has to answer: _given the graph and the policy, is this distribution actually correct? Was this record actually signed by the key it claims? Did this action actually happen at the time it claims?_
|
|
5
|
+
This is the **verifier half** of the atrib protocol, used by merchants closing transactions, auditors checking agent activity, teams accepting handoffs, policy systems reviewing high-impact actions, regulators querying historical state, and any party that needs to validate atrib data independently. The agent and tool servers produce signed attribution records. The Merkle log stores them. This package answers the questions any verifier has to answer: _given the graph and the policy, is this distribution actually correct? Was this record actually signed by the key it claims? Did this action actually happen at the time it claims?_
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pnpm add @atrib/verify
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Verify a local build with `pnpm --filter @atrib/verify test`.
|
|
6
14
|
|
|
7
15
|
## Quick start
|
|
8
16
|
|
|
@@ -15,6 +23,8 @@ const verifier = new AtribVerifier({
|
|
|
15
23
|
logEndpoint: 'https://log.atrib.dev/v1',
|
|
16
24
|
})
|
|
17
25
|
|
|
26
|
+
// recommendationDoc is a §4.7 settlement RecommendationDocument produced by a
|
|
27
|
+
// calculator or merchant (signed distribution over record hashes).
|
|
18
28
|
const result = await verifier.verify(recommendationDoc)
|
|
19
29
|
// {
|
|
20
30
|
// valid: true,
|
|
@@ -83,7 +93,7 @@ const result = await verifyRecord(record, {
|
|
|
83
93
|
informedByCandidates: [], // optional, for informed_by[] resolution
|
|
84
94
|
identityClaim, // optional, for capability_check (caller does directory lookup)
|
|
85
95
|
resolvedFacts, // optional, caller-resolved facts for capability_check
|
|
86
|
-
authorizationEvidence, // optional, OAuth/MCP
|
|
96
|
+
authorizationEvidence, // optional, OAuth/MCP, AAuth, or x401 evidence blocks
|
|
87
97
|
ap2ViEvidence, // optional, transaction-only AP2 / VI evidence bundle
|
|
88
98
|
ap2ViEvidenceOptions, // optional, passed to verifyAp2ViEvidenceAsync()
|
|
89
99
|
})
|
|
@@ -107,7 +117,7 @@ const result = await verifyRecord(record, {
|
|
|
107
117
|
- `posture`: `{ timestamp_granularity, timestamp_consistent, timestamp_granularity_explicit, args_commitment_form, result_commitment_form, tool_name_form }` ([D045](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d045-privacy-postures-normative-spec-section) / [D061](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d061-add-tool_name-args_hash-result_hash-fields-to-§121) / [§8.2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#82-opaque-name-posture) / [§8.3](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#83-salted-commitment-posture) / [§8.4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#84-coarsened-timing-posture)). Always populated. Surfaces (a) the declared timing granularity, whether the timestamp value structurally matches the spec's trailing-zero invariant, and whether the field was explicitly set vs defaulted; (b) the structurally-detected `args_hash` / `result_hash` commitment scheme: `'salted-sha256'` when `args_salt` / `result_salt` is present, `'plain-sha256'` otherwise (the `'hmac-sha256'` variant from [§8.3](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#83-salted-commitment-posture) is signaled out-of-band and is not structurally detectable); and (c) the [§8.2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#82-opaque-name-posture) `tool_name_form`: `'hashed'` when `tool_name` matches `^sha256:[0-9a-f]{64}$`, `'plain'` for any other present value, `null` when the field is absent. Per [D061](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d061-add-tool_name-args_hash-result_hash-fields-to-121) the [§8.2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#82-opaque-name-posture) verbatim-vs-opaque distinction is NOT structurally detectable, both surface as `'plain'`.
|
|
108
118
|
- `capability_check`: `{ envelope, in_envelope, mismatches, unresolvable }` ([D051](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d051-capability-scoped-records-via-directory-published-envelopes) / [§6.7](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#67-capability-declarations)). Populated only when the caller passes a resolved `identityClaim` in options. Checks the record's `event_type` against the envelope's `event_types` allowlist and the record's `timestamp` against `expires_at`. `tool_names`, `max_amount`, and `counterparties` are checked when the caller supplies `resolvedFacts` from the local body or protocol event. Missing facts flag `unresolvable: true` rather than passing silently. Per [§6.7.3](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#673-out-of-envelope-records) out-of-envelope is a signal, not invalidation: mismatches do not flip `valid` to false. The caller is responsible for fetching the active envelope at the record's timestamp via `@atrib/directory`'s `lookup()` (or a cached equivalent); `@atrib/verify` intentionally has no `@atrib/directory` dependency.
|
|
109
119
|
- `cross_attestation`: `{ signers_count, signers_valid, missing }` ([D052](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d052-cross-attestation-requirement-for-transaction-records) / [§1.7.6](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#176-cross-attestation-requirement-for-transaction-records)). Populated only on transaction records (`event_type = transaction`). Each entry in `signers[]` is verified against the cross-attestation canonical bytes (JCS form with `signers: []` and the top-level `signature` field omitted, per [§1.7.6](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#176-cross-attestation-requirement-for-transaction-records)). `signatureOk` requires a valid signer entry whose `creator_key` matches the record's top-level `creator_key`; unrelated counterparty signers do not validate the record on behalf of its creator. `missing: true` when fewer than 2 distinct signer keys verify, atrib's normative minimum. Duplicate entries from one key do not inflate `signers_valid`. Per [§1.7.6](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#176-cross-attestation-requirement-for-transaction-records) missing is a signal, not invalidation: `valid` stays true if the underlying signature path holds. Agent-side Path 2 fallback records usually surface as `signers_count: 1, missing: true` until a counterparty signs the same bytes. Legacy single-signer transaction records (no `signers[]` array, only top-level `signature`) surface as `signers_count: 0, missing: true` so consumers can flag them while accepting the cryptographic validity.
|
|
110
|
-
- `evidence`: generic tiered external authorization evidence blocks ([D109](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d109-mcpoauth-authorization-evidence-uses-generic-tiered-evidence-blocks) / [§5.5.6](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#556-generic-authorization-evidence-blocks)). Populated when the caller passes `authorizationEvidence` or when AP2 / VI evidence is mirrored into the generic shape. Each block has `{ valid, protocol, issuer, subject, scope, attenuation_ok, delegation_ok, constraints, errors, warnings }`. These blocks do not alter `valid`, `signatureOk`, or `capability_check`.
|
|
120
|
+
- `evidence`: generic tiered external authorization evidence blocks ([D109](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d109-mcpoauth-authorization-evidence-uses-generic-tiered-evidence-blocks) / [§5.5.6](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#556-generic-authorization-evidence-blocks)). Populated when the caller passes `authorizationEvidence` or when AP2 / VI evidence is mirrored into the generic shape. Each block has `{ valid, protocol, issuer, subject, scope, attenuation_ok, delegation_ok, constraints, errors, warnings }`. Current authorization adapters are MCP/OAuth, AAuth, and x401. These blocks do not alter `valid`, `signatureOk`, or `capability_check`.
|
|
111
121
|
- `ap2_vi_evidence`: the async AP2 / VI verifier result ([D094](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d094-ap2--vi-evidence-attaches-to-verifier-results-as-a-tiered-block) / [§5.5.4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#554-ap2--verifiable-intent-evidence-checks)). Populated only when the caller passes `ap2ViEvidence` for a transaction record. It does not alter `valid`, `signatureOk`, or `cross_attestation`; consumers inspect `ap2_vi_evidence.valid` for AP2 authorization evidence.
|
|
112
122
|
|
|
113
123
|
**Pending per-record annotations** (tracked as a Pending decision in [DECISIONS.md P005](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#p005-reconcile-atribverify-readme-per-record-annotations-with-actual-code-surface)):
|
|
@@ -259,6 +269,57 @@ The shared endpoint must atomically remember the posted key until `expires_at_se
|
|
|
259
269
|
|
|
260
270
|
Producer-side MCP capture lives in `@atrib/mcp` behind the opt-in `authorizationEvidence` option. The producer writes evidence into the local-only sidecar without storing raw bearer tokens by default. Verifiers can pass that sidecar's `authorizationEvidence` and `resolvedFacts` to `verifyRecord()`.
|
|
261
271
|
|
|
272
|
+
### `verifyX401AuthorizationEvidence(evidence): X401AuthorizationEvidenceVerification`
|
|
273
|
+
|
|
274
|
+
Verifier-side x401 proof evidence checking. This runs outside the record signature path and does not verify OpenID4VP credentials, fetch remote credential results, call issuers, exchange OAuth tokens, or mint verification tokens. Callers supply decoded x401 objects or base64url JSON header values, then pass `resultVerified: true` or `tokenVerified: true` only after their own credential or token verifier accepts the result.
|
|
275
|
+
|
|
276
|
+
```typescript
|
|
277
|
+
import { encodeX401HeaderObject, verifyRecord } from '@atrib/verify'
|
|
278
|
+
|
|
279
|
+
const result = await verifyRecord(record, {
|
|
280
|
+
authorizationEvidence: [
|
|
281
|
+
{
|
|
282
|
+
protocol: 'x401',
|
|
283
|
+
x401: {
|
|
284
|
+
headers: {
|
|
285
|
+
'PROOF-REQUEST': encodeX401HeaderObject(proofRequest),
|
|
286
|
+
'PROOF-RESPONSE': encodeX401HeaderObject(resultArtifact),
|
|
287
|
+
},
|
|
288
|
+
resultVerified: true,
|
|
289
|
+
expectedRequestId: 'proof-template-financial-customer-v1',
|
|
290
|
+
expectedAgentId: 'did:web:agent.example',
|
|
291
|
+
expectedAgentOrigin: 'https://agent.example/origin',
|
|
292
|
+
agentOrigin: 'https://agent.example/origin',
|
|
293
|
+
agentOriginVerified: true,
|
|
294
|
+
issuerTrustVerified: true,
|
|
295
|
+
issuerTrustRootType: 'proof-trust-list',
|
|
296
|
+
issuerTrustRootRef: 'https://trust.example/x401.json',
|
|
297
|
+
proofPaymentBindingVerified: true,
|
|
298
|
+
proofPaymentBindingRef: 'ap2-receipt:checkout-123',
|
|
299
|
+
requiredSatisfiedRequirements: ['kyc:basic'],
|
|
300
|
+
},
|
|
301
|
+
},
|
|
302
|
+
],
|
|
303
|
+
})
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
Checks performed when evidence is present:
|
|
307
|
+
|
|
308
|
+
- x401 envelope, version, `credential_requirements.digital.requests[]`, and OAuth token endpoint.
|
|
309
|
+
- Request id and result-artifact binding when both are present.
|
|
310
|
+
- Visible OpenID4VP nonce from the credential request.
|
|
311
|
+
- Result artifact or x401 token object shape.
|
|
312
|
+
- Optional agent id, credential protocol, and satisfied requirement ids.
|
|
313
|
+
- Optional caller-owned agent-origin, issuer-trust, and proof-payment binding verifier facts.
|
|
314
|
+
- `PROOF-RESULT` error objects.
|
|
315
|
+
- Payment separation: x401 `payment` hints are reported as informational and do not satisfy x402, MPP, AP2, ACP, or UCP.
|
|
316
|
+
|
|
317
|
+
The default verification policy is `require`. A decoded proof response without `resultVerified: true` or `tokenVerified: true` is invalid, because parsing a header is not credential verification. Use `verificationPolicy: "best-effort"` for advisory review or `"off"` when another layer has already enforced the requirement. Optional agent-origin, issuer-trust, and proof-payment binding fields record caller-owned verifier outcomes. Explicit `false` values fail the evidence block. References are hashed in public details. Older draft names such as `PROOF-REQUIRED`, `PROOF-PRESENTATION`, and `presentation_requirements` are accepted with warnings by default; set `allowLegacyHeaders: false` or `allowLegacyFields: false` to reject them.
|
|
318
|
+
|
|
319
|
+
The returned `details` object is safe for archive projection and Explorer rendering by default. It exposes proof request, response, and result hashes, `proof_gate` status, `payment_separation`, hashed origin, trust-root, and proof-payment binding references, the visible request id, visible nonce, agent id, credential protocol, and whether a `credential_result_uri` was present. It does not expose raw credential payloads, raw proof-response header values, raw verification tokens, trust-list documents, proof-payment binding documents, or fetched result-by-reference bodies.
|
|
320
|
+
|
|
321
|
+
The offline x401 corpus lives at [`spec/conformance/5.5.6/x401/`](https://github.com/creatornader/atrib/blob/main/spec/conformance/5.5.6/x401/). It covers current headers, result artifacts, token responses, result-by-reference, request-id mismatch, proof-result errors, unverified proof failures, legacy-header strict mode, payment-hint separation, external origin facts, issuer-trust facts, and proof-payment binding facts.
|
|
322
|
+
|
|
262
323
|
### `verifyAAuthAuthorizationEvidence(evidence): Promise<AAuthAuthorizationEvidenceVerification>`
|
|
263
324
|
|
|
264
325
|
Verifier-side AAuth authorization evidence checking. This runs outside the record signature path and does not fetch AAuth metadata, fetch JWKS, mint tokens, call a PS, call an AS, or perform user interaction. Callers supply a compact AAuth JWT plus trusted JWKS, caller-verified claims, or decoded claims under an explicit `signaturePolicy`.
|
|
@@ -396,6 +457,8 @@ For advanced use (custom calculators, alternative signing flows), the package al
|
|
|
396
457
|
- `verifyAuthorizationEvidence(evidence)`: generic external authorization evidence dispatch for `verifyRecord()` evidence blocks
|
|
397
458
|
- `verifyOAuthAuthorizationEvidence(evidence)`: OAuth / MCP authorization evidence checks for access-token JWTs or caller-verified claims
|
|
398
459
|
- `verifyAAuthAuthorizationEvidence(evidence)`: AAuth authorization evidence checks for agent, resource, and auth tokens plus caller-verified HTTP signature facts
|
|
460
|
+
- `verifyX401AuthorizationEvidence(evidence)`: x401 proof evidence checks for proof request, proof response, proof result, and caller-verified proof outcomes
|
|
461
|
+
- `encodeX401HeaderObject(value)` / `decodeX401HeaderObject(value)`: base64url JSON helpers for x401 proof headers
|
|
399
462
|
- `introspectOAuthToken(options)`: host-owned OAuth token introspection helper for opaque-token evidence
|
|
400
463
|
- `oauthEvidenceFromIntrospectionResult(result, base?)`: adapter from host-owned introspection result to OAuth evidence input
|
|
401
464
|
- `createFetchDpopReplayCache(options)`: HTTP-backed DPoP replay-cache adapter for fleet-shared replay checks
|
|
@@ -428,7 +491,7 @@ The merchant's payment pipeline never crashes because of an atrib problem. It ju
|
|
|
428
491
|
|
|
429
492
|
## Test coverage
|
|
430
493
|
|
|
431
|
-
The test suite covers the [§4.6](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#46-the-calculation-algorithm) calculation algorithm, graph endpoint client, JCS canonicalization, Ed25519 signing, settlement recommendations, policy templates, policy builder, calculation edge cases, property-based testing with fast-check, AP2 / VI evidence checking, AP2 / VI crypto conformance, tiered AP2 / VI verifier attachment, and full `verify()` / `calculate()` paths including [§5.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract) degradation.
|
|
494
|
+
The test suite covers the [§4.6](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#46-the-calculation-algorithm) calculation algorithm, graph endpoint client, JCS canonicalization, Ed25519 signing, settlement recommendations, policy templates, policy builder, calculation edge cases, property-based testing with fast-check, AP2 / VI evidence checking, AP2 / VI crypto conformance, x401 proof evidence checking, x401 authorization evidence conformance, tiered AP2 / VI verifier attachment, and full `verify()` / `calculate()` paths including [§5.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract) degradation.
|
|
432
495
|
|
|
433
496
|
Run them with `pnpm --filter @atrib/verify test`.
|
|
434
497
|
|
|
@@ -457,3 +520,7 @@ The full protocol spec is at [`atrib-spec.md`](https://github.com/creatornader/a
|
|
|
457
520
|
---
|
|
458
521
|
|
|
459
522
|
> **A note on documentation links.** The atrib protocol repository is currently private (in-progress public preparation). Links in this README to the spec and sister packages (`atrib-spec.md`, `packages/agent/README.md`, etc.) point at `github.com/creatornader/atrib/blob/main/...` URLs that will resolve once the repository goes public. Until then, see [`atrib.dev`](https://atrib.dev) for the protocol overview.
|
|
523
|
+
|
|
524
|
+
## Part of atrib
|
|
525
|
+
|
|
526
|
+
atrib is an open protocol for verifiable agent actions. Every action becomes a signed, chain-linked record that anyone can verify against a public Merkle log, with no operator to trust. This package is one entrypoint. See the [full package family](https://github.com/creatornader/atrib#packages) and the [protocol spec](https://github.com/creatornader/atrib/blob/main/atrib-spec.md).
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
/** §2.11.10 domain-separation prefix for the anchoring-claim artifact. */
|
|
2
|
+
export declare const ANCHOR_CLAIM_PREFIX = "atrib-anchor/v1:";
|
|
3
|
+
/** Registered non-atrib-log anchor types per the §2.11.8 v1 registry. */
|
|
4
|
+
export declare const REGISTERED_NON_LOG_ANCHOR_TYPES: ReadonlySet<string>;
|
|
5
|
+
/**
|
|
6
|
+
* One `log_proofs` element. Legacy elements (absent `anchor_type`) carry
|
|
7
|
+
* the atrib-log triple; discriminated elements carry `anchor_id` + `proof`.
|
|
8
|
+
* The corpus additionally carries `log_index` and `entry_bytes_b64` on
|
|
9
|
+
* atrib-log elements so the inclusion proof and the §2.11.4 step-4 leaf
|
|
10
|
+
* comparison are independently checkable.
|
|
11
|
+
*/
|
|
12
|
+
export interface AnchorProofElement {
|
|
13
|
+
anchor_type?: string;
|
|
14
|
+
anchor_id?: string;
|
|
15
|
+
proof?: Record<string, unknown>;
|
|
16
|
+
log_id?: string;
|
|
17
|
+
log_index?: number;
|
|
18
|
+
checkpoint?: string;
|
|
19
|
+
inclusion_proof?: string[];
|
|
20
|
+
entry_bytes_b64?: string;
|
|
21
|
+
}
|
|
22
|
+
/** A proof bundle whose `log_proofs` array is the wire shape for all anchors. */
|
|
23
|
+
export interface AnchorProofBundle {
|
|
24
|
+
record_hash: string;
|
|
25
|
+
log_proofs: AnchorProofElement[];
|
|
26
|
+
}
|
|
27
|
+
/** Trust material for one log-shaped anchor (atrib log or Rekor instance). */
|
|
28
|
+
export interface AnchorTrustEntry {
|
|
29
|
+
/** §2.4 origin string the checkpoint's first line must match. */
|
|
30
|
+
origin: string;
|
|
31
|
+
/** The anchor service's Ed25519 public key, standard base64. */
|
|
32
|
+
pubkey_b64: string;
|
|
33
|
+
}
|
|
34
|
+
/** Declared operator grouping for independence counting (§2.11.11). */
|
|
35
|
+
export interface AnchorOperatorGroup {
|
|
36
|
+
group: string;
|
|
37
|
+
members: Array<{
|
|
38
|
+
anchor_type: string;
|
|
39
|
+
anchor_id: string;
|
|
40
|
+
}>;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Verifier trust configuration. `trust_material` maps anchor identities to
|
|
44
|
+
* their published keys; `trusted_logs` and `threshold_m` drive the
|
|
45
|
+
* unchanged §2.11.4 hard conditions; `required_anchors` (default 2) drives
|
|
46
|
+
* the §2.11.11 `plurality_met` tier; `operator_groups` declares operator
|
|
47
|
+
* identity for independence counting (default: one group per distinct
|
|
48
|
+
* `(anchor_type, anchor_id)` pair).
|
|
49
|
+
*/
|
|
50
|
+
export interface AnchorTrustConfig {
|
|
51
|
+
trust_material: {
|
|
52
|
+
logs: Record<string, AnchorTrustEntry>;
|
|
53
|
+
rekor?: Record<string, AnchorTrustEntry>;
|
|
54
|
+
};
|
|
55
|
+
trusted_logs?: string[];
|
|
56
|
+
threshold_m?: number;
|
|
57
|
+
required_anchors?: number;
|
|
58
|
+
operator_groups?: AnchorOperatorGroup[];
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* A "record not found" response from a trusted log inside the bundle's
|
|
62
|
+
* epoch window — the censorship-shaped equivocation input of §2.11.4.
|
|
63
|
+
*/
|
|
64
|
+
export interface AnchorNotFoundResponse {
|
|
65
|
+
log_id: string;
|
|
66
|
+
status: string;
|
|
67
|
+
epoch_window_ms: [number, number];
|
|
68
|
+
}
|
|
69
|
+
/** The §2.11.11 `anchor_plurality` annotation, exact field set. */
|
|
70
|
+
export interface AnchorPluralityAnnotation {
|
|
71
|
+
proof_count: number;
|
|
72
|
+
verified_count: number;
|
|
73
|
+
pending_count: number;
|
|
74
|
+
malformed_count: number;
|
|
75
|
+
unknown_types: string[];
|
|
76
|
+
independent_count: number;
|
|
77
|
+
plurality_met: boolean;
|
|
78
|
+
single_anchor: boolean;
|
|
79
|
+
equivocation_detected: boolean;
|
|
80
|
+
anchored_at_range_ms: [number, number] | null;
|
|
81
|
+
}
|
|
82
|
+
/** The disagreeing pair surfaced on §2.11.4 equivocation detection. */
|
|
83
|
+
export interface AnchorDisagreeingPair {
|
|
84
|
+
log_id_a: string;
|
|
85
|
+
leaf_hash_a_hex: string;
|
|
86
|
+
log_id_b: string;
|
|
87
|
+
leaf_hash_b_hex: string;
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* Full verifier verdict: the `anchor_plurality` annotation plus the
|
|
91
|
+
* unchanged §2.11.4 hard-condition facts. `hard_reject` is true only for
|
|
92
|
+
* the §2.11.4 conditions; `single_anchor` is a tier, never a failure.
|
|
93
|
+
*/
|
|
94
|
+
export interface AnchorPluralityVerdict {
|
|
95
|
+
anchor_plurality: AnchorPluralityAnnotation;
|
|
96
|
+
malformed_indices: number[];
|
|
97
|
+
invalid_indices: number[];
|
|
98
|
+
trusted_verified_count: number;
|
|
99
|
+
cross_log_threshold_not_met: boolean;
|
|
100
|
+
cross_log_equivocation_detected: boolean;
|
|
101
|
+
cross_log_censorship_suspected: boolean;
|
|
102
|
+
silent_log: string | null;
|
|
103
|
+
untrusted_surfaced: string[];
|
|
104
|
+
disagreeing_pair: AnchorDisagreeingPair | null;
|
|
105
|
+
hard_reject: boolean;
|
|
106
|
+
}
|
|
107
|
+
/** Per-element verification status. */
|
|
108
|
+
export type AnchorElementStatus = 'verified' | 'pending' | 'invalid' | 'malformed' | 'unknown';
|
|
109
|
+
/** Per-element verification result (exported for unit-level assertions). */
|
|
110
|
+
export interface AnchorElementResult {
|
|
111
|
+
status: AnchorElementStatus;
|
|
112
|
+
anchorType: string;
|
|
113
|
+
anchorId: string;
|
|
114
|
+
attestedTimeMs: number | null;
|
|
115
|
+
/** Committed entry bytes (atrib-log elements only), for §2.11.4 step 4. */
|
|
116
|
+
entryBytesB64: string | null;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Verify one `log_proofs` element against the bundle's `record_hash` and
|
|
120
|
+
* the caller's trust material. Pure: no network, no clock, no randomness.
|
|
121
|
+
* Never throws; unexpected failures surface as `invalid` (§5.8).
|
|
122
|
+
*/
|
|
123
|
+
export declare function verifyAnchorProofElement(el: AnchorProofElement, recordHash: string, trust: AnchorTrustConfig): Promise<AnchorElementResult>;
|
|
124
|
+
/**
|
|
125
|
+
* Operator-group key for independence counting (§2.11.11): the declared
|
|
126
|
+
* group when the trust config names one, else one group per distinct
|
|
127
|
+
* `(anchor_type, anchor_id)` pair (the default grouping).
|
|
128
|
+
*/
|
|
129
|
+
export declare function anchorOperatorGroup(anchorType: string, anchorId: string, trust: AnchorTrustConfig): string;
|
|
130
|
+
/**
|
|
131
|
+
* Compute the `anchor_plurality` annotation and the unchanged §2.11.4 hard
|
|
132
|
+
* conditions for a proof bundle. Deterministic: identical bundle + trust
|
|
133
|
+
* config + not-found responses in, identical verdict out. Never throws;
|
|
134
|
+
* a structurally hopeless bundle degrades to zero counts (§5.8).
|
|
135
|
+
*
|
|
136
|
+
* `single_anchor: true` is a TIER: the record stays valid, `hard_reject`
|
|
137
|
+
* stays false. Hard rejection is reserved for `cross_log_threshold_not_met`
|
|
138
|
+
* and `cross_log_equivocation_detected`; `cross_log_censorship_suspected`
|
|
139
|
+
* is a flag, not a rejection.
|
|
140
|
+
*/
|
|
141
|
+
export declare function verifyAnchorPlurality(bundle: AnchorProofBundle, trust: AnchorTrustConfig, notFoundResponses?: AnchorNotFoundResponse[]): Promise<AnchorPluralityVerdict>;
|
|
142
|
+
//# sourceMappingURL=anchor-plurality.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"anchor-plurality.d.ts","sourceRoot":"","sources":["../src/anchor-plurality.ts"],"names":[],"mappings":"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"}
|