@ttt-productions/auth-core 1.6.16 → 1.6.18

package/dist/server/authError.js.map

@@ -1 +1 @@
-{"version":3,"file":"authError.js","sourceRoot":"","sources":["../../src/server/authError.ts"],"names":[],"mappings":"AAyDA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAyB;IAC7B,OAAO,CAA6B;IAE7C,YAAY,IAA4B,EAAE,OAAe,EAAE,OAAmC;QAC5F,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACpD,CAAC;CACF","sourcesContent":["import type { AcceptanceRequiredDetails } from '../acceptance.js';\nimport type { EmailVerificationRequiredDetails } from '../email-verification.js';\n\n/**\n * Typed failure channel for `createAssertAuth`.\n *\n * Every EXPECTED auth outcome (not signed in, email unverified, missing profile,\n * account not in good standing) throws an `AuthAssertionError` whose `code` is\n * deliberately the matching `HttpsError` code string, so a consuming Cloud\n * Function maps it 1:1 at the app boundary:\n *\n *   catch (err) {\n *     if (err instanceof AuthAssertionError) throw new HttpsError(err.code, err.message);\n *     throw err;\n *   }\n *\n * WHY THE PACKAGE MUST NOT BUILD THE HttpsError ITSELF: firebase-functions 7.2.5\n * ships TWO distinct `HttpsError` classes — the one\n * exported from the ESM entry `firebase-functions/v2/https`, and the one the CJS\n * callable runtime closes over and `instanceof`-checks at\n * `lib/common/providers/https.js`. An `HttpsError` constructed by this package's\n * ESM `dist` fails that identity check, so `onCall` logged \"Unhandled error\" and\n * replaced a correct 400 with `500 INTERNAL`. Measured:\n *\n *   ESM class === CJS class ?              false\n *   esm-built error instanceof CJS class ? false\n *   httpErrorCode.status:                  400   (the error itself was correct)\n *\n * Because `assertAuth` is the first line of every callable, that turned EVERY auth\n * rejection — unauthenticated, unverified email, suspended, banned — into a generic\n * 500: users saw a generic error instead of the verify-email dialog, and monitoring\n * filled with 500s that were really expected answers. Constructing the HttpsError in\n * APP module space fixes the identity permanently and cannot regress when\n * firebase-functions repackages.\n *\n * This also brings auth-core in line with engineering-rules QUALITY-102 (generic\n * packages stay framework-agnostic; the consuming app's adapter binds the framework) and\n * mirrors `report-core`'s `ReportCoreTaskError`, which already works this way.\n */\nexport type AuthAssertionErrorCode =\n  'unauthenticated' | 'failed-precondition' | 'not-found' | 'permission-denied';\n\n/**\n * Structured details an `AuthAssertionError` may carry — one per refusal the client answers\n * with a surface of its own, each told apart by `reason`: the email-verification refusal\n * (`reason: 'email-verification-required'`, recognized by `isEmailVerificationRequiredError`)\n * and the acceptance refusal (`reason: 'acceptance-required'`, recognized by\n * `isAcceptanceRequiredError`). The app forwards `details` as the `HttpsError` details so the\n * client can recognize them:\n *\n *   throw new HttpsError(err.code, err.message, err.details);\n *\n * Every other rejection leaves `details` undefined.\n */\nexport type AuthAssertionErrorDetails =\n  AcceptanceRequiredDetails | EmailVerificationRequiredDetails;\n\nexport class AuthAssertionError extends Error {\n  readonly code: AuthAssertionErrorCode;\n  readonly details?: AuthAssertionErrorDetails;\n\n  constructor(code: AuthAssertionErrorCode, message: string, details?: AuthAssertionErrorDetails) {\n    super(message);\n    this.name = 'AuthAssertionError';\n    this.code = code;\n    if (details !== undefined) this.details = details;\n  }\n}\n"]}
+{"version":3,"file":"authError.js","sourceRoot":"","sources":["../../src/server/authError.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAyB;IAC7B,OAAO,CAA6B;IAE7C,YAAY,IAA4B,EAAE,OAAe,EAAE,OAAmC;QAC5F,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACpD,CAAC;CACF","sourcesContent":["import type { AcceptanceRequiredDetails } from '../acceptance.js';\nimport type { EmailVerificationRequiredDetails } from '../email-verification.js';\n\n// firebase-functions' callable runtime instanceof-checks its own HttpsError class, which one built\n// in this package's ESM dist fails (a 500 INTERNAL), so the consuming app builds the HttpsError.\nexport type AuthAssertionErrorCode =\n  'unauthenticated' | 'failed-precondition' | 'not-found' | 'permission-denied';\n\nexport type AuthAssertionErrorDetails =\n  AcceptanceRequiredDetails | EmailVerificationRequiredDetails;\n\nexport class AuthAssertionError extends Error {\n  readonly code: AuthAssertionErrorCode;\n  readonly details?: AuthAssertionErrorDetails;\n\n  constructor(code: AuthAssertionErrorCode, message: string, details?: AuthAssertionErrorDetails) {\n    super(message);\n    this.name = 'AuthAssertionError';\n    this.code = code;\n    if (details !== undefined) this.details = details;\n  }\n}\n"]}

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
 export { createAssertAuth } from './assertAuth.js';
 export { AuthAssertionError } from './authError.js';
 export type { AuthAssertionErrorCode, AuthAssertionErrorDetails } from './authError.js';
-export type { AcceptanceGateConfig, AssertAuthConfig, AssertAuthFn, AuthContext, AuthRequirements, AdminCheckOptions, UserStatus, } from './types.js';
+export type { AcceptanceGateConfig, AssertAuthConfig, AssertAuthFn, AuthContext, AuthRequirements, UserStatus, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AACxF,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,GACX,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AACxF,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/server/index.js

@@ -1,4 +1,3 @@
-// Public surface of @ttt-productions/auth-core/server.
 export { createAssertAuth } from './assertAuth.js';
 export { AuthAssertionError } from './authError.js';
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["// Public surface of @ttt-productions/auth-core/server.\n\nexport { createAssertAuth } from './assertAuth.js';\nexport { AuthAssertionError } from './authError.js';\nexport type { AuthAssertionErrorCode, AuthAssertionErrorDetails } from './authError.js';\nexport type {\n  AcceptanceGateConfig,\n  AssertAuthConfig,\n  AssertAuthFn,\n  AuthContext,\n  AuthRequirements,\n  AdminCheckOptions,\n  UserStatus,\n} from './types.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["export { createAssertAuth } from './assertAuth.js';\nexport { AuthAssertionError } from './authError.js';\nexport type { AuthAssertionErrorCode, AuthAssertionErrorDetails } from './authError.js';\nexport type {\n  AcceptanceGateConfig,\n  AssertAuthConfig,\n  AssertAuthFn,\n  AuthContext,\n  AuthRequirements,\n  UserStatus,\n} from './types.js';\n"]}

package/dist/server/types.d.ts

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

package/dist/server/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,IAAI;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,cAAc,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,KAAK,CAAC;IAChB,4IAA4I;IAC5I,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IACpD;;;;OAIG;IACH,SAAS,EAAE,MAAM,SAAS,CAAC;IAE3B;;;OAGG;IACH,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAEzC;;;;OAIG;IACH,aAAa,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,UAAU,CAAC;IAE3C;;;;OAIG;IACH,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAElG;;;;;OAKG;IACH,UAAU,CAAC,EAAE,oBAAoB,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,IAAI,CAC/C,OAAO,EAAE,eAAe,EACxB,YAAY,CAAC,EAAE,gBAAgB,KAC5B,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,MAAM,WAAW,gBAAgB,CAAC,aAAa,GAAG,KAAK;IACrD,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,IAAI;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,cAAc,CAAC;IACtB,OAAO,CAAC,EAAE,KAAK,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE3D,MAAM,WAAW,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,aAAa,GAAG,KAAK;IAC3E,SAAS,EAAE,MAAM,SAAS,CAAC;IAE3B,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAEzC,aAAa,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,UAAU,CAAC;IAE3C,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9F,UAAU,CAAC,EAAE,oBAAoB,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IAEjB,aAAa,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/C;AAED,MAAM,MAAM,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,aAAa,GAAG,KAAK,IAAI,CACtE,OAAO,EAAE,eAAe,EACxB,YAAY,CAAC,EAAE,gBAAgB,CAAC,aAAa,CAAC,KAC3C,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC"}

package/dist/server/types.js

@@ -1,4 +1,2 @@
-// Types for the createAssertAuth factory. Fully generic over the consuming
-// app's user document shape. The package contains no app-specific knowledge.
 export {};
 //# sourceMappingURL=types.js.map

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: (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"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { CallableRequest } from 'firebase-functions/v2/https';\nimport type { DecodedIdToken } from 'firebase-admin/auth';\nimport type { Firestore } from 'firebase-admin/firestore';\n\nexport interface AuthRequirements<TAdminOptions = never> {\n  allowUnverified?: boolean;\n\n  emailVerified?: boolean;\n\n  allowAnyStatus?: boolean;\n\n  allowSuspended?: boolean;\n\n  allowUnaccepted?: boolean;\n\n  admin?: TAdminOptions;\n}\n\nexport interface AuthContext<TUser = unknown, TAdmin = void> {\n  uid: string;\n  token: DecodedIdToken;\n  userDoc?: TUser;\n  admin?: TAdmin;\n}\n\nexport type UserStatus = 'active' | 'suspended' | 'banned';\n\nexport interface AssertAuthConfig<TUser, TAdmin = void, TAdminOptions = never> {\n  firestore: () => Firestore;\n\n  userProfilePath: (uid: string) => string;\n\n  getUserStatus: (user: TUser) => UserStatus;\n\n  requireAdmin: (uid: string, token: DecodedIdToken, options: TAdminOptions) => Promise<TAdmin>;\n\n  acceptance?: AcceptanceGateConfig;\n}\n\nexport interface AcceptanceGateConfig {\n  claimKey: string;\n\n  requiredLevel: () => number | Promise<number>;\n}\n\nexport type AssertAuthFn<TUser, TAdmin = void, TAdminOptions = never> = (\n  request: CallableRequest,\n  requirements?: AuthRequirements<TAdminOptions>,\n) => Promise<AuthContext<TUser, TAdmin>>;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ttt-productions/auth-core",
-    "version": "1.6.16",
+    "version": "1.6.18",
     "description": "Shared Firebase authentication utilities and React hooks for TTT Productions apps",
     "repository": {
         "type": "git",