@x1id/resolve 0.2.1 → 0.3.0

package/dist/attestation.js

@@ -0,0 +1,278 @@
+/**
+ * Domain/social verification attestations (`Attestation` accounts, #7379) —
+ * read WITH the universal staleness rule from docs/record-trust.md
+ * structurally enforced, plus instruction builders for `set_attestor` /
+ * `create_attestation` / `close_attestation`.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). Builders return the
+ * transport-neutral {@link BuiltInstruction} `delegate.ts` defines; PDAs are
+ * NOT derived here (see delegate.ts's module docs for why — derive
+ * `["attestation", handlePda, kindByte]` / `["attestor_config"]` with your
+ * runtime's canonical `findProgramAddress`).
+ *
+ * # What an attestation proves — and, honestly, what it does not
+ *
+ * An `Attestation` proves exactly one statement: **"the key configured in
+ * `AttestorConfig` — the x1id review process — attested this evidence at
+ * time `attestedAt`."** It is NOT a trustless proof of domain or social
+ * control: the verification (DNS lookup, social-post check, human review)
+ * happens OFF-chain, and the chain records only that the attestor key signed
+ * off on it. That key is admin-rotatable, so the trust anchor is "whoever
+ * the registry admin currently designates" — rotatable-key trust, not
+ * trustlessness. Consumers needing stronger guarantees must not render an
+ * attestation as more than it is.
+ *
+ * # Verified = ONE live attestation of EITHER kind
+ *
+ * Per the #7145 decision (a single strong signal is enough — requiring two
+ * would reject Nike proving control of nike.com), a handle is "verified"
+ * when at least one NON-STALE attestation of either kind exists; `kind`
+ * records which signal proved it. {@link isHandleVerified} implements
+ * exactly this.
+ *
+ * # Why every function here demands `registeredAt` — epoch-bound, no TTL
+ *
+ * Attestations do not expire on a timer (owner decision 2026-09-03); they
+ * are invalidated by OWNERSHIP EPOCH. A `Handle`'s address is
+ * `["handle", name]` — a pure function of the name — so release +
+ * re-register lands the new registration at the SAME pubkey, and the
+ * previous owner's attestation is physically attached to the new owner's
+ * name with no action by anyone. The mandatory read-side rule
+ * (docs/record-trust.md, the universal rule):
+ *
+ *     attestation.attested_at >= handle.registered_at
+ *
+ * An attestation that fails it belongs to a previous, unrelated owner and
+ * must never be rendered as verifying the current one. Like `records.ts`,
+ * there is deliberately no way to decode or fetch an attestation through
+ * this module without the handle's `registered_at` in hand. (The one
+ * documented blind spot is shared with `Handle.owner`/`Primary`/
+ * `RecordDelegate`: a bearer-NFT marketplace trade bumps no epoch, so the
+ * attestation keeps reading live until the attestor re-reviews or revokes.)
+ */
+import { encodeBase58 } from "./base58.js";
+import { decodeBase58_32 } from "./base58.js";
+/** Seed prefix of an attestation PDA: `["attestation", handlePda, kindByte]`. */
+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). */
+export const ATTESTATION_KIND_DNS = 0;
+/** `Attestation.kind` — social-account control proven. */
+export const ATTESTATION_KIND_SOCIAL = 1;
+/** 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
+ *  so a typo can never silently pass. */
+export const ATTESTATION_DISCRIMINATOR = Uint8Array.from([
+    152, 125, 183, 86, 36, 146, 121, 73,
+]);
+/** Anchor account discriminator: `sha256("account:AttestorConfig")[0..8]`. */
+export const ATTESTOR_CONFIG_DISCRIMINATOR = Uint8Array.from([
+    72, 128, 1, 99, 238, 231, 80, 72,
+]);
+/** Anchor instruction discriminator: `sha256("global:set_attestor")[0..8]`. */
+export const SET_ATTESTOR_DISCRIMINATOR = Uint8Array.from([
+    95, 11, 236, 157, 234, 146, 163, 237,
+]);
+/** Anchor instruction discriminator: `sha256("global:create_attestation")[0..8]`. */
+export const CREATE_ATTESTATION_DISCRIMINATOR = Uint8Array.from([
+    49, 24, 67, 80, 12, 249, 96, 239,
+]);
+/** Anchor instruction discriminator: `sha256("global:close_attestation")[0..8]`. */
+export const CLOSE_ATTESTATION_DISCRIMINATOR = Uint8Array.from([
+    249, 84, 133, 23, 48, 175, 252, 221,
+]);
+/** `Attestation` account size — every field is fixed-width, so unlike a
+ *  `Handle` the account is exactly this long:
+ *  disc(8) + handle(32) + kind(1) + evidence_hash(32) + attested_at(8)
+ *  + attestor(32) + bump(1). */
+export const ATTESTATION_LEN = 114;
+/** `AttestorConfig` account size: disc(8) + attestor(32) + bump(1). */
+export const ATTESTOR_CONFIG_LEN = 41;
+/** Byte offset of `handle` within an Attestation account. */
+const ATTESTATION_HANDLE_OFFSET = 8;
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+function toBytes32(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return v;
+}
+function toBase58(v, what) {
+    // Round-trip through bytes so a non-canonical base58 spelling and a byte
+    // input both come out identically.
+    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). */
+export function attestationKindName(kind) {
+    if (kind === ATTESTATION_KIND_DNS)
+        return "dns";
+    if (kind === ATTESTATION_KIND_SOCIAL)
+        return "social";
+    return null;
+}
+/**
+ * Decode one Attestation account.
+ *
+ * `registeredAt` is the owning Handle's `registered_at`, decoded by the
+ * caller from the Handle account — it decides `stale`. There is
+ * intentionally no overload without it (see the module docs).
+ *
+ * Returns null for anything that is not an Attestation: wrong length or
+ * wrong discriminator.
+ */
+export function decodeAttestation(raw, account, registeredAt) {
+    if (raw.length !== ATTESTATION_LEN)
+        return null;
+    for (let i = 0; i < 8; i++) {
+        if (raw[i] !== ATTESTATION_DISCRIMINATOR[i])
+            return null;
+    }
+    const dv = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    let o = 8;
+    const handle = encodeBase58(raw.slice(o, o + 32));
+    o += 32;
+    const kind = raw[o];
+    o += 1;
+    const evidenceHash = raw.slice(o, o + 32);
+    o += 32;
+    const attestedAt = dv.getBigInt64(o, true);
+    o += 8;
+    const attestor = encodeBase58(raw.slice(o, o + 32));
+    return {
+        account,
+        handle,
+        kind,
+        kindName: attestationKindName(kind),
+        evidenceHash,
+        attestedAt,
+        attestor,
+        stale: attestedAt < registeredAt,
+    };
+}
+/** The attestations that vouch for the CURRENT owner — `stale` ones
+ *  excluded. This is the list to judge verification from. */
+export function liveAttestations(attestations) {
+    return attestations.filter((a) => !a.stale);
+}
+/**
+ * The #7145 verified rule: a handle is verified when at least ONE non-stale
+ * attestation of EITHER kind exists (a single strong signal is enough; the
+ * surviving `kindName`s say which signals proved it).
+ */
+export function isHandleVerified(attestations) {
+    return attestations.some((a) => !a.stale);
+}
+/**
+ * Fetch every Attestation account of a handle — one `getProgramAccounts`
+ * call, filtered by the RPC on size (114), the Attestation discriminator at
+ * offset 0 and the handle pubkey at offset 8, then every byte re-checked
+ * locally (the node's filters are an optimisation, never the guarantee) —
+ * the exact shape of `fetchRecords`. Scoping the scan to the registry
+ * program id also IS the ownership check.
+ *
+ * `registeredAt` is `Handle.registered_at` as decoded from the Handle
+ * account the caller already has — the staleness rule needs it, and there
+ * is no variant of this function without it. Every attestation is returned,
+ * stale ones flagged, so an owner surface can show what a previous
+ * registration left behind; anything that renders a verified badge takes
+ * {@link isHandleVerified} / {@link liveAttestations}.
+ */
+export async function fetchAttestations(rpc, programId, handleAccount, registeredAt) {
+    const res = (await rpc("getProgramAccounts", [
+        programId,
+        {
+            encoding: "base64",
+            commitment: "confirmed",
+            filters: [
+                { dataSize: ATTESTATION_LEN },
+                { memcmp: { offset: 0, bytes: encodeBase58(ATTESTATION_DISCRIMINATOR) } },
+                { memcmp: { offset: ATTESTATION_HANDLE_OFFSET, bytes: handleAccount } },
+            ],
+        },
+    ]));
+    const out = [];
+    for (const a of res ?? []) {
+        const bin = atob(a.account.data[0]);
+        const raw = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            raw[i] = bin.charCodeAt(i);
+        const decoded = decodeAttestation(raw, a.pubkey, registeredAt);
+        // Defence in depth: the memcmp filter should guarantee the handle
+        // match, but a wrong offset would silently attribute someone else's
+        // attestation to this handle. A malformed account is skipped, not fatal.
+        if (decoded && decoded.handle === handleAccount)
+            out.push(decoded);
+    }
+    out.sort((x, y) => x.kind - y.kind);
+    return out;
+}
+/**
+ * Build `set_attestor` — admin-only: initialize or rotate the attestor key.
+ * Rotation does not void existing attestations (they record their signer as
+ * a historical fact); revoking a bad key's output is `close_attestation`.
+ */
+export function buildSetAttestorIx(p) {
+    const data = new Uint8Array(8 + 32);
+    data.set(SET_ATTESTOR_DISCRIMINATOR, 0);
+    data.set(toBytes32(p.attestor, "attestor"), 8);
+    const keys = [
+        { pubkey: toBase58(p.admin, "admin"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.attestorConfig, "attestorConfig"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/**
+ * Build `create_attestation` — attestor-only: stamp (or re-stamp,
+ * re-deriving `attested_at` from the Clock and replacing the evidence hash)
+ * 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 (p.evidenceHash.length !== 32) {
+        throw new Error("evidenceHash must be exactly 32 bytes (a sha256 digest)");
+    }
+    const data = new Uint8Array(8 + 1 + 32);
+    data.set(CREATE_ATTESTATION_DISCRIMINATOR, 0);
+    data[8] = p.kind;
+    data.set(p.evidenceHash, 9);
+    const keys = [
+        { pubkey: toBase58(p.attestor, "attestor"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.attestorConfig, "attestorConfig"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.attestation, "attestation"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/**
+ * Build `close_attestation` — revoke: close the account, rent to
+ * `recipient`. Attestor- or admin-signed (the admin path is the cleanup for
+ * a rotated-away key's output).
+ */
+export function buildCloseAttestationIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.signer, "signer"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.attestorConfig, "attestorConfig"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.attestation, "attestation"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.recipient, "recipient"), isSigner: false, isWritable: true },
+    ];
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys,
+        data: CLOSE_ATTESTATION_DISCRIMINATOR.slice(),
+    };
+}

package/dist/control.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Control-verification primitive — prove to a third party that a wallet
+ * currently controls a `@handle`. Companion to docs/control-proof.md, which
+ * is normative; this file implements it.
+ *
+ * The flow has exactly two SDK entry points, one per side:
+ *
+ * - **Verifier** calls {@link createControlChallenge}: it generates a fresh
+ *   nonce, reads the handle's CURRENT ownership epoch
+ *   (`Handle.registered_at`) from chain, and returns the challenge the
+ *   prover must sign. The verifier stores the returned object (nonce is
+ *   single-use, proofs expire — see the spec).
+ * - The prover signs the raw UTF-8 bytes of `challenge` with the wallet key
+ *   that controls the handle (no wallet prefix — see the spec's envelope
+ *   section) and returns `(signer, signature)`.
+ * - **Verifier** calls {@link verifyControlProof} with the ISSUED challenge
+ *   object (never a challenge string received from the prover) and the
+ *   proof. It re-reads the handle, requires the epoch to still match,
+ *   resolves who currently holds authority (`require_current_authority`
+ *   semantics: untokenized → `Handle.owner`; tokenized → the NFT holder,
+ *   NFT in that holder's associated token account), and verifies the
+ *   signature RFC-8032-strictly.
+ *
+ * Challenge format (built by `handle_normalize::control_challenge` in Rust
+ * and {@link buildControlChallenge} here — byte-identical by test):
+ *
+ *     x1-handles:ctl:v1:<handle>:<registered_at>:<nonce>
+ *
+ * The `ctl` purpose tag makes this space disjoint from the record
+ * verification challenges (`x1-handles:v1:...`): a signature obtained for a
+ * record verification can never validate as a control proof, and vice versa.
+ */
+import type { WasmResolver } from "./wasm.js";
+/** `<protocol>:<purpose>:<version>:` — everything a control challenge starts
+ *  with, and nothing a record-verification challenge ever starts with (their
+ *  second segment is the literal `v1`, and neither a canonical handle nor a
+ *  nonce may contain `:`). */
+export declare const CONTROL_CHALLENGE_PREFIX = "x1-handles:ctl:v1:";
+export interface ControlConfig {
+    /** X1 RPC endpoint. */
+    readonly rpcUrl: string;
+    /** WASM module for account derivation — same instance the resolver uses. */
+    readonly wasm: WasmResolver;
+    /** Optional fetch override for testing or custom transport. */
+    readonly fetchImpl?: typeof fetch;
+    /** @handle registry program id. Defaults to the canonical X1 deployment. */
+    readonly handleProgramId?: string;
+    /**
+     * Override for the ed25519 verifier — for runtimes whose WebCrypto lacks
+     * Ed25519. Any replacement MUST be RFC-8032 strict (reject `s >= L`);
+     * docs/control-proof.md names acceptable libraries. Defaults to
+     * {@link verifyEd25519Strict}.
+     */
+    readonly verifyEd25519?: (publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array) => Promise<boolean>;
+}
+/**
+ * A challenge the VERIFIER issued and must keep. `challenge` is what the
+ * prover signs; the other fields are the verifier's evidence of what it
+ * asked for. `verifyControlProof` takes this object — not a string handed
+ * back by the prover — so a prover can never substitute a challenge of its
+ * own choosing.
+ */
+export interface ControlChallenge {
+    /** The exact string whose raw UTF-8 bytes the prover must sign. */
+    readonly challenge: string;
+    /** Canonical handle (no `@`). */
+    readonly handle: string;
+    /** `Handle.registered_at` at issuance — the ownership epoch this
+     *  challenge is bound to. */
+    readonly registeredAt: bigint;
+    /** The verifier-issued single-use nonce embedded in `challenge`. */
+    readonly nonce: string;
+    /** `Date.now()` at issuance, ms — enforce the max proof age against it. */
+    readonly issuedAt: number;
+}
+/** What the prover hands back. */
+export interface ControlProof {
+    /** The wallet claiming control, base58. */
+    readonly signer: string;
+    /** 64-byte ed25519 signature over the raw UTF-8 bytes of the challenge. */
+    readonly signature: Uint8Array;
+}
+export type ControlFailureReason = 
+/** The handle account no longer exists or is not owned by the registry. */
+"handle-not-registered"
+/** `Handle.registered_at` changed since the challenge was issued — the
+ *  name was sold, released + re-registered, or otherwise changed epoch.
+ *  The proof is a previous owner's; issue a fresh challenge. */
+ | "epoch-changed"
+/** Tokenized handle whose NFT was burned — nobody controls the name. */
+ | "nft-burned"
+/** The signer is not the current authority (untokenized: not
+ *  `Handle.owner`; tokenized: not the NFT holder). */
+ | "signer-not-authority"
+/** Tokenized handle whose NFT sits outside the holder's associated token
+ *  account — the registry does not recognise that wallet as able to act
+ *  for the name (`require_current_authority` parity), so neither does a
+ *  control proof. */
+ | "nft-not-in-authority-ata"
+/** The signature does not verify (strictly) over the challenge bytes. */
+ | "bad-signature";
+export type ControlVerification = {
+    readonly valid: true;
+    /** Canonical handle the proof establishes control of. */
+    readonly handle: string;
+    /** The verified controller, base58. */
+    readonly signer: string;
+    /** The ownership epoch the proof is valid for. */
+    readonly registeredAt: bigint;
+    /** Whether authority came from holding the NFT (true) or from
+     *  `Handle.owner` (false). */
+    readonly tokenized: boolean;
+} | {
+    readonly valid: false;
+    readonly reason: ControlFailureReason;
+    readonly message: string;
+};
+/**
+ * Build the exact challenge string — byte-identical to the Rust
+ * `handle_normalize::control_challenge`. Throws {@link ResolveError}
+ * (`invalid-handle`) for a non-canonical handle and `RangeError` for a
+ * nonce outside the shared charset, rather than silently producing a string
+ * the Rust side would refuse.
+ *
+ * Verifiers normally never call this directly — {@link
+ * createControlChallenge} does, after reading `registeredAt` from chain, so
+ * a challenge cannot be built against a guessed or stale epoch.
+ */
+export declare function buildControlChallenge(handle: string, registeredAt: bigint, nonce: string): string;
+/**
+ * Parse a control challenge string, or null for anything that is not one —
+ * including every record-verification challenge (`x1-handles:v1:...`), whose
+ * signatures must never be accepted as control proofs.
+ */
+export declare function parseControlChallenge(challenge: string): {
+    readonly handle: string;
+    readonly registeredAt: bigint;
+    readonly nonce: string;
+} | null;
+/**
+ * Generate a verifier-issued nonce: `bytes` bytes (>= 16, the spec's entropy
+ * floor) from the platform CSPRNG, hex-encoded to stay inside the shared
+ * nonce charset. The nonce is SINGLE-USE — store it with the issued
+ * challenge and delete it the moment a proof against it is checked, pass or
+ * fail. A prover-chosen nonce is not a nonce; see docs/control-proof.md.
+ */
+export declare function generateControlNonce(bytes?: number): string;
+/**
+ * Verifier side, step 1: issue a challenge for a handle.
+ *
+ * Reads the handle's CURRENT `registered_at` from chain and binds the
+ * challenge to it — there is no way to obtain a challenge through this API
+ * without the live epoch in hand, which is what makes a past owner's proof
+ * worthless the moment the name changes hands.
+ *
+ * Store the returned object server-side (it is the only thing
+ * {@link verifyControlProof} accepts), enforce single use of `nonce`, and
+ * enforce a max proof age against `issuedAt` (the spec recommends 5 minutes).
+ *
+ * @throws {ResolveError} `invalid-handle` for bad input, `not-found` for an
+ * unregistered handle, `rpc-error` for transport problems.
+ */
+export declare function createControlChallenge(cfg: ControlConfig, handleInput: string): Promise<ControlChallenge>;
+/**
+ * Verifier side, step 2: check a proof against the challenge YOU issued.
+ *
+ * Takes the stored {@link ControlChallenge} — never a challenge string
+ * received from the prover — and re-derives the signed bytes from its
+ * fields, so neither side can substitute a different string. Then:
+ *
+ * 1. re-reads the handle and requires `registered_at` to still equal the
+ *    epoch the challenge was issued under (`epoch-changed` otherwise —
+ *    the name changed hands after issuance);
+ * 2. resolves the CURRENT authority with `require_current_authority`
+ *    semantics — untokenized → `Handle.owner`; tokenized → the NFT holder,
+ *    and only with the NFT in that holder's associated token account
+ *    (`Handle.owner` is stale once tokenized and is never consulted);
+ * 3. requires `proof.signer` to be that authority;
+ * 4. verifies the 64-byte ed25519 signature over the raw UTF-8 challenge
+ *    bytes, RFC-8032-strictly.
+ *
+ * Verification outcomes come back as `{ valid: false, reason }` — only
+ * transport failures throw (`ResolveError` `rpc-error`). Nonce single-use
+ * and max proof age are the CALLER's responsibility: delete the stored
+ * challenge the moment this returns, whatever the outcome, and refuse
+ * challenges older than your proof-age limit before calling.
+ */
+export declare function verifyControlProof(cfg: ControlConfig, issued: ControlChallenge, proof: ControlProof): Promise<ControlVerification>;
+/**
+ * RFC-8032-strict ed25519 verification via WebCrypto (`Ed25519`), available
+ * in Node 20+ and current browsers. Both are backed by implementations that
+ * reject a non-canonical `s >= L` (the malleability the spec's strictness
+ * requirement exists for) — the test suite pins this with known-answer
+ * vectors, including a rejected `s + L` forgery of a valid signature.
+ *
+ * Returns false for anything malformed (wrong lengths, off-curve key,
+ * invalid signature); throws only when the runtime has no Ed25519 WebCrypto
+ * at all — pass `verifyEd25519` in {@link ControlConfig} there, using a
+ * strict library named in docs/control-proof.md.
+ */
+export declare function verifyEd25519Strict(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): Promise<boolean>;