@invisible-labs/sdk 0.6.0-devnet.1

package/dist/index.d.ts

@@ -0,0 +1,499 @@
+import { S as Session } from './session-DFuy54C-.js';
+export { i as isAttested } from './session-DFuy54C-.js';
+export { A as AttestationError, a as AttestationErrorCode, b as CommandError, c as CommandErrorCode, d as CommandErrorOptions, e as CoordinatorWireErrorCode, C as CreateSessionOptions, I as InvalidDepositAmountError, f as InvisibleError, g as InvisibleErrorCode, h as InvisibleErrorOptions, L as LpLifecycleError, i as LpLifecycleErrorCode, N as NotImplementedError, j as NotImplementedErrorCode, P as PolicyValidationError, k as PolicyValidationErrorCode, R as RoutingError, l as RoutingErrorCode, S as StorageError, m as StorageErrorCode, T as TransportError, n as TransportErrorCode, W as WalletError, o as WalletErrorCode, p as closeSession, q as createSession, r as isInvisibleError, s as normalizeError } from './createSession-D3ym-Ira.js';
+import { T as Transport, N as NoiseWebSocketTransportOptions, U as Unsubscribe } from './types-ZhV7TIQY.js';
+export { C as ConnectionState, W as WebSocketFactory, a as WebSocketLike } from './types-ZhV7TIQY.js';
+import { C as CoordinatorEndpoint, b as CoordinatorReleasePin } from './types.generated-CHGSbmLp.js';
+export { A as AzureMaaPin, a as CoordinatorPoolConfig, L as LpPositionView, c as PayoutDestination, P as PayoutPolicy, S as StorageEnvelope } from './types.generated-CHGSbmLp.js';
+
+/**
+ * The API surface version this build implements. Bumped only on a breaking
+ * surface change. See docs/sdk-specification.md section 12.
+ */
+declare const apiVersion: "v0";
+/** Literal type of {@link apiVersion}. */
+type ApiVersion = typeof apiVersion;
+
+/**
+ * Branded scalar types.
+ *
+ * Branding makes structurally-identical primitives (a lamport amount, a base58
+ * address, a correlation id) non-interchangeable at the type level, so the
+ * compiler catches "passed a request id where an address was expected" before
+ * it reaches the wire. The brand exists only at compile time; at runtime these
+ * are plain `number` / `string`.
+ *
+ * Construct branded values through the smart constructors here. These
+ * constructors enforce scalar-level invariants; payout-policy semantics stay in
+ * the validation module.
+ */
+/** Attach a compile-time-only brand `B` to base type `T`. */
+type Brand<T, B extends string> = T & {
+    readonly __brand: B;
+};
+/** A non-negative integer amount of lamports (1 SOL = 1_000_000_000 lamports). */
+type Lamports = Brand<number, "Lamports">;
+/** A Solana account address as base58 text. */
+type PublicKey = Brand<string, "PublicKey">;
+/** A client-generated correlation id for one logical command. */
+type RequestId = Brand<string, "RequestId">;
+/** Lowercase hexadecimal text (no `0x` prefix). */
+type Hex = Brand<string, "Hex">;
+/**
+ * Brand a number as {@link Lamports}.
+ *
+ * @throws PolicyValidationError `INVALID_AMOUNT` if not a non-negative safe integer.
+ */
+declare function lamports(value: number): Lamports;
+/**
+ * Brand a string as a {@link PublicKey}.
+ *
+ * Enforces canonical base58 encoding of a 32-byte Solana public key.
+ *
+ * @throws PolicyValidationError `INVALID_DESTINATION_ADDRESS` if obviously malformed.
+ */
+declare function publicKey(value: string): PublicKey;
+/**
+ * Brand a non-empty string as a {@link RequestId}.
+ *
+ * @throws PolicyValidationError `INVALID_AMOUNT` is not appropriate here; an empty
+ *   id is a programming error, so this throws a plain `Error`.
+ */
+declare function requestId(value: string): RequestId;
+/**
+ * Brand a string as lowercase {@link Hex}.
+ *
+ * @throws Error if the string contains non-hex characters.
+ */
+declare function hex(value: string): Hex;
+
+interface ExponentialBackoffOptions {
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+    readonly multiplier?: number;
+    readonly jitterRatio?: number;
+    readonly random?: () => number;
+}
+interface ExponentialBackoff {
+    nextDelayMs(): number;
+    reset(): void;
+}
+/**
+ * Stateful exponential backoff shared by reconnecting SDK consumers.
+ * Jitter avoids synchronized reconnect storms while reset makes a healthy
+ * connection return to the normal cadence.
+ */
+declare function createExponentialBackoff(options: ExponentialBackoffOptions): ExponentialBackoff;
+
+/**
+ * In-memory transport.
+ *
+ * A zero-network channel used by unit tests. It transitions straight to `open`
+ * on connect. `send` delivers the raw frame bytes to an optional peer sink: the
+ * WebSocket message boundary is the frame boundary, so there is no extra length
+ * prefix (matching the production transport). Noise lives above this pure byte
+ * channel, never inside it.
+ *
+ * With no peer wired in, `send` is a silent no-op (legacy stub behaviour for
+ * tests that never exchange frames). A paired loopback coordinator supplies a
+ * `peer` sink so a real Noise XX handshake can run in-process (see the
+ * `testLoopback` fixture).
+ */
+
+/** Options for {@link inMemoryTransport}. Test-only paired-loopback wiring. */
+interface InMemoryTransportOptions {
+    /**
+     * Sink for frames written via `send()`. A paired in-process coordinator sets
+     * this so the client's raw bytes reach the responder. When omitted, `send`
+     * is a no-op so legacy stub-only tests keep working.
+     */
+    readonly peer?: (frame: Uint8Array) => void;
+}
+/** In-memory transport with a hook to feed inbound frames into `onMessage`. */
+interface InMemoryTransportHandle extends Transport {
+    /** Deliver a frame to this transport's `onMessage` listeners (peer -> client). */
+    readonly deliver: (frame: Uint8Array) => void;
+}
+declare function inMemoryTransport(options?: InMemoryTransportOptions): InMemoryTransportHandle;
+
+/**
+ * WebSocket transport - the one genuinely functional piece of the skeleton.
+ *
+ * `connect()` opens a real WebSocket and drives the lifecycle
+ * (`connecting -> open`, `-> closed` on close/error/abort). It is a pure byte
+ * channel: the Noise XX handshake and TDX attestation are session-level steps
+ * layered on top (see ./handshake), not part of opening the socket. `send`
+ * writes one raw frame to the socket; the WebSocket message boundary is the
+ * frame boundary, so there is no extra length prefix (Noise lives above).
+ *
+ * The WebSocket implementation is injected (default: the platform global
+ * `WebSocket`, present in browsers and Node 22+), so tests connect to a local
+ * mock server with no external network.
+ */
+
+declare function noiseWebSocketTransport(options: NoiseWebSocketTransportOptions): Transport;
+
+/**
+ * TDX DCAP attestation verifier (SDK port of
+ * `web/src/lib/coordinator/tdx-attestation.ts`).
+ *
+ * Verifies a TDX DCAP quote on three paths, using Web Crypto (`crypto.subtle`,
+ * a Node 22 / browser global) and `@peculiar/x509`:
+ *
+ *   - GCP  (spec section 5.1): cert chain to the pinned Intel SGX Root CA, TCB
+ *     validity, freshness nonce == REPORT_DATA[0:32], Noise binding ==
+ *     REPORT_DATA[32:64], debug bit clear, MRTD pin.
+ *   - Azure (spec section 5.2): MAA JWT issuer / JWKS / policy-hash / compliance
+ *     / debug, MAA<->DCAP REPORTDATA binding, hcl_keys hash binding, HCL AK pub
+ *     extraction, raw DCAP measurement binding, TPM AK quote signature, TPM
+ *     qualifying data binding.
+ *   - Local (loopback dev fallback): checks nonce and Noise pubkey consistency
+ *     only; no hardware attestation.
+ *
+ * Throws the SDK {@link AttestationError} (from `../core/errors.js`) with a
+ * closed `code` on any failure. Callers fail-closed: tear down the Noise
+ * transport rather than surface an unverified channel.
+ *
+ * Never log secrets, nonces, or raw decrypted payloads (spec section 9).
+ *
+ * @module JW-145 / JW-431
+ */
+type AttestationMode = "dev" | "prod";
+type AzureMaaPolicy = {
+    /** Expected MAA token issuer for the approved Azure Attestation provider. */
+    expectedIssuer: string;
+    /** Expected JWKS endpoint for that provider. Token headers must not choose it. */
+    expectedJwksUrl: string;
+    /** Expected Azure Attestation evaluation policy hash from the signed token. */
+    expectedPolicyHash: string;
+};
+type AttestationPolicy = {
+    /**
+     * Expected MRTD for the published production coordinator build.
+     * Dev mode ignores this pin entirely.
+     */
+    expectedMrtd?: string;
+    /**
+     * SHA-256 hash of the approved coordinator binary. Azure production
+     * attestation requires this pin because binary_hash is otherwise only
+     * response metadata, even though the TPM quote binds it cryptographically.
+     */
+    expectedBinaryHash?: string;
+    /**
+     * Runtime mode the client expects for this coordinator route. Production
+     * builds set this to "prod" so a prod hostname cannot silently accept an
+     * unpinned dev coordinator after DNS or load-balancer misrouting.
+     */
+    requiredMode?: AttestationMode;
+    /**
+     * Release tooling only: verify a prod quote before the new MRTD has been
+     * published. Runtime policy must leave this unset so prod stays fail-closed
+     * when the pin is missing.
+     */
+    allowUnpinnedProdMrtdForRelease?: boolean;
+    /**
+     * SHA-256 fingerprint (lowercase hex) of the DER-encoded Intel SGX Root CA.
+     * Defaults to {@link INTEL_SGX_ROOT_CA_FINGERPRINT_SHA256}. Override only in tests.
+     */
+    intelRootFingerprint?: string;
+    /**
+     * Temporary non-prod rollout escape hatch for legacy coordinators that have
+     * not rolled out `dcap_collateral`. When collateral is present, it is always
+     * verified. Production mode never honors this flag.
+     */
+    allowMissingDcapCollateral?: boolean;
+    /**
+     * Development-only escape hatch for a local coordinator running on a non-TDX
+     * machine. The transport only honors this for loopback coordinator URLs.
+     */
+    allowLocalAttestation?: boolean;
+    /**
+     * Azure-specific trust policy. Required for platform="azure-tdx-dcap" because
+     * MAA providers and policies are customer-configurable Azure resources.
+     */
+    azureMaa?: AzureMaaPolicy;
+};
+type SignedDcapJson = {
+    /**
+     * JSON string returned by Intel PCS. May be either the inner body
+     * (`tcbInfo` / `enclaveIdentity`) or the full PCS wrapper.
+     */
+    body: string;
+    /** Hex signature over the exact signed body bytes. */
+    signature: string;
+    /** PEM chain whose first certificate verifies `signature`, ending at Intel root. */
+    issuerChainPem: string;
+};
+type DcapCollateral = {
+    /** PEM X.509 CRL for the PCK certificate issuer. */
+    pckCrlPem: string;
+    /** PEM chain for the PCK CRL issuer, ending at Intel root. */
+    pckCrlIssuerChainPem: string;
+    /** PEM X.509 CRL issued by Intel root, covering collateral signing certs. */
+    rootCaCrlPem: string;
+    /** Signed Intel TDX TCB Info V3. */
+    tcbInfo: SignedDcapJson;
+    /** Signed Intel TD QE Identity V2. */
+    qeIdentity: SignedDcapJson;
+};
+type AttestedMetadata = {
+    mode: AttestationMode;
+    binaryHash: string;
+    mrtd: string;
+    rtmr0: string;
+    rtmr1: string;
+    rtmr2: string;
+    rtmr3: string;
+    pubkeyHex: string;
+    localAttestation: boolean;
+};
+type AttestResponse = {
+    quote: string;
+    /**
+     * Nonce echoed back by the coordinator. Informational only: freshness is
+     * enforced cryptographically via REPORT_DATA[0:32] inside the TDX quote, not
+     * by trusting this JSON field.
+     */
+    nonce: string;
+    pubkey: string;
+    binary_hash: string;
+    mode: AttestationMode;
+    /**
+     * Platform identifier set by the coordinator. Absent on GCP (tdx-dcap).
+     * Azure returns "azure-tdx-dcap".
+     */
+    platform?: string;
+    /**
+     * Azure only: MAA JWT from /attest/TdxVm, RS256-signed by MAA. Contains
+     * tdx_mrtd, tdx_td_attributes_debug, and x-ms-compliance-status.
+     */
+    maa_token?: string;
+    /**
+     * Azure only: TPM PCR quote packed as
+     * [4-byte msg_len LE][TPM2B_ATTEST][TPMT_SIGNATURE].
+     * qualifying_data = SHA-256(nonce || noise_pubkey || binary_hash). Base64-encoded.
+     */
+    tpm_quote?: string;
+    /**
+     * Azure only: raw bytes (base64) of the JSON key-blob from HCL report NV
+     * 0x1400001 [1056:]. SHA-256(hcl_keys_json_bytes) == DCAP REPORTDATA[0:32].
+     * Contains the AK public key as kid="HCLAkPub".
+     */
+    hcl_keys_json?: string;
+    /**
+     * Intel DCAP verification collateral. When present, the verifier evaluates
+     * PCK revocation, TCB Info, and TD QE Identity. Policies can require it.
+     */
+    dcap_collateral?: DcapCollateral;
+    local_attestation?: boolean;
+};
+/**
+ * Assert that an unknown JSON value has the shape of {@link AttestResponse}.
+ * Throws {@link AttestationError} ("NOT_ATTESTED") on any missing or wrong-typed
+ * field. Replaces an unsafe cast so missing fields produce a typed error rather
+ * than silently reaching downstream checks as `undefined`.
+ */
+declare function assertAttestResponse(value: unknown): asserts value is AttestResponse;
+declare function verifyAttestation(params: {
+    response: AttestResponse;
+    expectedNonce: Uint8Array;
+    expectedNoiseStaticPub: Uint8Array;
+    policy: AttestationPolicy;
+    timeoutMs?: number;
+}): Promise<AttestedMetadata>;
+
+/**
+ * Secure channel: Noise XX handshake + TDX attestation over a raw transport.
+ *
+ * Free functions, no class (SDK conformance). Given an open {@link Transport}
+ * and a {@link CoordinatorEndpoint}, {@link establishSecureChannel} drives:
+ *
+ *   1. the Noise XX handshake (initiator role) over the raw byte channel:
+ *        -> msg1 (e)            send raw
+ *        <- msg2 (e, ee, s, es) read raw, reveals the responder static pubkey
+ *        -> msg3 (s, se)        send raw, yields the split NoiseTransport
+ *   2. the attestation exchange over the freshly-split (but not-yet-promoted)
+ *      Noise transport:
+ *        -> encrypt(encodeAttestationRequest(nonceHex))
+ *        <- decodeAttestationResponse(decrypt(frame)) -> verifyAttestation
+ *
+ * On success the pending Noise transport is promoted to the live cipher and an
+ * attested channel handle is returned: `send`/`onMessage` transparently
+ * Noise-encrypt/decrypt application frames over the raw transport.
+ *
+ * The release pin (mrtd, intelRootFingerprint, azureMaa) and the endpoint's
+ * requiredMode map to the verifier's {@link AttestationPolicy}. The loopback
+ * local-attestation fallback (ADR-0037) is only enabled when the endpoint host
+ * is a loopback address - it must never be honored for a remote coordinator.
+ *
+ * Never log secrets, nonces, shares, or decrypted payloads (spec section 9).
+ *
+ * @module JW-428
+ */
+
+/** An established, attested Noise channel over a raw transport. */
+interface SecureChannel {
+    /** Verified attestation metadata for the coordinator this channel reached. */
+    readonly attestation: AttestedMetadata;
+    /** The coordinator's Noise static public key, pinned for this channel. */
+    readonly remoteStaticPublicKey: Uint8Array;
+    /** Request re-attestation without consuming application frames as responses. */
+    requestAttestation(nonceHex: string, timeoutMs: number): Promise<AttestResponse>;
+    /** Encrypt and send one application frame over the raw transport. */
+    send(plaintext: Uint8Array): void;
+    /** Subscribe to decrypted inbound application frames. */
+    onMessage(handler: (plaintext: Uint8Array) => void): Unsubscribe;
+    /** Subscribe to fatal channel failures such as Noise decrypt desync. */
+    onFatal(handler: (error: Error) => void): Unsubscribe;
+    /** Tear down the channel: detach listeners and stop accepting frames. */
+    close(): void;
+}
+
+/**
+ * Session-establishment seams layered on top of an open {@link Transport}.
+ *
+ * Once a socket is open, a session runs the Noise XX handshake and then TDX
+ * attestation before any sensitive command is allowed. The real logic lives in
+ * the secure-channel module (`../session/secureChannel`); these functions are
+ * the stable, transport-level entrypoints the root index re-exports.
+ *
+ * Both halves are driven from one underlying {@link establishSecureChannel}
+ * run, because attestation is requested over the same Noise cipher the
+ * handshake split. {@link performNoiseHandshake} runs that establishment and
+ * caches the resulting channel keyed on the transport; {@link performAttestation}
+ * reads the attestation evidence from it. Callers that want the whole flow in
+ * one step should use {@link establishAttestedChannel}.
+ */
+
+/** Result of a completed Noise XX handshake. */
+interface NoiseHandshakeResult {
+    /** The coordinator's Noise static public key, pinned for this session. */
+    readonly noiseStaticPublicKey: Uint8Array;
+    /**
+     * The attested secure channel produced by this handshake. Carried so a
+     * subsequent {@link performAttestation} can read attestation evidence without
+     * re-running the exchange. Internal: not part of the structural contract.
+     */
+    readonly channel: SecureChannel;
+}
+/** Result of a completed TDX attestation. */
+interface AttestationResult {
+    /** The verified release MRTD. */
+    readonly mrtd: string;
+    /** Attestation mode the coordinator reported. */
+    readonly mode: "prod" | "dev";
+    /** Coordinator binary hash reported by the verified attestation response. */
+    readonly binaryHash: string;
+    /** Noise static public key bound into the attestation quote. */
+    readonly pubkeyHex: string;
+    /** True only for explicit loopback local development attestation. */
+    readonly localAttestation: boolean;
+    readonly rtmr0?: string;
+    readonly rtmr1?: string;
+    readonly rtmr2?: string;
+    readonly rtmr3?: string;
+    /** When verification completed (epoch ms), stamped by the caller. */
+    readonly verifiedAtMs: number;
+}
+/**
+ * Run the Noise XX handshake over an open transport and pin the coordinator's
+ * static key. Drives a full attested-channel establishment (attestation is
+ * bound to the same Noise cipher) and returns the handshake half; read the
+ * attestation half from {@link performAttestation} with the returned result.
+ *
+ * @throws TransportError if the channel fails or the handshake is malformed.
+ * @throws AttestationError if attestation verification fails.
+ */
+declare function performNoiseHandshake(transport: Transport, endpoint: CoordinatorEndpoint, nonce?: Uint8Array): Promise<NoiseHandshakeResult>;
+/**
+ * Verify the coordinator's TDX attestation, bound to the handshake's Noise
+ * static key. Reads the evidence captured by {@link performNoiseHandshake}.
+ *
+ * @throws TransportError if the handshake result carries no channel.
+ */
+declare function performAttestation(_transport: Transport, handshake: NoiseHandshakeResult): Promise<AttestationResult>;
+
+/**
+ * Session guards used by mutating commands.
+ */
+
+/**
+ * Assert the session has passed attestation. Every mutating actor command calls
+ * this before touching the wire, so an unattested session can never sign or
+ * send sensitive material.
+ *
+ * @throws AttestationError `NOT_ATTESTED` when the session is not attested.
+ */
+declare function assertAttested(session: Session): void;
+
+/**
+ * `attestation` - read controls and verification triggers (spec section 4.1).
+ *
+ * Grouped as a small object of free functions over the opaque `Session`. The
+ * read accessors (`current`, `policy`) report the last verified result and the
+ * active pin; `assertValid` re-runs attestation over the live channel and
+ * `onPolicyViolation` subscribes to out-of-band re-attestation failures.
+ */
+
+declare const attestation: {
+    /**
+     * Force-verify the current session against the active policy by re-running
+     * attestation over the live channel. Updates the stored result on success.
+     *
+     * @throws AttestationError if verification fails.
+     * @throws TransportError if the session has no live attested channel.
+     */
+    assertValid(session: Session): Promise<AttestationResult>;
+    /** The last verified attestation result, or `null` before first attestation. */
+    current(session: Session): AttestationResult | null;
+    /** The release pin the active leader endpoint is verified against. Read-only. */
+    policy(session: Session): CoordinatorReleasePin;
+    /**
+     * Subscribe to out-of-band attestation failures (e.g. during periodic
+     * re-attestation). The handler fires with the verification error; returns an
+     * unsubscribe function.
+     */
+    onPolicyViolation(session: Session, handler: (error: Error) => void): Unsubscribe;
+};
+
+/**
+ * `coordinator` - endpoint pool inspection and failover (spec section 4.2).
+ *
+ * `endpoints` is a read accessor that works today. Leader discovery, version
+ * reporting, and failover depend on the coordinator network surface and are
+ * deferred (marked 🟡 V0-target in the spec).
+ */
+
+/** Coordinator-reported version and role snapshot. */
+interface CoordinatorVersion {
+    readonly mode: "prod" | "dev";
+    readonly protocolVersion: string;
+    readonly schemaVersion: string;
+    readonly hostname: string;
+    readonly leaderEpoch: number;
+}
+declare const coordinator: {
+    /** All configured endpoints, in the order supplied. Read-only. */
+    endpoints(session: Session): readonly CoordinatorEndpoint[];
+    /**
+     * The endpoint currently accepting mutating commands.
+     *
+     * @throws NotImplementedError - deferred (coordinator-pending).
+     */
+    currentLeader(_session: Session): Promise<CoordinatorEndpoint | null>;
+    /**
+     * The coordinator-reported version snapshot.
+     *
+     * @throws NotImplementedError - deferred (coordinator-pending).
+     */
+    version(_session: Session): Promise<CoordinatorVersion>;
+    /**
+     * Tear down the active session and reconnect through the next healthy
+     * endpoint, forcing a fresh attestation.
+     *
+     * @throws NotImplementedError - deferred (coordinator-pending).
+     */
+    forceFailover(_session: Session): Promise<void>;
+};
+
+export { type ApiVersion, type AttestResponse, type AttestationMode, type AttestationPolicy, type AttestationResult, type AzureMaaPolicy, type Brand, CoordinatorEndpoint, CoordinatorReleasePin, type CoordinatorVersion, type ExponentialBackoff, type ExponentialBackoffOptions, type Hex, type Lamports, type NoiseHandshakeResult, NoiseWebSocketTransportOptions, type PublicKey, type RequestId, Session, Transport, Unsubscribe, apiVersion, assertAttestResponse, assertAttested, attestation, coordinator, createExponentialBackoff, hex, inMemoryTransport, lamports, noiseWebSocketTransport, performAttestation, performNoiseHandshake, publicKey, requestId, verifyAttestation };

package/dist/index.js

@@ -0,0 +1,132 @@
+import { createStateController, reattestSerialized } from './chunk-7DSVN3MV.js';
+export { closeSession, createExponentialBackoff, createSession, noiseWebSocketTransport, performAttestation, performNoiseHandshake } from './chunk-7DSVN3MV.js';
+export { assertAttested, hex, lamports, publicKey, requestId } from './chunk-SZAYO2L5.js';
+import { getSessionState, failSessionClosed } from './chunk-JRMKCE3S.js';
+export { assertAttestResponse, verifyAttestation } from './chunk-NCY4FCYU.js';
+import { TransportError, NotImplementedError } from './chunk-OHIM2YWU.js';
+export { AttestationError, CommandError, InvalidDepositAmountError, InvisibleError, LpLifecycleError, NotImplementedError, PolicyValidationError, RoutingError, StorageError, TransportError, WalletError, isInvisibleError, normalizeError } from './chunk-OHIM2YWU.js';
+import './chunk-VR6T6OJS.js';
+
+// src/core/version.ts
+var apiVersion = "v0";
+
+// src/core/session.ts
+function isAttested(session) {
+  return session.attested;
+}
+
+// src/transport/inMemoryTransport.ts
+function inMemoryTransport(options = {}) {
+  const sc = createStateController("idle");
+  const messageListeners = /* @__PURE__ */ new Set();
+  return {
+    state: () => sc.get(),
+    onStateChange: (listener) => sc.onChange(listener),
+    onMessage(listener) {
+      messageListeners.add(listener);
+      return () => messageListeners.delete(listener);
+    },
+    deliver(frame) {
+      for (const listener of messageListeners) listener(frame);
+    },
+    async connect(signal) {
+      if (signal?.aborted) {
+        throw new TransportError("CONNECTION_LOST", "connect aborted before it started");
+      }
+      if (sc.get() === "open") return;
+      sc.set("connecting");
+      sc.set("open");
+    },
+    send(frame) {
+      if (sc.get() !== "open") {
+        throw new TransportError("CONNECTION_LOST", "cannot send on a non-open transport");
+      }
+      options.peer?.(frame);
+    },
+    close() {
+      if (sc.get() === "closed") return;
+      sc.set("closing");
+      sc.set("closed");
+    }
+  };
+}
+
+// src/attestation/index.ts
+var attestation = {
+  /**
+   * Force-verify the current session against the active policy by re-running
+   * attestation over the live channel. Updates the stored result on success.
+   *
+   * @throws AttestationError if verification fails.
+   * @throws TransportError if the session has no live attested channel.
+   */
+  async assertValid(session) {
+    const state = getSessionState(session);
+    const endpoint = state.pool.endpoints[0];
+    try {
+      const result = await reattestSerialized(state, endpoint, state.pool.noiseTransportTimeoutMs);
+      state.attestation = result;
+      state.attested = true;
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      failSessionClosed(state, error);
+      throw error;
+    }
+  },
+  /** The last verified attestation result, or `null` before first attestation. */
+  current(session) {
+    return getSessionState(session).attestation;
+  },
+  /** The release pin the active leader endpoint is verified against. Read-only. */
+  policy(session) {
+    return getSessionState(session).pool.endpoints[0].releasePin;
+  },
+  /**
+   * Subscribe to out-of-band attestation failures (e.g. during periodic
+   * re-attestation). The handler fires with the verification error; returns an
+   * unsubscribe function.
+   */
+  onPolicyViolation(session, handler) {
+    const handlers = getSessionState(session).policyViolationHandlers;
+    handlers.add(handler);
+    return () => handlers.delete(handler);
+  }
+};
+
+// src/coordinator/index.ts
+var coordinator = {
+  /** All configured endpoints, in the order supplied. Read-only. */
+  endpoints(session) {
+    return getSessionState(session).pool.endpoints;
+  },
+  /**
+   * The endpoint currently accepting mutating commands.
+   *
+   * @throws NotImplementedError - deferred (coordinator-pending).
+   */
+  currentLeader(_session) {
+    return Promise.reject(new NotImplementedError("coordinator.currentLeader"));
+  },
+  /**
+   * The coordinator-reported version snapshot.
+   *
+   * @throws NotImplementedError - deferred (coordinator-pending).
+   */
+  version(_session) {
+    return Promise.reject(new NotImplementedError("coordinator.version"));
+  },
+  /**
+   * Tear down the active session and reconnect through the next healthy
+   * endpoint, forcing a fresh attestation.
+   *
+   * @throws NotImplementedError - deferred (coordinator-pending).
+   */
+  forceFailover(_session) {
+    return Promise.reject(new NotImplementedError("coordinator.forceFailover"));
+  }
+};
+
+export { apiVersion, attestation, coordinator, inMemoryTransport, isAttested };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/version.ts","../src/core/session.ts","../src/transport/inMemoryTransport.ts","../src/attestation/index.ts","../src/coordinator/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * The API surface version this build implements. Bumped only on a breaking\n * surface change. See docs/sdk-specification.md section 12.\n */\nexport const apiVersion = \"v0\" as const;\n\n/** Literal type of {@link apiVersion}. */\nexport type ApiVersion = typeof apiVersion;\n","/**\n * The opaque session handle.\n *\n * A `Session` is the single stateful object the functional surface threads\n * through every call: `fn(session, args)`. It owns the transport, the\n * attestation state, and (later) the leader-epoch bookkeeping. Consumers treat\n * it as opaque - they read `session.attested` and pass it back to SDK\n * functions, but never reach inside. The internal state map and constructor\n * live alongside `createSession` (added in a later ticket); this module only\n * fixes the public shape so the rest of the surface can type against it.\n */\n\ndeclare const sessionBrand: unique symbol;\n\n/**\n * Opaque, attested session handle. Obtain one from `createSession`; pass it as\n * the first argument to every actor command. The only field consumers read is\n * {@link Session.attested}.\n */\nexport interface Session {\n  /**\n   * Whether the current Noise session has passed full TDX attestation. Sensitive\n   * commands refuse to run until this is `true`. Re-handshake or failover resets\n   * it to `false` until a fresh attestation completes.\n   */\n  readonly attested: boolean;\n  /** @internal Opacity brand; not constructable by consumers. */\n  readonly [sessionBrand]: true;\n}\n\n/** Convenience predicate mirroring {@link Session.attested}. */\nexport function isAttested(session: Session): boolean {\n  return session.attested;\n}\n","/**\n * In-memory transport.\n *\n * A zero-network channel used by unit tests. It transitions straight to `open`\n * on connect. `send` delivers the raw frame bytes to an optional peer sink: the\n * WebSocket message boundary is the frame boundary, so there is no extra length\n * prefix (matching the production transport). Noise lives above this pure byte\n * channel, never inside it.\n *\n * With no peer wired in, `send` is a silent no-op (legacy stub behaviour for\n * tests that never exchange frames). A paired loopback coordinator supplies a\n * `peer` sink so a real Noise XX handshake can run in-process (see the\n * `testLoopback` fixture).\n */\n\nimport { TransportError } from \"../core/errors.js\";\nimport { createStateController } from \"./stateController.js\";\nimport type { Transport, Unsubscribe } from \"./types.js\";\n\n/** Options for {@link inMemoryTransport}. Test-only paired-loopback wiring. */\nexport interface InMemoryTransportOptions {\n  /**\n   * Sink for frames written via `send()`. A paired in-process coordinator sets\n   * this so the client's raw bytes reach the responder. When omitted, `send`\n   * is a no-op so legacy stub-only tests keep working.\n   */\n  readonly peer?: (frame: Uint8Array) => void;\n}\n\n/** In-memory transport with a hook to feed inbound frames into `onMessage`. */\nexport interface InMemoryTransportHandle extends Transport {\n  /** Deliver a frame to this transport's `onMessage` listeners (peer -> client). */\n  readonly deliver: (frame: Uint8Array) => void;\n}\n\nexport function inMemoryTransport(options: InMemoryTransportOptions = {}): InMemoryTransportHandle {\n  const sc = createStateController(\"idle\");\n  const messageListeners = new Set<(frame: Uint8Array) => void>();\n\n  return {\n    state: () => sc.get(),\n    onStateChange: (listener) => sc.onChange(listener),\n    onMessage(listener): Unsubscribe {\n      messageListeners.add(listener);\n      return () => messageListeners.delete(listener);\n    },\n    deliver(frame: Uint8Array): void {\n      for (const listener of messageListeners) listener(frame);\n    },\n    async connect(signal) {\n      if (signal?.aborted) {\n        throw new TransportError(\"CONNECTION_LOST\", \"connect aborted before it started\");\n      }\n      if (sc.get() === \"open\") return;\n      sc.set(\"connecting\");\n      sc.set(\"open\");\n    },\n    send(frame: Uint8Array): void {\n      if (sc.get() !== \"open\") {\n        throw new TransportError(\"CONNECTION_LOST\", \"cannot send on a non-open transport\");\n      }\n      options.peer?.(frame);\n    },\n    close() {\n      if (sc.get() === \"closed\") return;\n      sc.set(\"closing\");\n      sc.set(\"closed\");\n    },\n  };\n}\n","/**\n * `attestation` - read controls and verification triggers (spec section 4.1).\n *\n * Grouped as a small object of free functions over the opaque `Session`. The\n * read accessors (`current`, `policy`) report the last verified result and the\n * active pin; `assertValid` re-runs attestation over the live channel and\n * `onPolicyViolation` subscribes to out-of-band re-attestation failures.\n */\n\nimport type { Session } from \"../core/session.js\";\nimport type { Unsubscribe } from \"../transport/types.js\";\nimport type { AttestationResult } from \"../transport/handshake.js\";\nimport type { CoordinatorReleasePin } from \"../schemas/types.generated.js\";\nimport { failSessionClosed, getSessionState } from \"../session/state.js\";\nimport { reattestSerialized } from \"./reattest.js\";\n\nexport const attestation = {\n  /**\n   * Force-verify the current session against the active policy by re-running\n   * attestation over the live channel. Updates the stored result on success.\n   *\n   * @throws AttestationError if verification fails.\n   * @throws TransportError if the session has no live attested channel.\n   */\n  async assertValid(session: Session): Promise<AttestationResult> {\n    const state = getSessionState(session);\n    const endpoint = state.pool.endpoints[0]!;\n    try {\n      const result = await reattestSerialized(state, endpoint, state.pool.noiseTransportTimeoutMs);\n      state.attestation = result;\n      state.attested = true;\n      return result;\n    } catch (err) {\n      const error = err instanceof Error ? err : new Error(String(err));\n      failSessionClosed(state, error);\n      throw error;\n    }\n  },\n\n  /** The last verified attestation result, or `null` before first attestation. */\n  current(session: Session): AttestationResult | null {\n    return getSessionState(session).attestation;\n  },\n\n  /** The release pin the active leader endpoint is verified against. Read-only. */\n  policy(session: Session): CoordinatorReleasePin {\n    return getSessionState(session).pool.endpoints[0]!.releasePin;\n  },\n\n  /**\n   * Subscribe to out-of-band attestation failures (e.g. during periodic\n   * re-attestation). The handler fires with the verification error; returns an\n   * unsubscribe function.\n   */\n  onPolicyViolation(session: Session, handler: (error: Error) => void): Unsubscribe {\n    const handlers = getSessionState(session).policyViolationHandlers;\n    handlers.add(handler);\n    return () => handlers.delete(handler);\n  },\n};\n","/**\n * `coordinator` - endpoint pool inspection and failover (spec section 4.2).\n *\n * `endpoints` is a read accessor that works today. Leader discovery, version\n * reporting, and failover depend on the coordinator network surface and are\n * deferred (marked 🟡 V0-target in the spec).\n */\n\nimport { NotImplementedError } from \"../core/errors.js\";\nimport type { Session } from \"../core/session.js\";\nimport type { CoordinatorEndpoint } from \"../schemas/types.generated.js\";\nimport { getSessionState } from \"../session/state.js\";\n\n/** Coordinator-reported version and role snapshot. */\nexport interface CoordinatorVersion {\n  readonly mode: \"prod\" | \"dev\";\n  readonly protocolVersion: string;\n  readonly schemaVersion: string;\n  readonly hostname: string;\n  readonly leaderEpoch: number;\n}\n\nexport const coordinator = {\n  /** All configured endpoints, in the order supplied. Read-only. */\n  endpoints(session: Session): readonly CoordinatorEndpoint[] {\n    return getSessionState(session).pool.endpoints;\n  },\n\n  /**\n   * The endpoint currently accepting mutating commands.\n   *\n   * @throws NotImplementedError - deferred (coordinator-pending).\n   */\n  currentLeader(_session: Session): Promise<CoordinatorEndpoint | null> {\n    return Promise.reject(new NotImplementedError(\"coordinator.currentLeader\"));\n  },\n\n  /**\n   * The coordinator-reported version snapshot.\n   *\n   * @throws NotImplementedError - deferred (coordinator-pending).\n   */\n  version(_session: Session): Promise<CoordinatorVersion> {\n    return Promise.reject(new NotImplementedError(\"coordinator.version\"));\n  },\n\n  /**\n   * Tear down the active session and reconnect through the next healthy\n   * endpoint, forcing a fresh attestation.\n   *\n   * @throws NotImplementedError - deferred (coordinator-pending).\n   */\n  forceFailover(_session: Session): Promise<void> {\n    return Promise.reject(new NotImplementedError(\"coordinator.forceFailover\"));\n  },\n};\n"]}