{"_id":"0xgas-auth","name":"0xgas-auth","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"0xgas-auth","version":"1.0.0","description":"Secure embedded wallet SDK for EVM chains — AWS KMS-backed signing via iframe widget","author":{"name":"0xGas","email":"hello@0xgas.dev"},"license":"MIT","homepage":"https://docs.0xgas.dev","repository":{"type":"git","url":"git+https://github.com/0xgasless/0xgas-auth.git"},"keywords":["ethereum","wallet","evm","kms","erc4337","smart-account","gasless","web3","signing","embedded-wallet"],"type":"module","sideEffects":false,"main":"./dist/cjs/index.js","module":"./dist/esm/index.js","types":"./dist/esm/index.d.ts","exports":{".":{"import":{"types":"./dist/esm/index.d.ts","default":"./dist/esm/index.js"},"require":{"types":"./dist/cjs/index.d.ts","default":"./dist/cjs/index.js"}}},"engines":{"node":">=16.0.0"},"scripts":{"clean":"rm -rf dist","build:esm":"tsc -p tsconfig.esm.json","build:cjs":"tsc -p tsconfig.cjs.json","build":"npm run clean && npm run build:esm && npm run build:cjs","prepublishOnly":"npm run build"},"peerDependencies":{"viem":">=1.0.0"},"peerDependenciesMeta":{"viem":{"optional":true}},"devDependencies":{"typescript":"^5.0.0","viem":"^2.0.0"},"_id":"0xgas-auth@1.0.0","bugs":{"url":"https://github.com/0xgasless/0xgas-auth/issues"},"_nodeVersion":"22.21.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-m0SNpNHeK/v8AISB7Y+Mszu7TTod7aeLfyTr+ixtu8lh9zAbSnr8aZuTgGWtnG1Ywd9n0fqYyli1I+T8a+jamg==","shasum":"79c8bccf9f88f2d81782e80e32491e0ac5a042d1","tarball":"https://registry.npmjs.org/0xgas-auth/-/0xgas-auth-1.0.0.tgz","fileCount":60,"unpackedSize":110872,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDXGF4kwnbFTfiwIOKOv+Z7CGF2f0nHYQ0UwdUXwa17zwIhAKjA/lFpGdISvRzlYR/1lg44Kv0F1+bd8wFe+KxdesWE"}]},"_npmUser":{"name":"achiit","email":"achihsingh@gmail.com"},"directories":{},"maintainers":[{"name":"achiit","email":"achihsingh@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/0xgas-auth_1.0.0_1772713333523_0.04189344105367643"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-05T12:22:13.522Z","1.0.0":"2026-03-05T12:22:13.747Z","modified":"2026-03-05T12:22:13.946Z"},"maintainers":[{"name":"achiit","email":"achihsingh@gmail.com"}],"description":"Secure embedded wallet SDK for EVM chains — AWS KMS-backed signing via iframe widget","homepage":"https://docs.0xgas.dev","keywords":["ethereum","wallet","evm","kms","erc4337","smart-account","gasless","web3","signing","embedded-wallet"],"repository":{"type":"git","url":"git+https://github.com/0xgasless/0xgas-auth.git"},"author":{"name":"0xGas","email":"hello@0xgas.dev"},"bugs":{"url":"https://github.com/0xgasless/0xgas-auth/issues"},"license":"MIT","readme":"# 0xgas-auth\n\n> Secure embedded wallet SDK for EVM chains — AWS KMS-backed signing via iframe widget.\n\n[![npm version](https://img.shields.io/npm/v/0xgas-auth)](https://www.npmjs.com/package/0xgas-auth)\n[![license](https://img.shields.io/npm/l/0xgas-auth)](./LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)\n\n`0xgas-auth` provides non-custodial, KMS-backed wallets through a secure iframe. Private keys and access tokens **never leave the iframe** — your application only receives addresses, emails, and signatures.\n\n---\n\n## Installation\n\n```bash\nnpm install 0xgas-auth\n# or\nyarn add 0xgas-auth\n# or\npnpm add 0xgas-auth\n```\n\n## Quick Start\n\n```ts\nimport { OxGasAuth } from '0xgas-auth';\n\nconst auth = new OxGasAuth({\n  apiKey: 'your-api-key',\n  chainId: 11155111, // Sepolia — auto-resolves to \"Sepolia\" in the widget\n  debug: true,       // Enable console logging during development\n});\n\n// Listen for events\nauth.on('connected', (wallet) => {\n  console.log('Connected:', wallet.address, wallet.email);\n});\n\n// Authenticate\nconst wallet = await auth.login();\nconsole.log('EOA Address:', wallet.address);\n\n// Sign a message hash (e.g. ERC-4337 UserOp hash)\nconst { signature } = await auth.signMessage('0xdeadbeef...');\n\n// Sign a transaction\nconst result = await auth.signTransaction({\n  to: '0x...',\n  value: '0',\n  data: '0x...',\n  chainId: 11155111,\n});\n```\n\n## Configuration\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `apiKey` | `string` | **(required)** | Your 0xgas API key |\n| `widgetUrl` | `string` | `https://d1p4m...cloudfront.net` | Override widget URL (self-hosted / local dev) |\n| `network` | `string` | `\"Ethereum\"` | Network name shown in approval screen |\n| `chainId` | `number` | — | Auto-resolves network name (40+ chains built-in) |\n| `zIndex` | `number` | `99999` | z-index of the widget overlay |\n| `loginTimeout` | `number` | `300000` (5 min) | Login timeout in ms |\n| `signTimeout` | `number` | `120000` (2 min) | Signing timeout in ms |\n| `debug` | `boolean` | `false` | Enable verbose console logging |\n\nYou can also use the shorthand string constructor:\n\n```ts\nconst auth = new OxGasAuth('your-api-key');\n```\n\n## API Reference\n\n### `login(): Promise<WalletInfo>`\n\nOpens the widget for email/password authentication. Returns wallet info with the KMS EOA address and email. Resolves immediately if already logged in.\n\n### `signMessage(message, network?): Promise<SignMessageResult>`\n\nSigns a message hash via the KMS widget. Accepts hex strings or `Uint8Array`. Used for ERC-4337 UserOperation signing.\n\n### `signTransaction(txParams): Promise<SignTxResult>`\n\nSigns a raw transaction via the KMS widget. Opens the \"Approve Transaction\" screen.\n\n### `getAddress(): \\`0x${string}\\``\n\nReturns the EOA address. Throws `NotConnectedError` if not logged in.\n\n### `getWalletInfo(): WalletInfo | null`\n\nReturns full wallet info or `null`.\n\n### `isConnected(): boolean`\n\nReturns whether the user is currently authenticated.\n\n### `getAuthState(): AuthState`\n\nReturns `\"disconnected\"`, `\"connecting\"`, or `\"connected\"`.\n\n### `logout(): Promise<void>`\n\nClears the session and removes the iframe.\n\n### `destroy(): void`\n\nFull teardown — clears state, removes iframe, removes all event listeners. Call this when unmounting.\n\n## Events\n\n```ts\nauth.on('connected',         (wallet) => { /* WalletInfo */ });\nauth.on('disconnected',      ()       => { /* logged out */ });\nauth.on('signatureComplete', (data)   => { /* { type, result } */ });\nauth.on('error',             (err)    => { /* any error */ });\nauth.on('stateChange',       (state)  => { /* AuthState */ });\n\n// One-shot listener\nauth.once('connected', (wallet) => { ... });\n\n// Unsubscribe\nconst unsub = auth.on('error', handler);\nunsub();\n```\n\n## Error Handling\n\nAll errors extend `OxGasError` and include a programmatic `code`:\n\n```ts\nimport {\n  OxGasError,\n  NotConnectedError,\n  SigningRejectedError,\n  SigningTimeoutError,\n  WidgetError,\n} from '0xgas-auth';\n\ntry {\n  await auth.signMessage(hash);\n} catch (err) {\n  if (err instanceof SigningRejectedError) {\n    console.log('User rejected');          // err.code === 'SIGNING_REJECTED'\n  } else if (err instanceof SigningTimeoutError) {\n    console.log('Timed out:', err.timeoutMs); // err.code === 'TIMEOUT'\n  } else if (err instanceof NotConnectedError) {\n    console.log('Not logged in');          // err.code === 'NOT_CONNECTED'\n  }\n}\n```\n\n## ERC-4337 Smart Account Integration\n\n`0xgas-auth` is designed to work with [`@0xgasless/smart-account`](https://www.npmjs.com/package/@0xgasless/smart-account) for gasless transactions:\n\n```ts\nimport { OxGasAuth } from '0xgas-auth';\nimport { createSmartAccountClient, PaymasterMode } from '@0xgasless/smart-account';\n\nconst auth = new OxGasAuth({\n  apiKey: 'your-key',\n  chainId: 11155111,\n});\n\nconst wallet = await auth.login();\n\nconst smartAccount = await createSmartAccountClient({\n  signer: auth,\n  paymasterUrl: 'https://paymaster.0xgasless.com/v1/11155111/rpc/your-api-key',\n  bundlerUrl: 'https://bundler.0xgasless.com/11155111',\n  chainId: 11155111,\n});\n\nconst { hash } = await smartAccount.sendTransaction(tx, {\n  paymasterServiceData: { mode: PaymasterMode.SPONSORED },\n});\n```\n\n## Supported Networks\n\nThe SDK includes a built-in registry of 40+ EVM networks. Pass `chainId` and the widget automatically displays the correct network name:\n\n```\nEthereum (1), Optimism (10), BNB Chain (56), Polygon (137),\nBase (8453), Arbitrum (42161), Avalanche (43114), Fantom (250),\nSepolia (11155111), Linea (59144), Scroll (534352), ...\n```\n\nAdd custom networks via the `network` option:\n\n```ts\nconst auth = new OxGasAuth({ apiKey: 'key', network: 'My L2' });\n```\n\n## TypeScript\n\nFull TypeScript support with exported types:\n\n```ts\nimport type {\n  OxGasAuthConfig,\n  WalletInfo,\n  SignMessageResult,\n  SignTxResult,\n  AuthState,\n} from '0xgas-auth';\n```\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md","_rev":"1-6dab4b5ff4e1fb77443a6ae266d00d0d"}