https://github.com/fells-code/seamless-auth-server
The Seamless Auth Server Side SDKs, allowing quick integration with seamless auth instances
https://github.com/fells-code/seamless-auth-server
passwordless passwordless-auth passwordless-authentication react
Last synced: 27 days ago
JSON representation
The Seamless Auth Server Side SDKs, allowing quick integration with seamless auth instances
- Host: GitHub
- URL: https://github.com/fells-code/seamless-auth-server
- Owner: fells-code
- Created: 2025-06-28T02:29:29.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-05-03T04:34:25.000Z (about 1 month ago)
- Last Synced: 2026-05-03T06:32:47.014Z (about 1 month ago)
- Topics: passwordless, passwordless-auth, passwordless-authentication, react
- Language: TypeScript
- Homepage: https://seamlessauth.com
- Size: 545 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Seamless Auth Server Packages
Seamless Auth is an open source, passwordless authentication system designed to be embedded directly into applications.
It provides a small, explicit core and framework-specific adapters that make it easy to integrate secure, session-based authentication into APIs and web applications without redirects, third-party identity providers, or opaque middleware chains.
This repository contains the core building blocks and official server-side framework integrations.
---
## Philosophy
Seamless Auth is built around a few guiding principles:
- **Passwordless by default**
Authentication is based on possession and verification, not shared secrets.
- **Embedded authentication**
Auth flows live inside your application. No redirects, callbacks, or hosted UI.
- **Server-side session validation**
Sessions are managed using secure, HTTP-only cookies and validated by the API.
- **Explicit over magical**
Authentication and authorization are enforced with clear, composable middleware.
- **Self-hosted and open source**
You control the infrastructure and the data.
---
## Packages
This repository is structured as a small core plus framework adapters.
### @seamless-auth/core
The core package contains framework-agnostic logic used across all integrations.
Responsibilities include:
- Verifying signed session cookies
- Authenticated server-to-server requests
- Resolving the current authenticated user
- Shared types and helpers
The core package does **not** depend on any specific web framework.
It is intended to be reused by:
- Node.js frameworks
- Server-side rendering environments
- Edge runtimes
- Future non-JavaScript adapters
Location:
```
packages/core
```
---
### @seamless-auth/express
The Express adapter provides middleware for integrating Seamless Auth into Express applications.
It builds on the core package and adds:
- `requireAuth` middleware for session authentication
- `requireRole` middleware for role-based authorization
- A normalized `req.user` contract for downstream handlers
The Express adapter intentionally keeps authentication and authorization concerns separate from business logic.
It is also the natural initializer boundary for adopter-supplied auth messaging configuration such as:
- email transports
- SMS transports
- custom auth-message handlers
- optional auth template overrides
For WebAuthn PRF flows, the adapter proxies PRF registration query flags and assertion request bodies to the Seamless Auth API. PRF outputs remain browser-only and are never handled by the server adapter.
Location:
```
packages/express
```
Example usage:
```ts
app.get(
"/api/beta_users",
requireAuth({ cookieSecret: process.env.COOKIE_SIGNING_KEY! }),
requireRole("betaUser"),
handler,
);
```
---
## Extensibility
Framework integrations are designed as thin adapters over the core package.
Future adapters are expected to follow the same pattern:
- Delegate cryptography and verification to `@seamless-auth/core`
- Populate a framework-native request context with a normalized user object
- Expose composable authentication and authorization primitives
Planned and likely future integrations include:
- Fastify
- NestJS
- Python (ASGI / FastAPI)
- Other server runtimes where cookie-based sessions are appropriate
Adding a new adapter does not require changes to the core authentication model.
---
## Versioning and Releases
This repository uses a staged release model:
- **Beta releases**
Automatically published from the `dev` branch under the `beta` npm dist-tag.
- **Stable releases**
Published when a GitHub Release is published for an explicit package tag
(for example `core-v1.0.0` or `express-v1.0.0`).
Each package is versioned and released independently.
---
## Documentation
Full documentation for Seamless Auth is available at:
[https://docs.seamlessauth.com](https://docs.seamlessauth.com)
The documentation covers:
- Architecture and authentication flow
- Session and cookie handling
- Role-based authorization
- Framework-specific integration guides
- Deployment considerations
---
## Repository Structure
```
.
├─ packages/
│ ├─ core/ # Framework-agnostic authentication logic
│ └─ express/ # Express middleware adapter
├─ .github/
│ └─ workflows/ # CI and release pipelines
└─ README.md
```
---
## License
This repository is licensed under the AGPL-3.0 license.
Individual packages may include additional notices or licenses where appropriate.
Refer to each package directory for details.