@cartbase/storefront 0.17.0 → 0.18.0

package/src/api/auth.ts

@@ -1,108 +1,108 @@
-/**
- * @cartbase/storefront/api/auth — passwordless code login (customer-accounts
- * card §2, Shopify Customer Account API direction).
- *
- * Ground truth: src/app/api/store/auth/code/{request,verify}/route.ts +
- * src/lib/customer-auth/{codes,session}.ts.
- *
- * ## Session discipline (READ THIS before wiring auth)
- *
- * `verifyLoginCode` mints a REAL Supabase session. The `access_token` is the
- * SAME `authorization: Bearer <jwt>` every /api/store/* route accepts — wire
- * it into `StorefrontClient` via `getAuthToken` and every subsequent call
- * (customers/me, orders, documents, cart-attach) is authenticated:
- *
- * ```ts
- * const { access_token, refresh_token } = await verifyLoginCode(client, { email, code })
- * // persist both; then construct/refresh the client with:
- * //   getAuthToken: () => readStoredAccessToken()
- * ```
- *
- * Tokens expire (`expires_in` seconds / `expires_at` epoch-seconds): refresh
- * with the Supabase client (`supabase.auth.setSession({access_token,
- * refresh_token})` then `refreshSession()`) — the Cartbase API does not proxy
- * token refresh. Password login (supabase.auth.signInWithPassword
- * client-side) yields an equivalent JWT and needs nothing from this module.
- *
- * ## Security posture (server-enforced; the SDK adds nothing)
- * - request NEVER reveals whether the email is registered (`{ok:true}`
- *   always — no enumeration oracle); the 6-digit code exists only in the
- *   sent email.
- * - Codes: hashed at rest, TTL 10 min, single-use, one live code per email
- *   (a new request supersedes prior codes), 5-wrong-attempt lockout.
- * - Rate limits (per 15-min window): 5 requests per email, 20 per IP →
- *   `429 rate_limited` — the ONLY distinguishable request failure.
- * - Every verify failure is `401 invalid_code` (generic, no oracle).
- */
-
-import type { StorefrontClient } from "./http"
-import type { StoreCustomer } from "./customers"
-
-export interface RequestLoginCodeInput {
-  email: string
-}
-
-export interface RequestLoginCodeResponse {
-  /** Always true — success is deliberately indistinguishable per email. */
-  ok: true
-}
-
-/**
- * POST /api/store/auth/code/request — passwordless login step 1: email a
- * 6-digit one-time code. Always `{ok: true}` (no enumeration oracle);
- * first-time emails register lazily at VERIFY, not here.
- *
- * Auth: anon (x-client-id only).
- * Errors: 429 rate_limited (5/email or 20/IP per 15 min) ·
- * 400 validation_failed (malformed email) · 400 missing_client_id.
- * Settings: the `auth-code` email template (notifications) carries the code.
- */
-export async function requestLoginCode(
-  client: StorefrontClient,
-  input: RequestLoginCodeInput
-): Promise<RequestLoginCodeResponse> {
-  return client.post("/api/store/auth/code/request", input)
-}
-
-export interface VerifyLoginCodeInput {
-  email: string
-  /** Exactly 6 digits (leading zeros count) — anything else → 400. */
-  code: string
-}
-
-/**
- * The minted session — a real Supabase token pair plus the resolved
- * customer (addresses embedded).
- */
-export interface CustomerSessionResponse {
-  /** Supabase JWT — send as `authorization: Bearer <access_token>`. */
-  access_token: string
-  refresh_token: string
-  /** Seconds until expiry. */
-  expires_in: number
-  /** Unix epoch seconds of expiry (may be absent). */
-  expires_at: number | undefined
-  /** `"bearer"` */
-  token_type: string
-  customer: StoreCustomer
-}
-
-/**
- * POST /api/store/auth/code/verify — passwordless login step 2: exchange
- * (email, code) for a session. This is ALSO passwordless registration — a
- * first-time email lazy-creates the customer (account_status per the store
- * approval policy) and triggers the welcome email.
- *
- * Auth: anon (x-client-id only).
- * Errors: 401 invalid_code (wrong/expired/consumed/locked-out — always
- * generic) · 400 validation_failed (email shape, non-6-digit code) ·
- * 400 missing_client_id.
- * Settings: store approval policy (`account_status` of new customers);
- * `account-welcome` email template.
- */
-export async function verifyLoginCode(
-  client: StorefrontClient,
-  input: VerifyLoginCodeInput
-): Promise<CustomerSessionResponse> {
-  return client.post("/api/store/auth/code/verify", input)
-}
+/**
+ * @cartbase/storefront/api/auth — passwordless code login (customer-accounts
+ * card §2, Shopify Customer Account API direction).
+ *
+ * Ground truth: src/app/api/store/auth/code/{request,verify}/route.ts +
+ * src/lib/customer-auth/{codes,session}.ts.
+ *
+ * ## Session discipline (READ THIS before wiring auth)
+ *
+ * `verifyLoginCode` mints a REAL Supabase session. The `access_token` is the
+ * SAME `authorization: Bearer <jwt>` every /api/store/* route accepts — wire
+ * it into `StorefrontClient` via `getAuthToken` and every subsequent call
+ * (customers/me, orders, documents, cart-attach) is authenticated:
+ *
+ * ```ts
+ * const { access_token, refresh_token } = await verifyLoginCode(client, { email, code })
+ * // persist both; then construct/refresh the client with:
+ * //   getAuthToken: () => readStoredAccessToken()
+ * ```
+ *
+ * Tokens expire (`expires_in` seconds / `expires_at` epoch-seconds): refresh
+ * with the Supabase client (`supabase.auth.setSession({access_token,
+ * refresh_token})` then `refreshSession()`) — the Cartbase API does not proxy
+ * token refresh. Password login (supabase.auth.signInWithPassword
+ * client-side) yields an equivalent JWT and needs nothing from this module.
+ *
+ * ## Security posture (server-enforced; the SDK adds nothing)
+ * - request NEVER reveals whether the email is registered (`{ok:true}`
+ *   always — no enumeration oracle); the 6-digit code exists only in the
+ *   sent email.
+ * - Codes: hashed at rest, TTL 10 min, single-use, one live code per email
+ *   (a new request supersedes prior codes), 5-wrong-attempt lockout.
+ * - Rate limits (per 15-min window): 5 requests per email, 20 per IP →
+ *   `429 rate_limited` — the ONLY distinguishable request failure.
+ * - Every verify failure is `401 invalid_code` (generic, no oracle).
+ */
+
+import type { StorefrontClient } from "./http"
+import type { StoreCustomer } from "./customers"
+
+export interface RequestLoginCodeInput {
+  email: string
+}
+
+export interface RequestLoginCodeResponse {
+  /** Always true — success is deliberately indistinguishable per email. */
+  ok: true
+}
+
+/**
+ * POST /api/store/auth/code/request — passwordless login step 1: email a
+ * 6-digit one-time code. Always `{ok: true}` (no enumeration oracle);
+ * first-time emails register lazily at VERIFY, not here.
+ *
+ * Auth: anon (x-client-id only).
+ * Errors: 429 rate_limited (5/email or 20/IP per 15 min) ·
+ * 400 validation_failed (malformed email) · 400 missing_client_id.
+ * Settings: the `auth-code` email template (notifications) carries the code.
+ */
+export async function requestLoginCode(
+  client: StorefrontClient,
+  input: RequestLoginCodeInput
+): Promise<RequestLoginCodeResponse> {
+  return client.post("/api/store/auth/code/request", input)
+}
+
+export interface VerifyLoginCodeInput {
+  email: string
+  /** Exactly 6 digits (leading zeros count) — anything else → 400. */
+  code: string
+}
+
+/**
+ * The minted session — a real Supabase token pair plus the resolved
+ * customer (addresses embedded).
+ */
+export interface CustomerSessionResponse {
+  /** Supabase JWT — send as `authorization: Bearer <access_token>`. */
+  access_token: string
+  refresh_token: string
+  /** Seconds until expiry. */
+  expires_in: number
+  /** Unix epoch seconds of expiry (may be absent). */
+  expires_at: number | undefined
+  /** `"bearer"` */
+  token_type: string
+  customer: StoreCustomer
+}
+
+/**
+ * POST /api/store/auth/code/verify — passwordless login step 2: exchange
+ * (email, code) for a session. This is ALSO passwordless registration — a
+ * first-time email lazy-creates the customer (account_status per the store
+ * approval policy) and triggers the welcome email.
+ *
+ * Auth: anon (x-client-id only).
+ * Errors: 401 invalid_code (wrong/expired/consumed/locked-out — always
+ * generic) · 400 validation_failed (email shape, non-6-digit code) ·
+ * 400 missing_client_id.
+ * Settings: store approval policy (`account_status` of new customers);
+ * `account-welcome` email template.
+ */
+export async function verifyLoginCode(
+  client: StorefrontClient,
+  input: VerifyLoginCodeInput
+): Promise<CustomerSessionResponse> {
+  return client.post("/api/store/auth/code/verify", input)
+}