Integrate Own Auth without a framework adapter

Integrate Own Auth in plain TypeScript without a framework adapter

Integrate Own Auth without a framework adapter by creating an Own Auth instance inside your existing TypeScript HTTP handlers, calling the provided auth methods for signup, signin, and verification, and managing session cookies and MFA flows directly. This approach keeps authentication inside your backend, uses your application database as the source of truth, and requires explicit handling of cookies, HTTP status codes, and session lifecycle in your route handlers.

Why this works: Own Auth is framework agnostic and exports creation helpers and runtime methods you can call from any server code. Use createOwnAuth to instantiate the package in your process, then call the public instance methods such as auth.signUpEmailPassword, auth.signInEmailPassword, auth.verifyMagicLink, and auth.getCurrentSession directly from plain request handlers.

Key operational responsibilities you must handle

• Route dispatch and HTTP semantics: return the correct status code for form submission, session creation, authentication failure, and successful requests with no response body.
• Cookie security and scope: set Secure, HttpOnly, SameSite, and an expiry that matches the session lifetime.
• Session lifecycle and revocation: enforce absolute expiry, optional idle expiry, individual session revocation, and full user session revocation.

Minimal TypeScript example using Node http

The following example shows a compact, framework agnostic integration pattern. It uses createOwnAuth to instantiate Own Auth, then exposes a small number of endpoints handled by Node's built in HTTP server. The code narrows auth.signInEmailPassword results before reading session fields and returns MFA challenge details when required.

import http from 'http'
import { createOwnAuth, createSessionCookie, clearSessionCookie } from 'own-auth'

// initialize Own Auth once during process startup
const auth = createOwnAuth({ /* supply required storage and config per docs */ })

async function handleSignin(req, res, body) {
  const { email, password } = JSON.parse(body)
  const result = await auth.signInEmailPassword({ email, password })

  // auth.signInEmailPassword can return an MFA challenge as the first factor result
  if (result.status === 'mfa_required') {
    // return the MFA challenge token, available methods, and expiry to the client
    res.writeHead(200, { 'Content-Type': 'application/json' })
    res.end(JSON.stringify({
      status: 'mfa_required',
      challengeToken: result.challengeToken,
      methods: result.methods,
      expiresAt: result.expiresAt
    }))
    return
  }

  // on success, set a secure session cookie using the sessionToken value
  if (result.status === 'success') {
    const sessionToken = result.sessionToken
    // createSessionCookie returns a Set-Cookie header string that encodes cookie options
    const cookieHeader = createSessionCookie(sessionToken)

    res.writeHead(201, {
      'Content-Type': 'application/json',
      'Set-Cookie': cookieHeader
    })
    // return only safe client fields
    res.end(JSON.stringify({ status: 'success', user: { id: result.user.id, email: result.user.email } }))
    return
  }

  // handle common errors
  res.writeHead(401, { 'Content-Type': 'application/json' })
  res.end(JSON.stringify({ status: 'error', reason: result.error || 'invalid_credentials' }))
}

const server = http.createServer(async (req, res) => {
  if (req.method === 'POST' && req.url === '/signin') {
    let body = ''
    for await (const chunk of req) body += chunk
    await handleSignin(req, res, body)
    return
  }

  // other routes omitted for brevity
  res.writeHead(404)
  res.end()
})

server.listen(3000)
console.log('Server listening on :3000')

Notes about this example: it follows the Own Auth rule to check result.status before accessing result.sessionToken or result.session. If an MFA challenge is returned, respond with the challenge token and available methods rather than treating it as an HTTP error. When the signin is successful, set a session cookie created by createSessionCookie and return only minimal safe user fields to the client.

Cookie attributes and HTTP semantics to enforce

When you write the session cookie, set Secure and HttpOnly to reduce token exposure to client scripts. Apply the SameSite policy required by your application flow, set the cookie path deliberately, and align cookie expiry with the server session expiry.

Return 201 Created when a handler creates and returns a new session resource. Return 200 OK for an MFA challenge payload, 401 Unauthorized for missing or invalid credentials, and 204 No Content for a successful action with no response body.

Session lifecycle and revocation

Keep sessions revocable and auditable. Own Auth provides database backed sessions with absolute expiry and individual or full user revocation. Wire logout and administrative flows to auth.revokeSession or auth.revokeAllSessions so a server side revocation takes effect even when a client retains an old cookie.

• Enforce absolute expiry on sessions to limit token lifetime.
• Support idle expiry if your product needs shorter windows when inactive.
• Log session creation and revocation events for audits and incident response.

When you handle signout, clear the cookie on the client and revoke the session on the server. Use clearSessionCookie to build the Set-Cookie header that removes the cookie in the browser, then call auth.revokeSession with the server side session id if you have it.

Operational checklist

1. Instantiate Own Auth once at process start with createOwnAuth and reuse the instance across requests.
2. Implement handlers that narrow auth.signInEmailPassword, auth.verifyMagicLink, and auth.verifySmsOtp results before reading session or user fields; return MFA challenge details when present.
3. Set session cookies with Secure, HttpOnly, an appropriate SameSite policy, and an expiry that matches the server session.
4. Expose logout and admin revocation endpoints that call auth.revokeSession or auth.revokeAllSessions and clear cookies.
5. Return an HTTP status that matches the result of each authentication operation.
6. Record session creation and revocation events needed for audits and incident response.