@owlmeans/server-auth 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +490 -0
- package/build/.gitkeep +0 -0
- package/build/actions/index.d.ts +2 -0
- package/build/actions/index.d.ts.map +1 -0
- package/build/actions/index.js +2 -0
- package/build/actions/index.js.map +1 -0
- package/build/actions/service.d.ts +4 -0
- package/build/actions/service.d.ts.map +1 -0
- package/build/actions/service.js +7 -0
- package/build/actions/service.js.map +1 -0
- package/build/consts.d.ts +5 -0
- package/build/consts.d.ts.map +1 -0
- package/build/consts.js +5 -0
- package/build/consts.js.map +1 -0
- package/build/index.d.ts +6 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +5 -0
- package/build/index.js.map +1 -0
- package/build/manager/actions/index.d.ts +2 -0
- package/build/manager/actions/index.d.ts.map +1 -0
- package/build/manager/actions/index.js +2 -0
- package/build/manager/actions/index.js.map +1 -0
- package/build/manager/actions/manager.d.ts +6 -0
- package/build/manager/actions/manager.d.ts.map +1 -0
- package/build/manager/actions/manager.js +10 -0
- package/build/manager/actions/manager.js.map +1 -0
- package/build/manager/consts.d.ts +3 -0
- package/build/manager/consts.d.ts.map +1 -0
- package/build/manager/consts.js +3 -0
- package/build/manager/consts.js.map +1 -0
- package/build/manager/context.d.ts +3 -0
- package/build/manager/context.d.ts.map +1 -0
- package/build/manager/context.js +26 -0
- package/build/manager/context.js.map +1 -0
- package/build/manager/exports.d.ts +16 -0
- package/build/manager/exports.d.ts.map +1 -0
- package/build/manager/exports.js +13 -0
- package/build/manager/exports.js.map +1 -0
- package/build/manager/index.d.ts +11 -0
- package/build/manager/index.d.ts.map +1 -0
- package/build/manager/index.js +10 -0
- package/build/manager/index.js.map +1 -0
- package/build/manager/main.d.ts +3 -0
- package/build/manager/main.d.ts.map +1 -0
- package/build/manager/main.js +7 -0
- package/build/manager/main.js.map +1 -0
- package/build/manager/model.d.ts +3 -0
- package/build/manager/model.d.ts.map +1 -0
- package/build/manager/model.js +68 -0
- package/build/manager/model.js.map +1 -0
- package/build/manager/modules.d.ts +2 -0
- package/build/manager/modules.d.ts.map +1 -0
- package/build/manager/modules.js +21 -0
- package/build/manager/modules.js.map +1 -0
- package/build/manager/plugins/basic-ed25519.d.ts +4 -0
- package/build/manager/plugins/basic-ed25519.d.ts.map +1 -0
- package/build/manager/plugins/basic-ed25519.js +42 -0
- package/build/manager/plugins/basic-ed25519.js.map +1 -0
- package/build/manager/plugins/basic-rely.d.ts +4 -0
- package/build/manager/plugins/basic-rely.d.ts.map +1 -0
- package/build/manager/plugins/basic-rely.js +152 -0
- package/build/manager/plugins/basic-rely.js.map +1 -0
- package/build/manager/plugins/export.d.ts +6 -0
- package/build/manager/plugins/export.d.ts.map +1 -0
- package/build/manager/plugins/export.js +5 -0
- package/build/manager/plugins/export.js.map +1 -0
- package/build/manager/plugins/index.d.ts +4 -0
- package/build/manager/plugins/index.d.ts.map +1 -0
- package/build/manager/plugins/index.js +9 -0
- package/build/manager/plugins/index.js.map +1 -0
- package/build/manager/plugins/re-captcha.d.ts +4 -0
- package/build/manager/plugins/re-captcha.d.ts.map +1 -0
- package/build/manager/plugins/re-captcha.js +49 -0
- package/build/manager/plugins/re-captcha.js.map +1 -0
- package/build/manager/plugins/types.d.ts +25 -0
- package/build/manager/plugins/types.d.ts.map +1 -0
- package/build/manager/plugins/types.js +2 -0
- package/build/manager/plugins/types.js.map +1 -0
- package/build/manager/plugins/utils.d.ts +8 -0
- package/build/manager/plugins/utils.d.ts.map +1 -0
- package/build/manager/plugins/utils.js +18 -0
- package/build/manager/plugins/utils.js.map +1 -0
- package/build/manager/rely/flow.d.ts +5 -0
- package/build/manager/rely/flow.d.ts.map +1 -0
- package/build/manager/rely/flow.js +127 -0
- package/build/manager/rely/flow.js.map +1 -0
- package/build/manager/rely/index.d.ts +2 -0
- package/build/manager/rely/index.d.ts.map +1 -0
- package/build/manager/rely/index.js +2 -0
- package/build/manager/rely/index.js.map +1 -0
- package/build/manager/rely.d.ts +3 -0
- package/build/manager/rely.d.ts.map +1 -0
- package/build/manager/rely.js +63 -0
- package/build/manager/rely.js.map +1 -0
- package/build/manager/types.d.ts +33 -0
- package/build/manager/types.d.ts.map +1 -0
- package/build/manager/types.js +2 -0
- package/build/manager/types.js.map +1 -0
- package/build/manager/utils/index.d.ts +2 -0
- package/build/manager/utils/index.d.ts.map +1 -0
- package/build/manager/utils/index.js +2 -0
- package/build/manager/utils/index.js.map +1 -0
- package/build/manager/utils/trusted.d.ts +5 -0
- package/build/manager/utils/trusted.d.ts.map +1 -0
- package/build/manager/utils/trusted.js +11 -0
- package/build/manager/utils/trusted.js.map +1 -0
- package/build/model/index.d.ts +2 -0
- package/build/model/index.d.ts.map +1 -0
- package/build/model/index.js +2 -0
- package/build/model/index.js.map +1 -0
- package/build/model/rely/consumer.d.ts +3 -0
- package/build/model/rely/consumer.d.ts.map +1 -0
- package/build/model/rely/consumer.js +9 -0
- package/build/model/rely/consumer.js.map +1 -0
- package/build/model/rely/index.d.ts +5 -0
- package/build/model/rely/index.d.ts.map +1 -0
- package/build/model/rely/index.js +4 -0
- package/build/model/rely/index.js.map +1 -0
- package/build/model/rely/peer.d.ts +5 -0
- package/build/model/rely/peer.d.ts.map +1 -0
- package/build/model/rely/peer.js +36 -0
- package/build/model/rely/peer.js.map +1 -0
- package/build/model/rely/provider.d.ts +3 -0
- package/build/model/rely/provider.d.ts.map +1 -0
- package/build/model/rely/provider.js +6 -0
- package/build/model/rely/provider.js.map +1 -0
- package/build/model/rely/types.d.ts +8 -0
- package/build/model/rely/types.d.ts.map +1 -0
- package/build/model/rely/types.js +2 -0
- package/build/model/rely/types.js.map +1 -0
- package/build/modules.d.ts +3 -0
- package/build/modules.d.ts.map +1 -0
- package/build/modules.js +11 -0
- package/build/modules.js.map +1 -0
- package/build/service.d.ts +7 -0
- package/build/service.d.ts.map +1 -0
- package/build/service.js +90 -0
- package/build/service.js.map +1 -0
- package/build/types.d.ts +13 -0
- package/build/types.d.ts.map +1 -0
- package/build/types.js +2 -0
- package/build/types.js.map +1 -0
- package/package.json +76 -0
- package/src/actions/index.ts +2 -0
- package/src/actions/service.ts +16 -0
- package/src/consts.ts +8 -0
- package/src/index.ts +6 -0
- package/src/manager/README.md +507 -0
- package/src/manager/actions/index.ts +2 -0
- package/src/manager/actions/manager.ts +23 -0
- package/src/manager/consts.ts +4 -0
- package/src/manager/context.ts +33 -0
- package/src/manager/exports.ts +17 -0
- package/src/manager/index.ts +11 -0
- package/src/manager/main.ts +9 -0
- package/src/manager/model.ts +93 -0
- package/src/manager/modules.ts +29 -0
- package/src/manager/plugins/basic-ed25519.ts +56 -0
- package/src/manager/plugins/basic-rely.ts +167 -0
- package/src/manager/plugins/export.ts +6 -0
- package/src/manager/plugins/index.ts +13 -0
- package/src/manager/plugins/re-captcha.ts +62 -0
- package/src/manager/plugins/types.ts +27 -0
- package/src/manager/plugins/utils.ts +21 -0
- package/src/manager/rely/flow.ts +135 -0
- package/src/manager/rely/index.ts +2 -0
- package/src/manager/rely.ts +90 -0
- package/src/manager/types.ts +42 -0
- package/src/manager/utils/index.ts +2 -0
- package/src/manager/utils/trusted.ts +16 -0
- package/src/model/index.ts +2 -0
- package/src/model/rely/consumer.ts +11 -0
- package/src/model/rely/index.ts +5 -0
- package/src/model/rely/peer.ts +43 -0
- package/src/model/rely/provider.ts +9 -0
- package/src/model/rely/types.ts +8 -0
- package/src/modules.ts +17 -0
- package/src/service.ts +126 -0
- package/src/types.ts +15 -0
- package/tsconfig.json +15 -0
- package/tsconfig.tsbuildinfo +1 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,490 @@
|
|
|
1
|
+
# @owlmeans/server-auth
|
|
2
|
+
|
|
3
|
+
Server-side authentication service for OwlMeans Common applications. This package provides a comprehensive server authentication implementation with Ed25519 signature verification, token management, cache integration, and centralized authentication hub capabilities.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
The `@owlmeans/server-auth` package delivers server-side authentication functionality for the OwlMeans ecosystem, offering:
|
|
8
|
+
|
|
9
|
+
- **Authentication Service**: Server-side authentication with Ed25519 signature verification
|
|
10
|
+
- **Token Management**: Authentication token creation, validation, and lifecycle management
|
|
11
|
+
- **Guard Integration**: Seamless integration with OwlMeans module guard system
|
|
12
|
+
- **Cache Support**: Authentication state caching for performance optimization
|
|
13
|
+
- **Central Auth Hub**: Complete authentication manager application for centralized authentication
|
|
14
|
+
- **Trusted Entity Support**: Integration with trusted service authentication
|
|
15
|
+
|
|
16
|
+
This package follows the OwlMeans "quadra" pattern as a server-side implementation complementing `@owlmeans/auth-common` and working with client authentication packages.
|
|
17
|
+
|
|
18
|
+
## Installation
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install @owlmeans/server-auth
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Dependencies
|
|
25
|
+
|
|
26
|
+
This package requires and integrates with:
|
|
27
|
+
- `@owlmeans/auth`: Core authentication types and validation
|
|
28
|
+
- `@owlmeans/auth-common`: Common authentication components
|
|
29
|
+
- `@owlmeans/basic-envelope`: Cryptographic message envelopes
|
|
30
|
+
- `@owlmeans/server-context`: Server context management
|
|
31
|
+
- `@owlmeans/basic-keys`: Cryptographic operations
|
|
32
|
+
- `@owlmeans/static-resource`: Resource management
|
|
33
|
+
|
|
34
|
+
## Core Concepts
|
|
35
|
+
|
|
36
|
+
### Authentication Service
|
|
37
|
+
|
|
38
|
+
The server authentication service handles token validation, signature verification, and authentication state management using Ed25519 cryptographic signatures.
|
|
39
|
+
|
|
40
|
+
### Token Verification
|
|
41
|
+
|
|
42
|
+
Implements secure token verification using envelope-based signatures and trusted entity validation, ensuring non-repudiable authentication.
|
|
43
|
+
|
|
44
|
+
### Central Auth Hub
|
|
45
|
+
|
|
46
|
+
Includes a complete authentication manager application that can serve as a centralized authentication hub for microservices architectures.
|
|
47
|
+
|
|
48
|
+
## API Reference
|
|
49
|
+
|
|
50
|
+
### Types
|
|
51
|
+
|
|
52
|
+
#### `AuthService`
|
|
53
|
+
Main server authentication service interface extending GuardService.
|
|
54
|
+
|
|
55
|
+
```typescript
|
|
56
|
+
interface AuthService extends GuardService {
|
|
57
|
+
authenticate: (token: AuthToken) => Promise<AuthToken>
|
|
58
|
+
unpack: (token: string) => Promise<Auth>
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
**Methods:**
|
|
63
|
+
- **`authenticate(token: AuthToken): Promise<AuthToken>`**: Validates and processes authentication token
|
|
64
|
+
- **`unpack(token: string): Promise<Auth>`**: Unpacks and verifies authentication token to extract Auth object
|
|
65
|
+
|
|
66
|
+
#### `AuthServiceAppend`
|
|
67
|
+
Interface for contexts that provide authentication service access.
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
interface AuthServiceAppend {
|
|
71
|
+
auth: () => AuthService
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
#### `AuthSpent`
|
|
76
|
+
Interface for authentication cache records.
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
interface AuthSpent extends ResourceRecord {
|
|
80
|
+
// Cache record for authentication state
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Factory Functions
|
|
85
|
+
|
|
86
|
+
#### `makeAuthService(alias?: string): AuthService`
|
|
87
|
+
|
|
88
|
+
Creates a server authentication service instance with signature verification capabilities.
|
|
89
|
+
|
|
90
|
+
**Parameters:**
|
|
91
|
+
- `alias` (optional): Service alias (default: `DEFAULT_ALIAS`)
|
|
92
|
+
|
|
93
|
+
**Returns:** AuthService instance
|
|
94
|
+
|
|
95
|
+
**Features:**
|
|
96
|
+
- Ed25519 signature verification
|
|
97
|
+
- Token unpacking and validation
|
|
98
|
+
- Cache integration for performance
|
|
99
|
+
- Trusted entity authentication
|
|
100
|
+
|
|
101
|
+
**Example:**
|
|
102
|
+
```typescript
|
|
103
|
+
import { makeAuthService } from '@owlmeans/server-auth'
|
|
104
|
+
|
|
105
|
+
const authService = makeAuthService('auth')
|
|
106
|
+
|
|
107
|
+
// Use as a guard service
|
|
108
|
+
const isAuthenticated = await authService.match(request)
|
|
109
|
+
if (isAuthenticated) {
|
|
110
|
+
const result = await authService.handle(request, response)
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
// Authenticate tokens
|
|
114
|
+
const validatedToken = await authService.authenticate(authToken)
|
|
115
|
+
|
|
116
|
+
// Unpack tokens to Auth objects
|
|
117
|
+
const auth = await authService.unpack(bearerToken)
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Service Methods
|
|
121
|
+
|
|
122
|
+
#### `match(req: AbstractRequest): Promise<boolean>`
|
|
123
|
+
|
|
124
|
+
Checks if a request contains valid authentication token format.
|
|
125
|
+
|
|
126
|
+
**Parameters:**
|
|
127
|
+
- `req`: Request object to check for authentication
|
|
128
|
+
|
|
129
|
+
**Returns:** Promise resolving to boolean indicating if auth token is present
|
|
130
|
+
|
|
131
|
+
**Example:**
|
|
132
|
+
```typescript
|
|
133
|
+
const hasAuth = await authService.match(req)
|
|
134
|
+
if (hasAuth) {
|
|
135
|
+
// Request has authentication token
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
#### `handle<T>(req: AbstractRequest, res: AbstractResponse<Auth>): Promise<T>`
|
|
140
|
+
|
|
141
|
+
Processes authentication request and validates the token signature.
|
|
142
|
+
|
|
143
|
+
**Parameters:**
|
|
144
|
+
- `req`: Request object with authentication token
|
|
145
|
+
- `res`: Response object to resolve with Auth data
|
|
146
|
+
|
|
147
|
+
**Returns:** Promise resolving to boolean indicating success
|
|
148
|
+
|
|
149
|
+
**Process:**
|
|
150
|
+
1. Extracts Ed25519 token from request
|
|
151
|
+
2. Creates envelope from token
|
|
152
|
+
3. Verifies signature against trusted entity
|
|
153
|
+
4. Resolves response with Auth object on success
|
|
154
|
+
|
|
155
|
+
**Example:**
|
|
156
|
+
```typescript
|
|
157
|
+
const success = await authService.handle(req, res)
|
|
158
|
+
if (success) {
|
|
159
|
+
// Authentication successful, Auth data available in res
|
|
160
|
+
}
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
#### `authenticate(token: AuthToken): Promise<AuthToken>`
|
|
164
|
+
|
|
165
|
+
Validates and processes an authentication token.
|
|
166
|
+
|
|
167
|
+
**Parameters:**
|
|
168
|
+
- `token`: Authentication token to validate
|
|
169
|
+
|
|
170
|
+
**Returns:** Promise resolving to validated AuthToken
|
|
171
|
+
|
|
172
|
+
**Throws:** `AuthenFailed` if token validation fails
|
|
173
|
+
|
|
174
|
+
**Example:**
|
|
175
|
+
```typescript
|
|
176
|
+
try {
|
|
177
|
+
const validToken = await authService.authenticate(userToken)
|
|
178
|
+
// Token is valid and can be used
|
|
179
|
+
} catch (error) {
|
|
180
|
+
if (error instanceof AuthenFailed) {
|
|
181
|
+
// Handle authentication failure
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
#### `unpack(token: string): Promise<Auth>`
|
|
187
|
+
|
|
188
|
+
Unpacks a bearer token string and extracts the Auth object.
|
|
189
|
+
|
|
190
|
+
**Parameters:**
|
|
191
|
+
- `token`: Bearer token string (e.g., "Bearer ed25519:...")
|
|
192
|
+
|
|
193
|
+
**Returns:** Promise resolving to Auth object
|
|
194
|
+
|
|
195
|
+
**Process:**
|
|
196
|
+
1. Splits bearer token to extract authorization part
|
|
197
|
+
2. Creates envelope from token
|
|
198
|
+
3. Verifies signature against trusted entity
|
|
199
|
+
4. Returns unpacked Auth object
|
|
200
|
+
|
|
201
|
+
**Example:**
|
|
202
|
+
```typescript
|
|
203
|
+
const bearerToken = "Bearer ed25519:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
|
|
204
|
+
const auth = await authService.unpack(bearerToken)
|
|
205
|
+
|
|
206
|
+
console.log(auth.userId) // Access user information
|
|
207
|
+
console.log(auth.role) // Access user role
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### Constants
|
|
211
|
+
|
|
212
|
+
#### Authentication Constants
|
|
213
|
+
|
|
214
|
+
```typescript
|
|
215
|
+
const DEFAULT_ALIAS = 'auth' // Default service alias
|
|
216
|
+
const AUTH_CACHE = 'auth-cache' // Cache resource name
|
|
217
|
+
const AUTH_SRV_KEY = 'server-auth-key' // Server key identifier
|
|
218
|
+
const AUTHEN_TIMEFRAME = 60 * 60 * 1000 // Authentication timeframe (1 hour)
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### Modules
|
|
222
|
+
|
|
223
|
+
The package provides predefined authentication modules for server-side routing. These modules are automatically configured with proper validation schemas and authentication handlers.
|
|
224
|
+
|
|
225
|
+
```typescript
|
|
226
|
+
import { modules } from '@owlmeans/server-auth'
|
|
227
|
+
|
|
228
|
+
// Modules include server-side authentication endpoints
|
|
229
|
+
// with proper request/response validation
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## Usage Examples
|
|
233
|
+
|
|
234
|
+
### Basic Server Authentication Setup
|
|
235
|
+
|
|
236
|
+
```typescript
|
|
237
|
+
import { makeAuthService } from '@owlmeans/server-auth'
|
|
238
|
+
import { makeServerContext } from '@owlmeans/server-context'
|
|
239
|
+
|
|
240
|
+
// Create server context
|
|
241
|
+
const context = makeServerContext({
|
|
242
|
+
service: 'auth-server',
|
|
243
|
+
type: AppType.Backend,
|
|
244
|
+
layer: Layer.Service
|
|
245
|
+
})
|
|
246
|
+
|
|
247
|
+
// Create and register authentication service
|
|
248
|
+
const authService = makeAuthService('auth')
|
|
249
|
+
context.registerService(authService)
|
|
250
|
+
|
|
251
|
+
await context.configure().init()
|
|
252
|
+
|
|
253
|
+
// Service is now available for authentication
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
### Using as Module Guard
|
|
257
|
+
|
|
258
|
+
```typescript
|
|
259
|
+
import { guard } from '@owlmeans/module'
|
|
260
|
+
|
|
261
|
+
// Create module with authentication guard
|
|
262
|
+
const protectedModule = module(
|
|
263
|
+
route('protected', '/api/protected'),
|
|
264
|
+
guard('auth') // References the auth service
|
|
265
|
+
)
|
|
266
|
+
|
|
267
|
+
// The auth service will automatically validate tokens for this module
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
### Manual Token Validation
|
|
271
|
+
|
|
272
|
+
```typescript
|
|
273
|
+
const authService = makeAuthService()
|
|
274
|
+
|
|
275
|
+
// Validate incoming request
|
|
276
|
+
const isValid = await authService.match(req)
|
|
277
|
+
if (isValid) {
|
|
278
|
+
const success = await authService.handle(req, res)
|
|
279
|
+
if (success) {
|
|
280
|
+
// Authentication successful
|
|
281
|
+
const auth = res.value // Auth object
|
|
282
|
+
console.log(`Authenticated user: ${auth.userId}`)
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
### Token Processing
|
|
288
|
+
|
|
289
|
+
```typescript
|
|
290
|
+
// Process authentication token
|
|
291
|
+
try {
|
|
292
|
+
const authToken = { token: 'user-auth-token' }
|
|
293
|
+
const validatedToken = await authService.authenticate(authToken)
|
|
294
|
+
|
|
295
|
+
// Token is now validated and can be used
|
|
296
|
+
console.log('Token validated successfully')
|
|
297
|
+
} catch (error) {
|
|
298
|
+
console.error('Authentication failed:', error.message)
|
|
299
|
+
}
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### Bearer Token Unpacking
|
|
303
|
+
|
|
304
|
+
```typescript
|
|
305
|
+
// Extract Auth from bearer token
|
|
306
|
+
const bearerToken = req.headers.authorization // "Bearer ed25519:..."
|
|
307
|
+
|
|
308
|
+
try {
|
|
309
|
+
const auth = await authService.unpack(bearerToken)
|
|
310
|
+
|
|
311
|
+
// Use Auth object
|
|
312
|
+
console.log(`User: ${auth.userId}, Role: ${auth.role}`)
|
|
313
|
+
console.log(`Scopes: ${auth.scopes.join(', ')}`)
|
|
314
|
+
} catch (error) {
|
|
315
|
+
console.error('Token unpacking failed:', error)
|
|
316
|
+
}
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
### Integration with Express.js
|
|
320
|
+
|
|
321
|
+
```typescript
|
|
322
|
+
import express from 'express'
|
|
323
|
+
|
|
324
|
+
const app = express()
|
|
325
|
+
const authService = makeAuthService()
|
|
326
|
+
|
|
327
|
+
// Authentication middleware
|
|
328
|
+
app.use(async (req, res, next) => {
|
|
329
|
+
const hasAuth = await authService.match(req)
|
|
330
|
+
|
|
331
|
+
if (hasAuth) {
|
|
332
|
+
try {
|
|
333
|
+
const authRes = { resolve: (auth) => { req.auth = auth } }
|
|
334
|
+
await authService.handle(req, authRes)
|
|
335
|
+
next()
|
|
336
|
+
} catch (error) {
|
|
337
|
+
res.status(401).json({ error: 'Authentication failed' })
|
|
338
|
+
}
|
|
339
|
+
} else {
|
|
340
|
+
res.status(401).json({ error: 'No authentication provided' })
|
|
341
|
+
}
|
|
342
|
+
})
|
|
343
|
+
|
|
344
|
+
// Protected routes
|
|
345
|
+
app.get('/api/protected', (req, res) => {
|
|
346
|
+
res.json({
|
|
347
|
+
message: 'Access granted',
|
|
348
|
+
user: req.auth.userId
|
|
349
|
+
})
|
|
350
|
+
})
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
### Cache Integration
|
|
354
|
+
|
|
355
|
+
```typescript
|
|
356
|
+
// Service automatically uses cache for performance
|
|
357
|
+
// Cache resource should be configured in context
|
|
358
|
+
|
|
359
|
+
const context = makeServerContext({
|
|
360
|
+
service: 'auth-app',
|
|
361
|
+
// ... other config
|
|
362
|
+
resources: [{
|
|
363
|
+
alias: 'auth-cache',
|
|
364
|
+
type: 'redis', // or other cache implementation
|
|
365
|
+
config: {
|
|
366
|
+
// cache configuration
|
|
367
|
+
}
|
|
368
|
+
}]
|
|
369
|
+
})
|
|
370
|
+
|
|
371
|
+
const authService = makeAuthService()
|
|
372
|
+
context.registerService(authService)
|
|
373
|
+
|
|
374
|
+
// Cache is automatically used for authentication state
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
### Multi-Service Authentication
|
|
378
|
+
|
|
379
|
+
```typescript
|
|
380
|
+
// Configure multiple auth services for different purposes
|
|
381
|
+
const userAuthService = makeAuthService('user-auth')
|
|
382
|
+
const serviceAuthService = makeAuthService('service-auth')
|
|
383
|
+
const adminAuthService = makeAuthService('admin-auth')
|
|
384
|
+
|
|
385
|
+
context.registerService(userAuthService)
|
|
386
|
+
context.registerService(serviceAuthService)
|
|
387
|
+
context.registerService(adminAuthService)
|
|
388
|
+
|
|
389
|
+
// Use different services for different authentication needs
|
|
390
|
+
const userAuth = await userAuthService.authenticate(userToken)
|
|
391
|
+
const serviceAuth = await serviceAuthService.authenticate(serviceToken)
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
## Authentication Manager Application
|
|
395
|
+
|
|
396
|
+
The package includes a complete authentication manager application for centralized authentication:
|
|
397
|
+
|
|
398
|
+
### Manager Features
|
|
399
|
+
|
|
400
|
+
- **Central Authentication Hub**: Serves as authentication center for microservices
|
|
401
|
+
- **Token Issuance**: Issues authentication tokens for validated users
|
|
402
|
+
- **Multi-Service Support**: Handles authentication for multiple services
|
|
403
|
+
- **Admin Interface**: Management interface for authentication configuration
|
|
404
|
+
|
|
405
|
+
### Manager Usage
|
|
406
|
+
|
|
407
|
+
```typescript
|
|
408
|
+
// Located in src/manager - see manager/README.md for details
|
|
409
|
+
import { authManager } from '@owlmeans/server-auth/manager'
|
|
410
|
+
|
|
411
|
+
// The manager provides a complete authentication application
|
|
412
|
+
// that can be deployed as a standalone service
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
## Security Considerations
|
|
416
|
+
|
|
417
|
+
### Token Security
|
|
418
|
+
- All tokens use Ed25519 signatures for non-repudiable authentication
|
|
419
|
+
- Tokens include expiration times to limit exposure windows
|
|
420
|
+
- Signature verification prevents token tampering
|
|
421
|
+
|
|
422
|
+
### Trusted Entities
|
|
423
|
+
- Authentication relies on trusted entity verification
|
|
424
|
+
- Trusted entities must be properly configured and secured
|
|
425
|
+
- Private keys should be stored securely and rotated regularly
|
|
426
|
+
|
|
427
|
+
### Cache Security
|
|
428
|
+
- Authentication cache should be secured and encrypted
|
|
429
|
+
- Cache entries should have appropriate TTL values
|
|
430
|
+
- Cache should be cleared on security events
|
|
431
|
+
|
|
432
|
+
## Error Handling
|
|
433
|
+
|
|
434
|
+
The package provides comprehensive error handling:
|
|
435
|
+
|
|
436
|
+
- **AuthenFailed**: Authentication token validation failed
|
|
437
|
+
- **AuthorizationError**: Authorization verification failed
|
|
438
|
+
- **SyntaxError**: Configuration or context errors
|
|
439
|
+
|
|
440
|
+
```typescript
|
|
441
|
+
try {
|
|
442
|
+
const auth = await authService.unpack(token)
|
|
443
|
+
} catch (error) {
|
|
444
|
+
if (error instanceof AuthenFailed) {
|
|
445
|
+
// Handle authentication failure
|
|
446
|
+
} else if (error instanceof AuthorizationError) {
|
|
447
|
+
// Handle authorization failure
|
|
448
|
+
}
|
|
449
|
+
}
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
## Performance Considerations
|
|
453
|
+
|
|
454
|
+
- **Cache Integration**: Uses cache for frequently accessed authentication data
|
|
455
|
+
- **Signature Verification**: Ed25519 operations are computationally efficient
|
|
456
|
+
- **Token Reuse**: Validated tokens can be cached to avoid repeated verification
|
|
457
|
+
- **Resource Management**: Proper cleanup of authentication resources
|
|
458
|
+
|
|
459
|
+
## Integration with OwlMeans Ecosystem
|
|
460
|
+
|
|
461
|
+
This package integrates with:
|
|
462
|
+
|
|
463
|
+
- **@owlmeans/auth-common**: Common authentication components
|
|
464
|
+
- **@owlmeans/client-auth**: Client-side authentication
|
|
465
|
+
- **@owlmeans/basic-envelope**: Cryptographic message envelopes
|
|
466
|
+
- **@owlmeans/server-context**: Server context management
|
|
467
|
+
- **@owlmeans/module**: Module guard system integration
|
|
468
|
+
|
|
469
|
+
## Best Practices
|
|
470
|
+
|
|
471
|
+
1. **Configure cache** for better authentication performance
|
|
472
|
+
2. **Use trusted entities** for secure signature verification
|
|
473
|
+
3. **Implement proper error handling** for authentication failures
|
|
474
|
+
4. **Set appropriate token TTL** values for security
|
|
475
|
+
5. **Monitor authentication logs** for security analysis
|
|
476
|
+
6. **Rotate trusted keys** regularly
|
|
477
|
+
|
|
478
|
+
## Related Packages
|
|
479
|
+
|
|
480
|
+
- **@owlmeans/client-auth**: Client-side authentication
|
|
481
|
+
- **@owlmeans/auth-common**: Common authentication components
|
|
482
|
+
- **@owlmeans/server-context**: Server context management
|
|
483
|
+
- **@owlmeans/basic-envelope**: Cryptographic envelopes
|
|
484
|
+
- **@owlmeans/static-resource**: Resource management
|
|
485
|
+
|
|
486
|
+
## Manager Application
|
|
487
|
+
|
|
488
|
+
For detailed information about the authentication manager application, see the [Manager README](src/manager/README.md).
|
|
489
|
+
|
|
490
|
+
The manager provides a complete authentication service that can function as a central authentication hub for microservices architectures.
|
package/build/.gitkeep
ADDED
|
File without changes
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/actions/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAA"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/actions/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAA"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/actions/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAS/C,eAAO,MAAM,YAAY,EAAE,kBAAkB,CAAC,SAAS,CAKtD,CAAA"}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { handleBody } from '@owlmeans/server-api';
|
|
2
|
+
import { assertContext } from '@owlmeans/context';
|
|
3
|
+
export const authenticate = handleBody(async (payload, ctx) => {
|
|
4
|
+
const context = assertContext(ctx, 'authenticate');
|
|
5
|
+
return await context.auth().authenticate(payload);
|
|
6
|
+
});
|
|
7
|
+
//# sourceMappingURL=service.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/actions/service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAGjD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAKjD,MAAM,CAAC,MAAM,YAAY,GAAkC,UAAU,CACnE,KAAK,EAAE,OAAkB,EAAE,GAAG,EAAE,EAAE;IAChC,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,EAAE,cAAc,CAAY,CAAA;IAC7D,OAAO,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;AACnD,CAAC,CACF,CAAA"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,gBAAgB,QAAiB,CAAA;AAE9C,eAAO,MAAM,YAAY,iBAAiB,CAAA;AAE1C,eAAO,MAAM,aAAa,SAAS,CAAA;AAEnC,eAAO,MAAM,UAAU,eAAe,CAAA"}
|
package/build/consts.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAE9C,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAA;AAE1C,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAA;AAEnC,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAA"}
|
package/build/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA"}
|
package/build/index.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/manager/actions/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAA"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/manager/actions/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAA"}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { AllowanceRequest, AuthCredentials } from '@owlmeans/auth';
|
|
2
|
+
import type { RefedModuleHandler } from '@owlmeans/server-module';
|
|
3
|
+
export declare const authenticationInit: RefedModuleHandler<AllowanceRequest>;
|
|
4
|
+
export declare const authenticate: RefedModuleHandler<AuthCredentials>;
|
|
5
|
+
export declare const rely: RefedModuleHandler<void>;
|
|
6
|
+
//# sourceMappingURL=manager.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/manager/actions/manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAGvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAIjE,eAAO,MAAM,kBAAkB,EAAE,kBAAkB,CAAC,gBAAgB,CAGnE,CAAA;AAED,eAAO,MAAM,YAAY,EAAE,kBAAkB,CAAC,eAAe,CAG5D,CAAA;AAED,eAAO,MAAM,IAAI,EAAE,kBAAkB,CAAC,IAAI,CAKzC,CAAA"}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { handleBody } from '@owlmeans/server-api';
|
|
2
|
+
import { makeAuthModel } from '../model.js';
|
|
3
|
+
import { handleConnection } from '@owlmeans/server-socket';
|
|
4
|
+
export const authenticationInit = handleBody(async (payload, ctx) => await makeAuthModel(ctx).init(payload));
|
|
5
|
+
export const authenticate = handleBody(async (payload, ctx) => await makeAuthModel(ctx).authenticate(payload));
|
|
6
|
+
export const rely = handleConnection(
|
|
7
|
+
// @TODO Request will contain information is there requrest
|
|
8
|
+
// privileged or not (privileged request implies auth provider)
|
|
9
|
+
async (conn, ctx, req) => await makeAuthModel(ctx).rely(conn, req.auth));
|
|
10
|
+
//# sourceMappingURL=manager.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/manager/actions/manager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAE1D,MAAM,CAAC,MAAM,kBAAkB,GAAyC,UAAU,CAChF,KAAK,EAAE,OAAyB,EAAE,GAAG,EAAE,EAAE,CACvC,MAAM,aAAa,CAAC,GAA4B,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAClE,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAwC,UAAU,CACzE,KAAK,EAAE,OAAwB,EAAE,GAAG,EAAE,EAAE,CACtC,MAAM,aAAa,CAAC,GAA4B,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAC1E,CAAA;AAED,MAAM,CAAC,MAAM,IAAI,GAA6B,gBAAgB;AAC5D,4DAA4D;AAC5D,+DAA+D;AAC/D,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,CACvB,MAAM,aAAa,CAAC,GAA4B,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CACzE,CAAA"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../../src/manager/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,YAAY,cAAc,CAAA;AAEvC,eAAO,MAAM,WAAW,gBAAgB,CAAA"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"consts.js","sourceRoot":"","sources":["../../src/manager/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAA;AAEvC,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAA"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/manager/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AASvD,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,cAAa,OAAO,KAAW,CAsB9G,CAAA"}
|