Files
skills/public/security-authentication.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

658 lines
30 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>security-authentication</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/security-authentication.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/security-authentication">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/security-authentication.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>security-authentication</h1><p class="lede">Authentication patterns including JWT, OAuth2, sessions, and multi-factor authentication for secure user identity verification</p><h1>Security: Authentication</h1>
<p><strong>Scope</strong>: Authentication patterns, identity verification, credential management, MFA <strong>Lines</strong>: ~380 <strong>Last Updated</strong>: 2025-10-27</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Implementing user login and authentication systems</li><li>Choosing authentication strategies for applications</li><li>Securing user credentials and password management</li><li>Implementing multi-factor authentication (MFA/2FA)</li><li>Designing session management systems</li><li>Preventing authentication bypass vulnerabilities</li><li>Migrating authentication systems</li></ul>
<h2>Authentication Fundamentals</h2>
<h3>Authentication vs Authorization</h3>
<p><strong>Authentication</strong>: &quot;Who are you?&quot; - Verifying identity <strong>Authorization</strong>: &quot;What can you do?&quot; - Verifying permissions</p>
<pre><code class="lang-python"># Authentication: Verify user identity
def authenticate(username: str, password: str) -&gt; User:
user = db.get_user_by_username(username)
if user and verify_password(password, user.password_hash):
return user
raise AuthenticationError(&quot;Invalid credentials&quot;)
# Authorization: Check permissions (see security-authorization.md)
def authorize(user: User, resource: str, action: str) -&gt; bool:
return user.has_permission(resource, action)</code></pre>
<h2>Password Security</h2>
<h3>Password Hashing</h3>
<p><strong>Bad - Never use</strong>:</p>
<pre><code class="lang-python"># ❌ Plain text storage
user.password = request.password
# ❌ Weak hashing (MD5, SHA1)
user.password = hashlib.md5(request.password.encode()).hexdigest()
# ❌ No salt
user.password = hashlib.sha256(request.password.encode()).hexdigest()</code></pre>
<p><strong>Good - Use strong hashing</strong>:</p>
<pre><code class="lang-python">import bcrypt
from argon2 import PasswordHasher
# ✅ bcrypt (widely used, battle-tested)
def hash_password_bcrypt(password: str) -&gt; bytes:
salt = bcrypt.gensalt(rounds=12) # Cost factor
return bcrypt.hashpw(password.encode(), salt)
def verify_password_bcrypt(password: str, hash: bytes) -&gt; bool:
return bcrypt.checkpw(password.encode(), hash)
# ✅ Argon2 (modern, recommended)
ph = PasswordHasher()
def hash_password_argon2(password: str) -&gt; str:
return ph.hash(password)
def verify_password_argon2(password: str, hash: str) -&gt; bool:
try:
ph.verify(hash, password)
return True
except:
return False</code></pre>
<h3>Password Validation</h3>
<pre><code class="lang-python">import re
from typing import List
def validate_password_strength(password: str) -&gt; tuple[bool, List[str]]:
&quot;&quot;&quot;
Validate password meets security requirements.
Returns (is_valid, list_of_errors)
&quot;&quot;&quot;
errors = []
# Minimum length
if len(password) &lt; 12:
errors.append(&quot;Password must be at least 12 characters&quot;)
# Character requirements
if not re.search(r&#x27;[A-Z]&#x27;, password):
errors.append(&quot;Password must contain uppercase letter&quot;)
if not re.search(r&#x27;[a-z]&#x27;, password):
errors.append(&quot;Password must contain lowercase letter&quot;)
if not re.search(r&#x27;\d&#x27;, password):
errors.append(&quot;Password must contain digit&quot;)
if not re.search(r&#x27;[^A-Za-z0-9]&#x27;, password):
errors.append(&quot;Password must contain special character&quot;)
# Check against common passwords (use library like commonpasswords)
if password.lower() in COMMON_PASSWORDS:
errors.append(&quot;Password is too common&quot;)
return (len(errors) == 0, errors)</code></pre>
<h3>Password Reset Flow</h3>
<pre><code class="lang-python">import secrets
from datetime import datetime, timedelta
# Step 1: Generate reset token
def create_password_reset_token(user_id: int) -&gt; str:
token = secrets.token_urlsafe(32)
expiry = datetime.utcnow() + timedelta(hours=1)
# Store hashed token
db.execute(&quot;&quot;&quot;
INSERT INTO password_reset_tokens (user_id, token_hash, expires_at)
VALUES (?, ?, ?)
&quot;&quot;&quot;, [user_id, hash_token(token), expiry])
return token # Send via email
# Step 2: Validate and reset
def reset_password(token: str, new_password: str) -&gt; bool:
token_hash = hash_token(token)
# Find valid token
record = db.fetch_one(&quot;&quot;&quot;
SELECT user_id FROM password_reset_tokens
WHERE token_hash = ? AND expires_at &gt; ? AND used = FALSE
&quot;&quot;&quot;, [token_hash, datetime.utcnow()])
if not record:
raise InvalidTokenError(&quot;Invalid or expired token&quot;)
# Update password
new_hash = hash_password(new_password)
db.execute(&quot;UPDATE users SET password_hash = ? WHERE id = ?&quot;,
[new_hash, record[&#x27;user_id&#x27;]])
# Mark token as used
db.execute(&quot;UPDATE password_reset_tokens SET used = TRUE WHERE token_hash = ?&quot;,
[token_hash])
return True</code></pre>
<h2>Session-Based Authentication</h2>
<h3>Session Implementation (Python/Flask)</h3>
<pre><code class="lang-python">from flask import Flask, session, request
from datetime import timedelta
app = Flask(__name__)
app.secret_key = &#x27;your-secret-key&#x27; # Use environment variable
app.permanent_session_lifetime = timedelta(hours=24)
@app.route(&#x27;/login&#x27;, methods=[&#x27;POST&#x27;])
def login():
credentials = request.json
# Authenticate user
user = authenticate(credentials[&#x27;username&#x27;], credentials[&#x27;password&#x27;])
# Create session
session.permanent = True
session[&#x27;user_id&#x27;] = user.id
session[&#x27;username&#x27;] = user.username
session[&#x27;role&#x27;] = user.role
return {&quot;message&quot;: &quot;Login successful&quot;}
@app.route(&#x27;/logout&#x27;, methods=[&#x27;POST&#x27;])
def logout():
session.clear()
return {&quot;message&quot;: &quot;Logout successful&quot;}
# Middleware to require authentication
from functools import wraps
def require_auth(f):
@wraps(f)
def decorated_function(*args, **kwargs):
if &#x27;user_id&#x27; not in session:
return {&quot;error&quot;: &quot;Unauthorized&quot;}, 401
return f(*args, **kwargs)
return decorated_function
@app.route(&#x27;/protected&#x27;)
@require_auth
def protected_route():
return {&quot;user_id&quot;: session[&#x27;user_id&#x27;]}</code></pre>
<h3>Session Security</h3>
<pre><code class="lang-python">from flask import Flask
from flask_session import Session
app = Flask(__name__)
# Configure secure session
app.config.update(
SESSION_COOKIE_SECURE=True, # HTTPS only
SESSION_COOKIE_HTTPONLY=True, # No JavaScript access
SESSION_COOKIE_SAMESITE=&#x27;Lax&#x27;, # CSRF protection
PERMANENT_SESSION_LIFETIME=3600, # 1 hour timeout
)
# Server-side session storage (Redis)
app.config.update(
SESSION_TYPE=&#x27;redis&#x27;,
SESSION_REDIS=redis.from_url(&#x27;redis://localhost:6379&#x27;)
)
Session(app)</code></pre>
<h2>JWT Authentication</h2>
<p>See <code>api-authentication.md</code> for comprehensive JWT implementation details.</p>
<p><strong>Quick reference</strong>:</p>
<pre><code class="lang-python">import jwt
from datetime import datetime, timedelta
SECRET_KEY = &quot;your-secret-key&quot;
def create_jwt(user_id: int) -&gt; str:
payload = {
&quot;sub&quot;: str(user_id),
&quot;iat&quot;: datetime.utcnow(),
&quot;exp&quot;: datetime.utcnow() + timedelta(hours=1)
}
return jwt.encode(payload, SECRET_KEY, algorithm=&quot;HS256&quot;)
def verify_jwt(token: str) -&gt; dict:
try:
return jwt.decode(token, SECRET_KEY, algorithms=[&quot;HS256&quot;])
except jwt.ExpiredSignatureError:
raise AuthenticationError(&quot;Token expired&quot;)
except jwt.InvalidTokenError:
raise AuthenticationError(&quot;Invalid token&quot;)</code></pre>
<h2>Multi-Factor Authentication (MFA)</h2>
<h3>TOTP (Time-based One-Time Password)</h3>
<pre><code class="lang-python">import pyotp
import qrcode
from io import BytesIO
class MFAService:
@staticmethod
def setup_totp(user: User) -&gt; dict:
&quot;&quot;&quot;Generate TOTP secret and QR code for user&quot;&quot;&quot;
secret = pyotp.random_base32()
# Store encrypted secret
user.mfa_secret = encrypt(secret)
user.mfa_enabled = False # Enable after verification
db.save(user)
# Generate provisioning URI
totp = pyotp.TOTP(secret)
uri = totp.provisioning_uri(
name=user.email,
issuer_name=&quot;YourApp&quot;
)
# Generate QR code
qr = qrcode.make(uri)
buffer = BytesIO()
qr.save(buffer, format=&#x27;PNG&#x27;)
return {
&quot;secret&quot;: secret, # Show once for manual entry
&quot;qr_code&quot;: buffer.getvalue()
}
@staticmethod
def verify_totp(user: User, code: str) -&gt; bool:
&quot;&quot;&quot;Verify TOTP code&quot;&quot;&quot;
if not user.mfa_enabled:
return False
secret = decrypt(user.mfa_secret)
totp = pyotp.TOTP(secret)
# Allow 30-second window (1 step before/after)
return totp.verify(code, valid_window=1)
@staticmethod
def enable_mfa(user: User, code: str) -&gt; bool:
&quot;&quot;&quot;Enable MFA after verifying setup code&quot;&quot;&quot;
if MFAService.verify_totp(user, code):
user.mfa_enabled = True
db.save(user)
return True
return False</code></pre>
<h3>MFA Login Flow</h3>
<pre><code class="lang-python">from flask import Flask, request, session
@app.route(&#x27;/login&#x27;, methods=[&#x27;POST&#x27;])
def login():
credentials = request.json
# Step 1: Verify username/password
user = authenticate(credentials[&#x27;username&#x27;], credentials[&#x27;password&#x27;])
if user.mfa_enabled:
# MFA required - issue temporary token
temp_token = create_temporary_token(user.id)
session[&#x27;requires_mfa&#x27;] = True
session[&#x27;temp_user_id&#x27;] = user.id
return {
&quot;requires_mfa&quot;: True,
&quot;temp_token&quot;: temp_token
}, 200
# No MFA - complete login
create_full_session(user)
return {&quot;message&quot;: &quot;Login successful&quot;}, 200
@app.route(&#x27;/login/mfa&#x27;, methods=[&#x27;POST&#x27;])
def login_mfa():
&quot;&quot;&quot;Complete MFA challenge&quot;&quot;&quot;
if not session.get(&#x27;requires_mfa&#x27;):
return {&quot;error&quot;: &quot;No MFA challenge pending&quot;}, 400
user_id = session[&#x27;temp_user_id&#x27;]
mfa_code = request.json[&#x27;code&#x27;]
user = db.get_user(user_id)
if MFAService.verify_totp(user, mfa_code):
# MFA verified - complete login
session.pop(&#x27;requires_mfa&#x27;)
session.pop(&#x27;temp_user_id&#x27;)
create_full_session(user)
return {&quot;message&quot;: &quot;Login successful&quot;}, 200
return {&quot;error&quot;: &quot;Invalid MFA code&quot;}, 401</code></pre>
<h3>Backup Codes</h3>
<pre><code class="lang-python">import secrets
def generate_backup_codes(count: int = 10) -&gt; List[str]:
&quot;&quot;&quot;Generate one-time backup codes&quot;&quot;&quot;
codes = [secrets.token_hex(4) for _ in range(count)] # 8-char codes
# Store hashed codes
hashed_codes = [hash_backup_code(code) for code in codes]
return codes, hashed_codes
def verify_backup_code(user: User, code: str) -&gt; bool:
&quot;&quot;&quot;Verify and consume backup code&quot;&quot;&quot;
code_hash = hash_backup_code(code)
# Find and remove code
result = db.execute(&quot;&quot;&quot;
DELETE FROM backup_codes
WHERE user_id = ? AND code_hash = ? AND used = FALSE
RETURNING id
&quot;&quot;&quot;, [user.id, code_hash])
return result is not None</code></pre>
<h2>OAuth 2.0 Authentication</h2>
<p>See <code>api-authentication.md</code> for full OAuth implementation.</p>
<p><strong>Quick integration (Python/Authlib)</strong>:</p>
<pre><code class="lang-python">from authlib.integrations.flask_client import OAuth
oauth = OAuth(app)
# Register OAuth provider
oauth.register(
&#x27;google&#x27;,
client_id=&#x27;YOUR_CLIENT_ID&#x27;,
client_secret=&#x27;YOUR_CLIENT_SECRET&#x27;,
server_metadata_url=&#x27;https://accounts.google.com/.well-known/openid-configuration&#x27;,
client_kwargs={&#x27;scope&#x27;: &#x27;openid email profile&#x27;}
)
@app.route(&#x27;/auth/google&#x27;)
def google_login():
redirect_uri = url_for(&#x27;google_callback&#x27;, _external=True)
return oauth.google.authorize_redirect(redirect_uri)
@app.route(&#x27;/auth/google/callback&#x27;)
def google_callback():
token = oauth.google.authorize_access_token()
user_info = oauth.google.parse_id_token(token)
# Find or create user
user = User.find_or_create_by_email(user_info[&#x27;email&#x27;])
create_full_session(user)
return redirect(&#x27;/dashboard&#x27;)</code></pre>
<h2>Security Best Practices</h2>
<h3>Account Lockout</h3>
<pre><code class="lang-python">from datetime import datetime, timedelta
def check_login_attempts(username: str) -&gt; bool:
&quot;&quot;&quot;Check if account is locked due to failed attempts&quot;&quot;&quot;
attempts = db.fetch_one(&quot;&quot;&quot;
SELECT COUNT(*) as count, MAX(attempted_at) as last_attempt
FROM login_attempts
WHERE username = ? AND attempted_at &gt; ?
&quot;&quot;&quot;, [username, datetime.utcnow() - timedelta(minutes=15)])
if attempts[&#x27;count&#x27;] &gt;= 5:
# Lock account for 15 minutes
return False
return True
def record_failed_login(username: str):
&quot;&quot;&quot;Record failed login attempt&quot;&quot;&quot;
db.execute(&quot;&quot;&quot;
INSERT INTO login_attempts (username, attempted_at, success)
VALUES (?, ?, FALSE)
&quot;&quot;&quot;, [username, datetime.utcnow()])
def clear_login_attempts(username: str):
&quot;&quot;&quot;Clear attempts after successful login&quot;&quot;&quot;
db.execute(&quot;DELETE FROM login_attempts WHERE username = ?&quot;, [username])</code></pre>
<h3>Security Checklist</h3>
<p><strong>Password Security</strong>:</p>
<ul><li>[ ] Use Argon2 or bcrypt (cost factor 12+)</li><li>[ ] Enforce minimum length (12+ characters)</li><li>[ ] Require complexity (uppercase, lowercase, digits, special)</li><li>[ ] Check against common password lists</li><li>[ ] Implement secure password reset flow</li><li>[ ] Never email passwords in plain text</li></ul>
<p><strong>Session Security</strong>:</p>
<ul><li>[ ] Use secure, httpOnly cookies</li><li>[ ] Set SameSite attribute (CSRF protection)</li><li>[ ] Implement session timeout (idle + absolute)</li><li>[ ] Regenerate session ID after login</li><li>[ ] Clear session on logout</li><li>[ ] Use server-side session storage for sensitive apps</li></ul>
<p><strong>Authentication Flow</strong>:</p>
<ul><li>[ ] Implement rate limiting on auth endpoints</li><li>[ ] Log all authentication attempts</li><li>[ ] Account lockout after failed attempts</li><li>[ ] MFA for sensitive operations</li><li>[ ] Secure password reset tokens (short-lived, one-time)</li><li>[ ] HTTPS only for authentication</li></ul>
<p><strong>Token Security</strong>:</p>
<ul><li>[ ] Short-lived access tokens (15min-1hr)</li><li>[ ] Secure token storage (httpOnly cookies or secure storage)</li><li>[ ] Implement token refresh mechanism</li><li>[ ] Validate token signature and expiration</li><li>[ ] Use refresh token rotation</li></ul>
<h2>Common Vulnerabilities</h2>
<h3>Brute Force Attack</h3>
<p><strong>Attack</strong>: Automated password guessing <strong>Prevention</strong>:</p>
<pre><code class="lang-python">from flask_limiter import Limiter
limiter = Limiter(app, key_func=get_remote_address)
@app.route(&#x27;/login&#x27;, methods=[&#x27;POST&#x27;])
@limiter.limit(&quot;5 per minute&quot;) # Rate limit
def login():
# Check account lockout
if not check_login_attempts(username):
return {&quot;error&quot;: &quot;Account locked&quot;}, 429
# Authenticate...</code></pre>
<h3>Credential Stuffing</h3>
<p><strong>Attack</strong>: Using leaked credentials from other sites <strong>Prevention</strong>:</p>
<ul><li>Implement MFA</li><li>Monitor for unusual login patterns</li><li>Check passwords against breach databases (haveibeenpwned.com API)</li></ul>
<h3>Session Fixation</h3>
<p><strong>Attack</strong>: Forcing user to use known session ID <strong>Prevention</strong>:</p>
<pre><code class="lang-python">from flask import session
@app.route(&#x27;/login&#x27;, methods=[&#x27;POST&#x27;])
def login():
# Authenticate user
user = authenticate(...)
# Regenerate session ID
session.regenerate()
session[&#x27;user_id&#x27;] = user.id</code></pre>
<h2>Related Skills</h2>
<ul><li><code>security-authorization.md</code> - Access control and permissions</li><li><code>security-input-validation.md</code> - Validating authentication inputs</li><li><code>security-secrets-management.md</code> - Storing authentication secrets</li><li><code>api-authentication.md</code> - JWT and OAuth 2.0 implementation</li><li><code>database-security.md</code> - Securing credential storage</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-27 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/security-authentication.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>