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

package/src/component/schema.ts

@@ -1,6 +1,24 @@
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values";
 
+import {
+  vApiKeyRateLimit,
+  vApiKeyRateLimitState,
+  vApiKeyScope,
+  vAuditActorType,
+  vAuditStatus,
+  vDeviceStatus,
+  vEnterprisePolicy,
+  vEnterpriseSecretKind,
+  vEnterpriseStatus,
+  vInviteStatus,
+  vScimResourceType,
+  vScimStatus,
+  vTag,
+  vWebhookDeliveryStatus,
+  vWebhookEndpointStatus,
+} from "./model";
+
 /**
  * Schema for the auth component.
  *
@@ -13,7 +31,7 @@ export default defineSchema({
    * Authenticated users. A user may have multiple linked accounts
    * and multiple concurrent sessions.
    */
-  user: defineTable({
+  User: defineTable({
     name: v.optional(v.string()),
     image: v.optional(v.string()),
     email: v.optional(v.string()),
@@ -24,33 +42,36 @@ export default defineSchema({
     extend: v.optional(v.any()),
   })
     .index("email", ["email"])
-    .index("phone", ["phone"]),
+    .index("email_verified", ["email", "emailVerificationTime"])
+    .index("phone", ["phone"])
+    .index("phone_verified", ["phone", "phoneVerificationTime"]),
 
   /**
    * Active sessions. A single user can have multiple concurrent sessions
    * across different devices or browsers. Sessions expire after a
    * configurable duration.
    */
-  session: defineTable({
-    userId: v.id("user"),
+  Session: defineTable({
+    userId: v.id("User"),
     expirationTime: v.number(),
-  }).index("userId", ["userId"]),
+  }).index("user_id", ["userId"]),
 
   /**
    * Authentication accounts. Each account links a user to a single
    * authentication provider (e.g. Google OAuth, email/password).
    * A user can have multiple accounts linked.
    */
-  account: defineTable({
-    userId: v.id("user"),
+  Account: defineTable({
+    userId: v.id("User"),
     provider: v.string(),
     providerAccountId: v.string(),
     secret: v.optional(v.string()),
     emailVerified: v.optional(v.string()),
     phoneVerified: v.optional(v.string()),
+    extend: v.optional(v.any()),
   })
-    .index("userIdAndProvider", ["userId", "provider"])
-    .index("providerAndAccountId", ["provider", "providerAccountId"]),
+    .index("user_id_provider", ["userId", "provider"])
+    .index("provider_account_id", ["provider", "providerAccountId"]),
 
   /**
    * Refresh tokens for session continuity. Tokens are single-use and form
@@ -60,14 +81,15 @@ export default defineSchema({
    * been used yet. A 10-second reuse window allows for concurrent requests.
    * Any invalid use of a token invalidates the entire chain.
    */
-  token: defineTable({
-    sessionId: v.id("session"),
+  RefreshToken: defineTable({
+    sessionId: v.id("Session"),
     expirationTime: v.number(),
     firstUsedTime: v.optional(v.number()),
-    parentRefreshTokenId: v.optional(v.id("token")),
+    parentRefreshTokenId: v.optional(v.id("RefreshToken")),
   })
-    .index("sessionId", ["sessionId"])
-    .index("sessionIdAndParentRefreshTokenId", [
+    .index("session_id", ["sessionId"])
+    .index("session_id_first_used", ["sessionId", "firstUsedTime"])
+    .index("session_id_parent_refresh_token_id", [
       "sessionId",
       "parentRefreshTokenId",
     ]),
@@ -75,8 +97,8 @@ export default defineSchema({
   /**
    * Verification codes for OTP tokens, magic link tokens, and OAuth codes.
    */
-  verification: defineTable({
-    accountId: v.id("account"),
+  VerificationCode: defineTable({
+    accountId: v.id("Account"),
     provider: v.string(),
     code: v.string(),
     expirationTime: v.number(),
@@ -84,15 +106,15 @@ export default defineSchema({
     emailVerified: v.optional(v.string()),
     phoneVerified: v.optional(v.string()),
   })
-    .index("accountId", ["accountId"])
+    .index("account_id", ["accountId"])
     .index("code", ["code"]),
 
   /**
    * PKCE verifiers for OAuth flows. Stores the cryptographic verifier
    * used to prove the authorization request originated from this client.
    */
-  verifier: defineTable({
-    sessionId: v.optional(v.id("session")),
+  AuthVerifier: defineTable({
+    sessionId: v.optional(v.id("Session")),
     signature: v.optional(v.string()),
   }).index("signature", ["signature"]),
 
@@ -101,8 +123,8 @@ export default defineSchema({
    * registered authenticator (Touch ID, Face ID, security key, etc.).
    * A user can have multiple passkeys across different devices.
    */
-  passkey: defineTable({
-    userId: v.id("user"),
+  Passkey: defineTable({
+    userId: v.id("User"),
     /** Base64url-encoded credential ID from the authenticator. */
     credentialId: v.string(),
     /** Public key bytes (SEC1 uncompressed for EC, SPKI for RSA). */
@@ -122,8 +144,8 @@ export default defineSchema({
     createdAt: v.number(),
     lastUsedAt: v.optional(v.number()),
   })
-    .index("userId", ["userId"])
-    .index("credentialId", ["credentialId"]),
+    .index("user_id", ["userId"])
+    .index("credential_id", ["credentialId"]),
 
   /**
    * TOTP two-factor authentication secrets. Each record links a user to
@@ -134,8 +156,8 @@ export default defineSchema({
    * by successfully entering a code from their authenticator app.
    * Unverified enrollments are in-progress setup that can be discarded.
    */
-  totp: defineTable({
-    userId: v.id("user"),
+  TotpFactor: defineTable({
+    userId: v.id("User"),
     /** Raw TOTP secret key bytes. */
     secret: v.bytes(),
     /** Number of digits in each code (typically 6). */
@@ -149,14 +171,15 @@ export default defineSchema({
     createdAt: v.number(),
     lastUsedAt: v.optional(v.number()),
   })
-    .index("userId", ["userId"]),
+    .index("user_id", ["userId"])
+    .index("user_id_verified", ["userId", "verified"]),
 
   /**
    * Device authorization codes (RFC 8628). Each record tracks a pending
    * device auth session — the device polls with `deviceCode` while the
    * user authorizes via `userCode` on a secondary device.
    */
-  device: defineTable({
+  DeviceCode: defineTable({
     /** High-entropy code used by the device for polling. Stored as SHA-256 hash. */
     deviceCodeHash: v.string(),
     /** Short human-readable code the user enters (e.g. "WDJB-MJHT"). */
@@ -166,62 +189,62 @@ export default defineSchema({
     /** Minimum polling interval in seconds. */
     interval: v.number(),
     /** Current status of this device authorization session. */
-    status: v.union(
-      v.literal("pending"),
-      v.literal("authorized"),
-      v.literal("denied"),
-    ),
+    status: vDeviceStatus,
     /** Set when the user authorizes — links to the authorizing user. */
-    userId: v.optional(v.id("user")),
+    userId: v.optional(v.id("User")),
     /** Set when the user authorizes — the session created for the device. */
-    sessionId: v.optional(v.id("session")),
+    sessionId: v.optional(v.id("Session")),
     /** Timestamp of the last poll request (for slow_down enforcement). */
     lastPolledAt: v.optional(v.number()),
   })
-    .index("deviceCodeHash", ["deviceCodeHash"])
-    .index("userCode", ["userCode", "status"]),
+    .index("device_code_hash", ["deviceCodeHash"])
+    .index("user_code_status", ["userCode", "status"]),
 
   /**
    * Rate limit tracking for OTP and password sign-in attempts.
    */
-  limit: defineTable({
+  RateLimit: defineTable({
     identifier: v.string(),
-    lastAttemptTime: v.number(),
-    attemptsLeft: v.number(),
-  }).index("identifier", ["identifier"]),
+    last_attempt_time: v.number(),
+    attempts_left: v.number(),
+  }).index("by_identifier", ["identifier"]),
 
   /**
    * Hierarchical groups. A group with no `parentGroupId` is a root group.
    * Groups can nest arbitrarily deep via `parentGroupId` for modeling
    * organizations, teams, departments, or any tree structure.
    */
-  group: defineTable({
+  Group: defineTable({
     name: v.string(),
     slug: v.optional(v.string()),
     type: v.optional(v.string()),
-    parentGroupId: v.optional(v.id("group")),
+    parentGroupId: v.optional(v.id("Group")),
+    /** Denormalized root group ID. Self-referencing for root groups. */
+    rootGroupId: v.optional(v.id("Group")),
+    /** Denormalized flag: `true` when `parentGroupId` is absent. */
+    isRoot: v.optional(v.boolean()),
     /** Faceted classification tags. Normalized at write time (trimmed, lowercased). */
-    tags: v.optional(
-      v.array(v.object({ key: v.string(), value: v.string() })),
-    ),
+    tags: v.optional(v.array(vTag)),
     extend: v.optional(v.any()),
   })
     .index("slug", ["slug"])
-    .index("parentGroupId", ["parentGroupId"])
+    .index("parent_group_id", ["parentGroupId"])
+    .index("root_group_id", ["rootGroupId"])
+    .index("is_root", ["isRoot"])
     .index("type", ["type"])
-    .index("typeAndParentGroupId", ["type", "parentGroupId"]),
+    .index("type_parent_group_id", ["type", "parentGroupId"]),
 
   /**
    * Denormalized group-tag index table for efficient tag-based filtering.
    * Each row maps one `(key, value)` pair to a group. Kept in sync by
    * `groupCreate`, `groupUpdate`, and `groupDelete`.
    */
-  groupTag: defineTable({
-    groupId: v.id("group"),
+  GroupTag: defineTable({
+    group_id: v.id("Group"),
     key: v.string(),
     value: v.string(),
   })
-    .index("by_group", ["groupId"])
+    .index("by_group", ["group_id"])
     .index("by_key_value", ["key", "value"])
     .index("by_key", ["key"]),
 
@@ -230,16 +253,18 @@ export default defineSchema({
    * role (e.g. "owner", "admin", "member", "viewer"). A user can be a
    * member of multiple groups with different roles in each.
    */
-  member: defineTable({
-    groupId: v.id("group"),
-    userId: v.id("user"),
+  GroupMember: defineTable({
+    groupId: v.id("Group"),
+    userId: v.id("User"),
     role: v.optional(v.string()),
+    roleIds: v.optional(v.array(v.string())),
     status: v.optional(v.string()),
     extend: v.optional(v.any()),
   })
-    .index("groupId", ["groupId"])
-    .index("groupIdAndUserId", ["groupId", "userId"])
-    .index("userId", ["userId"]),
+    .index("group_id", ["groupId"])
+    .index("group_id_user_id", ["groupId", "userId"])
+    .index("group_id_status", ["groupId", "status"])
+    .index("user_id", ["userId"]),
 
   /**
    * Invitations. Tracks pending, accepted, revoked, and expired
@@ -249,41 +274,202 @@ export default defineSchema({
    * `email` and `invitedByUserId` are optional to support CLI-generated
    * invite links where neither is known upfront.
    */
-  invite: defineTable({
-    groupId: v.optional(v.id("group")),
-    invitedByUserId: v.optional(v.id("user")),
+  GroupInvite: defineTable({
+    groupId: v.optional(v.id("Group")),
+    invitedByUserId: v.optional(v.id("User")),
     email: v.optional(v.string()),
     tokenHash: v.string(),
     role: v.optional(v.string()),
-    status: v.union(
-      v.literal("pending"),
-      v.literal("accepted"),
-      v.literal("revoked"),
-      v.literal("expired"),
-    ),
+    roleIds: v.optional(v.array(v.string())),
+    status: vInviteStatus,
     expiresTime: v.optional(v.number()),
-    acceptedByUserId: v.optional(v.id("user")),
+    acceptedByUserId: v.optional(v.id("User")),
     acceptedTime: v.optional(v.number()),
     extend: v.optional(v.any()),
   })
-    .index("tokenHash", ["tokenHash"])
+    .index("token_hash", ["tokenHash"])
     .index("status", ["status"])
-    .index("emailAndStatus", ["email", "status"])
-    .index("invitedByUserIdAndStatus", ["invitedByUserId", "status"])
-    .index("groupId", ["groupId"])
-    .index("groupIdAndStatus", ["groupId", "status"])
-    .index("roleAndStatusAndAcceptedByUserId", [
-      "role",
-      "status",
-      "acceptedByUserId",
-    ]),
+    .index("email_status", ["email", "status"])
+    .index("invited_by_user_id_status", ["invitedByUserId", "status"])
+    .index("group_id", ["groupId"])
+    .index("group_id_status", ["groupId", "status"]),
+
+  /**
+   * Enterprise configuration attached to a root group/organization.
+   *
+   * The `config` payload intentionally stays flexible so the headless enterprise
+   * SDK can evolve without forcing schema churn for every protocol-specific
+   * field addition.
+   */
+  Enterprise: defineTable({
+    groupId: v.id("Group"),
+    slug: v.optional(v.string()),
+    name: v.optional(v.string()),
+    status: vEnterpriseStatus,
+    policy: v.optional(vEnterprisePolicy),
+    config: v.optional(v.any()),
+    extend: v.optional(v.any()),
+  })
+    .index("group_id", ["groupId"])
+    .index("slug", ["slug"])
+    .index("status", ["status"]),
+
+  /**
+   * Verified or pending domains linked to an enterprise record.
+   */
+  EnterpriseDomain: defineTable({
+    enterpriseId: v.id("Enterprise"),
+    groupId: v.id("Group"),
+    domain: v.string(),
+    isPrimary: v.boolean(),
+    verifiedAt: v.optional(v.number()),
+  })
+    .index("enterprise_id", ["enterpriseId"])
+    .index("group_id", ["groupId"])
+    .index("domain", ["domain"]),
+
+  /**
+   * Pending DNS TXT verification challenges for enterprise domains.
+   */
+  EnterpriseDomainVerification: defineTable({
+    enterpriseId: v.id("Enterprise"),
+    groupId: v.id("Group"),
+    domainId: v.id("EnterpriseDomain"),
+    domain: v.string(),
+    recordName: v.string(),
+    token: v.string(),
+    tokenHash: v.string(),
+    requestedAt: v.number(),
+    expiresAt: v.number(),
+  })
+    .index("enterprise_id", ["enterpriseId"])
+    .index("domain_id", ["domainId"])
+    .index("token_hash", ["tokenHash"]),
+
+  /**
+   * Encrypted enterprise secrets stored separately from protocol config.
+   */
+  EnterpriseSecret: defineTable({
+    enterpriseId: v.id("Enterprise"),
+    groupId: v.id("Group"),
+    kind: vEnterpriseSecretKind,
+    ciphertext: v.string(),
+    updatedAt: v.number(),
+  })
+    .index("enterprise_id", ["enterpriseId"])
+    .index("enterprise_id_kind", ["enterpriseId", "kind"])
+    .index("group_id", ["groupId"]),
+
+  /**
+   * SCIM configuration for an enterprise tenant.
+   */
+  EnterpriseScimConfig: defineTable({
+    enterpriseId: v.id("Enterprise"),
+    groupId: v.id("Group"),
+    status: vScimStatus,
+    basePath: v.string(),
+    tokenHash: v.string(),
+    lastRotatedAt: v.optional(v.number()),
+    extend: v.optional(v.any()),
+  })
+    .index("enterprise_id", ["enterpriseId"])
+    .index("group_id", ["groupId"])
+    .index("token_hash", ["tokenHash"])
+    .index("status", ["status"]),
+
+  /**
+   * External SCIM identities mapped into local users/groups.
+   */
+  EnterpriseScimIdentity: defineTable({
+    enterpriseId: v.id("Enterprise"),
+    groupId: v.id("Group"),
+    resourceType: vScimResourceType,
+    externalId: v.string(),
+    userId: v.optional(v.id("User")),
+    mappedGroupId: v.optional(v.id("Group")),
+    lastProvisionedAt: v.optional(v.number()),
+    active: v.optional(v.boolean()),
+    raw: v.optional(v.any()),
+  })
+    .index("enterprise_id", ["enterpriseId"])
+    .index("group_id", ["groupId"])
+    .index("enterprise_id_resource_type_external_id", [
+      "enterpriseId",
+      "resourceType",
+      "externalId",
+    ])
+    .index("enterprise_id_user_id", ["enterpriseId", "userId"])
+    .index("user_id", ["userId"])
+    .index("mapped_group_id", ["mappedGroupId"]),
+
+  /**
+   * Immutable audit trail for enterprise operations.
+   */
+  EnterpriseAuditEvent: defineTable({
+    enterpriseId: v.id("Enterprise"),
+    groupId: v.id("Group"),
+    eventType: v.string(),
+    actorType: vAuditActorType,
+    actorId: v.optional(v.string()),
+    subjectType: v.string(),
+    subjectId: v.optional(v.string()),
+    status: vAuditStatus,
+    occurredAt: v.number(),
+    requestId: v.optional(v.string()),
+    ip: v.optional(v.string()),
+    metadata: v.optional(v.any()),
+  })
+    .index("enterprise_id_occurred_at", ["enterpriseId", "occurredAt"])
+    .index("group_id_occurred_at", ["groupId", "occurredAt"])
+    .index("event_type_occurred_at", ["eventType", "occurredAt"]),
+
+  /**
+   * Webhook endpoints subscribed to enterprise audit and lifecycle events.
+   */
+  EnterpriseWebhookEndpoint: defineTable({
+    enterpriseId: v.id("Enterprise"),
+    groupId: v.id("Group"),
+    url: v.string(),
+    status: vWebhookEndpointStatus,
+    secretHash: v.string(),
+    subscriptions: v.array(v.string()),
+    createdByUserId: v.optional(v.id("User")),
+    lastSuccessAt: v.optional(v.number()),
+    lastFailureAt: v.optional(v.number()),
+    failureCount: v.number(),
+    extend: v.optional(v.any()),
+  })
+    .index("enterprise_id", ["enterpriseId"])
+    .index("group_id", ["groupId"])
+    .index("status", ["status"]),
+
+  /**
+   * Delivery queue for outbound enterprise webhooks.
+   */
+  EnterpriseWebhookDelivery: defineTable({
+    enterpriseId: v.id("Enterprise"),
+    endpointId: v.id("EnterpriseWebhookEndpoint"),
+    auditEventId: v.optional(v.id("EnterpriseAuditEvent")),
+    eventType: v.string(),
+    status: vWebhookDeliveryStatus,
+    attemptCount: v.number(),
+    nextAttemptAt: v.number(),
+    lastAttemptAt: v.optional(v.number()),
+    lastResponseStatus: v.optional(v.number()),
+    lastError: v.optional(v.string()),
+    payload: v.any(),
+  })
+    .index("enterprise_id", ["enterpriseId"])
+    .index("status_next_attempt_at", ["status", "nextAttemptAt"])
+    .index("endpoint_id_status", ["endpointId", "status"])
+    .index("audit_event_id", ["auditEventId"]),
 
   /**
    * API keys for programmatic access. Each key links a user to a set of
    * scoped permissions and optional per-key rate limiting.
    *
    * The raw key is never stored — only a SHA-256 hash. A short prefix
-   * (e.g. "sk_live_abc1...") is kept for display in admin interfaces.
+   * (e.g. "sk_abc1...") is kept for display in admin interfaces.
    *
    * Keys support:
    * - **Scoped permissions**: resource:action pairs (e.g. users:read)
@@ -291,42 +477,29 @@ export default defineSchema({
    * - **Expiration**: optional TTL
    * - **Soft revocation**: `revoked` flag preserves audit trail
    */
-  key: defineTable({
-    userId: v.id("user"),
-    /** First chars of the key for display (e.g. "sk_live_abc1..."). */
+  ApiKey: defineTable({
+    userId: v.id("User"),
+    /** First chars of the key for display (e.g. "sk_abc1..."). */
     prefix: v.string(),
     /** SHA-256 hex hash of the full raw key. */
     hashedKey: v.string(),
     /** User-assigned name (e.g. "CI Pipeline", "Production API"). */
     name: v.string(),
     /** Scoped permissions: [{ resource: "users", actions: ["read", "list"] }]. */
-    scopes: v.array(
-      v.object({
-        resource: v.string(),
-        actions: v.array(v.string()),
-      }),
-    ),
+    scopes: v.array(vApiKeyScope),
     /** Optional per-key rate limit configuration. */
-    rateLimit: v.optional(
-      v.object({
-        maxRequests: v.number(),
-        windowMs: v.number(),
-      }),
-    ),
+    rateLimit: v.optional(vApiKeyRateLimit),
     /** Rate limit state tracking (token-bucket). */
-    rateLimitState: v.optional(
-      v.object({
-        attemptsLeft: v.number(),
-        lastAttemptTime: v.number(),
-      }),
-    ),
+    rateLimitState: v.optional(vApiKeyRateLimitState),
     /** Expiration timestamp. Null/undefined = never expires. */
     expiresAt: v.optional(v.number()),
     lastUsedAt: v.optional(v.number()),
     createdAt: v.number(),
     /** Soft-revoke flag. Revoked keys are kept for audit trail. */
     revoked: v.boolean(),
+    /** Arbitrary app-specific metadata attached to the key. */
+    metadata: v.optional(v.any()),
   })
-    .index("userId", ["userId"])
-    .index("hashedKey", ["hashedKey"]),
+    .index("user_id", ["userId"])
+    .index("hashed_key", ["hashedKey"]),
 });

package/src/providers/anonymous.ts

@@ -10,11 +10,6 @@
  * @module
  */
 
-import { Credentials } from "./credentials";
-import type {
-  GenericActionCtxWithAuthConfig,
-  ConvexCredentialsConfig,
-} from "../server/types";
 import {
   DocumentByName,
   GenericDataModel,
@@ -22,6 +17,12 @@ import {
 } from "convex/server";
 import { Value } from "convex/values";
 
+import type {
+  GenericActionCtxWithAuthConfig,
+  ConvexCredentialsConfig,
+} from "../server/types";
+import { Credentials } from "./credentials";
+
 /**
  * The available options to an {@link Anonymous} provider for Convex Auth.
  */
@@ -45,7 +46,7 @@ export interface AnonymousConfig<DataModel extends GenericDataModel> {
      * the database.
      */
     ctx: GenericActionCtxWithAuthConfig<DataModel>,
-  ) => WithoutSystemFields<DocumentByName<DataModel, "user">> & {
+  ) => WithoutSystemFields<DocumentByName<DataModel, "User">> & {
     isAnonymous: true;
   };
 }
@@ -69,7 +70,9 @@ export class Anonymous<DataModel extends GenericDataModel = GenericDataModel> {
   readonly type = "credentials" as const;
   readonly config: AnonymousConfig<DataModel>;
 
-  constructor(config: AnonymousConfig<DataModel> = {} as AnonymousConfig<DataModel>) {
+  constructor(
+    config: AnonymousConfig<DataModel> = {} as AnonymousConfig<DataModel>,
+  ) {
     this.id = config.id ?? "anonymous";
     this.config = config;
   }
@@ -94,16 +97,3 @@ export class Anonymous<DataModel extends GenericDataModel = GenericDataModel> {
     })._toMaterialized();
   }
 }
-
-// ============================================================================
-// Backward-compatible default export
-// ============================================================================
-
-/**
- * @deprecated Use `new Anonymous(config)` instead.
- */
-export default function anonymous<DataModel extends GenericDataModel>(
-  config: AnonymousConfig<DataModel> = {} as AnonymousConfig<DataModel>,
-): ConvexCredentialsConfig {
-  return new Anonymous(config)._toMaterialized();
-}