@lastshotlabs/bunshot 0.0.27 → 0.0.28

package/dist/packages/bunshot-core/src/userResolver.d.ts

@@ -0,0 +1,5 @@
+import { type ContextCarrier } from './context/contextAccess';
+import type { UserResolver } from './coreContracts';
+export type { UserResolver };
+export declare function getUserResolver(input: ContextCarrier): UserResolver;
+export declare function getUserResolverOrNull(input: ContextCarrier): UserResolver | null;

package/dist/packages/bunshot-core/src/userResolver.js

@@ -0,0 +1,14 @@
+import { resolveContext } from './context/contextAccess';
+// ---------------------------------------------------------------------------
+// UserResolver -- resolves a user identity from a raw HTTP request.
+// ---------------------------------------------------------------------------
+export function getUserResolver(input) {
+    const resolver = resolveContext(input).userResolver;
+    if (resolver === null) {
+        throw new Error('No UserResolver registered for this app instance.');
+    }
+    return resolver;
+}
+export function getUserResolverOrNull(input) {
+    return resolveContext(input).userResolver;
+}

package/dist/packages/bunshot-core/src/wsMessages.d.ts

@@ -0,0 +1,42 @@
+export interface StoredMessage {
+    id: string;
+    endpoint: string;
+    room: string;
+    senderId: string | null;
+    payload: unknown;
+    createdAt: number;
+}
+export interface WsMessageDefaults {
+    maxCount?: number;
+    ttlSeconds?: number;
+}
+export interface RoomPersistenceConfig {
+    persist: boolean;
+    maxCount?: number;
+    ttlSeconds?: number;
+}
+/**
+ * WsMessageRepository — storage contract for WebSocket message persistence.
+ *
+ * Implementations store messages per (endpoint, room) scope with
+ * configurable max count and TTL-based expiration.
+ */
+export interface WsMessageRepository {
+    /** Persist a message. Returns the stored message with generated id and timestamp. */
+    persist(message: StoredMessage, config: {
+        maxCount: number;
+        ttlSeconds: number;
+    }): Promise<StoredMessage>;
+    /**
+     * Get message history for a room.
+     * Cursor-based pagination using message `id` as cursor.
+     * Returns messages in oldest-first order.
+     */
+    getHistory(endpoint: string, room: string, opts?: {
+        limit?: number;
+        before?: string;
+        after?: string;
+    }): Promise<StoredMessage[]>;
+    /** Clear all stored messages (test isolation). */
+    clear(): Promise<void>;
+}

package/dist/packages/bunshot-core/src/wsMessages.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// WebSocket Message Persistence — repository contract and types
+// ---------------------------------------------------------------------------
+export {};

package/dist/packages/bunshot-permissions/src/adapters/memory.d.ts

@@ -0,0 +1,7 @@
+import type { PermissionsAdapter } from '../types/adapter';
+export type PermissionsMemoryAdapter = PermissionsAdapter & {
+    clear(): void;
+};
+export declare function createMemoryPermissionsAdapter(options?: {
+    maxEntries?: number;
+}): PermissionsMemoryAdapter;

package/dist/packages/bunshot-permissions/src/adapters/memory.js

@@ -0,0 +1,73 @@
+import { validateGrant } from '../lib/validation';
+import { registerClearCallback, evictOldestArray, DEFAULT_MAX_ENTRIES } from '../../../bunshot-core/src/index.js';
+let _warned = false;
+export function createMemoryPermissionsAdapter(options) {
+    const maxEntries = options?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    if (!_warned) {
+        _warned = true;
+    }
+    const grants = [];
+    registerClearCallback(() => { grants.length = 0; });
+    return {
+        async createGrant(grant) {
+            validateGrant(grant);
+            const id = crypto.randomUUID();
+            const fullGrant = {
+                ...grant,
+                id,
+                grantedAt: new Date(),
+            };
+            evictOldestArray(grants, maxEntries);
+            grants.push(fullGrant);
+            return id;
+        },
+        async revokeGrant(grantId, revokedBy) {
+            const grant = grants.find(g => g.id === grantId);
+            if (!grant || grant.revokedAt)
+                return false;
+            grant.revokedBy = revokedBy;
+            grant.revokedAt = new Date();
+            return true;
+        },
+        async getGrantsForSubject(subjectId, subjectType, scope) {
+            return grants.filter(g => {
+                if (g.subjectId !== subjectId)
+                    return false;
+                if (subjectType !== undefined && g.subjectType !== subjectType)
+                    return false;
+                if (scope !== undefined) {
+                    if (scope.tenantId !== undefined && g.tenantId !== scope.tenantId)
+                        return false;
+                    if (scope.resourceType !== undefined && g.resourceType !== scope.resourceType)
+                        return false;
+                    if (scope.resourceId !== undefined && g.resourceId !== scope.resourceId)
+                        return false;
+                }
+                return true;
+            });
+        },
+        async listGrantsOnResource(resourceType, resourceId, tenantId) {
+            return grants.filter(g => {
+                if (g.resourceType !== resourceType)
+                    return false;
+                if (g.resourceId !== resourceId)
+                    return false;
+                if (tenantId !== undefined && g.tenantId !== tenantId)
+                    return false;
+                return true;
+            });
+        },
+        async deleteAllGrantsForSubject(subject) {
+            // Hard delete — remove from array
+            const toRemove = grants.filter(g => g.subjectId === subject.subjectId && g.subjectType === subject.subjectType);
+            for (const grant of toRemove) {
+                const idx = grants.indexOf(grant);
+                if (idx !== -1)
+                    grants.splice(idx, 1);
+            }
+        },
+        clear() {
+            grants.length = 0;
+        },
+    };
+}

package/dist/packages/bunshot-permissions/src/index.d.ts

@@ -0,0 +1,10 @@
+export type { PermissionGrant, SubjectRef, SubjectType, GrantEffect } from './types/models';
+export type { PermissionsAdapter } from './types/adapter';
+export type { PermissionRegistry, ResourceTypeDefinition } from './types/registry';
+export type { PermissionEvaluator, GroupResolver } from './types/evaluator';
+export { createPermissionRegistry } from './lib/registry';
+export { createPermissionEvaluator } from './lib/evaluator';
+export { createMemoryPermissionsAdapter } from './adapters/memory';
+export type { PermissionsMemoryAdapter } from './adapters/memory';
+export { seedSuperAdmin } from './lib/bootstrap';
+export { validateGrant } from './lib/validation';

package/dist/packages/bunshot-permissions/src/index.js

@@ -0,0 +1,5 @@
+export { createPermissionRegistry } from './lib/registry';
+export { createPermissionEvaluator } from './lib/evaluator';
+export { createMemoryPermissionsAdapter } from './adapters/memory';
+export { seedSuperAdmin } from './lib/bootstrap';
+export { validateGrant } from './lib/validation';

package/dist/packages/bunshot-permissions/src/lib/bootstrap.d.ts

@@ -0,0 +1,7 @@
+import type { PermissionsAdapter } from '../types/adapter';
+import type { SubjectType } from '../types/models';
+export declare function seedSuperAdmin(adapter: PermissionsAdapter, opts: {
+    subjectId: string;
+    subjectType?: SubjectType;
+    grantedBy?: string;
+}): Promise<string>;

package/dist/packages/bunshot-permissions/src/lib/bootstrap.js

@@ -0,0 +1,12 @@
+export async function seedSuperAdmin(adapter, opts) {
+    return adapter.createGrant({
+        subjectId: opts.subjectId,
+        subjectType: opts.subjectType ?? 'user',
+        tenantId: null,
+        resourceType: null,
+        resourceId: null,
+        roles: ['super-admin'],
+        effect: 'allow',
+        grantedBy: opts.grantedBy ?? 'bootstrap',
+    });
+}

package/dist/packages/bunshot-permissions/src/lib/evaluator.d.ts

@@ -0,0 +1,10 @@
+import type { PermissionsAdapter } from '../types/adapter';
+import type { PermissionRegistry } from '../types/registry';
+import type { PermissionEvaluator, GroupResolver } from '../types/evaluator';
+interface EvaluatorConfig {
+    registry: PermissionRegistry;
+    adapter: PermissionsAdapter;
+    groupResolver?: GroupResolver;
+}
+export declare function createPermissionEvaluator(config: EvaluatorConfig): PermissionEvaluator;
+export {};

package/dist/packages/bunshot-permissions/src/lib/evaluator.js

@@ -0,0 +1,165 @@
+export function createPermissionEvaluator(config) {
+    const { registry, adapter, groupResolver } = config;
+    async function collectGrantsForSubject(subject, scope) {
+        // Fetch all grants for the subject (no scope filter) and filter in-memory
+        const allGrants = await adapter.getGrantsForSubject(subject.subjectId, subject.subjectType);
+        const tenantId = scope?.tenantId;
+        const resourceType = scope?.resourceType ?? null;
+        const resourceId = scope?.resourceId ?? null;
+        // Cascade levels — collect grants that match any of:
+        // 1. (tenantId=T, resourceType=RT, resourceId=RID) — specific resource
+        // 2. (tenantId=T, resourceType=RT, resourceId=null) — all resources of type in tenant
+        // 3. (tenantId=T, resourceType=null, resourceId=null) — anything in tenant
+        // 4. (tenantId=null, resourceType=null, resourceId=null) — global
+        return allGrants.filter(grant => {
+            // Global grant (level 4) — always in scope
+            if (grant.tenantId === null && grant.resourceType === null && grant.resourceId === null) {
+                return true;
+            }
+            // If no tenantId in scope, only global grants apply
+            if (tenantId === undefined) {
+                return false;
+            }
+            // Levels 1-3 only apply when tenant matches
+            if (grant.tenantId !== tenantId)
+                return false;
+            // Level 3: anything in tenant
+            if (grant.resourceType === null && grant.resourceId === null) {
+                return true;
+            }
+            // Levels 1-2 only if resourceType is specified and matches
+            if (resourceType !== null && grant.resourceType === resourceType) {
+                // Level 2: all resources of type in tenant (resourceId=null)
+                if (grant.resourceId === null) {
+                    return true;
+                }
+                // Level 1: specific resource
+                if (resourceId !== null && grant.resourceId === resourceId) {
+                    return true;
+                }
+            }
+            return false;
+        });
+    }
+    async function collectActiveGrants(subject, scope) {
+        let grants = await collectGrantsForSubject(subject, scope);
+        // Group expansion for users
+        if (subject.subjectType === 'user' && groupResolver) {
+            const tenantId = scope?.tenantId ?? null;
+            const groupIds = await groupResolver.getGroupsForUser(subject.subjectId, tenantId);
+            for (const groupId of groupIds) {
+                const groupGrants = await collectGrantsForSubject({ subjectId: groupId, subjectType: 'group' }, scope);
+                grants = grants.concat(groupGrants);
+            }
+        }
+        // Filter out revoked and expired grants
+        const now = new Date();
+        return grants.filter(g => {
+            if (g.revokedAt)
+                return false;
+            if (g.expiresAt && g.expiresAt < now)
+                return false;
+            return true;
+        });
+    }
+    function evaluateAction(grants, action, resourceType) {
+        const denyGrants = grants.filter(g => g.effect === 'deny');
+        const allowGrants = grants.filter(g => g.effect === 'allow');
+        // CRITICAL: deny always wins — check deny grants first
+        // Field-specific deny grants only block field access, not resource access
+        for (const grant of denyGrants) {
+            if (grant.fields)
+                continue; // field-specific deny doesn't block resource-level access
+            for (const role of grant.roles) {
+                const actions = registry.getActionsForRole(resourceType, role);
+                if (actions.includes('*') || actions.includes(action)) {
+                    return false;
+                }
+            }
+        }
+        // Check allow grants
+        for (const grant of allowGrants) {
+            for (const role of grant.roles) {
+                const actions = registry.getActionsForRole(resourceType, role);
+                if (actions.includes('*') || actions.includes(action)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    return {
+        async can(subject, action, scope) {
+            const activeGrants = await collectActiveGrants(subject, scope);
+            const resourceType = scope?.resourceType ?? '';
+            return evaluateAction(activeGrants, action, resourceType);
+        },
+        async canAccessField(subject, action, field, scope) {
+            const activeGrants = await collectActiveGrants(subject, scope);
+            const resourceType = scope?.resourceType ?? '';
+            const denyGrants = activeGrants.filter(g => g.effect === 'deny');
+            const allowGrants = activeGrants.filter(g => g.effect === 'allow');
+            // Check deny grants first — deny wins
+            for (const grant of denyGrants) {
+                for (const role of grant.roles) {
+                    const actions = registry.getActionsForRole(resourceType, role);
+                    if (actions.includes('*') || actions.includes(action)) {
+                        // Field-agnostic deny (no fields = all fields) blocks this field
+                        if (!grant.fields)
+                            return false;
+                        // Field-specific deny blocks if this field is listed
+                        if (grant.fields.includes(field))
+                            return false;
+                    }
+                }
+            }
+            // Check allow grants
+            for (const grant of allowGrants) {
+                for (const role of grant.roles) {
+                    const actions = registry.getActionsForRole(resourceType, role);
+                    if (actions.includes('*') || actions.includes(action)) {
+                        // Field-agnostic allow (no fields = all fields) grants this field
+                        if (!grant.fields)
+                            return true;
+                        // Field-specific allow grants if this field is listed
+                        if (grant.fields.includes(field))
+                            return true;
+                    }
+                }
+            }
+            return false;
+        },
+        async getAccessibleFields(subject, action, availableFields, scope) {
+            const activeGrants = await collectActiveGrants(subject, scope);
+            const resourceType = scope?.resourceType ?? '';
+            const denyGrants = activeGrants.filter(g => g.effect === 'deny');
+            const allowGrants = activeGrants.filter(g => g.effect === 'allow');
+            // Pre-compute which grants have matching actions
+            const actionMatchingDenies = denyGrants.filter(grant => grant.roles.some(role => {
+                const actions = registry.getActionsForRole(resourceType, role);
+                return actions.includes('*') || actions.includes(action);
+            }));
+            const actionMatchingAllows = allowGrants.filter(grant => grant.roles.some(role => {
+                const actions = registry.getActionsForRole(resourceType, role);
+                return actions.includes('*') || actions.includes(action);
+            }));
+            return availableFields.filter(field => {
+                // Deny check
+                for (const grant of actionMatchingDenies) {
+                    if (!grant.fields)
+                        return false; // field-agnostic deny blocks all
+                    if (grant.fields.includes(field))
+                        return false; // field-specific deny
+                }
+                // Allow check
+                for (const grant of actionMatchingAllows) {
+                    if (!grant.fields)
+                        return true; // field-agnostic allow grants all
+                    if (grant.fields.includes(field))
+                        return true; // field-specific allow
+                }
+                return false;
+            });
+        },
+    };
+}

package/dist/packages/bunshot-permissions/src/lib/registry.d.ts

@@ -0,0 +1,2 @@
+import type { PermissionRegistry } from '../types/registry';
+export declare function createPermissionRegistry(): PermissionRegistry;

package/dist/packages/bunshot-permissions/src/lib/registry.js

@@ -0,0 +1,31 @@
+export function createPermissionRegistry() {
+    const definitions = new Map();
+    return {
+        register(definition) {
+            // Intentional design choice — register once, immutable thereafter. This is not a limitation;
+            // it enforces clean domain ownership. Extending a domain means adding a new resource type
+            // (e.g. `admin:billing`), not re-registering an existing one with more actions. If you need
+            // to extend another plugin's namespace, that plugin must own the registration.
+            if (definitions.has(definition.resourceType)) {
+                throw new Error(`Resource type '${definition.resourceType}' is already registered`);
+            }
+            definitions.set(definition.resourceType, definition);
+        },
+        getActionsForRole(resourceType, role) {
+            // super-admin always gets ['*'] regardless of resourceType
+            if (role === 'super-admin') {
+                return ['*'];
+            }
+            const definition = definitions.get(resourceType);
+            if (!definition)
+                return [];
+            return definition.roles[role] ?? [];
+        },
+        getDefinition(resourceType) {
+            return definitions.get(resourceType) ?? null;
+        },
+        listResourceTypes() {
+            return Array.from(definitions.values());
+        },
+    };
+}

package/dist/packages/bunshot-permissions/src/lib/validation.d.ts

@@ -0,0 +1 @@
+export { validateGrant } from '../../../bunshot-core/src/index.js';

package/dist/packages/bunshot-permissions/src/lib/validation.js

@@ -0,0 +1 @@
+export { validateGrant } from '../../../bunshot-core/src/index.js';

package/dist/packages/bunshot-permissions/src/types/adapter.d.ts

@@ -0,0 +1 @@
+export type { PermissionsAdapter } from '../../../bunshot-core/src/index.js';

package/dist/packages/bunshot-permissions/src/types/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-permissions/src/types/evaluator.d.ts

@@ -0,0 +1 @@
+export type { GroupResolver, PermissionEvaluator } from '../../../bunshot-core/src/index.js';

package/dist/packages/bunshot-permissions/src/types/evaluator.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-permissions/src/types/models.d.ts

@@ -0,0 +1 @@
+export type { SubjectType, GrantEffect, SubjectRef, PermissionGrant } from '../../../bunshot-core/src/index.js';

package/dist/packages/bunshot-permissions/src/types/models.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-permissions/src/types/registry.d.ts

@@ -0,0 +1 @@
+export type { ResourceTypeDefinition, PermissionRegistry } from '../../../bunshot-core/src/index.js';

package/dist/packages/bunshot-permissions/src/types/registry.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-postgres/src/adapter.d.ts

@@ -0,0 +1,6 @@
+import { Pool } from 'pg';
+import type { AuthAdapter } from '../../bunshot-core/src/index.js';
+export interface PostgresAdapterOptions {
+    pool: Pool;
+}
+export declare function createPostgresAdapter(opts: PostgresAdapterOptions): Promise<AuthAdapter>;