parseCapabilityString

parseCapabilityString(cap): Capability

Defined in: packages/pipeline-casl/src/helpers/capability.ts:46

Expand a compact CapabilityString (e.g. from a JWT or cookie) back into a structured Capability.

This is a runtime-only deserialisation step — the inverse of 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

Parameters

cap

string

Returns

Capability

Throws

When the subject segment is empty or missing.

Throws

When the action segment is empty or missing.

Throws

When the conditions segment is not a JSON object.

Example

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'] }