@techelusive/nest-auth 0.0.0-stage → 0.2.0

package/docs/endpoints/organizations.md

@@ -0,0 +1,192 @@
+# Organizations
+
+Needs `organizations.enabled`; otherwise `403 FEATURE_DISABLED`. Every route needs a signed-in user, and roles (`owner`, `admin`, `member`) are checked per organization. If you're not a member, the organization's routes return `404 NOT_FOUND`. Concepts are explained in [Organizations](../organizations.md).
+
+## Organization object
+
+```json
+{
+  "id": "a1b2c3d4-0000-4000-8000-000000000001",
+  "name": "Acme Travels",
+  "slug": "acme-travels",
+  "metadata": {},
+  "createdByUserId": "5f0c8a2e-1d3b-4c5a-9e7f-0a1b2c3d4e5f",
+  "createdAt": "2026-10-20T06:30:00.000Z",
+  "updatedAt": "2026-10-20T06:30:00.000Z"
+}
+```
+
+---
+
+## GET /auth/organizations
+
+The organizations the user belongs to.
+
+**Response `200`**
+
+```json
+{
+  "success": true,
+  "organizations": [
+    { "id": "a1b2...", "name": "Acme Travels", "slug": "acme-travels", "metadata": {}, "role": "owner", "joinedAt": "2026-10-20T06:30:00.000Z" }
+  ]
+}
+```
+
+## POST /auth/organizations
+
+Creates an organization; the caller becomes its owner. Session checked live. When `organizations.allowUsersToCreate` is off, only app admins can create.
+
+**Request**
+
+```json
+{ "name": "Acme Travels", "slug": "acme-travels" }
+```
+
+| Field | Type | Required | Rules |
+|---|---|---|---|
+| `name` | string | yes | up to 100 characters |
+| `slug` | string | yes | 3–50 lowercase letters, digits and dashes; can't start or end with a dash |
+
+**Response `201`:** `{ "success": true, "organization": { ...organization object } }`
+
+**Errors:** `409 ORGANIZATION_SLUG_TAKEN`, `403 FORBIDDEN` (users may not create), `400 VALIDATION_ERROR` (`problems: ["too many organizations"]`, 100 per user).
+
+## POST /auth/organizations/switch
+
+Picks the organization this device works in. **Replace the stored access token** with the returned one; refreshes keep the organization. Session checked live.
+
+**Request**
+
+```json
+{ "organizationId": "a1b2c3d4-0000-4000-8000-000000000001" }
+```
+
+Send `{ "organizationId": null }` to leave organization mode.
+
+**Response `200`**
+
+```json
+{ "success": true, "accessToken": "eyJhbGciOiJFUzI1NiIs...", "expiresIn": 900, "organizationId": "a1b2c3d4-0000-4000-8000-000000000001" }
+```
+
+The new token carries `"org_id"` and `"org_role"`.
+
+## POST /auth/organizations/invitations/accept
+
+Accepts an emailed invitation. The signed-in user's **verified** email must match the invited email. Session checked live.
+
+**Request**
+
+```json
+{ "token": "oi_aW52aXRhdGlvbmV4YW1wbGV0b2tlbjEyMzQ1Njc4OTAxMjM" }
+```
+
+**Response `200`**
+
+```json
+{ "success": true, "organizationId": "a1b2c3d4-0000-4000-8000-000000000001", "role": "member" }
+```
+
+**Errors:** `400 INVALID_TOKEN` (unknown, used, expired (`organizations.invitationExpiresInDays`, 7 by default), cancelled, or a different / unverified email), `409 ALREADY_MEMBER`.
+
+---
+
+## GET /auth/organizations/:organizationId
+
+Any member. **Response `200`:** `{ "success": true, "organization": { ...organization object, "myRole": "admin" } }`
+
+## PATCH /auth/organizations/:organizationId
+
+Admin or owner. Session checked live.
+
+**Request** (all optional):
+
+```json
+{ "name": "Acme Travels India", "slug": "acme-india", "metadata": { "gstNumber": "29ABCDE1234F1Z5" } }
+```
+
+**Response `200`:** `{ "success": true, "organization": { ... } }`. Errors: `409 ORGANIZATION_SLUG_TAKEN`, `403 FORBIDDEN`.
+
+## DELETE /auth/organizations/:organizationId
+
+Owner only. Removes members, invitations and the organization's API keys. Session checked live. **Response `200`:** `{ "success": true }`
+
+---
+
+## GET /auth/organizations/:organizationId/members
+
+Any member.
+
+**Response `200`**
+
+```json
+{
+  "success": true,
+  "members": [
+    { "userId": "5f0c...", "email": "asha@example.com", "firstName": "Asha", "lastName": "Rao", "role": "owner", "joinedAt": "2026-10-20T06:30:00.000Z" },
+    { "userId": "9d2e...", "email": "ravi@example.com", "firstName": "Ravi", "lastName": "Kumar", "role": "member", "joinedAt": "2026-10-21T09:00:00.000Z" }
+  ]
+}
+```
+
+## PATCH /auth/organizations/:organizationId/members/:memberUserId
+
+Changes a member's role. Admins manage members and admins; **only owners** can make or unmake owners. Session checked live.
+
+**Request**
+
+```json
+{ "role": "admin" }
+```
+
+`role` is one of `"owner"`, `"admin"`, `"member"`.
+
+**Response `200`:** `{ "success": true }`. Errors: `403 FORBIDDEN`, `404 NOT_FOUND`, `409 LAST_OWNER`.
+
+## DELETE /auth/organizations/:organizationId/members/:memberUserId
+
+Removes a member. Use your own user id to **leave**. Session checked live. **Response `200`:** `{ "success": true }`. Errors: `403 FORBIDDEN`, `404 NOT_FOUND`, `409 LAST_OWNER`.
+
+---
+
+## GET /auth/organizations/:organizationId/invitations
+
+Admin or owner. Open (not accepted, not cancelled) invitations.
+
+**Response `200`**
+
+```json
+{
+  "success": true,
+  "invitations": [
+    {
+      "id": "c3d4...",
+      "organizationId": "a1b2...",
+      "email": "ravi@example.com",
+      "role": "member",
+      "invitedByUserId": "5f0c...",
+      "expiresAt": "2026-10-27T06:30:00.000Z",
+      "acceptedAt": null,
+      "revokedAt": null,
+      "createdAt": "2026-10-20T06:30:00.000Z"
+    }
+  ]
+}
+```
+
+## POST /auth/organizations/:organizationId/invitations
+
+Admin or owner (inviting an `owner` needs an owner). Sends an `organization_invitation` email; a new invitation to the same email replaces the old one. Session checked live.
+
+**Request**
+
+```json
+{ "email": "ravi@example.com", "role": "member" }
+```
+
+**Response `201`:** `{ "success": true }`. Errors: `400 INVALID_EMAIL`, `403 FORBIDDEN`.
+
+## DELETE /auth/organizations/:organizationId/invitations/:invitationId
+
+Admin or owner. Cancels an open invitation. Session checked live. **Response `200`:** `{ "success": true }`. Errors: `404 NOT_FOUND`.

package/docs/endpoints/passkeys.md

@@ -0,0 +1,195 @@
+# Passkeys
+
+Needs `passkeys.enabled` and the `passkeys` option on the server; otherwise `403 SIGN_IN_METHOD_DISABLED` / `501 NOT_CONFIGURED`. Each ceremony is two calls: **options** (the server creates a challenge) and **verify** (the device signed it). Browser code is in [Sign-in flows](../sign-in-flows.md#passkeys). Shared formats, the sign-in result and the user object are described in [Endpoints](README.md).
+
+---
+
+## POST /auth/passkeys/register/options
+
+Starts adding a passkey for the signed-in user.
+
+| | |
+|---|---|
+| Auth | User, session checked live |
+
+**Request:** no body.
+
+**Response `200`**
+
+```json
+{
+  "success": true,
+  "challengeToken": "ch_Zm9vYmFyZXhhbXBsZWNoYWxsZW5nZXRva2VuMTIzNDU2Nzg",
+  "options": {
+    "challenge": "lB3yW9kQ2x...",
+    "rp": { "name": "MyApp", "id": "myapp.com" },
+    "user": { "id": "NWYwYzhhMmUt...", "name": "asha@example.com", "displayName": "Asha Rao" },
+    "pubKeyCredParams": [{ "alg": -8, "type": "public-key" }, { "alg": -7, "type": "public-key" }, { "alg": -257, "type": "public-key" }],
+    "timeout": 60000,
+    "attestation": "none",
+    "excludeCredentials": [],
+    "authenticatorSelection": { "residentKey": "required", "userVerification": "required", "requireResidentKey": true }
+  }
+}
+```
+
+Pass `options` unchanged to `startRegistration({ optionsJSON: options })` (browser) or your platform's passkey API. The challenge expires after 5 minutes.
+
+**Errors**
+
+| Status | `code` | When |
+|---|---|---|
+| 400 | `VALIDATION_ERROR` | `problems: ["too many passkeys"]` (20 per user) |
+
+---
+
+## POST /auth/passkeys/register/verify
+
+Saves the new passkey.
+
+| | |
+|---|---|
+| Auth | User, session checked live |
+
+**Request**
+
+```json
+{
+  "challengeToken": "ch_Zm9vYmFyZXhhbXBsZWNoYWxsZW5nZXRva2VuMTIzNDU2Nzg",
+  "name": "My laptop",
+  "response": {
+    "id": "Q2xpZW50Q3JlZGVudGlhbElk",
+    "rawId": "Q2xpZW50Q3JlZGVudGlhbElk",
+    "type": "public-key",
+    "response": {
+      "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIi...",
+      "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YV...",
+      "transports": ["internal", "hybrid"]
+    },
+    "clientExtensionResults": {},
+    "authenticatorAttachment": "platform"
+  }
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `challengeToken` | string | yes | from `register/options` |
+| `response` | object | yes | exactly what the browser / platform API returned, as JSON |
+| `name` | string | no | up to 60 characters; default `"Passkey"` |
+
+**Response `200`**
+
+```json
+{
+  "success": true,
+  "passkey": { "id": "a7c1...", "name": "My laptop", "isBackedUp": true, "createdAt": "2026-10-20T06:30:00.000Z", "lastUsedAt": null }
+}
+```
+
+**Errors**
+
+| Status | `code` | When |
+|---|---|---|
+| 400 | `INVALID_TOKEN` | Challenge unknown, used or expired |
+| 401 | `INVALID_PASSKEY` | Verification failed (wrong origin, no fingerprint/PIN, tampered response) |
+
+---
+
+## POST /auth/passkeys/sign-in/options
+
+Starts a passkey sign-in. No email is needed: the device offers the user's passkeys for your site.
+
+| | |
+|---|---|
+| Auth | Public |
+| Rate limit | 30 per IP per 15 minutes |
+
+**Request:** no body.
+
+**Response `200`**
+
+```json
+{
+  "success": true,
+  "challengeToken": "ch_YW5vdGhlcmV4YW1wbGVjaGFsbGVuZ2V0b2tlbjEyMzQ1Njc",
+  "options": { "challenge": "pX9...", "timeout": 60000, "rpId": "myapp.com", "userVerification": "required" }
+}
+```
+
+---
+
+## POST /auth/passkeys/sign-in/verify
+
+Finishes the sign-in. No 2FA step follows: a passkey counts as two factors.
+
+| | |
+|---|---|
+| Auth | Public |
+
+**Request**
+
+```json
+{
+  "challengeToken": "ch_YW5vdGhlcmV4YW1wbGVjaGFsbGVuZ2V0b2tlbjEyMzQ1Njc",
+  "response": {
+    "id": "Q2xpZW50Q3JlZGVudGlhbElk",
+    "rawId": "Q2xpZW50Q3JlZGVudGlhbElk",
+    "type": "public-key",
+    "response": {
+      "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0Ii...",
+      "authenticatorData": "SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MFAAAAAQ",
+      "signature": "MEUCIQDf...",
+      "userHandle": "NWYwYzhhMmUt..."
+    },
+    "clientExtensionResults": {}
+  }
+}
+```
+
+**Response `200`:** the [sign-in result](README.md#sign-in-result) (always `signed_in` when successful).
+
+**Errors**
+
+| Status | `code` | When |
+|---|---|---|
+| 400 | `INVALID_TOKEN` | Challenge unknown, used or expired |
+| 401 | `INVALID_PASSKEY` | Unknown passkey or bad signature |
+| 403 | `ACCOUNT_*` | See [sign-in result](README.md#sign-in-result) |
+
+---
+
+## GET /auth/passkeys
+
+| | |
+|---|---|
+| Auth | User |
+
+**Response `200`**
+
+```json
+{
+  "success": true,
+  "passkeys": [
+    { "id": "a7c1...", "name": "My laptop", "isBackedUp": true, "createdAt": "2026-10-20T06:30:00.000Z", "lastUsedAt": "2026-10-21T08:00:00.000Z" }
+  ]
+}
+```
+
+## PATCH /auth/passkeys/:passkeyId
+
+Renames a passkey. Auth: User.
+
+**Request**
+
+```json
+{ "name": "Work phone" }
+```
+
+**Response `200`:** `{ "success": true }`. Errors: `404 NOT_FOUND`.
+
+## DELETE /auth/passkeys/:passkeyId
+
+Removes a passkey. Auth: User, session checked live. No body.
+
+**Response `200`:** `{ "success": true }`. Errors: `404 NOT_FOUND`, `409 LAST_SIGN_IN_METHOD`.

package/docs/endpoints/passwordless.md

@@ -0,0 +1,214 @@
+# Passwordless: email code, magic link, phone code
+
+The same endpoints **sign in**, **sign up** (when `allowSignUp` is on) and **verify** the email or phone, because receiving the code proves ownership. Shared formats, the sign-in result and the user object are described in [Endpoints](README.md).
+
+## Sign-up details
+
+The verify endpoints accept these optional fields. They are used **only when the request creates a new account**:
+
+| Field | Type | Rules |
+|---|---|---|
+| `firstName` | string | up to 100 characters |
+| `lastName` | string | up to 100 characters |
+| `acceptTerms` | boolean | |
+| `acceptPrivacyPolicy` | boolean | |
+
+If your settings require them and they are missing, the response is:
+
+```json
+{
+  "success": false,
+  "code": "VALIDATION_ERROR",
+  "message": "Some fields are missing or invalid.",
+  "missingSignUpDetails": ["firstName", "lastName", "acceptTerms"]
+}
+```
+
+For codes, the code is **not used up** by this error: show a form for the missing details and send the same code again with them.
+
+---
+
+## POST /auth/email/send-otp
+
+Emails a sign-in code. Needs `emailOtp.enabled`.
+
+| | |
+|---|---|
+| Auth | Public |
+| Rate limit | 10 per IP and 5 per email per hour; one code per minute per email |
+
+**Request**
+
+```json
+{ "email": "asha@example.com" }
+```
+
+**Response `200`** (always the same, whether or not the email has an account):
+
+```json
+{ "success": true, "message": "If this destination can receive codes, a code is on its way." }
+```
+
+**Errors**
+
+| Status | `code` | When |
+|---|---|---|
+| 400 | `INVALID_EMAIL` | |
+| 403 | `SIGN_IN_METHOD_DISABLED` | `emailOtp.enabled` is off |
+| 429 | `TOO_MANY_REQUESTS` | A code was sent less than `emailOtp.resendAfterSeconds` ago (60 by default, returned as `retryAfterSeconds`), or a rate limit was hit |
+
+---
+
+## POST /auth/email/verify-otp
+
+Signs in with the emailed code. Marks the email verified. Creates the account if the email is new and sign-up is allowed.
+
+| | |
+|---|---|
+| Auth | Public |
+| Rate limit | 30 per IP per 15 minutes |
+
+**Request**
+
+```json
+{
+  "email": "asha@example.com",
+  "code": "482913",
+  "firstName": "Asha",
+  "lastName": "Rao",
+  "acceptTerms": true,
+  "acceptPrivacyPolicy": true
+}
+```
+
+| Field | Type | Required |
+|---|---|---|
+| `email` | string | yes |
+| `code` | string | yes |
+| sign-up details | | only for new accounts, see above |
+
+**Response `200`:** the [sign-in result](README.md#sign-in-result).
+
+**Errors**
+
+| Status | `code` | When | Extra |
+|---|---|---|---|
+| 400 | `INVALID_OTP` | Wrong code | `attemptsLeft` |
+| 400 | `OTP_EXPIRED` | Expired (10 min), used, 5 wrong tries, or never sent | |
+| 400 | `VALIDATION_ERROR` | New account and details missing | `missingSignUpDetails` |
+| 400 | `EMAIL_DOMAIN_NOT_ALLOWED` | New account outside `allowedEmailDomains` | |
+| 403 | `SIGN_UP_CLOSED` | New email and sign-up is off | |
+
+```json
+{ "success": false, "code": "INVALID_OTP", "message": "This code is incorrect.", "attemptsLeft": 3 }
+```
+
+---
+
+## POST /auth/magic-link/send
+
+Emails a one-click sign-in link (valid `magicLink.expiresInMinutes`, 15 by default). Needs `magicLink.enabled`.
+
+| | |
+|---|---|
+| Auth | Public |
+| Rate limit | 10 per IP and 3 per email per hour |
+
+**Request**
+
+```json
+{ "email": "asha@example.com" }
+```
+
+**Response `200`** (always the same):
+
+```json
+{ "success": true, "message": "If this email can sign in, a sign-in link is on its way." }
+```
+
+---
+
+## POST /auth/magic-link/verify
+
+Signs in with the token from the link. The link works **once**, so for new users collect the sign-up details on the page before calling this.
+
+| | |
+|---|---|
+| Auth | Public |
+| Rate limit | 30 per IP per 15 minutes |
+
+**Request**
+
+```json
+{
+  "token": "ml_Q2x4bWZkY2V0ZXN0dG9rZW5leGFtcGxlMTIzNDU2Nzg5MDE",
+  "firstName": "Asha",
+  "lastName": "Rao",
+  "acceptTerms": true,
+  "acceptPrivacyPolicy": true
+}
+```
+
+**Response `200`:** the [sign-in result](README.md#sign-in-result).
+
+**Errors**
+
+| Status | `code` | When |
+|---|---|---|
+| 400 | `INVALID_TOKEN` | Unknown, used or expired link |
+| 400 | `VALIDATION_ERROR` | New account and `missingSignUpDetails` |
+| 403 | `SIGN_UP_CLOSED` / `SIGN_IN_METHOD_DISABLED` | |
+
+---
+
+## POST /auth/phone/send-otp
+
+Sends a sign-in code by SMS. Needs `phoneOtp.enabled` and an `smsSender`.
+
+| | |
+|---|---|
+| Auth | Public |
+| Rate limit | 10 per IP and 5 per number per hour; one code per minute per number |
+
+**Request**
+
+```json
+{ "phoneNumber": "+91 98765 43210" }
+```
+
+**Response `200`** (always the same):
+
+```json
+{ "success": true, "message": "If this destination can receive codes, a code is on its way." }
+```
+
+**Errors**
+
+| Status | `code` | When |
+|---|---|---|
+| 400 | `INVALID_PHONE` | No country code, or not a phone number |
+| 400 | `PHONE_COUNTRY_NOT_ALLOWED` | Country not in `phoneOtp.allowedCountryCodes` |
+| 403 | `SIGN_IN_METHOD_DISABLED` | Phone sign-in is off |
+| 501 | `NOT_CONFIGURED` | No `smsSender` set up on the server |
+| 429 | `TOO_MANY_REQUESTS` | Within `phoneOtp.resendAfterSeconds` (60 by default) of the last code, or a rate limit |
+
+---
+
+## POST /auth/phone/verify-otp
+
+Signs in with the SMS code. Marks the phone verified, which is also how an account with `pendingVerifications: ["phone"]` finishes activation.
+
+| | |
+|---|---|
+| Auth | Public |
+| Rate limit | 30 per IP per 15 minutes |
+
+**Request**
+
+```json
+{ "phoneNumber": "+919876543210", "code": "482913", "firstName": "Asha", "lastName": "Rao", "acceptTerms": true, "acceptPrivacyPolicy": true }
+```
+
+**Response `200`:** the [sign-in result](README.md#sign-in-result).
+
+**Errors:** same as [email verify-otp](#post-authemailverify-otp), plus `INVALID_PHONE`.