mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
Every page now loads /webmcp.js, scripts/webmcp.ts with its types stripped (npm run webmcp). Where the browser has document.modelContext it registers two read-only tools: search_skills over the published skills index, and get_skill, which returns a skill's markdown checked against the index digest. The markdown alternate link moves from build.py to site.py, so CI holds every page to it. The API catalog gains the site itself (llms.txt and the skills index) and hanzo.ai/agents; the live discovery check now fetches every catalog link. tests/site.mjs drives the tools through a recording modelContext, and checks a browser without one loads clean.
658 lines
30 KiB
HTML
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="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/security-authentication">
|
|
<link rel="alternate" type="text/markdown" href="/security-authentication.md">
|
|
<script type="module" src="/webmcp.js"></script>
|
|
</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>: "Who are you?" - Verifying identity <strong>Authorization</strong>: "What can you do?" - Verifying permissions</p>
|
|
<pre><code class="lang-python"># Authentication: Verify user identity
|
|
def authenticate(username: str, password: str) -> User:
|
|
user = db.get_user_by_username(username)
|
|
if user and verify_password(password, user.password_hash):
|
|
return user
|
|
raise AuthenticationError("Invalid credentials")
|
|
|
|
# Authorization: Check permissions (see security-authorization.md)
|
|
def authorize(user: User, resource: str, action: str) -> 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) -> bytes:
|
|
salt = bcrypt.gensalt(rounds=12) # Cost factor
|
|
return bcrypt.hashpw(password.encode(), salt)
|
|
|
|
def verify_password_bcrypt(password: str, hash: bytes) -> bool:
|
|
return bcrypt.checkpw(password.encode(), hash)
|
|
|
|
# ✅ Argon2 (modern, recommended)
|
|
ph = PasswordHasher()
|
|
|
|
def hash_password_argon2(password: str) -> str:
|
|
return ph.hash(password)
|
|
|
|
def verify_password_argon2(password: str, hash: str) -> 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) -> tuple[bool, List[str]]:
|
|
"""
|
|
Validate password meets security requirements.
|
|
Returns (is_valid, list_of_errors)
|
|
"""
|
|
errors = []
|
|
|
|
# Minimum length
|
|
if len(password) < 12:
|
|
errors.append("Password must be at least 12 characters")
|
|
|
|
# Character requirements
|
|
if not re.search(r'[A-Z]', password):
|
|
errors.append("Password must contain uppercase letter")
|
|
|
|
if not re.search(r'[a-z]', password):
|
|
errors.append("Password must contain lowercase letter")
|
|
|
|
if not re.search(r'\d', password):
|
|
errors.append("Password must contain digit")
|
|
|
|
if not re.search(r'[^A-Za-z0-9]', password):
|
|
errors.append("Password must contain special character")
|
|
|
|
# Check against common passwords (use library like commonpasswords)
|
|
if password.lower() in COMMON_PASSWORDS:
|
|
errors.append("Password is too common")
|
|
|
|
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) -> str:
|
|
token = secrets.token_urlsafe(32)
|
|
expiry = datetime.utcnow() + timedelta(hours=1)
|
|
|
|
# Store hashed token
|
|
db.execute("""
|
|
INSERT INTO password_reset_tokens (user_id, token_hash, expires_at)
|
|
VALUES (?, ?, ?)
|
|
""", [user_id, hash_token(token), expiry])
|
|
|
|
return token # Send via email
|
|
|
|
# Step 2: Validate and reset
|
|
def reset_password(token: str, new_password: str) -> bool:
|
|
token_hash = hash_token(token)
|
|
|
|
# Find valid token
|
|
record = db.fetch_one("""
|
|
SELECT user_id FROM password_reset_tokens
|
|
WHERE token_hash = ? AND expires_at > ? AND used = FALSE
|
|
""", [token_hash, datetime.utcnow()])
|
|
|
|
if not record:
|
|
raise InvalidTokenError("Invalid or expired token")
|
|
|
|
# Update password
|
|
new_hash = hash_password(new_password)
|
|
db.execute("UPDATE users SET password_hash = ? WHERE id = ?",
|
|
[new_hash, record['user_id']])
|
|
|
|
# Mark token as used
|
|
db.execute("UPDATE password_reset_tokens SET used = TRUE WHERE token_hash = ?",
|
|
[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 = 'your-secret-key' # Use environment variable
|
|
app.permanent_session_lifetime = timedelta(hours=24)
|
|
|
|
@app.route('/login', methods=['POST'])
|
|
def login():
|
|
credentials = request.json
|
|
|
|
# Authenticate user
|
|
user = authenticate(credentials['username'], credentials['password'])
|
|
|
|
# Create session
|
|
session.permanent = True
|
|
session['user_id'] = user.id
|
|
session['username'] = user.username
|
|
session['role'] = user.role
|
|
|
|
return {"message": "Login successful"}
|
|
|
|
@app.route('/logout', methods=['POST'])
|
|
def logout():
|
|
session.clear()
|
|
return {"message": "Logout successful"}
|
|
|
|
# Middleware to require authentication
|
|
from functools import wraps
|
|
|
|
def require_auth(f):
|
|
@wraps(f)
|
|
def decorated_function(*args, **kwargs):
|
|
if 'user_id' not in session:
|
|
return {"error": "Unauthorized"}, 401
|
|
return f(*args, **kwargs)
|
|
return decorated_function
|
|
|
|
@app.route('/protected')
|
|
@require_auth
|
|
def protected_route():
|
|
return {"user_id": session['user_id']}</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='Lax', # CSRF protection
|
|
PERMANENT_SESSION_LIFETIME=3600, # 1 hour timeout
|
|
)
|
|
|
|
# Server-side session storage (Redis)
|
|
app.config.update(
|
|
SESSION_TYPE='redis',
|
|
SESSION_REDIS=redis.from_url('redis://localhost:6379')
|
|
)
|
|
|
|
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 = "your-secret-key"
|
|
|
|
def create_jwt(user_id: int) -> str:
|
|
payload = {
|
|
"sub": str(user_id),
|
|
"iat": datetime.utcnow(),
|
|
"exp": datetime.utcnow() + timedelta(hours=1)
|
|
}
|
|
return jwt.encode(payload, SECRET_KEY, algorithm="HS256")
|
|
|
|
def verify_jwt(token: str) -> dict:
|
|
try:
|
|
return jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
|
|
except jwt.ExpiredSignatureError:
|
|
raise AuthenticationError("Token expired")
|
|
except jwt.InvalidTokenError:
|
|
raise AuthenticationError("Invalid token")</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) -> dict:
|
|
"""Generate TOTP secret and QR code for user"""
|
|
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="YourApp"
|
|
)
|
|
|
|
# Generate QR code
|
|
qr = qrcode.make(uri)
|
|
buffer = BytesIO()
|
|
qr.save(buffer, format='PNG')
|
|
|
|
return {
|
|
"secret": secret, # Show once for manual entry
|
|
"qr_code": buffer.getvalue()
|
|
}
|
|
|
|
@staticmethod
|
|
def verify_totp(user: User, code: str) -> bool:
|
|
"""Verify TOTP code"""
|
|
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) -> bool:
|
|
"""Enable MFA after verifying setup code"""
|
|
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('/login', methods=['POST'])
|
|
def login():
|
|
credentials = request.json
|
|
|
|
# Step 1: Verify username/password
|
|
user = authenticate(credentials['username'], credentials['password'])
|
|
|
|
if user.mfa_enabled:
|
|
# MFA required - issue temporary token
|
|
temp_token = create_temporary_token(user.id)
|
|
session['requires_mfa'] = True
|
|
session['temp_user_id'] = user.id
|
|
|
|
return {
|
|
"requires_mfa": True,
|
|
"temp_token": temp_token
|
|
}, 200
|
|
|
|
# No MFA - complete login
|
|
create_full_session(user)
|
|
return {"message": "Login successful"}, 200
|
|
|
|
@app.route('/login/mfa', methods=['POST'])
|
|
def login_mfa():
|
|
"""Complete MFA challenge"""
|
|
if not session.get('requires_mfa'):
|
|
return {"error": "No MFA challenge pending"}, 400
|
|
|
|
user_id = session['temp_user_id']
|
|
mfa_code = request.json['code']
|
|
|
|
user = db.get_user(user_id)
|
|
|
|
if MFAService.verify_totp(user, mfa_code):
|
|
# MFA verified - complete login
|
|
session.pop('requires_mfa')
|
|
session.pop('temp_user_id')
|
|
create_full_session(user)
|
|
|
|
return {"message": "Login successful"}, 200
|
|
|
|
return {"error": "Invalid MFA code"}, 401</code></pre>
|
|
<h3>Backup Codes</h3>
|
|
<pre><code class="lang-python">import secrets
|
|
|
|
def generate_backup_codes(count: int = 10) -> List[str]:
|
|
"""Generate one-time backup codes"""
|
|
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) -> bool:
|
|
"""Verify and consume backup code"""
|
|
code_hash = hash_backup_code(code)
|
|
|
|
# Find and remove code
|
|
result = db.execute("""
|
|
DELETE FROM backup_codes
|
|
WHERE user_id = ? AND code_hash = ? AND used = FALSE
|
|
RETURNING id
|
|
""", [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(
|
|
'google',
|
|
client_id='YOUR_CLIENT_ID',
|
|
client_secret='YOUR_CLIENT_SECRET',
|
|
server_metadata_url='https://accounts.google.com/.well-known/openid-configuration',
|
|
client_kwargs={'scope': 'openid email profile'}
|
|
)
|
|
|
|
@app.route('/auth/google')
|
|
def google_login():
|
|
redirect_uri = url_for('google_callback', _external=True)
|
|
return oauth.google.authorize_redirect(redirect_uri)
|
|
|
|
@app.route('/auth/google/callback')
|
|
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['email'])
|
|
create_full_session(user)
|
|
|
|
return redirect('/dashboard')</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) -> bool:
|
|
"""Check if account is locked due to failed attempts"""
|
|
attempts = db.fetch_one("""
|
|
SELECT COUNT(*) as count, MAX(attempted_at) as last_attempt
|
|
FROM login_attempts
|
|
WHERE username = ? AND attempted_at > ?
|
|
""", [username, datetime.utcnow() - timedelta(minutes=15)])
|
|
|
|
if attempts['count'] >= 5:
|
|
# Lock account for 15 minutes
|
|
return False
|
|
|
|
return True
|
|
|
|
def record_failed_login(username: str):
|
|
"""Record failed login attempt"""
|
|
db.execute("""
|
|
INSERT INTO login_attempts (username, attempted_at, success)
|
|
VALUES (?, ?, FALSE)
|
|
""", [username, datetime.utcnow()])
|
|
|
|
def clear_login_attempts(username: str):
|
|
"""Clear attempts after successful login"""
|
|
db.execute("DELETE FROM login_attempts WHERE username = ?", [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('/login', methods=['POST'])
|
|
@limiter.limit("5 per minute") # Rate limit
|
|
def login():
|
|
# Check account lockout
|
|
if not check_login_attempts(username):
|
|
return {"error": "Account locked"}, 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('/login', methods=['POST'])
|
|
def login():
|
|
# Authenticate user
|
|
user = authenticate(...)
|
|
|
|
# Regenerate session ID
|
|
session.regenerate()
|
|
|
|
session['user_id'] = 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> |