@cqrs-ddd/pipeline-casl 0.5.0

package/dist/helpers/authorizer.d.ts

@@ -0,0 +1,73 @@
+import { type IPipelineContext } from '@cqrs-ddd/pipeline';
+import type { CaslPrincipal } from '../interfaces/permission-source.interface.js';
+import type { AppAbility, Projected } from '../types/casl.types.js';
+/** The ability `CaslBehavior` built for the current pipeline execution. */
+export declare function getCaslAbility(context?: IPipelineContext): AppAbility | undefined;
+/** The principal that ability was built for; derive security-scoped keys from it. */
+export declare function getCaslPrincipal(context?: IPipelineContext): CaslPrincipal | undefined;
+/**
+ * Entity- and field-level authorization against the request ability.
+ *
+ * Uses the constructor ability, else the ambient ability stored by
+ * `CaslBehavior`. A missing ability denies.
+ *
+ * @example
+ * ```ts
+ * const user = await this.users.findById(command.id);
+ * this.authorizer.authorize('update', user, ['username']);
+ * user.update(command.changes);
+ *
+ * return this.authorizer.project('read', user, { id: user.id, email: user.email });
+ * ```
+ */
+export declare class CaslAuthorizer {
+    private readonly ability?;
+    constructor(ability?: AppAbility | undefined);
+    /**
+     * True when `action` is permitted on `subject` (and `field`, when given).
+     * Field checks use CASL field matching, unlike {@link project}: a grant of
+     * `fields: ['profile']` does not permit `'profile.secret'`; grant
+     * `'profile.*'` or `'profile.**'` to cover nested fields.
+     */
+    can(action: string, subject: object | string, field?: string): boolean;
+    /**
+     * Throws `UnauthorizedActionException` unless `action` is permitted on
+     * `subject` and every listed field. Fields use CASL field matching, as in
+     * {@link can}.
+     */
+    authorize(action: string, subject: object | string, fields?: readonly string[]): void;
+    /**
+     * Asserts `action` on `subject`, then returns the `candidate` fields the
+     * ability permits. Conditions use `subject`, never `candidate`.
+     */
+    project<TCandidate extends object>(action: string, subject: object | string, candidate: TCandidate): Projected<TCandidate>;
+    /**
+     * Whether the decision for `action` on `subject` depends on the entity's
+     * attributes: true when a rule for that subject, `all` or `manage` carries
+     * conditions, and when no ability is present. A handler that is about to
+     * decide against a cached or otherwise possibly stale entity reads a fresh
+     * one instead.
+     *
+     * @param action - The action about to be checked, such as `'read'`.
+     * @param subject - The subject type, such as `'User'`.
+     *
+     * @example
+     * ```ts
+     * const refresh = this.authorizer.dependsOnEntity('read', 'User');
+     * const user = await this.users.findById(query.id, { refresh });
+     * return user && this.authorizer.project('read', user, user.toJSON());
+     * ```
+     */
+    dependsOnEntity(action: string, subject: string): boolean;
+    private permitted;
+}
+/**
+ * Checks whether an ability contains conditional rules for any of the given subjects.
+ *
+ * Cache policies use this to detect that entity attributes can alter an
+ * authorization decision, which requires bypassing a response cache. Pass
+ * `action` to ignore rules that cannot affect that action; rules for `manage`
+ * always count. A subject list containing `'all'` matches every rule.
+ */
+export declare function hasEntityConditions(ability: AppAbility, subjects: readonly string[], action?: string): boolean;
+//# sourceMappingURL=authorizer.d.ts.map

package/dist/helpers/authorizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorizer.d.ts","sourceRoot":"","sources":["../../src/helpers/authorizer.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,gBAAgB,EAAiB,MAAM,oBAAoB,CAAC;AAG1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8CAA8C,CAAC;AAClF,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGpE,2EAA2E;AAC3E,wBAAgB,cAAc,CAC5B,OAAO,CAAC,EAAE,gBAAgB,GACzB,UAAU,GAAG,SAAS,CAGxB;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAC9B,OAAO,CAAC,EAAE,gBAAgB,GACzB,aAAa,GAAG,SAAS,CAG3B;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAArC,YAA6B,OAAO,CAAC,EAAE,UAAU,YAAA,EAAI;IAErD;;;;;OAKG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAOrE;IAED;;;;OAIG;IACH,SAAS,CACP,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GACzB,IAAI,CAYN;IAED;;;OAGG;IACH,OAAO,CAAC,UAAU,SAAS,MAAM,EAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,EAAE,UAAU,GACpB,SAAS,CAAC,UAAU,CAAC,CAavB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAGxD;IAED,OAAO,CAAC,SAAS;CAgBlB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CA2BT"}

package/dist/helpers/authorizer.js

@@ -0,0 +1,173 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { subject as caslSubject } from '@casl/ability';
+import { pipelineStore } from '@cqrs-ddd/pipeline';
+import { CASL_ABILITY_KEY, CASL_PRINCIPAL_KEY } from '../constants/tokens.js';
+import { UnauthorizedActionException } from '../errors/unauthorized-action.exception.js';
+import { projectPermittedFields } from './projection.js';
+/** The ability `CaslBehavior` built for the current pipeline execution. */
+export function getCaslAbility(context) {
+    const ctx = context ?? pipelineStore.getStore();
+    return ctx?.items.get(CASL_ABILITY_KEY);
+}
+/** The principal that ability was built for; derive security-scoped keys from it. */
+export function getCaslPrincipal(context) {
+    const ctx = context ?? pipelineStore.getStore();
+    return ctx?.items.get(CASL_PRINCIPAL_KEY);
+}
+/**
+ * Entity- and field-level authorization against the request ability.
+ *
+ * Uses the constructor ability, else the ambient ability stored by
+ * `CaslBehavior`. A missing ability denies.
+ *
+ * @example
+ * ```ts
+ * const user = await this.users.findById(command.id);
+ * this.authorizer.authorize('update', user, ['username']);
+ * user.update(command.changes);
+ *
+ * return this.authorizer.project('read', user, { id: user.id, email: user.email });
+ * ```
+ */
+export class CaslAuthorizer {
+    ability;
+    constructor(ability) {
+        this.ability = ability;
+    }
+    /**
+     * True when `action` is permitted on `subject` (and `field`, when given).
+     * Field checks use CASL field matching, unlike {@link project}: a grant of
+     * `fields: ['profile']` does not permit `'profile.secret'`; grant
+     * `'profile.*'` or `'profile.**'` to cover nested fields.
+     */
+    can(action, subject, field) {
+        const ability = this.ability ?? getCaslAbility();
+        if (!ability)
+            return false;
+        const { typedSubject } = resolveSubject(subject);
+        return field
+            ? ability.can(action, typedSubject, field)
+            : ability.can(action, typedSubject);
+    }
+    /**
+     * Throws `UnauthorizedActionException` unless `action` is permitted on
+     * `subject` and every listed field. Fields use CASL field matching, as in
+     * {@link can}.
+     */
+    authorize(action, subject, fields) {
+        const { ability, subjectType, entityId, typedSubject } = this.permitted(action, subject);
+        for (const field of fields ?? []) {
+            if (!ability.can(action, typedSubject, field)) {
+                throw denied(action, subjectType, entityId, ` field "${field}"`, [
+                    field,
+                ]);
+            }
+        }
+    }
+    /**
+     * Asserts `action` on `subject`, then returns the `candidate` fields the
+     * ability permits. Conditions use `subject`, never `candidate`.
+     */
+    project(action, subject, candidate) {
+        if (!candidate || typeof candidate !== 'object') {
+            throw new TypeError('CaslAuthorizer.project() requires a candidate object.');
+        }
+        const { ability, typedSubject } = this.permitted(action, subject);
+        return projectPermittedFields(ability, action, typedSubject, toSnapshot(candidate));
+    }
+    /**
+     * Whether the decision for `action` on `subject` depends on the entity's
+     * attributes: true when a rule for that subject, `all` or `manage` carries
+     * conditions, and when no ability is present. A handler that is about to
+     * decide against a cached or otherwise possibly stale entity reads a fresh
+     * one instead.
+     *
+     * @param action - The action about to be checked, such as `'read'`.
+     * @param subject - The subject type, such as `'User'`.
+     *
+     * @example
+     * ```ts
+     * const refresh = this.authorizer.dependsOnEntity('read', 'User');
+     * const user = await this.users.findById(query.id, { refresh });
+     * return user && this.authorizer.project('read', user, user.toJSON());
+     * ```
+     */
+    dependsOnEntity(action, subject) {
+        const ability = this.ability ?? getCaslAbility();
+        return !ability || hasEntityConditions(ability, [subject], action);
+    }
+    permitted(action, subject) {
+        const ability = this.ability ?? getCaslAbility();
+        const resolved = resolveSubject(subject);
+        if (!ability) {
+            throw denied(action, resolved.subjectType, resolved.entityId, ' (no authorization ability present in context)');
+        }
+        if (!ability.can(action, resolved.typedSubject)) {
+            throw denied(action, resolved.subjectType, resolved.entityId, '');
+        }
+        return { ability, ...resolved };
+    }
+}
+/**
+ * Checks whether an ability contains conditional rules for any of the given subjects.
+ *
+ * Cache policies use this to detect that entity attributes can alter an
+ * authorization decision, which requires bypassing a response cache. Pass
+ * `action` to ignore rules that cannot affect that action; rules for `manage`
+ * always count. A subject list containing `'all'` matches every rule.
+ */
+export function hasEntityConditions(ability, subjects, action) {
+    const wanted = new Set(subjects);
+    const asList = (value) => Array.isArray(value) ? value : [value];
+    return ability.rules.some((rule) => {
+        const conditions = rule.conditions;
+        const conditional = typeof conditions === 'function' ||
+            (typeof conditions === 'object' &&
+                conditions !== null &&
+                Object.keys(conditions).length > 0);
+        if (!conditional)
+            return false;
+        if (action !== undefined &&
+            !asList(rule.action).some((a) => a === action || a === 'manage')) {
+            return false;
+        }
+        return asList(rule.subject).some((s) => typeof s === 'string' &&
+            (s === 'all' || wanted.has('all') || wanted.has(s)));
+    });
+}
+function toSnapshot(value) {
+    return typeof value?.toJSON === 'function'
+        ? value.toJSON()
+        : value;
+}
+function denied(action, subjectType, entityId, detail, fields) {
+    return new UnauthorizedActionException({
+        action,
+        subject: subjectType,
+        entityId,
+        ...(fields ? { fields } : {}),
+        reason: `Access denied: insufficient permissions to ${action} ${subjectType}${detail}.`,
+    });
+}
+function resolveSubject(subject) {
+    if (typeof subject === 'string') {
+        return { subjectType: subject, typedSubject: subject };
+    }
+    // A value tagged by CASL's `subject()` is a plain object whose constructor
+    // is `Object`; its tag is the only reliable subject type.
+    const tagged = subject
+        .__caslSubjectType__;
+    const subjectType = typeof tagged === 'string' && tagged.length > 0
+        ? tagged
+        : subject.constructor?.name && subject.constructor.name !== 'Object'
+            ? subject.constructor.name
+            : 'Object';
+    const record = toSnapshot(subject);
+    const entityId = subject.id ??
+        record?.id;
+    const typedSubject = caslSubject(subjectType, {
+        ...record,
+    });
+    return { subjectType, entityId, typedSubject };
+}
+//# sourceMappingURL=authorizer.js.map

package/dist/helpers/authorizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorizer.js","sourceRoot":"","sources":["../../src/helpers/authorizer.ts"],"names":[],"mappings":"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"}

package/dist/helpers/capability.d.ts

@@ -0,0 +1,80 @@
+import type { Capability, CapabilityString } from '../types/casl.types.js';
+/**
+ * Expand a compact {@link CapabilityString} (e.g. from a JWT or cookie) back
+ * into a structured {@link Capability}.
+ *
+ * This is a **runtime-only deserialisation** step — the inverse of
+ * {@link serializeCapability}.
+ *
+ * Format: `[!]subject|action[|conditions[|fields[|reason]]]`
+ *
+ * - Prefix with `!` to create an inverted (deny) rule
+ * - Use CASL's `all` for any subject and `manage` for any action
+ * - `*` as conditions (or omitted) means no conditions
+ * - `*` as fields (or omitted) means all fields
+ * - Conditions remain readable JSON unless they contain `|`; those values are
+ *   `~`-prefixed base64url JSON so segment parsing stays reversible
+ * - Safe fields are comma-separated: `title,body,status`
+ * - Delimiter-bearing subject/action/fields/reason values are `~`-prefixed
+ *   base64url JSON so every valid capability can round-trip
+ *
+ * @throws {Error} When the subject segment is empty or missing.
+ * @throws {Error} When the action segment is empty or missing.
+ * @throws {Error} When the conditions segment is not a JSON object.
+ *
+ * @example
+ * ```ts
+ * parseCapabilityString('Post|read|*')
+ * // → { subject: 'Post', action: 'read' }
+ *
+ * parseCapabilityString('Post|manage|*')
+ * // → { subject: 'Post', action: 'manage' }
+ *
+ * parseCapabilityString('!Post|delete|*')
+ * // → { subject: 'Post', action: 'delete', inverted: true }
+ *
+ * parseCapabilityString('Post|update|{"authorId":"${user.id}"}|title,body')
+ * // → { subject: 'Post', action: 'update', conditions: { authorId: '${user.id}' }, fields: ['title', 'body'] }
+ *
+ * parseCapabilityString('Post|read|*|title,body,status')
+ * // → { subject: 'Post', action: 'read', fields: ['title', 'body', 'status'] }
+ * ```
+ */
+export declare function parseCapabilityString(cap: CapabilityString): Capability;
+/**
+ * Normalize a capability — whether it arrives as a {@link Capability} object
+ * or as a compact {@link CapabilityString} (for example from a JWT or cookie) —
+ * into a structured {@link Capability}.
+ */
+export declare function normalizeCapability(cap: Capability | CapabilityString): Capability;
+/**
+ * Collapse a {@link Capability} into a compact {@link CapabilityString}
+ * suitable for JWT claims, encrypted cookies, or session stores where payload
+ * size matters.
+ *
+ * This is a **runtime-only serialisation** step — the inverse of
+ * {@link parseCapabilityString}.
+ *
+ * The fields segment is appended when the capability restricts specific
+ * fields, or as `*` when a reason segment follows it; otherwise it is omitted,
+ * keeping the string compact for the common case.
+ *
+ * @example
+ * ```ts
+ * serializeCapability({ subject: 'Post', action: 'manage' })
+ * // → 'Post|manage|*'
+ *
+ * serializeCapability({ subject: 'all', action: 'manage' })
+ * // → 'all|manage|*'
+ *
+ * serializeCapability({ subject: 'Post', action: 'update', fields: ['title', 'body'] })
+ * // → 'Post|update|*|title,body'
+ *
+ * serializeCapability({ subject: 'Post', action: 'update', conditions: { authorId: 42 }, fields: ['title'] })
+ * // → 'Post|update|{"authorId":42}|title'
+ * ```
+ */
+export declare function serializeCapability(cap: Capability): CapabilityString;
+/** True for a non-null object whose prototype is `Object.prototype` or `null`. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+//# sourceMappingURL=capability.d.ts.map

package/dist/helpers/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/helpers/capability.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,gBAAgB,GAAG,UAAU,CA2DvE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,UAAU,GAAG,gBAAgB,GACjC,UAAU,CA4BZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,gBAAgB,CA8BrE;AAiID,kFAAkF;AAClF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMlC"}

package/dist/helpers/capability.js

@@ -0,0 +1,287 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Expand a compact {@link CapabilityString} (e.g. from a JWT or cookie) back
+ * into a structured {@link Capability}.
+ *
+ * This is a **runtime-only deserialisation** step — the inverse of
+ * {@link serializeCapability}.
+ *
+ * Format: `[!]subject|action[|conditions[|fields[|reason]]]`
+ *
+ * - Prefix with `!` to create an inverted (deny) rule
+ * - Use CASL's `all` for any subject and `manage` for any action
+ * - `*` as conditions (or omitted) means no conditions
+ * - `*` as fields (or omitted) means all fields
+ * - Conditions remain readable JSON unless they contain `|`; those values are
+ *   `~`-prefixed base64url JSON so segment parsing stays reversible
+ * - Safe fields are comma-separated: `title,body,status`
+ * - Delimiter-bearing subject/action/fields/reason values are `~`-prefixed
+ *   base64url JSON so every valid capability can round-trip
+ *
+ * @throws {Error} When the subject segment is empty or missing.
+ * @throws {Error} When the action segment is empty or missing.
+ * @throws {Error} When the conditions segment is not a JSON object.
+ *
+ * @example
+ * ```ts
+ * parseCapabilityString('Post|read|*')
+ * // → { subject: 'Post', action: 'read' }
+ *
+ * parseCapabilityString('Post|manage|*')
+ * // → { subject: 'Post', action: 'manage' }
+ *
+ * parseCapabilityString('!Post|delete|*')
+ * // → { subject: 'Post', action: 'delete', inverted: true }
+ *
+ * parseCapabilityString('Post|update|{"authorId":"${user.id}"}|title,body')
+ * // → { subject: 'Post', action: 'update', conditions: { authorId: '${user.id}' }, fields: ['title', 'body'] }
+ *
+ * parseCapabilityString('Post|read|*|title,body,status')
+ * // → { subject: 'Post', action: 'read', fields: ['title', 'body', 'status'] }
+ * ```
+ */
+export function parseCapabilityString(cap) {
+    let str = cap.trim();
+    let inverted = false;
+    if (str.startsWith('!')) {
+        inverted = true;
+        str = str.slice(1);
+    }
+    const parts = str.split('|');
+    if (parts.length > 5) {
+        throw new Error(`Invalid capability string: too many segments in "${cap}"`);
+    }
+    const subject = decodeTextSegment(parts[0], cap, 'subject');
+    const action = decodeTextSegment(parts[1], cap, 'action');
+    if (!subject) {
+        throw new Error(`Invalid capability string: missing subject in "${cap}"`);
+    }
+    if (!action) {
+        throw new Error(`Invalid capability string: missing action in "${cap}"`);
+    }
+    const rawConditions = parts[2];
+    const rawFields = parts[3];
+    const rawReason = parts[4];
+    let conditions;
+    if (rawConditions && rawConditions !== '*') {
+        let parsed;
+        try {
+            const json = rawConditions.startsWith('~')
+                ? Buffer.from(rawConditions.slice(1), 'base64url').toString('utf8')
+                : rawConditions;
+            parsed = JSON.parse(json);
+        }
+        catch {
+            throw new Error(`Invalid conditions JSON in capability string "${cap}": ${rawConditions}`);
+        }
+        if (!isPlainObject(parsed)) {
+            throw new TypeError(`Capability conditions must be a JSON object in "${cap}".`);
+        }
+        conditions = parsed;
+    }
+    const result = { subject, action };
+    if (inverted)
+        result.inverted = true;
+    if (conditions)
+        result.conditions = conditions;
+    if (rawFields && rawFields !== '*') {
+        result.fields = decodeFieldsSegment(rawFields, cap);
+    }
+    if (rawReason !== undefined && rawReason !== '*') {
+        result.reason = decodeTextSegment(rawReason, cap, 'reason');
+    }
+    return result;
+}
+/**
+ * Normalize a capability — whether it arrives as a {@link Capability} object
+ * or as a compact {@link CapabilityString} (for example from a JWT or cookie) —
+ * into a structured {@link Capability}.
+ */
+export function normalizeCapability(cap) {
+    if (typeof cap === 'string')
+        return parseCapabilityString(cap);
+    if (!isPlainObject(cap)) {
+        throw new TypeError('Capability must be an object or compact string.');
+    }
+    if (typeof cap.subject !== 'string' || cap.subject.length === 0) {
+        throw new TypeError('Capability subject must be a non-empty string.');
+    }
+    if (typeof cap.action !== 'string' || cap.action.length === 0) {
+        throw new TypeError('Capability action must be a non-empty string.');
+    }
+    if (cap.conditions !== undefined && !isPlainObject(cap.conditions)) {
+        throw new TypeError('Capability conditions must be a JSON object.');
+    }
+    if (cap.fields !== undefined &&
+        (!Array.isArray(cap.fields) ||
+            cap.fields.some((field) => typeof field !== 'string'))) {
+        throw new TypeError('Capability fields must be an array of strings.');
+    }
+    if (cap.inverted !== undefined && typeof cap.inverted !== 'boolean') {
+        throw new TypeError('Capability inverted must be a boolean.');
+    }
+    if (cap.reason !== undefined && typeof cap.reason !== 'string') {
+        throw new TypeError('Capability reason must be a string.');
+    }
+    return cap;
+}
+/**
+ * Collapse a {@link Capability} into a compact {@link CapabilityString}
+ * suitable for JWT claims, encrypted cookies, or session stores where payload
+ * size matters.
+ *
+ * This is a **runtime-only serialisation** step — the inverse of
+ * {@link parseCapabilityString}.
+ *
+ * The fields segment is appended when the capability restricts specific
+ * fields, or as `*` when a reason segment follows it; otherwise it is omitted,
+ * keeping the string compact for the common case.
+ *
+ * @example
+ * ```ts
+ * serializeCapability({ subject: 'Post', action: 'manage' })
+ * // → 'Post|manage|*'
+ *
+ * serializeCapability({ subject: 'all', action: 'manage' })
+ * // → 'all|manage|*'
+ *
+ * serializeCapability({ subject: 'Post', action: 'update', fields: ['title', 'body'] })
+ * // → 'Post|update|*|title,body'
+ *
+ * serializeCapability({ subject: 'Post', action: 'update', conditions: { authorId: 42 }, fields: ['title'] })
+ * // → 'Post|update|{"authorId":42}|title'
+ * ```
+ */
+export function serializeCapability(cap) {
+    const normalized = normalizeCapability(cap);
+    const prefix = normalized.inverted ? '!' : '';
+    const subject = encodeTextSegment(normalized.subject, true);
+    const action = encodeTextSegment(normalized.action);
+    let conditionsJson;
+    if (normalized.conditions !== undefined) {
+        try {
+            conditionsJson = JSON.stringify(copyJsonConditions(normalized.conditions));
+        }
+        catch {
+            throw new TypeError('Capability conditions must be a JSON object.');
+        }
+    }
+    const conditions = conditionsJson?.includes('|') === true
+        ? `~${Buffer.from(conditionsJson, 'utf8').toString('base64url')}`
+        : (conditionsJson ?? '*');
+    const fields = encodeFieldsSegment(normalized.fields);
+    const reason = normalized.reason !== undefined
+        ? encodeTextSegment(normalized.reason, false, true)
+        : undefined;
+    const base = `${prefix}${subject}|${action}|${conditions}`;
+    if (reason !== undefined)
+        return `${base}|${fields ?? '*'}|${reason}`;
+    return fields !== undefined ? `${base}|${fields}` : base;
+}
+/** Copy only lossless JSON data, without invoking getters or toJSON hooks. */
+function copyJsonConditions(value, ancestors = new WeakSet()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value !== 'object' ||
+        value === null ||
+        (!Array.isArray(value) && !isPlainObject(value)) ||
+        ancestors.has(value)) {
+        throw new TypeError('Unsupported condition value.');
+    }
+    ancestors.add(value);
+    try {
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        const keys = Reflect.ownKeys(descriptors);
+        if (Array.isArray(value)) {
+            // Arrays must have exactly their length property and contiguous indices.
+            if (keys.length !== value.length + 1)
+                throw new TypeError('Lossy condition array.');
+            const result = [];
+            for (let index = 0; index < value.length; index += 1) {
+                const descriptor = descriptors[String(index)];
+                if (!descriptor?.enumerable || !('value' in descriptor)) {
+                    throw new TypeError('Condition arrays must contain only JSON data.');
+                }
+                result.push(copyJsonConditions(descriptor.value, ancestors));
+            }
+            return result;
+        }
+        const result = Object.create(null);
+        for (const key of keys) {
+            if (typeof key !== 'string')
+                throw new TypeError('Symbol condition keys are unsupported.');
+            const descriptor = descriptors[key];
+            if (!descriptor.enumerable || !('value' in descriptor)) {
+                throw new TypeError('Conditions must contain only enumerable JSON data.');
+            }
+            result[key] = copyJsonConditions(descriptor.value, ancestors);
+        }
+        return result;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function encodeTextSegment(value, escapeBang = false, escapeStar = false) {
+    const needsEncoding = value.startsWith('~') ||
+        value.includes('|') ||
+        value.trim() !== value ||
+        (escapeBang && value.startsWith('!')) ||
+        (escapeStar && value === '*');
+    return needsEncoding
+        ? `~${Buffer.from(JSON.stringify(value), 'utf8').toString('base64url')}`
+        : value;
+}
+function decodeTextSegment(value, capability, label) {
+    if (!value?.startsWith('~'))
+        return value ?? '';
+    try {
+        const decoded = JSON.parse(Buffer.from(value.slice(1), 'base64url').toString('utf8'));
+        if (typeof decoded !== 'string')
+            throw new TypeError();
+        return decoded;
+    }
+    catch {
+        throw new Error(`Invalid encoded ${label} in capability string "${capability}".`);
+    }
+}
+function encodeFieldsSegment(fields) {
+    if (fields === undefined)
+        return undefined;
+    const safe = fields.length > 0 &&
+        fields.every((field) => field.length > 0 &&
+            field !== '*' &&
+            !field.startsWith('~') &&
+            !field.includes(',') &&
+            !field.includes('|') &&
+            field.trim() === field);
+    return safe
+        ? fields.join(',')
+        : `~${Buffer.from(JSON.stringify(fields), 'utf8').toString('base64url')}`;
+}
+function decodeFieldsSegment(value, capability) {
+    if (!value.startsWith('~'))
+        return value.split(',');
+    try {
+        const decoded = JSON.parse(Buffer.from(value.slice(1), 'base64url').toString('utf8'));
+        if (!Array.isArray(decoded) ||
+            decoded.some((field) => typeof field !== 'string')) {
+            throw new TypeError();
+        }
+        return decoded;
+    }
+    catch {
+        throw new Error(`Invalid encoded fields in capability string "${capability}".`);
+    }
+}
+/** True for a non-null object whose prototype is `Object.prototype` or `null`. */
+export function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+//# sourceMappingURL=capability.js.map

package/dist/helpers/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../src/helpers/capability.ts"],"names":[],"mappings":"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"}

package/dist/helpers/projection.d.ts

@@ -0,0 +1,11 @@
+import type { AppAbility } from '../types/casl.types.js';
+/**
+ * Projects a snapshot to the fields `ability` permits for `action`. Conditions
+ * are evaluated against the full subject. A granted parent path authorizes its
+ * descendants unless a descendant is explicitly denied; this differs from
+ * `ability.can(action, subject, 'parent.child')`, which needs
+ * `parent.*`/`parent.**`. Denied array elements become `null`. Cyclic input
+ * and more than 1024 path aliases throw.
+ */
+export declare function projectPermittedFields(ability: AppAbility, action: string, typedSubject: string, record: Record<string, unknown> | unknown[]): Record<string, unknown> | unknown[];
+//# sourceMappingURL=projection.d.ts.map