@estifanos-sh/convex-auth 0.0.1-preview.0

package/dist/providers/webauthn/attestation.js

@@ -0,0 +1,167 @@
+import { MetadataService, verifyRegistrationResponse } from "@simplewebauthn/server";
+import { decodeAttestationObject, isoBase64URL, verifyMDSBlob } from "@simplewebauthn/server/helpers";
+
+//#region src/providers/webauthn/attestation.ts
+/**
+* Trusted WebAuthn attestation policies.
+*
+* @module
+*/
+const FIDO_MDS_URL = "https://mds.fidoalliance.org/";
+const FIDO_MDS_VERIFIER = "fido-mds-v3";
+const AAGUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const ZERO_AAGUID = "00000000-0000-0000-0000-000000000000";
+const REJECTED_AUTHENTICATOR_STATUSES = new Set([
+	"REVOKED",
+	"USER_VERIFICATION_BYPASS",
+	"ATTESTATION_KEY_COMPROMISE",
+	"USER_KEY_REMOTE_COMPROMISE",
+	"USER_KEY_PHYSICAL_COMPROMISE"
+]);
+const CERTIFIED_AUTHENTICATOR_STATUSES = new Set([
+	"FIDO_CERTIFIED",
+	"FIDO_CERTIFIED_L1",
+	"FIDO_CERTIFIED_L1plus",
+	"FIDO_CERTIFIED_L2",
+	"FIDO_CERTIFIED_L2plus",
+	"FIDO_CERTIFIED_L3",
+	"FIDO_CERTIFIED_L3plus"
+]);
+let cachedMetadata;
+let metadataLoad;
+function normalizeAaguid(value) {
+	const normalized = value.trim().toLowerCase();
+	if (!AAGUID_PATTERN.test(normalized)) throw new Error(`Invalid AAGUID: ${value}`);
+	return normalized;
+}
+function normalizeAllowedAaguids(values) {
+	if (values === void 0) return null;
+	if (values.length === 0) throw new Error("fidoMds allowedAaguids must contain at least one AAGUID when provided.");
+	return new Set(values.map(normalizeAaguid));
+}
+/** @internal */
+function assertTrustedMetadataEntry(entry) {
+	if (!entry?.aaguid || !entry.metadataStatement) throw new Error("Authenticator is not present in the verified FIDO Metadata Service.");
+	const rejected = entry.statusReports.find((report) => REJECTED_AUTHENTICATOR_STATUSES.has(report.status));
+	if (rejected) throw new Error(`Authenticator metadata status is ${rejected.status}.`);
+	if (!entry.statusReports.some((report) => CERTIFIED_AUTHENTICATOR_STATUSES.has(report.status))) throw new Error("Authenticator does not have a current FIDO certification status.");
+}
+/** @internal */
+function assertFullAttestation(attestationObject) {
+	const decoded = decodeAttestationObject(isoBase64URL.toBuffer(attestationObject));
+	const format = decoded.get("fmt");
+	const statement = decoded.get("attStmt");
+	if (format === "none") throw new Error("Authenticator did not return an attestation statement.");
+	if (format === "fido-u2f") throw new Error("Legacy FIDO U2F attestation has no model AAGUID and cannot satisfy this policy.");
+	if (!statement.get("x5c")?.length) throw new Error("Self or anonymous attestation is not trusted by this policy.");
+}
+async function loadFidoMetadata() {
+	const response = await fetch(FIDO_MDS_URL);
+	if (!response.ok) throw new Error(`FIDO Metadata Service returned HTTP ${response.status}.`);
+	const verified = await verifyMDSBlob(await response.text());
+	await MetadataService.initialize({
+		mdsServers: [],
+		statements: verified.statements,
+		verificationMode: "strict"
+	});
+	const entries = /* @__PURE__ */ new Map();
+	for (const entry of verified.payload.entries) if (entry.aaguid) entries.set(normalizeAaguid(entry.aaguid), entry);
+	return {
+		entries,
+		nextUpdate: verified.parsedNextUpdate.getTime()
+	};
+}
+async function getFidoMetadata() {
+	if (cachedMetadata && Date.now() < cachedMetadata.nextUpdate) return cachedMetadata;
+	metadataLoad ??= loadFidoMetadata().then((metadata) => {
+		cachedMetadata = metadata;
+		return metadata;
+	}).finally(() => {
+		metadataLoad = void 0;
+	});
+	return await metadataLoad;
+}
+function assertAllowedAaguid(aaguid, allowed) {
+	if (aaguid === ZERO_AAGUID) throw new Error("Authenticator did not provide a model-specific AAGUID.");
+	if (allowed && !allowed.has(aaguid)) throw new Error(`Authenticator AAGUID ${aaguid} is not allowed by this policy.`);
+}
+async function verifyWithFidoMds(input, allowed) {
+	assertFullAttestation(input.attestationObject);
+	const metadata = await getFidoMetadata();
+	const result = await verifyRegistrationResponse({
+		response: {
+			id: input.credentialId,
+			rawId: input.credentialId,
+			type: "public-key",
+			response: {
+				clientDataJSON: input.clientDataJSON,
+				attestationObject: input.attestationObject,
+				...input.transports ? { transports: input.transports } : {}
+			},
+			clientExtensionResults: {}
+		},
+		expectedChallenge: input.expectedChallenge,
+		expectedOrigin: input.expectedOrigin,
+		expectedRPID: input.expectedRpId,
+		requireUserPresence: true,
+		requireUserVerification: input.requireUserVerification,
+		supportedAlgorithmIDs: input.supportedAlgorithms
+	});
+	if (!result.verified) throw new Error("Authenticator attestation verification failed.");
+	const aaguid = normalizeAaguid(result.registrationInfo.aaguid);
+	assertAllowedAaguid(aaguid, allowed);
+	const entry = metadata.entries.get(aaguid);
+	assertTrustedMetadataEntry(entry);
+	return {
+		aaguid,
+		format: result.registrationInfo.fmt,
+		metadataDescription: entry?.metadataStatement?.description
+	};
+}
+/**
+* Require full manufacturer attestation verified against FIDO Metadata
+* Service v3. Missing, self, anonymous, unknown, revoked, compromised, and
+* optionally non-allow-listed authenticators are rejected.
+*
+* The metadata blob, signature, certificate path, and status reports are
+* refreshed from the official FIDO service. A metadata outage therefore fails
+* registration and strict sign-in closed.
+*
+* @param options - Optional authenticator model allow list.
+* @returns A strict policy for `webauthn({ registration: { attestation } })`.
+*
+* @example
+* ```ts
+* import { webauthn } from "@estifanos-sh/convex-auth/providers";
+*
+* webauthn({
+*   registration: {
+*     authenticatorAttachment: "cross-platform",
+*     hints: ["security-key"],
+*     attestation: webauthn.attestation.fidoMds({
+*       allowedAaguids: ["2fc0579f-8113-47ea-b116-bb5a8db9202a"],
+*     }),
+*   },
+* });
+* ```
+*/
+function fidoMds(options = {}) {
+	const allowed = normalizeAllowedAaguids(options.allowedAaguids);
+	return {
+		conveyance: "direct",
+		verifier: {
+			id: FIDO_MDS_VERIFIER,
+			verify: async (input) => await verifyWithFidoMds(input, allowed),
+			assertTrusted: async (evidence) => {
+				if (evidence.status !== "trusted" || evidence.verifier !== FIDO_MDS_VERIFIER) throw new Error("Credential has no trusted FIDO MDS attestation evidence.");
+				const aaguid = normalizeAaguid(evidence.aaguid);
+				assertAllowedAaguid(aaguid, allowed);
+				assertTrustedMetadataEntry((await getFidoMetadata()).entries.get(aaguid));
+			}
+		}
+	};
+}
+
+//#endregion
+export { assertFullAttestation, assertTrustedMetadataEntry, fidoMds };
+//# sourceMappingURL=attestation.js.map

package/dist/providers/webauthn.d.ts

@@ -0,0 +1,83 @@
+import { WebAuthnAttestationEvidence, WebAuthnAttestationPolicy, WebAuthnProviderConfig } from "../server/types.js";
+import { fidoMds } from "./webauthn/attestation.js";
+
+//#region src/providers/webauthn.d.ts
+/** WebAuthn Level 3 hints that browsers may use to guide authenticator selection. */
+type WebAuthnHint = "security-key" | "client-device" | "hybrid";
+/** COSE algorithms supported by the WebAuthn verifier. */
+type WebAuthnAlgorithm = -7 | -257;
+/** Registration-ceremony options for the {@link webauthn} provider. */
+interface WebAuthnRegistrationConfig {
+  /** Restrict registration to platform or roaming authenticators. */
+  authenticatorAttachment?: "platform" | "cross-platform";
+  /** Discoverable credential preference. */
+  residentKey?: "required" | "preferred" | "discouraged";
+  /** User verification requirement for registration. */
+  userVerification?: "required" | "preferred" | "discouraged";
+  /** Non-binding hints used by supporting browsers to guide authenticator selection. */
+  hints?: readonly WebAuthnHint[];
+  /** Supported COSE algorithms in authenticator preference order. */
+  algorithms?: readonly WebAuthnAlgorithm[];
+  /**
+   * Strict authenticator-attestation policy. When present, registration and
+   * every later sign-in fail unless the credential has current trusted
+   * evidence from this policy.
+   */
+  attestation?: WebAuthnAttestationPolicy;
+}
+/** Authentication-ceremony options for the {@link webauthn} provider. */
+interface WebAuthnAuthenticationConfig {
+  /** User verification requirement for authentication. */
+  userVerification?: "required" | "preferred" | "discouraged";
+  /** Non-binding hints used by supporting browsers to guide authenticator selection. */
+  hints?: readonly WebAuthnHint[];
+}
+/** Configuration for the {@link webauthn} provider. */
+interface WebAuthnConfig {
+  /** Human-readable relying party name shown in authenticator prompts. */
+  rpName?: string;
+  /** Relying party ID, typically your app's hostname. */
+  rpId?: string;
+  /** Allowed origins for registration and authentication ceremonies. */
+  origin?: string | readonly string[];
+  /** Challenge lifetime in milliseconds before a ceremony expires. */
+  challengeExpirationMs?: number;
+  /** Credential-creation ceremony options. */
+  registration?: WebAuthnRegistrationConfig;
+  /** Credential-authentication ceremony options. */
+  authentication?: WebAuthnAuthenticationConfig;
+}
+/**
+ * Create a WebAuthn provider.
+ *
+ * @param config - Optional relying-party and ceremony-specific settings.
+ * @returns A configured WebAuthn provider for `defineAuth`.
+ *
+ * @example
+ * ```ts
+ * import { webauthn } from "@estifanos-sh/convex-auth/providers";
+ *
+ * webauthn({
+ *   rpName: "Staff access",
+ *   registration: {
+ *     authenticatorAttachment: "cross-platform",
+ *     residentKey: "discouraged",
+ *     userVerification: "required",
+ *     hints: ["security-key"],
+ *     attestation: webauthn.attestation.fidoMds(),
+ *   },
+ *   authentication: {
+ *     userVerification: "required",
+ *     hints: ["security-key"],
+ *   },
+ * })
+ * ```
+ */
+declare const webauthn: ((config?: WebAuthnConfig) => WebAuthnProviderConfig) & {
+  /** WebAuthn attestation policies. */attestation: Readonly<{
+    fidoMds: typeof fidoMds;
+  }>;
+};
+//#endregion
+export { WebAuthnAlgorithm, type WebAuthnAttestationEvidence, type WebAuthnAttestationPolicy, WebAuthnAuthenticationConfig, WebAuthnConfig, WebAuthnHint, WebAuthnRegistrationConfig, webauthn };
+//# sourceMappingURL=webauthn.d.ts.map

package/dist/providers/webauthn.js

@@ -0,0 +1,57 @@
+import { fidoMds } from "./webauthn/attestation.js";
+
+//#region src/providers/webauthn.ts
+/**
+* Create a WebAuthn provider.
+*
+* @param config - Optional relying-party and ceremony-specific settings.
+* @returns A configured WebAuthn provider for `defineAuth`.
+*
+* @example
+* ```ts
+* import { webauthn } from "@estifanos-sh/convex-auth/providers";
+*
+* webauthn({
+*   rpName: "Staff access",
+*   registration: {
+*     authenticatorAttachment: "cross-platform",
+*     residentKey: "discouraged",
+*     userVerification: "required",
+*     hints: ["security-key"],
+*     attestation: webauthn.attestation.fidoMds(),
+*   },
+*   authentication: {
+*     userVerification: "required",
+*     hints: ["security-key"],
+*   },
+* })
+* ```
+*/
+const webauthn = Object.assign(function webauthn(config = {}) {
+	return {
+		id: "webauthn",
+		type: "webauthn",
+		options: {
+			rpName: config.rpName,
+			rpId: config.rpId,
+			origin: typeof config.origin === "string" ? config.origin : config.origin ? [...config.origin] : void 0,
+			challengeExpirationMs: config.challengeExpirationMs ?? 3e5,
+			registration: {
+				residentKey: config.registration?.residentKey ?? "preferred",
+				userVerification: config.registration?.userVerification ?? "required",
+				algorithms: [...config.registration?.algorithms ?? [-7, -257]],
+				...config.registration?.authenticatorAttachment ? { authenticatorAttachment: config.registration.authenticatorAttachment } : {},
+				...config.registration?.hints ? { hints: [...config.registration.hints] } : {},
+				...config.registration?.attestation ? { attestation: config.registration.attestation } : {}
+			},
+			authentication: {
+				userVerification: config.authentication?.userVerification ?? "required",
+				...config.authentication?.hints ? { hints: [...config.authentication.hints] } : {}
+			}
+		}
+	};
+}, { attestation: Object.freeze({ fidoMds }) });
+
+//#endregion
+export { webauthn };
+//# sourceMappingURL=webauthn.js.map

package/dist/react/index.d.ts

@@ -0,0 +1,55 @@
+import { AuthApiRefs, AuthState, PlatformAuthClient, SignInOverloads } from "../client/core/types.js";
+import "../browser/index.js";
+import { ReactElement, ReactNode } from "react";
+
+//#region src/react/index.d.ts
+type AnyAuthClient = PlatformAuthClient<AuthApiRefs<boolean, boolean, boolean>>;
+/** Provide an app-owned auth client to descendants. */
+declare function ConvexAuthProvider({
+  auth,
+  children
+}: {
+  auth: AnyAuthClient;
+  children: ReactNode;
+}): ReactElement;
+/** Read the current auth state. Throws if no {@link ConvexAuthProvider} is above. */
+declare function useAuth(): AuthState;
+/** Render children only when signed in; supports a render prop receiving the JWT. */
+declare function SignedIn({
+  children
+}: {
+  children: ReactNode | ((token: string) => ReactNode);
+}): ReactElement | null;
+/** Render children only when signed out. */
+declare function SignedOut({
+  children
+}: {
+  children: ReactNode;
+}): ReactElement | null;
+/**
+ * Render children only while auth is still resolving or Convex is confirming a
+ * stored token.
+ */
+declare function AuthLoading({
+  children
+}: {
+  children: ReactNode;
+}): ReactElement | null;
+/**
+ * The auth actions (`signIn`, `signOut`), always callable. Throws if no
+ * {@link ConvexAuthProvider} is above — matching Svelte's non-nullable
+ * `signIn`/`signOut`, so callers never have to null-check the actions.
+ */
+declare function useAuthActions(): {
+  signIn: SignInOverloads;
+  signOut: () => Promise<void>;
+};
+/**
+ * The underlying imperative client, for factor flows (`client.totp.*`,
+ * `client.webauthn.*`, `client.device.*`) and low-level methods (`completeOAuth`,
+ * `param`, `initialize`). Throws if no {@link ConvexAuthProvider} is above.
+ */
+declare function useConvexAuthClient(): AnyAuthClient;
+//#endregion
+export { AuthLoading, ConvexAuthProvider, SignedIn, SignedOut, useAuth, useAuthActions, useConvexAuthClient };
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.js

@@ -0,0 +1,80 @@
+"use client";
+
+import { createContext, useCallback, useContext, useSyncExternalStore } from "react";
+import { Fragment, jsx } from "react/jsx-runtime";
+
+//#region src/react/index.tsx
+/**
+* React bindings for `@estifanos-sh/convex-auth/react`.
+*
+* @module
+*/
+const AuthClientContext = createContext(null);
+/** Provide an app-owned auth client to descendants. */
+function ConvexAuthProvider({ auth, children }) {
+	return /* @__PURE__ */ jsx(AuthClientContext.Provider, {
+		value: auth,
+		children
+	});
+}
+const NO_PROVIDER_MESSAGE = "No auth client found. Wrap the component tree in <ConvexAuthProvider auth={...}> before using the auth hooks.";
+/**
+* Read the app-owned auth client from context, throwing a clear error when no
+* {@link ConvexAuthProvider} is above. Failing fast on a missing provider — the
+* same contract as Svelte's `useConvexAuth()` — is far easier to debug than a
+* silent, perpetual `loading` state, and lets the hooks return non-nullable
+* values so callers never have to guard against an absent client.
+*/
+function useAuthClientOrThrow() {
+	const client = useContext(AuthClientContext);
+	if (client === null) throw new Error(NO_PROVIDER_MESSAGE);
+	return client;
+}
+/** Read the current auth state. Throws if no {@link ConvexAuthProvider} is above. */
+function useAuth() {
+	const client = useAuthClientOrThrow();
+	const subscribe = useCallback((onStoreChange) => client.subscribe(onStoreChange), [client]);
+	const getSnapshot = useCallback(() => client.getSnapshot(), [client]);
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+/** Render children only when signed in; supports a render prop receiving the JWT. */
+function SignedIn({ children }) {
+	const state = useAuth();
+	if (state.status !== "signedIn") return null;
+	return /* @__PURE__ */ jsx(Fragment, { children: typeof children === "function" ? children(state.token) : children });
+}
+/** Render children only when signed out. */
+function SignedOut({ children }) {
+	return useAuth().status === "signedOut" ? /* @__PURE__ */ jsx(Fragment, { children }) : null;
+}
+/**
+* Render children only while auth is still resolving or Convex is confirming a
+* stored token.
+*/
+function AuthLoading({ children }) {
+	return useAuth().status === "loading" ? /* @__PURE__ */ jsx(Fragment, { children }) : null;
+}
+/**
+* The auth actions (`signIn`, `signOut`), always callable. Throws if no
+* {@link ConvexAuthProvider} is above — matching Svelte's non-nullable
+* `signIn`/`signOut`, so callers never have to null-check the actions.
+*/
+function useAuthActions() {
+	const client = useAuthClientOrThrow();
+	return {
+		signIn: client.signIn,
+		signOut: client.signOut
+	};
+}
+/**
+* The underlying imperative client, for factor flows (`client.totp.*`,
+* `client.webauthn.*`, `client.device.*`) and low-level methods (`completeOAuth`,
+* `param`, `initialize`). Throws if no {@link ConvexAuthProvider} is above.
+*/
+function useConvexAuthClient() {
+	return useAuthClientOrThrow();
+}
+
+//#endregion
+export { AuthLoading, ConvexAuthProvider, SignedIn, SignedOut, useAuth, useAuthActions, useConvexAuthClient };
+//# sourceMappingURL=index.js.map