@ttt-productions/auth-core 1.6.15 → 1.6.16

package/dist/server/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,6EAA6E","sourcesContent":["// Types for the createAssertAuth factory. Fully generic over the consuming\n// app's user document shape. The package contains no app-specific knowledge.\n\nimport type { CallableRequest } from \"firebase-functions/v2/https\";\nimport type { DecodedIdToken } from \"firebase-admin/auth\";\nimport type { Firestore } from \"firebase-admin/firestore\";\n\n/**\n * Per-callable requirements passed at every assertAuth call site.\n * These are application-agnostic.\n */\nexport interface AuthRequirements {\n  /**\n   * Allow unverified email. Default: false.\n   * If true, the emailVerified check is skipped entirely.\n   * Special-case for system flows (e.g. user registration).\n   */\n  allowUnverified?: boolean;\n\n  /**\n   * Require email_verified=true on the auth token.\n   * Default: false. Skipped when allowUnverified=true.\n   */\n  emailVerified?: boolean;\n\n  /**\n   * Skip the status check entirely. Special-case for flows where the\n   * user doc may not exist yet (e.g. user registration).\n   * Default: false.\n   */\n  allowAnyStatus?: boolean;\n\n  /**\n   * Allow suspended users to pass the status check. Banned users still fail.\n   * Use ONLY for callables that are a suspended user's last recourse\n   * (e.g. admin-support chat / ban appeal).\n   * Default: false. Does NOT skip the existence check.\n   */\n  allowSuspended?: boolean;\n\n  /**\n   * Let a caller below the currently required acceptance level through. Meaningful only\n   * when the factory was configured with `acceptance`; ignored otherwise.\n   * Use ONLY for callables that must work before the caller accepts: the accept callable\n   * itself, registration (a new account holds no accepted level yet), and last-recourse\n   * paths such as sign-out, support, refunds, account deletion, and legally required\n   * reporting. Default: false.\n   */\n  allowUnaccepted?: boolean;\n\n  /**\n   * Require admin status. Delegates to config.requireAdmin().\n   * The shape of this object is forwarded verbatim to the consumer's\n   * requireAdmin callback — the package does not interpret it.\n   */\n  admin?: AdminCheckOptions;\n}\n\n/**\n * Options forwarded to the consumer's requireAdmin callback. Generic shape.\n * Consuming apps may add their own fields; the package does not validate.\n */\nexport interface AdminCheckOptions {\n  allowJrAdmin?: boolean;\n  useFastCheck?: boolean;\n  errorMessage?: string;\n  [key: string]: unknown;\n}\n\n/**\n * Return value from assertAuth. Generic over the consuming app's user\n * document type.\n */\nexport interface AuthContext<TUser = unknown, TAdmin = void> {\n  uid: string;\n  token: DecodedIdToken;\n  /** Populated when the user doc was read (default not-banned check). */\n  userDoc?: TUser;\n  /** Result returned by config.requireAdmin. Populated only when an admin check ran (AuthRequirements.admin was set). Undefined otherwise. */\n  admin?: TAdmin;\n}\n\n/**\n * Status the consuming app reports for a user doc. The package only\n * interprets these three values.\n */\nexport type UserStatus = \"active\" | \"suspended\" | \"banned\";\n\n/**\n * Configuration for createAssertAuth. The consuming app supplies every\n * app-specific operation as a callback.\n */\nexport interface AssertAuthConfig<TUser, TAdmin = void> {\n  /**\n   * Returns the admin Firestore instance. Called every assertAuth invocation\n   * that needs a Firestore read. Implementations typically return\n   * `admin.firestore()` from a memoized handle.\n   */\n  firestore: () => Firestore;\n\n  /**\n   * Returns the Firestore document path for a user profile, given a uid.\n   * Example: `userProfiles/${uid}`\n   */\n  userProfilePath: (uid: string) => string;\n\n  /**\n   * Returns the user's status given the user doc data. The package only\n   * acts on 'active' | 'suspended' | 'banned'. Apps may store status in any\n   * field; this callback interprets it.\n   */\n  getUserStatus: (user: TUser) => UserStatus;\n\n  /**\n   * Admin check. Called only when AuthRequirements.admin is set. The\n   * package forwards uid, token, and the admin options verbatim. The\n   * callback throws (typically HttpsError) on failure.\n   */\n  requireAdmin: (\n    uid: string,\n    token: DecodedIdToken,\n    options: AdminCheckOptions\n  ) => Promise<TAdmin>;\n\n  /**\n   * Optional acceptance-level gate. When set, every assertAuth call that does not pass\n   * `allowUnaccepted` refuses a caller whose accepted level (read from the token claim\n   * `claimKey`) is below the level `requiredLevel()` returns. Absent = no gate, exactly the\n   * behavior before the gate existed.\n   */\n  acceptance?: AcceptanceGateConfig;\n}\n\n/**\n * The consuming app's acceptance-level wiring. The package holds no claim name and no\n * document knowledge: the app names the claim and supplies the current requirement.\n */\nexport interface AcceptanceGateConfig {\n  /** The custom claim on the verified ID token that holds the caller's accepted level. */\n  claimKey: string;\n\n  /**\n   * The level currently required. Runs on every gated assertAuth, so it must be cheap —\n   * read it from a cached snapshot, never a fresh Firestore read per call. A non-finite or\n   * non-positive result requires nothing (see `normalizeAcceptanceLevel`); a throw rejects\n   * the call.\n   */\n  requiredLevel: () => number | Promise<number>;\n}\n\n/**\n * The function returned by createAssertAuth.\n */\nexport type AssertAuthFn<TUser, TAdmin = void> = (\n  request: CallableRequest,\n  requirements?: AuthRequirements\n) => Promise<AuthContext<TUser, TAdmin>>;\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,6EAA6E","sourcesContent":["// Types for the createAssertAuth factory. Fully generic over the consuming\n// app's user document shape. The package contains no app-specific knowledge.\n\nimport type { CallableRequest } from 'firebase-functions/v2/https';\nimport type { DecodedIdToken } from 'firebase-admin/auth';\nimport type { Firestore } from 'firebase-admin/firestore';\n\n/**\n * Per-callable requirements passed at every assertAuth call site.\n * These are application-agnostic.\n */\nexport interface AuthRequirements {\n  /**\n   * Allow unverified email. Default: false.\n   * If true, the emailVerified check is skipped entirely.\n   * Special-case for system flows (e.g. user registration).\n   */\n  allowUnverified?: boolean;\n\n  /**\n   * Require email_verified=true on the auth token.\n   * Default: false. Skipped when allowUnverified=true.\n   */\n  emailVerified?: boolean;\n\n  /**\n   * Skip the status check entirely. Special-case for flows where the\n   * user doc may not exist yet (e.g. user registration).\n   * Default: false.\n   */\n  allowAnyStatus?: boolean;\n\n  /**\n   * Allow suspended users to pass the status check. Banned users still fail.\n   * Use ONLY for callables that are a suspended user's last recourse\n   * (e.g. admin-support chat / ban appeal).\n   * Default: false. Does NOT skip the existence check.\n   */\n  allowSuspended?: boolean;\n\n  /**\n   * Let a caller below the currently required acceptance level through. Meaningful only\n   * when the factory was configured with `acceptance`; ignored otherwise.\n   * Use ONLY for callables that must work before the caller accepts: the accept callable\n   * itself, registration (a new account holds no accepted level yet), and last-recourse\n   * paths such as sign-out, support, refunds, account deletion, and legally required\n   * reporting. Default: false.\n   */\n  allowUnaccepted?: boolean;\n\n  /**\n   * Require admin status. Delegates to config.requireAdmin().\n   * The shape of this object is forwarded verbatim to the consumer's\n   * requireAdmin callback — the package does not interpret it.\n   */\n  admin?: AdminCheckOptions;\n}\n\n/**\n * Options forwarded to the consumer's requireAdmin callback. Generic shape.\n * Consuming apps may add their own fields; the package does not validate.\n */\nexport interface AdminCheckOptions {\n  allowJrAdmin?: boolean;\n  useFastCheck?: boolean;\n  errorMessage?: string;\n  [key: string]: unknown;\n}\n\n/**\n * Return value from assertAuth. Generic over the consuming app's user\n * document type.\n */\nexport interface AuthContext<TUser = unknown, TAdmin = void> {\n  uid: string;\n  token: DecodedIdToken;\n  /** Populated when the user doc was read (default not-banned check). */\n  userDoc?: TUser;\n  /** Result returned by config.requireAdmin. Populated only when an admin check ran (AuthRequirements.admin was set). Undefined otherwise. */\n  admin?: TAdmin;\n}\n\n/**\n * Status the consuming app reports for a user doc. The package only\n * interprets these three values.\n */\nexport type UserStatus = 'active' | 'suspended' | 'banned';\n\n/**\n * Configuration for createAssertAuth. The consuming app supplies every\n * app-specific operation as a callback.\n */\nexport interface AssertAuthConfig<TUser, TAdmin = void> {\n  /**\n   * Returns the admin Firestore instance. Called every assertAuth invocation\n   * that needs a Firestore read. Implementations typically return\n   * `admin.firestore()` from a memoized handle.\n   */\n  firestore: () => Firestore;\n\n  /**\n   * Returns the Firestore document path for a user profile, given a uid.\n   * Example: `userProfiles/${uid}`\n   */\n  userProfilePath: (uid: string) => string;\n\n  /**\n   * Returns the user's status given the user doc data. The package only\n   * acts on 'active' | 'suspended' | 'banned'. Apps may store status in any\n   * field; this callback interprets it.\n   */\n  getUserStatus: (user: TUser) => UserStatus;\n\n  /**\n   * Admin check. Called only when AuthRequirements.admin is set. The\n   * package forwards uid, token, and the admin options verbatim. The\n   * callback throws (typically HttpsError) on failure.\n   */\n  requireAdmin: (uid: string, token: DecodedIdToken, options: AdminCheckOptions) => Promise<TAdmin>;\n\n  /**\n   * Optional acceptance-level gate. When set, every assertAuth call that does not pass\n   * `allowUnaccepted` refuses a caller whose accepted level (read from the token claim\n   * `claimKey`) is below the level `requiredLevel()` returns. Absent = no gate, exactly the\n   * behavior before the gate existed.\n   */\n  acceptance?: AcceptanceGateConfig;\n}\n\n/**\n * The consuming app's acceptance-level wiring. The package holds no claim name and no\n * document knowledge: the app names the claim and supplies the current requirement.\n */\nexport interface AcceptanceGateConfig {\n  /** The custom claim on the verified ID token that holds the caller's accepted level. */\n  claimKey: string;\n\n  /**\n   * The level currently required. Runs on every gated assertAuth, so it must be cheap —\n   * read it from a cached snapshot, never a fresh Firestore read per call. A non-finite or\n   * non-positive result requires nothing (see `normalizeAcceptanceLevel`); a throw rejects\n   * the call.\n   */\n  requiredLevel: () => number | Promise<number>;\n}\n\n/**\n * The function returned by createAssertAuth.\n */\nexport type AssertAuthFn<TUser, TAdmin = void> = (\n  request: CallableRequest,\n  requirements?: AuthRequirements,\n) => Promise<AuthContext<TUser, TAdmin>>;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ttt-productions/auth-core",
-    "version": "1.6.15",
+    "version": "1.6.16",
     "description": "Shared Firebase authentication utilities and React hooks for TTT Productions apps",
     "repository": {
         "type": "git",
@@ -21,8 +21,8 @@
             "default": "./dist/index.js"
         },
         "./client": {
-            "types": "./dist/client.d.ts",
-            "default": "./dist/client.js"
+            "types": "./dist/client/index.d.ts",
+            "default": "./dist/client/index.js"
         },
         "./react": {
             "types": "./dist/react/index.d.ts",

package/dist/auth.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAGhD,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,KAAK,IAAI,EAC/B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACjC,WAAW,CAEb"}

package/dist/auth.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,IAAI,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAI3E,MAAM,UAAU,WAAW,CAAC,IAAU;IACpC,OAAO,IAAI,CAAC,WAAW,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAU,EACV,EAA+B,EAC/B,OAAkC;IAElC,OAAO,oBAAoB,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC","sourcesContent":["import type { Auth, User } from \"firebase/auth\";\nimport { onAuthStateChanged as fbOnAuthStateChanged } from \"firebase/auth\";\n\nexport type Unsubscribe = () => void;\n\nexport function getAuthUser(auth: Auth): User | null {\n  return auth.currentUser;\n}\n\n/**\n * Thin wrapper around Firebase onAuthStateChanged.\n * - always returns the unsubscribe function\n * - preserves Firebase callback signature\n */\nexport function onAuthStateChanged(\n  auth: Auth,\n  cb: (user: User | null) => void,\n  onError?: (error: unknown) => void\n): Unsubscribe {\n  return fbOnAuthStateChanged(auth, cb, onError);\n}\n"]}

package/dist/claims.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../src/claims.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE/D,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;AAEpD,MAAM,MAAM,YAAY,GAAG;IAEzB,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB,GAAG,EAAE,aAAa,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAQvF;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAIpF;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAErF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,CAUlF"}

package/dist/claims.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"claims.js","sourceRoot":"","sources":["../src/claims.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAiB;IACtD,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC/C,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;QACtE,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAChD,OAAO,KAAK,CAAC,MAAM,CAAC;IACtB,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAiB;IACnD,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC9C,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAAU;IACpD,OAAO,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,MAAwC;IAClE,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,EAAE,CAAkB,CAAC;IAE5C,MAAM,UAAU,GAAI,GAAW,CAAC,KAAK,CAAC;IACtC,MAAM,KAAK,GACT,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC;QAC7E,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;YAC/C,EAAE,CAAC;IAEL,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AACxB,CAAC","sourcesContent":["import type { Auth, User, IdTokenResult } from \"firebase/auth\";\n\nexport type IdTokenClaims = IdTokenResult[\"claims\"];\n\nexport type ParsedClaims = {\n  // common defaults (kept generic)\n  roles: string[];\n  // raw claims for app-level decisions\n  raw: IdTokenClaims;\n};\n\n/**\n * Get the current user's ID token claims.\n * Returns null if no current user.\n *\n * STALE-VERIFICATION RECONCILIATION: when the ACCOUNT says the email is\n * verified but the cached token claim still says it is not, force-mint a fresh\n * token and return ITS claims. Firebase ID tokens live for up to an hour and a\n * backend-side `emailVerified` flip (verification link applied elsewhere, or an\n * Admin SDK update) never invalidates them — without this, the UI (account\n * state) believes the user is verified while every backend call (token claim)\n * rejects with \"Email must be verified\" until the token happens to rotate.\n * One forced mint converges the two (the fresh token carries\n * `email_verified: true`); the check is directional, so an already-consistent\n * user never pays a forced refresh.\n */\nexport async function getIdTokenClaims(user: User | null): Promise<IdTokenClaims | null> {\n  if (!user) return null;\n  const res = await user.getIdTokenResult(false);\n  if (user.emailVerified === true && res.claims.email_verified !== true) {\n    const fresh = await user.getIdTokenResult(true);\n    return fresh.claims;\n  }\n  return res.claims;\n}\n\n/**\n * Forces refresh of ID token + claims.\n * Returns null if no current user.\n */\nexport async function refreshClaims(user: User | null): Promise<IdTokenClaims | null> {\n  if (!user) return null;\n  const res = await user.getIdTokenResult(true);\n  return res.claims;\n}\n\n/**\n * Convenience helper when you only have Auth.\n */\nexport async function refreshClaimsFromAuth(auth: Auth): Promise<IdTokenClaims | null> {\n  return refreshClaims(auth.currentUser);\n}\n\n/**\n * Keep parsing intentionally minimal and generic:\n * - normalize \"roles\" into string[]\n * - keep raw claims attached\n */\nexport function parseClaims(claims: IdTokenClaims | null | undefined): ParsedClaims {\n  const raw = (claims ?? {}) as IdTokenClaims;\n\n  const rolesValue = (raw as any).roles;\n  const roles =\n    Array.isArray(rolesValue) ? rolesValue.filter((x) => typeof x === \"string\") :\n    typeof rolesValue === \"string\" ? [rolesValue] :\n    [];\n\n  return { roles, raw };\n}\n"]}

package/dist/client.d.ts

@@ -1,2 +0,0 @@
-export * from "./auth.js";
-//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,cAAc,WAAW,CAAC"}

package/dist/client.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,4EAA4E;AAC5E,iEAAiE;AACjE,cAAc,WAAW,CAAC","sourcesContent":["// Firebase *client* auth runtime. Importing this subpath pulls firebase/auth\n// at runtime (e.g. onAuthStateChanged), so it is intentionally kept off the\n// pure root. The pure root exposes only contracts/config/errors.\nexport * from \"./auth.js\";\n"]}