@ixo/openhands-sdk 0.0.0-stage → 0.1.0

package/dist/esm/chain/signx.d.ts

@@ -0,0 +1,233 @@
+/**
+ * The ixo-native door: sign in by scanning a QR with the IXO Mobile app.
+ *
+ * `@ixo/signx-sdk` is not used, deliberately. It is a stateful browser
+ * EventEmitter that polls and holds a session — which means either shipping it
+ * to the client, on a page with a kilobyte of headroom, or running a
+ * long-lived object inside serverless functions that do not have lives long
+ * enough to hold one. The wire protocol underneath is four fields and two
+ * routes, so this speaks it directly.
+ *
+ * Read from the SDK's own source (`@ixo/signx-sdk` 1.3.2, in the portal's
+ * node_modules) rather than from documentation, because the payload has to
+ * match byte for byte or the phone refuses it.
+ *
+ * Server-side only: the relay is polled from a route handler, never the page.
+ */
+export type SignXNetwork = "devnet" | "testnet" | "mainnet";
+export declare const SIGNX_RELAY: Record<SignXNetwork, string>;
+export interface LoginRequest {
+    /** What the phone polls against, and what we poll for. */
+    hash: string;
+    /** sha256(hash + nonce) — proves whoever answers saw the QR, not just the hash. */
+    secureHash: string;
+    type: "SIGN_X_LOGIN";
+    sitename: string;
+    timeout: string;
+    network: SignXNetwork;
+    matrix: boolean;
+    version: number;
+}
+/** Whether a hash and secureHash pair is one this deployment actually issued. */
+export declare const weIssued: (hash: string, secureHash: string, secret: string) => boolean;
+/**
+ * A mark saying "we produced this string", for anything that has no hash pair
+ * of its own — a transact deeplink, most of all.
+ *
+ * The QR route exists to draw *our* codes. Without a mark it would draw
+ * anybody's: point it at a deeplink you control, embed it in a page wearing our
+ * name, and it is a phishing site with our server rendering the bait. A login
+ * proves itself through `weIssued`; a transact link has nothing to prove itself
+ * with, so it carries this instead.
+ */
+export declare const stampFor: (value: string, secret: string) => string;
+export declare const stampOk: (value: string, stamp: string, secret: string) => boolean;
+/**
+ * Start a login.
+ *
+ * The QR carries `hash` and `secureHash`; the nonce between them is derived
+ * from the server secret and never appears anywhere a client can read it. So a
+ * hash scraped off somebody's screen cannot be turned into a login this
+ * deployment will accept, and `weIssued` can tell ours from a stranger's
+ * without either side remembering anything.
+ */
+export declare function startLogin(args: {
+    sitename: string;
+    network: SignXNetwork;
+    matrix?: boolean;
+    timeoutMs?: number;
+    secret: string;
+}): {
+    request: LoginRequest;
+};
+/**
+ * What the QR encodes — the deeplink the IXO Mobile app opens.
+ *
+ * **Flat query parameters, one per field.** This is not a style choice: the app
+ * parses the link with `Linking.parse(url)` and hands `queryParams` straight to
+ * the screen as its route params, which then waits for `route.params.hash`. A
+ * link carrying one opaque blob gives it `{ data: "eyJ…" }`, no `hash`, and the
+ * phone sits on "Preparing SIGN X…" until it is closed — no error, because
+ * nothing ever got as far as validating.
+ *
+ * That is exactly what ours did. The shape below is copied field for field from
+ * `@ixo/signx-sdk` 1.3.2, `module/utils/encoding.js` → `convertDataToDeeplink`,
+ * which is the only description of this wire that is actually authoritative.
+ *
+ * Values are percent-encoded, which the SDK does not bother with. `Linking.parse`
+ * decodes them, so the phone sees the same strings either way — and a sitename
+ * with a space in it stops being a malformed URL.
+ *
+ * The `impactsx` scheme is the app's registered URL scheme, not its name. The
+ * app is called IXO Mobile everywhere a person can read it; renaming this
+ * string would open nothing.
+ */
+export declare function deeplinkFor(request: LoginRequest | MatrixLoginRequest | TransactStart["request"], scheme?: string): string;
+/** A Matrix scan, which carries no `matrix` flag — being Matrix is the point. */
+export interface MatrixLoginRequest {
+    hash: string;
+    secureHash: string;
+    type: "SIGN_X_MATRIX_LOGIN";
+    sitename: string;
+    timeout: string;
+    network: SignXNetwork;
+    version: number;
+}
+/** Start the Matrix ceremony. Same envelope as a login, different type. */
+export declare function startMatrixLogin(args: {
+    sitename: string;
+    network: SignXNetwork;
+    timeoutMs?: number;
+    secret: string;
+}): {
+    request: MatrixLoginRequest;
+};
+/** What the phone hands over once somebody approves the Matrix scan. */
+export interface SignXMatrix {
+    accessToken?: string;
+    userId?: string;
+    roomId?: string;
+    baseUrl?: string;
+    encryptedMnemonic?: string;
+}
+/**
+ * Has the phone answered the Matrix scan?
+ *
+ * `accessToken` is the test for "answered", exactly as the SDK has it — a reply
+ * without one is the relay still waiting in its own dialect, not a session.
+ */
+export declare function fetchMatrixLogin(network: SignXNetwork, hash: string, secret: string): Promise<SignXMatrix | null>;
+export interface SignXUser {
+    name?: string;
+    address: string;
+    pubKey?: string;
+    algo?: string;
+    did: string;
+    /**
+     * The Matrix half of the session, when the phone is new enough to send it.
+     *
+     * INFRA §1.1: the local mobile clone at 1.7.5 sends no matrix field at all,
+     * and which releases do is still open. So this is optional everywhere and
+     * nothing may require it — the chain half of a session must work without a
+     * vault.
+     */
+    matrix?: {
+        accessToken?: string;
+        userId?: string;
+        roomId?: string;
+        baseUrl?: string;
+        encryptedMnemonic?: string;
+    };
+}
+/**
+ * Something the relay told us, as opposed to a relay we could not reach.
+ *
+ * The distinction is the whole point: a refusal is final and should end the
+ * wait with its own words on screen, while an unreachable relay is worth one
+ * more try. Collapsing the two is what left people looking at a dead QR.
+ */
+export declare class SignXRefused extends Error {
+}
+/**
+ * Ask the relay whether the phone has answered yet.
+ *
+ * `null` means "not yet", which is the ordinary case and not an error — a
+ * person takes seconds to find their phone. Only a relay that refuses or
+ * answers nonsense throws.
+ */
+export declare function fetchLogin(network: SignXNetwork, hash: string, secret: string): Promise<SignXUser | null>;
+export interface TransactAccount {
+    address: string;
+    did: string;
+    /** Hex-encoded pubkey, as the phone expects it. */
+    pubkey: string;
+}
+/**
+ * The per-transaction hash the phone recomputes.
+ *
+ * Keys are sorted before stringify — the SDK does this deliberately so both
+ * ends agree regardless of property order. Reproduce it exactly or the phone
+ * silently refuses the transaction.
+ */
+export declare function hashTransactData(data: {
+    address: string;
+    did: string;
+    pubkey: string;
+    txBodyHex: string;
+    timestamp: string;
+}): string;
+export interface TransactStart {
+    /** The session, and what the QR points at. */
+    sessionHash: string;
+    /** The first transaction's hash — what a response is polled against. */
+    transactionHash: string;
+    request: {
+        sessionHash: string;
+        hash: string;
+        type: "SIGN_X_TRANSACT";
+        sitename: string;
+        network: SignXNetwork;
+        version: number;
+    };
+}
+/**
+ * Open a transact session on the relay and return what the QR should carry.
+ *
+ * `secureNonce` is derived from the session hash under the server secret, the
+ * same trick login uses: `start` and `poll` are different route modules and,
+ * in production, different serverless instances, so anything remembered
+ * between them is gone by the time it is read.
+ */
+export declare function startTransact(args: {
+    account: TransactAccount;
+    txBodyHexes: string[];
+    sitename: string;
+    network: SignXNetwork;
+    secret: string;
+    timestamp?: string;
+}): Promise<TransactStart>;
+export interface TransactResult {
+    code: number;
+    transactionHash?: string;
+    gasUsed?: number;
+    gasWanted?: number;
+    height?: number;
+    rawLog?: string;
+}
+/**
+ * Poll for what the phone did.
+ *
+ * `null` is "not yet" — the relay answers **418** for that, which is the one
+ * status here that is neither success nor failure.
+ *
+ * The trap worth naming: **a broadcast that landed with `code ≠ 0` still
+ * arrives on the success channel** (INFRA §1.1, from the mobile source). So a
+ * caller must check `code`, and `signWithSession` does.
+ */
+export declare function pollTransact(args: {
+    network: SignXNetwork;
+    transactionHash: string;
+    sessionHash: string;
+    secret: string;
+}): Promise<TransactResult | null>;
+//# sourceMappingURL=signx.d.ts.map

package/dist/esm/chain/signx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signx.d.ts","sourceRoot":"","sources":["../../../src/chain/signx.ts"],"names":[],"mappings":"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"}