@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.20

package/README.md

@@ -1,23 +1,31 @@
 # @robelest/convex-auth
 
-Component-first authentication for [Convex](https://convex.dev). One component, one class, full TypeScript support.
+Component-first authentication for [Convex](https://convex.dev). One component,
+one setup API, full TypeScript support.
 
 ## Features
 
-- **Class-based API** — `new Auth(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.
+- **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).
+- **SSR support** — framework-agnostic httpOnly cookie API (SvelteKit, TanStack
+  Start, Next.js).
 - **Context enrichment** — zero-boilerplate `ctx.auth.userId` via `AuthCtx`.
 
 ## Install
 
 ```bash
-npm install @robelest/convex-auth
+bun add @robelest/convex-auth
 ```
 
 > Renamed package: if you are migrating from earlier previews, replace
@@ -25,11 +33,22 @@ npm install @robelest/convex-auth
 
 ## 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 a
+  typed `CONVEX_DEPLOYMENT` like `dev:my-deployment` (usually set by
+  `npx convex dev`), or you can pass `--prod`, `--preview-name`,
+  `--deployment-name`, `--url`, or `--admin-key`.
+- Use `--url` for explicit or self-hosted targets. Typed deployment and
+  admin-key parsing only applies to Convex Cloud selections.
+
 ```bash
-npx @robelest/convex-auth
+bunx @robelest/convex-auth
 ```
 
-The interactive CLI sets up your Convex component, auth config, and HTTP routes in under a minute.
+The interactive CLI sets up your Convex component, auth config, and HTTP routes
+in under a minute.
 
 ## Manual Setup
 
@@ -45,14 +64,16 @@ export default app;
 
 ```ts
 // convex/auth.ts
-import { Auth } from "@robelest/convex-auth/component";
+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 = new Auth(components.auth, {
+const auth = createAuth(components.auth, {
   providers: [
-    OAuth(new GitHub(process.env.AUTH_GITHUB_ID!, process.env.AUTH_GITHUB_SECRET!)),
+    OAuth(
+      new GitHub(process.env.AUTH_GITHUB_ID!, process.env.AUTH_GITHUB_SECRET!),
+    ),
   ],
 });
 
@@ -72,7 +93,8 @@ export default http;
 
 ## Recommended Convex API Handling (`fluent-convex`)
 
-For new projects, we recommend `fluent-convex` for auth middleware composition and cleaner API exports.
+For new projects, we recommend `fluent-convex` for auth middleware composition
+and cleaner API exports.
 
 ```ts
 // convex/functions.ts
@@ -95,20 +117,39 @@ 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`.
+`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"` |
+| 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
 
-See the full [README](https://github.com/robelest/convex-auth#readme) for detailed usage, API reference, SSR integration, and more.
+See the full [README](https://github.com/robelest/convex-auth#readme) for
+detailed usage, API reference, SSR integration, and more.

package/dist/authorization/index.d.ts

@@ -0,0 +1,63 @@
+//#region src/authorization/index.d.ts
+/**
+ * Lightweight authorization helpers.
+ *
+ * @module
+ */
+/**
+ * Define typed role definitions for authorization.
+ *
+ * Transforms a declarative roles configuration object into a normalized
+ * map where each role has an `id` (matching its key), an optional `label`,
+ * and a typed `grants` array. The returned object is fully type-safe:
+ * role IDs and grant strings are narrowed to their literal types, so
+ * `member.resolve()` and `member.create()` calls are checked at compile time.
+ * This is the canonical way to define role metadata for the auth library.
+ *
+ * @param roles - An object mapping role IDs to their configuration.
+ *   Each entry must include a `grants` array of permission strings and
+ *   may include an optional human-readable `label`.
+ * @typeParam TRoles - The object literal shape of your role definitions.
+ * @returns An object with the same keys as `roles`, where each value
+ *   is `{ id, label?, grants }` — `id` is the role key as a string,
+ *   and `grants` is a mutable array of the declared grant strings.
+ *
+ * @example
+ * ```ts
+ * import { defineRoles } from "@robelest/convex-auth/authorization";
+ *
+ * const roles = defineRoles({
+ *   admin: { label: "Administrator", grants: ["issues:write", "members:manage"] },
+ *   member: { label: "Member", grants: ["issues:write"] },
+ *   viewer: { grants: ["issues:read"] },
+ * });
+ *
+ * // roles.admin.id   === "admin"
+ * // roles.admin.grants === ["issues:write", "members:manage"]
+ *
+ * // Pass to createAuth:
+ * const auth = createAuth(components.auth, {
+ *   providers: [...],
+ *   authorization: { roles },
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * type RoleId = keyof typeof roles;
+ * // RoleId = "admin" | "member" | "viewer"
+ * ```
+ *
+ * @see {@link ConvexAuthConfig}
+ */
+declare function defineRoles<const TRoles extends Record<string, {
+  label?: string;
+  grants: readonly string[];
+}>>(roles: TRoles): { [K in keyof TRoles]: {
+  id: K & string;
+  label?: TRoles[K]["label"];
+  grants: Array<TRoles[K]["grants"][number] & string>;
+} };
+//#endregion
+export { defineRoles };
+//# sourceMappingURL=index.d.ts.map

package/dist/authorization/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/authorization/index.ts"],"mappings":";;AAoDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,WAAA,sBACO,MAAA;EAEjB,KAAA;EAAgB,MAAA;AAAA,GAAA,CAGpB,KAAA,EAAO,MAAA,iBAEK,MAAA;EACV,EAAA,EAAI,CAAA;EACJ,KAAA,GAAQ,MAAA,CAAO,CAAA;EACf,MAAA,EAAQ,KAAA,CAAM,MAAA,CAAO,CAAA;AAAA"}

package/dist/authorization/index.js

@@ -0,0 +1,63 @@
+//#region src/authorization/index.ts
+/**
+* Lightweight authorization helpers.
+*
+* @module
+*/
+/**
+* Define typed role definitions for authorization.
+*
+* Transforms a declarative roles configuration object into a normalized
+* map where each role has an `id` (matching its key), an optional `label`,
+* and a typed `grants` array. The returned object is fully type-safe:
+* role IDs and grant strings are narrowed to their literal types, so
+* `member.resolve()` and `member.create()` calls are checked at compile time.
+* This is the canonical way to define role metadata for the auth library.
+*
+* @param roles - An object mapping role IDs to their configuration.
+*   Each entry must include a `grants` array of permission strings and
+*   may include an optional human-readable `label`.
+* @typeParam TRoles - The object literal shape of your role definitions.
+* @returns An object with the same keys as `roles`, where each value
+*   is `{ id, label?, grants }` — `id` is the role key as a string,
+*   and `grants` is a mutable array of the declared grant strings.
+*
+* @example
+* ```ts
+* import { defineRoles } from "@robelest/convex-auth/authorization";
+*
+* const roles = defineRoles({
+*   admin: { label: "Administrator", grants: ["issues:write", "members:manage"] },
+*   member: { label: "Member", grants: ["issues:write"] },
+*   viewer: { grants: ["issues:read"] },
+* });
+*
+* // roles.admin.id   === "admin"
+* // roles.admin.grants === ["issues:write", "members:manage"]
+*
+* // Pass to createAuth:
+* const auth = createAuth(components.auth, {
+*   providers: [...],
+*   authorization: { roles },
+* });
+* ```
+*
+* @example
+* ```ts
+* type RoleId = keyof typeof roles;
+* // RoleId = "admin" | "member" | "viewer"
+* ```
+*
+* @see {@link ConvexAuthConfig}
+*/
+function defineRoles(roles) {
+	return Object.fromEntries(Object.entries(roles).map(([id, role]) => [id, {
+		id,
+		...role.label ? { label: role.label } : {},
+		grants: [...role.grants]
+	}]));
+}
+
+//#endregion
+export { defineRoles };
+//# sourceMappingURL=index.js.map

package/dist/authorization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/authorization/index.ts"],"sourcesContent":["/**\n * Lightweight authorization helpers.\n *\n * @module\n */\n\n/**\n * Define typed role definitions for authorization.\n *\n * Transforms a declarative roles configuration object into a normalized\n * map where each role has an `id` (matching its key), an optional `label`,\n * and a typed `grants` array. The returned object is fully type-safe:\n * role IDs and grant strings are narrowed to their literal types, so\n * `member.resolve()` and `member.create()` calls are checked at compile time.\n * This is the canonical way to define role metadata for the auth library.\n *\n * @param roles - An object mapping role IDs to their configuration.\n *   Each entry must include a `grants` array of permission strings and\n *   may include an optional human-readable `label`.\n * @typeParam TRoles - The object literal shape of your role definitions.\n * @returns An object with the same keys as `roles`, where each value\n *   is `{ id, label?, grants }` — `id` is the role key as a string,\n *   and `grants` is a mutable array of the declared grant strings.\n *\n * @example\n * ```ts\n * import { defineRoles } from \"@robelest/convex-auth/authorization\";\n *\n * const roles = defineRoles({\n *   admin: { label: \"Administrator\", grants: [\"issues:write\", \"members:manage\"] },\n *   member: { label: \"Member\", grants: [\"issues:write\"] },\n *   viewer: { grants: [\"issues:read\"] },\n * });\n *\n * // roles.admin.id   === \"admin\"\n * // roles.admin.grants === [\"issues:write\", \"members:manage\"]\n *\n * // Pass to createAuth:\n * const auth = createAuth(components.auth, {\n *   providers: [...],\n *   authorization: { roles },\n * });\n * ```\n *\n * @example\n * ```ts\n * type RoleId = keyof typeof roles;\n * // RoleId = \"admin\" | \"member\" | \"viewer\"\n * ```\n *\n * @see {@link ConvexAuthConfig}\n */\nexport function defineRoles<\n  const TRoles extends Record<\n    string,\n    { label?: string; grants: readonly string[] }\n  >,\n>(\n  roles: TRoles,\n): {\n  [K in keyof TRoles]: {\n    id: K & string;\n    label?: TRoles[K][\"label\"];\n    grants: Array<TRoles[K][\"grants\"][number] & string>;\n  };\n} {\n  return Object.fromEntries(\n    Object.entries(roles).map(([id, role]) => [\n      id,\n      {\n        id,\n        ...(role.label ? { label: role.label } : {}),\n        grants: [...role.grants],\n      },\n    ]),\n  ) as {\n    [K in keyof TRoles]: {\n      id: K & string;\n      label?: TRoles[K][\"label\"];\n      grants: Array<TRoles[K][\"grants\"][number] & string>;\n    };\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,SAAgB,YAMd,OAOA;AACA,QAAO,OAAO,YACZ,OAAO,QAAQ,MAAM,CAAC,KAAK,CAAC,IAAI,UAAU,CACxC,IACA;EACE;EACA,GAAI,KAAK,QAAQ,EAAE,OAAO,KAAK,OAAO,GAAG,EAAE;EAC3C,QAAQ,CAAC,GAAG,KAAK,OAAO;EACzB,CACF,CAAC,CACH"}