@hwlt/era-connect 0.1.0

package/dist/shared-CI8zhQiE.d.ts

@@ -0,0 +1,218 @@
+//#region src/ur/ur.d.ts
+/** An immutable Uniform Resource: a registry type string plus its CBOR payload. */
+declare class Ur {
+  readonly type: string;
+  readonly cbor: Uint8Array;
+  constructor(type: string, cbor: Uint8Array);
+  /** The whole UR as one single-part `ur:` string, lowercase (the loggable form). */
+  toString(): string;
+  /** The single-part wire form, uppercase (QR alphanumeric mode). */
+  toWireString(): string;
+}
+//#endregion
+//#region src/core/rand.d.ts
+type RandomBytesFn = (length: number) => Uint8Array;
+//#endregion
+//#region src/qr/animated-ur.d.ts
+interface AnimatedUrOptions {
+  /**
+   * Payload bytes per fountain fragment. The on-wire frame adds a ~16-byte
+   * CBOR header, so the default 180 keeps frames within the ~200-byte
+   * per-fragment ceiling hardware-wallet cameras scan reliably. Larger
+   * fragments mean fewer frames but denser QR codes.
+   */
+  readonly maxFragmentLength?: number;
+}
+declare const DEFAULT_FRAGMENT_LENGTH = 180;
+/**
+ * Frame source for rendering a UR as an animated QR.
+ *
+ * Drive `nextFrame()` from your own ticker (~8 fps is the battle-tested
+ * default) and hand each string to your QR component. Frames are UPPERCASE so
+ * the QR encoder can use alphanumeric mode (~45% denser than byte mode).
+ */
+declare class AnimatedUr {
+  private readonly encoder;
+  constructor(ur: Ur, options?: AnimatedUrOptions);
+  /** Whether the payload fits one QR (no animation needed). */
+  get isSingleFrame(): boolean;
+  /** The UR registry type being sent, e.g. `eth-sign-request`. */
+  get urType(): string;
+  /** How many source fragments the payload was split into. */
+  get fragmentCount(): number;
+  /** Next wire frame (uppercase). Single-frame payloads return the same string every call. */
+  nextFrame(): string;
+  /** The whole request as ONE lowercase `ur:` string — the loggable form, not what is on screen. */
+  toString(): string;
+}
+//#endregion
+//#region src/core/errors.d.ts
+/**
+ * Closed set of error codes the SDK can produce. Integrators branch on
+ * `code`, never on message text — messages are for humans and may change.
+ */
+type EraErrorCode =
+/** No CSPRNG available: neither `globalThis.crypto.getRandomValues` nor an injected `randomBytes`. */
+'no-secure-random' |
+/** The scanned text is not a `ur:` string at all. */
+'not-a-ur' |
+/** A UR of a type this operation does not accept. */
+'wrong-ur-type' |
+/** Bytewords body malformed (unknown letter pair, too short). */
+'malformed-bytewords' |
+/** Bytewords or reassembly CRC32 does not match. */
+'checksum-mismatch' |
+/** CBOR payload malformed or outside the hardened decoder's policy. */
+'malformed-cbor' |
+/** The `<seq>` path segment of a multi-part UR is unreadable. */
+'malformed-sequence' |
+/** A fragment that does not belong to the stream being assembled. */
+'fragment-mismatch' |
+/** A size/count cap was exceeded (fragment count, message size, inflate ceiling). */
+'limit-exceeded' |
+/** `result()`/`parse()` called before the scan completed. */
+'incomplete-scan' |
+/** The reply echoes a different request id — it answers another sign request. */
+'request-id-mismatch' |
+/** The linked wallet carries no account for the requested path. */
+'account-not-found' |
+/** Invalid request properties (bad path string, chainId over the device's 32-bit ceiling, ...). */
+'invalid-props' |
+/** The device refused to sign (e.g. a Bitcoin message for a non-legacy address). */
+'empty-signature' |
+/** Reply CBOR/protobuf decoded but its shape is not the expected reply. */
+'malformed-reply' |
+/** gzip payload malformed, truncated, or a decompression bomb. */
+'gzip-error' |
+/** Protobuf payload malformed. */
+'protobuf-error' |
+/** A verification helper found a mismatch between request and reply. */
+'verification-failed';
+/** Every error thrown by this SDK. `code` is stable API; `message` is not. */
+declare class EraSdkError extends Error {
+  readonly code: EraErrorCode;
+  readonly details?: Record<string, unknown>;
+  constructor(code: EraErrorCode, message: string, details?: Record<string, unknown>);
+}
+//#endregion
+//#region src/scan/ur-scanner.d.ts
+interface UrScannerOptions {
+  /**
+   * Pin: frames of any other UR type are rejected BEFORE the fountain decoder
+   * sees them. The decoder commits to a stream once one binds, so a frame that
+   * gets that far has a say in what the rest of the session may look like —
+   * pinning is the cheap half of the hostile-QR cure (the decoder's
+   * two-fragment binding rule is the other half).
+   */
+  readonly expectedTypes?: readonly string[];
+}
+interface ScanRejection {
+  readonly code: EraErrorCode;
+  readonly message: string;
+  /**
+   * Consecutive occurrences of this same rejection. A static hostile or
+   * malformed QR produces the identical rejection at camera framerate; this
+   * counter lets a UI or a log show it once instead of ~10 times per second.
+   */
+  readonly repeated: number;
+}
+type ScanFeedResult = {
+  readonly kind: 'progress';
+  readonly progress: number;
+  readonly framesReceived: number;
+  readonly framesExpected: number;
+} | {
+  readonly kind: 'duplicate';
+} | {
+  readonly kind: 'rejected';
+  readonly rejection: ScanRejection;
+} | {
+  readonly kind: 'complete';
+  readonly ur: Ur;
+};
+/**
+ * Accumulates camera frames into a UR. Synchronous and non-throwing on the
+ * feed path (safe to call from camera callbacks); malformed frames come back
+ * as typed rejections, never exceptions.
+ */
+declare class UrScanner {
+  private readonly decoder;
+  private readonly expectedTypes;
+  private readonly seen;
+  private rejection;
+  /** Distinct frames remembered for dedup. Attacker-suppliable strings, so capped. */
+  private static readonly maxRememberedFrames;
+  constructor(options?: UrScannerOptions);
+  get isComplete(): boolean;
+  get progress(): number;
+  /** The UR type of the bound stream, or null until one binds. */
+  get urType(): string | null;
+  get framesReceived(): number;
+  get framesExpected(): number;
+  get lastRejection(): ScanRejection | null;
+  /** Feed one scanned frame. */
+  receivePart(frame: string): ScanFeedResult;
+  /** The assembled UR. Throws `incomplete-scan` until done. */
+  result(): Ur;
+  private reject;
+}
+/** A scanner whose completed UR parses into a typed result (a chain signature). */
+declare class TypedUrScanner<TResult> extends UrScanner {
+  private readonly parseResult;
+  constructor(options: UrScannerOptions, parseResult: (ur: Ur) => TResult);
+  /** Assemble + parse + validate (UR type, request-id echo) in one call. */
+  parse(): TResult;
+}
+//#endregion
+//#region src/chains/shared.d.ts
+/** Resolved SDK configuration handed to every chain module. */
+interface ChainContext {
+  readonly origin: string;
+  readonly randomBytes: RandomBytesFn | undefined;
+  readonly maxFragmentLength: number;
+}
+/** SDK configuration. Everything is optional; the SDK performs NO network I/O ever. */
+interface EraConnectConfig {
+  /**
+   * Wallet name the device shows the user on every request ("Sign for
+   * <origin>?"). Set it once here; individual requests can override.
+   */
+  readonly origin?: string | undefined;
+  /**
+   * CSPRNG override. By default `globalThis.crypto.getRandomValues` is used;
+   * on React Native install `react-native-get-random-values`, or inject a
+   * secure source here. Request-id minting throws `no-secure-random` when
+   * neither is available.
+   */
+  readonly randomBytes?: RandomBytesFn | undefined;
+  /** Default payload bytes per animated-QR fragment (180 unless overridden). */
+  readonly maxFragmentLength?: number | undefined;
+}
+declare const DEFAULT_ORIGIN = "ERA Connect";
+/** Optional expectations when parsing a reply standalone (outside `SignRequest.scanner()`). */
+interface ExpectedReply {
+  readonly requestId?: Uint8Array | string;
+}
+/**
+ * A built sign request: the UR to display plus everything needed to consume
+ * the reply. The request id is minted at CONSTRUCTION so the same object that
+ * renders the QR also validates the echo — a reply carrying a different id
+ * (from an earlier, cancelled flow re-presented to the camera) is refused
+ * instead of accepted.
+ */
+interface SignRequest<TResult> {
+  readonly ur: Ur;
+  /** Absent only where the protocol has no request id (Bitcoin PSBT). */
+  readonly requestId: Uint8Array | undefined;
+  /** UR types that can answer THIS request. */
+  readonly replyTypes: readonly string[];
+  /** Non-fatal advisories (e.g. `blind-sign-threshold`). */
+  readonly warnings: readonly string[];
+  /** Fragment + animate for display. */
+  toAnimated(options?: AnimatedUrOptions): AnimatedUr;
+  /** A scanner pre-pinned to `replyTypes`; its `parse()` validates the request-id echo. */
+  scanner(): TypedUrScanner<TResult>;
+}
+//#endregion
+export { Ur as _, SignRequest as a, TypedUrScanner as c, EraErrorCode as d, EraSdkError as f, RandomBytesFn as g, DEFAULT_FRAGMENT_LENGTH as h, ExpectedReply as i, UrScanner as l, AnimatedUrOptions as m, DEFAULT_ORIGIN as n, ScanFeedResult as o, AnimatedUr as p, EraConnectConfig as r, ScanRejection as s, ChainContext as t, UrScannerOptions as u };
+//# sourceMappingURL=shared-CI8zhQiE.d.ts.map