@spfn/auth 0.2.0-beta.46 → 0.2.0-beta.47

package/README.md

@@ -77,72 +77,95 @@ export default defineServerConfig()
     .build();
 ```
 
-#### Register Router in `router.ts`
+#### Register Router and Global Middleware in `router.ts`
 
 ```typescript
 import { defineRouter } from '@spfn/core/route';
-import { authRouter } from '@spfn/auth/server';
+import { authRouter, authenticate } from '@spfn/auth/server';
+import { getHealth } from './routes/health';
+import { createOrder } from './routes/orders';
 
 export const appRouter = defineRouter({
-    // Auth routes (fixed namespace)
-    auth: authRouter,
-
+    getHealth,
+    createOrder,
     // ... your other routes
-});
+})
+.packages([authRouter])    // Auth routes (/_auth/* namespace)
+.use([authenticate]);      // Global auth middleware on all routes
+
+export type AppRouter = typeof appRouter;
 ```
 
-### 3. Configure Client (Next.js)
+> **Important:** Public routes must explicitly skip auth with `.skip(['auth'])`.
+> See the [Authentication Guide](https://spfn.dev/docs/guides/authentication) for details.
 
-#### Option A: Use the built-in `authApi` (Recommended)
+### 3. Configure Next.js Interceptor
+
+Register the auth interceptor in your RPC proxy route. This handles session cookies, JWT signing, and key management automatically.
 
 ```typescript
-import { authApi } from '@spfn/auth';
+// app/api/rpc/[routeName]/route.ts
+import '@spfn/auth/nextjs/api';  // Must be first! Registers auth interceptor
+import { appRouter } from '@/server/router';
+import { createRpcProxy } from '@spfn/core/nextjs/server';
 
-// Type-safe API calls for auth routes
-const session = await authApi.getAuthSession.call({});
+export const { GET, POST } = createRpcProxy({ router: appRouter });
 ```
 
-#### Option B: Register Error Registry in Custom API Client
+Your API client needs no auth-specific configuration:
 
 ```typescript
+// src/lib/api-client.ts
 import { createApi } from '@spfn/core/nextjs';
 import type { AppRouter } from '@/server/router';
-import { authErrorRegistry } from "@spfn/auth/errors";
-import { appMetadata } from '@/server/router.metadata';
-import { errorRegistry } from "@spfn/core/errors";
 
-export const api = createApi<AppRouter>({
-    metadata: appMetadata,
-    errorRegistry: errorRegistry.concat(authErrorRegistry),
-});
+export const api = createApi<AppRouter>();
+```
+
+The built-in `authApi` is also available for auth-only calls:
+
+```typescript
+import { authApi } from '@spfn/auth';
+const session = await authApi.getAuthSession.call({});
 ```
 
 ### 4. Environment Variables
 
+Auth requires variables in **two separate files**: `.env.server` (SPFN backend) and `.env.local` (Next.js).
+
+#### `.env.server` (SPFN Backend)
+
 ```bash
 # Required
-SPFN_AUTH_JWT_SECRET=your-secret-key
+DATABASE_URL=postgresql://user:pass@localhost:5432/myapp_dev
 SPFN_AUTH_VERIFICATION_TOKEN_SECRET=your-verification-secret
-DATABASE_URL=postgresql://...
 
-# Next.js (required)
-SPFN_AUTH_SESSION_SECRET=your-32-char-secret
+# Admin account (required — at least one format)
+SPFN_AUTH_ADMIN_ACCOUNTS='[{"email":"admin@example.com","password":"Admin!@34","role":"superadmin"}]'
 
 # Optional
+SPFN_AUTH_JWT_SECRET=your-jwt-secret
 SPFN_AUTH_JWT_EXPIRES_IN=7d
 SPFN_AUTH_BCRYPT_SALT_ROUNDS=10
 SPFN_AUTH_SESSION_TTL=7d
 
-# Google OAuth
+# Google OAuth (optional)
 SPFN_AUTH_GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
 SPFN_AUTH_GOOGLE_CLIENT_SECRET=GOCSPX-...
-SPFN_APP_URL=http://localhost:3000
+```
+
+#### `.env.local` (Next.js)
 
-# Google OAuth (Optional)
-SPFN_AUTH_GOOGLE_SCOPES=email,profile,https://www.googleapis.com/auth/gmail.readonly
-SPFN_AUTH_GOOGLE_REDIRECT_URI=http://localhost:8790/_auth/oauth/google/callback
-SPFN_AUTH_OAUTH_SUCCESS_URL=/auth/callback
-SPFN_AUTH_OAUTH_ERROR_URL=http://localhost:3000/auth/error?error={error}
+```bash
+# Required
+DATABASE_URL=postgresql://user:pass@localhost:5432/myapp_dev
+SPFN_API_URL=http://localhost:8790
+
+# Required for session cookies (minimum 32 characters)
+SPFN_AUTH_SESSION_SECRET=my-super-secret-session-key-at-least-32-chars-long
+
+# Optional
+SPFN_AUTH_SESSION_TTL=7d
 
 # Email/SMS — configure via @spfn/notification
 # See @spfn/notification README for AWS SES/SNS settings

package/dist/{authenticate-CRDUKQbi.d.ts → authenticate-eucncHxN.d.ts}

@@ -382,6 +382,30 @@ interface AuthInitOptions {
     sessionTtl?: string | number;
 }
 
+/**
+ * One-Time Token Service
+ *
+ * Issues and verifies one-time tokens for direct API access.
+ */
+interface IssueOneTimeTokenResult {
+    token: string;
+    expiresAt: string;
+}
+/**
+ * Issue a one-time token for the authenticated user
+ *
+ * @param userId - Authenticated user's ID
+ * @returns Token string and ISO expiration timestamp
+ */
+declare function issueOneTimeTokenService(userId: string): Promise<IssueOneTimeTokenResult>;
+/**
+ * Verify and consume a one-time token
+ *
+ * @param token - The one-time token to verify
+ * @returns userId if valid, null if invalid/expired/consumed
+ */
+declare function verifyOneTimeTokenService(token: string): Promise<string | null>;
+
 /**
  * @spfn/auth - OAuth Service
  *
@@ -557,6 +581,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
         emailVerified: boolean;
         phoneVerified: boolean;
     }>;
+    issueOneTimeToken: _spfn_core_route.RouteDef<{}, {}, IssueOneTimeTokenResult>;
     oauthGoogleStart: _spfn_core_route.RouteDef<{
         query: _sinclair_typebox.TObject<{
             state: _sinclair_typebox.TString;
@@ -912,4 +937,4 @@ declare const authenticate: _spfn_core_route.NamedMiddleware<"auth">;
  */
 declare const optionalAuth: _spfn_core_route.NamedMiddleware<"optionalAuth">;
 
-export { getEnabledOAuthProviders as $, type AuthSession as A, type ChangePasswordParams as B, type CheckAccountExistsResult as C, sendVerificationCodeService as D, verifyCodeService as E, type SendVerificationCodeParams as F, type VerifyCodeParams as G, type VerifyCodeResult as H, INVITATION_STATUSES as I, registerPublicKeyService as J, KEY_ALGORITHM as K, type LoginResult as L, rotateKeyService as M, revokeKeyService as N, type OAuthStartResult as O, type PermissionConfig as P, type RegisterPublicKeyParams as Q, type RoleConfig as R, type SendVerificationCodeResult as S, type RotateKeyParams as T, type UserProfile as U, type VerificationTargetType as V, type RevokeKeyParams as W, oauthStartService as X, oauthCallbackService as Y, buildOAuthErrorUrl as Z, isOAuthProviderEnabled as _, type RegisterResult as a, getGoogleAccessToken as a0, type OAuthStartParams as a1, type OAuthCallbackParams as a2, type OAuthCallbackResult as a3, authenticate as a4, optionalAuth as a5, EmailSchema as a6, PhoneSchema as a7, PasswordSchema as a8, TargetTypeSchema as a9, VerificationPurposeSchema as aa, type RotateKeyResult as b, type ProfileInfo as c, USER_STATUSES as d, SOCIAL_PROVIDERS as e, type VerificationPurpose as f, VERIFICATION_TARGET_TYPES as g, VERIFICATION_PURPOSES as h, PERMISSION_CATEGORIES as i, type PermissionCategory as j, type AuthInitOptions as k, type KeyAlgorithmType as l, mainAuthRouter as m, type InvitationStatus as n, type UserStatus as o, type SocialProvider as p, type AuthContext as q, checkAccountExistsService as r, registerService as s, loginService as t, logoutService as u, changePasswordService as v, type CheckAccountExistsParams as w, type RegisterParams as x, type LoginParams as y, type LogoutParams as z };
+export { oauthCallbackService as $, type AuthSession as A, type LogoutParams as B, type CheckAccountExistsResult as C, type ChangePasswordParams as D, sendVerificationCodeService as E, verifyCodeService as F, type SendVerificationCodeParams as G, type VerifyCodeParams as H, type IssueOneTimeTokenResult as I, type VerifyCodeResult as J, KEY_ALGORITHM as K, type LoginResult as L, registerPublicKeyService as M, rotateKeyService as N, type OAuthStartResult as O, type PermissionConfig as P, revokeKeyService as Q, type RoleConfig as R, type SendVerificationCodeResult as S, type RegisterPublicKeyParams as T, type UserProfile as U, type VerificationTargetType as V, type RotateKeyParams as W, type RevokeKeyParams as X, issueOneTimeTokenService as Y, verifyOneTimeTokenService as Z, oauthStartService as _, type RegisterResult as a, buildOAuthErrorUrl as a0, isOAuthProviderEnabled as a1, getEnabledOAuthProviders as a2, getGoogleAccessToken as a3, type OAuthStartParams as a4, type OAuthCallbackParams as a5, type OAuthCallbackResult as a6, authenticate as a7, optionalAuth as a8, EmailSchema as a9, PhoneSchema as aa, PasswordSchema as ab, TargetTypeSchema as ac, VerificationPurposeSchema as ad, type RotateKeyResult as b, type ProfileInfo as c, INVITATION_STATUSES as d, USER_STATUSES as e, SOCIAL_PROVIDERS as f, type VerificationPurpose as g, VERIFICATION_TARGET_TYPES as h, VERIFICATION_PURPOSES as i, PERMISSION_CATEGORIES as j, type PermissionCategory as k, type AuthInitOptions as l, mainAuthRouter as m, type KeyAlgorithmType as n, type InvitationStatus as o, type UserStatus as p, type SocialProvider as q, type AuthContext as r, checkAccountExistsService as s, registerService as t, loginService as u, logoutService as v, changePasswordService as w, type CheckAccountExistsParams as x, type RegisterParams as y, type LoginParams as z };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _spfn_core_nextjs from '@spfn/core/nextjs';
-import { R as RoleConfig, P as PermissionConfig, C as CheckAccountExistsResult, S as SendVerificationCodeResult, a as RegisterResult, L as LoginResult, b as RotateKeyResult, O as OAuthStartResult, U as UserProfile, c as ProfileInfo, m as mainAuthRouter } from './authenticate-CRDUKQbi.js';
-export { k as AuthInitOptions, A as AuthSession, I as INVITATION_STATUSES, n as InvitationStatus, K as KEY_ALGORITHM, l as KeyAlgorithmType, i as PERMISSION_CATEGORIES, j as PermissionCategory, e as SOCIAL_PROVIDERS, p as SocialProvider, d as USER_STATUSES, o as UserStatus, h as VERIFICATION_PURPOSES, g as VERIFICATION_TARGET_TYPES, f as VerificationPurpose, V as VerificationTargetType } from './authenticate-CRDUKQbi.js';
+import { R as RoleConfig, P as PermissionConfig, C as CheckAccountExistsResult, S as SendVerificationCodeResult, a as RegisterResult, L as LoginResult, b as RotateKeyResult, I as IssueOneTimeTokenResult, O as OAuthStartResult, U as UserProfile, c as ProfileInfo, m as mainAuthRouter } from './authenticate-eucncHxN.js';
+export { l as AuthInitOptions, A as AuthSession, d as INVITATION_STATUSES, o as InvitationStatus, K as KEY_ALGORITHM, n as KeyAlgorithmType, j as PERMISSION_CATEGORIES, k as PermissionCategory, f as SOCIAL_PROVIDERS, q as SocialProvider, e as USER_STATUSES, p as UserStatus, i as VERIFICATION_PURPOSES, h as VERIFICATION_TARGET_TYPES, g as VerificationPurpose, V as VerificationTargetType } from './authenticate-eucncHxN.js';
 import * as _spfn_core_route from '@spfn/core/route';
 import { HttpMethod } from '@spfn/core/route';
 import * as _sinclair_typebox from '@sinclair/typebox';
@@ -177,6 +177,7 @@ declare const authApi: _spfn_core_nextjs.Client<_spfn_core_route.Router<{
         emailVerified: boolean;
         phoneVerified: boolean;
     }>;
+    issueOneTimeToken: _spfn_core_route.RouteDef<{}, {}, IssueOneTimeTokenResult>;
     oauthGoogleStart: _spfn_core_route.RouteDef<{
         query: _sinclair_typebox.TObject<{
             state: _sinclair_typebox.TString;

package/dist/index.js

@@ -172,6 +172,7 @@ var routeMap = {
   rotateKey: { method: "POST", path: "/_auth/keys/rotate" },
   changePassword: { method: "PUT", path: "/_auth/password" },
   getAuthSession: { method: "GET", path: "/_auth/session" },
+  issueOneTimeToken: { method: "POST", path: "/_auth/tokens" },
   getInvitation: { method: "GET", path: "/_auth/invitations/:token" },
   acceptInvitation: { method: "POST", path: "/_auth/invitations/accept" },
   createInvitation: { method: "POST", path: "/_auth/invitations" },