Local Sessions (auth-provider)
Category: Tech Stack · Areas: api, data
Description
Category
tech-stack
Areas
api, data
Slot
auth-provider
Boundary
This concern is the default auth-provider slot filler — a real, working,
self-contained authentication backend that needs no external identity service.
It supplies the mechanism the auth concern’s product surface sits on. An
external IdP (Auth0/OIDC, Clerk, …) is a different filler of the same slot,
swapped in without changing call sites.
For the family ownership table (and the boundaries with auth,
authorization-model, multi-tenancy, and security-owasp) see
README-auth-family.md.
Components
- Credential store: principals with securely hashed passwords (e.g. PBKDF2/ bcrypt/argon2 with per-credential salt), stored in the project datastore.
- Sessions: server-side sessions keyed by an HttpOnly cookie.
- Provider interface: a single auth/identity interface the rest of the app calls (signup, authenticate, resolve-principal, logout) so the backend is swappable.
Constraints
- Passwords are hashed (salted, work-factored) — never stored or logged in plaintext.
- Session cookies are HttpOnly (and Secure in production); sessions are validated server-side on each protected request.
- The app calls the provider interface, never local-session internals directly — so swapping to an external IdP is a filler change, not a rewrite.
- This filler is the runnable default; it does not preclude selecting an external IdP filler for production (recorded as a slot swap / deferred-live).
Drift Signals (anti-patterns to reject in review)
- Plaintext or unsalted/un-work-factored passwords → use a real password hash
- Client-readable session token (non-HttpOnly) or no server-side validation
- App code reaching into local-session internals instead of the provider interface → breaks swappability
When to use
Fills auth-provider for any product that selects the auth concern and has no
operator-chosen external IdP. It is the shipped default; operators override per
project (concerns.local.yml: auth-provider: <other-filler>) to choose an
external IdP filler instead.
Artifact Impact
Selecting this concern requires these artifacts to change (a selected concern absent from them is drift):
- TD: hashed-credential store, HttpOnly server-side sessions, single provider interface
- DATA_DESIGN: principals with hashed passwords + server-side session store
ADR References
Selecting this concern needs no ADR; concerns.md records it. Write an ADR only
when the project deviates from a constraint here.
Practices by activity
Agents working in any of these activities inherit the practices below through runtime work context, such as a DDx bead context digest.
These practices realize the default auth-provider filler — a working local
auth backend behind the provider interface the auth concern requires. They
cover the mechanism; for the family ownership table (auth /
authorization-model / multi-tenancy / security-owasp) see
README-auth-family.md.
Design
- Provider interface: expose one auth/identity interface (
signup,authenticate,resolve_principal,logout) that the app calls; keep local-session internals behind it. - Swap path: document how an external IdP filler (Auth0/OIDC) replaces this one — same interface, config-selected, no call-site change.
Build
- Passwords: hash with a salted, work-factored algorithm (PBKDF2/bcrypt/ argon2); never store or log plaintext; verify in constant time.
- Sessions: issue a server-side session on login, referenced by an HttpOnly cookie (Secure in production); validate on each protected request; clear on logout.
- Principal resolution:
resolve_principalreturns the authenticated principal (+ account/tenant + role) for the request, or unauthenticated.
Test
- Passwords are hashed (salted + work-factored); no plaintext anywhere.
- Session cookie is HttpOnly; sessions validated server-side; logout clears them.
- All app auth calls go through the provider interface (no direct internals).
- A working login/logout against the running system is observed (composes with
auth+verification).
Innsigle seal: model-primary by HELIX
The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.
- Composition
- model-primary
- Issuer
- HELIX
helix - Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a(build key)- Signed source
concerns/auth-local-sessions.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:0abf8d79…1d9fa889
This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.
Raw attestation JSON
{
"payload": {
"innsigle": "1",
"type": "https://innsigle.dev/claim/colophon/v1",
"issued_at": "2026-11-16T15:52:45Z",
"issuer": {
"id": "helix",
"name": "HELIX",
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
},
"subjects": [
{
"uri": "https://documentdrivendx.github.io/helix/concerns/auth-local-sessions/",
"digest": {
"alg": "sha256",
"value": "0abf8d796c3b0243f1fb72f30ca11410c99df50d26c5953c5093bd5d1d9fa889"
}
}
],
"colophon": {
"schema_version": "1",
"composition": "model-primary",
"ingredients": [
{
"kind": "model",
"name": "Claude",
"role": "draft"
},
{
"kind": "tool",
"name": "sloptimizer",
"role": "rewrite"
},
{
"kind": "human",
"name": "operator",
"role": "structure-edit"
}
],
"notes": null
}
},
"payload_encoding": "json",
"signatures": [
{
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"alg": "ed25519",
"sig": "CGiBjL6sIacnPNA-bW1yvogQJ0vwo2sy-p8q49caOhoEZknACEdKXJ-lXemAceq4VT0cef0IdloD5dozSsQgBg",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}