arlinkauth 0.1.0

package/README.md

@@ -0,0 +1,131 @@
+# arlinkauth
+
+Authentication SDK for Arweave apps. Sign in with GitHub or Google, get an Arweave wallet automatically.
+
+## Installation
+
+```bash
+npm install arlinkauth
+# or
+bun add arlinkauth
+```
+
+## Quick Start
+
+```typescript
+import { createArlinkAuthClient } from 'arlinkauth';
+
+const auth = createArlinkAuthClient({
+  apiUrl: 'https://your-worker.workers.dev'
+});
+
+// Initialize (checks for existing session)
+await auth.init();
+
+// Login with GitHub (opens popup)
+await auth.login();
+// or
+await auth.loginWithGoogle();
+
+// Get current user
+const user = auth.getState().user;
+console.log(user.arweave_address);
+
+// Sign and upload data to Arweave
+const result = await auth.dispatch({
+  data: 'Hello Arweave',
+  tags: [{ name: 'Content-Type', value: 'text/plain' }]
+});
+console.log(result.id); // Transaction ID
+
+// Logout
+auth.logout();
+```
+
+## React Integration
+
+```tsx
+import { AuthProvider, useAuth } from 'arlinkauth/react';
+
+function App() {
+  return (
+    <AuthProvider apiUrl="https://your-worker.workers.dev">
+      <YourApp />
+    </AuthProvider>
+  );
+}
+
+function YourApp() {
+  const { user, login, loginWithGoogle, logout, client } = useAuth();
+
+  if (!user) {
+    return (
+      <div>
+        <button onClick={login}>Sign in with GitHub</button>
+        <button onClick={loginWithGoogle}>Sign in with Google</button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      <p>Welcome, {user.name}</p>
+      <p>Arweave address: {user.arweave_address}</p>
+      <button onClick={logout}>Sign out</button>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### Client Methods
+
+| Method | Description |
+|--------|-------------|
+| `init()` | Initialize client, check for existing session |
+| `login()` | Login with GitHub (default) |
+| `loginWithGithub()` | Login with GitHub |
+| `loginWithGoogle()` | Login with Google |
+| `logout()` | Clear session |
+| `getState()` | Get current auth state |
+| `getToken()` | Get JWT token |
+| `isAuthenticated()` | Check if user is logged in |
+| `onAuthChange(callback)` | Subscribe to auth state changes |
+
+### Wallet Methods
+
+| Method | Description |
+|--------|-------------|
+| `sign(input)` | Sign an Arweave L1 transaction |
+| `signDataItem(input)` | Sign an ANS-104 data item |
+| `signature(input)` | Create raw signature of data |
+| `dispatch(input)` | Sign and upload to Arweave via bundler |
+
+### Types
+
+```typescript
+type ArlinkUser = {
+  id: string;
+  email: string | null;
+  name: string | null;
+  avatar_url: string | null;
+  github_id: number | null;
+  github_username: string | null;
+  google_id: string | null;
+  arweave_address: string | null;
+  created_at: string;
+  updated_at: string;
+};
+
+type AuthState = {
+  user: ArlinkUser | null;
+  token: string | null;
+  isLoading: boolean;
+  isAuthenticated: boolean;
+};
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import { type WauthClientOptions, type WauthUser, type AuthState, type AuthChangeListener, type OAuthProvider, type SignTransactionInput, type SignTransactionResult, type SignDataItemInput, type SignDataItemResult, type SignatureInput, type SignatureResult, type DispatchInput, type DispatchResult } from "./types.js";
+export declare function createWauthClient(options: WauthClientOptions): {
+    init: () => Promise<AuthState>;
+    login: () => Promise<boolean>;
+    loginWithGithub: () => Promise<boolean>;
+    loginWithGoogle: () => Promise<boolean>;
+    loginWithProvider: (provider: OAuthProvider) => Promise<boolean>;
+    logout: () => void;
+    handleCallback: () => boolean;
+    isAuthenticated: () => boolean;
+    getToken: () => string | null;
+    getState: () => AuthState;
+    onAuthChange: (listener: AuthChangeListener) => () => void;
+    api: {
+        getMe: () => Promise<WauthUser>;
+    };
+    sign: (input: SignTransactionInput) => Promise<SignTransactionResult>;
+    signDataItem: (input: SignDataItemInput) => Promise<SignDataItemResult>;
+    signature: (input: SignatureInput) => Promise<SignatureResult>;
+    dispatch: (input: DispatchInput) => Promise<DispatchResult>;
+};
+export type WauthClient = ReturnType<typeof createWauthClient>;

package/dist/client.js

@@ -0,0 +1,305 @@
+import { WalletAction, } from "./types.js";
+const DEFAULT_TOKEN_KEY = "arlinkauth_token";
+export function createWauthClient(options) {
+    const { apiUrl } = options;
+    const tokenKey = options.tokenKey ?? DEFAULT_TOKEN_KEY;
+    const listeners = new Set();
+    let state = {
+        user: null,
+        token: getStoredToken(),
+        isLoading: false,
+        isAuthenticated: false,
+    };
+    // ── Token Storage ───────────────────────────────────
+    function getStoredToken() {
+        try {
+            return localStorage.getItem(tokenKey);
+        }
+        catch {
+            return null;
+        }
+    }
+    function setStoredToken(token) {
+        try {
+            localStorage.setItem(tokenKey, token);
+        }
+        catch {
+            // SSR or storage unavailable
+        }
+    }
+    function removeStoredToken() {
+        try {
+            localStorage.removeItem(tokenKey);
+        }
+        catch {
+            // SSR or storage unavailable
+        }
+    }
+    // ── State Management ────────────────────────────────
+    function setState(partial) {
+        state = { ...state, ...partial };
+        for (const listener of listeners) {
+            listener(state);
+        }
+    }
+    function getState() {
+        return state;
+    }
+    function onAuthChange(listener) {
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+        };
+    }
+    // ── Authenticated Fetch ─────────────────────────────
+    async function fetchApi(path, init) {
+        const token = state.token;
+        if (!token) {
+            throw new Error("Not authenticated");
+        }
+        const res = await fetch(`${apiUrl}${path}`, {
+            ...init,
+            headers: {
+                ...init?.headers,
+                Authorization: `Bearer ${token}`,
+            },
+        });
+        if (res.status === 401) {
+            // Token is invalid/expired — clear it
+            removeStoredToken();
+            setState({ token: null, user: null, isAuthenticated: false });
+            throw new Error("Session expired");
+        }
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({}));
+            throw new Error(body.error ?? `API error: ${res.status}`);
+        }
+        return res.json();
+    }
+    // ── Auth Actions ────────────────────────────────────
+    /** Open a popup for OAuth login with the specified provider */
+    function loginWithProvider(provider) {
+        return new Promise((resolve) => {
+            const loginUrl = `${apiUrl}/auth/${provider}`;
+            const width = 500;
+            const height = 700;
+            const left = window.screenX + (window.outerWidth - width) / 2;
+            const top = window.screenY + (window.outerHeight - height) / 2;
+            const popup = window.open(loginUrl, "wauth-login", `width=${width},height=${height},left=${left},top=${top},popup=1`);
+            if (!popup) {
+                console.error("[arlinkauth] Failed to open popup - check popup blocker");
+                resolve(false);
+                return;
+            }
+            // Listen for message from popup
+            const handleMessage = async (event) => {
+                // Strict origin validation
+                if (event.origin !== new URL(apiUrl).origin)
+                    return;
+                // Strict message structure validation
+                if (typeof event.data !== "object" || event.data === null)
+                    return;
+                if (event.data.type !== "arlinkauth:callback")
+                    return;
+                if (typeof event.data.token !== "string" || event.data.token.length === 0)
+                    return;
+                // Basic JWT structure validation (header.payload.signature)
+                const tokenParts = event.data.token.split(".");
+                if (tokenParts.length !== 3)
+                    return;
+                window.removeEventListener("message", handleMessage);
+                popup.close();
+                // Store token and fetch user
+                setStoredToken(event.data.token);
+                setState({ token: event.data.token, isLoading: true, isAuthenticated: true });
+                try {
+                    const user = await api.getMe();
+                    setState({ user, isLoading: false, isAuthenticated: true });
+                    resolve(true);
+                }
+                catch {
+                    removeStoredToken();
+                    setState({ token: null, user: null, isLoading: false, isAuthenticated: false });
+                    resolve(false);
+                }
+            };
+            window.addEventListener("message", handleMessage);
+            // Clean up if popup is closed without completing auth
+            const checkClosed = setInterval(() => {
+                if (popup.closed) {
+                    clearInterval(checkClosed);
+                    window.removeEventListener("message", handleMessage);
+                    resolve(false);
+                }
+            }, 500);
+        });
+    }
+    /** Open a popup for GitHub OAuth login (no page refresh) */
+    function login() {
+        return loginWithProvider("github");
+    }
+    /** Open a popup for GitHub OAuth login */
+    function loginWithGithub() {
+        return loginWithProvider("github");
+    }
+    /** Open a popup for Google OAuth login */
+    function loginWithGoogle() {
+        return loginWithProvider("google");
+    }
+    /**
+     * Check for existing token in localStorage.
+     * (URL-based callback is no longer used - popup flow uses postMessage)
+     */
+    function handleCallback() {
+        const existing = getStoredToken();
+        if (existing) {
+            setState({ token: existing, isAuthenticated: true });
+            return true;
+        }
+        return false;
+    }
+    /** Clear the token and user state */
+    function logout() {
+        removeStoredToken();
+        setState({ token: null, user: null, isAuthenticated: false });
+    }
+    function isAuthenticated() {
+        return state.isAuthenticated;
+    }
+    function getToken() {
+        return state.token;
+    }
+    // ── API Methods ─────────────────────────────────────
+    const api = {
+        getMe: () => fetchApi("/api/me"),
+    };
+    // ── Wallet Signing Methods ─────────────────────────────
+    /**
+     * Sign an Arweave transaction.
+     * The transaction must be created using arweave-js and passed as the raw object.
+     */
+    async function sign(input) {
+        return fetchApi("/api/wallet/action", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                action: WalletAction.SIGN,
+                payload: { transaction: input.transaction },
+            }),
+        });
+    }
+    /**
+     * Sign an ANS-104 data item (for AO/bundled transactions).
+     * Returns the signed data item ID and raw bytes.
+     */
+    async function signDataItem(input) {
+        // Convert Uint8Array to array for JSON serialization
+        const data = input.data instanceof Uint8Array
+            ? Array.from(input.data)
+            : input.data;
+        return fetchApi("/api/wallet/action", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                action: WalletAction.SIGN_DATA_ITEM,
+                payload: {
+                    dataItem: {
+                        data,
+                        tags: input.tags,
+                        target: input.target,
+                        anchor: input.anchor,
+                    },
+                },
+            }),
+        });
+    }
+    /**
+     * Create a raw signature of arbitrary data.
+     * Returns the raw signature bytes.
+     */
+    async function signature(input) {
+        // Convert Uint8Array to array for JSON serialization
+        const data = input.data instanceof Uint8Array
+            ? Array.from(input.data)
+            : input.data;
+        return fetchApi("/api/wallet/action", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                action: WalletAction.SIGNATURE,
+                payload: { data },
+            }),
+        });
+    }
+    /**
+     * Sign and dispatch a data item to Arweave via a bundler (Turbo/Irys).
+     * Returns the transaction ID and bundler response.
+     */
+    async function dispatch(input) {
+        // Convert Uint8Array to array for JSON serialization
+        const data = input.data instanceof Uint8Array
+            ? Array.from(input.data)
+            : input.data;
+        return fetchApi("/api/wallet/action", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                action: WalletAction.DISPATCH,
+                payload: {
+                    data,
+                    tags: input.tags,
+                    target: input.target,
+                    anchor: input.anchor,
+                    bundler: input.bundler,
+                },
+            }),
+        });
+    }
+    // ── Initialize ──────────────────────────────────────
+    /**
+     * Initialize the client: check for existing session token
+     * and validate it by fetching /api/me.
+     */
+    async function init() {
+        handleCallback();
+        if (!state.token) {
+            setState({ isLoading: false, isAuthenticated: false });
+            return getState();
+        }
+        setState({ isLoading: true });
+        try {
+            const user = await api.getMe();
+            setState({ user, isLoading: false, isAuthenticated: true });
+        }
+        catch {
+            // Token invalid — clear everything
+            removeStoredToken();
+            setState({
+                token: null,
+                user: null,
+                isLoading: false,
+                isAuthenticated: false,
+            });
+        }
+        return getState();
+    }
+    return {
+        init,
+        login,
+        loginWithGithub,
+        loginWithGoogle,
+        loginWithProvider,
+        logout,
+        handleCallback,
+        isAuthenticated,
+        getToken,
+        getState,
+        onAuthChange,
+        api,
+        // Wallet signing methods
+        sign,
+        signDataItem,
+        signature,
+        dispatch,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createWauthClient, createWauthClient as createArlinkAuthClient } from "./client.js";
+export type { WauthClient, WauthClient as ArlinkAuthClient } from "./client.js";
+export { WalletAction, type WauthUser, type WauthUser as ArlinkUser, type WauthClientOptions, type WauthClientOptions as ArlinkAuthClientOptions, type AuthState, type AuthChangeListener, type OAuthProvider, type ArweaveTag, type SignTransactionInput, type SignTransactionResult, type SignDataItemInput, type SignDataItemResult, type SignatureInput, type SignatureResult, type BundlerType, type DispatchInput, type DispatchResult, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createWauthClient, createWauthClient as createArlinkAuthClient } from "./client.js";
+export { WalletAction, } from "./types.js";

package/dist/react.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+import { type WauthClient } from "./client.js";
+import type { AuthState, WauthClientOptions, WauthUser } from "./types.js";
+type AuthContextValue = {
+    user: WauthUser | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+    login: () => void;
+    loginWithGithub: () => void;
+    loginWithGoogle: () => void;
+    logout: () => void;
+    getToken: () => string | null;
+    client: WauthClient;
+    api: WauthClient["api"];
+};
+type AuthProviderProps = WauthClientOptions & {
+    children: ReactNode;
+};
+export declare function AuthProvider({ children, ...options }: AuthProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useAuth(): AuthContextValue;
+export type { WauthUser, AuthState, WauthClientOptions };
+export type { OAuthProvider, ArweaveTag, SignTransactionInput, SignTransactionResult, SignDataItemInput, SignDataItemResult, SignatureInput, SignatureResult, BundlerType, DispatchInput, DispatchResult, } from "./types.js";
+export { WalletAction } from "./types.js";

package/dist/react.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useState, useMemo, } from "react";
+import { createWauthClient } from "./client.js";
+const AuthContext = createContext(null);
+export function AuthProvider({ children, ...options }) {
+    const client = useMemo(() => createWauthClient(options), [options.apiUrl, options.tokenKey]);
+    const [authState, setAuthState] = useState(client.getState);
+    useEffect(() => {
+        // Subscribe to state changes
+        const unsubscribe = client.onAuthChange(setAuthState);
+        // Initialize: handle callback token + validate session
+        client.init();
+        return unsubscribe;
+    }, [client]);
+    const value = useMemo(() => ({
+        user: authState.user,
+        isLoading: authState.isLoading,
+        isAuthenticated: authState.isAuthenticated,
+        login: client.login,
+        loginWithGithub: client.loginWithGithub,
+        loginWithGoogle: client.loginWithGoogle,
+        logout: client.logout,
+        getToken: client.getToken,
+        client,
+        api: client.api,
+    }), [authState, client]);
+    return _jsx(AuthContext.Provider, { value: value, children: children });
+}
+// ── Hook ──────────────────────────────────────────────
+export function useAuth() {
+    const ctx = useContext(AuthContext);
+    if (!ctx) {
+        throw new Error("useAuth must be used within an <AuthProvider>");
+    }
+    return ctx;
+}
+export { WalletAction } from "./types.js";

package/dist/types.d.ts

@@ -0,0 +1,95 @@
+export type WauthUser = {
+    id: string;
+    email: string | null;
+    name: string | null;
+    avatar_url: string | null;
+    github_id: number | null;
+    github_username: string | null;
+    google_id: string | null;
+    arweave_address: string | null;
+    created_at: string;
+    updated_at: string;
+};
+export type OAuthProvider = "github" | "google";
+export declare enum WalletAction {
+    SIGN = "sign",
+    SIGN_DATA_ITEM = "signDataItem",
+    SIGNATURE = "signature",
+    DISPATCH = "dispatch"
+}
+/** Tag for Arweave transactions/data items */
+export type ArweaveTag = {
+    name: string;
+    value: string;
+};
+/** Input for signing an Arweave transaction */
+export type SignTransactionInput = {
+    /** Raw transaction object from arweave-js */
+    transaction: unknown;
+};
+/** Result of signing a transaction */
+export type SignTransactionResult = {
+    /** Signed transaction JSON */
+    [key: string]: unknown;
+};
+/** Input for signing an ANS-104 data item */
+export type SignDataItemInput = {
+    data: string | Uint8Array | number[];
+    tags?: ArweaveTag[];
+    target?: string;
+    anchor?: string;
+};
+/** Result of signing a data item */
+export type SignDataItemResult = {
+    /** Data item ID (transaction ID) */
+    id: string;
+    /** Raw signed data item bytes */
+    raw: number[];
+};
+/** Input for raw signature */
+export type SignatureInput = {
+    /** Data to sign - can be string, Uint8Array, or array of numbers */
+    data: string | Uint8Array | number[];
+};
+/** Result of raw signature */
+export type SignatureResult = {
+    /** Raw signature bytes */
+    signature: number[];
+};
+/** Bundler types for dispatching data items */
+export type BundlerType = "turbo" | "irys";
+/** Input for dispatching a data item to Arweave via bundler */
+export type DispatchInput = {
+    /** Data to upload - can be string or array of bytes */
+    data: string | Uint8Array | number[];
+    /** Optional tags for the data item */
+    tags?: ArweaveTag[];
+    /** Optional target address */
+    target?: string;
+    /** Optional anchor */
+    anchor?: string;
+    /** Which bundler to use (default: "turbo") */
+    bundler?: BundlerType;
+};
+/** Result of dispatching a data item */
+export type DispatchResult = {
+    /** Transaction/data item ID */
+    id: string;
+    /** Which bundler was used */
+    bundler: BundlerType;
+    /** Response from the bundler */
+    response: Record<string, unknown>;
+};
+export type WauthClientOptions = {
+    /** Base URL of the wauth worker (e.g. "https://wauth.example.workers.dev") */
+    apiUrl: string;
+    /** localStorage key for the JWT. Default: "wauth_token" */
+    tokenKey?: string;
+};
+export type AuthState = {
+    user: WauthUser | null;
+    token: string | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+};
+export type AuthChangeListener = (state: AuthState) => void;

package/dist/types.js

@@ -0,0 +1,9 @@
+// ── API Response Types ──────────────────────────────────
+// ── Wallet Action Types ──────────────────────────────────
+export var WalletAction;
+(function (WalletAction) {
+    WalletAction["SIGN"] = "sign";
+    WalletAction["SIGN_DATA_ITEM"] = "signDataItem";
+    WalletAction["SIGNATURE"] = "signature";
+    WalletAction["DISPATCH"] = "dispatch";
+})(WalletAction || (WalletAction = {}));

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "arlinkauth",
+  "version": "0.1.0",
+  "description": "Authentication SDK for Arweave apps - OAuth login with automatic wallet generation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "arweave",
+    "auth",
+    "oauth",
+    "wallet",
+    "ao",
+    "arlink"
+  ],
+  "author": "Ankush Singh",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ankushKun/arlinkauth.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ankushKun/arlinkauth/issues"
+  },
+  "homepage": "https://github.com/ankushKun/arlinkauth#readme",
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "typescript": "^5"
+  }
+}