@lalternative/auth 0.13.3 → 0.15.0

package/README.md

@@ -186,3 +186,118 @@ if (isInvitationFailure(outcome)) return <InvitationNotice reason={outcome} />
 
 `endpoint` is any backend that redeems a token, so an app already claiming
 against its own API keeps doing so; `extra` adds fields to the request body.
+
+## Customer passwords at the identity provider (0.14.0, completed in 0.15.0)
+
+From **0.14.0** — and working end to end from **0.15.0**, which relays the
+password to the provider instead of dropping it — an app can move its customers' passwords to the suite's
+identity provider while keeping its own login screen, its own domain and its
+own session. Nothing is enabled by a version bump alone: passwords stay local
+until `kratosPasswords` is passed. An app upgrading to 0.14.x never changes
+behaviour by accident.
+
+```ts
+createPlatformAuth({
+  // …
+  kratosPasswords: {
+    publicUrl: process.env.URBANGATE_PUBLIC_URL!,
+    issuer: process.env.URBANGATE_ISSUER_URL!,
+    clientId: process.env.URBANGATE_PROVISIONER_CLIENT_ID!,
+    clientSecret: process.env.URBANGATE_PROVISIONER_CLIENT_SECRET!,
+    role: "spore:user",
+    product: "spore",
+    onProvisioningDeferred: ({ userId, email }) => queueIdentityRepair(userId, email),
+  },
+})
+```
+
+The login form, its copy and its routes do not change, and nobody is
+redirected: the password is posted to this app as before and checked against
+Kratos instead of a local hash.
+
+### Each app keeps its own accounts
+
+The same person signing up on two products gets two local users and two
+passwords, which may use two different addresses. They are never told the
+products know each other. What they share — when the address is the same — is
+one identity at the provider, which is what an app key is issued against.
+
+An app therefore **must not deactivate or delete the identity** when it
+deletes a local account: it drops its own role and its local row. Deactivating
+the identity would sign the person out of every other product of the suite.
+
+The address is what joins the two, and nothing else does. Someone who signs up
+on spore with one address and on lalter with another gets **two identities**,
+and the provider has no way to know they are the same person. Their app keys
+are then split across those identities: `/keys` shows each set on its own, and
+a key minted under one cannot name the other's product. That follows from each
+app keeping its own accounts, and is not a defect to route around — but an
+integrator who used two addresses will meet it, and the answer is to sign up
+with the same address on both products.
+
+### Refusals a form must tell apart
+
+`res.error.message` carries the reason, so the existing error banner renders
+it with no change. A page that routes rather than renders uses the predicates:
+
+| Predicate | Meaning |
+|---|---|
+| `needsPasswordRecovery` | The identity has no password yet (an account predating the move). Send to recovery — it is **not** a wrong password. |
+| `isIdentityProviderUnavailable` | The provider is unreachable. The password was never refused; do not suggest changing it. |
+| `needsSecondFactor` | Kratos requires a second factor. |
+| `isAccountDisabled` | The identity is deactivated. |
+
+Verification fails closed: only an explicit refusal by Kratos reads as a wrong
+password, and an outage answers 503 so nobody rotates a password that was
+right.
+
+### The password reaches the provider, or the write fails
+
+Kratos holds the password, so every write must reach it: sign-up, the OTP
+reset and a password change all relay what the form collected before anything
+is stored locally. Kratos hashes it with the hasher its own configuration
+declares, so an app cannot hand over one it hashed itself.
+
+If the provider is unreachable the write fails with 503 and nothing changes,
+rather than storing a placeholder against a password Kratos never received —
+that account could never be opened again, and nothing would say why.
+
+This is the one place the package refuses rather than degrades. Reading
+(signing in) fails closed too, but a sign-up that cannot reach the provider
+still creates the local account: the person is registered, `identityId` stays
+null, and `onProvisioningDeferred` hands the repair to the app. Writing a
+password has no such fallback, because a password stored nowhere is not a
+state a repair can fix.
+
+### Why the sentinel hash
+
+Better Auth's `/sign-in/email` reads the credential row and refuses **before**
+reaching the verifier when it carries no hash, and its verifier is handed only
+`{hash, password}` — never the address. So the package writes
+`KRATOS_SENTINEL_HASH` in place of a hash and carries the address to the
+verifier from the route hook.
+
+The sentinel is a constant, not a hash: argon2/bcrypt/scrypt verification of
+it fails on its format, so a build that ever bypassed the custom verifier
+refuses everyone rather than admitting anyone.
+
+This is deliberate and it is a workaround. When Better Auth exposes a seam for
+an external credential provider, the replacement is to handle `/sign-in/email`
+before the native route runs, and the sentinel disappears. That was not taken
+now because it means re-implementing session creation, which is where a
+mistake becomes an authentication hole.
+
+### Provisioning is not atomic
+
+`user.create.after` runs after the insert commits, so a sign-up cannot be
+atomic with the identity it needs. A provider that is down leaves `identityId`
+null and the person registered all the same — a customer is never refused
+registration because the provider is unavailable. `onProvisioningDeferred`
+receives those sign-ups so the app can queue the repair, which re-sends
+through `provisionIdentity`. The endpoint is idempotent on the address, so a
+repair for someone who already got an identity returns that same one.
+
+### Rollout
+
+Per app, smallest customer base first — never all at once. An app that
+switches and breaks locks its customers out.

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { createAuthClient } from 'better-auth/react';
-import { f as AuthClientSurface, l as MagicLinkClientSurface, S as SsoClientSurface, d as AdminClientSurface, T as TwoFactorClientSurface, P as PlatformAuthClientConfig } from './types-3OHf736K.js';
+import { f as AuthClientSurface, l as MagicLinkClientSurface, S as SsoClientSurface, d as AdminClientSurface, T as TwoFactorClientSurface, P as PlatformAuthClientConfig } from './types-COX3VaBw.js';
 import 'better-auth';
 
 /**

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { L as LoginFormProps, R as RegisterFormProps, V as VerifyEmailFormProps, F as ForgotPasswordFormProps, M as MagicLinkFormProps, a as ResetPasswordFormProps, A as AuthLayoutProps, I as InvitationNoticeProps, b as AuthClientResult, c as LinkComponent } from './types-3OHf736K.js';
-export { d as AdminClientSurface, e as AuthClientDataResult, f as AuthClientSurface, g as AuthInviteProps, h as AuthNavProps, i as AuthThemeProps, j as InvitationFailure, k as LoginFormLabels, l as MagicLinkClientSurface, m as MagicLinkConfig, n as MagicLinkFormLabels, P as PlatformAuthClientConfig, o as PlatformAuthConfig, p as PlatformAuthMailer, q as PlatformAuthMailerArgs, r as PlatformAuthMailerType, s as PlatformRateLimitConfig, t as PlatformRateLimitRule, u as PlatformSession, v as PlatformSessionData, w as PlatformSsoConfig, x as PlatformTwoFactorConfig, y as PlatformUser, z as RegisterFormLabels, S as SsoClientSurface, T as TwoFactorClientSurface } from './types-3OHf736K.js';
+import { L as LoginFormProps, R as RegisterFormProps, V as VerifyEmailFormProps, F as ForgotPasswordFormProps, M as MagicLinkFormProps, a as ResetPasswordFormProps, A as AuthLayoutProps, I as InvitationNoticeProps, b as AuthClientResult, c as LinkComponent } from './types-COX3VaBw.js';
+export { d as AdminClientSurface, e as AuthClientDataResult, f as AuthClientSurface, g as AuthInviteProps, h as AuthNavProps, i as AuthThemeProps, j as InvitationFailure, k as LoginFormLabels, l as MagicLinkClientSurface, m as MagicLinkConfig, n as MagicLinkFormLabels, P as PlatformAuthClientConfig, o as PlatformAuthConfig, p as PlatformAuthMailer, q as PlatformAuthMailerArgs, r as PlatformAuthMailerType, s as PlatformKratosPasswordConfig, t as PlatformRateLimitConfig, u as PlatformRateLimitRule, v as PlatformSession, w as PlatformSessionData, x as PlatformSsoConfig, y as PlatformTwoFactorConfig, z as PlatformUser, B as RegisterFormLabels, S as SsoClientSurface, T as TwoFactorClientSurface } from './types-COX3VaBw.js';
 import * as better_auth_react from 'better-auth/react';
 import * as better_auth from 'better-auth';
 import { PlatformAuthClient } from './client.js';
 export { startSso } from './client.js';
 import * as react from 'react';
 import { InputHTMLAttributes, ReactNode } from 'react';
-export { C as ClaimOutcome, S as SsoMappedUser, a as SsoProfile, i as isInvitationFailure, m as mapSsoProfile } from './sso-profile-HO-u17jd.js';
+export { C as ClaimOutcome, S as SsoMappedUser, a as SsoProfile, i as isInvitationFailure, m as mapSsoProfile } from './sso-profile-aNyHaZHJ.js';
 
 /**
  * Returns a useSession hook bound to the given auth client.
@@ -221,6 +221,23 @@ declare function withInviteToken(href: string, token?: string): string;
  */
 declare function isEmailNotVerified(error: AuthClientResult["error"]): boolean;
 
+/**
+ * Whether the sign-in was refused because the person's identity carries no
+ * password yet at the provider — an account that predates the move, whose
+ * owner sets a password once through the recovery flow.
+ *
+ * It is not a wrong password, and rendering it as one sends the person
+ * retrying an old password that will never work again.
+ */
+declare function needsPasswordRecovery(error: AuthClientResult["error"]): boolean;
+/**
+ * Whether the identity provider could not be reached. The password was never
+ * refused: the person retries, and must not be told to change it.
+ */
+declare function isIdentityProviderUnavailable(error: AuthClientResult["error"]): boolean;
+declare function needsSecondFactor(error: AuthClientResult["error"]): boolean;
+declare function isAccountDisabled(error: AuthClientResult["error"]): boolean;
+
 type OAuthErrorLabels = {
     accountNotLinked: string;
     socialCancelled: string;
@@ -326,4 +343,4 @@ interface AuthLinkProps {
  */
 declare function AuthLink({ to, as: Link, className, children }: AuthLinkProps): react.JSX.Element;
 
-export { AuthClientResult, AuthField, type AuthFieldProps, AuthLayout, AuthLayoutProps, AuthLink, AuthSubmit, ForgotPasswordForm, ForgotPasswordFormProps, InvitationNotice, InvitationNoticeProps, LinkComponent, LoginForm, LoginFormProps, type MagicLinkErrorLabels, MagicLinkForm, MagicLinkFormProps, type OAuthErrorLabels, RegisterForm, RegisterFormProps, ResetPasswordForm, ResetPasswordFormProps, SocialButtons, VerifyEmailForm, VerifyEmailFormProps, clearOAuthError, initialMagicLinkError, initialOAuthError, isEmailNotVerified, isMagicLinkError, magicLinkErrorCallback, magicLinkErrorMessage, normalizeInviteToken, oauthErrorCallback, oauthErrorMessage, useLogout, useSession, withInviteToken };
+export { AuthClientResult, AuthField, type AuthFieldProps, AuthLayout, AuthLayoutProps, AuthLink, AuthSubmit, ForgotPasswordForm, ForgotPasswordFormProps, InvitationNotice, InvitationNoticeProps, LinkComponent, LoginForm, LoginFormProps, type MagicLinkErrorLabels, MagicLinkForm, MagicLinkFormProps, type OAuthErrorLabels, RegisterForm, RegisterFormProps, ResetPasswordForm, ResetPasswordFormProps, SocialButtons, VerifyEmailForm, VerifyEmailFormProps, clearOAuthError, initialMagicLinkError, initialOAuthError, isAccountDisabled, isEmailNotVerified, isIdentityProviderUnavailable, isMagicLinkError, magicLinkErrorCallback, magicLinkErrorMessage, needsPasswordRecovery, needsSecondFactor, normalizeInviteToken, oauthErrorCallback, oauthErrorMessage, useLogout, useSession, withInviteToken };

package/dist/index.js

@@ -1514,6 +1514,20 @@ function InvitationNotice({
     action
   ] });
 }
+
+// src/kratos-sign-in-error.ts
+function needsPasswordRecovery(error) {
+  return error?.code === "IDENTITY_HAS_NO_PASSWORD";
+}
+function isIdentityProviderUnavailable(error) {
+  return error?.code === "IDENTITY_PROVIDER_UNAVAILABLE" || error?.status === 503;
+}
+function needsSecondFactor(error) {
+  return error?.code === "SECOND_FACTOR_REQUIRED";
+}
+function isAccountDisabled(error) {
+  return error?.code === "ACCOUNT_DISABLED";
+}
 export {
   AuthField,
   AuthLayout,
@@ -1530,12 +1544,16 @@ export {
   clearOAuthError,
   initialMagicLinkError,
   initialOAuthError,
+  isAccountDisabled,
   isEmailNotVerified,
+  isIdentityProviderUnavailable,
   isInvitationFailure,
   isMagicLinkError,
   magicLinkErrorCallback,
   magicLinkErrorMessage,
   mapSsoProfile,
+  needsPasswordRecovery,
+  needsSecondFactor,
   normalizeInviteToken,
   oauthErrorCallback,
   oauthErrorMessage,