@calimero-network/mero-js 26.11.0 → 27.0.0

package/dist/cloud/connect.d.ts

@@ -1,213 +0,0 @@
-/**
- * The second way to log in: sign in to Calimero Cloud instead of connecting to
- * a node.
- *
- * # Two connection shapes, one SDK
- *
- * `createMeroJs({ baseUrl })` is the node connection: point at a node, hold a
- * credential on it, and drive its admin API and JSON-RPC. It assumes the caller
- * has a node — their own, or one they have an account on.
- *
- * `connectCloud(...)` is for the caller who has neither. They sign in with the
- * identity they already use (Google, through the cloud), and the cloud answers
- * with an attested TEE relay serving their namespace. Writes then go through
- * delegated execution: signed here, run there, attributed here.
- *
- * The two are not alternatives to be picked at random — they answer different
- * questions. "Which node do I talk to?" has an answer for a desktop app and no
- * answer at all for a web app whose user has never installed anything. This
- * function is that missing answer, which is why the login step it replaces is
- * the *node URL prompt* rather than the authentication.
- *
- * `connectCloudWithAccount(...)` is the same connection reached by the other
- * door: the caller holds an account root and signs in as the account itself,
- * with no Google login anywhere in it. Identical from there on, deliberately —
- * which login proved who you are changes nothing about how a relay is found or
- * how a write is authorised.
- *
- * # What it does not do
- *
- * # Sealing the relay
- *
- * TLS in front of a relay ends outside its TD, at the host's ingress, where
- * the warrant and the method's arguments are readable. Pass `seal` (a quote
- * verifier) and every call to the relay is sealed to the key its attested TD
- * holds, so they are readable only inside it.
- *
- * It does not read state. A relay writes on the author's behalf; reads still
- * come from a node the client can query, or from the app's own projection of
- * the events it receives. `connectCloud` is deliberately narrow about this
- * rather than presenting a half-working `MeroJs` whose `admin` and `rpc` would
- * need a credential nobody holds.
- */
-import { CloudClient } from './cloud-client.js';
-import type { CloudClientConfig, CloudNamespace, CloudRelay } from './cloud-client.js';
-import { RelayClient } from '../relay/relay-client.js';
-import type { IntentResult, NonceSource } from '../relay/index.js';
-import { type Signer } from '../signer/signer.js';
-import { type RootSource } from '../account/account.js';
-import { MeroClient } from '../transport/mero-client.js';
-import type { Audience } from '../login/index.js';
-import type { VerifyTransportQuote } from '../sealed/sealed.js';
-export interface ConnectCloudOptions {
-    /** Defaults to the hosted cloud. */
-    cloudBaseUrl?: string;
-    /** A stored MDMA session token. Provide this or `googleIdToken`. */
-    sessionToken?: string;
-    /** A Google ID token to exchange for a session. Provide this or `sessionToken`. */
-    googleIdToken?: string;
-    /** Persist a new or rolling-refreshed session. See {@link CloudClientConfig.onSession}. */
-    onSession?: CloudClientConfig['onSession'];
-    /** The author's account, hex — whose writes these will be. */
-    authorAccount: string;
-    /** The author's `AccountProof<DeviceCert>`, hex-encoded borsh. */
-    authorProof: string;
-    /**
-     * The author device's ed25519 signing secret, hex. Never transmitted.
-     *
-     * Mutually exclusive with {@link ConnectCloudOptions.signer}, and the weaker
-     * of the two in a browser — a secret that exists as a string can be read by
-     * anything on the origin.
-     */
-    deviceSecret?: string;
-    /**
-     * The author device's signer — use instead of
-     * {@link ConnectCloudOptions.deviceSecret}.
-     *
-     * A browser wallet holds its device key as a non-extractable `CryptoKey`,
-     * which has no hex form to pass. Without this, that wallet — the case this
-     * whole path was built for — had to hand-assemble the `RelayClient` the
-     * one-call path exists to build.
-     */
-    signer?: Signer;
-    /**
-     * Which namespace to write in.
-     *
-     * Optional only when the user owns exactly one: guessing among several would
-     * pick a tenant for them, and the failure would be a write landing in the
-     * wrong place rather than an error.
-     */
-    namespaceId?: string;
-    /**
-     * Where nonces come from.
-     *
-     * Defaults to `localStorage`, keyed by the author's device public key, so a
-     * reload continues the sequence instead of replaying it. Pass
-     * {@link createMemoryNonceSource} explicitly for a process that owns its
-     * whole sequence, or your own source to coordinate across tabs.
-     */
-    nonces?: NonceSource;
-    /** Seconds a minted warrant stays presentable. Defaults to 300. */
-    ttlSeconds?: number;
-    /**
-     * Seal every call to the relay to its attested TEE, verified with this — for
-     * example {@link createQuoteVerifier} with the MRTDs you trust. The warrant
-     * and the method's arguments then reach only the relay's TD, not whatever
-     * terminates TLS in front of it, and the relay is one this client checked
-     * itself rather than one the cloud vouched for. Calls to the cloud are not
-     * sealed; they carry no intent.
-     *
-     * Without it, calls to the relay are plain HTTPS.
-     */
-    seal?: VerifyTransportQuote;
-    fetch?: typeof fetch;
-    timeoutMs?: number;
-    /**
-     * The chosen relay node's device signing key, hex — if you know it.
-     *
-     * Supplying it makes `connection.client` able to *observe* as well as write:
-     * a relay is an ordinary node, and a keyholder with an account proof can log
-     * in to it and subscribe. The key has to come from somewhere the caller
-     * already trusts, which today means out of band, because the cloud does not
-     * publish it (mdma #312).
-     *
-     * Left unset, the key the cloud reported is used — `null` for now, which
-     * means `connection.client.canSubscribe === false` and nothing is guessed.
-     * When #312 lands, unchanged callers start observing.
-     */
-    relayNodeKey?: string;
-    /**
-     * The audience the observing session is bound to. Defaults to this runtime's
-     * own origin (or `cli`). See {@link RelayObserveConfig.audience}.
-     */
-    observeAudience?: Audience;
-}
-/** A signed-in cloud session with a relay ready to write through. */
-export interface CloudConnection {
-    /** The cloud API, for namespaces, billing, HA and sign-out. */
-    cloud: CloudClient;
-    /** The relay chosen for this namespace. */
-    relay: RelayClient;
-    /** The namespace writes will land in. */
-    namespaceId: string;
-    namespace: CloudNamespace;
-    /** What the cloud reported about the chosen relay. */
-    relayInfo: CloudRelay;
-    /** Run one method in one context, on the author's behalf. */
-    execute<T = unknown>(contextId: string, method: string, argsJson?: unknown): Promise<IntentResult<T>>;
-    /**
-     * The same connection behind the transport-neutral surface.
-     *
-     * `client.rpc.execute({ contextId, method, argsJson })` is the call a
-     * node-backed app already writes, so an app reaching the cloud this way keeps
-     * every call site it has — signing in *is* the transport decision, and it
-     * happens here, once. `relay` and `execute` above are unchanged and remain
-     * the direct path for a caller that wants `IntentResult` in hand.
-     *
-     * Whether it can also *observe* depends on one input: the relay node's
-     * device signing key. A relay is an ordinary node and serves `/sse` and
-     * `/ws`, but a login statement must be signed against a key learned out of
-     * band. Pass {@link ConnectCloudOptions.relayNodeKey} if you have it; the
-     * cloud does not publish it yet (mdma #312), so by default
-     * `client.canSubscribe === false` and `client.events` throws saying so.
-     */
-    client: MeroClient;
-}
-/**
- * Sign in to the cloud and return a connection that can write.
- *
- * Throws rather than returning a half-usable connection, and the message says
- * which step is missing — no namespace, several to choose between, HA not
- * enabled, or no relay that relays (only replicas, or relays waiting for a
- * grant). Every one of those is
- * something the user has to go and do, and a client that reports them alike
- * cannot tell them what.
- */
-export declare function connectCloud(options: ConnectCloudOptions): Promise<CloudConnection>;
-/** What {@link connectCloudWithAccount} needs on top of a root. */
-export interface ConnectCloudWithAccountOptions extends Omit<ConnectCloudOptions, 'sessionToken' | 'googleIdToken' | 'authorAccount'> {
-    /**
-     * The account root — a 64-hex secret, or a `Signer` over a key that cannot be
-     * exported. The whole credential: no Google login is involved.
-     */
-    root: RootSource;
-    /**
-     * Whose writes these are, hex. Defaults to the account the root derives,
-     * which is the only account it can open a session as.
-     *
-     * Worth passing only when the device certificate was issued by a *different*
-     * root than the one signing in — which core accepts and nothing here needs to
-     * forbid, but which is rare enough that defaulting to the signing root is the
-     * safer shape.
-     */
-    authorAccount?: string;
-}
-/**
- * The same connection, opened with an account root instead of a cloud session.
- *
- * The two sign-in paths end in the same place, and until now only one of them
- * ended in a usable client: a caller signing in with a root had to open the
- * session, read the relays and assemble a {@link RelayClient} by hand, which is
- * three chances to pair the wrong author with the wrong executor.
- *
- * It is one call rather than one function: the session is minted here and
- * everything after it is {@link connectCloud}, unchanged. Duplicating the
- * namespace choice and the three no-relay diagnostics would mean two copies of
- * the messages that tell a user what to go and do.
- *
- * The author defaults to the account the root derives. That is not a
- * convenience — passing an account the root does not own is the mistake this
- * shape removes, since the cloud would answer with that root's namespaces while
- * every warrant claimed somebody else's authorship.
- */
-export declare function connectCloudWithAccount(options: ConnectCloudWithAccountOptions): Promise<CloudConnection>;

package/dist/cloud/connect.js

@@ -1,260 +0,0 @@
-/**
- * The second way to log in: sign in to Calimero Cloud instead of connecting to
- * a node.
- *
- * # Two connection shapes, one SDK
- *
- * `createMeroJs({ baseUrl })` is the node connection: point at a node, hold a
- * credential on it, and drive its admin API and JSON-RPC. It assumes the caller
- * has a node — their own, or one they have an account on.
- *
- * `connectCloud(...)` is for the caller who has neither. They sign in with the
- * identity they already use (Google, through the cloud), and the cloud answers
- * with an attested TEE relay serving their namespace. Writes then go through
- * delegated execution: signed here, run there, attributed here.
- *
- * The two are not alternatives to be picked at random — they answer different
- * questions. "Which node do I talk to?" has an answer for a desktop app and no
- * answer at all for a web app whose user has never installed anything. This
- * function is that missing answer, which is why the login step it replaces is
- * the *node URL prompt* rather than the authentication.
- *
- * `connectCloudWithAccount(...)` is the same connection reached by the other
- * door: the caller holds an account root and signs in as the account itself,
- * with no Google login anywhere in it. Identical from there on, deliberately —
- * which login proved who you are changes nothing about how a relay is found or
- * how a write is authorised.
- *
- * # What it does not do
- *
- * # Sealing the relay
- *
- * TLS in front of a relay ends outside its TD, at the host's ingress, where
- * the warrant and the method's arguments are readable. Pass `seal` (a quote
- * verifier) and every call to the relay is sealed to the key its attested TD
- * holds, so they are readable only inside it.
- *
- * It does not read state. A relay writes on the author's behalf; reads still
- * come from a node the client can query, or from the app's own projection of
- * the events it receives. `connectCloud` is deliberately narrow about this
- * rather than presenting a half-working `MeroJs` whose `admin` and `rpc` would
- * need a credential nobody holds.
- */
-import { CloudClient, pickExecutingRelay } from './cloud-client.js';
-import { RelayClient } from '../relay/relay-client.js';
-import { createLocalStorageNonceSource, createMemoryNonceSource } from '../relay/nonce-source.js';
-import { resolveSigner } from '../signer/signer.js';
-import { resolveRoot } from '../account/account.js';
-import { MeroClient } from '../transport/mero-client.js';
-import { createAttestedSealedFetch } from '../sealed/sealed.js';
-/**
- * Sign in to the cloud and return a connection that can write.
- *
- * Throws rather than returning a half-usable connection, and the message says
- * which step is missing — no namespace, several to choose between, HA not
- * enabled, or no relay that relays (only replicas, or relays waiting for a
- * grant). Every one of those is
- * something the user has to go and do, and a client that reports them alike
- * cannot tell them what.
- */
-export async function connectCloud(options) {
-    if (!options.sessionToken && !options.googleIdToken) {
-        throw new Error('connectCloud needs either a sessionToken or a googleIdToken');
-    }
-    // Resolved before the first network call: a missing or duplicated key is the
-    // caller's mistake to fix, and finding out after signing in leaves a session
-    // minted for a connection that was never going to be built.
-    const signer = await resolveSigner(options.deviceSecret, options.signer, 'deviceSecret');
-    const cloud = new CloudClient({
-        cloudBaseUrl: options.cloudBaseUrl,
-        sessionToken: options.sessionToken,
-        onSession: options.onSession,
-        fetch: options.fetch,
-        timeoutMs: options.timeoutMs,
-    });
-    if (!options.sessionToken && options.googleIdToken) {
-        await cloud.signInWithGoogle(options.googleIdToken);
-    }
-    const namespaces = await cloud.getMyNamespaces();
-    const namespace = pickNamespace(namespaces, options.namespaceId);
-    // One read, used for both the choice and the diagnostic. `findExecutingRelay`
-    // would fetch again to explain itself, and a second call can disagree with the
-    // first — reporting "waiting for the grant" about a relay that was already
-    // usable a moment ago.
-    const relays = await cloud.getNamespaceRelays(namespace.namespaceId);
-    const relayInfo = pickExecutingRelay(relays);
-    if (!relayInfo) {
-        throw new Error(explainNoRelay(namespace, relays));
-    }
-    const relay = new RelayClient({
-        // Checked by `pickExecutingRelay`, which is the only thing that returns a
-        // relay — narrowed here rather than re-validated, so the invariant lives in
-        // one place.
-        relayUrl: relayInfo.relayUrl,
-        executorAccount: relayInfo.executorAccount,
-        authorAccount: options.authorAccount,
-        authorProof: options.authorProof,
-        signer,
-        nonces: options.nonces ?? defaultNonceSource(signer.publicKey),
-        ttlSeconds: options.ttlSeconds,
-        // Only the relay is sealed: a sealed fetch is bound to one node and refuses
-        // any other URL, and the cloud calls above carry no intent.
-        fetch: options.seal
-            ? createAttestedSealedFetch({
-                baseUrl: relayInfo.relayUrl,
-                verify: options.seal,
-                fetch: options.fetch,
-            })
-            : options.fetch,
-        timeoutMs: options.timeoutMs,
-    });
-    return {
-        cloud,
-        relay,
-        namespaceId: namespace.namespaceId,
-        namespace,
-        relayInfo,
-        execute: (contextId, method, argsJson) => relay.execute(contextId, method, argsJson),
-        // Built from the same `relay`, not a second one: one nonce sequence, one
-        // warrant signer. Two clients over one relay would hand out the same nonce
-        // twice and have the network refuse the loser as a replay.
-        //
-        // `observe` is always passed, with whatever key is known — the caller's if
-        // they had one, otherwise the cloud's, which is `null` until mdma #312. One
-        // code path rather than two, so the hosted case starts observing the day
-        // the field appears, without a line changing here or at the call site.
-        client: new MeroClient({
-            transport: 'relay',
-            relay,
-            observe: {
-                nodeKey: options.relayNodeKey ?? relayInfo.nodeKey,
-                audience: options.observeAudience,
-                fetch: options.fetch,
-                timeoutMs: options.timeoutMs,
-            },
-        }),
-    };
-}
-/**
- * The same connection, opened with an account root instead of a cloud session.
- *
- * The two sign-in paths end in the same place, and until now only one of them
- * ended in a usable client: a caller signing in with a root had to open the
- * session, read the relays and assemble a {@link RelayClient} by hand, which is
- * three chances to pair the wrong author with the wrong executor.
- *
- * It is one call rather than one function: the session is minted here and
- * everything after it is {@link connectCloud}, unchanged. Duplicating the
- * namespace choice and the three no-relay diagnostics would mean two copies of
- * the messages that tell a user what to go and do.
- *
- * The author defaults to the account the root derives. That is not a
- * convenience — passing an account the root does not own is the mistake this
- * shape removes, since the cloud would answer with that root's namespaces while
- * every warrant claimed somebody else's authorship.
- */
-export async function connectCloudWithAccount(options) {
-    const { root, authorAccount, ...rest } = options;
-    // Both keys resolved before the sign-in, for the reason `connectCloud` gives:
-    // a session minted for a connection that cannot be built is a credential
-    // issued for nothing.
-    const signer = await resolveSigner(rest.deviceSecret, rest.signer, 'deviceSecret');
-    const resolved = await resolveRoot(root);
-    const cloud = new CloudClient({
-        cloudBaseUrl: options.cloudBaseUrl,
-        // Reported here as well as on the connection's own client: this is where
-        // the session is first minted, and a caller persisting it would otherwise
-        // only hear about the rolling refreshes of a token it never saw.
-        onSession: options.onSession,
-        fetch: options.fetch,
-        timeoutMs: options.timeoutMs,
-    });
-    const session = await cloud.signInWithAccount(resolved.signer);
-    return connectCloud({
-        ...rest,
-        // Already resolved above, and passing both forms on would be refused.
-        deviceSecret: undefined,
-        signer,
-        sessionToken: session.sessionToken,
-        authorAccount: authorAccount ?? resolved.accountId,
-    });
-}
-/** The one namespace to write in, or an error naming the actual ambiguity. */
-function pickNamespace(namespaces, requested) {
-    if (requested) {
-        const found = namespaces.find((n) => n.namespaceId === requested);
-        if (!found) {
-            throw new Error(`this account owns no namespace ${requested}; it owns: ${namespaces.map((n) => n.namespaceId).join(', ') || '(none)'}`);
-        }
-        return found;
-    }
-    if (namespaces.length === 0) {
-        throw new Error('this account owns no namespaces in the cloud: claim one first, then enable HA on it so a relay is assigned');
-    }
-    if (namespaces.length > 1) {
-        throw new Error(`this account owns ${namespaces.length} namespaces — pass namespaceId to say which: ${namespaces
-            .map((n) => n.namespaceId)
-            .join(', ')}`);
-    }
-    return namespaces[0];
-}
-/**
- * Why no relay can write here — the states, kept apart.
- *
- * They are different asks of the user (turn HA on, wait, have an admin admit
- * TEEs as relays, or have an admin grant a capability) and one message for all
- * of them would send them to the wrong one.
- */
-function explainNoRelay(namespace, relays) {
-    if (relays.length === 0) {
-        return namespace.haStatus === 'enabled'
-            ? `namespace ${namespace.namespaceId} has HA enabled but no relay has been assigned to it yet — retry shortly`
-            : `namespace ${namespace.namespaceId} has no relays: enable HA on it in the cloud to have an attested node assigned`;
-    }
-    // A node that reports a role is decided by it alone: a `ReadOnlyTee` is a
-    // replica and never relays, whatever its grant, so asking for the grant would
-    // send the admin to the wrong fix. Only a node too old to report a role is
-    // still waiting on `CAN_AUTHOR_ON_BEHALF`.
-    const replicas = relays.filter((r) => r.teeRole !== null && r.teeRole !== 'RelayTee');
-    if (replicas.length === relays.length) {
-        return (`every node on namespace ${namespace.namespaceId} is a read-only TEE replica (ReadOnlyTee), ` +
-            `which never relays delegated writes: an admin of the namespace must set its TEE admission ` +
-            `policy with mode: 'relay' — AdminClient.setTeeAdmissionPolicy(namespaceId, { ..., mode: 'relay' }) ` +
-            `— so fleet nodes are admitted as RelayTee`);
-    }
-    const waitingOnGrant = relays.filter((r) => r.teeRole === null && !r.authorshipReady);
-    if (waitingOnGrant.length > 0 && waitingOnGrant.length + replicas.length === relays.length) {
-        // Name the call, not just the capability. The grant is a governance op only
-        // a namespace admin can publish, so this message is read by someone who has
-        // to go ask for it — and "grant CAN_AUTHOR_ON_BEHALF" alone leaves them
-        // relaying a constant to an admin who then has to work out the command.
-        // `openToDelegatedExecution` is the durable half (every relay assigned from
-        // then on lands open), `grantAuthorship` the one for relays already here.
-        return (`every relay on namespace ${namespace.namespaceId} is waiting for the authorship grant: ` +
-            `an admin of the namespace must grant CAN_AUTHOR_ON_BEHALF to ${waitingOnGrant.map((r) => r.executorAccount ?? r.peerId).join(', ') || 'the relay account'} — with AdminClient.grantAuthorship(namespaceId, account) for these relays, and ` +
-            `AdminClient.openToDelegatedExecution(namespaceId) so relays assigned later need no further op`);
-    }
-    return `namespace ${namespace.namespaceId} has ${relays.length} relay(s), but none is ready to relay yet (a URL, an executor account and a recent heartbeat) — retry shortly`;
-}
-/**
- * A persisted nonce source keyed by the author's device public key.
- *
- * The key is the *public* key: a per-device key is required (two devices of one
- * account are independent replicas) and the secret must never end up in a
- * storage key an extension or another script can enumerate. The signer names
- * its own public key, which is also the only form available when the private
- * half cannot be exported.
- *
- * Falls back to memory where there is no `localStorage` — Node, a worker, an
- * edge runtime. Those are processes that own their whole sequence, which is
- * exactly the case a memory counter is correct for.
- */
-function defaultNonceSource(devicePublicKey) {
-    const key = `mero-js:warrant-nonce:${devicePublicKey}`;
-    try {
-        return createLocalStorageNonceSource(key);
-    }
-    catch {
-        return createMemoryNonceSource(1);
-    }
-}

package/dist/cloud/enrol-redirect.d.ts

@@ -1,181 +0,0 @@
-/**
- * Getting an app's device key certified **by a wallet on another origin**.
- *
- * An app holds a device keypair and no account. It cannot certify that key
- * itself: certifying is a signature by an account root, and the root is the one
- * key in the system with nothing above it to revoke it — so a page that can
- * reach it can take the account for good. The whole design is that the app
- * never can.
- *
- * What separates them is the **same-origin policy**, and that is why this is a
- * redirect rather than a message, a popup API or a shared library. The wallet
- * keeps the root as a non-extractable key in *its* origin's IndexedDB; script
- * running on the app's origin cannot read another origin's storage, cannot read
- * its keys, and cannot draw its consent screen. Nothing weaker enforces that —
- * an iframe with a `postMessage` bridge would put the approval dialog inside a
- * document the app can style, overlay and click for you.
- *
- * So the shape is: send the person to the wallet naming the key you want
- * certified, they approve there, and the wallet redirects back with an
- * `AccountProof<DeviceCert>` over that key.
- *
- * ## The credential comes back in the FRAGMENT
- *
- * Same reason the cloud's link grant does — see `link-redirect.ts`. A fragment
- * is not sent to the server, so it lands in nobody's access log, no referrer
- * header and no proxy trace on the way. A query string would put a credential
- * into every log between here and the app's host.
- *
- * ## What the app must check before storing anything
- *
- * A fragment is written by whoever sent the person to this URL, which is not
- * necessarily the wallet. Three things therefore have to be checked locally:
- *
- * - the credential certifies **the key this app asked about** — otherwise the
- *   app stores a credential it cannot sign for, and every warrant it mints is
- *   refused somewhere far from here;
- * - the credential is **internally consistent** — the root signed it, the
- *   account it names is the one that root derives, and its device id was
- *   minted for that account ({@link verifyDeviceCredential});
- * - the account reported beside it is **the account the credential names** —
- *   the app shows that id to a person and keys state by it, so a mismatch is a
- *   credential filed under someone else's name.
- *
- * {@link completeDeviceEnrolment} does all three and throws on any of them,
- * before the caller has anything to store. What none of them establish is that
- * the account is the *person's* — anyone can mint a root offline and certify
- * any public key with it, and a device key is public once enrolled. That is
- * what the state narrows: {@link deviceEnrolmentUrl} remembers each request, and
- * {@link completeDeviceEnrolment} refuses an answer to a request this browser did
- * not start, rather than to a link someone sent.
- */
-import { type DeviceCredential } from '../device-cert/index.js';
-export interface DeviceEnrolmentOptions {
-    /**
-     * The wallet's origin — a different origin from this app's, and the reason
-     * the flow exists. Pointing it at this app's own origin is accepted (a
-     * wallet may be hosted anywhere) but certifies nothing the app could not
-     * already do.
-     */
-    walletUrl: string;
-    /** The device's ed25519 signing key to be certified, 64 hex. */
-    devicePublicKey: string;
-    /**
-     * The device's X25519 key-delivery key, 64 hex.
-     *
-     * Required, not optional: a certificate covers both keys, and one minted
-     * without a delivery key names a device no group key can ever be sealed to.
-     * Generate it alongside the signing key rather than enrolling twice.
-     */
-    kemPublicKey: string;
-    /**
-     * Where the wallet sends them back. Must be `https:`, or `http:` on
-     * localhost — see {@link assertSafeReturnTo}.
-     */
-    returnTo: string;
-}
-/**
- * The URL to send a person to.
- *
- * Built rather than documented as a string so the parameter names live in one
- * place: a wallet and an app that disagree about them fail as a blank consent
- * screen, which looks like an outage rather than a contract mismatch.
- *
- * Remembers the request under a fresh state the wallet echoes back, so
- * {@link completeDeviceEnrolment} can match the answer to it.
- */
-export declare function deviceEnrolmentUrl(options: DeviceEnrolmentOptions): string;
-/** Send the person to the wallet to approve this device. Does not return. */
-export declare function beginDeviceEnrolment(options: DeviceEnrolmentOptions): never;
-/** What came back in the fragment, unverified. */
-export interface DeviceEnrolmentCallback {
-    /** The `AccountProof<DeviceCert>`, hex borsh — as `signDeviceCert` returns it. */
-    credential: string;
-    /** The account the wallet says certified this device, 64 hex. */
-    account: string;
-    /** The device id the wallet minted, 64 hex. */
-    device: string;
-    /** The state the wallet echoed back from {@link deviceEnrolmentUrl}. */
-    state?: string;
-}
-/**
- * Read an enrolment out of the current URL fragment, and strip it.
- *
- * Returns `null` on an ordinary page load, so a caller can run it
- * unconditionally at startup. Throws when the person declined, because that is
- * an outcome the app has to show rather than a state to wait in.
- *
- * Nothing is verified here — the shape is separated from the checking so a
- * caller can see what arrived (to log it, or to name the account in a refusal)
- * even when it goes on to be refused. Nothing read out of this belongs in
- * storage until {@link completeDeviceEnrolment} has passed.
- */
-export declare function readEnrolmentCallback(location?: {
-    hash: string;
-}): DeviceEnrolmentCallback | null;
-export interface CompleteDeviceEnrolmentOptions extends DeviceEnrolmentCallback {
-    /**
-     * The signing key this app asked to have certified, 64 hex.
-     *
-     * The binding that makes the returned credential usable: it must be *this*
-     * app's key, held in this app, or nothing it signs verifies against the
-     * certificate it presents.
-     */
-    devicePublicKey: string;
-    /** The delivery key asked about, 64 hex. Checked when supplied. */
-    kemPublicKey?: string;
-}
-/** A device this app may now sign as. */
-export interface EnrolledDevice {
-    /** The credential to present, hex — `RelayClientConfig.authorProof`. */
-    credential: string;
-    /** The account it belongs to, 64 hex. */
-    account: string;
-    /** The device id within that account, 64 hex. */
-    device: string;
-    /** Everything the certificate says, already checked. */
-    certificate: DeviceCredential;
-}
-/**
- * Verify what came back, and refuse loudly rather than returning a half-checked
- * credential.
- *
- * Every throw here is a credential that must not reach storage. The order is
- * deliberate: the cheap local comparisons first, so a fragment aimed at the
- * wrong app is rejected without a signature verification, and the message names
- * what disagreed rather than reporting "invalid credential".
- *
- * The state is spent on the first call, so an answer is accepted at most once.
- */
-export declare function completeDeviceEnrolment(options: CompleteDeviceEnrolmentOptions): Promise<EnrolledDevice>;
-/**
- * Where a credential may be delivered.
- *
- * `https:` anywhere, `http:` only on loopback. Plain HTTP elsewhere would put
- * the fragment on a page any network position can rewrite, and the fragment is
- * the credential; loopback is exempt because it never leaves the machine and is
- * the only way to develop against a wallet at all.
- *
- * Everything else — `javascript:`, `data:`, a custom app scheme — is refused.
- * The first two are script the wallet would be asked to run; a custom scheme is
- * a legitimate thing to want for a native app, but which installed handler
- * claims it is not something this SDK can check, so it is refused here rather
- * than accepted on trust.
- */
-/**
- * Is the credential coming back to somewhere other than the page that asked?
- *
- * Normally an app enrols its own device key and gets the answer back on its own
- * origin, so the two match. They can legitimately differ — a callback page on a
- * sibling host, an app mid-migration — which is why this is not refused.
- *
- * But it is the shape an abuse would also take: send someone to the real wallet
- * and have the credential delivered elsewhere. Nothing here can tell the two
- * apart, and a client-side check constrains nobody who did not call this
- * function anyway. What it is good for is the honest case — surfacing the
- * mismatch to whoever is building the app, and giving a wallet the same fact to
- * put in front of the person approving.
- *
- * Exported so a wallet can render it, rather than each caller re-deriving it.
- */
-export declare function callbackIsForeign(returnTo: string, pageOrigin?: string): boolean;