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

package/src/server/types.ts

@@ -12,8 +12,17 @@ import {
   RegisteredQuery,
   TableNamesInDataModel,
 } from "convex/server";
+import type { Infer } from "convex/values";
 import { GenericId, Value } from "convex/values";
 
+import {
+  vApiKeyDoc,
+  vAuthVerifierDoc,
+  vDeviceCodeDoc,
+  vPasskeyDoc,
+  vTotpFactorDoc,
+  vUserDoc,
+} from "../component/model";
 import schema from "../component/schema";
 import { CredentialsUserConfig } from "../providers/credentials";
 
@@ -24,6 +33,30 @@ import { CredentialsUserConfig } from "../providers/credentials";
 /** A value that is either `T` or a `PromiseLike<T>`. */
 export type Awaitable<T> = T | PromiseLike<T>;
 
+export type AuthRoleDefinition = {
+  id?: string;
+  label?: string;
+  grants: string[];
+};
+
+export type AuthAuthorizationConfig = {
+  roles: Record<string, AuthRoleDefinition>;
+};
+
+export type AuthRoleId<
+  TAuthorization extends AuthAuthorizationConfig | undefined,
+> = TAuthorization extends { roles: infer TRoles extends Record<string, any> }
+  ? keyof TRoles & string
+  : string;
+
+export type AuthGrant<
+  TAuthorization extends AuthAuthorizationConfig | undefined,
+> = TAuthorization extends {
+  roles: infer TRoles extends Record<string, { grants: readonly any[] }>;
+}
+  ? TRoles[keyof TRoles]["grants"][number] & string
+  : string;
+
 /**
  * The config for the Convex Auth library, passed to `createAuth`.
  */
@@ -238,6 +271,18 @@ export type ConvexAuthConfig = {
       },
     ) => Promise<void>;
   };
+  /**
+   * Application-defined role and grant model used by membership access checks.
+   */
+  authorization?: {
+    roles: Record<
+      string,
+      {
+        label?: string;
+        grants: string[];
+      }
+    >;
+  };
 };
 
 /**
@@ -282,6 +327,62 @@ export interface SSOProviderConfig {
   type: "sso";
 }
 
+export type EnterpriseAccountLinkingPolicy = "verifiedEmail" | "none";
+
+export type EnterpriseScimReuseUserPolicy = "externalId" | "none";
+
+export type EnterpriseJitProvisioningMode =
+  | "off"
+  | "createUser"
+  | "createUserAndMembership";
+
+export type EnterpriseDeprovisionMode = "soft" | "hard";
+
+export interface EnterprisePolicy {
+  version: 1;
+  identity: {
+    accountLinking: {
+      oidc: EnterpriseAccountLinkingPolicy;
+      saml: EnterpriseAccountLinkingPolicy;
+    };
+  };
+  provisioning: {
+    scimReuse: {
+      user: EnterpriseScimReuseUserPolicy;
+    };
+    jit: {
+      mode: EnterpriseJitProvisioningMode;
+      defaultRoleIds: string[];
+    };
+    deprovision: {
+      mode: EnterpriseDeprovisionMode;
+    };
+  };
+  extend?: Record<string, unknown>;
+}
+
+export interface EnterprisePolicyPatch {
+  identity?: {
+    accountLinking?: {
+      oidc?: EnterpriseAccountLinkingPolicy;
+      saml?: EnterpriseAccountLinkingPolicy;
+    };
+  };
+  provisioning?: {
+    scimReuse?: {
+      user?: EnterpriseScimReuseUserPolicy;
+    };
+    jit?: {
+      mode?: EnterpriseJitProvisioningMode;
+      defaultRoleIds?: string[];
+    };
+    deprovision?: {
+      mode?: EnterpriseDeprovisionMode;
+    };
+  };
+  extend?: Record<string, unknown>;
+}
+
 /**
  * Email provider config for magic link / OTP sign-in.
  */
@@ -567,6 +668,7 @@ export type AuthServerHelpers = {
       ctx: GenericActionCtx<any>,
       args: AuthCreateAccountArgs,
     ) => Promise<{
+      ok: true;
       account: GenericDoc<GenericDataModel, "Account">;
       user: GenericDoc<GenericDataModel, "User">;
     }>;
@@ -580,7 +682,7 @@ export type AuthServerHelpers = {
     update: (
       ctx: GenericActionCtx<any>,
       args: AuthUpdateAccountArgs,
-    ) => Promise<void>;
+    ) => Promise<{ ok: true; accountId: GenericId<"Account"> }>;
   };
   session: {
     current: (ctx: {
@@ -589,7 +691,32 @@ export type AuthServerHelpers = {
     invalidate: (
       ctx: GenericActionCtx<any>,
       args: AuthInvalidateSessionsArgs,
-    ) => Promise<void>;
+    ) => Promise<{
+      ok: true;
+      userId: GenericId<"User">;
+      except: GenericId<"Session">[];
+    }>;
+  };
+  access: {
+    check: (
+      ctx: GenericActionCtx<any>,
+      args: {
+        userId: GenericId<"User">;
+        groupId: GenericId<"Group">;
+        grants: string[];
+        maxDepth?: number;
+      },
+    ) => Promise<{
+      ok: boolean;
+      grants: string[];
+      missingGrants: string[];
+      roleIds: string[];
+      matchedGroupId: GenericId<"Group"> | null;
+      membership: GenericDoc<GenericDataModel, "GroupMember"> | null;
+      isDirect: boolean;
+      isInherited: boolean;
+      depth: number | null;
+    }>;
   };
   provider: {
     signIn: (
@@ -621,7 +748,7 @@ export type ConvexAuthMaterializedConfig = {
   providers: AuthProviderMaterializedConfig[];
 } & Pick<
   ConvexAuthConfig,
-  "component" | "session" | "jwt" | "signIn" | "callbacks"
+  "component" | "session" | "jwt" | "signIn" | "callbacks" | "authorization"
 >;
 
 export interface SAMLAttributeMapping {
@@ -857,12 +984,12 @@ export type GroupOrderBy = "_creationTime" | "name" | "slug" | "type";
 export type MemberWhere = {
   groupId?: string;
   userId?: string;
-  role?: string;
+  roleId?: string;
   status?: string;
 };
 
 /** Sortable fields for `auth.member.list()`. */
-export type MemberOrderBy = "_creationTime" | "role" | "status";
+export type MemberOrderBy = "_creationTime" | "status";
 
 /** Filter fields for `auth.invite.list()`. All optional. */
 export type InviteWhere = {
@@ -871,7 +998,7 @@ export type InviteWhere = {
   status?: "pending" | "accepted" | "revoked" | "expired";
   email?: string;
   invitedByUserId?: string;
-  role?: string;
+  roleId?: string;
   acceptedByUserId?: string;
 };
 
@@ -1055,6 +1182,28 @@ export type AuthComponentApi = {
     enterpriseDomainAdd: FunctionReference<"mutation", "internal", any, any>;
     enterpriseDomainList: FunctionReference<"query", "internal", any, any>;
     enterpriseDomainDelete: FunctionReference<"mutation", "internal", any, any>;
+    enterpriseDomainVerificationGet: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseDomainVerificationUpsert: FunctionReference<
+      "mutation",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseDomainVerificationDelete: FunctionReference<
+      "mutation",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseDomainVerify: FunctionReference<"mutation", "internal", any, any>;
+    enterpriseSecretUpsert: FunctionReference<"mutation", "internal", any, any>;
+    enterpriseSecretGet: FunctionReference<"query", "internal", any, any>;
+    enterpriseSecretDelete: FunctionReference<"mutation", "internal", any, any>;
     enterpriseScimConfigUpsert: FunctionReference<
       "mutation",
       "internal",
@@ -1080,6 +1229,12 @@ export type AuthComponentApi = {
       any,
       any
     >;
+    enterpriseScimIdentityGetByEnterpriseAndUser: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
     enterpriseScimIdentityGetByMappedGroup: FunctionReference<
       "query",
       "internal",
@@ -1123,6 +1278,12 @@ export type AuthComponentApi = {
       any,
       any
     >;
+    enterpriseWebhookEndpointGet: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
     enterpriseWebhookEndpointUpdate: FunctionReference<
       "mutation",
       "internal",
@@ -1243,80 +1404,25 @@ export type SessionInfoWithTokens = {
 // code can work with typed results from cross-component queries/mutations
 // instead of casting to `any` at every field access.
 
-export interface TotpDoc {
-  _id: string;
-  _creationTime: number;
-  userId: string;
-  secret: ArrayBuffer;
-  digits: number;
-  period: number;
-  verified: boolean;
-  name?: string;
-  createdAt: number;
-  lastUsedAt?: number;
-}
+export type TotpDoc = Infer<typeof vTotpFactorDoc>;
 
-export interface PasskeyDoc {
-  _id: string;
-  _creationTime: number;
-  userId: string;
-  credentialId: string;
-  publicKey: ArrayBuffer;
-  algorithm: number;
-  counter: number;
-  transports?: string[];
-  deviceType: string;
-  backedUp: boolean;
-  name?: string;
-  createdAt: number;
-  lastUsedAt?: number;
-}
+export type PasskeyDoc = Infer<typeof vPasskeyDoc>;
 
-export interface VerifierDoc {
-  _id: string;
-  _creationTime: number;
-  signature?: string;
-  sessionId?: string;
-}
+export type VerifierDoc = Infer<typeof vAuthVerifierDoc>;
 
 /**
- * Plain cross-component user document shape with `string` IDs.
+ * Cross-component user document shape inferred from the component validator.
  *
- * Used by internal typed wrappers (`queryUserById`, etc.) that operate
- * across the component boundary where Convex `Id<"User">` is erased
- * to a plain string. Not intended for consumer use — consumers should
- * use `UserDoc` (exported from `@robelest/convex-auth/component`)
- * which preserves typed `Id<"User">`.
+ * Used by internal typed wrappers (`queryUserById`, etc.) so server code stays
+ * aligned with the component runtime contract. Not intended for consumer use —
+ * consumers should use `UserDoc` (exported from
+ * `@robelest/convex-auth/component`).
  *
  * @internal
  */
-export interface CrossComponentUserDoc {
-  _id: string;
-  _creationTime: number;
-  email?: string;
-  emailVerificationTime?: number;
-  phone?: string;
-  phoneVerificationTime?: number;
-  name?: string;
-  image?: string;
-  isAnonymous?: boolean;
-}
+export type CrossComponentUserDoc = Infer<typeof vUserDoc>;
 
-export interface KeyDoc {
-  _id: string;
-  _creationTime: number;
-  userId: string;
-  prefix: string;
-  hashedKey: string;
-  name: string;
-  scopes: Array<{ resource: string; actions: string[] }>;
-  rateLimit?: { maxRequests: number; windowMs: number };
-  rateLimitState?: { attemptsLeft: number; lastAttemptTime: number };
-  expiresAt?: number;
-  lastUsedAt?: number;
-  createdAt: number;
-  revoked: boolean;
-}
+export type KeyDoc = Infer<typeof vApiKeyDoc>;
 
 // ---------------------------------------------------------------------------
 // Cross-component wrapper context
@@ -1555,18 +1661,7 @@ export async function mutateKeyDelete(
 
 // -- Device authorization queries / mutations --
 
-export interface DeviceDoc {
-  _id: string;
-  _creationTime: number;
-  deviceCodeHash: string;
-  userCode: string;
-  expiresAt: number;
-  interval: number;
-  status: "pending" | "authorized" | "denied";
-  userId?: string;
-  sessionId?: string;
-  lastPolledAt?: number;
-}
+export type DeviceDoc = Infer<typeof vDeviceCodeDoc>;
 
 export async function mutateDeviceInsert(
   ctx: ComponentCallCtx,

package/src/server/users.ts

@@ -37,6 +37,7 @@ function mergeExtend(
   return existingRecord ? { ...existingRecord, ...incoming } : incoming;
 }
 
+/** @internal */
 export async function upsertUserAndAccount(
   ctx: MutationCtx,
   sessionId: GenericId<"Session"> | null,

package/src/server/utils.ts

@@ -3,7 +3,11 @@ import {
   generateRandomString as osloGenerateRandomString,
 } from "@oslojs/crypto/random";
 import { sha256 as rawSha256 } from "@oslojs/crypto/sha2";
-import { encodeHexLowerCase } from "@oslojs/encoding";
+import {
+  decodeBase64urlIgnorePadding,
+  encodeBase64urlNoPadding,
+  encodeHexLowerCase,
+} from "@oslojs/encoding";
 
 import { AuthError } from "./fx";
 
@@ -13,6 +17,7 @@ import { AuthError } from "./fx";
  * Uses `AuthError.toConvexError()` directly since this is a synchronous guard
  * called inline in many expressions — not suitable for Fx pipeline wrapping.
  */
+/** @internal */
 export function requireEnv(name: string) {
   const value = process.env[name];
   if (value === undefined) {
@@ -25,6 +30,7 @@ export function requireEnv(name: string) {
   return value;
 }
 
+/** @internal */
 export function isLocalHost(host?: string) {
   if (host === undefined) {
     return false;
@@ -45,13 +51,17 @@ export function isLocalHost(host?: string) {
 
 // Internal server utilities (merged from former internalUtils.ts)
 
+/** @internal */
 export const TOKEN_SUB_CLAIM_DIVIDER = "|";
+/** @internal */
 export const REFRESH_TOKEN_DIVIDER = "|";
 
+/** @internal */
 export async function sha256(input: string) {
   return encodeHexLowerCase(rawSha256(new TextEncoder().encode(input)));
 }
 
+/** @internal */
 export function generateRandomString(length: number, alphabet: string) {
   const random: RandomReader = {
     read(bytes) {
@@ -62,10 +72,12 @@ export function generateRandomString(length: number, alphabet: string) {
   return osloGenerateRandomString(random, alphabet, length);
 }
 
+/** @internal */
 export function errorMessage(error: unknown) {
   return error instanceof Error ? error.message : String(error);
 }
 
+/** @internal */
 export function logError(error: unknown) {
   logWithLevel(
     LOG_LEVELS.ERROR,
@@ -75,6 +87,7 @@ export function logError(error: unknown) {
   );
 }
 
+/** @internal */
 export const LOG_LEVELS = {
   ERROR: "ERROR",
   WARN: "WARN",
@@ -83,6 +96,7 @@ export const LOG_LEVELS = {
 } as const;
 type LogLevel = keyof typeof LOG_LEVELS;
 
+/** @internal */
 export function logWithLevel(level: LogLevel, ...args: unknown[]) {
   const configuredLogLevel =
     LOG_LEVELS[
@@ -111,6 +125,7 @@ export function logWithLevel(level: LogLevel, ...args: unknown[]) {
 }
 
 const UNREDACTED_LENGTH = 5;
+/** @internal */
 export function maybeRedact(value: string) {
   if (value === "") {
     return "";
@@ -129,3 +144,58 @@ export function maybeRedact(value: string) {
     return value;
   }
 }
+
+const SECRET_KEY_ENV = "AUTH_SECRET_ENCRYPTION_KEY";
+const SECRET_IV_LENGTH = 12;
+
+function toArrayBuffer(bytes: Uint8Array) {
+  return bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength,
+  ) as ArrayBuffer;
+}
+
+async function getSecretCryptoKey() {
+  const material = requireEnv(SECRET_KEY_ENV);
+  const rawKey = rawSha256(new TextEncoder().encode(material));
+  return await crypto.subtle.importKey(
+    "raw",
+    toArrayBuffer(rawKey),
+    { name: "AES-GCM" },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+/** @internal */
+export async function encryptSecret(value: string) {
+  const key = await getSecretCryptoKey();
+  const iv = crypto.getRandomValues(new Uint8Array(SECRET_IV_LENGTH));
+  const encrypted = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv: toArrayBuffer(iv) },
+    key,
+    toArrayBuffer(new TextEncoder().encode(value)),
+  );
+  return `${encodeBase64urlNoPadding(iv)}.${encodeBase64urlNoPadding(new Uint8Array(encrypted))}`;
+}
+
+/** @internal */
+export async function decryptSecret(ciphertext: string) {
+  const [ivEncoded, payloadEncoded] = ciphertext.split(".");
+  if (!ivEncoded || !payloadEncoded) {
+    throw new AuthError(
+      "INVALID_PARAMETERS",
+      "Stored enterprise secret is malformed.",
+    ).toConvexError();
+  }
+  const key = await getSecretCryptoKey();
+  const decrypted = await crypto.subtle.decrypt(
+    {
+      name: "AES-GCM",
+      iv: toArrayBuffer(decodeBase64urlIgnorePadding(ivEncoded)),
+    },
+    key,
+    toArrayBuffer(decodeBase64urlIgnorePadding(payloadEncoded)),
+  );
+  return new TextDecoder().decode(decrypted);
+}

package/src/server/version.ts

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/generate-version.js — do not edit.
-export const AUTH_VERSION = "0.0.4-preview.13";
+export const AUTH_VERSION = "0.0.4-preview.16";