@x1id/resolve 0.23.0 → 0.43.0

package/README.md

@@ -544,6 +544,22 @@ the supplied on-chain records disagree. `agentVerificationLevel` reports only
 the highest level it actually checked — L1 requires the manifest's claimed
 attestation to match a *live* one, never assumed from presence alone.
 
+**Manifest v2** (0.32.0, `docs/agent-records.md` §3.1) adds per-capability /
+per-endpoint `pricing` (`{amount, mint, unit}`), `payment.methods` (x402 on
+the `x1` or `cdp` rail) and a name-bound `payment.payTo: {name}` — never an
+address. Resolve what to pay from the chain:
+
+```ts
+import { resolveManifestPayTo, manifestOffers, manifestCapabilities, payToWarnings } from "@x1id/resolve";
+
+// records / authority: the payTo name's decoded address records and its
+// current owner (or pNFT holder) — the inputs of paymentAddressFor (W16).
+const perMethod = resolveManifestPayTo(result.manifest, { records, authority });
+// [{ method, chain: "X1", payTo: { address, basis: "verified-record" } }, …]
+const offers = manifestOffers(result.manifest); // [{ capability, url, price }, …]
+const warnings = payToWarnings(result.manifest, { X1: perMethod[0]?.payTo?.address });
+```
+
 ## Verifying a non-SVM address record
 
 Prove control of an ETH, BTC, or another SVM address so its `Record` gets
@@ -702,6 +718,61 @@ the SIMD-0048 off-chain envelope). A nonce is single-use and expires, so on
 This is the hosted-session flow. For a server-less proof your own backend
 verifies, see `signInWithX1ID` in [SIGNIN.md](./SIGNIN.md).
 
+## Sign in with X1ID (OpenID Connect, `@x1id/resolve/oidc`)
+
+For apps that want a standard OIDC login at `auth.x1id.io` (code + PKCE,
+verified ID token, `/me` claims) instead of handling wallet signatures
+themselves:
+
+```ts
+import { createX1idOidcClient, completeX1idLogin } from "@x1id/resolve/oidc";
+import { createX1idLoginButton } from "@x1id/resolve/login-button";
+
+const x1id = createX1idOidcClient({ clientId: "x1c_…", redirectUri: "https://app.example/callback" });
+document.querySelector("#login")!.append(createX1idLoginButton({ client: x1id })); // login page
+const { sub, userInfo } = await completeX1idLogin(x1id);                             // /callback page
+```
+
+`sub` is the wallet address (the account key); a login proves wallet control
+at sign-in, not legal identity. Server (confidential) clients, refresh,
+logout and the custom element are in
+[services/auth/README.md](../services/auth/README.md#relying-party-quick-start).
+
+## Messaging (`@x1id/resolve/messaging`)
+
+End-to-end encrypted messages between @names
+([spec](../docs/specs/x1id-messaging.md)). A separate entry point: it is the
+only part of the package with runtime dependencies (the audited
+`@noble/curves`, `@noble/ciphers`, `@noble/hashes`), so the root import never
+loads them.
+
+```ts
+import {
+  messagingKeyDerivationMessage, deriveMessagingKeyPair, encodeMessagingKeyRecord,
+  resolveMessagingKey, sealMessage, attachSignature, openMessage, buildMessageProofMemoIx,
+} from "@x1id/resolve/messaging";
+
+// 1. Key from a wallet signature (sign twice on set-up; both must match).
+const sig = await wallet.signMessage(messagingKeyDerivationMessage(me, 0));
+const keys = deriveMessagingKeyPair(sig, me, 0);
+// 2. The owner publishes it as the `x1.msg.key` text record (owner pays):
+//    value = encodeMessagingKeyRecord({ publicKey: keys.publicKey, wallet: me, index: 0 })
+// 3. Resolve a recipient with the trust rule (key set after the current
+//    holder's ownership epoch, by the holder or a delegate granted after it).
+const r = await resolveMessagingKey("@bob", { rpcUrl, handleProgramId, wasm, find });
+if (!r.verdict.ok) throw new Error(`@bob can't receive messages (${r.verdict.reason})`);
+// 4. Seal for ONE network (bound into the signed header), have the sender's wallet
+//    sign the digest, send the envelope (+ recipientName: "bob") to that network's relay.
+const u = sealMessage({ network: "mainnet", sender: me, recipient: r.verdict.key.wallet, recipientKey: r.verdict.key.publicKey, senderKey: keys.publicKey, text });
+const envelope = attachSignature(u, await wallet.signMessage(u.signingMessage));
+// 5. The recipient: openMessage(envelope, theirKeys, { network: "mainnet" }) verifies and decrypts.
+// Optional sender-paid proof: buildMessageProofMemoIx({ sender: me, digest: u.digest }).
+```
+
+Wallets whose message signatures don't verify on X1 sign a never-broadcast
+memo transaction instead: `envelopeSigningTransaction` +
+`attachTransactionSignature`.
+
 ## Errors
 
 `ResolveError` carries a `code` a UI can branch on:

package/dist/accounts.d.ts

@@ -43,6 +43,12 @@ export interface ParsedHandle {
     readonly holderEpoch: bigint;
     /** Set when the handle is tokenized (NFT extension present). */
     readonly nftMint: Uint8Array | null;
+    /** `Handle.recovery` — the configured recovery key, or null (Recovery 2). */
+    readonly recovery: Uint8Array | null;
+    /** `Handle.recovery_initiated_at` (0 = no recovery pending). */
+    readonly recoveryInitiatedAt: bigint;
+    /** `Handle.recovery_target` — who owns it once a pending recovery completes. */
+    readonly recoveryTarget: Uint8Array | null;
 }
 export declare function readI64(data: Uint8Array, offset: number): bigint;
 export declare function readU64(data: Uint8Array, offset: number): bigint;

package/dist/accounts.js

@@ -96,11 +96,16 @@ export function parseHandleAccount(data) {
     // recovery: Option<Pubkey>
     if (pos >= data.length)
         return null;
+    const recovery = data[pos] === 1 ? data.slice(pos + 1, pos + 33) : null;
     pos += 1 + (data[pos] === 1 ? 32 : 0);
+    if (pos + 8 > data.length)
+        return null;
+    const recoveryInitiatedAt = readI64(data, pos);
     pos += 8; // recovery_initiated_at
     // recovery_target: Option<Pubkey>
     if (pos >= data.length)
         return null;
+    const recoveryTarget = data[pos] === 1 ? data.slice(pos + 1, pos + 33) : null;
     pos += 1 + (data[pos] === 1 ? 32 : 0);
     if (pos + 8 > data.length)
         return null;
@@ -110,7 +115,7 @@ export function parseHandleAccount(data) {
         : null;
     const recordsClearedAt = data.length >= RECORDS_CLEARED_EXT_OFFSET + 8 ? readI64(data, RECORDS_CLEARED_EXT_OFFSET) : 0n;
     const holderEpoch = data.length >= HOLDER_EPOCH_EXT_OFFSET + 8 ? readI64(data, HOLDER_EPOCH_EXT_OFFSET) : 0n;
-    return { name, owner, registeredAt, recordsClearedAt, holderEpoch, nftMint };
+    return { name, owner, registeredAt, recordsClearedAt, holderEpoch, nftMint, recovery, recoveryInitiatedAt, recoveryTarget };
 }
 /** Build the RPC plumbing every reader in this package shares. */
 export function makeAccountReader(rpcUrl, fetchImpl) {

package/dist/agent.d.ts

@@ -26,6 +26,8 @@
 import type { HandleTextRecord } from "./textRecords.js";
 import type { HandleAttestation } from "./attestation.js";
 import type { HandleRecord } from "./records.js";
+import { type PaymentRecordLike, type PaymentResolution } from "./payment.js";
+import { type Chain } from "./types.js";
 /** The six well-known `TextRecord` keys an agent handle may set. Every
  *  value must be `https://` EXCEPT `manifest`, which may also be
  *  `ipfs://<cid>` — see {@link checkAgentUrl}. */
@@ -38,11 +40,66 @@ export declare const AGENT_RECORD_KEYS: Readonly<{
     readonly capabilities: "agent.capabilities";
 }>;
 export type AgentEndpointType = "x402" | "mcp" | "a2a" | "http";
-/** `agent.manifest` v1 (`docs/agent-records.md` §3), as accepted by
- *  {@link validateManifest}. */
+/** Manifest versions {@link validateManifest} accepts. v1 is the original
+ *  shape; v2 (`docs/agent-records.md` §3.1) adds per-capability / per-endpoint
+ *  pricing, accepted payment methods and a name-bound `payTo`. A v1 manifest
+ *  validates exactly as it always did. */
+export declare const AGENT_MANIFEST_VERSIONS: readonly [1, 2];
+export type AgentManifestVersion = (typeof AGENT_MANIFEST_VERSIONS)[number];
+/** Billing units a v2 price may use. `per-call` is the x402 "exact" unit; the
+ *  rest are metered units the seller's live 402 quotes per request. */
+export declare const AGENT_PRICE_UNITS: readonly ["per-call", "per-1k-tokens", "per-1k-chars", "per-minute", "per-mb"];
+export type AgentPriceUnit = (typeof AGENT_PRICE_UNITS)[number];
+/** The native-asset sentinel for {@link AgentPrice.mint}: XNT on X1. */
+export declare const AGENT_NATIVE_MINT = "XNT";
+/** One v2 price. `amount` is a decimal string of the asset's SMALLEST units
+ *  (lamports for XNT, base units for an SPL mint) — never a float. */
+export interface AgentPrice {
+    readonly amount: string;
+    /** `"XNT"` (native) or an SPL mint (base58) on X1; a CDP-rail asset may also
+     *  be an EVM token address (`0x…`). */
+    readonly mint: string;
+    readonly unit: AgentPriceUnit;
+}
+/** One accepted payment method (v2). `rail: "x1"` is the X1-native x402 rail
+ *  (self-sponsored, settled on X1); `rail: "cdp"` is the Coinbase CDP
+ *  facilitator rail (e.g. USDC on Solana / Base). */
+export interface AgentPaymentMethod {
+    readonly id?: string;
+    readonly type: "x402";
+    readonly rail: "x1" | "cdp";
+    /** CAIP-2 network id — for `x1` the X1 network matching `x1id.network`
+     *  (`X1_TESTNET_NETWORK` / `X1_MAINNET_NETWORK`). */
+    readonly network: string;
+    readonly scheme?: string;
+    readonly facilitator?: string;
+    /** Mints this method settles (same spelling as {@link AgentPrice.mint}). */
+    readonly assets?: readonly string[];
+}
+/** One advertised capability (v2), searchable in the directory by `id`. */
+export interface AgentCapability {
+    readonly id: string;
+    readonly description?: string;
+    /** The `endpoints[].id` that serves this capability. */
+    readonly endpoint?: string;
+    readonly pricing?: readonly AgentPrice[];
+}
+export interface AgentEndpoint {
+    /** v2: stable id, referenced from `capabilities.items[].endpoint`. */
+    readonly id?: string;
+    readonly type: AgentEndpointType;
+    readonly url: string;
+    /** v2: capability ids served here. */
+    readonly capabilities?: readonly string[];
+    /** v2: this endpoint's own price(s). */
+    readonly pricing?: readonly AgentPrice[];
+}
+/** `agent.manifest` (`docs/agent-records.md` §3), v1 or v2, as accepted by
+ *  {@link validateManifest}. Fields marked v2 are checked (and meaningful)
+ *  only when `x1id.version === 2`. */
 export interface AgentManifest {
     readonly x1id: {
-        readonly version: 1;
+        readonly version: AgentManifestVersion;
         readonly name: string;
         readonly network: "testnet" | "mainnet";
         /** Base58 address of the `Handle` PDA — the uniqueness anchor. */
@@ -56,15 +113,26 @@ export interface AgentManifest {
         readonly attestation?: string;
         readonly description?: string;
     };
-    readonly endpoints?: readonly {
-        readonly type: AgentEndpointType;
-        readonly url: string;
-    }[];
+    readonly endpoints?: readonly AgentEndpoint[];
     readonly capabilities?: {
         readonly schema?: string;
-        readonly url: string;
+        /** Required in v1; optional in v2 when `items` is present. */
+        readonly url?: string;
+        /** v2: the searchable capability list. */
+        readonly items?: readonly AgentCapability[];
     };
     readonly payment?: {
+        /** v2: WHO gets paid — always an @name, never an address. The address is
+         *  resolved from the chain under the one payment rule (W16,
+         *  `paymentAddressFor`, the program's `name_pays_to`), so it cannot drift
+         *  from the name. Required in v2 whenever anything is priced. */
+        readonly payTo?: {
+            readonly name: string;
+        };
+        /** v2: accepted payment methods. Required in v2 whenever anything is priced. */
+        readonly methods?: readonly AgentPaymentMethod[];
+        /** v1 mirror of the address records (still accepted in v2, never used as
+         *  a v2 payTo). */
         readonly addresses?: readonly {
             readonly coinType: number;
             readonly address: string;
@@ -79,6 +147,8 @@ export interface AgentManifest {
         };
     };
 }
+/** v2 id grammar (capability / endpoint / method ids): a lowercase slug. */
+export declare const AGENT_ID_RE: RegExp;
 /** URL rule (`docs/agent-records.md` §2): every URL field is `https://`
  *  ONLY, except `agent.manifest`'s own record value, which may also be
  *  `ipfs://<cid>` (`allowIpfs`). */
@@ -120,6 +190,56 @@ export type ManifestValidationError = {
 } | {
     readonly code: "overclaims-verified";
     readonly coinType: number;
+}
+/** A v2 field has the wrong JSON type, or an array is over its cap. */
+ | {
+    readonly code: "bad-field";
+    readonly field: string;
+} | {
+    readonly code: "bad-id";
+    readonly field: string;
+} | {
+    readonly code: "duplicate-id";
+    readonly field: string;
+    readonly id: string;
+}
+/** An endpoint lists a capability id `capabilities.items[]` doesn't define. */
+ | {
+    readonly code: "unknown-capability";
+    readonly id: string;
+}
+/** A capability names an endpoint id `endpoints[]` doesn't define. */
+ | {
+    readonly code: "unknown-endpoint";
+    readonly id: string;
+} | {
+    readonly code: "bad-price";
+    readonly field: string;
+}
+/** Something is priced but `payment.payTo` is absent. */
+ | {
+    readonly code: "missing-payto";
+}
+/** `payment.payTo.name` is not this manifest's own `x1id.name`. */
+ | {
+    readonly code: "payto-name-mismatch";
+}
+/** `payment.payTo` carries an address (or anything but `name`) — v2 never
+ *  accepts a free-form pay-to address; it is resolved from the name. */
+ | {
+    readonly code: "free-form-payto";
+}
+/** Something is priced but `payment.methods` is empty / absent. */
+ | {
+    readonly code: "missing-payment-method";
+} | {
+    readonly code: "bad-payment-method";
+    readonly field: string;
+}
+/** A price's mint is not settled by any listed payment method. */
+ | {
+    readonly code: "unsupported-price-mint";
+    readonly mint: string;
 };
 export type ManifestValidationResult = {
     readonly ok: true;
@@ -134,6 +254,62 @@ export type ManifestValidationResult = {
  * itself over what the caller already knows to be true on-chain.
  */
 export declare function validateManifest(raw: unknown, opts: ValidateManifestOptions): ManifestValidationResult;
+/** Every capability id a (validated) manifest advertises: v2 `items[].id`
+ *  plus endpoint tags, deduped, in first-seen order. `[]` for v1. Used by the
+ *  directory to index capability search. */
+export declare function manifestCapabilities(manifest: AgentManifest): string[];
+/** One priced thing a manifest offers (flattened for display / discovery). */
+export interface AgentOffer {
+    /** Capability id, or null for an endpoint-level price. */
+    readonly capability: string | null;
+    /** Endpoint id, when known. */
+    readonly endpoint: string | null;
+    /** Endpoint URL, when the price is (or the capability points) at one. */
+    readonly url: string | null;
+    readonly endpointType: AgentEndpointType | null;
+    readonly price: AgentPrice;
+}
+/** Flatten a v2 manifest's prices into offers. `[]` for v1. */
+export declare function manifestOffers(manifest: AgentManifest): AgentOffer[];
+/** The chain a payment method settles on, for the W16 rule. `null` = a
+ *  network the rule cannot resolve (the method is then flagged unpayable). */
+export declare function paymentMethodChain(method: Pick<AgentPaymentMethod, "rail" | "network">): Chain | null;
+export interface ResolvedPaymentMethod {
+    readonly method: AgentPaymentMethod;
+    readonly chain: Chain | null;
+    /** The address to pay for this method, resolved from the @name — or null
+     *  when the name has no honest address on that chain (see `reason`). */
+    readonly payTo: PaymentResolution | null;
+    readonly reason?: "unsupported-network" | "no-verified-record" | "no-authority";
+}
+/**
+ * Resolve a v2 manifest's payTo per payment method from the CHAIN — never from
+ * the manifest. `records` are the payTo name's decoded address records,
+ * `authority` its current authority (owner / pNFT holder), exactly the inputs
+ * of {@link paymentAddressFor} (W16, the program's `name_pays_to`).
+ *
+ * The owner fallback is only meaningful on SVM chains (X1 / SOL — the
+ * authority is an SVM key); on ETH only a live VERIFIED record pays, else the
+ * method has no address (`no-verified-record`), never the owner's SVM key.
+ */
+export declare function resolveManifestPayTo(manifest: AgentManifest, input: {
+    readonly records: readonly PaymentRecordLike[];
+    readonly authority: string | null;
+}): ResolvedPaymentMethod[];
+/** A divergence between what a manifest SAYS about its pay-to and what the
+ *  chain resolves for the name. Reported, never silently resolved. */
+export interface PayToWarning {
+    readonly code: "payto-diverges";
+    readonly coinType: number;
+    /** The address the manifest mirrors. */
+    readonly claimed: string;
+    /** The W16-resolved address for that chain. */
+    readonly resolved: string;
+}
+/** Flag every `payment.addresses[]` mirror entry (v1 or v2) whose chain has a
+ *  W16-resolved address that differs. `resolved` maps chain → the address
+ *  {@link paymentAddressFor} returned for the name. */
+export declare function payToWarnings(manifest: AgentManifest, resolved: Partial<Record<Chain, string>>): PayToWarning[];
 /** Pick the agent-related well-known keys out of a handle's live text
  *  records (pass the output of `liveTextRecords` — stale entries excluded
  *  already, matching every other read path's convention). */