@gauts/auth 0.10.4 → 0.10.5
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/README.md +43 -35
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,7 +1,13 @@
|
|
|
1
1
|
# `@gauts/auth`
|
|
2
2
|
|
|
3
|
-
[](https://bundlephobia.com/package/@gauts/auth)
|
|
4
|
+
[](https://bundlephobia.com/package/@gauts/auth)
|
|
5
|
+
|
|
6
|
+
[](https://www.npmjs.com/package/@gauts/auth)
|
|
7
|
+
[](https://www.npmjs.com/package/@gauts/auth)
|
|
8
|
+
[](https://nodejs.org)
|
|
9
|
+
[](https://github.com/GVALFER/GAUTS-AUTH/blob/main/LICENSE)
|
|
10
|
+
[](https://github.com/GVALFER/GAUTS-AUTH/actions/workflows/ci.yml)
|
|
5
11
|
|
|
6
12
|
Secure authentication for Node.js applications, with password login, persistent sessions, social providers, and adapters for popular frameworks and databases.
|
|
7
13
|
|
|
@@ -54,13 +60,7 @@ npm install @gauts/auth express
|
|
|
54
60
|
npm install @gauts/auth fastify
|
|
55
61
|
```
|
|
56
62
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
```bash
|
|
60
|
-
npm install @gauts/auth next
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
Run only the matching API command. `hono`, `express`, `fastify`, and `next` only need to be installed when the corresponding project does not already provide them.
|
|
63
|
+
Run only the matching API command. `hono`, `express`, and `fastify` only need to be installed when the corresponding project does not already provide them.
|
|
64
64
|
|
|
65
65
|
Express TypeScript projects also install its type declarations:
|
|
66
66
|
|
|
@@ -250,7 +250,15 @@ Express exposes authenticated values through `response.locals`. Fastify exposes
|
|
|
250
250
|
|
|
251
251
|
When `storedHash` is missing, the package performs password work with the configured algorithm and always returns `false`. Applications do not need a dummy hash. Keep the response identical for unknown accounts and incorrect passwords.
|
|
252
252
|
|
|
253
|
-
### 4. Connect the Next.js frontend
|
|
253
|
+
### 4. Connect the Next.js frontend (Optional)
|
|
254
|
+
|
|
255
|
+
This step is optional and only needed if you want to renew the session in SSR.
|
|
256
|
+
|
|
257
|
+
When the Next.js frontend is a separate project, run this command inside the frontend project:
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
npm install @gauts/auth next
|
|
261
|
+
```
|
|
254
262
|
|
|
255
263
|
Create the renewal adapter with the API's private URL:
|
|
256
264
|
|
|
@@ -316,16 +324,16 @@ The application owns the redirect URL. When `unauthorizedUrl` is provided, the a
|
|
|
316
324
|
|
|
317
325
|
### `createHonoAuth()`
|
|
318
326
|
|
|
319
|
-
| Property | Type / allowed values |
|
|
320
|
-
| ---------- | --------------------- |
|
|
321
|
-
| `db` | `DbAdapter` |
|
|
322
|
-
| `getIp` | `HonoGetIp` | Only with IP validation
|
|
323
|
-
| `password` | `PasswordConfig` |
|
|
324
|
-
| `session` | `SessionConfig` |
|
|
325
|
-
| `cookie` | `HonoCookieConfig` |
|
|
326
|
-
| `cache` | `{ ttl: number }` |
|
|
327
|
-
| `secret` | `string` |
|
|
328
|
-
| `social` | `SocialConfig` |
|
|
327
|
+
| Property | Type / allowed values | Required | Default | Description |
|
|
328
|
+
| ---------- | --------------------- | :---------------------: | ----------------- | --------------------------------------------------------------------------------------------------- |
|
|
329
|
+
| `db` | `DbAdapter` | ✅ | — | Authoritative session persistence and account loading. |
|
|
330
|
+
| `getIp` | `HonoGetIp` | Only with IP validation | Omitted | Returns the client IP from a source trusted by the application. May be synchronous or asynchronous. |
|
|
331
|
+
| `password` | `PasswordConfig` | ❌ | Argon2id defaults | Password hashing and verification configuration. |
|
|
332
|
+
| `session` | `SessionConfig` | ❌ | Session defaults | Expiry, renewal, and client validation configuration. |
|
|
333
|
+
| `cookie` | `HonoCookieConfig` | ❌ | Cookie defaults | Names, domain, path, SameSite, and Secure settings. |
|
|
334
|
+
| `cache` | `{ ttl: number }` | ❌ | Disabled | Enables the short signed browser cache. |
|
|
335
|
+
| `secret` | `string` | ✅ | — | HMAC secret for signed session context and optional social data. Minimum 32 UTF-8 bytes. |
|
|
336
|
+
| `social` | `SocialConfig` | ❌ | Disabled | Enables configured social providers, redirects, and optional registration. |
|
|
329
337
|
|
|
330
338
|
```ts
|
|
331
339
|
type HonoGetIp = (c: Context) => Promise<string | null | undefined> | string | null | undefined;
|
|
@@ -417,14 +425,14 @@ renew_at = min((updated_at ?? created_at) + renewInterval, maxExpiresAt)
|
|
|
417
425
|
|
|
418
426
|
### Cookies
|
|
419
427
|
|
|
420
|
-
| Property | Type / allowed values | Default | Description
|
|
421
|
-
| ------------- | ----------------------------- | ----------------- |
|
|
422
|
-
| `sessionName` | Valid cookie name | `"__ses"` | Contains the opaque token. This is the only authenticating cookie.
|
|
428
|
+
| Property | Type / allowed values | Default | Description |
|
|
429
|
+
| ------------- | ----------------------------- | ----------------- | ---------------------------------------------------------------------------------------------- |
|
|
430
|
+
| `sessionName` | Valid cookie name | `"__ses"` | Contains the opaque token. This is the only authenticating cookie. |
|
|
423
431
|
| `contextName` | Valid cookie name | `"__ctx"` | Contains signed renewal scheduling and the optional short cache. It never authenticates alone. |
|
|
424
|
-
| `domain` | `string` | Browser host only | Optional cookie domain.
|
|
425
|
-
| `path` | String beginning with `/` | `"/"` | Cookie path.
|
|
426
|
-
| `sameSite` | `"Strict" \| "Lax" \| "None"` | `"Lax"` | Browser SameSite policy.
|
|
427
|
-
| `secure` | `boolean` | `true` | Requires HTTPS when enabled. Set `false` only for local HTTP development.
|
|
432
|
+
| `domain` | `string` | Browser host only | Optional cookie domain. |
|
|
433
|
+
| `path` | String beginning with `/` | `"/"` | Cookie path. |
|
|
434
|
+
| `sameSite` | `"Strict" \| "Lax" \| "None"` | `"Lax"` | Browser SameSite policy. |
|
|
435
|
+
| `secure` | `boolean` | `true` | Requires HTTPS when enabled. Set `false` only for local HTTP development. |
|
|
428
436
|
|
|
429
437
|
Both cookies are always `HttpOnly`, expire with the authoritative session, and must use unique names. Deleting `__ctx` does not log the user out: the next authenticated API request validates `__ses` through the database and rebuilds the signed context. Deleting `__ses` ends browser authentication because `__ctx` is never accepted on its own.
|
|
430
438
|
|
|
@@ -688,11 +696,11 @@ export const nextAuth = createNextAuth({
|
|
|
688
696
|
});
|
|
689
697
|
```
|
|
690
698
|
|
|
691
|
-
| Property | Type / allowed values | Required | Default | Description
|
|
692
|
-
| -------------------- | -------------------------------- | :------: | --------- |
|
|
693
|
-
| `renewUrl` | Absolute `http:` or `https:` URL | ✅ | — | Trusted private API renewal endpoint.
|
|
694
|
-
| `cookie.sessionName` | Valid cookie name | ❌ | `"__ses"` | Session cookie read and forwarded to the API.
|
|
695
|
-
| `cookie.contextName` | Valid cookie name | ❌ | `"__ctx"` | Signed context decoded only to schedule SSR renewal.
|
|
699
|
+
| Property | Type / allowed values | Required | Default | Description |
|
|
700
|
+
| -------------------- | -------------------------------- | :------: | --------- | ---------------------------------------------------- |
|
|
701
|
+
| `renewUrl` | Absolute `http:` or `https:` URL | ✅ | — | Trusted private API renewal endpoint. |
|
|
702
|
+
| `cookie.sessionName` | Valid cookie name | ❌ | `"__ses"` | Session cookie read and forwarded to the API. |
|
|
703
|
+
| `cookie.contextName` | Valid cookie name | ❌ | `"__ctx"` | Signed context decoded only to schedule SSR renewal. |
|
|
696
704
|
|
|
697
705
|
## Session flow
|
|
698
706
|
|
|
@@ -807,7 +815,7 @@ await auth.createSession({
|
|
|
807
815
|
| Method | Purpose |
|
|
808
816
|
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
809
817
|
| `auth.createSession({ account_id, context, country? })` | Creates the DB session and writes the browser cookies. `country` is optional login-time metadata. |
|
|
810
|
-
| `auth.resolveSession(context)` | Resolves a request, renews inline when due, and returns the selected account and session.
|
|
818
|
+
| `auth.resolveSession(context)` | Resolves a request, renews inline when due, and returns the selected account and session. |
|
|
811
819
|
| `auth.renewSession(context)` | Performs DB validation, renews when due, and writes authoritative cookies. |
|
|
812
820
|
| `auth.revokeSession(context)` | Revokes the current DB session and clears cookies. |
|
|
813
821
|
| `auth.clearSession(context)` | Clears browser cookies without revoking the DB session. |
|
|
@@ -832,7 +840,7 @@ app.get("/account", auth.requireSession, (_request, response) => {
|
|
|
832
840
|
| Method | Purpose |
|
|
833
841
|
| ----------------------------------------------------------------- | ---------------------------------------------------- |
|
|
834
842
|
| `auth.createSession({ account_id, request, response, country? })` | Creates the DB session and writes cookies. |
|
|
835
|
-
| `auth.resolveSession({ request, response })` | Resolves and automatically renews when due.
|
|
843
|
+
| `auth.resolveSession({ request, response })` | Resolves and automatically renews when due. |
|
|
836
844
|
| `auth.renewSession({ request, response })` | Renews when due and writes authoritative cookies. |
|
|
837
845
|
| `auth.revokeSession({ request, response })` | Revokes the current session and clears cookies. |
|
|
838
846
|
| `auth.clearSession(response)` | Clears cookies without revoking the DB session. |
|
|
@@ -863,7 +871,7 @@ app.get("/account", { preHandler: auth.requireSession }, (request) => ({
|
|
|
863
871
|
| -------------------------------------------------------------- | -------------------------------------------------------------- |
|
|
864
872
|
| `auth.decorate(app)` | Declares the native request decorators once at startup. |
|
|
865
873
|
| `auth.createSession({ account_id, request, reply, country? })` | Creates the DB session and writes cookies. |
|
|
866
|
-
| `auth.resolveSession({ request, reply })` | Resolves and automatically renews when due.
|
|
874
|
+
| `auth.resolveSession({ request, reply })` | Resolves and automatically renews when due. |
|
|
867
875
|
| `auth.renewSession({ request, reply })` | Renews when due and writes authoritative cookies. |
|
|
868
876
|
| `auth.revokeSession({ request, reply })` | Revokes the current session and clears cookies. |
|
|
869
877
|
| `auth.clearSession(reply)` | Clears cookies without revoking the DB session. |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gauts/auth",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.5",
|
|
4
4
|
"description": "Secure authentication for Node.js applications, with password login, persistent sessions, social providers, and adapters for popular frameworks and databases.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "GVALFER",
|