feat: add docs

docs/assets/app.css

@@ -1,3 +1,82 @@
 @import 'unpoly';
 @import '@docsearch/css';
+
+/* Gray colors */
+@import '@radix-ui/colors/mauve.css';
+@import '@radix-ui/colors/mauve-alpha.css';
+@import '@radix-ui/colors/mauve-dark.css';
+@import '@radix-ui/colors/mauve-dark-alpha.css';
+
+/* Accent colors */
+@import '@radix-ui/colors/violet.css';
+@import '@radix-ui/colors/violet-alpha.css';
+@import '@radix-ui/colors/violet-dark.css';
+@import '@radix-ui/colors/violet-dark-alpha.css';
+
+/* Interface colors */
+@import '@radix-ui/colors/orange-alpha.css';
+@import '@radix-ui/colors/violet-alpha.css';
+@import '@radix-ui/colors/orange-dark-alpha.css';
+@import '@radix-ui/colors/violet-dark-alpha.css';
+
+/**
+ * Dimer doc theme styles
+ */
 @import '@dimerapp/docs-theme/styles';
+
+:root {
+  --progress-bar-color: var(--violet-a11);
+  --sidebar-active-link-bg-color: var(--violet-a6);
+  --sidebar-active-link-text-color: var(--violet-12);
+  --aside-active-link-text-color: var(--violet-11);
+  --pre-tabs-active-border-color: var(--violet-10);
+
+  --note-icon-color: var(--violet-a11);
+  --code-bg-color: var(--violet-a3);
+  --code-text-color: var(--violet-a11);
+  --code-highlight-border-color: var(--violet-11);
+  --sidebar-loading-link-bg-color: var(--violet-a3);
+  --docsearch-primary-color: var(--violet-9);
+}
+
+html.dark {
+  --progress-bar-color: var(--violet-a11);
+  --sidebar-active-link-bg-color: var(--violet-a5);
+  --sidebar-active-link-text-color: var(--violet-12);
+  --aside-active-link-text-color: var(--violet-11);
+  --pre-tabs-active-border-color: var(--violet-a10);
+
+  --note-icon-color: var(--violet-a11);
+  --code-bg-color: var(--violet-a3);
+  --code-text-color: var(--violet-a11);
+  --code-highlight-border-color: var(--violet-a8);
+  --sidebar-loading-link-bg-color: var(--violet-a7);
+  --docsearch-primary-color: var(--violet-8);
+}
+
+.markdown .media_box {
+  padding: 2rem;
+  border: 4px solid var(--mauve-4);
+  border-radius: 4px;
+  margin: var(--prose-elements-margin) 0;
+}
+
+.markdown .media_box figure, .markdown .media_box p {
+  margin: 0;
+}
+
+.markdown ul li ul {
+  margin: 0px;
+}
+
+
+@media only screen and (min-width: 768px) {
+  .header_container {
+    background-color: var(--mauveA1);
+    backdrop-filter: blur(10px);
+  }
+}
+
+.markdown .table_container {
+  overflow-x: auto;
+}

docs/assets/app.js

@@ -1,4 +1,5 @@
 import 'unpoly'
+
 import Alpine from 'alpinejs'
 import mediumZoom from 'medium-zoom'
 import docsearch from '@docsearch/js'
@@ -10,7 +11,12 @@ import {
   initSearchComponent,
 } from '@dimerapp/docs-theme/scripts'
 
-import.meta.glob(['../content/**/*.png', '../content/**/*.jpeg', '../content/**/*.jpg'])
+import.meta.glob([
+  '../content/**/*.png',
+  '../content/**/*.jpeg',
+  '../content/**/*.jpg',
+  '../content/**/*.webp',
+])
 
 Alpine.plugin(tabs)
 Alpine.plugin(Persist)

docs/bin/build.ts

@@ -38,8 +38,8 @@ async function exportHTML() {
   const { default: ace } = await import('@adonisjs/core/services/ace')
   const { default: app } = await import('@adonisjs/core/services/app')
 
-  for (let collection of collections) {
-    for (let entry of collection.all()) {
+  for (const collection of collections) {
+    for (const entry of collection.all()) {
       try {
         const output = await entry.writeToDisk(app.makePath('dist'), { collection, entry })
         ace.ui.logger.action(`create ${output.filePath}`).succeeded()

docs/bin/download_sponsors.ts

@@ -43,7 +43,7 @@ export async function downloadSponsors() {
     /**
      * Processing sponsors
      */
-    for (let source of sources) {
+    for (const source of sources) {
       const { body } = await request(source)
       const sponsors = await body.json()
       if (Array.isArray(sponsors)) {

docs/content/config.json

@@ -1,26 +1,18 @@
 {
   "links": {
     "home": {
-      "title": "Your project name",
+      "title": "Adonis 2FA",
       "href": "/"
     },
     "github": {
-      "title": "Your project on Github",
-      "href": "https://github.com/dimerapp"
+      "title": "Adonis 2FA on GitHub",
+      "href": "https://github.com/nulix-dev/adonis-2fa"
     }
   },
   "sponsors_sources": [
+    "nulix-dev"
   ],
-  "search": {
-  },
-  "advertising_sponsors": [
-    {
-      "link": "",
-      "logo": "",
-      "logo_dark": "",
-      "logo_styles": ""
-    }
-  ],
-  "fileEditBaseUrl": "https://github.com/dimerapp/docs-boilerplate/blob/develop",
-  "copyright": "Your project legal name"
+  "search": {},
+  "fileEditBaseUrl": "https://github.com/nulix-dev/adonis-2fa/tree/develop/docs",
+  "copyright": "Nulix"
 }

docs/content/docs/basic_flow/controller.md

@@ -0,0 +1,75 @@
+---
+summary: How set Adonis-2FA Basic flow controller
+---
+
+# Controller
+
+This is the controller that we recommend to the basic flow.
+
+```ts
+import twoFactorAuth from '@nulix/adonis-2fa/services/main'
+import type { HttpContext } from '@adonisjs/core/http'
+
+import { verifyOtpValidator } from '#validators/verify_otp'
+
+export default class TwoFactorAuthController {
+  async generate({ auth }: HttpContext) {
+    const user = auth.user!
+
+    user.twoFactorSecret = twoFactorAuth.generateSecret(user.email)
+    user.isTwoFactorEnabled = false
+
+    await user.save()
+
+    return user.twoFactorSecret
+  }
+
+  async disable({ auth, response }: HttpContext) {
+    if (!auth.user!.isTwoFactorEnabled) {
+      return response.badRequest({ message: 'User without 2FA active' })
+    }
+
+    await auth
+      .user!.merge({ isTwoFactorEnabled: false, twoFactorRecoveryCodes: [], twoFactorSecret: null })
+      .save()
+
+    return response.noContent()
+  }
+
+  async verify({ auth, request, response }: HttpContext) {
+    const { otp } = await request.validateUsing(verifyOtpValidator)
+
+    const user = auth.user!
+
+    const isValid = twoFactorAuth.verifyToken(
+      user.twoFactorSecret?.secret,
+      otp,
+      user.twoFactorRecoveryCodes
+    )
+
+    if (!isValid) {
+      return response.badRequest({ message: 'OTP invalid' })
+    }
+
+    if (!user.isTwoFactorEnabled) {
+      await user.merge({ isTwoFactorEnabled: true }).save()
+    }
+
+    return response.ok({ message: 'OTP valid' })
+  }
+
+  async generateRecoveryCodes({ auth, response }: HttpContext) {
+    const user = auth.user!
+
+    if (!user.isTwoFactorEnabled) {
+      return response.badRequest({ message: 'User without 2FA active' })
+    }
+
+    const recoveryCodes = twoFactorAuth.generateRecoveryCodes()
+
+    await user.merge({ twoFactorRecoveryCodes: recoveryCodes }).save()
+
+    return { recovery_codes: recoveryCodes }
+  }
+}
+```

docs/content/docs/basic_flow/routes.md

@@ -0,0 +1,72 @@
+---
+summary: How set Adonis-2FA Basic flow routes
+---
+
+# Routes
+
+This is the routes that we recommend to the basic flow. This examples is for `api` projects, and can be adapted to `web` projects as well.
+
+```ts
+import { middleware } from '#start/kernel'
+import router from '@adonisjs/core/services/router'
+
+const TwoFactorsController = () => import('#controllers/two_factor_auth_controller')
+
+router
+  .group(() => {
+    router.post('generate', [TwoFactorsController, 'generate']).as('generate')
+    router.post('verify', [TwoFactorsController, 'verify']).as('verify')
+    router
+      .post('generate-recovery-codes', [TwoFactorsController, 'generateRecoveryCodes'])
+      .as('generate_recovery_codes')
+    router.post('disable', [TwoFactorsController, 'disable']).as('disable')
+  })
+  .as('2fa')
+  .prefix('2fa')
+  .middleware(middleware.auth())
+```
+
+You can wrap this code in a function and call it inside your authenticated group of routes.
+
+:::codegroup
+
+```ts
+// title: start/routes/2fa.ts
+import { middleware } from '#start/kernel'
+import router from '@adonisjs/core/services/router'
+
+const TwoFactorsController = () => import('#controllers/two_factor_auth_controller')
+
+export function twoFactorAuthRoutes() {
+  router
+    .group(() => {
+      router.post('generate', [TwoFactorsController, 'generate']).as('generate')
+      router.post('verify', [TwoFactorsController, 'verify']).as('verify')
+      router
+        .post('generate-recovery-codes', [TwoFactorsController, 'generateRecoveryCodes'])
+        .as('generate_recovery_codes')
+      router.post('disable', [TwoFactorsController, 'disable']).as('disable')
+    })
+    .as('2fa')
+    .prefix('2fa')
+}
+```
+
+```ts
+// title: start/routes.ts
+import router from '@adonisjs/core/services/router'
+import { middleware } from '#start/kernel'
+
+import { twoFactorAuthRoutes } from './routes/2fa.js'
+
+router
+  .group(() => {
+    // ...other routes
+    twoFactorAuthRoutes()
+  })
+  .as('v1')
+  .prefix('v1')
+  .use(middleware.auth())
+```
+
+:::

docs/content/docs/basic_flow/validation.md

@@ -0,0 +1,22 @@
+---
+summary: How set Adonis-2FA Basic flow validation
+---
+
+# Validation
+
+This is the validation that we recommend to the basic flow.
+
+:::codegroup
+
+```ts
+// title: app/validators/verify_otp.ts
+import vine from '@vinejs/vine'
+
+export const verifyOtpValidator = vine.compile(
+  vine.object({
+    otp: vine.string(),
+  })
+)
+```
+
+:::

docs/content/docs/db.json

@@ -4,5 +4,41 @@
     "title": "Introduction",
     "contentPath": "./introduction.md",
     "category": "Guides"
+  },
+  {
+    "permalink": "usage",
+    "title": "Usage",
+    "contentPath": "./usage.md",
+    "category": "Guides"
+  },
+  {
+    "permalink": "lucid/migration",
+    "title": "Migration",
+    "contentPath": "./lucid/migration.md",
+    "category": "Lucid Integration"
+  },
+  {
+    "permalink": "lucid/model",
+    "title": "Model",
+    "contentPath": "./lucid/model.md",
+    "category": "Lucid Integration"
+  },
+  {
+    "permalink": "basic-flow/routes",
+    "title": "Routes",
+    "contentPath": "./basic_flow/routes.md",
+    "category": "Basic Flow"
+  },
+  {
+    "permalink": "basic-flow/validation",
+    "title": "Validation",
+    "contentPath": "./basic_flow/validation.md",
+    "category": "Basic Flow"
+  },
+  {
+    "permalink": "basic-flow/controller",
+    "title": "Controller",
+    "contentPath": "./basic_flow/controller.md",
+    "category": "Basic Flow"
   }
-]
+]