How long does Ezvento setup take?

Most stores are up and running in under 10 minutes. Create your account, add your store name and address, and start billing. You can add products later or import from Excel.

Is GST compliance automatic in Ezvento?

Yes. Ezvento automatically calculates GST based on your product HSN codes. You can export GSTR-1 and GSTR-3B reports in one click. E-invoices are generated for B2B sales automatically.

Can I use Ezvento on my tablet or phone?

Absolutely. The POS works beautifully on iPad, Android tablets, and any touchscreen device. No expensive POS hardware needed — just a device and a printer.

What happens if internet goes down while using Ezvento?

Ezvento works offline. You can keep billing, scanning barcodes, and printing receipts. When your internet comes back, everything syncs automatically. No sale is ever lost.

What is the price of Ezvento?

Ezvento starts at ₹999/month for the Launch plan (1 store, 3 users) and ₹2,499/month for the Grow plan (3 stores, 10 users). All plans include a 14-day free trial with no credit card required.

Can I track credit (udhar) sales in Ezvento?

Yes. Link a sale to a customer as credit. See all outstanding balances in one place. Send payment reminders. Record partial payments. Full credit ledger for every customer.

Do I need special hardware to use Ezvento?

No. Ezvento works on any device with a browser. For printing, any thermal receipt printer connected via USB or network will work. Barcode scanners plug in directly.

Can I manage multiple stores with Ezvento?

Yes. The Grow plan supports 3 stores, and Scale supports unlimited. See all stores from one dashboard, transfer stock between locations, and get consolidated reports.

Auth & Security

Ezvento's authentication layer combines Supabase Auth (PKCE), custom JWT claims, 2FA (TOTP), PIN-based cashier login, manager PIN approvals, and tamper-evident audit logging. Every route is protected by either API-level or page-level guards.

Auth Provider

Supabase Auth

PKCE flow, OAuth (Google)

2FA Method

TOTP

Time-based OTP with backup codes

Cashier Auth

4–6 digit PIN, no password

Audit Logging

Hash Chain

Tamper-evident activity logs

Signup Flow

New users create an account, verify their email, and get an organization + trial subscription automatically.

Enter credentials

User provides email (or phone) and password on /signup. Optionally selects a plan (Launch / Grow / Scale) from Dodo Payments.

POST /auth/v1/signup { email, password, phone? }

Email verification

Supabase sends a verification email. User clicks the magic link which returns to /auth/callback with a PKCE code.

GET /auth/callback?code=xxx&plan=grow

Tenant creation

ensureTenant() checks if a Prisma User exists. If not, it creates the tenant, user, subscription, and ORGANIZATION_OWNER role assignment in a single transaction.

prisma.$transaction -> tenant.create + user.create + subscription.create + userRoleAssignment.create

Subscription selection

New users are redirected to /payment with their selected plan. Dodo Payments handles the checkout. Existing users skip this step.

redirect: /payment?plan=grow

Onboarding wizard

First-time owners complete an onboarding wizard: store name, industry preset (retail/restaurant/wholesale), GSTIN, and first store creation.

redirect: /onboarding

Tenant Auto-Creation

ensureTenant() runs inside the auth callback. If the Supabase user has no Prisma record yet, it creates:

Tenant — subdomain derived from email prefix
User — isOwner: true, linked to the tenant
Subscription — TRIALING status with 14-day trial end
UserRoleAssignment — ORGANIZATION_OWNER role, ORG scope

All four operations run inside prisma.$transaction for atomicity.

Login Flow

Returning users authenticate, complete 2FA if required, and are routed to their persona's landing page.

Email + password

User submits credentials. Supabase validates and returns an access_token + refresh_token pair.

POST /auth/v1/token?grant_type=password

2FA check

If the user's role requires 2FA and twoFactorEnabled is false, redirect to /2fa-setup. If enabled, redirect to /2fa-verify.

if (requiresTwoFactor && !twoFactorEnabled) -> /2fa-setup

TOTP verification

User enters the 6-digit code from their authenticator app. The server verifies it against the stored secret.

POST /api/auth/2fa/verify { code: '123456' }

Persona resolution

The callback route resolves roles → personaType, sets the ezvento-persona cookie, and redirects to the default landing page.

cookie: ezvento-persona=MANAGER; redirect: /dashboard

Landing page

Single-role users go straight to their defaultLandingPath. Multi-role users go to /persona-select.

redirect: /dashboard or /cashier/counter-select or /persona-select

2FA Setup & Verification

2FA Setup (/2fa-setup)

Users with a 2FA-required role who haven't enrolled are redirected here.

User lands on /2fa-setup after login.
Server calls POST /api/auth/2fa/setup which generates a TOTP secret using generateSecret().
A QR code is generated (via qrcode package) as a data URI and displayed to the user.
User scans the QR code with Google Authenticator, Authy, or 1Password.
User enters the first 6-digit code to verify. Server confirms the secret and sets twoFactorEnabled: true on the User model.
Backup codes are generated and shown once. They can be used if the authenticator app is lost.

POST /api/auth/2fa/setup
Response: { secret, qrCode, uri }

POST /api/auth/2fa/verify
Body: { code: '123456' }
Response: { success: true, backupCodes: ['abc123', 'def456', ...] }

2FA Verification (/2fa-verify)

Every login for 2FA-required roles must pass this step.

After successful email/password authentication, the proxy checks the JWT claims requiresTwoFactor and twoFactorEnabled.
If both are true, the user is redirected to /2fa-verify.
User enters the current 6-digit code from their authenticator app.
Client POSTs to /api/auth/2fa/verify with the code.
Server verifies the code against the stored twoFactorSecret using totp.verify() with a 1-step window tolerance.
On success, the server sets a 2fa-verified cookie and redirects to the persona landing page.
On failure, the user gets 3 attempts before a cooldown is enforced.

// Proxy check (src/proxy.ts)
const twoFactorEnabled = payload.twoFactorEnabled === true
const requiresTwoFactor = payload.requiresTwoFactor === true
if (requiresTwoFactor && !twoFactorEnabled) {
  return NextResponse.redirect(new URL('/2fa-setup', request.url))
}

Roles requiring 2FA: Organization Owner, Regional Manager, Store Manager, Inventory Staff, Warehouse Manager, Accountant, and Auditor. Only Cashiers are exempt (they use PIN-fast login instead).

Password Reset

Users who forget their password can request a reset via email. The flow uses Supabase's built-in recovery mechanism with Resend for email delivery.

Request reset

User clicks 'Forgot password' and enters their email. Supabase sends a password recovery email.

POST /auth/v1/recover { email }

Email sent via Resend

The transactional email system (Resend) delivers a branded email with a secure reset link containing a Supabase recovery token.

Resend API -> user inbox

Click reset link

User clicks the link. It routes to /auth/callback?type=recovery which exchanges the code for a session and redirects to /update-password.

GET /auth/callback?type=recovery&code=xxx -> /update-password

Set new password

User enters a new password twice. Supabase updates the auth record and invalidates all existing sessions.

POST /auth/v1/user { password: 'newpass' }

Resend Email Integration

Password reset emails are sent via the Resend API using a branded template. The email includes:

Ezvento logo and brand colors
A clear CTA button with the secure reset link
Expiry warning (link expires in 1 hour)
A "Didn't request this?" security notice

All transactional emails (signup welcome, password reset, invoice, payment reminder) share the same Resend API key and domain configuration.

Session Management

Sessions are created lazily, validated on every request, and can be revoked individually or in bulk. The permission version system ensures role changes take effect immediately.

Field	Type	Description
id	String	CUID primary key
jti	String	JWT ID from Supabase (unique)
userId	String	Prisma User ID
tenantId	String	Tenant for tenant isolation
permissionVersion	Int	Snapshot of User.permissionVersion at creation
ipAddress	String?	Client IP at session creation
userAgent	String?	User agent string
deviceLabel	String?	Human-readable device name
expiresAt	DateTime	JWT exp mapped to DateTime
lastActiveAt	DateTime	Touched on every validated request
createdAt	DateTime	Session creation time
revokedAt	DateTime?	Set on force-logout
revokedById	String?	User who initiated the revocation
revokedReason	String?	Reason for revocation (e.g., 'security_breach')
scopeType	ScopeType?	Bound operational scope (e.g., STORE)
scopeIds	String[]	IDs for the bound scope
counterId	String?	Bound counter (for cashier sessions)
shiftId	String?	Bound shift (for cashier sessions)

Lazy Session Creation

Sessions are not created at login. Instead, ensureSession() is called on the first API request that needs auth:

Check if a Session row exists for the JWT's jti
If yes and not revoked → touch lastActiveAt and return
If revoked → return 401 SESSION_REVOKED
If absent → INSERT a new Session row with permissionVersion snapshot

Permission Version Invalidation

When a user's role assignments change, User.permissionVersion is incremented. On the next request:

checkPermissionVersion() compares JWT claim vs DB value
If mismatch → return 401 PERMISSION_VERSION_STALE
Client prompts re-login, which fetches a fresh JWT with updated claims
No automatic revocation needed — the JWT simply becomes invalid

Session Revocation

Two methods are available:

revokeSession({ sessionId, revokedById, reason }) — revoke a single session by its CUID
revokeAllUserSessions({ userId, revokedById, reason }) — revoke every active session for a user (force-logout)

Revoked sessions remain in the database for audit but have revokedAt set. The next request with that JWT\u0026apos;s jti fails with 401.

Scope Binding

Cashiers and helpers can bind a specific counter/location to their session via the scope selector UI:

bindSessionScope({
  sessionId,
  scopeType: 'STORE',
  scopeIds: ['store_abc'],
  counterId: 'counter_123',
  shiftId: 'shift_456',
})

Subsequent API calls validate that the requested store/counter matches the bound scope. This prevents a cashier from billing on a counter they didn't select.

PIN-Based Cashier Auth

Cashiers log in with a 4–6 digit PIN instead of a password. This enables fast shift handovers at the POS without typing long passwords.

Cashier Login Flow

Cashier navigates to /cashier (public route).
Enters their 4–6 digit PIN on the numeric keypad.
Client POSTs to /api/auth/verify-pin with { pin, counterId }.
Server finds the user by PIN hash (bcrypt), validates the counter assignment, and creates a Supabase session.
Server sets ezvento-persona=CASHIER cookie.
Cashier is redirected to /cashier/counter-select.

Manager PIN for Approvals

Cashier attempts a high-risk action (e.g., cancel a ₹5000+ bill).
Backend returns 403 APPROVAL_REQUIRED.
Client shows a PIN entry dialog.
On-duty manager enters their 4–6 digit manager PIN.
Server finds eligible approvers with anyRoleCanApprove(roles, permission), validates the PIN, and creates an ApprovalRequest.
Cashier retries the original request with X-Approval-Id: <approvalId>.

Security: PINs are stored as bcrypt hashes with a work factor of 12. The manager PIN is separate from the cashier PIN (stored in managerPin on the User model). PINs can be reset by Store Managers and Owners via USER_RESET_PIN.

JWT Claims

Ezvento uses a custom Supabase access token hook to inject tenant-specific claims into the JWT. This eliminates DB round-trips for common lookups.

Claim	Type	Description	Source
appUserId	string	Prisma User.id — the primary user identifier in our DB	custom_access_token_hook
tenantId	string	The user's tenant ID for all tenant-scoped queries	custom_access_token_hook
isOwner	boolean	True if the user is the organization owner	custom_access_token_hook
isPlatformAdmin	boolean	True if the user is a platform admin (separate from tenant RBAC)	custom_access_token_hook
permissionVersion	number	Current User.permissionVersion; stale JWTs are rejected	custom_access_token_hook
jti	string	Standard JWT claim — Supabase session ID, used for session revocation	Supabase Auth
exp	number	Standard JWT claim — Unix timestamp when the token expires	Supabase Auth
sub	string	Standard JWT claim — Supabase user UUID	Supabase Auth
email	string	Standard JWT claim — user's email address	Supabase Auth
twoFactorEnabled	boolean	Whether the user has completed TOTP enrollment	custom_access_token_hook
requiresTwoFactor	boolean	Whether the user's role mandates 2FA	custom_access_token_hook

Decoding JWT Claims

The decodeJwtClaims() helper in src/lib/api.ts base64-decodes the JWT payload without a network call:

export function decodeJwtClaims(accessToken: string) {
  const payload = JSON.parse(
    Buffer.from(accessToken.split('.')[1], 'base64').toString('utf8')
  )
  return {
    tenantId: payload.tenantId,
    appUserId: payload.appUserId,
    isOwner: payload.isOwner,
    isPlatformAdmin: payload.isPlatformAdmin,
    permissionVersion: payload.permissionVersion,
    jti: payload.jti,
    exp: payload.exp,
  }
}

This is used in both API routes and proxy middleware to make fast auth decisions without hitting the database.

Security Features

Defense-in-depth measures across the proxy, API layer, and database.

Rate Limiting

Auth routes: 10 requests per min per IP. API routes: 60 requests per min per IP. Disabled in development for E2E testing.

src/lib/rate-limit.ts + src/proxy.ts

CSRF Protection

Non-GET API requests validate the Origin/Referer header against a trusted origins list. Same-origin requests are always allowed.

src/proxy.ts (origin check for /api/* mutations)

Admin Host Guard

/admin/** returns 404 on non-admin hosts. Prevents enumeration attacks by not disclosing the admin surface.

src/proxy.ts (host check)

Session Revocation

Force-logout sets revokedAt on the Session row. Next request sees 'revoked' and returns 401. Revoke-all clears every session for a user.

src/lib/auth/sessions.ts: revokeSession() / revokeAllUserSessions()

Permission Version Invalidation

Role changes increment User.permissionVersion. JWTs with a stale version are rejected, forcing re-auth with fresh claims.

src/lib/auth/sessions.ts: checkPermissionVersion()

Audit Logging

Every significant action is logged with tamper-evident hash chains. Old values and new values are captured for compliance.

src/lib/api.ts: logActivity()

Lazy Session Creation

Sessions are created on first API call, not at login. This avoids DB writes during the OAuth callback and defers work to the first real request.

src/lib/auth/sessions.ts: ensureSession()

Scope Binding

Cashiers and helpers can bind a counter/location to their session. Subsequent requests are validated against this bound scope.

src/lib/auth/sessions.ts: bindSessionScope()

Tamper-Evident Audit Logs

Every logActivity() call computes a SHA-256 hash chain. Each log entry includes:

hash — SHA-256 of the current entry + previous hash
previousHash — the hash of the prior entry in this tenant
oldValues and newValues — before/after snapshots
approvedById and approvalId — link to manager PIN approvals

If any entry is tampered with in the database, the hash chain breaks and can be detected during an audit.

Tenant Isolation

Every database query includes a tenantId filter. This is enforced at the Prisma layer and backed by Row-Level Security (RLS) policies in PostgreSQL:

CREATE POLICY tenant_isolation ON "SalesInvoice"
  FOR ALL
  USING (tenant_id = current_setting('app.current_tenant')::uuid);

Even if an application-level filter is bypassed, RLS ensures the query only returns rows for the current tenant.

Auth & Security

Auth Provider

Supabase Auth

PKCE flow, OAuth (Google)

2FA Method

TOTP

Time-based OTP with backup codes

Cashier Auth

4–6 digit PIN, no password

Audit Logging

Hash Chain

Tamper-evident activity logs

Signup Flow

New users create an account, verify their email, and get an organization + trial subscription automatically.

Enter credentials

User provides email (or phone) and password on /signup. Optionally selects a plan (Launch / Grow / Scale) from Dodo Payments.

POST /auth/v1/signup { email, password, phone? }

Email verification

Supabase sends a verification email. User clicks the magic link which returns to /auth/callback with a PKCE code.

GET /auth/callback?code=xxx&plan=grow

Tenant creation

ensureTenant() checks if a Prisma User exists. If not, it creates the tenant, user, subscription, and ORGANIZATION_OWNER role assignment in a single transaction.

prisma.$transaction -> tenant.create + user.create + subscription.create + userRoleAssignment.create

Subscription selection

New users are redirected to /payment with their selected plan. Dodo Payments handles the checkout. Existing users skip this step.

redirect: /payment?plan=grow

Onboarding wizard

First-time owners complete an onboarding wizard: store name, industry preset (retail/restaurant/wholesale), GSTIN, and first store creation.

redirect: /onboarding

Tenant Auto-Creation

ensureTenant() runs inside the auth callback. If the Supabase user has no Prisma record yet, it creates:

Tenant — subdomain derived from email prefix
User — isOwner: true, linked to the tenant
Subscription — TRIALING status with 14-day trial end
UserRoleAssignment — ORGANIZATION_OWNER role, ORG scope

All four operations run inside prisma.$transaction for atomicity.

Login Flow

Returning users authenticate, complete 2FA if required, and are routed to their persona's landing page.

Email + password

User submits credentials. Supabase validates and returns an access_token + refresh_token pair.

POST /auth/v1/token?grant_type=password

2FA check

If the user's role requires 2FA and twoFactorEnabled is false, redirect to /2fa-setup. If enabled, redirect to /2fa-verify.

if (requiresTwoFactor && !twoFactorEnabled) -> /2fa-setup

TOTP verification

User enters the 6-digit code from their authenticator app. The server verifies it against the stored secret.

POST /api/auth/2fa/verify { code: '123456' }

Persona resolution

The callback route resolves roles → personaType, sets the ezvento-persona cookie, and redirects to the default landing page.

cookie: ezvento-persona=MANAGER; redirect: /dashboard

Landing page

Single-role users go straight to their defaultLandingPath. Multi-role users go to /persona-select.

redirect: /dashboard or /cashier/counter-select or /persona-select

2FA Setup & Verification

2FA Setup (/2fa-setup)

Users with a 2FA-required role who haven't enrolled are redirected here.

User lands on /2fa-setup after login.
Server calls POST /api/auth/2fa/setup which generates a TOTP secret using generateSecret().
A QR code is generated (via qrcode package) as a data URI and displayed to the user.
User scans the QR code with Google Authenticator, Authy, or 1Password.
User enters the first 6-digit code to verify. Server confirms the secret and sets twoFactorEnabled: true on the User model.
Backup codes are generated and shown once. They can be used if the authenticator app is lost.

POST /api/auth/2fa/setup
Response: { secret, qrCode, uri }

POST /api/auth/2fa/verify
Body: { code: '123456' }
Response: { success: true, backupCodes: ['abc123', 'def456', ...] }

2FA Verification (/2fa-verify)

Every login for 2FA-required roles must pass this step.

After successful email/password authentication, the proxy checks the JWT claims requiresTwoFactor and twoFactorEnabled.
If both are true, the user is redirected to /2fa-verify.
User enters the current 6-digit code from their authenticator app.
Client POSTs to /api/auth/2fa/verify with the code.
Server verifies the code against the stored twoFactorSecret using totp.verify() with a 1-step window tolerance.
On success, the server sets a 2fa-verified cookie and redirects to the persona landing page.
On failure, the user gets 3 attempts before a cooldown is enforced.

// Proxy check (src/proxy.ts)
const twoFactorEnabled = payload.twoFactorEnabled === true
const requiresTwoFactor = payload.requiresTwoFactor === true
if (requiresTwoFactor && !twoFactorEnabled) {
  return NextResponse.redirect(new URL('/2fa-setup', request.url))
}

Roles requiring 2FA: Organization Owner, Regional Manager, Store Manager, Inventory Staff, Warehouse Manager, Accountant, and Auditor. Only Cashiers are exempt (they use PIN-fast login instead).

Password Reset

Users who forget their password can request a reset via email. The flow uses Supabase's built-in recovery mechanism with Resend for email delivery.

Request reset

User clicks 'Forgot password' and enters their email. Supabase sends a password recovery email.

POST /auth/v1/recover { email }

Email sent via Resend

The transactional email system (Resend) delivers a branded email with a secure reset link containing a Supabase recovery token.

Resend API -> user inbox

Click reset link

User clicks the link. It routes to /auth/callback?type=recovery which exchanges the code for a session and redirects to /update-password.

GET /auth/callback?type=recovery&code=xxx -> /update-password

Set new password

User enters a new password twice. Supabase updates the auth record and invalidates all existing sessions.

POST /auth/v1/user { password: 'newpass' }

Resend Email Integration

Password reset emails are sent via the Resend API using a branded template. The email includes:

Ezvento logo and brand colors
A clear CTA button with the secure reset link
Expiry warning (link expires in 1 hour)
A "Didn't request this?" security notice

All transactional emails (signup welcome, password reset, invoice, payment reminder) share the same Resend API key and domain configuration.

Session Management

Sessions are created lazily, validated on every request, and can be revoked individually or in bulk. The permission version system ensures role changes take effect immediately.

Field	Type	Description
id	String	CUID primary key
jti	String	JWT ID from Supabase (unique)
userId	String	Prisma User ID
tenantId	String	Tenant for tenant isolation
permissionVersion	Int	Snapshot of User.permissionVersion at creation
ipAddress	String?	Client IP at session creation
userAgent	String?	User agent string
deviceLabel	String?	Human-readable device name
expiresAt	DateTime	JWT exp mapped to DateTime
lastActiveAt	DateTime	Touched on every validated request
createdAt	DateTime	Session creation time
revokedAt	DateTime?	Set on force-logout
revokedById	String?	User who initiated the revocation
revokedReason	String?	Reason for revocation (e.g., 'security_breach')
scopeType	ScopeType?	Bound operational scope (e.g., STORE)
scopeIds	String[]	IDs for the bound scope
counterId	String?	Bound counter (for cashier sessions)
shiftId	String?	Bound shift (for cashier sessions)

Lazy Session Creation

Sessions are not created at login. Instead, ensureSession() is called on the first API request that needs auth:

Check if a Session row exists for the JWT's jti
If yes and not revoked → touch lastActiveAt and return
If revoked → return 401 SESSION_REVOKED
If absent → INSERT a new Session row with permissionVersion snapshot

Permission Version Invalidation

When a user's role assignments change, User.permissionVersion is incremented. On the next request:

checkPermissionVersion() compares JWT claim vs DB value
If mismatch → return 401 PERMISSION_VERSION_STALE
Client prompts re-login, which fetches a fresh JWT with updated claims
No automatic revocation needed — the JWT simply becomes invalid

Session Revocation

Two methods are available:

revokeSession({ sessionId, revokedById, reason }) — revoke a single session by its CUID
revokeAllUserSessions({ userId, revokedById, reason }) — revoke every active session for a user (force-logout)

Revoked sessions remain in the database for audit but have revokedAt set. The next request with that JWT\u0026apos;s jti fails with 401.

Scope Binding

Cashiers and helpers can bind a specific counter/location to their session via the scope selector UI:

bindSessionScope({
  sessionId,
  scopeType: 'STORE',
  scopeIds: ['store_abc'],
  counterId: 'counter_123',
  shiftId: 'shift_456',
})

Subsequent API calls validate that the requested store/counter matches the bound scope. This prevents a cashier from billing on a counter they didn't select.

PIN-Based Cashier Auth

Cashiers log in with a 4–6 digit PIN instead of a password. This enables fast shift handovers at the POS without typing long passwords.

Cashier Login Flow

Cashier navigates to /cashier (public route).
Enters their 4–6 digit PIN on the numeric keypad.
Client POSTs to /api/auth/verify-pin with { pin, counterId }.
Server finds the user by PIN hash (bcrypt), validates the counter assignment, and creates a Supabase session.
Server sets ezvento-persona=CASHIER cookie.
Cashier is redirected to /cashier/counter-select.

Manager PIN for Approvals

Cashier attempts a high-risk action (e.g., cancel a ₹5000+ bill).
Backend returns 403 APPROVAL_REQUIRED.
Client shows a PIN entry dialog.
On-duty manager enters their 4–6 digit manager PIN.
Server finds eligible approvers with anyRoleCanApprove(roles, permission), validates the PIN, and creates an ApprovalRequest.
Cashier retries the original request with X-Approval-Id: <approvalId>.

JWT Claims

Ezvento uses a custom Supabase access token hook to inject tenant-specific claims into the JWT. This eliminates DB round-trips for common lookups.

Claim	Type	Description	Source
appUserId	string	Prisma User.id — the primary user identifier in our DB	custom_access_token_hook
tenantId	string	The user's tenant ID for all tenant-scoped queries	custom_access_token_hook
isOwner	boolean	True if the user is the organization owner	custom_access_token_hook
isPlatformAdmin	boolean	True if the user is a platform admin (separate from tenant RBAC)	custom_access_token_hook
permissionVersion	number	Current User.permissionVersion; stale JWTs are rejected	custom_access_token_hook
jti	string	Standard JWT claim — Supabase session ID, used for session revocation	Supabase Auth
exp	number	Standard JWT claim — Unix timestamp when the token expires	Supabase Auth
sub	string	Standard JWT claim — Supabase user UUID	Supabase Auth
email	string	Standard JWT claim — user's email address	Supabase Auth
twoFactorEnabled	boolean	Whether the user has completed TOTP enrollment	custom_access_token_hook
requiresTwoFactor	boolean	Whether the user's role mandates 2FA	custom_access_token_hook

Decoding JWT Claims

The decodeJwtClaims() helper in src/lib/api.ts base64-decodes the JWT payload without a network call:

export function decodeJwtClaims(accessToken: string) {
  const payload = JSON.parse(
    Buffer.from(accessToken.split('.')[1], 'base64').toString('utf8')
  )
  return {
    tenantId: payload.tenantId,
    appUserId: payload.appUserId,
    isOwner: payload.isOwner,
    isPlatformAdmin: payload.isPlatformAdmin,
    permissionVersion: payload.permissionVersion,
    jti: payload.jti,
    exp: payload.exp,
  }
}

This is used in both API routes and proxy middleware to make fast auth decisions without hitting the database.

Security Features

Defense-in-depth measures across the proxy, API layer, and database.

Rate Limiting

Auth routes: 10 requests per min per IP. API routes: 60 requests per min per IP. Disabled in development for E2E testing.

src/lib/rate-limit.ts + src/proxy.ts

CSRF Protection

Non-GET API requests validate the Origin/Referer header against a trusted origins list. Same-origin requests are always allowed.

src/proxy.ts (origin check for /api/* mutations)

Admin Host Guard

/admin/** returns 404 on non-admin hosts. Prevents enumeration attacks by not disclosing the admin surface.

src/proxy.ts (host check)

Session Revocation

Force-logout sets revokedAt on the Session row. Next request sees 'revoked' and returns 401. Revoke-all clears every session for a user.

src/lib/auth/sessions.ts: revokeSession() / revokeAllUserSessions()

Permission Version Invalidation

Role changes increment User.permissionVersion. JWTs with a stale version are rejected, forcing re-auth with fresh claims.

src/lib/auth/sessions.ts: checkPermissionVersion()

Audit Logging

Every significant action is logged with tamper-evident hash chains. Old values and new values are captured for compliance.

src/lib/api.ts: logActivity()

Lazy Session Creation

Sessions are created on first API call, not at login. This avoids DB writes during the OAuth callback and defers work to the first real request.

src/lib/auth/sessions.ts: ensureSession()

Scope Binding

Cashiers and helpers can bind a counter/location to their session. Subsequent requests are validated against this bound scope.

src/lib/auth/sessions.ts: bindSessionScope()

Tamper-Evident Audit Logs

Every logActivity() call computes a SHA-256 hash chain. Each log entry includes:

hash — SHA-256 of the current entry + previous hash
previousHash — the hash of the prior entry in this tenant
oldValues and newValues — before/after snapshots
approvedById and approvalId — link to manager PIN approvals

If any entry is tampered with in the database, the hash chain breaks and can be detected during an audit.

Tenant Isolation

Every database query includes a tenantId filter. This is enforced at the Prisma layer and backed by Row-Level Security (RLS) policies in PostgreSQL:

CREATE POLICY tenant_isolation ON "SalesInvoice"
  FOR ALL
  USING (tenant_id = current_setting('app.current_tenant')::uuid);

Even if an application-level filter is bypassed, RLS ensures the query only returns rows for the current tenant.