@productcraft/auth 0.5.2 → 0.7.1

package/README.md

@@ -90,8 +90,11 @@ await consumer.auth.signup({
 
 await consumer.auth.refresh({ refresh_token });
 await consumer.auth.logout({ refresh_token });
-await consumer.auth.requestReset({ email });
-await consumer.auth.resetPassword({ token, new_password: "..." });
+
+// Forgot password. `sendPasswordResetEmail` mints the code AND emails it
+// via Mail — this is what you want for a normal reset flow.
+await consumer.auth.sendPasswordResetEmail({ email });
+await consumer.auth.resetPassword({ code, new_password: "..." });
 
 // Sign in with Apple (native iOS flow). See "Federated sign-in" below.
 await consumer.auth.signinWithProvider({
@@ -116,6 +119,27 @@ await consumer.oauth.clientCredentials({ clientId, clientSecret, scope });
 
 > **Wire-shape note.** Auth's JSON wire is snake_case, and the SDK returns response objects as-is (e.g. `access_token`, `refresh_token`, `token_type`, `expires_in`). Request DTOs follow the same convention; some convenience fields (`identifier`, `password`, `nonce`) are unaffected, but anywhere the spec uses an underscore the SDK does too.
 
+### One-time codes: who sends the email?
+
+Verification and password-reset each come in two flavours. **Picking the wrong one is silent** — you get a `2xx` and no email is ever sent — so choose deliberately:
+
+| Method | Mints a code | Sends the email | Returns |
+| --- | --- | --- | --- |
+| `auth.requestVerification()` | ✅ | ❌ | `{ code, expires_at }` |
+| `auth.sendVerificationEmail()` | ✅ | ✅ via Mail | `{ expires_at }` |
+| `auth.requestReset()` | ✅ | ❌ | `{ code, expires_at }` |
+| `auth.sendPasswordResetEmail()` | ✅ | ✅ via Mail | `{ expires_at }` |
+
+**Use `send*` for a normal flow.** Mail delivers the code using your app's configured sender and template, and you never handle the plaintext code.
+
+**Use `request*` only when you are delivering the code yourself** — your own SMTP, an SMS provider, or consuming it in-process (e.g. provisioning a test account). If you call `request*` and drop the returned `code` on the floor, your users get nothing and nothing is logged anywhere, because no send was ever attempted.
+
+Each pair is gated by a *separate* PAK permission (`auth.user.verify.create` vs `auth.user.verify.send-email`, and likewise for `password-reset`), so a workspace can enable minting without enabling outbound mail.
+
+The `send*` methods fail loudly with a typed `412` when Mail isn't ready — `ENVOI_NOT_ENABLED`, `ENVOI_SENDER_NOT_CONFIGURED`, `ENVOI_TEMPLATE_NOT_CONFIGURED`, `ENVOI_APP_NOT_BOUND_TO_WORKSPACE` — or `503 ENVOI_DISPATCH_FAILED`. If your endpoint returns a uniform response to prevent account enumeration, catch and **log** these rather than discarding them; a swallowed 412 is indistinguishable from the silent failure above.
+
+Both `request*` and `send*` return `{}` when the contact doesn't match (or is already verified / unverified as appropriate). That's the anti-enumeration contract, not an error — there is nothing to branch on.
+
 ## Federated sign-in (Apple, Google)
 
 `consumer.auth.signinWithProvider` lets a BFF exchange a provider-issued identity token for an Auth `{ access_token, refresh_token }` pair. The endpoint creates the EndUser on first sign-in and returns the same account on subsequent ones — the SDK is a thin wrapper over Auth's `POST /{appSlug}/v1/auth/oauth/{provider}` which does the heavy lifting (Apple JWKS verification, issuer pinning, audience validation against the app's configured native client ids, server-side nonce replay protection, account creation / linking).
@@ -193,6 +217,56 @@ await consumer.auth.signinWithProvider({
 
 No SDK upgrade required — the per-provider TS enum widens automatically with the next spec refresh.
 
+## Passkeys (WebAuthn)
+
+Passkeys are switched on per app in the console (relying-party id + the
+site origin in `allowed_redirect_origins`). Once they are, each ceremony
+is one call on `auth.consumer(appSlug).passkeys`. The helpers run
+**in the browser** — they drive `navigator.credentials` — but importing
+the package anywhere is safe; nothing touches a browser global until you
+call them.
+
+```ts
+import { Auth, isPasskeySupported, PasskeyError } from "@productcraft/auth";
+
+if (!isPasskeySupported()) hidePasskeyButton(); // false in Node and in insecure contexts
+
+// Enrol — signed-in user adds a passkey as an MFA factor
+const me = new Auth({ auth: { type: "bearer", token: accessToken } }).consumer("acme");
+const { factor, recovery_codes } = await me.passkeys.enroll({ label: "MacBook" });
+// show recovery_codes once — they are not retrievable later
+
+// Passwordless sign-in — no password, no email; discoverable credential
+const anon = new Auth().consumer("acme");
+const session = await anon.passkeys.signIn({ mediation: "conditional" }); // amr: ["webauthn"]
+
+// MFA step of a password sign-in — when signin() answered { mfa_required, mfa_token, factors }
+const session2 = await anon.passkeys.completeMfaChallenge({ mfa_token: signin.mfa_token });
+
+// Step-up inside a live session
+const { amr, mfa_at } = await me.passkeys.stepUp();
+```
+
+Each helper does the options call → `navigator.credentials.create()` /
+`.get()` → verify call, with every buffer base64url-encoded in both
+directions and the `public_key` members renamed to the WebAuthn spec's
+camelCase (the Auth wire is snake_case). Browser-side failures reject
+with `PasskeyError` (`code`: `unsupported`, `cancelled`, `timeout`,
+`invalid_state`, `security`, `no_credential`, `unknown`; `cause` holds
+the DOM error); server-side failures stay `AuthHttpError`, so a 401 on
+a forged or replayed assertion is distinguishable from the user
+dismissing the prompt. Pass `signal: AbortSignal.timeout(ms)` to bound
+the prompt yourself.
+
+The encoding layer is exported for anyone who wants the pieces:
+`toB64u`, `fromB64u`, `decodeOptions`, `encodeCredential`, plus
+`createPasskeyCredential(public_key)` / `getPasskeyCredential(public_key)`
+which wrap `navigator.credentials` on their own.
+
+`signIn()` never sends an identifier: `/auth/passkey/options` takes none
+by design (it would be an account-existence oracle), so sign-in relies on
+a discoverable (resident) credential.
+
 ## JWT verification
 
 Every Auth app publishes a JWKS at `/{appSlug}/v1/.well-known/jwks.json`. The SDK gives you a verified-claims helper and a jose-compatible JWKS resolver.
@@ -255,7 +329,7 @@ For the per-app boundary, the JWKS is the cryptographic gate (only the app's key
 
 ### Passport integration
 
-Use the companion package [`@productcraft/auth-passport`](../auth-passport):
+Use the companion package [`@productcraft/auth-passport`](https://github.com/clauderanelagh/productcraft-node/tree/main/packages/auth-passport):
 
 ```bash
 npm install @productcraft/auth-passport passport-jwt
@@ -319,4 +393,4 @@ When the spec changes, the nightly `spec-refresh` workflow re-runs codegen and o
 
 ## License
 
-[MIT](../../LICENSE).
+[MIT](https://github.com/clauderanelagh/productcraft-node/blob/main/LICENSE).