@ab-org/sdk-core 0.1.1 → 0.1.2-beta.0

package/dist/cubeSignerAuth-DrPc9FeB.d.ts

@@ -0,0 +1,426 @@
+type WalletCapability = "eth_accounts" | "eth_requestAccounts" | "eth_chainId" | "eth_signTransaction" | "eth_sendTransaction" | "personal_sign" | "eth_signTypedData_v4" | "wallet_disconnect" | "wallet_rehydrate" | string;
+interface SessionCapabilityPolicy {
+    id: string;
+    appId?: string;
+    origin?: string;
+    expiresAt?: number;
+    methods?: WalletCapability[];
+    chains?: SupportedChain[];
+    tokens?: SupportedToken[];
+    maxAmount?: string;
+    revocable?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface SessionCapabilityCheck {
+    capability: WalletCapability;
+    chain?: SupportedChain;
+    token?: SupportedToken;
+    amount?: string | number | bigint;
+    appId?: string;
+    origin?: string;
+    now?: number;
+}
+declare class SessionCapabilityError extends Error {
+    constructor(message: string);
+}
+declare const createSessionCapabilityPolicy: (input?: Partial<SessionCapabilityPolicy>) => SessionCapabilityPolicy;
+declare const isSessionExpired: (session: Pick<WalletSession, "expiresAt"> | null | undefined, now?: number) => boolean;
+declare const isCapabilityPolicyExpired: (policy: SessionCapabilityPolicy | null | undefined, now?: number) => boolean;
+declare const sessionSupportsCapability: (session: Pick<WalletSession, "capabilities"> | null | undefined, capability: WalletCapability) => boolean;
+declare const describeSessionCapabilityPolicy: (policy: SessionCapabilityPolicy | null | undefined) => string[];
+declare const assertSessionCapability: (session: WalletSession, check: SessionCapabilityCheck) => void;
+
+type ChainNamespace = "evm" | "solana" | "ab-core";
+type ChainRpcFamily = "evm" | "solana" | "custom";
+interface ChainDescriptor {
+    chain: SupportedChain;
+    namespace: ChainNamespace;
+    reference: string;
+    label: string;
+    rpcFamily: ChainRpcFamily;
+    evmChainId?: number;
+    supportsSmartSessions: boolean;
+    supportsAccountAbstraction: boolean;
+}
+interface ChainContext {
+    walletChain: SupportedChain;
+    walletChainDescriptor: ChainDescriptor;
+    settlementChain: SupportedChain;
+    settlementChainDescriptor: ChainDescriptor;
+}
+declare const getChainDescriptor: (chain: SupportedChain) => ChainDescriptor;
+declare const getAllChainDescriptors: () => ChainDescriptor[];
+declare const getSupportedChainFromEvmChainId: (value: string | number | bigint) => SupportedChain;
+declare const createChainContext: (walletChain: SupportedChain, settlementChain?: SupportedChain) => ChainContext;
+
+type SupportedChain = "AB_CORE" | "ETH" | "BSC" | "SOL" | "ETH_TENDERLY" | "BSC_TENDERLY";
+type SupportedToken = "USD1" | "USDC" | "USDT" | "ETH" | "AB";
+type ProviderCategory = "plugin" | "social";
+type WalletType = "injected" | "social" | "smart";
+type WalletAuthSource = "google" | "twitter" | "wallet" | "session";
+type EvmQuantity = string | number | bigint;
+interface EvmAccessListItem {
+    address: string;
+    storageKeys?: string[];
+}
+interface EvmTransactionRequest {
+    from?: string;
+    to?: string;
+    data?: string;
+    gas?: EvmQuantity;
+    gasPrice?: EvmQuantity;
+    maxFeePerGas?: EvmQuantity;
+    maxPriorityFeePerGas?: EvmQuantity;
+    nonce?: EvmQuantity;
+    value?: EvmQuantity;
+    type?: EvmQuantity;
+    chainId?: EvmQuantity;
+    accessList?: EvmAccessListItem[];
+}
+interface WalletProviderRequest {
+    method: string;
+    params?: unknown[];
+}
+interface WalletProvider {
+    request<T = unknown>(payload: WalletProviderRequest): Promise<T>;
+    disconnect(): Promise<void>;
+}
+interface WalletConnectArgs {
+    options?: unknown;
+    payload?: unknown;
+}
+interface WalletAdapter {
+    id: string;
+    title: string;
+    icon?: string;
+    category?: ProviderCategory;
+    connect(args?: WalletConnectArgs): Promise<WalletSession>;
+    disconnect(): Promise<void>;
+    getProvider(): WalletProvider | null;
+    /**
+     * Silently restore a wallet session from persisted data without user interaction.
+     * Returns a fresh session if the wallet can be reconnected, or null otherwise.
+     */
+    reconnect?(persistedSession: WalletSession): Promise<WalletSession | null>;
+}
+interface WalletSession {
+    address: string;
+    chain: SupportedChain;
+    provider: WalletProvider;
+    walletType?: WalletType;
+    authSource?: WalletAuthSource;
+    sessionId?: string;
+    expiresAt?: number;
+    capabilities?: WalletCapability[];
+    sessionData?: unknown;
+    chainContext?: ChainContext;
+    capabilityPolicy?: SessionCapabilityPolicy;
+}
+interface BalanceInfo {
+    formatted: string;
+    symbol: SupportedToken;
+    wei: bigint;
+}
+interface WalletState {
+    session: WalletSession | null;
+    balance: BalanceInfo | null;
+    isConnecting: boolean;
+}
+
+type Environment = "prod" | "gamma" | "beta";
+interface EnvInterface {
+    Region?: string;
+    SignerApiRoot: string;
+    OrgEventsTopicArn: string;
+}
+type Scope = string;
+type MfaVote = "approve" | "reject";
+interface RatchetConfig {
+    session?: number;
+    auth?: number;
+    refresh?: number;
+    grace?: number;
+}
+interface ClientSessionInfo {
+    session_id: string;
+    epoch: number;
+    epoch_token: string;
+    auth_token_exp: number;
+    refresh_token_exp: number;
+    refresh_token?: string;
+    auth_token?: string;
+    [key: string]: unknown;
+}
+interface SessionData {
+    org_id: string;
+    role_id?: string | null;
+    purpose?: string | null;
+    token: string;
+    refresh_token: string;
+    session_info: ClientSessionInfo;
+    session_exp: number | null | undefined;
+    env: Record<string, EnvInterface>;
+}
+interface SessionMetadata {
+    env: Record<string, EnvInterface>;
+    org_id: string;
+    role_id?: string | null;
+    purpose?: string | null;
+    session_exp: number | null | undefined;
+    session_id: string;
+    epoch: number;
+}
+interface SessionManager {
+    onInvalidToken?: () => void;
+    metadata(): Promise<SessionMetadata>;
+    token(): Promise<string>;
+    retrieve?(): Promise<SessionData>;
+    store?(data: SessionData): Promise<void>;
+}
+interface IdentityProof {
+    user_info?: {
+        initialized?: boolean;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface KeyInfo {
+    key_id: string;
+    material_id: string;
+    public_key: string;
+    key_type: string;
+    [key: string]: unknown;
+}
+interface EvmSignRequest {
+    chain_id: number;
+    tx: Record<string, unknown>;
+}
+interface EvmSignResponse {
+    rlp_signed_tx: string;
+    [key: string]: unknown;
+}
+interface Eip191SignRequest {
+    data: string;
+    metadata?: unknown;
+}
+interface Eip712SignRequest {
+    chain_id: number;
+    typed_data: Record<string, unknown>;
+    metadata?: unknown;
+}
+interface Eip191Or712SignResponse {
+    signature: string;
+    [key: string]: unknown;
+}
+interface MfaIdAndConf {
+    id: string;
+    confirmation: string;
+}
+interface ManyMfaReceipts {
+    orgId: string;
+    receipts: MfaIdAndConf[];
+}
+interface SingleMfaReceipt {
+    mfaId: string;
+    mfaOrgId: string;
+    mfaConf: string;
+}
+type MfaReceipts = ManyMfaReceipts | SingleMfaReceipt;
+interface MfaRequestInfo {
+    id: string;
+    org_id?: string;
+    receipt?: {
+        confirmation?: string;
+        [key: string]: unknown;
+    } | null;
+    request: {
+        path: string;
+        body?: unknown;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface AcceptedMfaSession {
+    token: string;
+    refresh_token: string;
+    expiration: number | null | undefined;
+    session_info: ClientSessionInfo;
+}
+interface AcceptedMfaRequired {
+    id?: string;
+    ids?: string[];
+    org_id: string;
+    session?: AcceptedMfaSession;
+}
+interface AcceptedResponse {
+    accepted?: {
+        MfaRequired?: AcceptedMfaRequired;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+type Response<U> = U | AcceptedResponse;
+type RequestFn<U> = (headers?: HeadersInit) => Promise<Response<U>>;
+declare class CubistApiClient {
+    #private;
+    constructor(sessionManager: SessionManager, sessionMeta: SessionMetadata, targetOrgId?: string);
+    get env(): EnvInterface;
+    get orgId(): string;
+    get sessionMeta(): SessionMetadata;
+    withOrg(orgId: string): CubistApiClient;
+    sessionKeysList(): Promise<KeyInfo[]>;
+    keyGetByMaterialId(keyType: string, materialId: string): Promise<KeyInfo>;
+    sessionRevoke(sessionId?: string): Promise<void>;
+    mfaGet(mfaId: string): Promise<MfaRequestInfo>;
+    mfaVoteCs(mfaId: string, mfaVote: MfaVote): Promise<MfaRequestInfo>;
+    signEvm(key: Key | string, req: EvmSignRequest, mfaReceipt?: MfaReceipts): Promise<CubeSignerResponse<EvmSignResponse>>;
+    signEip191(key: Key | string, req: Eip191SignRequest, mfaReceipt?: MfaReceipts): Promise<CubeSignerResponse<Eip191Or712SignResponse>>;
+    signEip712(key: Key | string, req: Eip712SignRequest, mfaReceipt?: MfaReceipts): Promise<CubeSignerResponse<Eip191Or712SignResponse>>;
+}
+declare class Key {
+    #private;
+    readonly id: string;
+    readonly materialId: string;
+    readonly publicKey: string;
+    cached: KeyInfo;
+    constructor(client: CubeSignerClient | CubistApiClient, data: KeyInfo);
+    signEvm(req: EvmSignRequest, mfaReceipt?: MfaReceipts): Promise<CubeSignerResponse<EvmSignResponse>>;
+    signEip191(req: Eip191SignRequest, mfaReceipt?: MfaReceipts): Promise<CubeSignerResponse<Eip191Or712SignResponse>>;
+    signEip712(req: Eip712SignRequest, mfaReceipt?: MfaReceipts): Promise<CubeSignerResponse<Eip191Or712SignResponse>>;
+}
+declare class MfaRequest {
+    #private;
+    constructor(apiClient: CubistApiClient, data: string | MfaRequestInfo);
+    get id(): string;
+    fetch(): Promise<MfaRequestInfo>;
+    receipt(): Promise<SingleMfaReceipt | undefined>;
+    approve(): Promise<MfaRequest>;
+}
+declare class OrgClient {
+    #private;
+    constructor(apiClient: CubistApiClient);
+    get id(): string;
+    getMfaRequest(mfaId: string): MfaRequest;
+}
+declare class CubeSignerResponse<U> {
+    #private;
+    protected constructor(env: EnvInterface, requestFn: RequestFn<U>, resp: Response<U>);
+    static create<U>(env: EnvInterface, requestFn: RequestFn<U>, mfaReceipt?: MfaReceipts): Promise<CubeSignerResponse<U>>;
+    mfaId(): string | undefined;
+    mfaIds(): string[];
+    requiresMfa(): boolean;
+    mfaClient(): Promise<CubeSignerClient | undefined>;
+    data(): U;
+    approve(client: CubeSignerClient): Promise<CubeSignerResponse<U>>;
+    execWithMfaApproval(mfaReceipt: MfaReceipts): Promise<CubeSignerResponse<U>>;
+}
+declare class CubeSignerClient {
+    #private;
+    constructor(apiClient: CubistApiClient);
+    get apiClient(): CubistApiClient;
+    get env(): EnvInterface;
+    get orgId(): string;
+    static create(session: string | SessionData | SessionManager, targetOrgId?: string): Promise<CubeSignerClient>;
+    static createOidcSession(env: EnvInterface, orgId: string, token: string, scopes: Array<Scope>, lifetimes?: RatchetConfig, mfaReceipt?: MfaReceipts, purpose?: string): Promise<CubeSignerResponse<SessionData>>;
+    static proveOidcIdentity(env: EnvInterface, orgId: string, token: string): Promise<IdentityProof>;
+    org(): OrgClient;
+    getOrg(orgId: string): OrgClient;
+    sessionKeys(): Promise<Key[]>;
+    getKeyByMaterialId(keyType: string, materialId: string): Promise<Key>;
+    revokeSession(): Promise<void>;
+}
+
+/**
+ * Hook for OIDC login when user does not yet exist in CubeSigner.
+ * Before creating a session, we call CubeSigner SDK's proof (proveOidcIdentity) to check
+ * if the user exists. If proof fails (e.g. user not registered), this is invoked so the
+ * caller can register the user on their backend; then login proceeds.
+ */
+interface OidcLoginHooks {
+    /**
+     * Register the user on your backend when CubeSigner proof indicates the user does not exist.
+     * Called with the same OIDC token; after this resolves, OIDC session creation continues.
+     */
+    registerUser(oidcToken: string): Promise<void>;
+}
+interface CubeSignerConfig {
+    /** CubeSigner environment name or custom env object. */
+    env: Environment | EnvInterface;
+    /** Organization ID. */
+    orgId: string;
+    /** Session scopes (default: `["sign:*", "manage:*"]`). */
+    scopes?: string[];
+    /** Optional capability policy applied to smart-wallet sessions created from this auth flow. */
+    defaultSessionPolicy?: Partial<SessionCapabilityPolicy>;
+    /**
+     * Optional OIDC login hook. When provided, OIDC login will call CubeSigner SDK's
+     * proveOidcIdentity first; if the user does not exist (proof fails), registerUser is
+     * called, then login proceeds. If omitted, login uses the OIDC token directly.
+     */
+    oidcLoginHooks?: OidcLoginHooks;
+}
+interface CubeSignerSession {
+    /** Authenticated CubeSigner client — use it for signing, key management, etc. */
+    client: CubeSignerClient;
+    /** Raw session data (can be persisted / refreshed). */
+    sessionData: SessionData;
+}
+interface TwitterCodeExchangeParams {
+    /** Authorization code from Twitter OAuth 2.0 PKCE flow. */
+    code: string;
+    /** PKCE code_verifier that was generated for the auth request. */
+    codeVerifier: string;
+    /** redirect_uri that was used in the authorization request. */
+    redirectUri: string;
+}
+declare class CubeSignerAuth {
+    private readonly env;
+    private readonly orgId;
+    private readonly scopes;
+    readonly defaultSessionPolicy?: Partial<SessionCapabilityPolicy>;
+    private readonly oidcLoginHooks?;
+    private _client;
+    private _sessionData;
+    constructor(config: CubeSignerConfig);
+    /** Currently authenticated client (null if not logged in). */
+    get client(): CubeSignerClient | null;
+    get currentSession(): CubeSignerSession | null;
+    /**
+     * Login with a Google ID token (JWT).
+     * The token is used directly as the OIDC credential.
+     */
+    loginWithGoogle(idToken: string): Promise<CubeSignerSession>;
+    /**
+     * Login with a generic OIDC ID token.
+     * Useful when the caller already finished the upstream provider flow.
+     */
+    loginWithOidcToken(idToken: string): Promise<CubeSignerSession>;
+    /**
+     * Login with a Twitter OAuth 2.0 authorization code.
+     *
+     * 1. Exchange the code for an OIDC `id_token` via CubeSigner's
+     *    `/v0/org/{org_id}/oauth2/twitter` endpoint.
+     * 2. Create a CubeSigner session with that token.
+     */
+    loginWithTwitter(params: TwitterCodeExchangeParams): Promise<CubeSignerSession>;
+    signOut(): Promise<void>;
+    /**
+     * Restore a CubeSigner session from previously persisted SessionData.
+     * Useful for reconnecting after page reload without re-authentication.
+     */
+    restoreSession(sessionData: SessionData): Promise<CubeSignerSession>;
+    private authenticateWithOidcToken;
+    /**
+     * Exchange a Twitter authorization code for an OIDC id_token
+     * via CubeSigner's dedicated endpoint.
+     *
+     * `POST {SignerApiRoot}/v0/org/{org_id}/oauth2/twitter`
+     */
+    private exchangeTwitterCode;
+    /**
+     * Create a CubeSigner OIDC session from a generic OIDC id_token.
+     */
+    private createOidcSession;
+}
+
+export { getSupportedChainFromEvmChainId as A, type BalanceInfo as B, CubeSignerAuth as C, isCapabilityPolicyExpired as D, type EvmTransactionRequest as E, isSessionExpired as F, sessionSupportsCapability as G, type OidcLoginHooks as O, type ProviderCategory as P, type SessionCapabilityCheck as S, type TwitterCodeExchangeParams as T, type WalletState as W, type CubeSignerConfig as a, type CubeSignerSession as b, type WalletSession as c, type WalletAdapter as d, type WalletConnectArgs as e, type WalletCapability as f, type WalletProviderRequest as g, type SupportedChain as h, type WalletProvider as i, type ChainContext as j, type SessionCapabilityPolicy as k, type ChainDescriptor as l, type ChainNamespace as m, type ChainRpcFamily as n, type EvmAccessListItem as o, type EvmQuantity as p, SessionCapabilityError as q, type SupportedToken as r, type WalletAuthSource as s, type WalletType as t, assertSessionCapability as u, createChainContext as v, createSessionCapabilityPolicy as w, describeSessionCapabilityPolicy as x, getAllChainDescriptors as y, getChainDescriptor as z };