@lastshotlabs/slingshot-permissions

npm install @lastshotlabs/slingshot-permissions

Functions

createAuthGroupResolver

Creates a GroupResolver backed by a Slingshot auth runtime when one is available.

The returned resolver is lazy: it reads the current runtime on each call so it can be created before the auth plugin has populated pluginState. When auth is unavailable or the adapter does not implement group lookups, the resolver returns an empty set.

function createAuthGroupResolver(getRuntime: () => AuthLikeRuntime | null | undefined,): GroupResolver

Source: packages/slingshot-permissions/src/lib/authGroupResolver.ts

createEvaluationCache

TTL-based evaluation cache for permission checks.

Caches the boolean result of evaluator.can() calls keyed by (subjectId + subjectType + action + tenantId + resourceType + resourceId). On cache hit within the configured TTL the cached value is returned without hitting the backing adapter.

Use invalidate() after permission changes (grant create/revoke/delete) to bust the entire cache, or invalidateForActor(actorId) to bust only entries for a specific subject.

function createEvaluationCache(options?: EvaluationCacheOptions): EvaluationCache

Source: packages/slingshot-permissions/src/lib/evaluationCache.ts

createMemoryAuditTrailStore

Audit trail for permission changes.

Records every create / update / delete operation performed through a PermissionsAdapter so that operators and compliance tooling can answer “who changed what and when”.

The audit trail is opt-in: create an AuditTrailStore, then wrap your adapter with withAuditTrail().

function createMemoryAuditTrailStore(options?: MemoryAuditTrailStoreOptions,): AuditTrailStore

Source: packages/slingshot-permissions/src/lib/auditTrail.ts

createMemoryPermissionsAdapter

Alias for TestablePermissionsAdapter returned by createMemoryPermissionsAdapter. Exposes the clear() method for resetting state between tests.

function createMemoryPermissionsAdapter(options?: { maxEntries?: number; }): PermissionsMemoryAdapter

Source: packages/slingshot-permissions/src/adapters/memory.ts

createMongoPermissionsAdapter

MongoDB document shape for a PermissionGrant. _id is a UUID string rather than an ObjectId to align with the cross-adapter ID convention.

function createMongoPermissionsAdapter(conn: MongoConnectionLike): PermissionsMongoAdapter

Source: packages/slingshot-permissions/src/adapters/mongo.ts

createPermissionEvaluator

Health snapshot describing the evaluator’s recent error and timeout activity. Cross-package consumers should read this snapshot through PermissionsHealthCap rather than calling getHealth() directly; the capability is the canonical public surface and the local getHealth() is what the package uses to populate it.

All fields are cumulative counters since evaluator creation; consumers track deltas to compute rates if needed.

function createPermissionEvaluator(config: EvaluatorConfig): EvaluatorWithHealth

Source: packages/slingshot-permissions/src/lib/evaluator.ts

createPermissionRegistry

Creates an in-memory PermissionRegistry for registering resource type definitions.

The registry maps resource types (e.g. 'posts', 'admin:billing') to their allowed roles and the actions each role grants. Once registered, a resource type is immutable — re-registration throws to enforce clean domain ownership.

The super-admin role (SUPER_ADMIN_ROLE) always returns ['*'] for any resource type, regardless of what is registered.

function createPermissionRegistry(): PermissionRegistry

Source: packages/slingshot-permissions/src/lib/registry.ts

createPermissionsPackage

Configuration for the permissions package.

Controls the backing adapter, optional group expansion, and evaluator limits used when resolving role grants for user, group, and service-account subjects.

function createPermissionsPackage(rawConfig?: PermissionsPluginConfig,): SlingshotPackageDefinition

Source: packages/slingshot-permissions/src/plugin.ts

createPermissionsPostgresAdapter

A scalar value type accepted as a parameterised query parameter by pg.

async function createPermissionsPostgresAdapter(pool: PoolLike, options?: CreatePermissionsPostgresAdapterOptions,): Promise< PermissionsPostgresAdapter &

Source: packages/slingshot-permissions/src/adapters/postgres.ts

createSqlitePermissionsAdapter

A single synchronous schema migration function that receives an open RuntimeSqliteDatabase and executes DDL statements via db.run().

Remarks: Never edit or reorder existing entries — append new migrations to the end of MIGRATIONS only.

function createSqlitePermissionsAdapter(db: RuntimeSqliteDatabase,): PermissionsSqliteAdapter

Source: packages/slingshot-permissions/src/adapters/sqlite.ts

Permissions

Public contract for slingshot-permissions.

The package publishes four typed capabilities at boot:

• PermissionsEvaluatorCap — answers can() queries
• PermissionsRegistryCap — resource-type registry for role → action mappings
• PermissionsAdapterCap — persistence adapter for grants
• PermissionsHealthCap — aggregated health snapshot

Cross-package consumers resolve them via ctx.capabilities.require(...) instead of reaching into PERMISSIONS_RUNTIME_KEY directly.

Source: packages/slingshot-permissions/src/public.ts

PermissionsAdapterCap

Public contract for slingshot-permissions.

The package publishes four typed capabilities at boot:

• PermissionsEvaluatorCap — answers can() queries
• PermissionsRegistryCap — resource-type registry for role → action mappings
• PermissionsAdapterCap — persistence adapter for grants
• PermissionsHealthCap — aggregated health snapshot

Cross-package consumers resolve them via ctx.capabilities.require(...) instead of reaching into PERMISSIONS_RUNTIME_KEY directly.

Source: packages/slingshot-permissions/src/public.ts

permissionsAdapterFactories

A record that maps every StoreType to a factory function producing a PermissionsAdapter from StoreInfra. Pass to the framework’s adapter resolution machinery so the correct backend is selected at startup.

Remarks: redis is rejected because there is no Redis permissions adapter.

Source: packages/slingshot-permissions/src/factories.ts

PermissionsEvaluatorCap

Public contract for slingshot-permissions.

The package publishes four typed capabilities at boot:

• PermissionsEvaluatorCap — answers can() queries
• PermissionsRegistryCap — resource-type registry for role → action mappings
• PermissionsAdapterCap — persistence adapter for grants
• PermissionsHealthCap — aggregated health snapshot

Cross-package consumers resolve them via ctx.capabilities.require(...) instead of reaching into PERMISSIONS_RUNTIME_KEY directly.

Source: packages/slingshot-permissions/src/public.ts

PermissionsHealthCap

Public contract for slingshot-permissions.

The package publishes four typed capabilities at boot:

• PermissionsEvaluatorCap — answers can() queries
• PermissionsRegistryCap — resource-type registry for role → action mappings
• PermissionsAdapterCap — persistence adapter for grants
• PermissionsHealthCap — aggregated health snapshot

Cross-package consumers resolve them via ctx.capabilities.require(...) instead of reaching into PERMISSIONS_RUNTIME_KEY directly.

Source: packages/slingshot-permissions/src/public.ts

PermissionsRegistryCap

Public contract for slingshot-permissions.

The package publishes four typed capabilities at boot:

• PermissionsEvaluatorCap — answers can() queries
• PermissionsRegistryCap — resource-type registry for role → action mappings
• PermissionsAdapterCap — persistence adapter for grants
• PermissionsHealthCap — aggregated health snapshot

Cross-package consumers resolve them via ctx.capabilities.require(...) instead of reaching into PERMISSIONS_RUNTIME_KEY directly.

Source: packages/slingshot-permissions/src/public.ts

seedSuperAdmin

Seeds a super-admin grant for the given subject using the SUPER_ADMIN_ROLE.

The grant is global (no tenant, no resource) so it applies everywhere. This function is idempotent — if the subject already holds an active super-admin grant it returns that grant’s ID without creating a duplicate. Safe to call on every deployment.

async function seedSuperAdmin(adapter: PermissionsAdapter, opts: { subjectId: string; subjectType?: SubjectType; grantedBy?: string },): Promise<string>

Source: packages/slingshot-permissions/src/lib/bootstrap.ts

SUPER_ADMIN_ROLE

The type of entity a permission grant applies to.

• 'user' — a concrete end-user identity; subjectId is the user’s primary key as stored in the auth adapter (e.g. a UUID or nanoid)
• 'group' — a named collection of users resolved at evaluation time via GroupResolver; subjectId is the group’s ID; grants to a group apply to all current members
• 'service-account' — a non-human M2M client or API service identity; subjectId is the service account’s client ID or name; used for backend-to-backend trust grants that should not be confused with end-user permissions

Source: packages/slingshot-core/src/permissions.ts

validateGrant

The type of entity a permission grant applies to.

• 'user' — a concrete end-user identity; subjectId is the user’s primary key as stored in the auth adapter (e.g. a UUID or nanoid)
• 'group' — a named collection of users resolved at evaluation time via GroupResolver; subjectId is the group’s ID; grants to a group apply to all current members
• 'service-account' — a non-human M2M client or API service identity; subjectId is the service account’s client ID or name; used for backend-to-backend trust grants that should not be confused with end-user permissions

function validateGrant(grant: Omit<PermissionGrant, 'id' | 'grantedAt'>): void

Source: packages/slingshot-core/src/permissions.ts

withAuditTrail

Audit trail for permission changes.

Records every create / update / delete operation performed through a PermissionsAdapter so that operators and compliance tooling can answer “who changed what and when”.

The audit trail is opt-in: create an AuditTrailStore, then wrap your adapter with withAuditTrail().

function withAuditTrail(adapter: PermissionsAdapter, store: AuditTrailStore, options?: WithAuditTrailOptions,): PermissionsAdapter

Source: packages/slingshot-permissions/src/lib/auditTrail.ts

Classes

PermissionQueryTimeoutError

Health snapshot describing the evaluator’s recent error and timeout activity. Cross-package consumers should read this snapshot through PermissionsHealthCap rather than calling getHealth() directly; the capability is the canonical public surface and the local getHealth() is what the package uses to populate it.

All fields are cumulative counters since evaluator creation; consumers track deltas to compute rates if needed.

Source: packages/slingshot-permissions/src/lib/evaluator.ts

PermissionsAdapterError

Errors thrown by the permissions plugin.

Source: packages/slingshot-permissions/src/errors.ts

PermissionsConfigError

Errors thrown by the permissions plugin.

Source: packages/slingshot-permissions/src/errors.ts

PermissionsError

Errors thrown by the permissions plugin.

Source: packages/slingshot-permissions/src/errors.ts

Interfaces

AuditTrailEntry

Audit trail for permission changes.

Records every create / update / delete operation performed through a PermissionsAdapter so that operators and compliance tooling can answer “who changed what and when”.

The audit trail is opt-in: create an AuditTrailStore, then wrap your adapter with withAuditTrail().

Source: packages/slingshot-permissions/src/lib/auditTrail.ts

AuditTrailFilter

Audit trail for permission changes.

Records every create / update / delete operation performed through a PermissionsAdapter so that operators and compliance tooling can answer “who changed what and when”.

The audit trail is opt-in: create an AuditTrailStore, then wrap your adapter with withAuditTrail().

Source: packages/slingshot-permissions/src/lib/auditTrail.ts

AuditTrailStore

Audit trail for permission changes.

Records every create / update / delete operation performed through a PermissionsAdapter so that operators and compliance tooling can answer “who changed what and when”.

The audit trail is opt-in: create an AuditTrailStore, then wrap your adapter with withAuditTrail().

Source: packages/slingshot-permissions/src/lib/auditTrail.ts

CreatePermissionsPostgresAdapterOptions

A scalar value type accepted as a parameterised query parameter by pg.

Source: packages/slingshot-permissions/src/adapters/postgres.ts

EvaluationCache

TTL-based evaluation cache for permission checks.

Caches the boolean result of evaluator.can() calls keyed by (subjectId + subjectType + action + tenantId + resourceType + resourceId). On cache hit within the configured TTL the cached value is returned without hitting the backing adapter.

Use invalidate() after permission changes (grant create/revoke/delete) to bust the entire cache, or invalidateForActor(actorId) to bust only entries for a specific subject.

Source: packages/slingshot-permissions/src/lib/evaluationCache.ts

EvaluationCacheEntry

TTL-based evaluation cache for permission checks.

Caches the boolean result of evaluator.can() calls keyed by (subjectId + subjectType + action + tenantId + resourceType + resourceId). On cache hit within the configured TTL the cached value is returned without hitting the backing adapter.

Use invalidate() after permission changes (grant create/revoke/delete) to bust the entire cache, or invalidateForActor(actorId) to bust only entries for a specific subject.

Source: packages/slingshot-permissions/src/lib/evaluationCache.ts

EvaluationCacheOptions

TTL-based evaluation cache for permission checks.

Caches the boolean result of evaluator.can() calls keyed by (subjectId + subjectType + action + tenantId + resourceType + resourceId). On cache hit within the configured TTL the cached value is returned without hitting the backing adapter.

Use invalidate() after permission changes (grant create/revoke/delete) to bust the entire cache, or invalidateForActor(actorId) to bust only entries for a specific subject.

Source: packages/slingshot-permissions/src/lib/evaluationCache.ts

EvaluatorHealth

Health snapshot describing the evaluator’s recent error and timeout activity. Cross-package consumers should read this snapshot through PermissionsHealthCap rather than calling getHealth() directly; the capability is the canonical public surface and the local getHealth() is what the package uses to populate it.

All fields are cumulative counters since evaluator creation; consumers track deltas to compute rates if needed.

Source: packages/slingshot-permissions/src/lib/evaluator.ts

EvaluatorLogger

Health snapshot describing the evaluator’s recent error and timeout activity. Cross-package consumers should read this snapshot through PermissionsHealthCap rather than calling getHealth() directly; the capability is the canonical public surface and the local getHealth() is what the package uses to populate it.

All fields are cumulative counters since evaluator creation; consumers track deltas to compute rates if needed.

Source: packages/slingshot-permissions/src/lib/evaluator.ts

EvaluatorWithHealth

Health snapshot describing the evaluator’s recent error and timeout activity. Cross-package consumers should read this snapshot through PermissionsHealthCap rather than calling getHealth() directly; the capability is the canonical public surface and the local getHealth() is what the package uses to populate it.

All fields are cumulative counters since evaluator creation; consumers track deltas to compute rates if needed.

Source: packages/slingshot-permissions/src/lib/evaluator.ts

GroupExpansionFailure

Health snapshot describing the evaluator’s recent error and timeout activity. Cross-package consumers should read this snapshot through PermissionsHealthCap rather than calling getHealth() directly; the capability is the canonical public surface and the local getHealth() is what the package uses to populate it.

All fields are cumulative counters since evaluator creation; consumers track deltas to compute rates if needed.

Source: packages/slingshot-permissions/src/lib/evaluator.ts

GroupResolver

The type of entity a permission grant applies to.

• 'user' — a concrete end-user identity; subjectId is the user’s primary key as stored in the auth adapter (e.g. a UUID or nanoid)
• 'group' — a named collection of users resolved at evaluation time via GroupResolver; subjectId is the group’s ID; grants to a group apply to all current members
• 'service-account' — a non-human M2M client or API service identity; subjectId is the service account’s client ID or name; used for backend-to-backend trust grants that should not be confused with end-user permissions

Source: packages/slingshot-core/src/permissions.ts

MemoryAuditTrailStoreOptions

Audit trail for permission changes.

Records every create / update / delete operation performed through a PermissionsAdapter so that operators and compliance tooling can answer “who changed what and when”.

The audit trail is opt-in: create an AuditTrailStore, then wrap your adapter with withAuditTrail().

Source: packages/slingshot-permissions/src/lib/auditTrail.ts

PermissionEvaluator

The type of entity a permission grant applies to.

• 'user' — a concrete end-user identity; subjectId is the user’s primary key as stored in the auth adapter (e.g. a UUID or nanoid)
• 'group' — a named collection of users resolved at evaluation time via GroupResolver; subjectId is the group’s ID; grants to a group apply to all current members
• 'service-account' — a non-human M2M client or API service identity; subjectId is the service account’s client ID or name; used for backend-to-backend trust grants that should not be confused with end-user permissions

Source: packages/slingshot-core/src/permissions.ts

PermissionGrant

The type of entity a permission grant applies to.

• 'user' — a concrete end-user identity; subjectId is the user’s primary key as stored in the auth adapter (e.g. a UUID or nanoid)
• 'group' — a named collection of users resolved at evaluation time via GroupResolver; subjectId is the group’s ID; grants to a group apply to all current members
• 'service-account' — a non-human M2M client or API service identity; subjectId is the service account’s client ID or name; used for backend-to-backend trust grants that should not be confused with end-user permissions

Source: packages/slingshot-core/src/permissions.ts

PermissionRegistry

The type of entity a permission grant applies to.

• 'user' — a concrete end-user identity; subjectId is the user’s primary key as stored in the auth adapter (e.g. a UUID or nanoid)
• 'group' — a named collection of users resolved at evaluation time via GroupResolver; subjectId is the group’s ID; grants to a group apply to all current members
• 'service-account' — a non-human M2M client or API service identity; subjectId is the service account’s client ID or name; used for backend-to-backend trust grants that should not be confused with end-user permissions

Source: packages/slingshot-core/src/permissions.ts

PermissionsAdapter

The type of entity a permission grant applies to.

• 'user' — a concrete end-user identity; subjectId is the user’s primary key as stored in the auth adapter (e.g. a UUID or nanoid)
• 'group' — a named collection of users resolved at evaluation time via GroupResolver; subjectId is the group’s ID; grants to a group apply to all current members
• 'service-account' — a non-human M2M client or API service identity; subjectId is the service account’s client ID or name; used for backend-to-backend trust grants that should not be confused with end-user permissions

Source: packages/slingshot-core/src/permissions.ts

PermissionsHealth

Public contract for slingshot-permissions.

The package publishes four typed capabilities at boot:

• PermissionsEvaluatorCap — answers can() queries
• PermissionsRegistryCap — resource-type registry for role → action mappings
• PermissionsAdapterCap — persistence adapter for grants
• PermissionsHealthCap — aggregated health snapshot

Cross-package consumers resolve them via ctx.capabilities.require(...) instead of reaching into PERMISSIONS_RUNTIME_KEY directly.

Source: packages/slingshot-permissions/src/public.ts

PermissionsPluginConfig

Configuration for the permissions package.

Controls the backing adapter, optional group expansion, and evaluator limits used when resolving role grants for user, group, and service-account subjects.

Source: packages/slingshot-permissions/src/plugin.ts

PermissionsPostgresAdapterHealth

A scalar value type accepted as a parameterised query parameter by pg.

Source: packages/slingshot-permissions/src/adapters/postgres.ts

ResourceTypeDefinition

The type of entity a permission grant applies to.

• 'user' — a concrete end-user identity; subjectId is the user’s primary key as stored in the auth adapter (e.g. a UUID or nanoid)
• 'group' — a named collection of users resolved at evaluation time via GroupResolver; subjectId is the group’s ID; grants to a group apply to all current members
• 'service-account' — a non-human M2M client or API service identity; subjectId is the service account’s client ID or name; used for backend-to-backend trust grants that should not be confused with end-user permissions

Source: packages/slingshot-core/src/permissions.ts

SubjectRef

The type of entity a permission grant applies to.

• 'user' — a concrete end-user identity; subjectId is the user’s primary key as stored in the auth adapter (e.g. a UUID or nanoid)
• 'group' — a named collection of users resolved at evaluation time via GroupResolver; subjectId is the group’s ID; grants to a group apply to all current members
• 'service-account' — a non-human M2M client or API service identity; subjectId is the service account’s client ID or name; used for backend-to-backend trust grants that should not be confused with end-user permissions

Source: packages/slingshot-core/src/permissions.ts

TestablePermissionsAdapter

The type of entity a permission grant applies to.

• 'user' — a concrete end-user identity; subjectId is the user’s primary key as stored in the auth adapter (e.g. a UUID or nanoid)
• 'group' — a named collection of users resolved at evaluation time via GroupResolver; subjectId is the group’s ID; grants to a group apply to all current members
• 'service-account' — a non-human M2M client or API service identity; subjectId is the service account’s client ID or name; used for backend-to-backend trust grants that should not be confused with end-user permissions

Source: packages/slingshot-core/src/permissions.ts

WithAuditTrailOptions

Audit trail for permission changes.

Records every create / update / delete operation performed through a PermissionsAdapter so that operators and compliance tooling can answer “who changed what and when”.

The audit trail is opt-in: create an AuditTrailStore, then wrap your adapter with withAuditTrail().

Source: packages/slingshot-permissions/src/lib/auditTrail.ts

Types

AuditAction

Audit trail for permission changes.

Records every create / update / delete operation performed through a PermissionsAdapter so that operators and compliance tooling can answer “who changed what and when”.

The audit trail is opt-in: create an AuditTrailStore, then wrap your adapter with withAuditTrail().

Source: packages/slingshot-permissions/src/lib/auditTrail.ts

AuditResourceType

Audit trail for permission changes.

Records every create / update / delete operation performed through a PermissionsAdapter so that operators and compliance tooling can answer “who changed what and when”.

The audit trail is opt-in: create an AuditTrailStore, then wrap your adapter with withAuditTrail().

Source: packages/slingshot-permissions/src/lib/auditTrail.ts

GrantEffect

The type of entity a permission grant applies to.

• 'user' — a concrete end-user identity; subjectId is the user’s primary key as stored in the auth adapter (e.g. a UUID or nanoid)
• 'group' — a named collection of users resolved at evaluation time via GroupResolver; subjectId is the group’s ID; grants to a group apply to all current members
• 'service-account' — a non-human M2M client or API service identity; subjectId is the service account’s client ID or name; used for backend-to-backend trust grants that should not be confused with end-user permissions

Source: packages/slingshot-core/src/permissions.ts

PermissionsAdapterFactories

A record that maps every StoreType to a factory function producing a PermissionsAdapter from StoreInfra. Pass to the framework’s adapter resolution machinery so the correct backend is selected at startup.

Remarks: redis is rejected because there is no Redis permissions adapter.

Source: packages/slingshot-permissions/src/factories.ts

PermissionsMongoAdapter

MongoDB document shape for a PermissionGrant. _id is a UUID string rather than an ObjectId to align with the cross-adapter ID convention.

Source: packages/slingshot-permissions/src/adapters/mongo.ts

PermissionsPostgresAdapter

A scalar value type accepted as a parameterised query parameter by pg.

Source: packages/slingshot-permissions/src/adapters/postgres.ts

PermissionsSqliteAdapter

A single synchronous schema migration function that receives an open RuntimeSqliteDatabase and executes DDL statements via db.run().

Remarks: Never edit or reorder existing entries — append new migrations to the end of MIGRATIONS only.

Source: packages/slingshot-permissions/src/adapters/sqlite.ts

SubjectType

The type of entity a permission grant applies to.

• 'user' — a concrete end-user identity; subjectId is the user’s primary key as stored in the auth adapter (e.g. a UUID or nanoid)
• 'group' — a named collection of users resolved at evaluation time via GroupResolver; subjectId is the group’s ID; grants to a group apply to all current members
• 'service-account' — a non-human M2M client or API service identity; subjectId is the service account’s client ID or name; used for backend-to-backend trust grants that should not be confused with end-user permissions

Source: packages/slingshot-core/src/permissions.ts