endpoint-permissions-kit 0.1.0 → 0.2.0

package/dist/types/properties.d.ts

@@ -0,0 +1,17 @@
+import type { Data, Properties } from './types';
+declare const properties: {
+    /**
+     * Checks one path declared in `registerActions`.
+     * Array indexes never appear in the paths of `data` (elements share their
+     * container's path), and a leading wildcard would grant that leaf under every
+     * root key.
+     */
+    checkDeclaredPath(property: string, permissionPath: string): void;
+    /**
+     * Compares the paths of `data` with the fields the permission allows.
+     * Denies the request with `PROPERTIES_NOT_ALLOWED`, or returns a cropped copy
+     * when the `cropper` option is on. `data` is never mutated.
+     */
+    resolve(data: Data, allowed: Properties, cropper: boolean): Data;
+};
+export default properties;

package/dist/types/registry.d.ts

@@ -16,4 +16,7 @@ export interface RoleBuilder {
 export interface GrantBuilder {
     registerActions(actions: GrantDefs): GrantBuilder;
 }
-export declare function defineModule(segment: string): ModuleBuilder;
+declare const registry: {
+    defineModule(segment: string): ModuleBuilder;
+};
+export default registry;

package/dist/types/resolve.d.ts

@@ -1,13 +1,57 @@
-import type { Authorization, Method, PermissionId, Properties } from './types';
-import type { NameEntry } from './state';
-export type Access = {
+import type { ModuleEntry, NameEntry, Snapshot } from './state';
+import type { Method, MethodAccessMap, Properties, Role, UserAssignments } from './types';
+/** The caller, with every assignment already checked against the sealed catalog. */
+interface Identity {
+    readonly role: Role;
+    readonly assigned: ReadonlySet<string>;
+    readonly names: ReadonlyMap<string, string>;
+}
+/** The single permission of a module an identity resolves to. */
+interface ChosenPermission {
+    readonly permissionId: string;
+    readonly entry: NameEntry;
+}
+type Access = {
     readonly status: 'granted';
     readonly properties: Properties;
-    readonly authorization: Authorization;
 } | {
     readonly status: 'disabled';
 } | {
     readonly status: 'unassigned';
 };
-export declare function permissionIdOf(role: string, action: string, name: string): PermissionId;
-export declare function resolveAccess(nameEntry: NameEntry, permissionId: string, role: string, method: Method, assigned: ReadonlySet<string>): Access;
+declare const resolve: {
+    /**
+     * Checks the identity a request or a view arrives with. Every assignment must be
+     * well formed, belong to the authenticated role and exist as assignable: one
+     * stale row denies everything, so it cannot silently widen or narrow access.
+     *
+     * It also indexes the assignments by module. A request names no permission name,
+     * so two names of the same module would leave the choice to the library: that is
+     * `AMBIGUOUS_PERMISSION` and it denies everything.
+     */
+    identity(assignments: UserAssignments, snapshot: Snapshot, roles: ReadonlySet<string>): Identity;
+    /**
+     * The permission of a module this identity resolves to. The request carries no
+     * name, so a direct assignment on that module decides, and without one the only
+     * name its grants reach does. `undefined` means the module is out of reach.
+     *
+     * Two reachable names deny with `AMBIGUOUS_PERMISSION`: picking one would widen
+     * or narrow the access the user was given, without anyone asking for it.
+     */
+    permission(registeredModule: ModuleEntry, action: string, identity: Identity): ChosenPermission | undefined;
+    /**
+     * Decides one `(role, module, name, method)`. A direct assignment decides
+     * completely and ignores grants; without it the applicable grants are combined.
+     */
+    access(nameEntry: NameEntry, permissionId: string, role: string, method: Method, assigned: ReadonlySet<string>): Access;
+    /**
+     * The four methods of one permission, for the read-only views.
+     * Returns `undefined` when the permission is out of reach, which is how a view
+     * distinguishes "not yours" from "yours but nothing enabled".
+     *
+     * Mirrors the precedence of `access` in a single pass over the grants, because a
+     * view needs no fields. Any change to `access` belongs here too.
+     */
+    methodAccess(nameEntry: NameEntry, permissionId: string, role: string, assigned: ReadonlySet<string>): MethodAccessMap | undefined;
+};
+export default resolve;

package/dist/types/seal.d.ts

@@ -1 +1,8 @@
-export declare function seal(): void;
+declare const sealer: {
+    /**
+     * Closes the registry: checks the references that could still be completed by
+     * a later import, then materializes the views. Idempotent.
+     */
+    seal(): void;
+};
+export default sealer;

package/dist/types/state.d.ts

@@ -1,10 +1,6 @@
+import type { PermissionReference } from './identifiers';
 import type { ActionDefs, GrantDefs, HookFn, Method, NamedPermissionCatalog } from './types';
-export interface PermissionReference {
-    readonly role: string;
-    readonly action: string;
-    readonly name: string;
-}
-export interface GrantEntry {
+interface GrantEntry {
     readonly source: PermissionReference;
     readonly actions: GrantDefs;
 }
@@ -17,14 +13,21 @@ export interface ModuleEntry {
     readonly names: Map<string, NameEntry>;
     readonly hooks: Map<Method, HookFn[]>;
 }
-interface Snapshot {
+export interface Snapshot {
     readonly named: NamedPermissionCatalog;
     readonly assignable: ReadonlySet<string>;
 }
 export interface State {
     roles: Set<string>;
+    cropper: boolean;
     readonly modules: Map<string, ModuleEntry>;
     snapshot: Snapshot | null;
 }
-export declare function getOrCreateState(): State;
-export {};
+declare const state: {
+    getOrCreate(): State;
+    /** Every write to the registry goes through this: sealing freezes the configuration. */
+    requireOpen(currentState: State): void;
+    /** Every read of a materialized view goes through this. */
+    requireSnapshot(currentState: State): Snapshot;
+};
+export default state;

package/dist/types/types.d.ts

@@ -1,10 +1,10 @@
-import type { ALL_FIELDS, METHODS } from './constants';
+import type constants from './constants';
 export interface RoleRegistry {
     general: true;
 }
 export type Role = keyof RoleRegistry & string;
-export type Method = (typeof METHODS)[number];
-export type Properties = readonly string[] | typeof ALL_FIELDS;
+export type Method = (typeof constants.METHODS)[number];
+export type Properties = readonly string[] | typeof constants.ALL_FIELDS;
 export type PermissionId = `${Role}::${string}::${string}`;
 export interface ActionDef {
     enabled: boolean;
@@ -18,21 +18,12 @@ export interface GrantDef {
 export type GrantDefs = Partial<Record<Method, GrantDef>>;
 export type Data = Record<string, unknown>;
 export type Context = Record<string, unknown>;
-export interface Authorization {
-    readonly direct: boolean;
-    readonly grantedBy: readonly PermissionId[];
-}
-export interface ResolvedPermission {
-    readonly role: Role;
-    readonly action: string;
-    readonly name: string;
-    readonly permissionId: PermissionId;
-    readonly method: Method;
-    readonly enabled: true;
-    readonly properties: Properties;
-    readonly authorization: Authorization;
-}
-export type HookFn = (data: Data | undefined, context: Context | undefined, permission: ResolvedPermission) => unknown;
+export type ContextValues = {
+    roles: readonly string[];
+    cropper: boolean;
+};
+export type ContextKey = keyof ContextValues;
+export type HookFn = (data: Data, context: Context, permissions: readonly string[]) => unknown;
 export type ValidationError = {
     readonly code: Exclude<PkitErrorCode, 'PROPERTIES_NOT_ALLOWED'>;
     readonly message: string;
@@ -46,29 +37,30 @@ export type ValidationError = {
     readonly cause: unknown;
 };
 export type ValidationErrorCode = ValidationError['code'];
-export type PkitErrorCode = 'ROLE_NOT_DECLARED' | 'DUPLICATE_REGISTRATION' | 'INVALID_DEFINITION' | 'INVALID_INPUT' | 'SEALED' | 'NOT_SEALED' | 'UNKNOWN_ROLE' | 'UNKNOWN_ACTION' | 'UNKNOWN_PERMISSION' | 'PERMISSION_ROLE_MISMATCH' | 'PERMISSION_NOT_ASSIGNED' | 'METHOD_DISABLED' | 'PROPERTIES_NOT_ALLOWED';
+export type PkitError = Error & {
+    name: 'PkitError';
+} & ({
+    code: Exclude<PkitErrorCode, 'PROPERTIES_NOT_ALLOWED'>;
+} | {
+    code: 'PROPERTIES_NOT_ALLOWED';
+    fields: readonly string[];
+});
+export type PkitErrorCode = 'ROLE_NOT_DECLARED' | 'DUPLICATE_REGISTRATION' | 'INVALID_DEFINITION' | 'INVALID_INPUT' | 'SEALED' | 'NOT_SEALED' | 'UNKNOWN_ROLE' | 'UNKNOWN_ACTION' | 'UNKNOWN_PERMISSION' | 'AMBIGUOUS_PERMISSION' | 'PERMISSION_ROLE_MISMATCH' | 'PERMISSION_NOT_ASSIGNED' | 'METHOD_DISABLED' | 'PROPERTIES_NOT_ALLOWED';
 export interface UserAssignments {
     role: Role;
     permissions: readonly string[];
 }
-interface PermissionInput extends UserAssignments {
+export interface ValidateInput extends UserAssignments {
     action: string;
-    name: string;
-    context?: Context;
-}
-export interface FindInput extends PermissionInput {
-    method: 'find';
-    select?: readonly string[];
+    method: Method;
     data?: Data;
+    context?: Context;
 }
-export interface WriteInput<RequestData extends Data = Data> extends PermissionInput {
-    method: Exclude<Method, 'find'>;
-    data: RequestData;
+export interface ValidateData {
+    readonly data: Data;
 }
-export type ValidateInput = FindInput | WriteInput;
-export type FindResult = Properties;
-export type ValidateResult<Result> = {
-    readonly result: Result;
+export type ValidateResult = {
+    readonly result: ValidateData;
     readonly errors: readonly [];
 } | {
     readonly result: null;
@@ -78,4 +70,3 @@ export type PermissionEntry = Readonly<ActionDef>;
 export type NamedPermissionCatalog = Readonly<Record<PermissionId, Readonly<Partial<Record<Method, PermissionEntry>>>>>;
 export type MethodAccessMap = Readonly<Record<Method, boolean>>;
 export type UserPermissionMap = Readonly<Record<PermissionId, MethodAccessMap>>;
-export {};

package/dist/types/validate.d.ts

@@ -1,3 +1,10 @@
-import type { Data, FindInput, FindResult, ValidateResult, WriteInput } from './types';
-export declare function validate(input: FindInput): Promise<ValidateResult<FindResult>>;
-export declare function validate<RequestData extends Data>(input: WriteInput<RequestData>): Promise<ValidateResult<RequestData>>;
+import type { ValidateInput, ValidateResult } from './types';
+declare const validator: {
+    /**
+     * The request boundary. Every failure of every phase becomes one entry of the
+     * returned contract, so this never throws and never answers with a partial
+     * success: on any failure `result` is `null`.
+     */
+    validate(input: ValidateInput): Promise<ValidateResult>;
+};
+export default validator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "endpoint-permissions-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-agnostic endpoint permissions with an in-memory registry, typed roles and validation hooks",
   "license": "Apache-2.0",
   "author": "yellyoshua",

package/dist/types/validators.d.ts

@@ -1,53 +0,0 @@
-import type { GrantEntry, ModuleEntry, NameEntry, PermissionReference, State } from './state';
-import type { ActionDefs, Context, Data, FindResult, HookFn, Method, PkitErrorCode, ResolvedPermission, Role, UserAssignments, ValidateInput } from './types';
-interface ValidationFailure {
-    code: PkitErrorCode;
-    message: string;
-}
-interface StringRules extends ValidationFailure {
-    minimumLength: number;
-}
-interface DirectRegistration {
-    action: string;
-    name: string;
-    role: string;
-}
-interface GrantRegistration {
-    action: string;
-    name: string;
-    permissionId: string;
-}
-interface HookRegistration {
-    action: string;
-    name?: string;
-    role?: string;
-    method: Method;
-}
-interface Identity {
-    role: Role;
-    assigned: ReadonlySet<string>;
-}
-interface ValidatedRequest {
-    registeredModule: ModuleEntry;
-    nameEntry: NameEntry;
-    permission: ResolvedPermission;
-    data: Data | undefined;
-    context: Context | undefined;
-    result: FindResult | Data;
-}
-export declare function validateStrings(value: unknown, rules: StringRules): asserts value is readonly string[];
-export declare function validateContextKey(key: unknown): asserts key is 'roles';
-export declare function validateSnapshot<Snapshot>(snapshot: Snapshot | null): asserts snapshot is Snapshot;
-export declare function validateRole(role: unknown, roles: ReadonlySet<string>, code: 'ROLE_NOT_DECLARED' | 'UNKNOWN_ROLE'): asserts role is Role;
-export declare function validateRoleCatalog(roles: unknown, state: State): asserts roles is readonly string[];
-export declare function validateRoleSegment(role: unknown): asserts role is string;
-export declare function validateModuleName(moduleName: unknown): asserts moduleName is string;
-export declare function validatePermissionName(name: unknown): asserts name is string;
-export declare function parsePermissionId(value: unknown, failure: ValidationFailure): PermissionReference;
-export declare function validateActions(actions: unknown, registration: DirectRegistration, state: State): ActionDefs;
-export declare function validateGrantActions(actions: unknown, registration: GrantRegistration, state: State): GrantEntry;
-export declare function validateHook(hook: unknown, registration: HookRegistration, state: State): asserts hook is HookFn;
-export declare function validateSealedRegistry(modules: ReadonlyMap<string, ModuleEntry>): void;
-export declare function validateIdentity(assignments: UserAssignments, state: State): Identity;
-export declare function validateRequest(input: ValidateInput, state: State): ValidatedRequest;
-export {};