feat(core): add credentials sign-in provider

packages/core/src/@types/config.ts

@@ -9,6 +9,45 @@ import type { EditableShape, Prettify, ShapeToObject } from "@/@types/utility.ts
 import type { OAuthProviderCredentials, OAuthProviderRecord } from "@/@types/oauth.ts"
 import type { JWTKey, SessionConfig, SessionStrategy, User, UserShape } from "@/@types/session.ts"
 
+export interface CredentialsPayload {
+    username: string
+    password: string
+}
+
+/**
+ * Context provided to the credentials provider's authorize function.
+ * It includes the credentials sent by the user and hashing utilities.
+ */
+export interface CredentialsProviderContext<T> {
+    /**
+     * User-provided credentials (e.g., email, password).
+     */
+    credentials: T
+    /**
+     * Hashes a password using the internal hashing algorithm (PBKDF2).
+     */
+    deriveSecret: (password: string, salt?: string, iterations?: number) => Promise<string>
+    /**
+     * Verifies a password against a hashed value.
+     */
+    verifySecret: (password: string, hashedPassword: string) => Promise<boolean>
+}
+
+/**
+ * Interface for the credentials provider.
+ */
+export interface CredentialsProvider<Identity extends EditableShape<UserShape> = EditableShape<UserShape>> {
+    hash?: (password: string, salt?: string, iterations?: number) => Promise<string>
+    verify?: (password: string, hashedPassword: string) => Promise<boolean>
+    /**
+     * Authenticates a user using credentials.
+     * Must return a User object or the identity type if the identity schema is provided.
+     */
+    authorize: (
+        ctx: CredentialsProviderContext<CredentialsPayload>
+    ) => Promise<ShapeToObject<Identity> | null> | ShapeToObject<Identity> | null
+}
+
 /**
  * Main configuration interface for Aura Auth.
  * This is the user-facing configuration object passed to `createAuth()`.
@@ -149,6 +188,10 @@ export interface AuthConfig<Identity extends EditableShape<UserShape> = Editable
         schema: ZodObject<Identity>
         unknownKeys: "passthrough" | "strict" | "strip"
     }>
+    /**
+     * Credentials provider for username/password or similar authentication.
+     */
+    credentials?: CredentialsProvider<Identity>
 }
 
 /**
@@ -254,6 +297,7 @@ export interface IdentityConfig<Schema extends ZodObject<any> = typeof UserIdent
 
 export interface RouterGlobalContext<DefaultUser extends User = User> {
     oauth: OAuthProviderRecord
+    credentials?: CredentialsProvider<any>
     cookies: CookieStoreConfig
     jose: JoseInstance<DefaultUser>
     secret?: JWTKey

packages/core/src/@types/errors.ts

@@ -45,6 +45,8 @@ export type AuthInternalErrorCode =
     | "UNTRUSTED_ORIGIN"
     | "INVALID_OAUTH_PROVIDER_CONFIGURATION"
     | "DUPLICATED_OAUTH_PROVIDER_ID"
+    | "CREDENTIALS_PROVIDER_NOT_CONFIGURED"
+    | "IDENTITY_VALIDATION_FAILED"
 
 export type AuthSecurityErrorCode =
     | "INVALID_STATE"

packages/core/src/@types/session.ts

@@ -1,7 +1,14 @@
 import { EditableShape, ShapeToObject } from "./utility.ts"
 import type { TypedJWTPayload } from "@aura-stack/jose"
 import type { UserIdentityType, UserShape } from "@/shared/identity.ts"
-import type { CookieStoreConfig, IdentityConfig, InternalLogger, JoseInstance, RouterGlobalContext } from "@/@types/config.ts"
+import type {
+    CookieStoreConfig,
+    CredentialsPayload,
+    IdentityConfig,
+    InternalLogger,
+    JoseInstance,
+    RouterGlobalContext,
+} from "@/@types/config.ts"
 
 export type User = UserIdentityType
 export type { UserShape } from "@/shared/identity.ts"
@@ -279,3 +286,13 @@ export interface UpdateSessionAPIOptions<DefaultUser extends User = User> {
 export type UpdateSessionReturn<DefaultUser extends User = User> =
     | { session: Session<DefaultUser>; headers: Headers; updated: true }
     | { session: null; headers: Headers; updated: false }
+
+export type SignInCredentialsOptions = FunctionAPIContext<{
+    payload: CredentialsPayload
+    redirectTo?: string
+}>
+
+export interface SignInCredentialsAPIOptions {
+    payload: CredentialsPayload
+    redirectTo?: string
+}

packages/core/src/actions/index.ts

@@ -1,4 +1,5 @@
 export { signInAction } from "@/actions/signIn/signIn.ts"
+export { signInCredentialsAction } from "@/actions/signIn/credentials.ts"
 export { callbackAction } from "@/actions/callback/callback.ts"
 export { sessionAction } from "@/actions/session/session.ts"
 export { signOutAction } from "@/actions/signOut/signOut.ts"

packages/core/src/actions/signIn/credentials.ts

@@ -0,0 +1,36 @@
+import { z } from "zod/v4"
+import { createEndpoint, createEndpointConfig } from "@aura-stack/router"
+import { signInCredentials } from "@/api/credentials.ts"
+
+const config = createEndpointConfig({
+    schemas: {
+        body: z.object({
+            username: z.string(),
+            password: z.string(),
+        }),
+        searchParams: z.object({
+            redirectTo: z.string().optional(),
+        }),
+    },
+})
+
+/**
+ * Handles the credentials-based sign-in flow.
+ * It extracts credentials from the request body, calls the provider's `authorize` function,
+ * validates the returned user object, and creates a session.
+ *
+ * @returns The signed-in user and session cookies.
+ */
+export const signInCredentialsAction = createEndpoint(
+    "POST",
+    "/signIn/credentials",
+    async (ctx) => {
+        const payload = ctx.body
+        const { headers, success } = await signInCredentials({
+            ctx: ctx.context,
+            payload,
+        })
+        return Response.json({ success }, { headers, status: success ? 200 : 401 })
+    },
+    config
+)

packages/core/src/api/createApi.ts

@@ -1,8 +1,5 @@
-import { signIn } from "@/api/signIn.ts"
-import { signOut } from "@/api/signOut.ts"
-import { getSession } from "@/api/getSession.ts"
-import { updateSession } from "./updateSession.ts"
 import { validateRedirectTo } from "@/shared/utils.ts"
+import { getSession, signIn, signInCredentials, signOut, updateSession } from "@/api/index.ts"
 import type { GlobalContext } from "@aura-stack/router"
 import type {
     BuiltInOAuthProvider,
@@ -14,6 +11,7 @@ import type {
     SignOutAPIOptions,
     UpdateSessionAPIOptions,
     User,
+    SignInCredentialsAPIOptions,
 } from "@/@types/index.ts"
 
 export const createAuthAPI = <DefaultUser extends User = User>(ctx: GlobalContext) => {
@@ -34,6 +32,13 @@ export const createAuthAPI = <DefaultUser extends User = User>(ctx: GlobalContex
                 redirectTo: options?.redirectTo,
             })
         },
+        signInCredentials: async (options: SignInCredentialsAPIOptions) => {
+            return signInCredentials({
+                ctx,
+                payload: options.payload,
+                redirectTo: options.redirectTo,
+            })
+        },
         signOut: async (options: SignOutAPIOptions) => {
             const redirectTo = validateRedirectTo(options?.redirectTo ?? "/")
             return signOut({ ctx, headers: options.headers, redirectTo, skipCSRFCheck: true })

packages/core/src/api/credentials.ts

@@ -0,0 +1,43 @@
+import { AuthValidationError } from "@/shared/errors.ts"
+import { secureApiHeaders } from "@/shared/headers.ts"
+import { createCSRF, hashPassword, verifyPassword } from "@/shared/security.ts"
+import { HeadersBuilder } from "@aura-stack/router"
+import type { SignInCredentialsOptions } from "@/@types/session.ts"
+
+export const signInCredentials = async ({ ctx, payload }: SignInCredentialsOptions) => {
+    const { cookies, credentials, sessionStrategy, logger } = ctx
+    try {
+        const session = await credentials?.authorize({
+            credentials: payload,
+            deriveSecret: credentials?.hash ?? hashPassword,
+            verifySecret: credentials?.verify ?? verifyPassword,
+        })
+        if (!session) {
+            throw new AuthValidationError("INVALID_CREDENTIALS", "The provided credentials are invalid.")
+        }
+        const sessionToken = await sessionStrategy.createSession(session)
+        const csrfToken = await createCSRF(ctx.jose)
+
+        logger?.log("CREDENTIALS_SIGN_IN_SUCCESS")
+
+        const headers = new HeadersBuilder(secureApiHeaders)
+            .setCookie(cookies.csrfToken.name, csrfToken, cookies.csrfToken.attributes)
+            .setCookie(cookies.sessionToken.name, sessionToken, cookies.sessionToken.attributes)
+            .toHeaders()
+        return {
+            success: true,
+            headers,
+        }
+    } catch {
+        logger?.log("INVALID_CREDENTIALS", {
+            severity: "warning",
+            structuredData: {
+                path: "/signIn/credentials",
+            },
+        })
+        return {
+            success: false,
+            headers: new Headers(secureApiHeaders),
+        }
+    }
+}

packages/core/src/api/index.ts

@@ -1,4 +1,6 @@
 export { createAuthAPI } from "@/api/createApi.ts"
 export { signIn } from "@/api/signIn.ts"
+export { signInCredentials } from "@/api/credentials.ts"
 export { signOut } from "@/api/signOut.ts"
 export { getSession } from "@/api/getSession.ts"
+export { updateSession } from "@/api/updateSession.ts"

packages/core/src/createAuth.ts

@@ -5,6 +5,7 @@ import { isSecureConnection } from "@/shared/utils.ts"
 import { createErrorHandler } from "@/router/errorHandler.ts"
 import {
     signInAction,
+    signInCredentialsAction,
     callbackAction,
     sessionAction,
     signOutAction,
@@ -34,6 +35,7 @@ export const createAuthInstance = <Identity extends EditableShape<UserShape>>(au
     const router = createRouter(
         [
             signInAction(config.context.oauth),
+            signInCredentialsAction,
             callbackAction(config.context.oauth),
             sessionAction,
             signOutAction,

packages/core/src/router/context.ts

@@ -20,6 +20,7 @@ export const createContext = <Identity extends EditableShape<UserShape>>(config?
 
     const ctx = {
         oauth: createBuiltInOAuthProviders(config?.oauth),
+        credentials: config?.credentials,
         cookies: standardCookieStore,
         jose: jose,
         secret: config?.secret,

packages/core/src/shared/errors.ts

@@ -17,7 +17,7 @@ export class OAuthProtocolError extends Error {
         this.error = error
         this.errorURI = errorURI
         this.name = new.target.name
-        Error.captureStackTrace(this, new.target)
+        Error?.captureStackTrace(this, new.target)
     }
 }
 
@@ -35,7 +35,7 @@ export class AuthInternalError extends Error {
         super(message, options)
         this.code = code
         this.name = new.target.name
-        Error.captureStackTrace(this, new.target)
+        Error?.captureStackTrace(this, new.target)
     }
 }
 
@@ -53,7 +53,7 @@ export class AuthSecurityError extends Error {
         super(message, options)
         this.code = code
         this.name = new.target.name
-        Error.captureStackTrace(this, new.target)
+        Error?.captureStackTrace(this, new.target)
     }
 }
 
@@ -65,7 +65,7 @@ export class AuthClientError extends Error {
         super(message, options)
         this.code = code
         this.name = new.target.name
-        Error.captureStackTrace(this, new.target)
+        Error?.captureStackTrace(this, new.target)
     }
 }
 

packages/core/src/shared/logger.ts

@@ -290,6 +290,18 @@ export const logMessages = {
         msgId: "IDENTITY_VALIDATION_FAILED",
         message: "User identity validation against the schema failed",
     },
+    CREDENTIALS_SIGN_IN_SUCCESS: {
+        facility: 4,
+        severity: "info",
+        msgId: "CREDENTIALS_SIGN_IN_SUCCESS",
+        message: "User successfully authenticated with credentials",
+    },
+    INVALID_CREDENTIALS: {
+        facility: 4,
+        severity: "warning",
+        msgId: "INVALID_CREDENTIALS",
+        message: "Authentication failed due to invalid credentials",
+    },
 } as const
 
 export const createLogEntry = <T extends keyof typeof logMessages>(key: T, overrides?: Partial<SyslogOptions>): SyslogOptions => {
@@ -298,7 +310,6 @@ export const createLogEntry = <T extends keyof typeof logMessages>(key: T, overr
         ...message,
         timestamp: new Date().toISOString(),
         hostname: "aura-auth",
-        procId: typeof process !== "undefined" && process.pid ? process.pid.toString() : "-",
         ...overrides,
     }
 }

packages/core/src/shared/security.ts

@@ -81,3 +81,53 @@ export const verifyCSRF = async <DefaultUser extends User = User>(
         throw new AuthSecurityError("CSRF_TOKEN_INVALID", "The CSRF tokens do not match.")
     }
 }
+
+/**
+ * Hashes a password using PBKDF2 with SHA-256.
+ * PBKDF2 is available in standard Web Crypto (SubtleCrypto).
+ *
+ * @param password - The password to hash.
+ * @param salt - Optional salt (base64url encoded). If not provided, a random salt will be generated.
+ * @param iterations - The number of PBKDF2 iterations. Default is 100,000.
+ * @returns The hashed password in the format `iterations:salt:hash` (all segments base64url encoded).
+ */
+export const hashPassword = async (password: string, salt?: string, iterations = 100000) => {
+    const subtle = getSubtleCrypto()
+    const saltBuffer = (salt ? base64url.decode(salt) : getRandomBytes(16)) as any
+    const baseKey = await subtle.importKey("raw", encoder.encode(password) as any, "PBKDF2", false, ["deriveBits"])
+    const derivedKey = await subtle.deriveBits(
+        {
+            name: "PBKDF2",
+            salt: saltBuffer,
+            iterations,
+            hash: "SHA-256",
+        },
+        baseKey,
+        256
+    )
+    const hashValues = new Uint8Array(derivedKey)
+    const hash = base64url.encode(hashValues)
+    const saltStr = base64url.encode(saltBuffer)
+    return `${iterations}:${saltStr}:${hash}`
+}
+
+/**
+ * Verifies a password against a hashed value.
+ *
+ * @param password - The password to verify.
+ * @param hashedPassword - The hashed password to compare against.
+ * @returns A promise that resolves to true if the password matches the hash, false otherwise.
+ */
+export const verifyPassword = async (password: string, hashedPassword: string) => {
+    try {
+        const segments = hashedPassword.split(":")
+        if (segments.length !== 3) return false
+        const [iterationsStr, saltStr] = segments
+        const iterations = parseInt(iterationsStr, 10)
+        if (isNaN(iterations)) return false
+        const newHashed = await hashPassword(password, saltStr, iterations)
+        return timingSafeEqual(newHashed, hashedPassword)
+    } catch {
+        return false
+    }
+}