Skip to content

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_principal returns 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"
    }
  ]
}