@robelest/convex-auth 0.0.4-preview.13 → 0.0.4-preview.16

package/README.md

@@ -1,21 +1,152 @@
 # @robelest/convex-auth
 
-Component-first authentication for [Convex](https://convex.dev).
+Component-first authentication for [Convex](https://convex.dev). One component,
+one setup API, full TypeScript support.
 
-[![npm version](https://img.shields.io/npm/v/@robelest/convex-auth.svg?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/@robelest/convex-auth)
-[![npm downloads](https://img.shields.io/npm/dm/@robelest/convex-auth?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/@robelest/convex-auth)
+## Features
+
+- **Convex-native setup API** — `createAuth(components.auth, { providers })`
+  gives you everything.
+- **OAuth via Arctic** — 50+ providers through [Arctic](https://arcticjs.dev),
+  zero-dependency OAuth 2.0.
+- **Fluent Convex builders (recommended)** — cleaner auth-aware API handling
+  with middleware and explicit `.public()` / `.internal()` exports.
+- **Password, passkeys, TOTP, magic links, OTP, phone, anonymous** — all built
+  in.
+- **Device Authorization (RFC 8628)** — authenticate CLIs, smart TVs, and IoT
+  devices.
+- **API keys** — scoped permissions, SHA-256 hashed storage, optional rate
+  limiting.
+- **Groups, memberships, invites** — hierarchical multi-tenancy with roles.
+- **SSR support** — framework-agnostic httpOnly cookie API (SvelteKit, TanStack
+  Start, Next.js).
+- **Context enrichment** — zero-boilerplate `ctx.auth.userId` via `AuthCtx`.
 
 ## Install
 
 ```bash
-pnpm add @robelest/convex-auth
-pnpx @robelest/convex-auth
+bun add @robelest/convex-auth
 ```
 
-## Documentation
+> Renamed package: if you are migrating from earlier previews, replace
+> `@convex-dev/auth` with `@robelest/convex-auth` in imports and CLI commands.
+
+## Quick Start
+
+Before running setup:
+
+- Run from your app project root (must include `package.json`).
+- Make sure a Convex deployment can be resolved. By default the CLI reads
+  `CONVEX_DEPLOYMENT` (usually set by `npx convex dev`), or you can pass
+  `--prod`, `--preview-name`, `--deployment-name`, `--url`, or `--admin-key`.
+
+```bash
+bunx @robelest/convex-auth
+```
+
+The interactive CLI sets up your Convex component, auth config, and HTTP routes
+in under a minute.
+
+## Manual Setup
+
+```ts
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import auth from "@robelest/convex-auth/convex.config";
+
+const app = defineApp();
+app.use(auth);
+export default app;
+```
+
+```ts
+// convex/auth.ts
+import { createAuth } from "@robelest/convex-auth/component";
+import { components } from "./_generated/api";
+import { GitHub } from "arctic";
+import { OAuth } from "@robelest/convex-auth/providers";
+
+const auth = createAuth(components.auth, {
+  providers: [
+    OAuth(
+      new GitHub(process.env.AUTH_GITHUB_ID!, process.env.AUTH_GITHUB_SECRET!),
+    ),
+  ],
+});
+
+export { auth };
+export const { signIn, signOut, store } = auth;
+```
 
-**[convex-auth.pages.dev](https://convex-auth.pages.dev)**
+```ts
+// convex/http.ts
+import { httpRouter } from "convex/server";
+import { auth } from "./auth";
 
-## License
+const http = httpRouter();
+auth.http.add(http);
+export default http;
+```
+
+## Recommended Convex API Handling (`fluent-convex`)
+
+For new projects, we recommend `fluent-convex` for auth middleware composition
+and cleaner API exports.
+
+```ts
+// convex/functions.ts
+import { createBuilder } from "fluent-convex";
+import { WithZod } from "fluent-convex/zod";
+import type { DataModel } from "./_generated/dataModel";
+import { auth } from "./auth";
+
+const convex = createBuilder<DataModel>();
+
+const withRequiredAuth = convex.createMiddleware<any, { auth: any }>(
+  async (ctx, next) => {
+    const userId = await auth.user.require(ctx);
+    const user = await auth.user.get(ctx, userId);
+    return next({ ...ctx, auth: { ...ctx.auth, userId, user } });
+  },
+);
+
+export const query = convex.query().use(withRequiredAuth).extend(WithZod);
+export const mutation = convex.mutation().use(withRequiredAuth).extend(WithZod);
+```
+
+`AuthCtx` from `@robelest/convex-auth/component` remains supported if your
+project already uses `convex-helpers`.
+
+## Providers
+
+| Provider          | Import                                                                  |
+| ----------------- | ----------------------------------------------------------------------- |
+| OAuth (Arctic)    | `import { OAuth } from "@robelest/convex-auth/providers"`               |
+| Password          | `import { Password } from "@robelest/convex-auth/providers/password"`   |
+| Passkey           | `import { Passkey } from "@robelest/convex-auth/providers/passkey"`     |
+| TOTP              | `import { Totp } from "@robelest/convex-auth/providers/totp"`           |
+| Phone/SMS         | `import { phone } from "@robelest/convex-auth/providers/phone"`         |
+| Anonymous         | `import { Anonymous } from "@robelest/convex-auth/providers/anonymous"` |
+| Device (RFC 8628) | `import { Device } from "@robelest/convex-auth/providers"`              |
+
+## Enterprise
+
+The enterprise direction is a headless SDK/API rather than a hosted admin UI.
+
+- `auth.sso.*` stores enterprise config on top of `auth.group`, with distinct
+  `admin` and `client` helper surfaces.
+- Standardized helpers are exposed as `auth.sso.admin.connection.*`,
+  `auth.sso.admin.connection.domain.*`, `auth.sso.admin.oidc.*`,
+  `auth.sso.admin.saml.*`, `auth.sso.admin.policy.*`,
+  `auth.sso.admin.audit.list`, `auth.sso.admin.webhook.endpoint.*`,
+  `auth.sso.client.signIn`, `auth.sso.client.metadata`, and
+  `auth.scim.admin.configure/get/validate`.
+- Enterprise helpers are server-side primitives. Consumers can build and expose
+  their own Convex RPC wrappers when needed.
+- `auth.sso.client.metadata(...)` uses the local `@robelest/samlify` package to
+  parse IdP metadata and generate SP metadata from the same setup state.
+
+## Documentation
 
-[Apache-2.0](../../LICENSE)
+See the full [README](https://github.com/robelest/convex-auth#readme) for
+detailed usage, API reference, SSR integration, and more.