npm package: @nanodb-orm/plugin-auth
Description: Auth plugin for nanodb-orm (user/account/session/verification helpers)
Latest version: 0.1.9

# @nanodb-orm/plugin-auth

Auth plugin for `nanodb-orm`.

This plugin is ORM-level and lightweight, and follows `nanodb-orm` plugin conventions:
- user / account / session / verification table conventions (configurable)
- email normalization and `emailVerified` defaulting
- credential password hashing and verification
- session `expiresIn` + `updateAge` refresh model
- verification token hashing by default

## Install

```bash
npm install @nanodb-orm/plugin-auth
```

## Usage

```typescript
import { createDatabase } from 'nanodb-orm';
import { authPlugin, withAuth } from '@nanodb-orm/plugin-auth';

const db = await createDatabase({
  tables,
  plugins: [authPlugin()],
  preview: { deterministicPluginOrdering: true },
});

const authDb = withAuth(db);
const hash = authDb.auth.hashPassword('my-strong-password');
const ok = authDb.auth.verifyPassword('my-strong-password', hash);

// Auth tables are available directly from the plugin API:
const userTable = authDb.auth.tables.user;
const sessionTable = authDb.auth.tables.session;
```

### Typed `db.auth.tables` mapping

If you want explicit table types on `db.auth.tables`, pass a typed table map into `withAuth`:

```typescript
import { withAuth } from '@nanodb-orm/plugin-auth';
import { users, accounts, sessions, verifications } from './schema';

const authDb = withAuth(db, {
  user: users,
  account: accounts,
  session: sessions,
  verification: verifications,
});

// Fully typed:
authDb.auth.tables.user;
authDb.auth.tables.account;
authDb.auth.tables.session;
authDb.auth.tables.verification;
```

## Options

Use one progressive flow: start with defaults, then add only what you need.

### 1) Default (zero-config)

```typescript
authPlugin();
```

Default policy used by `authPlugin()`:

```typescript
{
  tablePrefix: '_nanodb_auth',
  session: {
    expiresIn: 60 * 60 * 24 * 7,
    updateAge: 60 * 60 * 24,
  },
  emailAndPassword: {
    minPasswordLength: 8,
    maxPasswordLength: 128,
  },
}
```

### 2) Progressively customize

```typescript
authPlugin({
  tablePrefix: '_nanodb_auth',
  tables: {
    users: ['user'],
    accounts: ['account'],
    sessions: ['session'],
    verifications: ['verification'],
  },
  fields: {
    userEmail: 'email',
    userEmailVerified: 'emailVerified',

    accountPassword: 'password',
    accountProviderId: 'providerId',
    accountAccountId: 'accountId',
    accountUserId: 'userId',

    sessionToken: 'token',
    sessionUserId: 'userId',
    sessionExpiresAt: 'expiresAt',
    sessionCreatedAt: 'createdAt',
    sessionUpdatedAt: 'updatedAt',

    verificationIdentifier: 'identifier',
    verificationValue: 'value',
    verificationExpiresAt: 'expiresAt',
    verificationCreatedAt: 'createdAt',
    verificationUpdatedAt: 'updatedAt',
  },
  emailAndPassword: {
    enabled: true,
    minPasswordLength: 8,
    maxPasswordLength: 128,
    requireEmailVerification: false,
  },
  session: {
    expiresIn: 60 * 60 * 24 * 7,
    updateAge: 60 * 60 * 24,
    disableSessionRefresh: false,
    tokenBytes: 32,
  },
  verification: {
    expiresIn: 60 * 60,
    hashToken: true,
  },
  allowedProviders: ['credential', 'google', 'github'],
});
```

## Notes

- Plugin name is `auth`, and the installed API is on `db.auth`.
- Auth tables are available on `db.auth.tables`.
- Default auth schema uses FK constraints for relational integrity:
  - `account.userId -> user.id` (`ON DELETE CASCADE`, `ON UPDATE CASCADE`)
  - `session.userId -> user.id` (`ON DELETE CASCADE`, `ON UPDATE CASCADE`)
- Exports: `authPlugin` and `withAuth`.