@erpgulf/auth-sdk 0.1.0-beta.1

package/README.md

@@ -0,0 +1,357 @@
+# `@erpgulf/auth-sdk`
+
+Framework-independent TypeScript SDK for the shared ERPGulf authentication flow.
+It hides Frappe endpoints, master-token handling, response formats, and policy
+terminology from consuming applications.
+
+The package has no React, React Native, or Expo dependency. It uses global
+`fetch` by default and can accept a custom transport for compatible runtimes and
+tests.
+
+> `@erpgulf/auth-sdk` does **not** manage user token refresh or session
+> persistence.
+
+## Installation
+
+The beta is distributed publicly through npmjs.org. After publication succeeds,
+install the exact version without registry credentials:
+
+```sh
+npm install --save-exact @erpgulf/auth-sdk@0.1.0-beta.1
+```
+
+Or with pnpm:
+
+```sh
+pnpm add --save-exact @erpgulf/auth-sdk@0.1.0-beta.1
+```
+
+If you previously configured `@erpgulf` for GitHub Packages, replace that scope
+mapping in the consuming project's `.npmrc` so it overrides any old user-level
+configuration:
+
+```ini
+@erpgulf:registry=https://registry.npmjs.org
+```
+
+New projects using the default npm registry need no `.npmrc` setup. Public
+distribution does not grant access to ERPGulf backend tenants.
+
+This prerelease is for integration testing. Consumer and staging validation
+remain outstanding; public availability does not make it a stable release. The
+package provides ESM JavaScript and TypeScript declarations and requires Node.js
+20 or newer for Node consumers.
+
+## Create a client
+
+Supply the backend URL at runtime. Each client owns an independent normalized
+URL and in-memory master-token cache.
+
+```ts
+import { createAuthClient } from "@erpgulf/auth-sdk";
+
+const auth = createAuthClient({
+  baseUrl: "https://customer.example.com",
+  timeoutMs: 10_000,
+  metadata: {
+    appId: "employee-app",
+    appVersion: "2.4.0",
+  },
+});
+```
+
+HTTPS is required by default. Local development over HTTP must be explicitly
+enabled with `allowInsecureHttp: true`. Base URLs may include custom ports, but
+credentials, query strings, fragments, and non-root paths are rejected.
+
+Server discovery, QR scanning, and company-code lookup happen before client
+creation and are outside this package.
+
+## Authentication flow
+
+`begin` fetches and normalizes login policy, then runs the single authoritative
+flow resolver:
+
+```ts
+const flow = await auth.begin({ mobileNumber: "5550001" });
+
+flow.action; // "SIGN_UP" | "SIGN_IN"
+flow.nextStep;
+flow.credentials.password; // "required" | "optional" | "disabled"
+flow.credentials.otp; // "required" | "optional" | "disabled"
+flow.credentials.atLeastOneOf; // e.g. ["password", "otp"]
+```
+
+`atLeastOneOf` describes enabled optional credentials when the backend does not
+mark either one mandatory. This preserves `Optional` OTP semantics instead of
+silently converting it to required. Contradictory or credential-free policies
+fail with `UNSUPPORTED_POLICY`.
+
+Applications can use `nextStep` for common UI routing and the full credential
+requirements for optional inputs. Presentation remains entirely app-owned.
+`nextStep` is a hint, not a complete form definition: inspect `credentials` for
+optional fields and `policy.employeeHasExistingPassword` to distinguish creating
+a password from verifying one, including when both credentials are required.
+
+Prefer `begin` for policy-guided integration. `getLoginPolicy` is the
+lower-level alternative for apps with their own resolver; calling both is
+unnecessary. Neither flow hints nor low-level operations enforce backend
+authorization. The full policy matrix, especially password-only flows without an
+existing password, requires backend confirmation before rollout. Unit tests
+describe the current resolver, not proof that every combination is supported by
+the server.
+
+## Login policy
+
+```ts
+const policy = await auth.getLoginPolicy({ mobileNumber: "5550001" });
+```
+
+Backend values `Mandatory`, `Optional`, and `No` become `required`, `optional`,
+and `disabled`. Raw Frappe payloads and strings are not returned.
+
+The supplied backend example uses a GET request with a form body.
+Standards-based `fetch` does not support GET bodies, so the default adapter
+sends the safely encoded mobile number as `?mobile=...`, while preserving GET
+and the documented content-type. The existing `origin/expo-auth-starter` example
+at commit `fd8b565` sends POST form data; it does not prove GET-query support.
+Verify query-parameter compatibility against an authorized staging backend
+before rollout. The SDK has not switched methods based on that conflicting
+example.
+
+## Master token behavior
+
+The SDK automatically acquires a master access token for login policy, OTP, and
+sign-in requests. It:
+
+- validates the confirmed response with Zod;
+- caches the access token only in the client instance's memory;
+- calculates expiry from `expires_in` and uses a 30-second safety skew;
+- deduplicates simultaneous acquisition into one request;
+- never logs, persists, or publicly exposes the credential;
+- ignores the returned master refresh token and calls the master-token endpoint
+  again when required.
+
+Only HTTP 401 with `exc_type: "AuthenticationError"` and without a
+`status: "error"` business-error marker triggers invalidation, fresh
+acquisition, and one retry. This middleware signal comes from the existing app
+example, not a live-backend test. Bare 401, all 403 responses, and credential
+errors do not trigger automatic replay. A second matching rejection is
+`MASTER_TOKEN_REJECTED`. There are no general network, timeout,
+malformed-response, or 5xx retries.
+
+Safe replay of OTP/sign-in still requires the backend to emit that middleware
+signal **before processing the operation**. Confirm this contract in staging.
+Client serialization does not expose the internal master-token cache. This is
+accidental-disclosure protection, not isolation from malicious application code.
+
+## Send OTP
+
+```ts
+const otp = await auth.sendOtp({ mobileNumber: "5550001" });
+otp.expiresIn; // seconds
+```
+
+The backend success message is not used for business logic. A timeout or unknown
+network outcome is not automatically replayed, avoiding duplicate OTP actions.
+
+## Sign up
+
+Sign-up is not sent with master Authorization under the confirmed contract.
+Optional credentials are omitted rather than encoded as `undefined`. The
+existing app example does send master Authorization for sign-up; reconcile this
+discrepancy in staging. The SDK retains the supplied contract for now.
+
+```ts
+const result = await auth.signUp({
+  mobileNumber: "5550001",
+  otp: "<OTP>",
+  password: "<PASSWORD>", // omit when policy allows
+});
+```
+
+At least one credential must be present. The SDK does not retain either value or
+compare the returned phone number with the submitted number.
+
+## Sign in
+
+Sign-in is master-token authenticated. Its confirmed credential combinations
+are:
+
+```ts
+await auth.signIn({ mobileNumber, password });
+await auth.signIn({ mobileNumber, otp });
+await auth.signIn({ mobileNumber, password, otp });
+```
+
+Calling sign-in with neither password nor OTP fails locally with
+`INVALID_SIGN_IN_INPUT`. Values are form encoded, and absent fields are omitted.
+Sign-in is never replayed after an ambiguous network failure because a submitted
+OTP may already have been consumed. The only automatic retry is the bounded
+explicit master-auth rejection path described above.
+
+These are low-level operations: they do not fetch or enforce policy implicitly.
+Passwords are not trimmed. If the employee has no self-chosen password, a
+supplied password may **set** it rather than verify identity. Do not treat a
+password-only request in that state as verified proof of identity; confirm the
+backend's onboarding rules and enforce authorization on the server.
+
+## Results and app-owned session state
+
+Sign-up returns `AuthResult`; sign-in returns `SignInResult`, which adds the
+normalized password and OTP policies reported by sign-in.
+
+```ts
+const result = await auth.signIn({ mobileNumber, password });
+
+result.token.accessToken;
+result.token.refreshToken;
+result.token.expiresIn;
+result.employee;
+result.authenticatedAt;
+result.passwordPolicy;
+result.otpPolicy;
+
+// SDK responsibility ends here.
+await appSessionManager.save({
+  accessToken: result.token.accessToken,
+  refreshToken: result.token.refreshToken,
+});
+```
+
+Token type casing from the backend is normalized to `Bearer` when it is a
+case-insensitive bearer value. The SDK returns user tokens but never stores,
+refreshes, or rotates them.
+
+## Errors
+
+All SDK failures use `AuthError`:
+
+```ts
+import { AuthError } from "@erpgulf/auth-sdk";
+
+try {
+  await auth.signIn({ mobileNumber, otp });
+} catch (error: unknown) {
+  if (error instanceof AuthError) {
+    console.log(error.code, error.retryable, error.httpStatus);
+  }
+}
+```
+
+Confirmed sign-in errors are normalized as follows:
+
+| Backend meaning                | SDK code                 |
+| ------------------------------ | ------------------------ |
+| Invalid or expired OTP         | `INVALID_OR_EXPIRED_OTP` |
+| Invalid password               | `INVALID_PASSWORD`       |
+| Unknown authentication failure | `AUTHENTICATION_FAILED`  |
+
+Malformed confirmed responses use `INVALID_RESPONSE`; network and timeout errors
+use `NETWORK_ERROR` and `TIMEOUT`. Error messages never include response
+payloads, credentials, or Authorization headers. Native/custom transport
+exceptions are replaced with safe messages; their raw causes are not attached
+because they can contain request credentials. Custom transports must return HTTP
+errors as responses, not throw them.
+
+For dispatched `sendOtp`, `signUp`, and `signIn` requests, network failures,
+timeouts, 5xx responses, and malformed successes have `retryable: false`: the
+operation may already have taken effect. Do not automatically repeat it. A
+retryable acquisition failure can occur before the protected mutation is sent;
+read-only policy failures may also be retryable. The flag does not promise that
+an error will resolve on retry.
+
+Response schemas validate required fields, success markers, and known policy
+values while stripping extra object fields. Additive backend metadata is
+accepted but is not exposed to consumers; unknown policy enum values still fail
+closed.
+
+## Custom transport
+
+`HttpTransport` and its request/response types are public only to support
+runtimes without compatible global `fetch` and deterministic tests. It
+transports data; it must not implement user-session token storage or refresh.
+The default transport requests `redirect: "error"`, `cache: "no-store"`, and
+`credentials: "omit"`. It does not follow redirects or opt into browser cookies
+or HTTP caching. Custom transports must provide equivalent protection and must
+not automatically retry requests. They receive sensitive headers and bodies and
+are part of the trusted application boundary. Throw `AuthError` with code
+`TIMEOUT` for timeouts; other thrown values become `NETWORK_ERROR`.
+
+Browser/Node fetch behavior does not prove React Native/Expo adapter behavior.
+Verify these options on each target runtime; use a conforming transport where
+the runtime ignores them. The backend must also return `Cache-Control: no-store`
+for authentication responses to protect intermediaries and native caches.
+
+## Security and explicit non-goals
+
+The SDK does not log authentication data. Do not log request bodies or returned
+results in consuming apps. Validate/allowlist URLs from untrusted QR codes or
+company lookup before client creation: HTTPS and URL syntax checks cannot
+establish a server's trustworthiness.
+
+This package intentionally does not implement:
+
+- user access/refresh-token storage, refresh, or rotation;
+- session restoration, global auth state, logout, or business API interception;
+- SecureStore, Keychain, or AsyncStorage;
+- React, React Native, Expo, hooks, navigation, or UI;
+- server/company/tenant discovery or app-specific branches.
+
+## Development
+
+From the repository root:
+
+```sh
+pnpm install
+pnpm lint
+pnpm format:check
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Tests use fake credentials and mock transports, plus an ephemeral loopback HTTP
+server to verify native-fetch redirect rejection. They never contact a live
+backend. Running the suite requires permission to bind a loopback port.
+
+## Versioning
+
+The initial public npm testing version is `0.1.0-beta.1`, published with the
+`beta` dist-tag. The first release uses an authenticated npm maintainer;
+subsequent releases can use the repository's manually dispatched
+trusted-publishing workflow. Fixes use `0.1.0-beta.2`, `0.1.0-beta.3`, and
+subsequent beta increments. Record consumer-visible changes with
+`pnpm changeset`. Stable `0.1.0` must wait for validation in real consuming
+applications; the beta workflow rejects stable versions and never publishes with
+`latest`.
+
+## Backend contracts still needed
+
+Success shapes are validated against supplied contract examples, not live calls,
+and sign-in's two known credential errors are mapped. Representative error
+responses are still needed for invalid mobile, OTP generation rate limiting,
+invalid/expired master token, sign-up failures (including already signed up),
+and login-policy failures. Until confirmed, those cases use safe generic errors.
+
+Before rollout, use an authorized staging tenant and disposable test employees:
+
+- Verify GET `?mobile=...` policy lookup with a known test number, including a
+  leading `+`; compare with an approved POST-form control if GET fails. Never
+  send a GET body with standards-based fetch.
+- Capture sanitized expired-master, invalid-OTP, invalid-password, and
+  permission errors. Confirm the exact middleware discriminator and that
+  rejected master authentication cannot generate OTPs, consume OTPs, or set
+  passwords.
+- Reconcile sign-up Authorization requirements and all supported combinations of
+  signed-up/existing-password flags and password/OTP policies. Include Optional
+  OTP, disabled credentials, and password creation versus verification.
+- Verify OTP-only, password-only, and combined sign-in with disposable accounts;
+  confirm expiry units, token casing, nullable email, and normalized results.
+- Confirm the server sends no-store headers. Check redirect rejection, cookie
+  omission, caching, timeout behavior, and browser CORS on each deployment
+  runtime, especially React Native/Expo. Never use real credentials in redirect
+  tests.
+
+Unit and loopback tests verify SDK behavior; supplied examples verify documented
+shapes; none of these replace the staging checks above.

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+type PasswordPolicy = "required" | "optional" | "disabled";
+type OtpPolicy = "required" | "optional" | "disabled";
+interface AuthPolicy {
+    readonly employeeId: string;
+    readonly employeeHasExistingPassword: boolean;
+    readonly employeeHasSignedUp: boolean;
+    readonly passwordPolicy: PasswordPolicy;
+    readonly otpPolicy: OtpPolicy;
+}
+
+interface AuthToken {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+    readonly expiresIn: number;
+    readonly tokenType: string;
+    readonly scope: string;
+}
+interface AuthEmployee {
+    readonly id: string;
+    readonly name: string;
+    readonly phone: string;
+    readonly email: string | null;
+}
+interface AuthResult {
+    readonly token: AuthToken;
+    readonly employee: AuthEmployee;
+    readonly authenticatedAt: string;
+}
+interface SignInResult extends AuthResult {
+    readonly passwordPolicy: PasswordPolicy;
+    readonly otpPolicy: OtpPolicy;
+}
+interface SendOtpResult {
+    readonly expiresIn: number;
+}
+interface GetLoginPolicyInput {
+    readonly mobileNumber: string;
+}
+interface SendOtpInput {
+    readonly mobileNumber: string;
+}
+interface SignUpInput {
+    readonly mobileNumber: string;
+    readonly otp?: string;
+    readonly password?: string;
+}
+interface SignInInput {
+    readonly mobileNumber: string;
+    readonly otp?: string;
+    readonly password?: string;
+}
+
+type AuthAction = "SIGN_UP" | "SIGN_IN";
+type AuthNextStep = "CREATE_PASSWORD" | "ENTER_PASSWORD" | "ENTER_OTP" | "ENTER_PASSWORD_AND_OTP" | "CHOOSE_PASSWORD_OR_OTP";
+type CredentialName = "password" | "otp";
+interface CredentialRequirements {
+    readonly password: PasswordPolicy;
+    readonly otp: OtpPolicy;
+    readonly atLeastOneOf: readonly CredentialName[];
+}
+interface AuthFlow {
+    readonly action: AuthAction;
+    readonly nextStep: AuthNextStep;
+    readonly credentials: CredentialRequirements;
+    readonly policy: AuthPolicy;
+}
+
+type HttpMethod = "GET" | "POST";
+interface HttpRequest {
+    readonly url: string;
+    readonly method: HttpMethod;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+    readonly timeoutMs?: number;
+}
+interface HttpResponse {
+    readonly status: number;
+    readonly body: unknown;
+}
+interface HttpTransport {
+    /**
+     * Return HTTP failures as responses. Throw AuthError(TIMEOUT) for timeouts;
+     * other thrown values are normalized to NETWORK_ERROR without their cause.
+     * Implementations must reject redirects, disable auth-response caching and
+     * avoid ambient cookies. Credentials must never be logged or persisted.
+     */
+    request(request: HttpRequest): Promise<HttpResponse>;
+}
+
+interface AuthClientMetadata {
+    readonly appId?: string;
+    readonly appVersion?: string;
+}
+interface AuthClientConfig {
+    readonly baseUrl: string;
+    readonly timeoutMs?: number;
+    readonly transport?: HttpTransport;
+    readonly metadata?: AuthClientMetadata;
+    readonly allowInsecureHttp?: boolean;
+}
+interface AuthClient {
+    begin(input: GetLoginPolicyInput): Promise<AuthFlow>;
+    getLoginPolicy(input: GetLoginPolicyInput): Promise<AuthPolicy>;
+    sendOtp(input: SendOtpInput): Promise<SendOtpResult>;
+    signUp(input: SignUpInput): Promise<AuthResult>;
+    signIn(input: SignInInput): Promise<SignInResult>;
+}
+
+declare function createAuthClient(config: AuthClientConfig): AuthClient;
+
+type AuthErrorCode = "AUTHENTICATION_FAILED" | "INVALID_BASE_URL" | "INVALID_CLIENT_CONFIG" | "INVALID_MOBILE" | "INVALID_OR_EXPIRED_OTP" | "INVALID_PASSWORD" | "INVALID_RESPONSE" | "INVALID_SIGN_IN_INPUT" | "INVALID_SIGN_UP_INPUT" | "MASTER_TOKEN_FAILED" | "MASTER_TOKEN_REJECTED" | "NETWORK_ERROR" | "SERVER_ERROR" | "TIMEOUT" | "UNSUPPORTED_POLICY";
+interface AuthErrorOptions {
+    readonly cause?: unknown;
+    readonly httpStatus?: number;
+    readonly retryable?: boolean;
+}
+declare class AuthError extends Error {
+    readonly code: AuthErrorCode;
+    readonly httpStatus: number | undefined;
+    readonly retryable: boolean;
+    constructor(code: AuthErrorCode, message: string, options?: AuthErrorOptions);
+}
+declare function isAuthError(error: unknown): error is AuthError;
+
+export { type AuthAction, type AuthClient, type AuthClientConfig, type AuthClientMetadata, type AuthEmployee, AuthError, type AuthErrorCode, type AuthErrorOptions, type AuthFlow, type AuthNextStep, type AuthPolicy, type AuthResult, type AuthToken, type CredentialName, type CredentialRequirements, type GetLoginPolicyInput, type HttpMethod, type HttpRequest, type HttpResponse, type HttpTransport, type OtpPolicy, type PasswordPolicy, type SendOtpInput, type SendOtpResult, type SignInInput, type SignInResult, type SignUpInput, createAuthClient, isAuthError };