@dotbots-boutique/auth-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DotBots.Boutique
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,299 @@
+# @dotbots-boutique/auth-sdk
+ 
+The official authentication and authorisation SDK for apps running on the [DotBots Boutique](https://dotbots.boutique) platform.
+ 
+## What is DotBots Boutique?
+ 
+[DotBots Boutique](https://dotbots.boutique) is a marketplace platform where vibe coders build and publish apps. The platform handles user management, authentication, authorisation, payments, and infrastructure, and offers a growing set of additional services — so you can focus on building your app.
+ 
+---
+ 
+## Installation
+ 
+```bash
+npm install @dotbots-boutique/auth-sdk
+```
+ 
+> **Note:** This package is for **browser use only**. Do not install it in a Deno or Node backend. A separate `@dotbots-boutique/server-sdk` for backend use is coming soon.
+ 
+---
+ 
+## Quick start
+ 
+### React
+ 
+```tsx
+// main.tsx
+import { DotBotsAuth } from '@dotbots-boutique/auth-sdk';
+import { DotBotsAuthProvider } from '@dotbots-boutique/auth-sdk/react';
+ 
+const auth = new DotBotsAuth({
+  appId: import.meta.env.VITE_DOTBOTS_APP_ID,
+  apiUrl: import.meta.env.VITE_DOTBOTS_API_URL
+});
+ 
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <DotBotsAuthProvider auth={auth}>
+    <App />
+  </DotBotsAuthProvider>
+);
+```
+ 
+```tsx
+// In any component
+import { useDotBotsAuth } from '@dotbots-boutique/auth-sdk/react';
+ 
+const MyComponent = () => {
+  const { user, can, hasRole, fetch, logout } = useDotBotsAuth();
+ 
+  return (
+    <div>
+      <p>Welcome, {user?.name}</p>
+      {can('customers.read') && <CustomerList />}
+      {hasRole('admin') && <AdminPanel />}
+      <button onClick={logout}>Log out</button>
+    </div>
+  );
+};
+```
+ 
+### Without React
+ 
+```typescript
+import { DotBotsAuth } from '@dotbots-boutique/auth-sdk';
+ 
+const auth = new DotBotsAuth({
+  appId: import.meta.env.VITE_DOTBOTS_APP_ID,
+  apiUrl: import.meta.env.VITE_DOTBOTS_API_URL
+});
+ 
+await auth.initialize();
+ 
+const user = await auth.getUser();
+console.log(user.name, user.roles);
+```
+ 
+---
+ 
+## How authentication works
+ 
+Your app can run in two modes — the SDK handles both automatically.
+ 
+**Inside an iframe** (embedded in the DotBots Boutique marketplace):
+1. The SDK sends a `DOTBOTS_READY` message to the marketplace
+2. The marketplace responds with a short-lived auth code
+3. The SDK exchanges the code for an access token and refresh token
+ 
+**Standalone** (opened directly on your app's domain):
+1. The SDK checks for a `?code=` parameter in the URL
+2. If absent, it redirects the user to the DotBots login page
+3. After login, the user is redirected back with a code that the SDK exchanges for tokens
+ 
+All tokens are stored in memory only — never in `localStorage`, `sessionStorage`, or cookies.
+ 
+---
+ 
+## Making API calls
+ 
+Always use `auth.fetch()` instead of the native `fetch()`. The SDK automatically:
+- Adds the `Authorization`, `X-App-Id` and `X-Environment` headers
+- Routes calls through the local proxy when available
+- Refreshes the access token when it is about to expire
+- Retries once on a `401` response
+ 
+```typescript
+// GET
+const response = await auth.fetch('/api/customers');
+const customers = await response.json();
+ 
+// POST
+const response = await auth.fetch('/api/customers', {
+  method: 'POST',
+  body: JSON.stringify({ name: 'Acme' })
+});
+```
+ 
+---
+ 
+## Checking permissions
+ 
+```typescript
+auth.can('customers.read')                           // true/false
+auth.canAll(['customers.read', 'customers.write'])   // true/false — all required
+auth.canAny(['customers.read', 'invoices.read'])     // true/false — at least one
+auth.hasRole('admin')                                // true/false
+```
+ 
+---
+ 
+## Events
+ 
+```typescript
+auth.on('tokenRefreshed', () => { });
+auth.on('sessionExpired', () => {
+  // Show a message to the user
+});
+auth.on('loggedOut', () => { });
+auth.on('userLoaded', (user) => { });
+```
+ 
+---
+ 
+## Error handling
+ 
+```typescript
+import { DotBotsAuthError } from '@dotbots-boutique/auth-sdk';
+ 
+try {
+  await auth.initialize();
+} catch (error) {
+  if (error instanceof DotBotsAuthError) {
+    switch (error.code) {
+      case 'IFRAME_TIMEOUT':
+        // Marketplace did not respond in time
+        break;
+      case 'UNAUTHORIZED':
+        // User has no access to this app
+        break;
+      case 'NETWORK_ERROR':
+        // API unreachable
+        break;
+      case 'CODE_EXPIRED':
+        // Auth code was already expired or invalid
+        break;
+    }
+  }
+}
+```
+ 
+### Error codes
+ 
+| Code | Description | Fatal |
+|------|-------------|-------|
+| `IFRAME_TIMEOUT` | Marketplace did not respond within the timeout | Yes |
+| `CODE_EXPIRED` | Auth code was already expired or invalid | Yes |
+| `UNAUTHORIZED` | User has no access to this app | Yes |
+| `REFRESH_FAILED` | Token refresh failed | Yes |
+| `NETWORK_ERROR` | API unreachable | Yes |
+| `NOT_INITIALIZED` | `initialize()` has not been called yet | Yes |
+| `PROXY_UNAVAILABLE` | Proxy config could not be fetched | No — falls back to direct API |
+ 
+---
+ 
+## Configuration
+ 
+```typescript
+interface DotBotsConfig {
+  appId: string;                     // Required — app ID assigned by the platform
+  apiUrl: string;                    // Required — always 'https://api.dotbots.ai'
+  marketplaceOrigin?: string;        // Default: 'https://dotbots.boutique'
+  tokenRefreshBuffer?: number;       // Default: 60000 (ms before expiry to refresh)
+  iframeTimeout?: number;            // Default: 5000 (ms to wait for auth code)
+  onTokenRefreshFailed?: () => void; // Called when token refresh fails
+}
+```
+ 
+---
+ 
+## DotBotsUser
+ 
+```typescript
+interface DotBotsUser {
+  id: string;
+  name: string | null;        // null if 'profile' scope not granted
+  email: string | null;       // null if 'email' scope not granted
+  orgId: string;
+  orgName: string | null;     // null if 'org' scope not granted
+  roles: string[];
+  permissions: string[];
+  avatarUrl: string | null;   // null if 'avatar' scope not granted
+}
+```
+ 
+Fields marked as `null` are not provided by the platform because the user has not granted the corresponding scope. Scopes are declared in your app's `dotbots.boutique.json` file.
+ 
+---
+ 
+## Backend integration
+ 
+If your app has a backend, forward the three headers from the frontend request to your backend, and from your backend to the proxy.
+ 
+```typescript
+// Deno backend example
+app.get('/api/customers', async (req) => {
+  const proxyUrl = Deno.env.get('DOTBOTS_PROXY_URL');
+ 
+  const response = await fetch(`${proxyUrl}/api/customers`, {
+    headers: {
+      'Authorization': req.headers.get('authorization') ?? '',
+      'X-App-Id': req.headers.get('x-app-id') ?? '',
+      'X-Environment': req.headers.get('x-environment') ?? '',
+    }
+  });
+ 
+  return response;
+});
+```
+ 
+**Never** store tokens in a database or log file, and never forward them to services outside the DotBots platform. The access token is scoped to your specific app — it cannot be used to access any other app's data.
+ 
+---
+ 
+## dotbots.boutique.json
+ 
+Your repository must contain a `dotbots.boutique.json` file. Use the `env` field to declare any environment variables your app needs beyond the platform defaults. The platform will ask the installer to fill these in before deployment.
+ 
+```json
+{
+  "dotbotsPromptVersion": "2.1.0",
+  "database": true,
+  "scopes": {
+    "profile": { "description": "Read the user's name", "access": "required" },
+    "email": { "description": "Read the user's email", "access": "optional" }
+  },
+  "roles": [
+    { "name": "admin", "description": "Full access" }
+  ],
+  "permissions": [
+    { "name": "customers.read", "description": "View customers" }
+  ],
+  "env": [
+    {
+      "name": "STRIPE_API_KEY",
+      "description": "Stripe API key for payment processing",
+      "required": true,
+      "secret": true
+    }
+  ]
+}
+```
+ 
+Platform variables (`DATABASE_URL`, `PORT`, `DOTBOTS_APP_ID`, `DOTBOTS_PROXY_URL`, `DOTBOTS_API_URL`) are injected automatically and do not need to be declared here.
+ 
+---
+ 
+## Security
+ 
+- Tokens are stored in memory only — never persisted
+- `postMessage` origin is always validated — only messages from `marketplaceOrigin` are accepted
+- Auth codes are single-use and removed from the URL immediately after exchange
+- No runtime dependencies — eliminates supply chain risk entirely
+- Open source — [view the source on GitHub](https://github.com/dotbots-boutique/auth-sdk)
+ 
+To report a security vulnerability, please email [security@dotbots.ai](mailto:security@dotbots.ai) instead of opening a public issue.
+ 
+---
+ 
+## Exports
+ 
+```typescript
+import { DotBotsAuth, DotBotsAuthError } from '@dotbots-boutique/auth-sdk';
+import type { DotBotsUser, DotBotsConfig, DotBotsAuthEvent, DotBotsProxyConfig } from '@dotbots-boutique/auth-sdk';
+import { DotBotsAuthProvider, useDotBotsAuth } from '@dotbots-boutique/auth-sdk/react';
+```
+ 
+---
+ 
+## License
+ 
+[MIT](./LICENSE) — © DotBots Boutique

package/SECURITY.md

@@ -0,0 +1,51 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.x.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+We take security seriously. If you discover a security vulnerability in `@dotbots-boutique/auth-sdk`, please report it responsibly.
+
+### How to Report
+
+1. **Do NOT** open a public GitHub issue for security vulnerabilities
+2. Email your findings to **security@dotbots.ai**
+3. Include a detailed description of the vulnerability
+4. Include steps to reproduce the issue
+5. If possible, include a suggested fix
+
+### What to Expect
+
+- **Acknowledgment**: We will acknowledge your report within 48 hours
+- **Assessment**: We will assess the impact and severity within 5 business days
+- **Resolution**: We aim to release a fix within 14 days for critical issues
+- **Credit**: With your permission, we will credit you in the release notes
+
+### Scope
+
+The following are in scope for this security policy:
+
+- Token handling and storage
+- postMessage origin validation
+- Authentication flow vulnerabilities
+- Data exposure through the SDK
+
+### Out of Scope
+
+- Vulnerabilities in the DotBots API itself (report to security@dotbots.ai separately)
+- Issues in third-party dependencies
+- Issues requiring physical access to a device
+
+## Security Design Principles
+
+This SDK follows these security principles:
+
+1. **Tokens are never persisted** — stored only in memory, never in localStorage, sessionStorage, or cookies
+2. **postMessage origins are always validated** — only messages from the configured marketplace origin are accepted
+3. **Auth codes are single-use** — removed from URL and memory immediately after exchange
+4. **No sensitive data in logs** — tokens are never logged, even in development mode
+5. **Zero runtime dependencies** — minimizes supply chain attack surface