@productcraft/auth 0.6.0 → 0.8.0

package/README.md

@@ -13,9 +13,8 @@ Server-side only. For React / Next.js apps, call this from your backend (BFF pat
 ```ts
 import { Auth } from "@productcraft/auth";
 
-const auth = new Auth({
-  auth: { type: "apiKey", key: process.env.PCFT_KEY! },
-});
+// Reads PRODUCTCRAFT_API_KEY (and PRODUCTCRAFT_AUTH_APP) from the environment
+const auth = new Auth();
 ```
 
 The SDK splits into three caller contexts.
@@ -217,6 +216,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.
@@ -260,6 +309,8 @@ try {
 
 Behind the scenes: JWKS fetched once, cached in-memory (10 min TTL by default), singleflighted so 100 concurrent verifies do 1 fetch, auto-refetched if a token's `kid` isn't in the cached JWKS (rotation handling). Issuer + audience are checked against `scope.acceptedIssuers` + `scope.expectedAudience` automatically.
 
+**Refresh tokens are refused.** A token carrying `token_use: "refresh"` (or the older `type: "refresh"`) throws `JwtRefreshTokenError` (code `ERR_JWT_REFRESH_TOKEN`) even when its signature, issuer and audience are valid: a refresh token is only good at the refresh endpoint, never as an access token. `createAuthJwtStrategy` from `@productcraft/auth-passport` refuses them too. If you call `jwtVerify` yourself (below), check `isRefreshToken(payload)` and reject.
+
 ### Building blocks for `jose`, NestJS guards, Hono, etc.
 
 `scope.jwks.getKey` is a [jose-compatible](https://github.com/panva/jose) key resolver — pass it anywhere a `GetKeyFunction` is expected.
@@ -279,7 +330,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
@@ -318,11 +369,28 @@ import {
 } from "@productcraft/auth";
 ```
 
+## Credentials from the environment
+
+Server-side, omit `auth` and the client reads your workspace key from the environment:
+
+```bash
+# .env
+PRODUCTCRAFT_API_KEY=pcft_live_...
+PRODUCTCRAFT_AUTH_APP=acme           # default slug for auth.consumer()
+```
+
+- An explicit `auth` always wins over the environment.
+- Hosts are never read from the environment. Override them in code with `baseUrl`.
+- This is a server-only fallback. Never put a key in `NEXT_PUBLIC_*` or any other variable a bundler inlines into browser code.
+- `auth.app(appId)` and the workspace methods (`apps`, `stats`) use the explicit `auth`, else `PRODUCTCRAFT_API_KEY`.
+- `auth.consumer()` takes its slug from `PRODUCTCRAFT_AUTH_APP` when you omit it, and **never** reads a credential from the environment: consumer routes act for an end user, so only an explicit `auth` is sent. PAK-only consumer routes (`signup_requires_pak` sign-ups, tenants, code mint, factors) therefore need `new Auth({ auth: { type: "apiKey", key: process.env.MY_APP_PAK! } })`.
+
 ## Configuration
 
 ```ts
 new Auth({
   // Auth credential the SDK presents to Auth
+  // Omit to use PRODUCTCRAFT_API_KEY from the environment
   auth: { type: "apiKey", key: "pcft_live_..." }
       | { type: "bearer", token: "eyJ..." }
       | { type: "cookie", value: "auth_token=..." },
@@ -343,4 +411,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).