From 9d858c790bbd3bfc5727b2d334dccfc009e9eceb Mon Sep 17 00:00:00 2001 From: lucythecat Date: Wed, 6 Dec 2023 09:31:23 +0900 Subject: [PATCH] add more reference pages --- .../src/reference/main/Adapter.md | 31 +++++++++++++++ .../reference/main/Adapter/deleteSession.md | 0 .../main/Adapter/deleteUserSessions.md | 0 .../main/Adapter/getSessionAndUser.md | 0 .../reference/main/Adapter/getUserSessions.md | 0 .../src/reference/main/Adapter/index.md | 0 .../src/reference/main/Adapter/setSession.md | 0 .../main/Adapter/updateSessionExpiration.md | 0 .../src/reference/main/DatabaseSession.md | 24 ++++++++++++ .../main/DatabaseSessionAttributes.md | 11 ++++++ .../src/reference/main/DatabaseUser.md | 22 +++++++++++ .../reference/main/DatabaseUserAttributes.md | 11 ++++++ .../src/reference/main/LegacyScrypt/hash.md | 21 ++++++++++ .../src/reference/main/LegacyScrypt/index.md | 36 ++++++++++++++++++ .../src/reference/main/LegacyScrypt/verify.md | 22 +++++++++++ .../src/reference/main/Lucia/index.md | 30 +++++++++++---- .../src/reference/main/Scrypt/hash.md | 21 ++++++++++ .../src/reference/main/Scrypt/index.md | 38 +++++++++++++++++++ .../src/reference/main/Scrypt/verify.md | 22 +++++++++++ .../src/reference/main/Session.md | 25 ++++++++++++ .../src/reference/main/SessionCookie.md | 5 +++ .../main/SessionCookieAttributesOptions.md | 0 .../reference/main/SessionCookieOptions.md | 0 .../src/reference/main/TimeSpan.md | 5 +++ documentation-v3/src/reference/main/User.md | 19 ++++++++++ .../src/reference/main/generateId.md | 24 ++++++++++++ 26 files changed, 360 insertions(+), 7 deletions(-) create mode 100644 documentation-v3/src/reference/main/Adapter.md delete mode 100644 documentation-v3/src/reference/main/Adapter/deleteSession.md delete mode 100644 documentation-v3/src/reference/main/Adapter/deleteUserSessions.md delete mode 100644 documentation-v3/src/reference/main/Adapter/getSessionAndUser.md delete mode 100644 documentation-v3/src/reference/main/Adapter/getUserSessions.md delete mode 100644 documentation-v3/src/reference/main/Adapter/index.md delete mode 100644 documentation-v3/src/reference/main/Adapter/setSession.md delete mode 100644 documentation-v3/src/reference/main/Adapter/updateSessionExpiration.md create mode 100644 documentation-v3/src/reference/main/DatabaseSessionAttributes.md delete mode 100644 documentation-v3/src/reference/main/SessionCookieAttributesOptions.md delete mode 100644 documentation-v3/src/reference/main/SessionCookieOptions.md diff --git a/documentation-v3/src/reference/main/Adapter.md b/documentation-v3/src/reference/main/Adapter.md new file mode 100644 index 000000000..cb5c34c50 --- /dev/null +++ b/documentation-v3/src/reference/main/Adapter.md @@ -0,0 +1,31 @@ +--- +type: "interface" +--- + +Represents a database adapter. + +## Definition + +```ts +//$ DatabaseSession=ref:main +//$ DatabaseUser=ref:main +interface Adapter { + deleteSession(sessionId: string): Promise; + deleteUserSessions(userId: string): Promise; + getSessionAndUser( + sessionId: string + ): Promise<[session: $$DatabaseSession | null, user: $$DatabaseUser | null]>; + getUserSessions(userId: string): Promise<$$DatabaseSession[]>; + setSession(session: $$DatabaseSession): Promise; + updateSessionExpiration(sessionId: string, expiresAt: Date): Promise; +} +``` + +### Methods + +- `deleteSession()`: Deletes the session +- `deleteUserSessions()`: Deletes all sessions linked to the user +- `getSessionAndUser()`: Returns the session and the user linked to the session +- `getUserSessions()`: Returns all sessions linked to a user +- `setSession()`: Inserts the session +- `updateSessionExpiration()`: Updates the `expires_at` field of the session diff --git a/documentation-v3/src/reference/main/Adapter/deleteSession.md b/documentation-v3/src/reference/main/Adapter/deleteSession.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/documentation-v3/src/reference/main/Adapter/deleteUserSessions.md b/documentation-v3/src/reference/main/Adapter/deleteUserSessions.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/documentation-v3/src/reference/main/Adapter/getSessionAndUser.md b/documentation-v3/src/reference/main/Adapter/getSessionAndUser.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/documentation-v3/src/reference/main/Adapter/getUserSessions.md b/documentation-v3/src/reference/main/Adapter/getUserSessions.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/documentation-v3/src/reference/main/Adapter/index.md b/documentation-v3/src/reference/main/Adapter/index.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/documentation-v3/src/reference/main/Adapter/setSession.md b/documentation-v3/src/reference/main/Adapter/setSession.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/documentation-v3/src/reference/main/Adapter/updateSessionExpiration.md b/documentation-v3/src/reference/main/Adapter/updateSessionExpiration.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/documentation-v3/src/reference/main/DatabaseSession.md b/documentation-v3/src/reference/main/DatabaseSession.md index e69de29bb..10bfbfee9 100644 --- a/documentation-v3/src/reference/main/DatabaseSession.md +++ b/documentation-v3/src/reference/main/DatabaseSession.md @@ -0,0 +1,24 @@ +--- +type: "interface" +--- + +Represents a session stored in a database. + +## Definition + +```ts +//$ DatabaseSessionAttributes=ref:main +interface DatabaseSession { + id: string; + userId: string; + expiresAt: Date; + attributes: $$DatabaseSessionAttributes; +} +``` + +### Properties + +- `id` +- `userId` +- `expiresAt` +- `attributes` diff --git a/documentation-v3/src/reference/main/DatabaseSessionAttributes.md b/documentation-v3/src/reference/main/DatabaseSessionAttributes.md new file mode 100644 index 000000000..3d03ce9cb --- /dev/null +++ b/documentation-v3/src/reference/main/DatabaseSessionAttributes.md @@ -0,0 +1,11 @@ +--- +type: "interface" +--- + +Additional data stored in the session table. + +## Definition + +```ts +interface DatabaseSessionAttributes {} +``` diff --git a/documentation-v3/src/reference/main/DatabaseUser.md b/documentation-v3/src/reference/main/DatabaseUser.md index e69de29bb..abfe8f4a9 100644 --- a/documentation-v3/src/reference/main/DatabaseUser.md +++ b/documentation-v3/src/reference/main/DatabaseUser.md @@ -0,0 +1,22 @@ +--- +type: "interface" +--- + +Represents a session stored in a database. + +## Definition + +```ts +//$ DatabaseUserAttributes=ref:main +interface DatabaseUser { + id: string; + attributes: DatabaseUserAttributes; +} +``` + +### Properties + +- `id` +- `userId` +- `expiresAt` +- `attributes` diff --git a/documentation-v3/src/reference/main/DatabaseUserAttributes.md b/documentation-v3/src/reference/main/DatabaseUserAttributes.md index e69de29bb..74c3cb679 100644 --- a/documentation-v3/src/reference/main/DatabaseUserAttributes.md +++ b/documentation-v3/src/reference/main/DatabaseUserAttributes.md @@ -0,0 +1,11 @@ +--- +type: "interface" +--- + +Additional data stored in the user table. + +## Definition + +```ts +interface DatabaseUserAttributes {} +``` diff --git a/documentation-v3/src/reference/main/LegacyScrypt/hash.md b/documentation-v3/src/reference/main/LegacyScrypt/hash.md index e69de29bb..207214ba9 100644 --- a/documentation-v3/src/reference/main/LegacyScrypt/hash.md +++ b/documentation-v3/src/reference/main/LegacyScrypt/hash.md @@ -0,0 +1,21 @@ +--- +type: "method" +--- + +Hashes the provided password with scrypt. + +## Definition + +```ts +function hash(password: string): Promise; +``` + +### Parameters + +- `password` + +## Example + +```ts +const hash = await scrypt.hash(password); +``` diff --git a/documentation-v3/src/reference/main/LegacyScrypt/index.md b/documentation-v3/src/reference/main/LegacyScrypt/index.md index e69de29bb..b79b879f7 100644 --- a/documentation-v3/src/reference/main/LegacyScrypt/index.md +++ b/documentation-v3/src/reference/main/LegacyScrypt/index.md @@ -0,0 +1,36 @@ +--- +type: "class" +--- + +A pure JS implementation of Scrypt for projects that used Lucia v1/v2. For new projects, use [`Scrypt`](). + +The output hash is a combination of the scrypt hash and the 32-bytes salt, in the format of `:`. + +## Constructor + +```ts +function constructor(options?: { N?: number; r?: number; p?: number; dkLen?: number }): this; +``` + +### Parameters + +- `options` + - `N` (default: `16384`) + - `r` (default: `16`) + - `p` (default: `1`) + - `dkLen` (default: `64`) + +## Methods + +- [`hash()`](ref:password/Argon2id) +- [`verify()`](ref:password/Argon2id) + +## Example + +```ts +import { LegacyScrypt } from "lucia"; + +const scrypt = new LegacyScrypt(); +const hash = await scrypt.hash(password); +const validPassword = await scrypt.verify(hash, password); +``` diff --git a/documentation-v3/src/reference/main/LegacyScrypt/verify.md b/documentation-v3/src/reference/main/LegacyScrypt/verify.md index e69de29bb..d468c4a50 100644 --- a/documentation-v3/src/reference/main/LegacyScrypt/verify.md +++ b/documentation-v3/src/reference/main/LegacyScrypt/verify.md @@ -0,0 +1,22 @@ +--- +type: "method" +--- + +Verifies the password with the hash using scrypt. + +## Definition + +```ts +function verify(hash: string, password: string): Promise; +``` + +### Parameters + +- `hash` +- `password` + +## Example + +```ts +const validPassword = await scrypt.verify(hash, password); +``` diff --git a/documentation-v3/src/reference/main/Lucia/index.md b/documentation-v3/src/reference/main/Lucia/index.md index 5502b3c78..02d6f3ba2 100644 --- a/documentation-v3/src/reference/main/Lucia/index.md +++ b/documentation-v3/src/reference/main/Lucia/index.md @@ -24,7 +24,16 @@ function constructor< middleware?: _Middleware; csrfProtection?: boolean | $$CSRFProtectionOptions; sessionExpiresIn?: $$TimeSpan; - sessionCookie?: $$SessionCookieOptions; + sessionCookie?: { + name?: string; + expires?: boolean; + attributes: { + sameSite?: "lax" | "strict"; + domain?: string; + path?: string; + secure?: boolean; + }; + }; getSessionAttributes?: ( databaseSessionAttributes: $$DatabaseSessionAttributes ) => _SessionAttributes; @@ -37,12 +46,19 @@ function constructor< - `adapter`: Database adapter - `options`: - - `middleware`: Middleware - - `csrfProtection`: If CSRF protection is enabled and its options (default: `true`) - - `sessionExpiresIn`: How long a session lasts for maximum for inactive users - - `sessionCookie`: Session cookie options - - `getSessionAttributes()`: Transforms database session attributes and the returned object is added to the [`Session`](ref:main) object - - `getUserAttributes()`: Transforms database user attributes and the returned object is added to the [`User`](ref:main) object + - `middleware`: Middleware + - `csrfProtection`: If CSRF protection is enabled and its options (default: `true`) + - `sessionExpiresIn`: How long a session lasts for maximum for inactive users + - `sessionCookie`: Session cookie options + - `name`: Cookie name (default: `auth_session`) + - `expires`: Set to `false` for cookies to persist indefinitely (default: `true`) + - `attributes`: Cookie attributes + - `sameSite` + - `domain` + - `path` + - `secure` + - `getSessionAttributes()`: Transforms database session attributes and the returned object is added to the [`Session`](ref:main) object + - `getUserAttributes()`: Transforms database user attributes and the returned object is added to the [`User`](ref:main) object ## Method diff --git a/documentation-v3/src/reference/main/Scrypt/hash.md b/documentation-v3/src/reference/main/Scrypt/hash.md index e69de29bb..207214ba9 100644 --- a/documentation-v3/src/reference/main/Scrypt/hash.md +++ b/documentation-v3/src/reference/main/Scrypt/hash.md @@ -0,0 +1,21 @@ +--- +type: "method" +--- + +Hashes the provided password with scrypt. + +## Definition + +```ts +function hash(password: string): Promise; +``` + +### Parameters + +- `password` + +## Example + +```ts +const hash = await scrypt.hash(password); +``` diff --git a/documentation-v3/src/reference/main/Scrypt/index.md b/documentation-v3/src/reference/main/Scrypt/index.md index e69de29bb..e61570249 100644 --- a/documentation-v3/src/reference/main/Scrypt/index.md +++ b/documentation-v3/src/reference/main/Scrypt/index.md @@ -0,0 +1,38 @@ +--- +type: "class" +--- + +A pure JS implementation of Scrypt. Provides methods for hashing passwords and verifying hashes with [scrypt](https://datatracker.ietf.org/doc/html/rfc7914). By default, the configuration is set to [the recommended values](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html). + +The output hash is a combination of the scrypt hash and the 32-bytes salt, in the format of `:`. + +Since it's pure JS, it is anywhere from 2~3 times slower than implementations based on native code. See Oslo's [`Scrypt`]() for a faster API (Node.js-only). + +## Constructor + +```ts +function constructor(options?: { N?: number; r?: number; p?: number; dkLen?: number }): this; +``` + +### Parameters + +- `options` + - `N` (default: `16384`) + - `r` (default: `16`) + - `p` (default: `1`) + - `dkLen` (default: `64`) + +## Methods + +- [`hash()`](ref:password/Argon2id) +- [`verify()`](ref:password/Argon2id) + +## Example + +```ts +import { Scrypt } from "lucia"; + +const scrypt = new Scrypt(); +const hash = await scrypt.hash(password); +const validPassword = await scrypt.verify(hash, password); +``` diff --git a/documentation-v3/src/reference/main/Scrypt/verify.md b/documentation-v3/src/reference/main/Scrypt/verify.md index e69de29bb..d468c4a50 100644 --- a/documentation-v3/src/reference/main/Scrypt/verify.md +++ b/documentation-v3/src/reference/main/Scrypt/verify.md @@ -0,0 +1,22 @@ +--- +type: "method" +--- + +Verifies the password with the hash using scrypt. + +## Definition + +```ts +function verify(hash: string, password: string): Promise; +``` + +### Parameters + +- `hash` +- `password` + +## Example + +```ts +const validPassword = await scrypt.verify(hash, password); +``` diff --git a/documentation-v3/src/reference/main/Session.md b/documentation-v3/src/reference/main/Session.md index e69de29bb..fff25fcd6 100644 --- a/documentation-v3/src/reference/main/Session.md +++ b/documentation-v3/src/reference/main/Session.md @@ -0,0 +1,25 @@ +--- +type: "interface" +--- + +Represents a session. + +## Definition + +```ts +//$ SessionAttributes=ref:main +interface Session extends SessionAttributes { + id: string; + expiresAt: Date; + fresh: boolean; + userId: string; +} +``` + + +### Properties + +- `id` +- `expiresAt` +- `fresh`: `true` if session was newly created or its expiration was extended +- `userId` \ No newline at end of file diff --git a/documentation-v3/src/reference/main/SessionCookie.md b/documentation-v3/src/reference/main/SessionCookie.md index e69de29bb..27bfb1637 100644 --- a/documentation-v3/src/reference/main/SessionCookie.md +++ b/documentation-v3/src/reference/main/SessionCookie.md @@ -0,0 +1,5 @@ +--- +type: "class" +--- + +See [`SessionCookie`](https://oslo.js.org/reference/session/SessionCookie/) from `oslo/session`. \ No newline at end of file diff --git a/documentation-v3/src/reference/main/SessionCookieAttributesOptions.md b/documentation-v3/src/reference/main/SessionCookieAttributesOptions.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/documentation-v3/src/reference/main/SessionCookieOptions.md b/documentation-v3/src/reference/main/SessionCookieOptions.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/documentation-v3/src/reference/main/TimeSpan.md b/documentation-v3/src/reference/main/TimeSpan.md index e69de29bb..30b6d73b7 100644 --- a/documentation-v3/src/reference/main/TimeSpan.md +++ b/documentation-v3/src/reference/main/TimeSpan.md @@ -0,0 +1,5 @@ +--- +type: "class" +--- + +See [`TimeSpan`](https://oslo.js.org/reference/main/TimeSpan/) from `oslo`. \ No newline at end of file diff --git a/documentation-v3/src/reference/main/User.md b/documentation-v3/src/reference/main/User.md index e69de29bb..2bde4ee2e 100644 --- a/documentation-v3/src/reference/main/User.md +++ b/documentation-v3/src/reference/main/User.md @@ -0,0 +1,19 @@ +--- +type: "interface" +--- + +Represents a user. + +## Definition + +```ts +//$ UserAttributes=ref:main +interface Session extends UserAttributes { + id: string; +} +``` + + +### Properties + +- `id` \ No newline at end of file diff --git a/documentation-v3/src/reference/main/generateId.md b/documentation-v3/src/reference/main/generateId.md index e69de29bb..74a9bfcd1 100644 --- a/documentation-v3/src/reference/main/generateId.md +++ b/documentation-v3/src/reference/main/generateId.md @@ -0,0 +1,24 @@ +--- +type: "function" +--- + +Generates a cryptographically strong random string made of `a-z` (lowercase) and `0-9`. + +## Definition + +```ts +function generateId(length: number): string; +``` + +### Parameters + +- `length` + +## Example + +```ts +import { generateId } from "oslo/random"; + +// 10-characters long string +generateId(10); +```