nostr-attestations 0.0.0-development

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheCryptoDonkey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# nostr-attestations
+
+One Nostr event kind for all attestations — credentials, endorsements, vouches, provenance, licensing, and trust.
+
+## Install
+
+```
+npm install nostr-attestations
+```
+
+## Quick Start
+
+```typescript
+import { createAttestation, TYPES } from 'nostr-attestations'
+
+// Create an unsigned attestation event template
+const event = createAttestation({
+  type: TYPES.CREDENTIAL,
+  identifier: '<subject-pubkey>',
+  subject: '<subject-pubkey>',
+  summary: 'Professional credential verified',
+  expiration: 1735689600,
+  tags: [['profession', 'attorney'], ['jurisdiction', 'US-NY']],
+  content: JSON.stringify({ proof: '...' }),
+})
+// => { kind: 31000, tags: [...], content: '...' }
+// Sign with your preferred library and publish to relays
+```
+
+No relay client, no signing library, no crypto. Bring your own. Works with nostr-tools, any Nostr SDK, or bare WebSocket code.
+
+## Why This?
+
+Nostr has several ways to label or badge identities, but none designed for verifiable attestations. [NIP-58](https://github.com/nostr-protocol/nips/blob/master/58.md) badges are display-only — no expiry, no revocation, no structured claims. [NIP-85](https://github.com/nostr-protocol/nips/blob/master/85.md) covers social graph metrics, not arbitrary claims. [NIP-32](https://github.com/nostr-protocol/nips/blob/master/32.md) labels are lightweight but not individually replaceable per subject.
+
+nostr-attestations uses **one kind (31000) with a `type` tag** instead of inventing a new event kind for every attestation use case. Credentials, endorsements, vouches, licensing, provenance, and revocations all share the same event structure. New attestation types need zero protocol changes — just define a new `type` value.
+
+## Revocation
+
+```typescript
+import { createRevocation, isRevoked, parseAttestation } from 'nostr-attestations'
+
+// Revoke a previously issued attestation
+const revocation = createRevocation({
+  type: 'credential',
+  identifier: '<subject-pubkey>',
+  subject: '<subject-pubkey>',
+  reason: 'licence-expired',
+  effective: 1704067200,
+})
+// Publish — addressable event semantics replace the original
+
+// Check if a fetched event is revoked
+const revoked = isRevoked(event) // true if ["status", "revoked"] tag present
+```
+
+## Parsing
+
+```typescript
+import { parseAttestation } from 'nostr-attestations'
+
+const attestation = parseAttestation(event)
+// {
+//   kind: 31000,
+//   type: 'credential',
+//   pubkey: '<attestor-pubkey>',
+//   createdAt: 1700000000,
+//   identifier: '<subject-pubkey>',
+//   subject: '<subject-pubkey>',
+//   summary: 'Professional credential verified',
+//   expiration: 1735689600,
+//   revoked: false,
+//   reason: null,
+//   tags: [...],
+//   content: '...',
+// }
+```
+
+## API Reference
+
+### Builders
+
+| Function | Signature | Returns |
+|----------|-----------|---------|
+| `createAttestation` | `(params: AttestationParams) => EventTemplate` | Unsigned attestation event |
+| `createRevocation` | `(params: RevocationParams) => EventTemplate` | Unsigned revocation event |
+
+### Parsers
+
+| Function | Signature | Returns |
+|----------|-----------|---------|
+| `parseAttestation` | `(event: NostrEvent) => Attestation` | Typed attestation data |
+| `isRevoked` | `(event: NostrEvent) => boolean` | True if event has `["status", "revoked"]` |
+
+### Validators
+
+| Function | Signature | Returns |
+|----------|-----------|---------|
+| `validateAttestation` | `(event: NostrEvent) => ValidationResult` | `{ valid: boolean, errors: string[] }` |
+
+### Filters
+
+| Function | Signature | Returns |
+|----------|-----------|---------|
+| `attestationFilter` | `(params: FilterParams) => NostrFilter` | Relay query filter |
+| `revocationFilter` | `(type: string, identifier: string) => NostrFilter` | Revocation check filter |
+| `buildDTag` | `(type: string, identifier: string) => string` | `"type:identifier"` string |
+| `parseDTag` | `(dTag: string) => { type: string; identifier: string } \| null` | Parsed d-tag |
+
+### Constants
+
+| Export | Value | Description |
+|--------|-------|-------------|
+| `ATTESTATION_KIND` | `31000` | NIP-VA event kind |
+| `TYPES` | `{ CREDENTIAL, ENDORSEMENT, VOUCH, VERIFIER, PROVENANCE }` | Well-known type constants |
+
+### Types
+
+`AttestationParams`, `RevocationParams`, `Attestation`, `ValidationResult`, `FilterParams`, `NostrFilter`, `NostrEvent`, `EventTemplate` — all exported from the package root.
+
+## Test Vectors
+
+`vectors/attestations.json` contains 10 frozen conformance test vectors covering the full range of attestation types (credential, endorsement, vouch, verifier, provenance) and states (active, revoked, self-attestation). Any conformant implementation must produce identical parse results from these inputs. The vectors are pinned — if tests against them fail, the implementation is broken, not the vector.
+
+## NIP-VA
+
+Full protocol specification: [NIP-VA.md](./NIP-VA.md)
+
+## Licence
+
+MIT

package/dist/builders.d.ts

@@ -0,0 +1,12 @@
+import type { AttestationParams, RevocationParams, EventTemplate } from './types.js';
+/**
+ * Create an unsigned attestation event template.
+ * The caller is responsible for signing (adding pubkey, id, sig, created_at).
+ */
+export declare function createAttestation(params: AttestationParams): EventTemplate;
+/**
+ * Create an unsigned revocation event template.
+ * When published, this replaces the original attestation via addressable event semantics.
+ */
+export declare function createRevocation(params: RevocationParams): EventTemplate;
+//# sourceMappingURL=builders.d.ts.map

package/dist/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAEpF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,aAAa,CAwC1E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,aAAa,CAyBxE"}

package/dist/builders.js

@@ -0,0 +1,71 @@
+import { ATTESTATION_KIND } from './constants.js';
+import { buildDTag } from './filters.js';
+/**
+ * Create an unsigned attestation event template.
+ * The caller is responsible for signing (adding pubkey, id, sig, created_at).
+ */
+export function createAttestation(params) {
+    if (!params.type)
+        throw new Error('type must not be empty');
+    if (params.type.includes(':'))
+        throw new Error('type must not contain colons');
+    const tags = [];
+    // d-tag: type:identifier, or type:subject if no identifier, or just type
+    const identifier = params.identifier ?? params.subject;
+    if (identifier) {
+        tags.push(['d', buildDTag(params.type, identifier)]);
+    }
+    else {
+        tags.push(['d', params.type]);
+    }
+    tags.push(['type', params.type]);
+    if (params.subject) {
+        tags.push(['p', params.subject]);
+    }
+    if (params.summary) {
+        tags.push(['summary', params.summary]);
+    }
+    if (params.expiration != null) {
+        if (!Number.isFinite(params.expiration))
+            throw new Error('expiration must be a finite number');
+        tags.push(['expiration', String(params.expiration)]);
+    }
+    if (params.tags) {
+        for (const tag of params.tags) {
+            tags.push(tag);
+        }
+    }
+    return {
+        kind: ATTESTATION_KIND,
+        tags,
+        content: params.content ?? '',
+    };
+}
+/**
+ * Create an unsigned revocation event template.
+ * When published, this replaces the original attestation via addressable event semantics.
+ */
+export function createRevocation(params) {
+    const tags = [
+        ['d', buildDTag(params.type, params.identifier)],
+        ['type', params.type],
+        ['status', 'revoked'],
+    ];
+    if (params.subject) {
+        tags.push(['p', params.subject]);
+    }
+    if (params.reason) {
+        tags.push(['reason', params.reason]);
+    }
+    if (params.effective != null) {
+        if (!Number.isFinite(params.effective))
+            throw new Error('effective must be a finite number');
+        tags.push(['effective', String(params.effective)]);
+    }
+    return {
+        kind: ATTESTATION_KIND,
+        tags,
+        content: '',
+    };
+}
+//# sourceMappingURL=builders.js.map

package/dist/builders.js.map

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

package/dist/constants.d.ts

@@ -0,0 +1,14 @@
+/** NIP-VA Verifiable Attestation event kind (addressable). */
+export declare const ATTESTATION_KIND: 31000;
+/**
+ * Well-known attestation type constants.
+ * Applications may define their own types beyond these.
+ */
+export declare const TYPES: {
+    readonly CREDENTIAL: "credential";
+    readonly ENDORSEMENT: "endorsement";
+    readonly VOUCH: "vouch";
+    readonly VERIFIER: "verifier";
+    readonly PROVENANCE: "provenance";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,EAAG,KAAc,CAAA;AAE9C;;;GAGG;AACH,eAAO,MAAM,KAAK;;;;;;CAMR,CAAA"}

package/dist/constants.js

@@ -0,0 +1,14 @@
+/** NIP-VA Verifiable Attestation event kind (addressable). */
+export const ATTESTATION_KIND = 31000;
+/**
+ * Well-known attestation type constants.
+ * Applications may define their own types beyond these.
+ */
+export const TYPES = {
+    CREDENTIAL: 'credential',
+    ENDORSEMENT: 'endorsement',
+    VOUCH: 'vouch',
+    VERIFIER: 'verifier',
+    PROVENANCE: 'provenance',
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAc,CAAA;AAE9C;;;GAGG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,UAAU,EAAE,YAAY;IACxB,WAAW,EAAE,aAAa;IAC1B,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,UAAU;IACpB,UAAU,EAAE,YAAY;CAChB,CAAA"}

package/dist/filters.d.ts

@@ -0,0 +1,19 @@
+import type { FilterParams, NostrFilter } from './types.js';
+/**
+ * Build a d-tag from type and identifier.
+ * Type values must not contain colons — the first colon is the delimiter.
+ */
+export declare function buildDTag(type: string, identifier: string): string;
+/**
+ * Parse a d-tag into type and identifier.
+ * Returns null if the d-tag does not contain a colon.
+ */
+export declare function parseDTag(dTag: string): {
+    type: string;
+    identifier: string;
+} | null;
+/** Build a Nostr relay filter for querying attestation events. */
+export declare function attestationFilter(params: FilterParams): NostrFilter;
+/** Build a Nostr relay filter for fetching the latest version of a specific attestation (for revocation checking). */
+export declare function revocationFilter(type: string, identifier: string): NostrFilter;
+//# sourceMappingURL=filters.d.ts.map

package/dist/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../src/filters.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE3D;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAIlE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAOnF;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAMnE;AAED,sHAAsH;AACtH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,CAK9E"}

package/dist/filters.js

@@ -0,0 +1,44 @@
+import { ATTESTATION_KIND } from './constants.js';
+/**
+ * Build a d-tag from type and identifier.
+ * Type values must not contain colons — the first colon is the delimiter.
+ */
+export function buildDTag(type, identifier) {
+    if (!type)
+        throw new Error('type must not be empty');
+    if (type.includes(':'))
+        throw new Error('type must not contain colons');
+    return `${type}:${identifier}`;
+}
+/**
+ * Parse a d-tag into type and identifier.
+ * Returns null if the d-tag does not contain a colon.
+ */
+export function parseDTag(dTag) {
+    const idx = dTag.indexOf(':');
+    if (idx <= 0)
+        return null;
+    return {
+        type: dTag.slice(0, idx),
+        identifier: dTag.slice(idx + 1),
+    };
+}
+/** Build a Nostr relay filter for querying attestation events. */
+export function attestationFilter(params) {
+    const filter = { kinds: [ATTESTATION_KIND] };
+    if (params.authors?.length)
+        filter.authors = params.authors;
+    if (params.subject)
+        filter['#p'] = [params.subject];
+    if (params.type)
+        filter['#type'] = [params.type];
+    return filter;
+}
+/** Build a Nostr relay filter for fetching the latest version of a specific attestation (for revocation checking). */
+export function revocationFilter(type, identifier) {
+    return {
+        kinds: [ATTESTATION_KIND],
+        '#d': [buildDTag(type, identifier)],
+    };
+}
+//# sourceMappingURL=filters.js.map

package/dist/filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.js","sourceRoot":"","sources":["../src/filters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAGjD;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,UAAkB;IACxD,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAA;IACpD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAA;IACvE,OAAO,GAAG,IAAI,IAAI,UAAU,EAAE,CAAA;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC7B,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IACzB,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QACxB,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC;KAChC,CAAA;AACH,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,iBAAiB,CAAC,MAAoB;IACpD,MAAM,MAAM,GAAgB,EAAE,KAAK,EAAE,CAAC,gBAAgB,CAAC,EAAE,CAAA;IACzD,IAAI,MAAM,CAAC,OAAO,EAAE,MAAM;QAAE,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;IAC3D,IAAI,MAAM,CAAC,OAAO;QAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACnD,IAAI,MAAM,CAAC,IAAI;QAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAChD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,sHAAsH;AACtH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,UAAkB;IAC/D,OAAO;QACL,KAAK,EAAE,CAAC,gBAAgB,CAAC;QACzB,IAAI,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;KACpC,CAAA;AACH,CAAC"}

package/dist/helpers.d.ts

@@ -0,0 +1,3 @@
+/** Find the first tag with the given name. Internal helper — not part of the public API. */
+export declare function findTag(tags: string[][], name: string): string | null;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGrE"}

package/dist/helpers.js

@@ -0,0 +1,6 @@
+/** Find the first tag with the given name. Internal helper — not part of the public API. */
+export function findTag(tags, name) {
+    const tag = tags.find(t => t[0] === name);
+    return tag?.[1] ?? null;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,MAAM,UAAU,OAAO,CAAC,IAAgB,EAAE,IAAY;IACpD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAA;IACzC,OAAO,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAA;AACzB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { ATTESTATION_KIND, TYPES } from './constants.js';
+export { createAttestation, createRevocation } from './builders.js';
+export { parseAttestation, isRevoked } from './parsers.js';
+export { validateAttestation } from './validators.js';
+export { buildDTag, parseDTag, attestationFilter, revocationFilter } from './filters.js';
+export type { AttestationParams, RevocationParams, Attestation, ValidationResult, FilterParams, NostrFilter, NostrEvent, EventTemplate, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAExD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEnE,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAE1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAExF,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { ATTESTATION_KIND, TYPES } from './constants.js';
+export { createAttestation, createRevocation } from './builders.js';
+export { parseAttestation, isRevoked } from './parsers.js';
+export { validateAttestation } from './validators.js';
+export { buildDTag, parseDTag, attestationFilter, revocationFilter } from './filters.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAExD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEnE,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAE1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA"}

package/dist/parsers.d.ts

@@ -0,0 +1,12 @@
+import type { NostrEvent, Attestation } from './types.js';
+/**
+ * Parse a NostrEvent into a typed Attestation.
+ * Returns null if the event is not a valid kind 31000 attestation.
+ */
+export declare function parseAttestation(event: NostrEvent): Attestation | null;
+/**
+ * Check whether a NostrEvent is a revoked attestation.
+ * Returns false for non-attestation events.
+ */
+export declare function isRevoked(event: NostrEvent): boolean;
+//# sourceMappingURL=parsers.d.ts.map

package/dist/parsers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsers.d.ts","sourceRoot":"","sources":["../src/parsers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAEzD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAyBtE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAGpD"}

package/dist/parsers.js

@@ -0,0 +1,41 @@
+import { ATTESTATION_KIND } from './constants.js';
+import { findTag } from './helpers.js';
+import { parseDTag } from './filters.js';
+/**
+ * Parse a NostrEvent into a typed Attestation.
+ * Returns null if the event is not a valid kind 31000 attestation.
+ */
+export function parseAttestation(event) {
+    if (event.kind !== ATTESTATION_KIND)
+        return null;
+    const type = findTag(event.tags, 'type');
+    if (!type)
+        return null;
+    const dTag = findTag(event.tags, 'd');
+    const parsed = dTag ? parseDTag(dTag) : null;
+    const expirationStr = findTag(event.tags, 'expiration');
+    return {
+        kind: ATTESTATION_KIND,
+        type,
+        pubkey: event.pubkey,
+        createdAt: event.created_at,
+        identifier: parsed?.identifier ?? null,
+        subject: findTag(event.tags, 'p'),
+        summary: findTag(event.tags, 'summary'),
+        expiration: expirationStr ? Number(expirationStr) : null,
+        revoked: findTag(event.tags, 'status') === 'revoked',
+        reason: findTag(event.tags, 'reason'),
+        tags: event.tags,
+        content: event.content,
+    };
+}
+/**
+ * Check whether a NostrEvent is a revoked attestation.
+ * Returns false for non-attestation events.
+ */
+export function isRevoked(event) {
+    if (event.kind !== ATTESTATION_KIND)
+        return false;
+    return findTag(event.tags, 'status') === 'revoked';
+}
+//# sourceMappingURL=parsers.js.map

package/dist/parsers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsers.js","sourceRoot":"","sources":["../src/parsers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAGxC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAiB;IAChD,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB;QAAE,OAAO,IAAI,CAAA;IAEhD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACxC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IAEtB,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IACrC,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAE5C,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;IAEvD,OAAO;QACL,IAAI,EAAE,gBAAyB;QAC/B,IAAI;QACJ,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,SAAS,EAAE,KAAK,CAAC,UAAU;QAC3B,UAAU,EAAE,MAAM,EAAE,UAAU,IAAI,IAAI;QACtC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC;QACjC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC;QACvC,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI;QACxD,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,KAAK,SAAS;QACpD,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC;QACrC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAiB;IACzC,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB;QAAE,OAAO,KAAK,CAAA;IACjD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,KAAK,SAAS,CAAA;AACpD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,90 @@
+/** Unsigned event template returned by builders. */
+export interface EventTemplate {
+    kind: number;
+    tags: string[][];
+    content: string;
+    created_at?: number;
+}
+/** Signed Nostr event consumed by parsers and validators. */
+export interface NostrEvent {
+    kind: number;
+    pubkey: string;
+    created_at: number;
+    tags: string[][];
+    content: string;
+    id: string;
+    sig: string;
+}
+/** Parameters for creating an attestation event. */
+export interface AttestationParams {
+    /** Application-defined attestation type (must not contain colons). */
+    type: string;
+    /** D-tag second segment: hex pubkey or context string. */
+    identifier?: string;
+    /** P-tag: hex pubkey of the subject (for third-party attestations). */
+    subject?: string;
+    /** Human-readable fallback for clients that do not understand the type. */
+    summary?: string;
+    /** Unix timestamp for attestation expiry (NIP-40). */
+    expiration?: number;
+    /** Additional application-specific tags. */
+    tags?: string[][];
+    /** Event content: empty string, human-readable text, or JSON. */
+    content?: string;
+}
+/** Parameters for creating a revocation event. */
+export interface RevocationParams {
+    /** Type of the attestation being revoked. */
+    type: string;
+    /** D-tag second segment — must match the original attestation. */
+    identifier: string;
+    /** P-tag — include if the original attestation had one. */
+    subject?: string;
+    /** Human-readable revocation reason. */
+    reason?: string;
+    /** Unix timestamp for when the revocation takes effect. */
+    effective?: number;
+}
+/** Parsed attestation data extracted from a NostrEvent. */
+export interface Attestation {
+    kind: 31000;
+    type: string;
+    /** Attestor's pubkey (from outer event). */
+    pubkey: string;
+    /** Event timestamp (from outer event). */
+    createdAt: number;
+    /** D-tag second segment (pubkey or context string). */
+    identifier: string | null;
+    /** P-tag value (hex pubkey of subject, if present). */
+    subject: string | null;
+    summary: string | null;
+    expiration: number | null;
+    revoked: boolean;
+    reason: string | null;
+    /** All tags from the original event (for application-specific access). */
+    tags: string[][];
+    content: string;
+}
+/** Result of structural validation. */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/** Parameters for building a Nostr relay filter. */
+export interface FilterParams {
+    /** Filter by attestation type (uses type tag). */
+    type?: string;
+    /** Filter by subject pubkey (p-tag). */
+    subject?: string;
+    /** Filter by attestor pubkeys. */
+    authors?: string[];
+}
+/** Nostr relay filter object. */
+export interface NostrFilter {
+    kinds: number[];
+    authors?: string[];
+    '#p'?: string[];
+    '#d'?: string[];
+    '#type'?: string[];
+}
+//# 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":"AAAA,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,CAAA;IACjB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAA;IAClB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,KAAK,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,uDAAuD;IACvD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,iCAAiC;AACjC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/validators.d.ts

@@ -0,0 +1,7 @@
+import type { NostrEvent, ValidationResult } from './types.js';
+/**
+ * Validate structural correctness of a Nostr event as a kind 31000 attestation.
+ * Does not verify signatures or check relay state.
+ */
+export declare function validateAttestation(event: NostrEvent): ValidationResult;
+//# sourceMappingURL=validators.d.ts.map

package/dist/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE9D;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,gBAAgB,CAgCvE"}

package/dist/validators.js

@@ -0,0 +1,37 @@
+import { ATTESTATION_KIND } from './constants.js';
+import { findTag } from './helpers.js';
+/**
+ * Validate structural correctness of a Nostr event as a kind 31000 attestation.
+ * Does not verify signatures or check relay state.
+ */
+export function validateAttestation(event) {
+    const errors = [];
+    if (event.kind !== ATTESTATION_KIND) {
+        errors.push('kind must be 31000');
+    }
+    const dTag = findTag(event.tags, 'd');
+    if (!dTag) {
+        errors.push('missing required d tag');
+    }
+    const type = findTag(event.tags, 'type');
+    if (type == null) {
+        errors.push('missing required type tag');
+    }
+    else if (!type.trim()) {
+        errors.push('type tag must not be empty');
+    }
+    else if (type.includes(':')) {
+        errors.push('type must not contain colons');
+    }
+    // d-tag must start with the type value (or equal it for self-attestations)
+    if (dTag && type && !type.includes(':')) {
+        if (dTag !== type && !dTag.startsWith(`${type}:`)) {
+            errors.push(`d tag must start with type value "${type}"`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+//# sourceMappingURL=validators.js.map

package/dist/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGtC;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAiB;IACnD,MAAM,MAAM,GAAa,EAAE,CAAA;IAE3B,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;QACpC,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAA;IACnC,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IACrC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAA;IACvC,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACxC,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACjB,MAAM,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;IAC1C,CAAC;SAAM,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAA;IAC3C,CAAC;SAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAA;IAC7C,CAAC;IAED,2EAA2E;IAC3E,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACxC,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC;YAClD,MAAM,CAAC,IAAI,CAAC,qCAAqC,IAAI,GAAG,CAAC,CAAA;QAC3D,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;QAC1B,MAAM;KACP,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "nostr-attestations",
+  "version": "0.0.0-development",
+  "description": "Builders, parsers, and validators for NIP-VA (kind 31000) Verifiable Attestation events on Nostr.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "LICENSE",
+    "vectors/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "homepage": "https://github.com/forgesworn/nostr-attestations",
+  "keywords": [
+    "nostr",
+    "attestation",
+    "credential",
+    "endorsement",
+    "verification",
+    "identity",
+    "nip",
+    "verifiable",
+    "trust",
+    "reputation",
+    "provenance",
+    "revocation",
+    "addressable-event",
+    "kind-31000",
+    "zero-dependency",
+    "typescript"
+  ],
+  "author": "forgesworn",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forgesworn/nostr-attestations.git"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "eslint": "^10.0.3",
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.57.0",
+    "vitest": "^4.1.0"
+  }
+}

package/vectors/attestations.json

@@ -0,0 +1,398 @@
+[
+  {
+    "name": "simple-credential",
+    "description": "Third-party credential attestation with expiration and profession tags",
+    "event": {
+      "kind": 31000,
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "created_at": 1700000000,
+      "tags": [
+        ["d", "credential:def456"],
+        ["type", "credential"],
+        ["p", "def456"],
+        ["expiration", "1735689600"],
+        ["summary", "Professional credential verified"],
+        ["profession", "attorney"],
+        ["jurisdiction", "US-NY"]
+      ],
+      "content": "{\"proof\":\"ring-sig-abc\"}",
+      "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "sig": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    "expected": {
+      "kind": 31000,
+      "type": "credential",
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "createdAt": 1700000000,
+      "identifier": "def456",
+      "subject": "def456",
+      "summary": "Professional credential verified",
+      "expiration": 1735689600,
+      "revoked": false,
+      "reason": null,
+      "tags": [
+        ["d", "credential:def456"],
+        ["type", "credential"],
+        ["p", "def456"],
+        ["expiration", "1735689600"],
+        ["summary", "Professional credential verified"],
+        ["profession", "attorney"],
+        ["jurisdiction", "US-NY"]
+      ],
+      "content": "{\"proof\":\"ring-sig-abc\"}"
+    },
+    "valid": true
+  },
+  {
+    "name": "self-attestation",
+    "description": "Verifier registration with no p tag — self-attestation",
+    "event": {
+      "kind": 31000,
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "created_at": 1700000000,
+      "tags": [
+        ["d", "verifier:notary"],
+        ["type", "verifier"],
+        ["summary", "Identity verification service"]
+      ],
+      "content": "",
+      "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "sig": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    "expected": {
+      "kind": 31000,
+      "type": "verifier",
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "createdAt": 1700000000,
+      "identifier": "notary",
+      "subject": null,
+      "summary": "Identity verification service",
+      "expiration": null,
+      "revoked": false,
+      "reason": null,
+      "tags": [
+        ["d", "verifier:notary"],
+        ["type", "verifier"],
+        ["summary", "Identity verification service"]
+      ],
+      "content": ""
+    },
+    "valid": true
+  },
+  {
+    "name": "endorsement-with-app-tags",
+    "description": "Endorsement with context and confidence application-specific tags",
+    "event": {
+      "kind": 31000,
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "created_at": 1700000000,
+      "tags": [
+        ["d", "endorsement:def456"],
+        ["type", "endorsement"],
+        ["p", "def456"],
+        ["summary", "Reliable provider"],
+        ["context", "plumbing"],
+        ["confidence", "high"]
+      ],
+      "content": "",
+      "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "sig": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    "expected": {
+      "kind": 31000,
+      "type": "endorsement",
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "createdAt": 1700000000,
+      "identifier": "def456",
+      "subject": "def456",
+      "summary": "Reliable provider",
+      "expiration": null,
+      "revoked": false,
+      "reason": null,
+      "tags": [
+        ["d", "endorsement:def456"],
+        ["type", "endorsement"],
+        ["p", "def456"],
+        ["summary", "Reliable provider"],
+        ["context", "plumbing"],
+        ["confidence", "high"]
+      ],
+      "content": ""
+    },
+    "valid": true
+  },
+  {
+    "name": "provenance-with-event-ref",
+    "description": "Provenance attestation with e tag referencing the original event",
+    "event": {
+      "kind": 31000,
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "created_at": 1700000000,
+      "tags": [
+        ["d", "provenance:evt123"],
+        ["type", "provenance"],
+        ["e", "evt123"],
+        ["summary", "Authenticity verified"],
+        ["origin", "Sheffield, UK"],
+        ["method", "physical-inspection"]
+      ],
+      "content": "{\"chain_of_custody\":[\"maker\",\"distributor\",\"retailer\"]}",
+      "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "sig": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    "expected": {
+      "kind": 31000,
+      "type": "provenance",
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "createdAt": 1700000000,
+      "identifier": "evt123",
+      "subject": null,
+      "summary": "Authenticity verified",
+      "expiration": null,
+      "revoked": false,
+      "reason": null,
+      "tags": [
+        ["d", "provenance:evt123"],
+        ["type", "provenance"],
+        ["e", "evt123"],
+        ["summary", "Authenticity verified"],
+        ["origin", "Sheffield, UK"],
+        ["method", "physical-inspection"]
+      ],
+      "content": "{\"chain_of_custody\":[\"maker\",\"distributor\",\"retailer\"]}"
+    },
+    "valid": true
+  },
+  {
+    "name": "revocation-with-reason",
+    "description": "Revoked credential with reason tag",
+    "event": {
+      "kind": 31000,
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "created_at": 1700000000,
+      "tags": [
+        ["d", "credential:def456"],
+        ["type", "credential"],
+        ["p", "def456"],
+        ["status", "revoked"],
+        ["reason", "license-expired"],
+        ["summary", "Credential revoked"]
+      ],
+      "content": "",
+      "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "sig": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    "expected": {
+      "kind": 31000,
+      "type": "credential",
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "createdAt": 1700000000,
+      "identifier": "def456",
+      "subject": "def456",
+      "summary": "Credential revoked",
+      "expiration": null,
+      "revoked": true,
+      "reason": "license-expired",
+      "tags": [
+        ["d", "credential:def456"],
+        ["type", "credential"],
+        ["p", "def456"],
+        ["status", "revoked"],
+        ["reason", "license-expired"],
+        ["summary", "Credential revoked"]
+      ],
+      "content": ""
+    },
+    "valid": true
+  },
+  {
+    "name": "revocation-with-effective",
+    "description": "Revocation with effective timestamp indicating when revocation takes effect",
+    "event": {
+      "kind": 31000,
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "created_at": 1700000000,
+      "tags": [
+        ["d", "credential:ghi789"],
+        ["type", "credential"],
+        ["p", "ghi789"],
+        ["status", "revoked"],
+        ["reason", "compromised"],
+        ["effective", "1704067200"]
+      ],
+      "content": "",
+      "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "sig": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    "expected": {
+      "kind": 31000,
+      "type": "credential",
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "createdAt": 1700000000,
+      "identifier": "ghi789",
+      "subject": "ghi789",
+      "summary": null,
+      "expiration": null,
+      "revoked": true,
+      "reason": "compromised",
+      "tags": [
+        ["d", "credential:ghi789"],
+        ["type", "credential"],
+        ["p", "ghi789"],
+        ["status", "revoked"],
+        ["reason", "compromised"],
+        ["effective", "1704067200"]
+      ],
+      "content": ""
+    },
+    "valid": true
+  },
+  {
+    "name": "attestation-with-expiration",
+    "description": "NIP-40 expiration tag parsed as a number",
+    "event": {
+      "kind": 31000,
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "created_at": 1700000000,
+      "tags": [
+        ["d", "vouch:def456"],
+        ["type", "vouch"],
+        ["p", "def456"],
+        ["expiration", "1735689600"]
+      ],
+      "content": "",
+      "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "sig": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    "expected": {
+      "kind": 31000,
+      "type": "vouch",
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "createdAt": 1700000000,
+      "identifier": "def456",
+      "subject": "def456",
+      "summary": null,
+      "expiration": 1735689600,
+      "revoked": false,
+      "reason": null,
+      "tags": [
+        ["d", "vouch:def456"],
+        ["type", "vouch"],
+        ["p", "def456"],
+        ["expiration", "1735689600"]
+      ],
+      "content": ""
+    },
+    "valid": true
+  },
+  {
+    "name": "attestation-with-labels",
+    "description": "NIP-32 L/l namespace label tags alongside standard attestation tags",
+    "event": {
+      "kind": 31000,
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "created_at": 1700000000,
+      "tags": [
+        ["d", "credential:def456"],
+        ["type", "credential"],
+        ["p", "def456"],
+        ["L", "example.com/identity"],
+        ["l", "verified", "example.com/identity"]
+      ],
+      "content": "",
+      "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "sig": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    "expected": {
+      "kind": 31000,
+      "type": "credential",
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "createdAt": 1700000000,
+      "identifier": "def456",
+      "subject": "def456",
+      "summary": null,
+      "expiration": null,
+      "revoked": false,
+      "reason": null,
+      "tags": [
+        ["d", "credential:def456"],
+        ["type", "credential"],
+        ["p", "def456"],
+        ["L", "example.com/identity"],
+        ["l", "verified", "example.com/identity"]
+      ],
+      "content": ""
+    },
+    "valid": true
+  },
+  {
+    "name": "minimal-attestation",
+    "description": "Only required tags — d tag has no colon so identifier is null",
+    "event": {
+      "kind": 31000,
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "created_at": 1700000000,
+      "tags": [
+        ["d", "credential"],
+        ["type", "credential"]
+      ],
+      "content": "",
+      "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "sig": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    "expected": {
+      "kind": 31000,
+      "type": "credential",
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "createdAt": 1700000000,
+      "identifier": null,
+      "subject": null,
+      "summary": null,
+      "expiration": null,
+      "revoked": false,
+      "reason": null,
+      "tags": [
+        ["d", "credential"],
+        ["type", "credential"]
+      ],
+      "content": ""
+    },
+    "valid": true
+  },
+  {
+    "name": "attestation-with-json-content",
+    "description": "Structured proof payload in content field",
+    "event": {
+      "kind": 31000,
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "created_at": 1700000000,
+      "tags": [
+        ["d", "credential:def456"],
+        ["type", "credential"],
+        ["p", "def456"]
+      ],
+      "content": "{\"signatures\":[{\"type\":\"schnorr\",\"value\":\"deadbeef\"}],\"merkle_root\":\"cafebabe\"}",
+      "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "sig": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    "expected": {
+      "kind": 31000,
+      "type": "credential",
+      "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "createdAt": 1700000000,
+      "identifier": "def456",
+      "subject": "def456",
+      "summary": null,
+      "expiration": null,
+      "revoked": false,
+      "reason": null,
+      "tags": [
+        ["d", "credential:def456"],
+        ["type", "credential"],
+        ["p", "def456"]
+      ],
+      "content": "{\"signatures\":[{\"type\":\"schnorr\",\"value\":\"deadbeef\"}],\"merkle_root\":\"cafebabe\"}"
+    },
+    "valid": true
+  }
+]