@x1id/resolve 0.7.0 → 0.8.0

package/README.md

@@ -204,6 +204,76 @@ one: `ResolveError { code: "not-found", reason: "nft-burned" }`. The registry
 account's stale `owner` field is never returned for a tokenized handle, on any
 path.
 
+## Per-platform verification ("verified by [platform]")
+
+Beyond the per-chain `verification` above, a handle can carry **per-platform
+verifications** — the blue-tick signal that a handle proved control of an X,
+Discord, GitHub, Telegram account or a domain (#7145). A resolver that supplies
+them (the tools/api REST `/resolve` response) attaches an optional
+`verifications[]` to the `Resolved` result:
+
+```ts
+import { isVerified, verifiedPlatforms, isVerifiedOn } from "@x1id/resolve";
+
+// `resolved` is a Resolved carrying the resolver's `verifications[]`, e.g.
+//   verifications: [
+//     { platform: "x",      value: "@michelle",    verified: true, attested_at: 1730000000 },
+//     { platform: "github", value: "michelle",     verified: true, attested_at: 1730000100 },
+//     { platform: "domain", value: "michelle.com", verified: true, attested_at: 1730000200 },
+//   ]
+
+isVerified(resolved);                 // true  — show the blue tick (any live signal)
+verifiedPlatforms(resolved);          // ["x", "github", "domain"]
+isVerifiedOn(resolved, "github");     // true
+isVerifiedOn(resolved, "telegram");   // false
+```
+
+**Rendering a badge.** Light the tick when `isVerified(resolved)` is true; on
+hover/focus, list `verifiedPlatforms(resolved)`, and pull each platform's
+account handle from the paired `value` (`@michelle` for `x`, `michelle.com` for
+`domain`). Platform slugs are `x` / `discord` / `github` / `telegram`, plus
+legacy `domain` (DNS) and `social` (pre-per-platform, no attribution).
+
+All three helpers are **absence-tolerant**: an older resolver, the SDK's own
+on-chain `resolve()` (which does not populate the field — see below), or a
+handle with no live verifications all yield `false` / `[]`, never a throw. The
+field is optional and additive, so existing `Resolved` consumers are unaffected.
+
+> **Honest trust caveat — read before you render.** A verification is an
+> **off-chain review** (a DNS lookup, an OAuth completion, a human check) that
+> x1id's **attestor key** signed off on. It is **not** a trustless proof: that
+> key is admin-rotatable, so the anchor is "whoever the registry admin currently
+> designates". Verifications are also **epoch-bound** — the resolver emits an
+> entry only while the underlying attestation is live (`attested_at >=
+> registered_at` **and** `>= records_cleared_at`), so a previous owner's proof
+> never leaks through. Render it as **"verified by x1id"**, never as more.
+
+### Reading verification straight from chain
+
+The SDK's own on-chain `resolve()` does **not** populate `verifications` (it
+returns only what an RPC read proves). To compute the same signal from chain,
+read the `Attestation` accounts directly — this applies the staleness rule
+structurally:
+
+```ts
+import {
+  fetchAttestations, liveAttestations, isHandleVerified,
+  platformSlug, textRecordKeyFor,
+} from "@x1id/resolve";
+
+const atts = await fetchAttestations(rpc, programId, handleAccount, registeredAt, recordsClearedAt);
+isHandleVerified(atts);                                  // the #7145 tick, from chain
+for (const a of liveAttestations(atts)) {
+  platformSlug(a.kind);       // "x" | "discord" | "github" | "telegram" | null (legacy)
+  textRecordKeyFor(a.kind);   // "com.x" | ... | "website" | null — where the value lives
+}
+```
+
+`platformSlug` / `textRecordKeyFor` mirror the on-chain
+`Attestation::platform_slug` and the shared contract table exactly, so an
+integrator joining a live attestation to its paired text record reads the same
+mapping the program, resolver and app badge use.
+
 ## What works today
 
 | | Status |
@@ -300,7 +370,7 @@ Also shipped, same build → sign → relay shape:
 | Typed text records (website / avatar / socials) | `buildCreateTextRecordIx`, `buildUpdateTextRecordIx`, `buildCloseTextRecordIx` |
 | Register a handle | `buildRegisterIx` (+ `fetchConfigTreasury`) |
 | Verify a non-SVM address record | `buildCreateRecordIx`, `buildVerifyRecordEthIx`, `buildVerifyRecordSvmIx`, `buildVerifyRecordBtcIx` (+ `buildRecordChallenge`, `splitEthSignature`, `splitBtcSignature`) — see [Verifying a non-SVM address record](#verifying-a-non-svm-address-record) |
-| Domain / social attestations | `buildCreateAttestationIx`, `buildCloseAttestationIx` (+ `fetchAttestations`, `isHandleVerified`) |
+| Domain / social / per-platform attestations | `buildCreateAttestationIx` (kinds 0–5), `buildCloseAttestationIx` (+ `fetchAttestations`, `isHandleVerified`, `platformSlug`, `textRecordKeyFor`) — see [Per-platform verification](#per-platform-verification-verified-by-platform) |
 | Agent records (identity, manifest, x402 hints) | `validateManifest`, `agentVerificationLevel`, `x402AcceptsFromManifest`, `agentTextRecords` — see [Agent records](#agent-records) below |
 | Subname records / revoke | `buildRevokeSubnameIx`, `buildCreateSubnameRecordIx`, `buildUpdateSubnameRecordIx`, `buildCloseSubnameRecordIx` |
 | Voucher claim / refund | `buildClaimVoucherIx`, `buildRefundVoucherIx` |

package/dist/attestation.d.ts

@@ -62,14 +62,35 @@
  */
 import type { AddressLike, BuiltInstruction } from "./delegate.js";
 import type { RpcFn } from "./accounts.js";
+import type { HandleVerification } from "./types.js";
 /** Seed prefix of an attestation PDA: `["attestation", handlePda, kindByte]`. */
 export declare const ATTESTATION_SEED = "attestation";
 /** Seed of the attestor-config singleton PDA: `["attestor_config"]`. */
 export declare const ATTESTOR_CONFIG_SEED = "attestor_config";
-/** `Attestation.kind` — domain control proven (DNS TXT challenge). */
+/** `Attestation.kind` — domain control proven (DNS TXT challenge). LEGACY-safe:
+ *  kept valid forever. Pairs with the `website` text record. */
 export declare const ATTESTATION_KIND_DNS = 0;
-/** `Attestation.kind` — social-account control proven. */
+/** `Attestation.kind` — generic social-account control proven. LEGACY: the
+ *  single pre-per-platform code, carrying no platform attribution. Kept valid
+ *  forever so existing accounts are never orphaned; new attestations should use
+ *  one of the per-platform codes below. */
 export declare const ATTESTATION_KIND_SOCIAL = 1;
+/** `Attestation.kind` — X (Twitter) control proven. Pairs with text record
+ *  `com.x`; platform slug `x`. */
+export declare const ATTESTATION_KIND_X = 2;
+/** `Attestation.kind` — Discord control proven. Pairs with text record
+ *  `com.discord`; platform slug `discord`. */
+export declare const ATTESTATION_KIND_DISCORD = 3;
+/** `Attestation.kind` — GitHub control proven. Pairs with text record
+ *  `com.github`; platform slug `github`. */
+export declare const ATTESTATION_KIND_GITHUB = 4;
+/** `Attestation.kind` — Telegram control proven. Pairs with text record
+ *  `org.telegram`; platform slug `telegram`. */
+export declare const ATTESTATION_KIND_TELEGRAM = 5;
+/** One past the highest valid `kind`. `create_attestation` refuses anything
+ *  `>=` this on-chain; the SDK's builder enforces the same bound. Mirrors
+ *  `Attestation::KIND_COUNT` (programs/x1-handles/src/state.rs). */
+export declare const ATTESTATION_KIND_COUNT = 6;
 /** Anchor account discriminator: `sha256("account:Attestation")[0..8]`.
  *  Pinned (this SDK is zero-dependency and cannot assume WebCrypto SHA-256
  *  everywhere it runs); asserted against a re-derivation in the test suite
@@ -90,19 +111,42 @@ export declare const CLOSE_ATTESTATION_DISCRIMINATOR: Uint8Array;
 export declare const ATTESTATION_LEN = 114;
 /** `AttestorConfig` account size: disc(8) + attestor(32) + bump(1). */
 export declare const ATTESTOR_CONFIG_LEN = 41;
+/** Human name an attestation `kind` byte carries. */
+export type AttestationKindName = "dns" | "social" | "x" | "discord" | "github" | "telegram";
 /** Which verification signal an attestation `kind` byte names, or null for a
- *  kind this SDK does not know (future program versions may add kinds). */
-export declare function attestationKindName(kind: number): "dns" | "social" | null;
+ *  kind this SDK does not know (future program versions may add kinds). For the
+ *  per-platform kinds this returns the platform slug; the two legacy kinds keep
+ *  their historical names (`dns`, `social`). */
+export declare function attestationKindName(kind: number): AttestationKindName | null;
+/**
+ * The canonical platform slug for a `kind`, or null for the two legacy codes
+ * (0 = dns, 1 = social — neither names a single platform) and for any unknown
+ * kind. Mirrors `Attestation::platform_slug` (programs/x1-handles/src/state.rs)
+ * exactly: `Some` only for the per-platform kinds 2..5.
+ */
+export declare function platformSlug(kind: number): string | null;
+/**
+ * The text-record key an attestation `kind` pairs with — where the actual
+ * account handle / domain for that platform lives — or null for the legacy
+ * generic-social kind (1) and any unknown kind. Mirrors the shared contract
+ * table: kind 0 → `website`, 2 → `com.x`, 3 → `com.discord`, 4 → `com.github`,
+ * 5 → `org.telegram`.
+ */
+export declare function textRecordKeyFor(kind: number): string | null;
 /** A decoded verification attestation, staleness already judged. */
 export interface HandleAttestation {
     /** The Attestation account's address, base58. */
     readonly account: string;
     /** The Handle account this attestation is for, base58. */
     readonly handle: string;
-    /** Raw kind byte (0 = dns, 1 = social). */
+    /** Raw kind byte (0 = dns, 1 = social, 2 = x, 3 = discord, 4 = github,
+     *  5 = telegram). */
     readonly kind: number;
-    /** Human name for `kind`, or null for an unknown kind. */
-    readonly kindName: "dns" | "social" | null;
+    /** Human name for `kind`, or null for an unknown kind. Per-platform kinds
+     *  resolve to their platform slug; see {@link platformSlug} /
+     *  {@link textRecordKeyFor} to map a kind to its slug and paired text-record
+     *  key. */
+    readonly kindName: AttestationKindName | null;
     /** `sha256` commitment to the off-chain verdict-inputs bundle. */
     readonly evidenceHash: Uint8Array;
     /** Unix seconds the attestation was (last) stamped. */
@@ -189,7 +233,11 @@ export interface CreateAttestationParams {
     /** The `["attestation", handle, kindByte]` PDA — derive per the module
      *  docs, with the SAME kind byte passed below. */
     readonly attestation: AddressLike;
-    /** {@link ATTESTATION_KIND_DNS} or {@link ATTESTATION_KIND_SOCIAL}. */
+    /** One of the `ATTESTATION_KIND_*` codes (0..{@link ATTESTATION_KIND_COUNT}
+     *  − 1): {@link ATTESTATION_KIND_DNS}, {@link ATTESTATION_KIND_SOCIAL}, or a
+     *  per-platform kind ({@link ATTESTATION_KIND_X},
+     *  {@link ATTESTATION_KIND_DISCORD}, {@link ATTESTATION_KIND_GITHUB},
+     *  {@link ATTESTATION_KIND_TELEGRAM}). */
     readonly kind: number;
     /** `sha256` of the off-chain verdict-inputs bundle (32 bytes) — a
      *  commitment, never the raw evidence. */
@@ -224,3 +272,31 @@ export interface CloseAttestationParams {
  * a rotated-away key's output).
  */
 export declare function buildCloseAttestationIx(p: CloseAttestationParams): BuiltInstruction;
+/** The minimal shape the verification helpers read — any {@link Resolved}
+ *  satisfies it, as does a bare `{ verifications }` an integrator assembles
+ *  from a raw REST payload. */
+export interface HasVerifications {
+    readonly verifications?: readonly HandleVerification[];
+}
+/**
+ * The platform slugs a handle is LIVE-verified on — e.g. `["x", "github"]` —
+ * de-duplicated, in first-seen order. Only entries with `verified === true`
+ * count. Returns `[]` when `verifications` is absent or empty.
+ */
+export declare function verifiedPlatforms(resolved: HasVerifications): string[];
+/**
+ * Whether a handle carries a live verification for a specific platform slug
+ * (`"x"`, `"discord"`, `"github"`, `"telegram"`, `"domain"`, `"social"`).
+ * False when `verifications` is absent.
+ */
+export declare function isVerifiedOn(resolved: HasVerifications, platform: string): boolean;
+/**
+ * The #7145 single-signal rule at the resolve layer: true when the handle has
+ * AT LEAST ONE live verification of any platform. This is the blue-tick
+ * condition. False when `verifications` is absent or empty.
+ *
+ * Trust caveat (see {@link HandleVerification}): a true here means x1id's
+ * rotatable attestor key signed off on an off-chain review that was still live
+ * at resolve time — render it as "verified by x1id", not as trustless proof.
+ */
+export declare function isVerified(resolved: HasVerifications): boolean;

package/dist/attestation.js

@@ -66,10 +66,30 @@ import { decodeBase58_32 } from "./base58.js";
 export const ATTESTATION_SEED = "attestation";
 /** Seed of the attestor-config singleton PDA: `["attestor_config"]`. */
 export const ATTESTOR_CONFIG_SEED = "attestor_config";
-/** `Attestation.kind` — domain control proven (DNS TXT challenge). */
+/** `Attestation.kind` — domain control proven (DNS TXT challenge). LEGACY-safe:
+ *  kept valid forever. Pairs with the `website` text record. */
 export const ATTESTATION_KIND_DNS = 0;
-/** `Attestation.kind` — social-account control proven. */
+/** `Attestation.kind` — generic social-account control proven. LEGACY: the
+ *  single pre-per-platform code, carrying no platform attribution. Kept valid
+ *  forever so existing accounts are never orphaned; new attestations should use
+ *  one of the per-platform codes below. */
 export const ATTESTATION_KIND_SOCIAL = 1;
+/** `Attestation.kind` — X (Twitter) control proven. Pairs with text record
+ *  `com.x`; platform slug `x`. */
+export const ATTESTATION_KIND_X = 2;
+/** `Attestation.kind` — Discord control proven. Pairs with text record
+ *  `com.discord`; platform slug `discord`. */
+export const ATTESTATION_KIND_DISCORD = 3;
+/** `Attestation.kind` — GitHub control proven. Pairs with text record
+ *  `com.github`; platform slug `github`. */
+export const ATTESTATION_KIND_GITHUB = 4;
+/** `Attestation.kind` — Telegram control proven. Pairs with text record
+ *  `org.telegram`; platform slug `telegram`. */
+export const ATTESTATION_KIND_TELEGRAM = 5;
+/** One past the highest valid `kind`. `create_attestation` refuses anything
+ *  `>=` this on-chain; the SDK's builder enforces the same bound. Mirrors
+ *  `Attestation::KIND_COUNT` (programs/x1-handles/src/state.rs). */
+export const ATTESTATION_KIND_COUNT = 6;
 /** Anchor account discriminator: `sha256("account:Attestation")[0..8]`.
  *  Pinned (this SDK is zero-dependency and cannot assume WebCrypto SHA-256
  *  everywhere it runs); asserted against a re-derivation in the test suite
@@ -120,13 +140,69 @@ function toBase58(v, what) {
     return encodeBase58(toBytes32(v, what));
 }
 /** Which verification signal an attestation `kind` byte names, or null for a
- *  kind this SDK does not know (future program versions may add kinds). */
+ *  kind this SDK does not know (future program versions may add kinds). For the
+ *  per-platform kinds this returns the platform slug; the two legacy kinds keep
+ *  their historical names (`dns`, `social`). */
 export function attestationKindName(kind) {
-    if (kind === ATTESTATION_KIND_DNS)
-        return "dns";
-    if (kind === ATTESTATION_KIND_SOCIAL)
-        return "social";
-    return null;
+    switch (kind) {
+        case ATTESTATION_KIND_DNS:
+            return "dns";
+        case ATTESTATION_KIND_SOCIAL:
+            return "social";
+        case ATTESTATION_KIND_X:
+            return "x";
+        case ATTESTATION_KIND_DISCORD:
+            return "discord";
+        case ATTESTATION_KIND_GITHUB:
+            return "github";
+        case ATTESTATION_KIND_TELEGRAM:
+            return "telegram";
+        default:
+            return null;
+    }
+}
+/**
+ * The canonical platform slug for a `kind`, or null for the two legacy codes
+ * (0 = dns, 1 = social — neither names a single platform) and for any unknown
+ * kind. Mirrors `Attestation::platform_slug` (programs/x1-handles/src/state.rs)
+ * exactly: `Some` only for the per-platform kinds 2..5.
+ */
+export function platformSlug(kind) {
+    switch (kind) {
+        case ATTESTATION_KIND_X:
+            return "x";
+        case ATTESTATION_KIND_DISCORD:
+            return "discord";
+        case ATTESTATION_KIND_GITHUB:
+            return "github";
+        case ATTESTATION_KIND_TELEGRAM:
+            return "telegram";
+        default:
+            return null;
+    }
+}
+/**
+ * The text-record key an attestation `kind` pairs with — where the actual
+ * account handle / domain for that platform lives — or null for the legacy
+ * generic-social kind (1) and any unknown kind. Mirrors the shared contract
+ * table: kind 0 → `website`, 2 → `com.x`, 3 → `com.discord`, 4 → `com.github`,
+ * 5 → `org.telegram`.
+ */
+export function textRecordKeyFor(kind) {
+    switch (kind) {
+        case ATTESTATION_KIND_DNS:
+            return "website";
+        case ATTESTATION_KIND_X:
+            return "com.x";
+        case ATTESTATION_KIND_DISCORD:
+            return "com.discord";
+        case ATTESTATION_KIND_GITHUB:
+            return "com.github";
+        case ATTESTATION_KIND_TELEGRAM:
+            return "org.telegram";
+        default:
+            return null;
+    }
 }
 /**
  * Decode one Attestation account.
@@ -250,8 +326,9 @@ export function buildSetAttestorIx(p) {
  * the (handle, kind) attestation.
  */
 export function buildCreateAttestationIx(p) {
-    if (!Number.isInteger(p.kind) || p.kind < 0 || p.kind > 1) {
-        throw new Error("kind must be 0 (dns) or 1 (social)");
+    if (!Number.isInteger(p.kind) || p.kind < 0 || p.kind >= ATTESTATION_KIND_COUNT) {
+        throw new Error(`kind must be an integer in 0..${ATTESTATION_KIND_COUNT - 1} ` +
+            "(0 dns, 1 social, 2 x, 3 discord, 4 github, 5 telegram)");
     }
     if (p.evidenceHash.length !== 32) {
         throw new Error("evidenceHash must be exactly 32 bytes (a sha256 digest)");
@@ -288,3 +365,36 @@ export function buildCloseAttestationIx(p) {
         data: CLOSE_ATTESTATION_DISCRIMINATOR.slice(),
     };
 }
+/**
+ * The platform slugs a handle is LIVE-verified on — e.g. `["x", "github"]` —
+ * de-duplicated, in first-seen order. Only entries with `verified === true`
+ * count. Returns `[]` when `verifications` is absent or empty.
+ */
+export function verifiedPlatforms(resolved) {
+    const out = [];
+    for (const v of resolved.verifications ?? []) {
+        if (v && v.verified && !out.includes(v.platform))
+            out.push(v.platform);
+    }
+    return out;
+}
+/**
+ * Whether a handle carries a live verification for a specific platform slug
+ * (`"x"`, `"discord"`, `"github"`, `"telegram"`, `"domain"`, `"social"`).
+ * False when `verifications` is absent.
+ */
+export function isVerifiedOn(resolved, platform) {
+    return (resolved.verifications ?? []).some((v) => v && v.verified && v.platform === platform);
+}
+/**
+ * The #7145 single-signal rule at the resolve layer: true when the handle has
+ * AT LEAST ONE live verification of any platform. This is the blue-tick
+ * condition. False when `verifications` is absent or empty.
+ *
+ * Trust caveat (see {@link HandleVerification}): a true here means x1id's
+ * rotatable attestor key signed off on an off-chain review that was still live
+ * at resolve time — render it as "verified by x1id", not as trustless proof.
+ */
+export function isVerified(resolved) {
+    return (resolved.verifications ?? []).some((v) => v && v.verified);
+}

package/dist/types.d.ts

@@ -11,6 +11,43 @@ export type Verification =
 "verified"
 /** Record exists but ownership was never proved. Show a warning. */
  | "unverified";
+/**
+ * One per-platform verification a handle carries — the "verified by
+ * [platform]" signal (#7145). Shape mirrors the resolver's REST `/resolve`
+ * `verifications[]` entries exactly (snake_case `attested_at`), so an
+ * integrator can drop a decoded REST array straight onto
+ * {@link Resolved.verifications} with no transformation.
+ *
+ * # What this proves — and, honestly, what it does not
+ *
+ * A verification is an off-chain review (a DNS lookup, an OAuth completion, a
+ * human check) that x1id's **attestor key** signed off on at `attested_at`.
+ * It is NOT a trustless proof: the attestor key is admin-rotatable, so the
+ * trust anchor is "whoever the registry admin currently designates". Entries
+ * are also epoch-bound — the resolver emits an entry only while the underlying
+ * attestation is LIVE (not stale): `attested_at >= handle.registered_at` AND
+ * `>= handle.records_cleared_at`. Render it as "verified by x1id", never as
+ * more than that.
+ */
+export interface HandleVerification {
+    /**
+     * Platform slug: `"x"`, `"discord"`, `"github"`, `"telegram"`, `"domain"`
+     * (legacy DNS/kind 0), or `"social"` (legacy generic/kind 1). Match this
+     * against {@link platformSlug}'s output when joining to an attestation kind.
+     */
+    readonly platform: string;
+    /**
+     * The paired text-record value for a live verification (e.g. `"@michelle"`
+     * for `x`, `"michelle.com"` for `domain`), or `null` when the text record
+     * is missing/stale or the platform carries none (legacy `social`).
+     */
+    readonly value: string | null;
+    /** Whether this verification is live. The resolver only emits live ones,
+     *  but readers must still honour the flag. */
+    readonly verified: boolean;
+    /** Unix seconds the attestation was (last) stamped. */
+    readonly attested_at: number;
+}
 /**
  * A successfully resolved name.
  *
@@ -31,6 +68,17 @@ export interface Resolved {
     readonly chain: Chain;
     /** Whether ownership of `address` was proved. */
     readonly verification: Verification;
+    /**
+     * Per-platform "verified by [platform]" signals for this handle (#7145),
+     * when the producing resolver supplies them (the tools/api REST `/resolve`
+     * response carries a `verifications[]` field; the SDK's own on-chain
+     * `resolve()` does not populate this — read attestations directly via
+     * {@link fetchAttestations}). **Optional and additive**: an older resolver,
+     * or a handle with no live verifications, omits it. Never index into it
+     * blindly — use {@link isVerified} / {@link verifiedPlatforms} /
+     * {@link isVerifiedOn}, which tolerate its absence.
+     */
+    readonly verifications?: readonly HandleVerification[];
 }
 /** Chains a handle can carry a record for. SLIP-44 based. */
 export type Chain = "X1" | "SOL" | "ETH" | "BTC";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Resolve @handles and X1NS names on X1. Never silently picks between namespaces.",
   "type": "module",
   "main": "./dist/index.js",