Class: AuthSystem<S>
Defined in: packages/polizy/src/polizy.ts:211
Type Parameters
S
S extends AuthSchema<any, any, any, any, any>
Constructors
Constructor
new AuthSystem<
S>(config):AuthSystem<S>
Defined in: packages/polizy/src/polizy.ts:238
Parameters
config
defaultCheckDepth?
number
defaultGroupRelation?
keyof S["relations"]
Relation addMember/removeMember use when no as is given and the
schema declares more than one group relation. Without it, an ambiguous
call throws. Useful when a second group relation (e.g. the role scaffold's
assignee) is added to a schema that previously had exactly one.
defaultHierarchyRelation?
keyof S["relations"]
Like defaultGroupRelation, for setParent/removeParent.
fieldSeparator?
string
Overrides the schema's field separator (defaults to the schema's, then "#").
logger?
maxDepthBehavior?
"throw" | "deny"
nonSubjectTypes?
readonly SchemaObjectTypes<S>[]
Object types that must never surface as subjects in listSubjects (unless
explicitly requested via ofType). The role scaffold's role type is
added automatically. Roles are an indirection node, not an actor.
schema
S
storage
StorageAdapter<SchemaSubjectTypes<S>, SchemaObjectTypes<S>> | StorageAdapter<string, string>
Storage adapter for checking and writing permissions. Accepts a schema-bound adapter or a wide string-typed adapter, sparing consumers a TS variance artifact.
Returns
AuthSystem<S>
Methods
addMember()
addMember(
args):Promise<StoredTuple<SchemaSubjectTypes<S>,SchemaObjectTypes<S>>>
Defined in: packages/polizy/src/polizy.ts:1559
Parameters
args
as?
keyof S["relations"]
condition?
group
AnyObject<SchemaObjectTypes<S>>
member
Subject<SchemaSubjectTypes<S>> | AnyObject<SchemaObjectTypes<S>>
Returns
Promise<StoredTuple<SchemaSubjectTypes<S>, SchemaObjectTypes<S>>>
allow()
allow(
args):Promise<StoredTuple<SchemaSubjectTypes<S>,SchemaObjectTypes<S>>>
Defined in: packages/polizy/src/polizy.ts:1504
Parameters
args
onWhat
AnyObject<SchemaObjectTypes<S>>
toBe
keyof S["relations"]
when?
who
Subject<SchemaSubjectTypes<S>> | AnyObject<SchemaObjectTypes<S>>
Returns
Promise<StoredTuple<SchemaSubjectTypes<S>, SchemaObjectTypes<S>>>
allowMany()
allowMany(
grants):Promise<StoredTuple<SchemaSubjectTypes<S>,SchemaObjectTypes<S>>[]>
Defined in: packages/polizy/src/polizy.ts:1522
Idempotently grant several relationships at once.
Parameters
grants
object[]
Returns
Promise<StoredTuple<SchemaSubjectTypes<S>, SchemaObjectTypes<S>>[]>
check()
check(
request):Promise<boolean>
Defined in: packages/polizy/src/polizy.ts:391
Parameters
request
CheckRequest<S> & ReadOptions<S>
Returns
Promise<boolean>
checkMany()
checkMany(
requests,options?):Promise<boolean[]>
Defined in: packages/polizy/src/polizy.ts:537
Answer several authorization questions at once. Each question is resolved
with its own memo (questions may carry different context), but every
question still benefits from within-question memoization.
Note: per-request contextual tuples are intentionally not supported — one reader per batch.
Parameters
requests
CheckRequest<S>[]
options?
ReadOptions<S>
Returns
Promise<boolean[]>
checkOrThrow()
checkOrThrow(
request):Promise<void>
Defined in: packages/polizy/src/polizy.ts:518
Like check, but throws NotAuthorizedError when denied.
Parameters
request
CheckRequest<S> & ReadOptions<S>
Returns
Promise<void>
countAccessibleObjects()
countAccessibleObjects(
args):Promise<number>
Defined in: packages/polizy/src/polizy.ts:720
Count the objects of ofType that who can access (optionally filtered to a
single canThey). Computes the full set today (O(reachable)); a future
materialized index can accelerate it without an API change.
Parameters
args
ListAccessibleObjectsArgs<S> & ReadOptions<S>
Returns
Promise<number>
countSubjects()
countSubjects(
args):Promise<number>
Defined in: packages/polizy/src/polizy.ts:686
Count the subjects that can perform canThey on onWhat. A wildcard grant
(everyone(type)) counts as ONE entry (the {type, "*"} subject) — it is
not expanded to a per-user count. Computes the full set today (so it is
O(reachable), not yet sub-linear); a future materialized index can
accelerate it without an API change.
Parameters
args
object & ReadOptions<S>
Returns
Promise<number>
disallowAllMatching()
disallowAllMatching(
filter):Promise<number>
Defined in: packages/polizy/src/polizy.ts:1551
Parameters
filter
onWhat?
AnyObject<SchemaObjectTypes<S>>
was?
keyof S["relations"]
who?
Subject<SchemaSubjectTypes<S>> | AnyObject<SchemaObjectTypes<S>>
Returns
Promise<number>
explain()
explain(
request,options?):Promise<ExplainResult>
Defined in: packages/polizy/src/polizy.ts:589
Explain why a check is allowed or denied, returning the granting path.
Unlike check, explain never raises MaxDepthExceededError on depth; past the
depth cap it fails soft and returns { allowed: false, via: null } even under
maxDepthBehavior "throw".
Parameters
request
CheckRequest<S>
options?
ReadOptions<S>
Returns
Promise<ExplainResult>
listAccessibleObjects()
listAccessibleObjects(
args):Promise<ListAccessibleObjectsResult<S>>
Defined in: packages/polizy/src/polizy.ts:1039
Parameters
args
ListAccessibleObjectsArgs<S> & object & ReadOptions<S>
Returns
Promise<ListAccessibleObjectsResult<S>>
listSubjects()
listSubjects(
args):Promise<Subject<SchemaSubjectTypes<S>>[]>
Defined in: packages/polizy/src/polizy.ts:623
Reverse expansion: list the subjects that can perform canThey on onWhat.
Candidates are gathered from direct holders, group members (transitively),
and the object's hierarchy ancestors, then each is confirmed with check.
Parameters
args
object & ReadOptions<S>
Returns
Promise<Subject<SchemaSubjectTypes<S>>[]>
listTuples()
listTuples(
filter,options?):Promise<StoredTuple<SchemaSubjectTypes<S>,SchemaObjectTypes<S>>[]>
Defined in: packages/polizy/src/polizy.ts:1019
Parameters
filter
Partial<Omit<InputTuple<SchemaSubjectTypes<S>, SchemaObjectTypes<S>>, "id"> & object>
options?
limit?
number
offset?
number
Returns
Promise<StoredTuple<SchemaSubjectTypes<S>, SchemaObjectTypes<S>>[]>
removeMember()
removeMember(
args):Promise<number>
Defined in: packages/polizy/src/polizy.ts:1577
Parameters
args
as?
keyof S["relations"]
group
AnyObject<SchemaObjectTypes<S>>
member
Subject<SchemaSubjectTypes<S>> | AnyObject<SchemaObjectTypes<S>>
Returns
Promise<number>
removeParent()
removeParent(
args):Promise<number>
Defined in: packages/polizy/src/polizy.ts:1610
Parameters
args
as?
keyof S["relations"]
child
AnyObject<SchemaObjectTypes<S>>
parent
AnyObject<SchemaObjectTypes<S>>
Returns
Promise<number>
setParent()
setParent(
args):Promise<StoredTuple<SchemaSubjectTypes<S>,SchemaObjectTypes<S>>>
Defined in: packages/polizy/src/polizy.ts:1590
Parameters
args
as?
keyof S["relations"]
child
AnyObject<SchemaObjectTypes<S>>
condition?
parent
AnyObject<SchemaObjectTypes<S>>
Returns
Promise<StoredTuple<SchemaSubjectTypes<S>, SchemaObjectTypes<S>>>
someoneCan()
someoneCan(
args):Promise<boolean>
Defined in: packages/polizy/src/polizy.ts:646
Existence query: does ANY subject (optionally of ofType) hold canThey on
onWhat? Short-circuits the reverse expansion at the first qualifying
subject rather than enumerating the whole set (field-level schemas fall back
to the gather-then-confirm path).
Parameters
args
object & ReadOptions<S>
Returns
Promise<boolean>
withReadScope()
withReadScope<
T>(fn,options?):Promise<T>
Defined in: packages/polizy/src/polizy.ts:411
Run several read operations against ONE shared read pass. Inside fn,
scope.check/checkMany/explain/listAccessibleObjects/listSubjects
all share a single reader, so each subject/object/relation is fetched from
storage at most once for the whole scope — not once per operation. Ideal for
a page that asks many authorization questions (a list endpoint, a dashboard).
{ preload: true } fetches the entire tuple set up front in ONE read, so
every check then resolves in memory — use it when the working set is small
or storage round-trips are expensive (e.g. an in-browser database). Omit it
for large stores, where the per-key range reads scale better.
Type Parameters
T
T
Parameters
fn
(scope) => Promise<T>
options?
ReadOptions<S>
Returns
Promise<T>
writeTuple()
writeTuple(
tuple):Promise<StoredTuple<SchemaSubjectTypes<S>,SchemaObjectTypes<S>>>
Defined in: packages/polizy/src/polizy.ts:1480
Parameters
tuple
Omit<InputTuple<SchemaSubjectTypes<S>, SchemaObjectTypes<S>>, "id"> & object
Returns
Promise<StoredTuple<SchemaSubjectTypes<S>, SchemaObjectTypes<S>>>