@spfn/auth 0.3.0-beta.23 → 0.3.0-beta.25

package/dist/client.d.ts

@@ -89,5 +89,105 @@ interface SignInWithPasskeyValue {
  * private key.
  */
 declare function signInWithPasskey(api: AuthApi, options?: SignInWithPasskeyOptions): Promise<PasskeyResult<SignInWithPasskeyValue>>;
+interface RenewSessionValue {
+    /** The new device key the session now runs on. */
+    keyId: string;
+}
+/**
+ * Renew a bound session key with a passkey assertion.
+ *
+ * What an app calls when a request came back `SessionRenewalRequiredError`: the
+ * session's short-lived key has run out and one WebAuthn ceremony puts a new one
+ * in the cookie. The person sees the system prompt, not a sign-in form.
+ *
+ * The body is `{ response }` and nothing else. The expiring key's id lives in an
+ * HttpOnly cookie that page script cannot read, and the new key pair is the
+ * Next.js proxy's to generate — both are injected there, exactly as they are for
+ * `signInWithPasskey`. Nothing here handles a private key.
+ *
+ * Refusals from the server are rejected promises rather than results, on the same
+ * rule the rest of this file follows: a `SessionRenewalRefusedError` means the
+ * server declined — the key is past its grace, or was revoked — and the app's
+ * answer is to send the person to sign in, which is not the same as the ceremony
+ * failing.
+ */
+declare function renewSession(api: AuthApi): Promise<PasskeyResult<RenewSessionValue>>;
+/** What a successful disable answers with — the mode the account is now in. */
+interface DisableSessionBindingValue {
+    mode: 'none';
+}
+interface DisableSessionBindingOptions {
+    /**
+     * The account password, for a browser with no passkey to hand.
+     *
+     * Send it, or let the ceremony run — one of the two is required. Key age is
+     * deliberately not accepted: a session cookie copied in the minutes after a
+     * sign-in carries exactly that, and it must not be able to switch the
+     * protection off.
+     */
+    currentPassword?: string;
+}
+/**
+ * Turn session binding off for this account.
+ *
+ * With `currentPassword` this is one call. Without it, the passkey ceremony runs
+ * first and the assertion is what proves ownership — the same ceremony renewal
+ * uses, for the same reason.
+ *
+ * Turning binding *on* needs no ceremony and no helper: it is
+ * `api.setSessionBinding.call({ body: { mode: 'passkey' } })`. Leaving is the
+ * privileged direction here, which is the reverse of the usual posture and is
+ * the whole reason this helper exists.
+ */
+declare function disableSessionBinding(api: AuthApi, options?: DisableSessionBindingOptions): Promise<PasskeyResult<DisableSessionBindingValue>>;
+/**
+ * What a completed step-up answers with — the sign-in the 202 was standing in for.
+ *
+ * Deliberately loose about the login fields. Through the Next.js proxy the
+ * session is already sealed by the time this resolves and the app reads it from
+ * the session cookie; a native client reads `userId` off the body. `keyId` and
+ * `challengeHash` are the proxy's business and are not repeated here.
+ */
+interface CompleteMfaValue {
+    userId?: string;
+    keyId: string;
+}
+/**
+ * Finish a sign-in that answered `mfaRequired` with a code from the
+ * authenticator app.
+ *
+ * The challenge is the `secret` from that 202 — or, on the web OAuth path, the
+ * `?challenge=` the callback handler put on the confirm page's URL. It is single
+ * use and lives ten minutes.
+ *
+ * A wrong code is a rejected promise carrying `MfaVerificationFailedError`, not
+ * a result: it is the server declining rather than a ceremony failing, and there
+ * is no ceremony here at all. Five wrong ones end the challenge and the person
+ * signs in again.
+ *
+ * @param api - the typed auth client
+ * @param challenge - the challenge secret from the 202 or the callback query
+ * @param code - the six digits, spaces and dashes and all
+ */
+declare function completeMfaWithCode(api: AuthApi, challenge: string, code: string): Promise<CompleteMfaValue>;
+/**
+ * Finish the same sign-in with one of the ten written-down recovery codes.
+ *
+ * Single use, and the count in `mfa/status` drops by one — an app that warns at
+ * two remaining reads it from there after this resolves.
+ */
+declare function completeMfaWithRecoveryCode(api: AuthApi, challenge: string, recoveryCode: string): Promise<CompleteMfaValue>;
+/**
+ * Finish the same sign-in with a passkey the owner marked as a second factor.
+ *
+ * `options` from the server, `navigator.credentials` in the browser, `verify`
+ * back — the shape every ceremony in this file has, and a discriminated union
+ * rather than a throw for the same reason: a person who dismisses the system
+ * sheet has not hit an application error.
+ *
+ * The challenge is what names the account, since there is no session yet. A
+ * passkey the owner never marked is refused with the same body as a wrong code.
+ */
+declare function completeMfaWithPasskey(api: AuthApi, challenge: string): Promise<PasskeyResult<CompleteMfaValue>>;
 
-export { type AuthApi, type EnrollPasskeyOptions, type EnrollPasskeyValue, type PasskeyFailureReason, type PasskeyResult, type SignInWithPasskeyOptions, type SignInWithPasskeyValue, enrollPasskey, isConditionalMediationAvailable, isPasskeySupported, signInWithPasskey };
+export { type AuthApi, type CompleteMfaValue, type DisableSessionBindingOptions, type DisableSessionBindingValue, type EnrollPasskeyOptions, type EnrollPasskeyValue, type PasskeyFailureReason, type PasskeyResult, type RenewSessionValue, type SignInWithPasskeyOptions, type SignInWithPasskeyValue, completeMfaWithCode, completeMfaWithPasskey, completeMfaWithRecoveryCode, disableSessionBinding, enrollPasskey, isConditionalMediationAvailable, isPasskeySupported, renewSession, signInWithPasskey };

package/dist/client.js

@@ -50,10 +50,75 @@ async function signInWithPasskey(api, options = {}) {
   });
   return { ok: true, ...session };
 }
+async function renewSession(api) {
+  if (!isPasskeySupported()) {
+    return { ok: false, reason: "unsupported" };
+  }
+  const optionsJSON = await api.sessionRenewOptions.call({
+    body: {}
+  });
+  let response;
+  try {
+    response = await startAuthentication({ optionsJSON });
+  } catch (error) {
+    return { ok: false, reason: failureReason(error, "no-credential"), error };
+  }
+  const renewed = await api.sessionRenewVerify.call({
+    body: { response }
+  });
+  return { ok: true, keyId: renewed.keyId };
+}
+async function disableSessionBinding(api, options = {}) {
+  if (options.currentPassword) {
+    await api.setSessionBinding.call({ body: { mode: "none", currentPassword: options.currentPassword } });
+    return { ok: true, mode: "none" };
+  }
+  if (!isPasskeySupported()) {
+    return { ok: false, reason: "unsupported" };
+  }
+  const optionsJSON = await api.sessionBindingDisableOptions.call({
+    body: {}
+  });
+  let response;
+  try {
+    response = await startAuthentication({ optionsJSON });
+  } catch (error) {
+    return { ok: false, reason: failureReason(error, "no-credential"), error };
+  }
+  await api.setSessionBinding.call({ body: { mode: "none", response } });
+  return { ok: true, mode: "none" };
+}
+async function completeMfaWithCode(api, challenge, code) {
+  return await api.mfaVerify.call({ body: { challenge, code } });
+}
+async function completeMfaWithRecoveryCode(api, challenge, recoveryCode) {
+  return await api.mfaVerify.call({ body: { challenge, recoveryCode } });
+}
+async function completeMfaWithPasskey(api, challenge) {
+  if (!isPasskeySupported()) {
+    return { ok: false, reason: "unsupported" };
+  }
+  const optionsJSON = await api.mfaVerifyOptions.call({
+    body: { challenge }
+  });
+  let response;
+  try {
+    response = await startAuthentication({ optionsJSON });
+  } catch (error) {
+    return { ok: false, reason: failureReason(error, "no-credential"), error };
+  }
+  const verified = await api.mfaVerify.call({ body: { challenge, response } });
+  return { ok: true, ...verified };
+}
 export {
+  completeMfaWithCode,
+  completeMfaWithPasskey,
+  completeMfaWithRecoveryCode,
+  disableSessionBinding,
   enrollPasskey,
   isConditionalMediationAvailable,
   isPasskeySupported,
+  renewSession,
   signInWithPasskey
 };
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client/passkeys.ts"],"sourcesContent":["/**\n * @spfn/auth/client - Passkeys (WebAuthn)\n *\n * Four browser helpers over the two ceremonies. Each one is `options` from the\n * server, `navigator.credentials` in the browser, `verify` back to the server —\n * and each answers with a discriminated union instead of throwing.\n *\n * That is the whole point of this file. A person closing the system passkey\n * sheet raises `NotAllowedError`, and so does a person whose authenticator has\n * nothing to offer; neither is an application error, and code that has to tell\n * them apart by catching and re-reading `error.name` gets it wrong once and\n * shows a red banner to someone who simply changed their mind.\n *\n * Ships to browsers: no Node built-ins here, `Buffer` included. The base64url\n * helpers come from `@simplewebauthn/browser`, which is bundled into this entry.\n */\n\nimport {\n    browserSupportsWebAuthn,\n    browserSupportsWebAuthnAutofill,\n    startAuthentication,\n    startRegistration,\n    type AuthenticationResponseJSON,\n    type PublicKeyCredentialCreationOptionsJSON,\n    type PublicKeyCredentialRequestOptionsJSON,\n    type RegistrationResponseJSON,\n} from '@simplewebauthn/browser';\n\nimport type { authApi } from '@spfn/auth';\n\n/** The typed auth client these helpers drive. */\nexport type AuthApi = typeof authApi;\n\n/**\n * Why a ceremony did not produce a session.\n *\n * - `unsupported`: this browser has no WebAuthn at all\n * - `cancelled`: the person dismissed the prompt\n * - `no-credential`: the authenticator had nothing for this relying party\n * - `error`: anything else, with the original error attached\n */\nexport type PasskeyFailureReason = 'unsupported' | 'cancelled' | 'no-credential' | 'error';\n\nexport type PasskeyResult<T> =\n    | ({ ok: true } & T)\n    | { ok: false; reason: PasskeyFailureReason; error?: unknown };\n\n/** Whether this browser can run a WebAuthn ceremony at all. */\nexport function isPasskeySupported(): boolean\n{\n    return browserSupportsWebAuthn();\n}\n\n/**\n * Whether the browser can offer passkeys inside the ordinary autofill dropdown.\n *\n * Worth checking before rendering a sign-in form: conditional mediation is what\n * turns a passkey into \"tap the suggestion above the keyboard\", and where it is\n * missing the form needs a visible \"Sign in with a passkey\" button instead.\n */\nexport async function isConditionalMediationAvailable(): Promise<boolean>\n{\n    return await browserSupportsWebAuthnAutofill();\n}\n\n/**\n * The reason a ceremony failure should be reported as.\n *\n * `NotAllowedError` is the browser's answer both to \"the person said no\" and to\n * \"nothing here matched\", and the specification deliberately does not\n * distinguish them — telling a caller which applied would say whether a\n * credential for this site exists on the device. So it is `cancelled` in both\n * cases on registration, and `no-credential` on a sign-in that offered no\n * credentials to choose from, which is the reading a UI wants.\n */\nfunction failureReason(error: unknown, whenNotAllowed: PasskeyFailureReason): PasskeyFailureReason\n{\n    return (error as { name?: string } | null)?.name === 'NotAllowedError' ? whenNotAllowed : 'error';\n}\n\nexport interface EnrollPasskeyOptions\n{\n    /** Owner-facing name for the passkey list, e.g. the device model. */\n    label?: string;\n    /** Sent when the session proved itself longer ago than the recent-auth window. */\n    currentPassword?: string;\n}\n\nexport interface EnrollPasskeyValue\n{\n    passkeyId: string;\n    label: string | null;\n    createdAt: string;\n}\n\n/**\n * Enroll a passkey on the device in front of the user.\n *\n * Requires a signed-in session. A 403 with code `RECENT_AUTH_REQUIRED` from the\n * options call means the caller should prompt for the password and try again\n * with `currentPassword`; that is a rejected promise, not a result here, because\n * it is the server declining rather than the ceremony failing.\n */\nexport async function enrollPasskey(\n    api: AuthApi,\n    options: EnrollPasskeyOptions = {},\n): Promise<PasskeyResult<EnrollPasskeyValue>>\n{\n    if (!isPasskeySupported())\n    {\n        return { ok: false, reason: 'unsupported' };\n    }\n\n    const optionsJSON = await api.passkeyRegisterOptions.call({\n        body: { currentPassword: options.currentPassword },\n    }) as PublicKeyCredentialCreationOptionsJSON;\n\n    let response: RegistrationResponseJSON;\n\n    try\n    {\n        response = await startRegistration({ optionsJSON });\n    }\n    catch (error)\n    {\n        return { ok: false, reason: failureReason(error, 'cancelled'), error };\n    }\n\n    const enrolled = await api.passkeyRegisterVerify.call({\n        body: { response, label: options.label },\n    }) as EnrollPasskeyValue;\n\n    return { ok: true, ...enrolled };\n}\n\nexport interface SignInWithPasskeyOptions\n{\n    /**\n     * Offer the passkey through the browser's autofill dropdown instead of a\n     * modal. Needs an `<input autocomplete=\"username webauthn\">` on the page.\n     */\n    conditional?: boolean;\n    deviceName?: string;\n    platform?: string;\n}\n\nexport interface SignInWithPasskeyValue\n{\n    userId: string;\n    publicId: string;\n    email?: string;\n    phone?: string;\n    passwordChangeRequired: boolean;\n}\n\n/**\n * Sign in with a passkey, no identifier asked for.\n *\n * The device key the session runs on is generated and stored by the Next.js\n * proxy interceptor, exactly as on a password login — nothing here handles a\n * private key.\n */\nexport async function signInWithPasskey(\n    api: AuthApi,\n    options: SignInWithPasskeyOptions = {},\n): Promise<PasskeyResult<SignInWithPasskeyValue>>\n{\n    if (!isPasskeySupported())\n    {\n        return { ok: false, reason: 'unsupported' };\n    }\n\n    const optionsJSON = await api.passkeyLoginOptions.call({\n        body: {},\n    }) as PublicKeyCredentialRequestOptionsJSON;\n\n    let response: AuthenticationResponseJSON;\n\n    try\n    {\n        response = await startAuthentication({ optionsJSON, useBrowserAutofill: options.conditional === true });\n    }\n    catch (error)\n    {\n        return { ok: false, reason: failureReason(error, 'no-credential'), error };\n    }\n\n    const session = await api.passkeyLoginVerify.call({\n        body: { response },\n    }) as SignInWithPasskeyValue;\n\n    return { ok: true, ...session };\n}\n"],"mappings":";AAiBA;AAAA,EACI;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAKG;AAsBA,SAAS,qBAChB;AACI,SAAO,wBAAwB;AACnC;AASA,eAAsB,kCACtB;AACI,SAAO,MAAM,gCAAgC;AACjD;AAYA,SAAS,cAAc,OAAgB,gBACvC;AACI,SAAQ,OAAoC,SAAS,oBAAoB,iBAAiB;AAC9F;AAyBA,eAAsB,cAClB,KACA,UAAgC,CAAC,GAErC;AACI,MAAI,CAAC,mBAAmB,GACxB;AACI,WAAO,EAAE,IAAI,OAAO,QAAQ,cAAc;AAAA,EAC9C;AAEA,QAAM,cAAc,MAAM,IAAI,uBAAuB,KAAK;AAAA,IACtD,MAAM,EAAE,iBAAiB,QAAQ,gBAAgB;AAAA,EACrD,CAAC;AAED,MAAI;AAEJ,MACA;AACI,eAAW,MAAM,kBAAkB,EAAE,YAAY,CAAC;AAAA,EACtD,SACO,OACP;AACI,WAAO,EAAE,IAAI,OAAO,QAAQ,cAAc,OAAO,WAAW,GAAG,MAAM;AAAA,EACzE;AAEA,QAAM,WAAW,MAAM,IAAI,sBAAsB,KAAK;AAAA,IAClD,MAAM,EAAE,UAAU,OAAO,QAAQ,MAAM;AAAA,EAC3C,CAAC;AAED,SAAO,EAAE,IAAI,MAAM,GAAG,SAAS;AACnC;AA6BA,eAAsB,kBAClB,KACA,UAAoC,CAAC,GAEzC;AACI,MAAI,CAAC,mBAAmB,GACxB;AACI,WAAO,EAAE,IAAI,OAAO,QAAQ,cAAc;AAAA,EAC9C;AAEA,QAAM,cAAc,MAAM,IAAI,oBAAoB,KAAK;AAAA,IACnD,MAAM,CAAC;AAAA,EACX,CAAC;AAED,MAAI;AAEJ,MACA;AACI,eAAW,MAAM,oBAAoB,EAAE,aAAa,oBAAoB,QAAQ,gBAAgB,KAAK,CAAC;AAAA,EAC1G,SACO,OACP;AACI,WAAO,EAAE,IAAI,OAAO,QAAQ,cAAc,OAAO,eAAe,GAAG,MAAM;AAAA,EAC7E;AAEA,QAAM,UAAU,MAAM,IAAI,mBAAmB,KAAK;AAAA,IAC9C,MAAM,EAAE,SAAS;AAAA,EACrB,CAAC;AAED,SAAO,EAAE,IAAI,MAAM,GAAG,QAAQ;AAClC;","names":[]}
+{"version":3,"sources":["../src/client/passkeys.ts"],"sourcesContent":["/**\n * @spfn/auth/client - Passkeys (WebAuthn)\n *\n * Four browser helpers over the two ceremonies. Each one is `options` from the\n * server, `navigator.credentials` in the browser, `verify` back to the server —\n * and each answers with a discriminated union instead of throwing.\n *\n * That is the whole point of this file. A person closing the system passkey\n * sheet raises `NotAllowedError`, and so does a person whose authenticator has\n * nothing to offer; neither is an application error, and code that has to tell\n * them apart by catching and re-reading `error.name` gets it wrong once and\n * shows a red banner to someone who simply changed their mind.\n *\n * Ships to browsers: no Node built-ins here, `Buffer` included. The base64url\n * helpers come from `@simplewebauthn/browser`, which is bundled into this entry.\n */\n\nimport {\n    browserSupportsWebAuthn,\n    browserSupportsWebAuthnAutofill,\n    startAuthentication,\n    startRegistration,\n    type AuthenticationResponseJSON,\n    type PublicKeyCredentialCreationOptionsJSON,\n    type PublicKeyCredentialRequestOptionsJSON,\n    type RegistrationResponseJSON,\n} from '@simplewebauthn/browser';\n\nimport type { authApi } from '@spfn/auth';\n\n/** The typed auth client these helpers drive. */\nexport type AuthApi = typeof authApi;\n\n/**\n * Why a ceremony did not produce a session.\n *\n * - `unsupported`: this browser has no WebAuthn at all\n * - `cancelled`: the person dismissed the prompt\n * - `no-credential`: the authenticator had nothing for this relying party\n * - `error`: anything else, with the original error attached\n */\nexport type PasskeyFailureReason = 'unsupported' | 'cancelled' | 'no-credential' | 'error';\n\nexport type PasskeyResult<T> =\n    | ({ ok: true } & T)\n    | { ok: false; reason: PasskeyFailureReason; error?: unknown };\n\n/** Whether this browser can run a WebAuthn ceremony at all. */\nexport function isPasskeySupported(): boolean\n{\n    return browserSupportsWebAuthn();\n}\n\n/**\n * Whether the browser can offer passkeys inside the ordinary autofill dropdown.\n *\n * Worth checking before rendering a sign-in form: conditional mediation is what\n * turns a passkey into \"tap the suggestion above the keyboard\", and where it is\n * missing the form needs a visible \"Sign in with a passkey\" button instead.\n */\nexport async function isConditionalMediationAvailable(): Promise<boolean>\n{\n    return await browserSupportsWebAuthnAutofill();\n}\n\n/**\n * The reason a ceremony failure should be reported as.\n *\n * `NotAllowedError` is the browser's answer both to \"the person said no\" and to\n * \"nothing here matched\", and the specification deliberately does not\n * distinguish them — telling a caller which applied would say whether a\n * credential for this site exists on the device. So it is `cancelled` in both\n * cases on registration, and `no-credential` on a sign-in that offered no\n * credentials to choose from, which is the reading a UI wants.\n */\nfunction failureReason(error: unknown, whenNotAllowed: PasskeyFailureReason): PasskeyFailureReason\n{\n    return (error as { name?: string } | null)?.name === 'NotAllowedError' ? whenNotAllowed : 'error';\n}\n\nexport interface EnrollPasskeyOptions\n{\n    /** Owner-facing name for the passkey list, e.g. the device model. */\n    label?: string;\n    /** Sent when the session proved itself longer ago than the recent-auth window. */\n    currentPassword?: string;\n}\n\nexport interface EnrollPasskeyValue\n{\n    passkeyId: string;\n    label: string | null;\n    createdAt: string;\n}\n\n/**\n * Enroll a passkey on the device in front of the user.\n *\n * Requires a signed-in session. A 403 with code `RECENT_AUTH_REQUIRED` from the\n * options call means the caller should prompt for the password and try again\n * with `currentPassword`; that is a rejected promise, not a result here, because\n * it is the server declining rather than the ceremony failing.\n */\nexport async function enrollPasskey(\n    api: AuthApi,\n    options: EnrollPasskeyOptions = {},\n): Promise<PasskeyResult<EnrollPasskeyValue>>\n{\n    if (!isPasskeySupported())\n    {\n        return { ok: false, reason: 'unsupported' };\n    }\n\n    const optionsJSON = await api.passkeyRegisterOptions.call({\n        body: { currentPassword: options.currentPassword },\n    }) as PublicKeyCredentialCreationOptionsJSON;\n\n    let response: RegistrationResponseJSON;\n\n    try\n    {\n        response = await startRegistration({ optionsJSON });\n    }\n    catch (error)\n    {\n        return { ok: false, reason: failureReason(error, 'cancelled'), error };\n    }\n\n    const enrolled = await api.passkeyRegisterVerify.call({\n        body: { response, label: options.label },\n    }) as EnrollPasskeyValue;\n\n    return { ok: true, ...enrolled };\n}\n\nexport interface SignInWithPasskeyOptions\n{\n    /**\n     * Offer the passkey through the browser's autofill dropdown instead of a\n     * modal. Needs an `<input autocomplete=\"username webauthn\">` on the page.\n     */\n    conditional?: boolean;\n    deviceName?: string;\n    platform?: string;\n}\n\nexport interface SignInWithPasskeyValue\n{\n    userId: string;\n    publicId: string;\n    email?: string;\n    phone?: string;\n    passwordChangeRequired: boolean;\n}\n\n/**\n * Sign in with a passkey, no identifier asked for.\n *\n * The device key the session runs on is generated and stored by the Next.js\n * proxy interceptor, exactly as on a password login — nothing here handles a\n * private key.\n */\nexport async function signInWithPasskey(\n    api: AuthApi,\n    options: SignInWithPasskeyOptions = {},\n): Promise<PasskeyResult<SignInWithPasskeyValue>>\n{\n    if (!isPasskeySupported())\n    {\n        return { ok: false, reason: 'unsupported' };\n    }\n\n    const optionsJSON = await api.passkeyLoginOptions.call({\n        body: {},\n    }) as PublicKeyCredentialRequestOptionsJSON;\n\n    let response: AuthenticationResponseJSON;\n\n    try\n    {\n        response = await startAuthentication({ optionsJSON, useBrowserAutofill: options.conditional === true });\n    }\n    catch (error)\n    {\n        return { ok: false, reason: failureReason(error, 'no-credential'), error };\n    }\n\n    const session = await api.passkeyLoginVerify.call({\n        body: { response },\n    }) as SignInWithPasskeyValue;\n\n    return { ok: true, ...session };\n}\n\nexport interface RenewSessionValue\n{\n    /** The new device key the session now runs on. */\n    keyId: string;\n}\n\n/**\n * Renew a bound session key with a passkey assertion.\n *\n * What an app calls when a request came back `SessionRenewalRequiredError`: the\n * session's short-lived key has run out and one WebAuthn ceremony puts a new one\n * in the cookie. The person sees the system prompt, not a sign-in form.\n *\n * The body is `{ response }` and nothing else. The expiring key's id lives in an\n * HttpOnly cookie that page script cannot read, and the new key pair is the\n * Next.js proxy's to generate — both are injected there, exactly as they are for\n * `signInWithPasskey`. Nothing here handles a private key.\n *\n * Refusals from the server are rejected promises rather than results, on the same\n * rule the rest of this file follows: a `SessionRenewalRefusedError` means the\n * server declined — the key is past its grace, or was revoked — and the app's\n * answer is to send the person to sign in, which is not the same as the ceremony\n * failing.\n */\nexport async function renewSession(api: AuthApi): Promise<PasskeyResult<RenewSessionValue>>\n{\n    if (!isPasskeySupported())\n    {\n        return { ok: false, reason: 'unsupported' };\n    }\n\n    const optionsJSON = await api.sessionRenewOptions.call({\n        body: {},\n    }) as PublicKeyCredentialRequestOptionsJSON;\n\n    let response: AuthenticationResponseJSON;\n\n    try\n    {\n        response = await startAuthentication({ optionsJSON });\n    }\n    catch (error)\n    {\n        return { ok: false, reason: failureReason(error, 'no-credential'), error };\n    }\n\n    const renewed = await api.sessionRenewVerify.call({\n        body: { response },\n    }) as { keyId: string };\n\n    return { ok: true, keyId: renewed.keyId };\n}\n\n/** What a successful disable answers with — the mode the account is now in. */\nexport interface DisableSessionBindingValue\n{\n    mode: 'none';\n}\n\nexport interface DisableSessionBindingOptions\n{\n    /**\n     * The account password, for a browser with no passkey to hand.\n     *\n     * Send it, or let the ceremony run — one of the two is required. Key age is\n     * deliberately not accepted: a session cookie copied in the minutes after a\n     * sign-in carries exactly that, and it must not be able to switch the\n     * protection off.\n     */\n    currentPassword?: string;\n}\n\n/**\n * Turn session binding off for this account.\n *\n * With `currentPassword` this is one call. Without it, the passkey ceremony runs\n * first and the assertion is what proves ownership — the same ceremony renewal\n * uses, for the same reason.\n *\n * Turning binding *on* needs no ceremony and no helper: it is\n * `api.setSessionBinding.call({ body: { mode: 'passkey' } })`. Leaving is the\n * privileged direction here, which is the reverse of the usual posture and is\n * the whole reason this helper exists.\n */\nexport async function disableSessionBinding(\n    api: AuthApi,\n    options: DisableSessionBindingOptions = {},\n): Promise<PasskeyResult<DisableSessionBindingValue>>\n{\n    if (options.currentPassword)\n    {\n        await api.setSessionBinding.call({ body: { mode: 'none', currentPassword: options.currentPassword } });\n\n        return { ok: true, mode: 'none' };\n    }\n\n    if (!isPasskeySupported())\n    {\n        return { ok: false, reason: 'unsupported' };\n    }\n\n    const optionsJSON = await api.sessionBindingDisableOptions.call({\n        body: {},\n    }) as PublicKeyCredentialRequestOptionsJSON;\n\n    let response: AuthenticationResponseJSON;\n\n    try\n    {\n        response = await startAuthentication({ optionsJSON });\n    }\n    catch (error)\n    {\n        return { ok: false, reason: failureReason(error, 'no-credential'), error };\n    }\n\n    await api.setSessionBinding.call({ body: { mode: 'none', response } });\n\n    return { ok: true, mode: 'none' };\n}\n\n// ============================================================================\n// Second-factor step-up on a new device (#95)\n// ============================================================================\n\n/**\n * What a completed step-up answers with — the sign-in the 202 was standing in for.\n *\n * Deliberately loose about the login fields. Through the Next.js proxy the\n * session is already sealed by the time this resolves and the app reads it from\n * the session cookie; a native client reads `userId` off the body. `keyId` and\n * `challengeHash` are the proxy's business and are not repeated here.\n */\nexport interface CompleteMfaValue\n{\n    userId?: string;\n    keyId: string;\n}\n\n/**\n * Finish a sign-in that answered `mfaRequired` with a code from the\n * authenticator app.\n *\n * The challenge is the `secret` from that 202 — or, on the web OAuth path, the\n * `?challenge=` the callback handler put on the confirm page's URL. It is single\n * use and lives ten minutes.\n *\n * A wrong code is a rejected promise carrying `MfaVerificationFailedError`, not\n * a result: it is the server declining rather than a ceremony failing, and there\n * is no ceremony here at all. Five wrong ones end the challenge and the person\n * signs in again.\n *\n * @param api - the typed auth client\n * @param challenge - the challenge secret from the 202 or the callback query\n * @param code - the six digits, spaces and dashes and all\n */\nexport async function completeMfaWithCode(\n    api: AuthApi,\n    challenge: string,\n    code: string,\n): Promise<CompleteMfaValue>\n{\n    return await api.mfaVerify.call({ body: { challenge, code } }) as CompleteMfaValue;\n}\n\n/**\n * Finish the same sign-in with one of the ten written-down recovery codes.\n *\n * Single use, and the count in `mfa/status` drops by one — an app that warns at\n * two remaining reads it from there after this resolves.\n */\nexport async function completeMfaWithRecoveryCode(\n    api: AuthApi,\n    challenge: string,\n    recoveryCode: string,\n): Promise<CompleteMfaValue>\n{\n    return await api.mfaVerify.call({ body: { challenge, recoveryCode } }) as CompleteMfaValue;\n}\n\n/**\n * Finish the same sign-in with a passkey the owner marked as a second factor.\n *\n * `options` from the server, `navigator.credentials` in the browser, `verify`\n * back — the shape every ceremony in this file has, and a discriminated union\n * rather than a throw for the same reason: a person who dismisses the system\n * sheet has not hit an application error.\n *\n * The challenge is what names the account, since there is no session yet. A\n * passkey the owner never marked is refused with the same body as a wrong code.\n */\nexport async function completeMfaWithPasskey(\n    api: AuthApi,\n    challenge: string,\n): Promise<PasskeyResult<CompleteMfaValue>>\n{\n    if (!isPasskeySupported())\n    {\n        return { ok: false, reason: 'unsupported' };\n    }\n\n    const optionsJSON = await api.mfaVerifyOptions.call({\n        body: { challenge },\n    }) as PublicKeyCredentialRequestOptionsJSON;\n\n    let response: AuthenticationResponseJSON;\n\n    try\n    {\n        response = await startAuthentication({ optionsJSON });\n    }\n    catch (error)\n    {\n        return { ok: false, reason: failureReason(error, 'no-credential'), error };\n    }\n\n    const verified = await api.mfaVerify.call({ body: { challenge, response } }) as CompleteMfaValue;\n\n    return { ok: true, ...verified };\n}\n"],"mappings":"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","names":[]}

package/dist/config.d.ts

@@ -376,6 +376,67 @@ declare const authEnvSchema: {
     } & {
         key: "SPFN_AUTH_MFA_STEP_UP_MINUTES";
     };
+    SPFN_AUTH_MFA_CONFIRM_PATH: {
+        description: string;
+        default: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_AUTH_MFA_CONFIRM_PATH";
+    };
+    SPFN_AUTH_MFA_CHALLENGE_TTL_MINUTES: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_AUTH_MFA_CHALLENGE_TTL_MINUTES";
+    };
+    SPFN_AUTH_BOUND_KEY_TTL_HOURS: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_AUTH_BOUND_KEY_TTL_HOURS";
+    };
+    SPFN_AUTH_BOUND_KEY_RENEW_GRACE_HOURS: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_AUTH_BOUND_KEY_RENEW_GRACE_HOURS";
+    };
+    SPFN_AUTH_CONCURRENT_USE_WINDOW_MS: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_AUTH_CONCURRENT_USE_WINDOW_MS";
+    };
+    SPFN_AUTH_SESSION_RENEW_PATH: {
+        description: string;
+        default: string;
+        required: boolean;
+        nextjs: boolean;
+        examples: string[];
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_AUTH_SESSION_RENEW_PATH";
+    };
     SPFN_API_URL: {
         description: string;
         default: string;
@@ -980,6 +1041,67 @@ declare const env: _spfn_core_env.InferEnvType<{
     } & {
         key: "SPFN_AUTH_MFA_STEP_UP_MINUTES";
     };
+    SPFN_AUTH_MFA_CONFIRM_PATH: {
+        description: string;
+        default: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_AUTH_MFA_CONFIRM_PATH";
+    };
+    SPFN_AUTH_MFA_CHALLENGE_TTL_MINUTES: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_AUTH_MFA_CHALLENGE_TTL_MINUTES";
+    };
+    SPFN_AUTH_BOUND_KEY_TTL_HOURS: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_AUTH_BOUND_KEY_TTL_HOURS";
+    };
+    SPFN_AUTH_BOUND_KEY_RENEW_GRACE_HOURS: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_AUTH_BOUND_KEY_RENEW_GRACE_HOURS";
+    };
+    SPFN_AUTH_CONCURRENT_USE_WINDOW_MS: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_AUTH_CONCURRENT_USE_WINDOW_MS";
+    };
+    SPFN_AUTH_SESSION_RENEW_PATH: {
+        description: string;
+        default: string;
+        required: boolean;
+        nextjs: boolean;
+        examples: string[];
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_AUTH_SESSION_RENEW_PATH";
+    };
     SPFN_API_URL: {
         description: string;
         default: string;

package/dist/config.js

@@ -360,6 +360,59 @@ var authEnvSchema = defineEnvSchema({
       examples: [5, 10, 30]
     })
   },
+  SPFN_AUTH_MFA_CONFIRM_PATH: {
+    ...envString({
+      description: "App page that asks for the second factor after a 202 sign-in, as a path on {NEXT_PUBLIC_SPFN_APP_URL || SPFN_APP_URL}. createOAuthCallbackHandler redirects the browser there with ?challenge= when a social sign-in needs a step-up; the page posts that challenge and a code to /_auth/mfa/verify. It is a page in your app, not an API route.",
+      default: "/auth/mfa",
+      required: false,
+      examples: ["/auth/mfa", "/sign-in/two-factor"]
+    })
+  },
+  SPFN_AUTH_MFA_CHALLENGE_TTL_MINUTES: {
+    ...envNumber({
+      description: "How long a new-device second-factor challenge stays spendable. A sign-in on an enrolled account from a device it has never seen answers 202 with a challenge instead of a session, and the key it registered is inactive until POST /_auth/mfa/verify spends it. This is how long the person has to reach for their authenticator \u2014 and how long an attacker holding only the password has. The Next.js proxy seals its pending cookie for the same span.",
+      default: 10,
+      required: false,
+      examples: [5, 10, 15]
+    })
+  },
+  // ============================================================================
+  // Session binding (#97)
+  // ============================================================================
+  SPFN_AUTH_BOUND_KEY_TTL_HOURS: {
+    ...envNumber({
+      description: "How long a session key bound to a passkey lives. This is the window in which a copied session cookie is still indistinguishable from the original, so it is hours rather than days; past it the browser runs one WebAuthn ceremony and gets a new key. Only applies to accounts that turned session binding on.",
+      default: 24,
+      required: false,
+      examples: [8, 24, 72]
+    })
+  },
+  SPFN_AUTH_BOUND_KEY_RENEW_GRACE_HOURS: {
+    ...envNumber({
+      description: "How long after a bound key expires a passkey renewal is still offered. Past it the account signs in again. Open-ended grace would make an expired key a long-lived key with extra steps.",
+      default: 168,
+      required: false,
+      examples: [24, 168, 720]
+    })
+  },
+  SPFN_AUTH_CONCURRENT_USE_WINDOW_MS: {
+    ...envNumber({
+      description: "How far apart two sightings of one device key from two client addresses still count as concurrent use, surfaced as `concurrentUseAtMillis` on the key list. A signal for the owner to read, never a refusal \u2014 addresses change legitimately. Meaningful only where proxy-guard is configured, since without it every web request carries the Next.js server's address.",
+      default: 3e5,
+      required: false,
+      examples: [6e4, 3e5, 9e5]
+    })
+  },
+  SPFN_AUTH_SESSION_RENEW_PATH: {
+    ...envString({
+      description: "Page in your app that runs the renewal ceremony. `RequireAuth` redirects a bound session whose key expired here instead of to the sign-in page; the page calls `renewSession(api)` and returns the user to where they were. Override per guard with the `renewalPath` prop.",
+      default: "/auth/renew",
+      required: false,
+      nextjs: true,
+      // Read by RequireAuth, which renders in the Next.js runtime
+      examples: ["/auth/renew", "/session/renew"]
+    })
+  },
   // ============================================================================
   // API Configuration
   // ============================================================================