@ttt-productions/auth-core 1.6.16 → 1.6.17

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.17",
     "description": "Shared Firebase authentication utilities and React hooks for TTT Productions apps",
     "repository": {
         "type": "git",