feat(examples): add database-conns POC for live-tenant signup and change-password

Signed re-add of the database-conns example that previously entered the
branch via an unsigned upstream merge lineage. Content matches the
validated PR tree.

Author: tusharpandey13

examples/database-conns/.env.example

@@ -0,0 +1,6 @@
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_CLIENT_ID=your_client_id
+AUTH0_CLIENT_SECRET=your_client_secret
+AUTH0_DB_CONNECTION=Username-Password-Authentication
+APP_BASE_URL=http://localhost:3000
+PORT=3000

examples/database-conns/README.md

@@ -0,0 +1,114 @@
+# Database Connections POC Example
+
+This is a manual harness for live-tenant testing of `signUp` and `changePassword` database connection operations with Auth0.
+
+## Prerequisites
+
+- An Auth0 tenant with a database connection enabled on the app
+- Signup enabled on the connection (or expect documented signup-disabled behavior)
+- The client configured as either a confidential app (with client secret) or public app as configured
+- Node.js and npm installed
+
+## Setup
+
+1. Copy `.env.example` to `.env` and fill in your Auth0 tenant credentials:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Install workspace dependencies at the repo root:
+   ```bash
+   npm install
+   ```
+
+3. Build the auth0-auth-js and auth0-server-js packages first to ensure the example resolves the new database connection surface from dist:
+   ```bash
+   npm run build --workspace=packages/auth0-auth-js
+   npm run build --workspace=packages/auth0-server-js
+   ```
+
+4. Install the example dependencies:
+   ```bash
+   npm install --workspace=examples/database-conns
+   ```
+
+## Running
+
+```bash
+npm start --workspace=examples/database-conns
+```
+
+The app will start on the port specified in your `.env` (default: `http://localhost:3000`).
+
+## Testing
+
+### Sign Up
+
+Test user registration:
+
+```bash
+curl -X POST localhost:3000/signup \
+  -H 'content-type: application/json' \
+  -d '{"email":"new@example.com","password":"Str0ng-pw!"}'
+```
+
+Expected success response:
+```json
+{
+  "ok": true,
+  "user": {
+    "id": "...",
+    "email": "new@example.com",
+    "emailVerified": false
+  }
+}
+```
+
+Expected error when re-running with the same email:
+```json
+{
+  "ok": false,
+  "code": "signup_error",
+  "message": "...",
+  "cause": { "error": "..." }
+}
+```
+
+### Change Password
+
+Test password reset request:
+
+```bash
+curl -X POST localhost:3000/change-password \
+  -H 'content-type: application/json' \
+  -d '{"email":"new@example.com"}'
+```
+
+Expected success response:
+```json
+{
+  "ok": true,
+  "message": "We've just sent you an email to reset your password."
+}
+```
+
+A password reset email will be sent to the specified email address from your Auth0 tenant.
+
+## Investigation Notes
+
+This POC is the live-tenant check that closes the signup success-rate investigation. When running the tests above, capture observed status codes and response codes for:
+
+- Existing user signup attempt (expect 4xx validation error)
+- Weak password signup attempt (expect 4xx validation error)
+- Signup with disabled connection (expect 4xx validation error)
+
+These should all be expected validation 4xx responses, not a defect. Any 5xx or unexpected behavior indicates a platform issue.
+
+## Implementation Details
+
+The example:
+- Uses a simple no-op state store for the `ServerClient` (database operations never read or write session state)
+- Catches `SignUpError` and `ChangePasswordError` and surfaces them with appropriate HTTP status codes
+- Reads plain text responses from the change-password endpoint
+
+See the source files for implementation details.

examples/database-conns/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "example-database-conns",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "tsx src/index.ts --project tsconfig.json",
+    "build": "tsc --project tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.1",
+    "tsx": "^4.19.2",
+    "typescript": "~5.8.3"
+  },
+  "dependencies": {
+    "@auth0/auth0-server-js": "*",
+    "dotenv": "^16.4.7",
+    "express": "^5.1.0"
+  }
+}

examples/database-conns/src/auth0.ts

@@ -0,0 +1,23 @@
+import 'dotenv/config';
+import { ServerClient } from '@auth0/auth0-server-js';
+
+export const connection = process.env.AUTH0_DB_CONNECTION!;
+
+export const auth0 = new ServerClient({
+  domain: process.env.AUTH0_DOMAIN!,
+  clientId: process.env.AUTH0_CLIENT_ID!,
+  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
+  // ServerClient requires state and transaction stores at construction. The database operations
+  // (signUp / changePassword) never read or write them, so no-op stores are sufficient
+  // for this POC. A real app uses StatelessStateStore / StatefulStateStore and CookieTransactionStore.
+  stateStore: {
+    set: async () => {},
+    get: async () => undefined,
+    delete: async () => {},
+  } as any,
+  transactionStore: {
+    create: async () => 'noop',
+    read: async () => undefined,
+    delete: async () => {},
+  } as any,
+});

examples/database-conns/src/index.ts

@@ -0,0 +1,41 @@
+import express from 'express';
+import { auth0, connection } from './auth0.js';
+import { SignUpError, ChangePasswordError } from '@auth0/auth0-server-js';
+
+const app = express();
+app.use(express.json());
+
+// POST /signup { email, password }
+app.post('/signup', async (req, res) => {
+  try {
+    const result = await auth0.database.signUp({
+      email: req.body.email,
+      password: req.body.password,
+      connection,
+    });
+    res.json({ ok: true, user: result }); // result.id normalized
+  } catch (err) {
+    if (err instanceof SignUpError) {
+      res.status(400).json({ ok: false, code: err.code, message: err.message, cause: err.cause });
+    } else {
+      res.status(500).json({ ok: false, message: 'unexpected' });
+    }
+  }
+});
+
+// POST /change-password { email }
+app.post('/change-password', async (req, res) => {
+  try {
+    const message = await auth0.database.changePassword({ email: req.body.email, connection });
+    res.json({ ok: true, message }); // plain-text confirmation
+  } catch (err) {
+    if (err instanceof ChangePasswordError) {
+      res.status(400).json({ ok: false, code: err.code, message: err.message });
+    } else {
+      res.status(500).json({ ok: false, message: 'unexpected' });
+    }
+  }
+});
+
+const port = Number(process.env.PORT ?? 3000);
+app.listen(port, () => console.log(`database-conns POC on http://localhost:${port}`));

examples/database-conns/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}