@atrib/verify 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Types for @atrib/verify. graph objects, policy documents,
+ * and settlement recommendation documents.
+ *
+ * Mirrors §3.5 (graph response schema) and §4.7 (recommendation document).
+ */
+/**
+ * Graph-layer event_type. Short labels for the three primitives the v1
+ * graph + calculation algorithm operate on, plus the catch-all `extension`
+ * for records carrying an event_type URI not in atrib normative set
+ * (extension URIs are graph nodes but are NOT participants in §3.2.4 edge
+ * derivation in v1; see spec §3.2.1).
+ *
+ * Records arriving at the graph builder carry an absolute URI in
+ * `record.event_type` per §1.2.4. The builder normalizes URIs to these
+ * short labels via `graphLabelFromEventTypeUri()`. Extension URIs are
+ * preserved verbatim on `GraphNode.event_type_uri` for graph clients that
+ * want the original URI.
+ */
+export type EventType = 'tool_call' | 'transaction' | 'observation' | 'directory_anchor' | 'annotation' | 'revision' | 'gap_node' | 'dangling_node' | 'extension';
+/**
+ * Map an attribution record's event_type URI to a graph-layer short label.
+ * Atrib normative URIs map to their canonical short label; everything else
+ * collapses to `'extension'` (the graph-layer opaque-typed category).
+ */
+export declare function graphLabelFromEventTypeUri(uri: string): EventType;
+/** An unsigned hop: a tool call with no attribution record in response (§1.6, §3.2.5). */
+export interface GapNode {
+    type: 'gap_node';
+    tool_url: string;
+    tool_name: string;
+    context_id: string;
+    timestamp: number;
+    signed: false;
+}
+export type EdgeType = 'CHAIN_PRECEDES' | 'SESSION_PRECEDES' | 'SESSION_PARALLEL' | 'CONVERGES_ON' | 'CROSS_SESSION' | 'INFORMED_BY' | 'PROVENANCE_OF' | 'ANNOTATES' | 'REVISES';
+export type VerificationState = 'unsigned' | 'signature_valid' | 'log_committed' | 'witnessed'
+/**
+ * Per spec §1.9.3: a record signed by a key that was retired before
+ * the record's log_index. The signature is still cryptographically
+ * valid, but the key was revoked at the moment of signing, so the
+ * record MUST NOT contribute to attribution calculations (§4.6).
+ * Verifiers carrying a revocation registry annotate records with this
+ * state when (creator_key, log_index) falls after a key_revocation.
+ */
+ | 'revoked_after_revocation';
+/** A node in the attribution graph (§3.5.2). */
+export interface GraphNode {
+    id: string;
+    event_type: EventType;
+    /**
+     * The original event_type URI from the underlying record (§1.2.4), or
+     * null for synthetic nodes (gap_node). Atrib normative URIs are present
+     * as their canonical strings; extension URIs are preserved verbatim.
+     * Graph clients that need to filter by URI rather than short label use
+     * this field.
+     */
+    event_type_uri: string | null;
+    content_id: string | null;
+    creator_key: string | null;
+    chain_root: string | null;
+    context_id: string;
+    timestamp: number;
+    log_index: number | null;
+    verification_state: VerificationState;
+    is_genesis: boolean;
+}
+/** An edge in the attribution graph (§3.5.3). */
+export interface GraphEdge {
+    type: EdgeType;
+    source: string;
+    target: string;
+    directed: boolean;
+    /**
+     * True when the edge target is a synthetic dangling node — the agent's
+     * declared informed_by or provenance_token reference did not resolve to a
+     * record in the resolved set. Per spec §3.2.4 steps 6 + 7, dangling
+     * references MUST be surfaced as edges (not silently dropped) so verifiers
+     * can see what the agent claimed even when the upstream isn't accessible.
+     * Only INFORMED_BY and PROVENANCE_OF edges can be dangling.
+     */
+    dangling?: boolean;
+    /**
+     * Optional reason annotation. Currently used by PROVENANCE_OF dangling
+     * edges with the value `"no_token_source_in_record_set"` per spec §3.2.4
+     * step 7.
+     */
+    reason?: string;
+}
+/** A graph response object (§3.5.1). */
+export interface GraphResponse {
+    spec_version: 'atrib/1.0';
+    context_id: string;
+    generated_at: number;
+    node_count: number;
+    edge_count: number;
+    has_transaction: boolean;
+    cross_session_count: number;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+export type DistributionMethod = 'proportional' | 'equal' | 'weighted';
+export interface EdgeWeights {
+    CHAIN_PRECEDES?: number;
+    SESSION_PRECEDES?: number;
+    SESSION_PARALLEL?: number;
+    CONVERGES_ON?: number;
+    CROSS_SESSION?: number;
+    unsigned?: number;
+}
+export type Modifier = {
+    type: 'temporal_decay';
+    half_life_ms: number;
+} | {
+    type: 'chain_depth_penalty';
+    penalty_per_level: number;
+} | {
+    type: 'call_count_boost';
+    multiplier_per_call: number;
+    cap: number;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+export interface PolicyConstraints {
+    minimum_share?: number;
+    maximum_share?: number;
+    minimum_own_share?: number;
+    maximum_total_share?: number;
+}
+/** A policy document (§4.2). */
+export interface PolicyDocument {
+    spec_version: 'atrib/1.0';
+    policy_id?: string;
+    role?: 'merchant' | 'creator' | 'default';
+    edge_weights?: EdgeWeights;
+    modifiers?: Modifier[];
+    distribution?: DistributionMethod;
+    constraints?: PolicyConstraints;
+}
+/** Minimal policy shape for creator policy entries. Accepts any spec_version. */
+export interface CreatorPolicySnapshot {
+    spec_version: string;
+    constraints?: {
+        minimum_share?: number;
+        maximum_share?: number;
+        minimum_own_share?: number;
+        maximum_total_share?: number;
+    };
+    [key: string]: unknown;
+}
+/** Creator policy entry in the session policy record (§4.5.3). */
+export interface CreatorPolicyEntry {
+    server_url: string;
+    policy_url: string;
+    status: 'compatible' | 'floor_scaled' | 'conflict_defaulted' | 'not_found';
+    /** The fetched policy document snapshot, if available. */
+    policy?: CreatorPolicySnapshot | undefined;
+}
+/** Session policy record (§4.5.3). Full record as created by the agent. */
+export interface SessionPolicyRecord {
+    spec_version: 'atrib/1.0';
+    record_id: string;
+    context_id: string;
+    created_at: number;
+    merchant_policy: string;
+    creator_policies: CreatorPolicyEntry[];
+    agreed_policy: string;
+    applied_constraints: {
+        minimum_floors: Record<string, number>;
+    };
+    warnings: string[];
+}
+/** A creator key → share fraction map. May contain "__unsigned__" sentinel. */
+export type Distribution = Record<string, number>;
+export interface RecommendationDocument {
+    spec_version: 'atrib/1.0';
+    document_type: 'settlement_recommendation';
+    context_id: string;
+    transaction_id: string;
+    policy_record_id: string;
+    graph_checkpoint: string;
+    graph_tree_size: number;
+    calculated_at: number;
+    calculated_by: string;
+    distribution: Distribution;
+    maximum_total_share: number | null;
+    warnings: string[];
+    signature: string;
+}
+/** Verification result for a recommendation document (§5.5.2). */
+export interface VerificationResult {
+    valid: boolean;
+    signatureOk: boolean;
+    calcMatch: boolean;
+    distribution: Distribution;
+    warnings: string[];
+    graph_node_count: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Map an attribution record's event_type URI to a graph-layer short label.
+ * Atrib normative URIs map to their canonical short label; everything else
+ * collapses to `'extension'` (the graph-layer opaque-typed category).
+ */
+export function graphLabelFromEventTypeUri(uri) {
+    switch (uri) {
+        case 'https://atrib.dev/v1/types/tool_call':
+            return 'tool_call';
+        case 'https://atrib.dev/v1/types/transaction':
+            return 'transaction';
+        case 'https://atrib.dev/v1/types/observation':
+            return 'observation';
+        case 'https://atrib.dev/v1/types/directory_anchor':
+            return 'directory_anchor';
+        case 'https://atrib.dev/v1/types/annotation':
+            return 'annotation';
+        case 'https://atrib.dev/v1/types/revision':
+            return 'revision';
+        default:
+            return 'extension';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AA4BtC;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,sCAAsC;YACzC,OAAO,WAAW,CAAA;QACpB,KAAK,wCAAwC;YAC3C,OAAO,aAAa,CAAA;QACtB,KAAK,wCAAwC;YAC3C,OAAO,aAAa,CAAA;QACtB,KAAK,6CAA6C;YAChD,OAAO,kBAAkB,CAAA;QAC3B,KAAK,uCAAuC;YAC1C,OAAO,YAAY,CAAA;QACrB,KAAK,qCAAqC;YACxC,OAAO,UAAU,CAAA;QACnB;YACE,OAAO,WAAW,CAAA;IACtB,CAAC;AACH,CAAC"}

package/dist/verifier.d.ts

@@ -0,0 +1,54 @@
+import type { PolicyDocument, RecommendationDocument, VerificationResult } from './types.js';
+/** Init options for AtribVerifier (§5.5.1). */
+export interface AtribVerifierOptions {
+    logEndpoint?: string;
+    graphEndpoint?: string;
+    resolveEndpoint?: string;
+    /** Base64url Ed25519 32-byte seed. Optional. verify() works without it. */
+    merchantKey?: string;
+}
+/** Options for post-hoc calculation (§5.5.3). */
+export interface CalculateOptions {
+    context_id: string;
+    /** A policy document, or "default" to use the §4.3 default policy. */
+    policy: PolicyDocument | 'default';
+    /** Whether to sign the result with merchantKey. */
+    signWith?: 'merchant';
+    /** Optional pin to a specific log tree size. */
+    treeSize?: number;
+}
+export declare class AtribVerifier {
+    private readonly logEndpoint;
+    private readonly graphEndpoint;
+    private readonly merchantPrivateKey;
+    constructor(options?: AtribVerifierOptions);
+    /**
+     * Verify a settlement recommendation (§5.5.2).
+     *
+     * Steps:
+     *   1. Verify Ed25519 signature using calculated_by's public key (looked up
+     *      via the resolve service when calculated_by is a known service URL,
+     *      or assumed to be the merchant key when calculated_by is "local").
+     *   2. Fetch the graph at graph_tree_size.
+     *   3. Fetch the session policy record (or use default if "default").
+     *   4. Run calculate() locally and compare distributions within 1e-9.
+     */
+    verify(doc: RecommendationDocument): Promise<VerificationResult>;
+    /**
+     * Post-hoc calculation when no agent SDK was present (§5.5.3).
+     *
+     * Always returns a recommendation document. If signWith === "merchant" but
+     * no merchantKey is set, the document is returned UNSIGNED with a warning
+     * (degradation contract §5.8: never throws due to a missing key).
+     */
+    calculate(options: CalculateOptions): Promise<RecommendationDocument>;
+    /**
+     * Resolve the public key for a `calculated_by` URL.
+     *
+     * For v1: only "local" (returns null. caller must supply key separately or
+     * accept signatureOk=false) and the well-known atrib resolve endpoint are
+     * supported. Future revisions may add a key directory.
+     */
+    private resolveCalculatedByPublicKey;
+}
+//# sourceMappingURL=verifier.d.ts.map

package/dist/verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../src/verifier.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EACV,cAAc,EACd,sBAAsB,EAEtB,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAMnB,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,MAAM,EAAE,cAAc,GAAG,SAAS,CAAA;IAClC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,UAAU,CAAA;IACrB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAmB;gBAE1C,OAAO,GAAE,oBAAyB;IAsB9C;;;;;;;;;;OAUG;IACG,MAAM,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAiEtE;;;;;;OAMG;IACG,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA2D3E;;;;;;OAMG;YACW,4BAA4B;CAuB3C"}

package/dist/verifier.js

@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * AtribVerifier. the merchant verification class (§5.5).
+ *
+ * Provides:
+ *   - verify(recommendationDoc) → independently reproduces calculation (§5.5.2)
+ *   - calculate({ context_id, policy, signWith }) → post-hoc calculation (§5.5.3)
+ *
+ * Per §5.8 degradation contract: never throws on missing keys, returns warnings instead.
+ */
+import { base64urlDecode } from '@atrib/mcp';
+import { calculate, DEFAULT_POLICY } from './calculate.js';
+import { fetchGraph, fetchSessionPolicyRecord, fetchPolicyDocument } from './graph-fetch.js';
+import { signRecommendation, verifyRecommendationSignature, distributionsMatch, } from './recommendation.js';
+const DEFAULT_LOG_ENDPOINT = 'https://log.atrib.dev/v1';
+const DEFAULT_GRAPH_ENDPOINT = 'https://graph.atrib.dev/v1';
+const DEFAULT_RESOLVE_ENDPOINT = 'https://resolve.atrib.dev/v1';
+export class AtribVerifier {
+    logEndpoint;
+    graphEndpoint;
+    merchantPrivateKey;
+    constructor(options = {}) {
+        this.logEndpoint = options.logEndpoint ?? DEFAULT_LOG_ENDPOINT;
+        this.graphEndpoint = options.graphEndpoint ?? DEFAULT_GRAPH_ENDPOINT;
+        // resolveEndpoint reserved for v2 remote-calculation API
+        void (options.resolveEndpoint ?? DEFAULT_RESOLVE_ENDPOINT);
+        let key = null;
+        if (options.merchantKey) {
+            try {
+                const decoded = base64urlDecode(options.merchantKey);
+                if (decoded.length === 32) {
+                    key = decoded;
+                }
+                else {
+                    console.warn('atrib: merchantKey must be 32 bytes; recommendations will be unsigned');
+                }
+            }
+            catch {
+                console.warn('atrib: failed to decode merchantKey; recommendations will be unsigned');
+            }
+        }
+        this.merchantPrivateKey = key;
+    }
+    /**
+     * Verify a settlement recommendation (§5.5.2).
+     *
+     * Steps:
+     *   1. Verify Ed25519 signature using calculated_by's public key (looked up
+     *      via the resolve service when calculated_by is a known service URL,
+     *      or assumed to be the merchant key when calculated_by is "local").
+     *   2. Fetch the graph at graph_tree_size.
+     *   3. Fetch the session policy record (or use default if "default").
+     *   4. Run calculate() locally and compare distributions within 1e-9.
+     */
+    async verify(doc) {
+        const warnings = [];
+        let signatureOk = false;
+        let calcMatch = false;
+        let localDistribution = doc.distribution;
+        let nodeCount = 0;
+        // Step 1: signature
+        try {
+            const pubKey = await this.resolveCalculatedByPublicKey(doc.calculated_by);
+            if (!pubKey) {
+                warnings.push(`unknown calculated_by; cannot verify signature: ${doc.calculated_by}`);
+            }
+            else {
+                signatureOk = await verifyRecommendationSignature(doc, pubKey);
+                if (!signatureOk)
+                    warnings.push('signature verification failed');
+            }
+        }
+        catch (err) {
+            warnings.push(`signature verification error: ${err.message}`);
+        }
+        // Step 2 & 3 & 4: re-run calculation
+        try {
+            const graph = await fetchGraph(this.graphEndpoint, doc.context_id, doc.graph_tree_size);
+            nodeCount = graph.node_count;
+            let policyRecord = null;
+            let policy = DEFAULT_POLICY;
+            if (doc.policy_record_id !== 'default') {
+                try {
+                    policyRecord = await fetchSessionPolicyRecord(this.graphEndpoint, doc.policy_record_id);
+                    if (policyRecord.agreed_policy && policyRecord.agreed_policy !== 'default') {
+                        try {
+                            policy = await fetchPolicyDocument(policyRecord.agreed_policy);
+                        }
+                        catch {
+                            warnings.push(`failed to fetch agreed policy ${policyRecord.agreed_policy}, falling back to default`);
+                        }
+                    }
+                }
+                catch {
+                    warnings.push(`failed to fetch session policy record ${doc.policy_record_id}, falling back to default`);
+                }
+            }
+            localDistribution = calculate(graph, policy, policyRecord);
+            calcMatch = distributionsMatch(localDistribution, doc.distribution);
+            if (!calcMatch) {
+                warnings.push('local recalculation does not match document distribution');
+            }
+        }
+        catch (err) {
+            warnings.push(`graph fetch or calculation error: ${err.message}`);
+        }
+        return {
+            valid: signatureOk && calcMatch,
+            signatureOk,
+            calcMatch,
+            distribution: localDistribution,
+            warnings,
+            graph_node_count: nodeCount,
+        };
+    }
+    /**
+     * Post-hoc calculation when no agent SDK was present (§5.5.3).
+     *
+     * Always returns a recommendation document. If signWith === "merchant" but
+     * no merchantKey is set, the document is returned UNSIGNED with a warning
+     * (degradation contract §5.8: never throws due to a missing key).
+     */
+    async calculate(options) {
+        const warnings = [];
+        const policy = options.policy === 'default' ? DEFAULT_POLICY : options.policy;
+        // graph_checkpoint records the log origin, not a full signed checkpoint.
+        // A full checkpoint would require fetching GET /v1/checkpoint from the log,
+        // which is not available in the post-hoc path. The origin string is
+        // sufficient for identifying which log the data came from.
+        const graphCheckpoint = this.logEndpoint;
+        let treeSize = options.treeSize ?? 0;
+        let distribution = {};
+        let transactionId = '';
+        let maxTotalShare = null;
+        try {
+            const graph = await fetchGraph(this.graphEndpoint, options.context_id, options.treeSize);
+            treeSize = options.treeSize ?? 0; // 0 = unpinned; caller should supply treeSize for reproducible verification
+            const txNode = graph.nodes.find((n) => n.event_type === 'transaction');
+            if (!txNode) {
+                warnings.push('no transaction node found in graph; distribution is empty');
+            }
+            else {
+                transactionId = txNode.id;
+            }
+            distribution = calculate(graph, policy, null);
+            maxTotalShare = policy.constraints?.maximum_total_share ?? null;
+        }
+        catch (err) {
+            warnings.push(`graph fetch or calculation error: ${err.message}`);
+        }
+        const unsigned = {
+            spec_version: 'atrib/1.0',
+            document_type: 'settlement_recommendation',
+            context_id: options.context_id,
+            transaction_id: transactionId,
+            policy_record_id: options.policy === 'default' ? 'default' : (policy.policy_id ?? 'default'),
+            graph_checkpoint: graphCheckpoint,
+            graph_tree_size: treeSize,
+            calculated_at: Date.now(),
+            calculated_by: 'local',
+            distribution,
+            maximum_total_share: maxTotalShare,
+            warnings,
+        };
+        if (options.signWith === 'merchant') {
+            if (!this.merchantPrivateKey) {
+                warnings.push('merchantKey not set. Recommendation unsigned');
+                return { ...unsigned, signature: '' };
+            }
+            try {
+                return await signRecommendation(unsigned, this.merchantPrivateKey);
+            }
+            catch (err) {
+                warnings.push(`signing failed: ${err.message}`);
+                return { ...unsigned, signature: '' };
+            }
+        }
+        return { ...unsigned, signature: '' };
+    }
+    /**
+     * Resolve the public key for a `calculated_by` URL.
+     *
+     * For v1: only "local" (returns null. caller must supply key separately or
+     * accept signatureOk=false) and the well-known atrib resolve endpoint are
+     * supported. Future revisions may add a key directory.
+     */
+    async resolveCalculatedByPublicKey(calculatedBy) {
+        if (calculatedBy === 'local') {
+            // For "local", the merchant signed it themselves. but we have no way
+            // to know which merchant. Caller would need to supply the public key
+            // out-of-band. Return null to surface this.
+            return null;
+        }
+        // atrib resolution service publishes its key at /pubkey.
+        // Validate hostname to prevent SSRF via crafted calculated_by URLs.
+        try {
+            const parsed = new URL(calculatedBy);
+            if (parsed.protocol !== 'https:' || parsed.hostname !== 'resolve.atrib.dev') {
+                return null;
+            }
+            const url = `${calculatedBy.replace(/\/$/, '')}/pubkey`;
+            const res = await fetch(url);
+            if (!res.ok)
+                return null;
+            const text = (await res.text()).trim();
+            return text;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=verifier.js.map

package/dist/verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.js","sourceRoot":"","sources":["../src/verifier.ts"],"names":[],"mappings":"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"}

package/dist/verify-record.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Per-record verification (single AtribRecord).
+ *
+ * Distinct from `AtribVerifier.verify(recommendationDoc)` which verifies a
+ * settlement recommendation document by re-running the §4.6 calculation.
+ * This module verifies one signed record at a time and surfaces the
+ * per-record annotations defined in the package README.
+ *
+ * Implemented annotations (this file):
+ *   - provenance:             { token, upstream_record_hash, upstream_resolved }    (D044 / §1.2.6)
+ *   - informed_by_resolution: { resolved: string[], dangling: string[] }            (D041 / §1.2.5, §3.2.4)
+ *   - posture:                { timestamp_granularity, timestamp_consistent }       (D045 / §8.4)
+ *
+ * Pending annotations (tracked in DECISIONS.md P005):
+ *   - capability_check:       D051 / §6.7  (needs @atrib/directory integration)
+ *   - cross_attestation:      D052 / §1.7.6  (needs `signers[]` type addition + transaction-record signing variant in @atrib/mcp)
+ *   - cross_log_*:            D050 / §2.11  (needs multi-log proof-bundle infrastructure)
+ *   - tool_name_form / args_commitment_form: §8.2 / §8.3  (needs tool_name + args_hash fields on the record shape — currently only content_id is exposed)
+ */
+import { base64urlDecode, type AtribRecord } from '@atrib/mcp';
+/**
+ * Provenance surfacing for a record carrying `provenance_token` (D044 /
+ * spec §1.2.6).
+ */
+export interface ProvenanceAnnotation {
+    token: string;
+    /**
+     * Full sha256:<64hex> record_hash of the upstream record, or null when
+     * no candidate was supplied or the candidate did not match.
+     */
+    upstream_record_hash: string | null;
+    /**
+     * True iff a candidate upstream record was supplied AND the first 16
+     * bytes of its canonical-form SHA-256 match the decoded token.
+     */
+    upstream_resolved: boolean;
+}
+/**
+ * Informed-by surfacing for a record carrying `informed_by[]` (D041 /
+ * spec §1.2.5). Splits the entries into resolved (caller supplied a
+ * candidate whose canonical-form SHA-256 matches the entry) and dangling
+ * (no candidate matched). Dangling references are flagged but do not
+ * fail verification — they're a signal that the verifier hasn't seen
+ * upstream context, not that the record is invalid.
+ */
+export interface InformedByAnnotation {
+    resolved: string[];
+    dangling: string[];
+}
+/**
+ * Posture surfacing for a record. Currently exposes only the timing
+ * posture (§8.4); tool_name_form (§8.2) and args_commitment_form (§8.3)
+ * require fields that aren't on the current AtribRecord shape.
+ *
+ * `timestamp_granularity` is the declared coarsening level (or 'ms' by
+ * default when absent). `timestamp_consistent` is true iff the timestamp
+ * value matches the granularity's trailing-zero invariant per spec §8.4
+ * (e.g., 'min' requires `timestamp % 60000 == 0`). A consistent posture
+ * means the record's coarsening claim is structurally honest; an
+ * inconsistent posture means the implementation declared a granularity
+ * that the timestamp doesn't satisfy, which validators and verifiers
+ * MUST reject per §8.4.
+ */
+export interface PostureAnnotation {
+    timestamp_granularity: 'ms' | 's' | 'min' | 'h' | 'd';
+    /**
+     * True iff the timestamp value matches the declared granularity's
+     * trailing-zero pattern. 'ms' is always consistent (no constraint).
+     */
+    timestamp_consistent: boolean;
+    /**
+     * True iff the granularity field was explicitly present on the record,
+     * false iff it defaulted to 'ms' because the field was absent.
+     * Surfaced separately because absence affects JCS canonical form per §1.3.
+     */
+    timestamp_granularity_explicit: boolean;
+}
+export interface RecordVerificationResult {
+    /** True iff signatureOk AND no fatal warnings. */
+    valid: boolean;
+    /** Ed25519 signature check over JCS-canonical bytes (§1.4.3). */
+    signatureOk: boolean;
+    /**
+     * Provenance annotation. Populated only when the record carries a
+     * `provenance_token` field. Genesis-record-only per spec §1.2.6;
+     * verifyRecord does NOT enforce that invariant here (it's the
+     * validator + verifier-of-the-chain's job per the spec) — callers that
+     * want the strict check should also confirm the record's chain_root
+     * equals genesisChainRoot(record.context_id).
+     */
+    provenance?: ProvenanceAnnotation;
+    /**
+     * Informed-by annotation. Populated only when the record carries a
+     * non-empty `informed_by[]`. `resolved` lists the entries that match
+     * a caller-supplied candidate; `dangling` lists the entries that did
+     * not match any candidate. With no candidates supplied, all entries
+     * land in `dangling` (verification continues regardless).
+     */
+    informed_by_resolution?: InformedByAnnotation;
+    /**
+     * Posture annotation. Always populated (every record has a timing
+     * posture, even if it defaults to 'ms'). Surfaces the declared
+     * granularity and whether the timestamp value structurally matches it.
+     */
+    posture: PostureAnnotation;
+    warnings: string[];
+}
+export interface VerifyRecordOptions {
+    /**
+     * Candidate upstream record for provenance_token resolution. If
+     * supplied and the candidate's canonical SHA-256[:16] matches the
+     * record's provenance_token, the verifier surfaces
+     * upstream_record_hash and sets upstream_resolved=true.
+     */
+    upstreamCandidate?: AtribRecord;
+    /**
+     * Candidate records for informed_by[] resolution. The verifier hashes
+     * each candidate (canonical form) and tries to match each
+     * informed_by entry against the candidate set. Entries that match a
+     * candidate land in `resolved`; entries that do not land in `dangling`.
+     * Pass an empty array (or omit) when the verifier has no upstream
+     * context — every entry will land in `dangling`, which is informational
+     * not invalidating.
+     */
+    informedByCandidates?: AtribRecord[];
+}
+/**
+ * Verify one signed record.
+ *
+ * Always returns a result; never throws. Per spec §5.8 graceful-
+ * degradation: invalid inputs (malformed signature, malformed
+ * provenance_token, etc.) are surfaced via warnings + signatureOk=false
+ * rather than thrown errors.
+ */
+export declare function verifyRecord(record: AtribRecord, options?: VerifyRecordOptions): Promise<RecordVerificationResult>;
+declare function resolveProvenance(token: string, upstreamCandidate: AtribRecord | undefined): ProvenanceAnnotation;
+declare function resolveInformedBy(entries: string[], candidates: AtribRecord[], warnings: string[]): InformedByAnnotation;
+declare function detectPosture(record: AtribRecord, warnings: string[]): PostureAnnotation;
+export declare const __test_only__: {
+    PROVENANCE_TOKEN_PATTERN: RegExp;
+    SHA256_REF_PATTERN: RegExp;
+    GRANULARITY_MULTIPLIER: Record<"s" | "ms" | "min" | "h" | "d", number>;
+    resolveProvenance: typeof resolveProvenance;
+    resolveInformedBy: typeof resolveInformedBy;
+    detectPosture: typeof detectPosture;
+    base64urlDecode: typeof base64urlDecode;
+};
+export {};
+//# sourceMappingURL=verify-record.d.ts.map