@baeta/extension-auth

Interfaces

AuthMethodOptions<Result, Root, Context, Args>

Options for authorization methods

Type Parameters

Type Parameter
Result
Root
Context
Args

Properties

Property	Type	Description
grants?	GetGrant<Result, Root, Context, Args>	Permissions to grant after successful authorization
onError?	ScopeErrorResolver	Custom error handler for this operation
skipDefaults?	boolean	Whether to skip default scopes for this operation

---

AuthMethodSubscribeOptions<Root, Context, Args>

Options for subscription authorization

Type Parameters

Type Parameter
Root
Context
Args

Properties

Property	Type	Description
onError?	ScopeErrorResolver	Custom error handler for this subscription
skipDefaults?	boolean	Whether to skip default scopes for this subscription

---

AuthOptions

Configuration options for the Auth Extension

Properties

Property	Type	Description
defaultScopes?	DefaultScopes	Default authorization scopes for queries, mutations or subscriptions
errorResolver?	ScopeErrorResolver	Custom error resolver for authorization failures

Type Aliases

DefaultScopes

DefaultScopes: object

Configuration for default authorization scopes that apply to all operations of a specific type.

Type declaration

Name	Type	Description
Mutation?	ScopeRules	Default scopes applied to all Mutation operations
Query?	ScopeRules	Default scopes applied to all Query operations
Subscription?	object	Default scopes for Subscription operations
Subscription.resolve?	ScopeRules	Scopes applied during the resolve phase
Subscription.subscribe?	ScopeRules	Scopes applied during the subscription phase

---

GetGrant<Result, Root, Context, Args>

GetGrant<Result, Root, Context, Args>: GetGrantFn<Result, Root, Context, Args> | any[]

Union type for grant specifications. Can be either a static grant result or a function that determines grants dynamically.

Type Parameters

Type Parameter
Result
Root
Context
Args

---

GetGrantFn()<Result, Root, Context, Args>

GetGrantFn<Result, Root, Context, Args>: (params, result) => any[] | PromiseLike<any[]>

Function that determines grants based on resolver parameters and result. Used for dynamic permission granting based on resolved data.

Type Parameters

Type Parameter
Result
Root
Context
Args

Parameters

Parameter	Type
params	MiddlewareParams<Root, Context, Args>
result	Result

Returns

any[] | PromiseLike<any[]>

---

GetGrantResult

GetGrantResult: AuthExtension.Grants | AuthExtension.Grants[]

Represents the result of a grant operation. Can be either a single grant or an array of grants defined in AuthExtension.GrantsMap.

---

GetPostScopeRules()<Result, Root, Context, Args>

GetPostScopeRules<Result, Root, Context, Args>: (params, result) => boolean | ScopeRules | Promise<boolean | ScopeRules>

Function to get scope rules for post-resolution authorization

Type Parameters

Type Parameter
Result
Root
Context
Args

Parameters

Parameter	Type
params	MiddlewareParams<Root, Context, Args>
result	Result

Returns

boolean | ScopeRules | Promise<boolean | ScopeRules>

---

GetScopeLoader()<Ctx>

GetScopeLoader<Ctx>: (ctx) => ScopeLoaderMap | Promise<ScopeLoaderMap>

Function that creates scope loaders for authorization checks. Returns a map of scope loaders that can be synchronous or asynchronous.

Type Parameters

Type Parameter
Ctx

Parameters

Parameter	Type	Description
ctx	Ctx	The application context

Returns

ScopeLoaderMap | Promise<ScopeLoaderMap>

A map of scope loaders or a promise resolving to scope loaders

Example

const getScopeLoader: GetScopeLoader<Context> = (ctx) => ({
  isLoggedIn: async () => {
    if (!ctx.userId) throw new UnauthenticatedError();
    return true;
  },
  hasAccess: (role) => ctx.user?.role === role,
});

---

GetScopeRules()<Root, Context, Args>

GetScopeRules<Root, Context, Args>: (params) => boolean | ScopeRules | Promise<boolean | ScopeRules>

Function to get scope rules for pre-resolution authorization

Type Parameters

Type Parameter
Root
Context
Args

Parameters

Parameter	Type
params	MiddlewareParams<Root, Context, Args>

Returns

boolean | ScopeRules | Promise<boolean | ScopeRules>

---

LogicRule

LogicRule: "$and" | "$or" | "$chain" | "$race"

Possible logical operators that can be used in a rule

---

ScopeErrorResolver()

ScopeErrorResolver: (err, path) => Error | unknown

Custom error resolver function for authorization failures.

Parameters

Parameter	Type
err	unknown
path	string

Returns

Error | unknown

---

ScopeLoader<T>

ScopeLoader<T>: boolean | (value) => boolean | Promise<boolean>

Represents a scope loader that can be either a boolean value or a function. Function loaders receive the scope value and return a boolean result.

Type Parameters

Type Parameter
T

Example

// Boolean loader
const publicLoader: ScopeLoader<boolean> = true;

// Function loader
const roleLoader: ScopeLoader<string> = (role) => userRole === role;

---

ScopeLoaderMap

ScopeLoaderMap: { [K in Scopes]: ScopeLoader<AuthExtension.Scopes[K]> }

Maps scope names to their respective loaders. Each loader handles authorization checks for its scope.

Example

const loaders: ScopeLoaderMap = {
  isPublic: true,
  isLoggedIn: () => Boolean(ctx.userId),
  hasAccess: (role) => ctx.user?.roles.includes(role),
};

---

ScopeRule<T>

ScopeRule<T>: T extends boolean ? true : T

Utility type that enforces boolean scopes must be true. For non-boolean scopes, preserves the original type.

Type Parameters

Type Parameter
T

---

ScopeRules

ScopeRules: { [K in Scopes]?: ScopeRule<AuthExtension.Scopes[K]> } & { [r in LogicRule]?: ScopeRules } & object

Defines the structure of authorization scope rules. Combines individual scope rules with logical operators and granted permissions.

Type declaration

Name	Type
$granted?	AuthExtension.Grants

---

Scopes

Scopes: keyof AuthExtension.Scopes

Type alias representing all available scope keys defined in AuthExtension.Scopes. Used as the base for constructing scope rules.

Functions

aggregateErrorResolver()

aggregateErrorResolver(err, path): any

Default error resolver for authorization failures. If multiple authorization errors are encountered they are combined into AggregateGraphQLError with proper HTTP status codes.

Parameters

Parameter	Type
err	AggregateError
path	string

Returns

any

---

authExtension()

authExtension<Ctx>(loadScopes, options): () => Extension

Creates an authentication extension.

Type Parameters

Type Parameter
Ctx

Parameters

Parameter	Type	Description
loadScopes	GetScopeLoader<Ctx>	Function to load authorization scopes
options	AuthOptions	Configuration options for the auth extension

Returns

Function

A factory function that creates an AuthExtension instance

Returns

Extension

Example

const authExt = authExtension<Context>(
  async (ctx) => ({
    isLoggedIn: () => ctx.userId != null,
    hasRole: (role) => ctx.user?.role === role,
  }),
  {
    defaultScopes: {
      Query: { isLoggedIn: true },
      Mutation: { isLoggedIn: true },
      Subscription: { subscribe: { isLoggedIn: true } },
    },
  },
);