#Core and Contexts

PermissionCore owns initialization, health, scope facades, subject facades, runtime decisions, diagnostics, and shutdown. The host still owns authentication and the MonSQLize connection. Menu config API details such as load/actions/response live under scoped.menus.config, while subject contexts only evaluate the resulting authorization state.

#Purpose and preconditions

This section narrows the public contract for this method family. Read it before wiring the call into an admin page, route guard, or diagnostic tool.

#What Do You Want to Do?

Use this table as the shortest route from a task to the first method. Methods that can change broad state use a preview/execute pair so the admin UI can show impact before writing.

#Signatures

The signatures below are the public contract. The code block is kept executable-looking so TypeScript users can compare argument order, option requirements, and raw return wrappers quickly.

new PermissionCore(options: PermissionCoreOptions)
init(): Promise<PermissionCoreHealth>
health(): Promise<PermissionCoreHealth>
scope(scope: PermissionScope, defaults?: ScopedMutationDefaults): ScopedPermissionContext
forSubject(subject: PermissionSubject, context?: PolicyContext): SubjectPermissionContext
can(subject: PermissionSubject, action: PermissionAction, resource: string, context?: PolicyContext): Promise<boolean>
cannot(subject: PermissionSubject, action: PermissionAction, resource: string, context?: PolicyContext): Promise<boolean>
assert(subject: PermissionSubject, action: PermissionAction, resource: string, context?: PolicyContext): Promise<void>
getPermissions(subject: PermissionSubject, context?: PolicyContext): Promise<SubjectRuntimeResult<EffectivePermissionSnapshot>>
getResources(subject: PermissionSubject, action?: PermissionAction, context?: PolicyContext): Promise<SubjectRuntimeResult<EffectiveResourcePattern[]>>
explain(subject: PermissionSubject, action: PermissionAction, resource: string, context?: PolicyContext): Promise<SubjectRuntimeResult<PermissionExplanation>>
close(): Promise<void>

#Constructor Options and Shared Inputs

These inputs are shared by multiple APIs. They decide the namespace, scope, subject, policy context, revision controls, preview controls, and bounded response shape used throughout the package.

#PermissionCoreOptions

cache: {
  enabled: true,
  consistency: 'ordered-bounded-stale',
  ttlMs: 30_000,
}

#PermissionScope

#PermissionSubject and PolicyContext

#Common Response Contracts

Management writes return mutation envelopes. Reads return versioned or paged envelopes. Subject runtime calls return booleans, void, or bounded diagnostic results depending on the method.

#MutationOptions and Revision Options

#Read and Page Responses

#Write and Preview Responses

#Method Details: Initialization and Health

This section narrows the public contract for this method family. Read it before wiring the call into an admin page, route guard, or diagnostic tool.

#new PermissionCore(options)

• Purpose: Construct the root permission-core service with MonSQLize, cache, token, audit, and resource-scheme options.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#init()

• Purpose: Initialize the core service, persistence metadata, indexes, and runtime health state before use.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#health()

• Purpose: Read readiness and component health for the core service, including schema, database, cache, token, and audit status.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: VersionedResult<T> or SubjectRuntimeResult<T> depending on the context. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#Method Details: Create Management and Subject Contexts

This section narrows the public contract for this method family. Read it before wiring the call into an admin page, route guard, or diagnostic tool.

#scope(scope, defaults?)

• Purpose: Create a management facade for one trusted permission scope.
• Parameters: scope is the trusted permission namespace. defaults can bind this admin request's actorId/reason/requestId; scoped mutation and preview methods merge those audit defaults before validating per-call options.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: ScopedPermissionContext, including withDefaults(), roles, userRoles, and menus.

#forSubject(subject, context?)

• Purpose: Create a subject facade for one trusted user, scope, claims set, and optional policy context.
• Parameters: Pass trusted host state only: normalized scope, authenticated user ID, claims/context, and collection options that map every active scope field.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#Method Details: Execute Permission Decisions

This section narrows the public contract for this method family. Read it before wiring the call into an admin page, route guard, or diagnostic tool.

#can(subject, action, resource, context?) / subject.can(action, resource)

• Purpose: Return whether a trusted subject can perform one action on one resource.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: boolean or the documented matcher result. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#cannot(subject, action, resource, context?) / subject.cannot(action, resource)

• Purpose: Return the inverse of can(...) for branches that read more naturally as a negative condition.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: boolean or the documented matcher result. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#assert(subject, action, resource, context?) / subject.assert(action, resource)

• Purpose: Stop the current flow by throwing when the subject cannot perform the requested action.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: Promise<void> on success, or a structured PermissionCoreError. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#Method Details: Read and Explain

This section narrows the public contract for this method family. Read it before wiring the call into an admin page, route guard, or diagnostic tool.

#getPermissions(subject, context?) / subject.getPermissions()

• Purpose: Read the subject's resolved role IDs, rule sources, and bounded diagnostics for troubleshooting.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: VersionedResult<T> or SubjectRuntimeResult<T> depending on the context. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#getResources(subject, action?, context?) / subject.getResources(action?)

• Purpose: List effective resource patterns for the subject, optionally narrowed to one action.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: VersionedResult<T> or SubjectRuntimeResult<T> depending on the context. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#explain(subject, action, resource, context?) / subject.explain(action, resource)

• Purpose: Return the decision reason and bounded evaluation details for one permission check.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: VersionedResult<T> or SubjectRuntimeResult<T> depending on the context. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#Method Details: Close

This section narrows the public contract for this method family. Read it before wiring the call into an admin page, route guard, or diagnostic tool.

#close()

• Purpose: Drain and close permission-core resources in the correct order during shutdown.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: Promise<void> on success, or a structured PermissionCoreError. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#Responses and side effects

Side effects are scoped and revisioned. Writes record audit evidence and invalidate affected semantic cache keys; reads preserve bounded detail metadata so callers can tell whether diagnostics were complete.

{
  "data": {
    "allowed": false,
    "action": "read",
    "resource": "db:orders",
    "reason": "no-allow",
    "evaluations": [{
      "action": "read",
      "allowed": false,
      "reason": "no-allow",
      "evaluatedAllows": { "total": 0, "items": [], "truncated": false, "digest": "..." },
      "evaluatedDenies": { "total": 0, "items": [], "truncated": false, "digest": "..." }
    }]
  },
  "detailBudget": { "limit": 100, "returned": 0, "truncated": false, "digest": "..." }
}

#Failures and limits

Failures close authorization instead of widening it. Important limits are enforced before state is committed, and stale previews or revisions must be refreshed rather than guessed.

#Example

The example keeps one narrow path per page. It shows the raw method family and a compact response shape, while the full runnable scenarios live in the examples section.

const pc = new PermissionCore({ monsqlize: msq });
await pc.init();
const scoped = pc.scope(
  { tenantId: 'acme' },
  { actorId: 'admin', requestId: 'req-42' },
);
const subject = pc.forSubject({ userId: 'u-1', scope: { tenantId: 'acme' } });
const allowed = await subject.can('read', 'db:orders');
await pc.close();

{ "allowed": false }

#Related

Continue with the linked guide or neighboring API page when you need workflow context rather than only signatures.

Continue with Roles.