passkey-kit 0.12.1 → 0.14.0

package/dist/index.js

@@ -0,0 +1,36 @@
+/**
+ * Passkey Kit — create and use smart-wallet accounts on Stellar with WebAuthn
+ * passkeys.
+ *
+ * Storage adapters live under the `passkey-kit/storage` subpath; the server-only
+ * entrypoint lives under `passkey-kit/server`.
+ *
+ * @packageDocumentation
+ */
+// Core client. (The server-only `PasskeyServer` lives at `passkey-kit/server`
+// so it — and the relayer secret it holds — can never be bundled into browser
+// code.)
+export { PasskeyKit, } from "./kit.js";
+export { SACClient, buildTokenTransferHostFunction } from "./sac.js";
+// Generated contract client
+export { Client as PasskeyClient } from "passkey-kit-sdk";
+// Signer abstraction
+export { PasskeySigner, Ed25519Signer, PolicySigner, } from "./signers.js";
+// Signer-key helpers, storage + result types
+export { SignerKey, SignerStore, } from "./types.js";
+// Typed errors
+export { PasskeyKitError, PasskeyKitErrorCode, ConfigurationError, WalletNotConnectedError, WalletOwnershipError, WebAuthnError, SigningError, SignerNotFoundError, SimulationError, SubmissionError, ValidationError, IndexerError, RelayerError, ContractError, wrapError, } from "./errors.js";
+// Contract-error decoding
+export { CONTRACT_ERROR_REGISTRY, contractErrorFromCode, decodeContractError, } from "./contract-errors.js";
+// Indexer abstraction. Mercury's hosted passkey-indexer is keyless, so the
+// `MercuryIndexer` backend is browser-safe and exported here (no `/server` gate).
+export { MercuryIndexer, mercuryPasskeyIndexerUrl, MERCURY_PASSKEY_INDEXER_URLS, lookupWithRetry, } from "./indexer/index.js";
+// Events
+export { PasskeyEventEmitter, } from "./events.js";
+// Crypto / derivation helpers
+export { deriveContractAddress, extractPublicKeyFromAttestation, compactSignature, generateChallenge, isOnP256Curve, } from "./utils.js";
+// Client-side validation
+export { validateAddress, validateAmount, validateExpiration, validateSecp256r1PublicKey, } from "./validation.js";
+// Package metadata
+export { VERSION, NAME } from "./version.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;;;;;;;;GAQG;AAEH,8EAA8E;AAC9E,8EAA8E;AAC9E,SAAS;AACT,OAAO,EACL,UAAU,GAIX,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,SAAS,EAAE,8BAA8B,EAAE,MAAM,UAAU,CAAC;AAErE,4BAA4B;AAC5B,OAAO,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE1D,qBAAqB;AACrB,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,GAKb,MAAM,cAAc,CAAC;AAEtB,6CAA6C;AAC7C,OAAO,EACL,SAAS,EACT,WAAW,GAWZ,MAAM,YAAY,CAAC;AAEpB,eAAe;AACf,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,SAAS,GACV,MAAM,aAAa,CAAC;AAErB,0BAA0B;AAC1B,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,GAGpB,MAAM,sBAAsB,CAAC;AAE9B,2EAA2E;AAC3E,kFAAkF;AAClF,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,4BAA4B,EAC5B,eAAe,GAQhB,MAAM,oBAAoB,CAAC;AAE5B,SAAS;AACT,OAAO,EACL,mBAAmB,GAIpB,MAAM,aAAa,CAAC;AAErB,8BAA8B;AAC9B,OAAO,EACL,qBAAqB,EACrB,+BAA+B,EAC/B,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,yBAAyB;AACzB,OAAO,EACL,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,mBAAmB;AACnB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC"}

package/dist/indexer/codec.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ScVal encoding helpers for the Mercury indexer backend.
+ *
+ * The hosted passkey-indexer returns fully-decoded signer JSON, so the only
+ * on-chain encoding the backend still needs is the contract `SignerKey` ScVal —
+ * for the temporary-signer eviction probe (`contractDataExists`) and the
+ * reverse-lookup on-chain confirmation (`getSigner`). Both go through the
+ * contract Spec built from a throwaway client.
+ *
+ * @packageDocumentation
+ */
+import { xdr } from "@stellar/stellar-sdk";
+import type { Spec as ContractSpec } from "@stellar/stellar-sdk/contract";
+import { SignerKey } from "../types.js";
+export declare function walletSpec(): ContractSpec;
+/** Encode an SDK-side {@link SignerKey} into its contract `SignerKey` ScVal. */
+export declare function signerKeyToContractScVal(key: SignerKey): xdr.ScVal;
+//# sourceMappingURL=codec.d.ts.map

package/dist/indexer/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/indexer/codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAC3C,OAAO,KAAK,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE1E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAOxC,wBAAgB,UAAU,IAAI,YAAY,CAYzC;AAED,gFAAgF;AAChF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,SAAS,GAAG,GAAG,CAAC,KAAK,CAElE"}

package/dist/indexer/codec.js

@@ -0,0 +1,32 @@
+/**
+ * ScVal encoding helpers for the Mercury indexer backend.
+ *
+ * The hosted passkey-indexer returns fully-decoded signer JSON, so the only
+ * on-chain encoding the backend still needs is the contract `SignerKey` ScVal —
+ * for the temporary-signer eviction probe (`contractDataExists`) and the
+ * reverse-lookup on-chain confirmation (`getSigner`). Both go through the
+ * contract Spec built from a throwaway client.
+ *
+ * @packageDocumentation
+ */
+import { Client as PasskeyClient } from "passkey-kit-sdk";
+import { signerKeyToScVal } from "../kit/auth-payload.js";
+import { toContractSignerKey } from "../kit/wallet-ops.js";
+// The contract Spec is network-independent, so memoize a single instance built
+// from a throwaway client (constructing a client does not touch the network).
+let cachedSpec;
+export function walletSpec() {
+    if (!cachedSpec) {
+        cachedSpec = new PasskeyClient({
+            contractId: "CAXCIOHU357VIEDAWOU6YZUL3IU3CDFLCHA6O4PT2VDICDX4PNGSVZDL",
+            networkPassphrase: "Test SDF Network ; September 2015",
+            rpcUrl: "https://rpc.invalid",
+        }).spec;
+    }
+    return cachedSpec;
+}
+/** Encode an SDK-side {@link SignerKey} into its contract `SignerKey` ScVal. */
+export function signerKeyToContractScVal(key) {
+    return signerKeyToScVal(walletSpec(), toContractSignerKey(key));
+}
+//# sourceMappingURL=codec.js.map

package/dist/indexer/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/indexer/codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,+EAA+E;AAC/E,8EAA8E;AAC9E,IAAI,UAAoC,CAAC;AACzC,MAAM,UAAU,UAAU;IACxB,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,UAAU,GACR,IAAI,aAAa,CAAC;YAChB,UAAU,EACR,0DAA0D;YAC5D,iBAAiB,EAAE,mCAAmC;YACtD,MAAM,EAAE,qBAAqB;SAC9B,CACF,CAAC,IAAI,CAAC;IACT,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,wBAAwB,CAAC,GAAc;IACrD,OAAO,gBAAgB,CAAC,UAAU,EAAE,EAAE,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC;AAClE,CAAC"}

package/dist/indexer/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Indexer abstraction barrel.
+ *
+ * The {@link SignerIndexer} interface + {@link WalletSigner} types, the pure
+ * {@link lookupWithRetry} helper, and the {@link MercuryIndexer} backend are all
+ * browser-safe — Mercury's hosted passkey-indexer is keyless, so nothing here
+ * holds a secret — and the whole module is re-exported from the main
+ * `passkey-kit` entry.
+ *
+ * @packageDocumentation
+ */
+export type { SignerIndexer, WalletSigner, IndexerHealth, SignerStatus, SignerStorageClass, FindWalletsHardeningDeps, } from "./types.js";
+export { MercuryIndexer, mercuryPasskeyIndexerUrl, type MercuryIndexerConfig, } from "./mercury.js";
+export { MERCURY_PASSKEY_INDEXER_URLS } from "../constants.js";
+/**
+ * Poll a lookup until it satisfies `predicate` (defaults to "non-empty"), for
+ * post-write discovery assertions where the indexer lags the ledger. Defaults
+ * to 20 attempts × 2s.
+ */
+export declare function lookupWithRetry<T>(fn: () => Promise<T[]>, options?: {
+    attempts?: number;
+    delayMs?: number;
+    predicate?: (result: T[]) => boolean;
+}): Promise<T[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/indexer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/indexer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,YAAY,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,EAAE,CAAC,EACtB,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC;CACtC,GACA,OAAO,CAAC,CAAC,EAAE,CAAC,CAcd"}

package/dist/indexer/index.js

@@ -0,0 +1,34 @@
+/**
+ * Indexer abstraction barrel.
+ *
+ * The {@link SignerIndexer} interface + {@link WalletSigner} types, the pure
+ * {@link lookupWithRetry} helper, and the {@link MercuryIndexer} backend are all
+ * browser-safe — Mercury's hosted passkey-indexer is keyless, so nothing here
+ * holds a secret — and the whole module is re-exported from the main
+ * `passkey-kit` entry.
+ *
+ * @packageDocumentation
+ */
+export { MercuryIndexer, mercuryPasskeyIndexerUrl, } from "./mercury.js";
+export { MERCURY_PASSKEY_INDEXER_URLS } from "../constants.js";
+/**
+ * Poll a lookup until it satisfies `predicate` (defaults to "non-empty"), for
+ * post-write discovery assertions where the indexer lags the ledger. Defaults
+ * to 20 attempts × 2s.
+ */
+export async function lookupWithRetry(fn, options) {
+    const attempts = options?.attempts ?? 20;
+    const delayMs = options?.delayMs ?? 2000;
+    const predicate = options?.predicate ?? ((r) => r.length > 0);
+    let last = [];
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        last = await fn();
+        if (predicate(last))
+            return last;
+        if (attempt < attempts - 1) {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    return last;
+}
+//# sourceMappingURL=index.js.map

package/dist/indexer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/indexer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAWH,OAAO,EACL,cAAc,EACd,wBAAwB,GAEzB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,EAAsB,EACtB,OAIC;IAED,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC;IACzC,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE9D,IAAI,IAAI,GAAQ,EAAE,CAAC;IACnB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,QAAQ,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QACvD,IAAI,GAAG,MAAM,EAAE,EAAE,CAAC;QAClB,IAAI,SAAS,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACjC,IAAI,OAAO,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/indexer/mercury.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Mercury hosted passkey-indexer backend.
+ *
+ * Queries Mercury's public, **keyless** passkey-indexer REST API — no JWT, no
+ * API key — which indexes passkey-kit smart-wallet signers on both networks with
+ * full history across both signer generations (legacy `("sw_v1", …)` tuple
+ * events and the v1 typed `#[contractevent]`s). The endpoint returns fully
+ * decoded signer rows, so this backend maps JSON straight onto {@link WalletSigner}
+ * with no XDR round-trip.
+ *
+ * Base URLs (see {@link mercuryPasskeyIndexerUrl}):
+ *   `https://{testnet,mainnet}.mercurydata.app/rest/passkey-indexer`
+ *     GET /                              -> `{ service, status }` health
+ *     GET /api/wallet/:contractId        -> signers (this backend's getSigners)
+ *     GET /api/lookup/:credentialId      -> wallets by passkey keyId (hex)
+ *     GET /api/lookup/address/:address   -> wallets by ed25519 (G…) / policy (C…)
+ *     GET /api/stats                     -> indexer statistics
+ *
+ * Docs: https://docs.mercurydata.app/smart-wallet-indexers/introduction-1
+ *
+ * @packageDocumentation
+ */
+import { type Server } from "@stellar/stellar-sdk/rpc";
+import { SignerKey } from "../types.js";
+import type { FindWalletsHardeningDeps, IndexerHealth, SignerIndexer, WalletSigner } from "./types.js";
+/**
+ * Resolve the hosted passkey-indexer base URL for a network. Mercury indexes
+ * both testnet and mainnet; any other network returns `undefined` (no hosted
+ * endpoint — pass an explicit `url` to point at a self-hosted instance).
+ */
+export declare function mercuryPasskeyIndexerUrl(networkPassphrase: string): string | undefined;
+export interface MercuryIndexerConfig {
+    /**
+     * Hosted passkey-indexer base URL, e.g.
+     * `https://testnet.mercurydata.app/rest/passkey-indexer`. Keyless (public
+     * REST). Prefer {@link MercuryIndexer.forNetwork} to resolve this per network.
+     */
+    url: string;
+    /**
+     * RPC server — enables the temporary-signer eviction probe and lets
+     * `findWallets` confirm reverse-lookup candidates on-chain.
+     */
+    rpc?: Server;
+    /**
+     * Deps that let `findWallets` confirm a candidate by deterministic derivation
+     * from the keyId, skipping an RPC round-trip.
+     */
+    hardening?: FindWalletsHardeningDeps;
+    /** Injectable fetch (tests / non-global runtimes). Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+}
+export declare class MercuryIndexer implements SignerIndexer {
+    private readonly config;
+    constructor(config: MercuryIndexerConfig);
+    /**
+     * Null-tolerant factory: resolve the hosted base URL for `networkPassphrase`
+     * (unless `url` is given), returning `null` when the network has no hosted
+     * endpoint and no explicit `url` — callers treat `null` as "discovery
+     * disabled".
+     */
+    static forNetwork(config: Omit<MercuryIndexerConfig, "url"> & {
+        url?: string;
+    }, networkPassphrase: string): MercuryIndexer | null;
+    /**
+     * GET a passkey-indexer route. Returns the parsed JSON, or `null` on a `404`
+     * (a genuine "not found" is an answer, not a failure). Any other non-2xx, a
+     * timeout, or a transport error throws an {@link IndexerError}.
+     */
+    private get;
+    getSigners(wallet: string): Promise<WalletSigner[]>;
+    /**
+     * Whether the signer's temporary ledger entry still exists on-chain. Probes by
+     * the `SignerKey` ScVal — the exact key the contract stores the entry under
+     * (`storage().temporary().set::<SignerKey, SignerVal>`) — so it actually
+     * matches. Throws on a transport error (caller decides eviction only from a
+     * genuine not-found).
+     */
+    private entryExists;
+    findWallets(key: SignerKey): Promise<string[]>;
+    /**
+     * Harden the reverse lookup (#598 F3): keep a candidate only if it is either
+     * the deterministic derivation of the keyId OR still holds the signer entry
+     * on-chain — never trust an unverified indexer row.
+     *
+     * Fail-CLOSED: when candidates exist but no confirmation route
+     * does — no `rpc`, and no usable derivation (`hardening` only covers
+     * Secp256r1 keys) — this throws instead of returning unconfirmed rows. An
+     * unverifiable answer must never be handed to a caller that will route
+     * deposits or identity to it.
+     */
+    private confirmCandidates;
+    health(): Promise<IndexerHealth>;
+}
+//# sourceMappingURL=mercury.d.ts.map

package/dist/indexer/mercury.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mercury.d.ts","sourceRoot":"","sources":["../../src/indexer/mercury.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,SAAS,EAAqB,MAAM,aAAa,CAAC;AAS3D,OAAO,KAAK,EACV,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAC;AAIpB;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,iBAAiB,EAAE,MAAM,GACxB,MAAM,GAAG,SAAS,CAMpB;AAmDD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,qBAAa,cAAe,YAAW,aAAa;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,oBAAoB;IASzD;;;;;OAKG;IACH,MAAM,CAAC,UAAU,CACf,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,KAAK,CAAC,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,EAC5D,iBAAiB,EAAE,MAAM,GACxB,cAAc,GAAG,IAAI;IAMxB;;;;OAIG;YACW,GAAG;IAqCX,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA8BzD;;;;;;OAMG;YACW,WAAW;IASnB,WAAW,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAapD;;;;;;;;;;OAUG;YACW,iBAAiB;IAsCzB,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC;CAiBvC"}

package/dist/indexer/mercury.js

@@ -0,0 +1,245 @@
+/**
+ * Mercury hosted passkey-indexer backend.
+ *
+ * Queries Mercury's public, **keyless** passkey-indexer REST API — no JWT, no
+ * API key — which indexes passkey-kit smart-wallet signers on both networks with
+ * full history across both signer generations (legacy `("sw_v1", …)` tuple
+ * events and the v1 typed `#[contractevent]`s). The endpoint returns fully
+ * decoded signer rows, so this backend maps JSON straight onto {@link WalletSigner}
+ * with no XDR round-trip.
+ *
+ * Base URLs (see {@link mercuryPasskeyIndexerUrl}):
+ *   `https://{testnet,mainnet}.mercurydata.app/rest/passkey-indexer`
+ *     GET /                              -> `{ service, status }` health
+ *     GET /api/wallet/:contractId        -> signers (this backend's getSigners)
+ *     GET /api/lookup/:credentialId      -> wallets by passkey keyId (hex)
+ *     GET /api/lookup/address/:address   -> wallets by ed25519 (G…) / policy (C…)
+ *     GET /api/stats                     -> indexer statistics
+ *
+ * Docs: https://docs.mercurydata.app/smart-wallet-indexers/introduction-1
+ *
+ * @packageDocumentation
+ */
+import { Networks } from "@stellar/stellar-sdk";
+import { Durability } from "@stellar/stellar-sdk/rpc";
+import { SignerKey } from "../types.js";
+import { IndexerError, PasskeyKitErrorCode } from "../errors.js";
+import { DEFAULT_INDEXER_TIMEOUT_MS, MERCURY_PASSKEY_INDEXER_URLS, } from "../constants.js";
+import { getSigner } from "../kit/wallet-ops.js";
+import { contractDataExists } from "../rpc-data.js";
+import base64url from "../base64url.js";
+import { signerKeyToContractScVal, walletSpec } from "./codec.js";
+import { deriveContractAddress } from "../utils.js";
+/**
+ * Resolve the hosted passkey-indexer base URL for a network. Mercury indexes
+ * both testnet and mainnet; any other network returns `undefined` (no hosted
+ * endpoint — pass an explicit `url` to point at a self-hosted instance).
+ */
+export function mercuryPasskeyIndexerUrl(networkPassphrase) {
+    if (networkPassphrase === Networks.PUBLIC)
+        return MERCURY_PASSKEY_INDEXER_URLS.mainnet;
+    if (networkPassphrase === Networks.TESTNET)
+        return MERCURY_PASSKEY_INDEXER_URLS.testnet;
+    return undefined;
+}
+export class MercuryIndexer {
+    config;
+    constructor(config) {
+        this.config = config;
+        if (!config.url) {
+            throw new IndexerError("MercuryIndexer requires a url", PasskeyKitErrorCode.INDEXER_NOT_CONFIGURED);
+        }
+    }
+    /**
+     * Null-tolerant factory: resolve the hosted base URL for `networkPassphrase`
+     * (unless `url` is given), returning `null` when the network has no hosted
+     * endpoint and no explicit `url` — callers treat `null` as "discovery
+     * disabled".
+     */
+    static forNetwork(config, networkPassphrase) {
+        const url = config.url ?? mercuryPasskeyIndexerUrl(networkPassphrase);
+        if (!url)
+            return null;
+        return new MercuryIndexer({ ...config, url });
+    }
+    /**
+     * GET a passkey-indexer route. Returns the parsed JSON, or `null` on a `404`
+     * (a genuine "not found" is an answer, not a failure). Any other non-2xx, a
+     * timeout, or a transport error throws an {@link IndexerError}.
+     */
+    async get(path) {
+        const doFetch = this.config.fetch ?? fetch;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), DEFAULT_INDEXER_TIMEOUT_MS);
+        try {
+            const response = await doFetch(`${this.config.url}${path}`, {
+                signal: controller.signal,
+            });
+            if (response.status === 404)
+                return null;
+            if (!response.ok) {
+                const body = await response.text().catch(() => "");
+                throw new IndexerError(`Mercury passkey-indexer GET ${path} failed (${response.status}): ${body.slice(0, 200)}`, PasskeyKitErrorCode.INDEXER_REQUEST_FAILED, { path, status: response.status });
+            }
+            return (await response.json());
+        }
+        catch (err) {
+            if (err instanceof IndexerError)
+                throw err;
+            const aborted = err instanceof Error && err.name === "AbortError";
+            throw new IndexerError(aborted
+                ? `Mercury passkey-indexer GET ${path} timed out`
+                : String(err), PasskeyKitErrorCode.INDEXER_REQUEST_FAILED, { path }, err instanceof Error ? err : undefined);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async getSigners(wallet) {
+        const res = await this.get(`/api/wallet/${wallet}`);
+        if (!res)
+            return []; // 404: the wallet has no indexed signers
+        const signers = res.signers.map(jsonToWalletSigner);
+        // Eviction probe: the indexer derives `status` from signer add/update/remove
+        // events and cannot observe temporary-entry TTL eviction, so confirm each
+        // live temporary signer still exists on-chain (#598 F6 / audit H2). A genuine
+        // not-found => evicted; a transport error leaves the reported status intact.
+        if (this.config.rpc) {
+            for (const signer of signers) {
+                if (signer.storage === "temporary" && signer.status === "live") {
+                    try {
+                        if (!(await this.entryExists(wallet, signer.key))) {
+                            signer.status = "evicted";
+                        }
+                    }
+                    catch {
+                        // Transport error (429/5xx/timeout): eviction undeterminable — keep
+                        // the row as the indexer reported it rather than false-evicting.
+                    }
+                }
+            }
+        }
+        return signers;
+    }
+    /**
+     * Whether the signer's temporary ledger entry still exists on-chain. Probes by
+     * the `SignerKey` ScVal — the exact key the contract stores the entry under
+     * (`storage().temporary().set::<SignerKey, SignerVal>`) — so it actually
+     * matches. Throws on a transport error (caller decides eviction only from a
+     * genuine not-found).
+     */
+    async entryExists(wallet, key) {
+        return contractDataExists(this.config.rpc, wallet, signerKeyToContractScVal(key), Durability.Temporary);
+    }
+    async findWallets(key) {
+        // Secp256r1 keys are looked up by hex credential id; ed25519/policy keys by
+        // their strkey address. The SDK carries the Secp256r1 keyId as base64url, so
+        // convert to the hex the credential-id route expects.
+        const path = key.key === "Secp256r1"
+            ? `/api/lookup/${base64url.toBuffer(key.value).toString("hex")}`
+            : `/api/lookup/address/${key.value}`;
+        const res = await this.get(path);
+        const candidates = res?.wallets.map((w) => w.contract_id) ?? [];
+        return this.confirmCandidates(candidates, key);
+    }
+    /**
+     * Harden the reverse lookup (#598 F3): keep a candidate only if it is either
+     * the deterministic derivation of the keyId OR still holds the signer entry
+     * on-chain — never trust an unverified indexer row.
+     *
+     * Fail-CLOSED: when candidates exist but no confirmation route
+     * does — no `rpc`, and no usable derivation (`hardening` only covers
+     * Secp256r1 keys) — this throws instead of returning unconfirmed rows. An
+     * unverifiable answer must never be handed to a caller that will route
+     * deposits or identity to it.
+     */
+    async confirmCandidates(candidates, key) {
+        const { rpc, hardening } = this.config;
+        const derived = hardening && key.key === "Secp256r1"
+            ? deriveContractAddress(base64url.toBuffer(key.value), hardening.deployerPublicKey, hardening.networkPassphrase)
+            : undefined;
+        if (candidates.length > 0 && !rpc && !derived) {
+            throw new IndexerError("Cannot confirm reverse-lookup candidates: configure `rpc` (any key type) " +
+                "or `hardening` (Secp256r1 derivation) — unconfirmed indexer rows are never returned", PasskeyKitErrorCode.INDEXER_NOT_CONFIGURED, { key: key.key, candidates: candidates.length });
+        }
+        const confirmed = [];
+        for (const candidate of candidates) {
+            if (candidate === derived) {
+                confirmed.push(candidate);
+                continue;
+            }
+            if (rpc) {
+                const signer = await getSigner({ rpc, spec: walletSpec() }, candidate, key);
+                if (signer)
+                    confirmed.push(candidate);
+            }
+        }
+        return confirmed;
+    }
+    async health() {
+        try {
+            const res = await this.get("/");
+            if (res?.status === "ok")
+                return { ok: true, backend: "mercury" };
+            return {
+                ok: false,
+                backend: "mercury",
+                detail: `unexpected health payload: ${JSON.stringify(res)}`,
+            };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                backend: "mercury",
+                detail: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+}
+/** Map a passkey-indexer JSON signer key onto the SDK-side {@link SignerKey}. */
+function keyFromJson(k) {
+    switch (k.type) {
+        case "secp256r1":
+            // The indexer renders the credential id as lowercase hex; the SDK carries
+            // it as base64url (matches StoredPasskey.keyId and the contract SignerKey).
+            return SignerKey.Secp256r1(Buffer.from(k.value, "hex").toString("base64url"));
+        case "ed25519":
+            return SignerKey.Ed25519(k.value); // already a `G…` strkey
+        case "policy":
+            return SignerKey.Policy(k.value); // already a `C…` strkey
+    }
+}
+/** Decode the JSON limits object into the SDK's {@link SignerLimits}. */
+function limitsFromJson(limits) {
+    if (limits === undefined)
+        return undefined; // unlimited (contract `None`)
+    // `{}` -> an empty Map: a scoped-but-empty limit set = deny-all, matching the
+    // contract's fail-closed `Some(empty)` semantics.
+    const out = new Map();
+    for (const [contract, keys] of Object.entries(limits)) {
+        out.set(contract, keys === null ? undefined : keys.map(keyFromJson));
+    }
+    return out;
+}
+/** Map a fully-decoded passkey-indexer signer row onto a {@link WalletSigner}. */
+function jsonToWalletSigner(json) {
+    const publicKey = json.publicKey
+        ? new Uint8Array(Buffer.from(json.publicKey, "hex"))
+        : undefined;
+    // WalletSigner.expiration is contract-typed as UNIX seconds. Only carry it
+    // when the indexer reports the `unix` (v1) unit; a legacy `ledger`-sequence
+    // expiration is conveyed through the indexer-derived `status`, never smuggled
+    // into the seconds field where a consumer would misread it as a timestamp.
+    const expiration = json.expiration != null && json.expiration_unit !== "ledger"
+        ? json.expiration
+        : undefined;
+    return {
+        key: keyFromJson(json.key),
+        ...(publicKey ? { publicKey } : {}),
+        ...(expiration != null ? { expiration } : {}),
+        limits: limitsFromJson(json.limits),
+        storage: json.storage,
+        status: json.status,
+    };
+}
+//# sourceMappingURL=mercury.js.map

package/dist/indexer/mercury.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mercury.js","sourceRoot":"","sources":["../../src/indexer/mercury.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAe,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,SAAS,EAAqB,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,SAAS,MAAM,iBAAiB,CAAC;AAOxC,OAAO,EAAE,wBAAwB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,iBAAyB;IAEzB,IAAI,iBAAiB,KAAK,QAAQ,CAAC,MAAM;QACvC,OAAO,4BAA4B,CAAC,OAAO,CAAC;IAC9C,IAAI,iBAAiB,KAAK,QAAQ,CAAC,OAAO;QACxC,OAAO,4BAA4B,CAAC,OAAO,CAAC;IAC9C,OAAO,SAAS,CAAC;AACnB,CAAC;AAwED,MAAM,OAAO,cAAc;IACI;IAA7B,YAA6B,MAA4B;QAA5B,WAAM,GAAN,MAAM,CAAsB;QACvD,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;YAChB,MAAM,IAAI,YAAY,CACpB,+BAA+B,EAC/B,mBAAmB,CAAC,sBAAsB,CAC3C,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,UAAU,CACf,MAA4D,EAC5D,iBAAyB;QAEzB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,wBAAwB,CAAC,iBAAiB,CAAC,CAAC;QACtE,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QACtB,OAAO,IAAI,cAAc,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IAChD,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,GAAG,CAAI,IAAY;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC;QAC3C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CACxB,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EACxB,0BAA0B,CAC3B,CAAC;QACF,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,EAAE,EAAE;gBAC1D,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,IAAI,CAAC;YACzC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;gBACnD,MAAM,IAAI,YAAY,CACpB,+BAA+B,IAAI,YAAY,QAAQ,CAAC,MAAM,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EACxF,mBAAmB,CAAC,sBAAsB,EAC1C,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAClC,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAM,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,YAAY;gBAAE,MAAM,GAAG,CAAC;YAC3C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,CAAC;YAClE,MAAM,IAAI,YAAY,CACpB,OAAO;gBACL,CAAC,CAAC,+BAA+B,IAAI,YAAY;gBACjD,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EACf,mBAAmB,CAAC,sBAAsB,EAC1C,EAAE,IAAI,EAAE,EACR,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CACvC,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,MAAc;QAC7B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CACxB,eAAe,MAAM,EAAE,CACxB,CAAC;QACF,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,CAAC,CAAC,yCAAyC;QAE9D,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAEpD,6EAA6E;QAC7E,0EAA0E;QAC1E,8EAA8E;QAC9E,6EAA6E;QAC7E,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;YACpB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,MAAM,CAAC,OAAO,KAAK,WAAW,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;oBAC/D,IAAI,CAAC;wBACH,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;4BAClD,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC;wBAC5B,CAAC;oBACH,CAAC;oBAAC,MAAM,CAAC;wBACP,oEAAoE;wBACpE,iEAAiE;oBACnE,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,WAAW,CAAC,MAAc,EAAE,GAAc;QACtD,OAAO,kBAAkB,CACvB,IAAI,CAAC,MAAM,CAAC,GAAI,EAChB,MAAM,EACN,wBAAwB,CAAC,GAAG,CAAC,EAC7B,UAAU,CAAC,SAAS,CACrB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,GAAc;QAC9B,4EAA4E;QAC5E,6EAA6E;QAC7E,sDAAsD;QACtD,MAAM,IAAI,GACR,GAAG,CAAC,GAAG,KAAK,WAAW;YACrB,CAAC,CAAC,eAAe,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE;YAChE,CAAC,CAAC,uBAAuB,GAAG,CAAC,KAAK,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAA+B,IAAI,CAAC,CAAC;QAC/D,MAAM,UAAU,GAAG,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QAChE,OAAO,IAAI,CAAC,iBAAiB,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;;;;;OAUG;IACK,KAAK,CAAC,iBAAiB,CAC7B,UAAoB,EACpB,GAAc;QAEd,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QAEvC,MAAM,OAAO,GACX,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,WAAW;YAClC,CAAC,CAAC,qBAAqB,CACnB,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAC7B,SAAS,CAAC,iBAAiB,EAC3B,SAAS,CAAC,iBAAiB,CAC5B;YACH,CAAC,CAAC,SAAS,CAAC;QAEhB,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YAC9C,MAAM,IAAI,YAAY,CACpB,2EAA2E;gBACzE,qFAAqF,EACvF,mBAAmB,CAAC,sBAAsB,EAC1C,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,UAAU,CAAC,MAAM,EAAE,CAChD,CAAC;QACJ,CAAC;QAED,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;gBAC1B,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBAC1B,SAAS;YACX,CAAC;YACD,IAAI,GAAG,EAAE,CAAC;gBACR,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;gBAC5E,IAAI,MAAM;oBAAE,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAwC,GAAG,CAAC,CAAC;YACvE,IAAI,GAAG,EAAE,MAAM,KAAK,IAAI;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;YAClE,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,OAAO,EAAE,SAAS;gBAClB,MAAM,EAAE,8BAA8B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE;aAC5D,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,OAAO,EAAE,SAAS;gBAClB,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACzD,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAED,iFAAiF;AACjF,SAAS,WAAW,CAAC,CAAwB;IAC3C,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,WAAW;YACd,0EAA0E;YAC1E,4EAA4E;YAC5E,OAAO,SAAS,CAAC,SAAS,CACxB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAClD,CAAC;QACJ,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,wBAAwB;QAC7D,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,wBAAwB;IAC9D,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,SAAS,cAAc,CACrB,MAA0C;IAE1C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC,CAAC,8BAA8B;IAC1E,8EAA8E;IAC9E,kDAAkD;IAClD,MAAM,GAAG,GAAiB,IAAI,GAAG,EAAE,CAAC;IACpC,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACtD,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,kFAAkF;AAClF,SAAS,kBAAkB,CAAC,IAA8B;IACxD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS;QAC9B,CAAC,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QACpD,CAAC,CAAC,SAAS,CAAC;IAEd,2EAA2E;IAC3E,4EAA4E;IAC5E,8EAA8E;IAC9E,2EAA2E;IAC3E,MAAM,UAAU,GACd,IAAI,CAAC,UAAU,IAAI,IAAI,IAAI,IAAI,CAAC,eAAe,KAAK,QAAQ;QAC1D,CAAC,CAAC,IAAI,CAAC,UAAU;QACjB,CAAC,CAAC,SAAS,CAAC;IAEhB,OAAO;QACL,GAAG,EAAE,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC;QAC1B,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnC,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,MAAM,EAAE,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC;QACnC,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC;AACJ,CAAC"}

package/dist/indexer/stellar-indexer.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Stellar Indexer backend (Creit Tech), over `POST /v1/contract-data/`.
+ *
+ * The wallet stores one top-level contract-data entry per signer
+ * (`key = SignerKey ScVal`, `val = SignerVal`), so signer enumeration is a
+ * contract-scoped query and reverse lookup is derive-then-confirm: derive the
+ * wallet address from the keyId, then confirm the signer entry exists there.
+ * Removed signers appear as tombstoned (`deleted_at`) entries.
+ *
+ * WIRE FORMAT (F2-confirmed, todo 959 c2502 / todo 967):
+ * - The live API returns each entry's `key`/`val` as **JSON ScVal**, e.g.
+ *   `{"vec":[{"symbol":"Secp256r1"},{"bytes":"<hex>"}]}` — NOT base64 XDR. We
+ *   convert JSON ScVal -> `xdr.ScVal` ({@link jsonScValToXdr}) and reuse the
+ *   contract-spec decoders (`scValToSignerKey`/`decodeSignerVal`). The JSON
+ *   convention is the standard Stellar one: `symbol`, `bytes` (hex), `address`
+ *   (strkey), `vec` (array), `map` (`[{key,val}]`), `u64`/`i64` (string),
+ *   `u32`/`i32` (number), `bool`, `string`, `void` (None).
+ * - Entry fields: `id, contract_id, durability, key, val,
+ *   last_modified_ledger_seq, tx_meta_version, timestamp, created_at,
+ *   updated_at, deleted_at`.
+ *
+ * NETWORK: **the Stellar Indexer indexes MAINNET only** — a testnet contract
+ * returns HTTP 200 with zero entries (F2). To keep "unsupported network" from
+ * masquerading as "wallet has no signers", the backend is network-aware: use
+ * {@link StellarIndexerBackend.forNetwork} (returns `null` off mainnet), and a
+ * config pinned to a non-mainnet passphrase throws at construction rather than
+ * silently returning `[]`. Live validation therefore needs a mainnet v1 wallet
+ * (endgame-gated); until then this is unit-tested against the documented shape.
+ *
+ * @packageDocumentation
+ */
+import { Networks, xdr } from "@stellar/stellar-sdk";
+import { SignerKey } from "../types.js";
+import type { FindWalletsHardeningDeps, IndexerHealth, SignerIndexer, WalletSigner } from "./types.js";
+/** Max contract ids per contract-data request (API cap). */
+export declare const MAX_CONTRACTS_PER_QUERY = 25;
+/** The only network the Stellar Indexer indexes (mainnet). */
+export declare const STELLAR_INDEXER_NETWORK = Networks.PUBLIC;
+/**
+ * A raw contract-data entry (F2-confirmed live shape). `key`/`val` are JSON
+ * ScVal objects (see {@link jsonScValToXdr}), not base64-XDR strings; the extra
+ * fields are carried through untyped since only these four drive decoding.
+ */
+export interface StellarIndexerEntry {
+    /** JSON ScVal of the SignerKey. */
+    key: unknown;
+    /** JSON ScVal of the SignerVal. */
+    val: unknown;
+    durability: "persistent" | "temporary";
+    deleted_at: string | null;
+    id?: string;
+    contract_id?: string;
+    last_modified_ledger_seq?: number;
+    tx_meta_version?: string | number;
+    timestamp?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface StellarIndexerConfig {
+    /** Base URL, e.g. https://api.stellarindexer.com */
+    url: string;
+    /** Bearer access token (server-side secret). */
+    accessToken: string;
+    /**
+     * Network passphrase this backend serves. The Stellar Indexer indexes mainnet
+     * only; a non-mainnet passphrase throws at construction (prefer
+     * {@link StellarIndexerBackend.forNetwork} to get a `null` off mainnet). When
+     * omitted, mainnet is assumed.
+     */
+    networkPassphrase?: string;
+    /** Deps enabling derive-then-confirm reverse lookup. */
+    hardening?: FindWalletsHardeningDeps;
+    /** Clock source (seconds); injectable for tests. */
+    now?: () => number;
+}
+export declare class StellarIndexerBackend implements SignerIndexer {
+    private readonly config;
+    constructor(config: StellarIndexerConfig);
+    /**
+     * Network-aware factory: the backend for mainnet, or `null` for any other
+     * network (the Stellar Indexer doesn't index testnet, so "discovery disabled"
+     * is the honest answer — callers treat `null` as no-indexer rather than an
+     * empty signer set).
+     */
+    static forNetwork(config: Omit<StellarIndexerConfig, "networkPassphrase">, networkPassphrase: string): StellarIndexerBackend | null;
+    private nowSeconds;
+    private query;
+    getSigners(wallet: string): Promise<WalletSigner[]>;
+    /**
+     * Group entries by signer key and resolve status. A key with any live entry
+     * is live/expired; a key whose every entry is tombstoned (no live counterpart
+     * in either durability) is `removed`.
+     */
+    entriesToSigners(entries: StellarIndexerEntry[]): WalletSigner[];
+    /**
+     * Reverse lookup via derive-then-confirm. Only Secp256r1 keyIds are
+     * derivable; Ed25519/Policy signers are not discoverable through this backend
+     * (use Mercury's event-driven index for those).
+     */
+    findWallets(key: SignerKey): Promise<string[]>;
+    health(): Promise<IndexerHealth>;
+}
+/**
+ * Convert a Stellar JSON-ScVal object into an `xdr.ScVal`.
+ *
+ * The Stellar Indexer serializes ledger-entry `key`/`val` as JSON ScVal — a
+ * single-key object per value (`{"vec":[...]}`, `{"symbol":"…"}`, …). This is
+ * the inverse of that serialization for the variants a smart-wallet
+ * SignerKey/SignerVal can contain, letting the contract-spec decoders take over.
+ *
+ * Unknown variant keys THROW (never silently misdecode): an unexpected wire
+ * shape must surface as an error, not a wrong signer.
+ */
+export declare function jsonScValToXdr(json: unknown): xdr.ScVal;
+//# sourceMappingURL=stellar-indexer.d.ts.map

package/dist/indexer/stellar-indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stellar-indexer.d.ts","sourceRoot":"","sources":["../../src/indexer/stellar-indexer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAW,QAAQ,EAAiB,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIxC,OAAO,KAAK,EACV,wBAAwB,EACxB,aAAa,EACb,aAAa,EAEb,YAAY,EACb,MAAM,YAAY,CAAC;AASpB,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,kBAAkB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,GAAG,EAAE,OAAO,CAAC;IACb,mCAAmC;IACnC,GAAG,EAAE,OAAO,CAAC;IACb,UAAU,EAAE,YAAY,GAAG,WAAW,CAAC;IACvC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,qBAAsB,YAAW,aAAa;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,oBAAoB;IAmBzD;;;;;OAKG;IACH,MAAM,CAAC,UAAU,CACf,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EACvD,iBAAiB,EAAE,MAAM,GACxB,qBAAqB,GAAG,IAAI;IAK/B,OAAO,CAAC,UAAU;YAIJ,KAAK;IA2Cb,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAKzD;;;;OAIG;IACH,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,YAAY,EAAE;IA6BhE;;;;OAIG;IACG,WAAW,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA2B9C,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC;CAcvC;AAyBD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,GAAG,CAAC,KAAK,CAwEvD"}