@baeta/extension-auth

Interfaces

AuthMiddlewareOptions<Grants, Result, Root, Context, Args>

Options for authorization middlewares

Type Parameters

Type Parameter
Grants extends string
Result
Root
Context
Args

Properties

Property	Type	Description
grants?	GetGrant<Grants, 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

---

AuthMiddlewareSubscribeOptions<Root, Context, Args>

Options for authorization middlewares

Type Parameters

Type Parameter
Root
Context
Args

Properties

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

---

AuthOptions

Configuration options for the Auth Extension

Properties

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

Type Aliases

DefaultScopes<Scopes, Grants>

DefaultScopes<Scopes, Grants>: object

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

Type Parameters

Type Parameter
Scopes extends ScopesShape
Grants extends string

Type declaration

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

---

GetGrant<Grants, Result, Root, Context, Args>

GetGrant<Grants, Result, Root, Context, Args>: GetGrantFn<Grants, Result, Root, Context, Args> | GetGrantResult<Grants>

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

Type Parameters

Type Parameter
Grants extends string
Result
Root
Context
Args

---

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

GetGrantFn<Grants, Result, Root, Context, Args>: (params, result) => GetGrantResult<Grants> | PromiseLike<GetGrantResult<Grants>>

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

Type Parameters

Type Parameter
Grants extends string
Result
Root
Context
Args

Parameters

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

Returns

GetGrantResult<Grants> | PromiseLike<GetGrantResult<Grants>>

---

GetGrantResult<Grants>

GetGrantResult<Grants>: Grants | Grants[]

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

Type Parameters

Type Parameter
Grants extends string

---

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

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

Function to get scope rules for post-resolution authorization

Type Parameters

Type Parameter
Scopes extends ScopesShape
Grants extends string
Result
Root
Context
Args

Parameters

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

Returns

boolean | ScopeRules<Scopes, Grants> | Promise<boolean | ScopeRules<Scopes, Grants>>

---

GetScopeLoader()<Scopes, Ctx>

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

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

Type Parameters

Type Parameter
Scopes extends ScopesShape
Ctx

Parameters

Parameter	Type	Description
ctx	Ctx	The application context

Returns

ScopeLoaderMap<Scopes> | Promise<ScopeLoaderMap<Scopes>>

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()<Scopes, Grants, Root, Context, Args>

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

Function to get scope rules for pre-resolution authorization

Type Parameters

Type Parameter
Scopes extends ScopesShape
Grants extends string
Root
Context
Args

Parameters

Parameter	Type
params	MiddlewareParams<Root, Context, Args>

Returns

boolean | ScopeRules<Scopes, Grants> | Promise<boolean | ScopeRules<Scopes, Grants>>

---

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<Scopes>

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

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

Type Parameters

Type Parameter
Scopes extends ScopesShape

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<Scopes, Grants>

ScopeRules<Scopes, Grants>: { [K in keyof Scopes]?: ScopeRule<Scopes[K]> } & { [r in LogicRule]?: ScopeRules<Scopes, Grants> } & object

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

Type declaration

Name	Type
$granted?	Grants

Type Parameters

Type Parameter
Scopes
Grants extends string

---

ScopesShape

ScopesShape: {} | {}

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<Scopes, 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 } },
    },
  },
);