TinyCloud uses Sign-In with Ethereum (SIWE) for authentication. Users prove wallet ownership to establish sessions that authorize access to their space.
How SIWE Works
Connect wallet
The user connects their Ethereum wallet (MetaMask, WalletConnect, etc.)
Sign message
The SDK constructs a SIWE message containing domain, address, and session parameters. The user signs this message with their wallet.
Session created
TinyCloud verifies the signature and creates a session. The session key can perform operations on behalf of the user until expiry.
Sign In
import { TinyCloudWeb } from '@tinycloudlabs/web-sdk';
const tc = new TinyCloudWeb({
host: 'https://api.tinycloud.xyz',
prefix: 'my-app',
});
// Triggers wallet popup for signature
await tc.signIn();
// Session is now active
console.log('Signed in as:', tc.userAuthorization.getSpaceId());
Session Persistence
Sessions can be persisted to survive page reloads (Web) or process restarts (Node).
const tc = new TinyCloudWeb({
host: 'https://api.tinycloud.xyz',
prefix: 'my-app',
sessionConfig: {
// 'localStorage' persists across tabs/sessions
// 'sessionStorage' clears when tab closes
// 'memory' clears on page reload
storageType: 'localStorage',
},
});
Resume Existing Session
Check for and resume a persisted session without requiring a new signature.
const tc = new TinyCloudWeb({
host: 'https://api.tinycloud.xyz',
prefix: 'my-app',
sessionConfig: { storageType: 'localStorage' },
});
// Try to resume existing session
const resumed = await tc.tryResumeSession();
if (resumed) {
console.log('Session resumed');
} else {
// No valid session, need fresh sign-in
await tc.signIn();
}
Node SDK Sign Strategies
The Node SDK supports different strategies for signing the SIWE message.
Auto-sign (default)
Callback
Event Emitter
Signs automatically using the provided private key.const tc = new TinyCloudNode({
privateKey: process.env.WALLET_PRIVATE_KEY,
// signStrategy defaults to 'auto'
});
await tc.signIn(); // Signs immediately
Provide a callback to handle signing, useful for custom signing flows.const tc = new TinyCloudNode({
privateKey: process.env.WALLET_PRIVATE_KEY,
signStrategy: 'callback',
onSignRequest: async (message) => {
console.log('Sign request received:', message);
// Custom logic here (e.g., user confirmation)
return true; // Return true to proceed with signing
},
});
await tc.signIn();
Use events for decoupled signing workflows.const tc = new TinyCloudNode({
privateKey: process.env.WALLET_PRIVATE_KEY,
signStrategy: 'event-emitter',
});
tc.on('signRequest', async (message, approve) => {
console.log('Sign request:', message);
// Perform any async checks
approve(); // Call to proceed
});
await tc.signIn();
Session Expiry
Sessions have a limited lifetime. Handle expiry gracefully.
const tc = new TinyCloudWeb({
host: 'https://api.tinycloud.xyz',
prefix: 'my-app',
sessionConfig: {
storageType: 'localStorage',
expirationTime: '24h', // Session duration
},
});
// Check if session is still valid
if (tc.isSessionExpired()) {
await tc.signIn(); // Re-authenticate
}
Sign Out
Clear the current session.
await tc.signOut();
// Session cleared from storage
After signing out, all operations will fail until a new signIn() is completed.
