updated Readme.md file

Signed-off-by: Ishan Jogi <ijogi@redhat.com>

Author: ishanjogi89

functions/jwt-parser/1.0.0/README.md

@@ -1,143 +1,162 @@
 # JWT Parser Function
 
-The JWT Parser function allows Serverless Workflow 1.x workflows to parse and extract information from JWT (JSON Web Token) tokens using jq expressions. This function decodes the JWT payload and optionally extracts specific claims.
+A Serverless Workflow 1.x function that decodes JWT (JSON Web Token) payloads using jq expressions. This function provides pure jq-based JWT parsing without external dependencies.
 
-## Overview
+## Technical Implementation
 
-This function uses a `set` task with jq expressions to:
-- Decode JWT tokens (with or without "Bearer " prefix)
-- Extract the complete JWT payload as JSON
-- Optionally extract specific claims using jq paths
+This function implements JWT payload extraction through a `set` task using jq expressions:
+
+**Core JWT Decoding Logic:**
+```jq
+if (.token | startswith("Bearer ")) then
+  (.token[7:] | split(".")[1] | @base64d | fromjson)
+else
+  (.token | split(".")[1] | @base64d | fromjson)
+end
+```
+
+**Technical Steps:**
+1. **Prefix Handling**: Detects and removes "Bearer " prefix if present
+2. **Token Splitting**: Splits JWT on "." to isolate header, payload, signature
+3. **Payload Extraction**: Selects the middle part (index 1) containing claims
+4. **Base64 Decoding**: Uses `@base64d` to decode the base64url payload
+5. **JSON Parsing**: Converts decoded string to JSON object with `fromjson`
+6. **Optional Claim Navigation**: Uses jq path expressions for specific claim extraction
 
 ## Usage
 
-### Basic JWT Parsing (Complete Payload)
+### Complete Payload Extraction
 
 ```yaml
 document:
   dsl: 1.0.0-alpha1
-  namespace: examples
-  name: jwt-parsing
+  namespace: technical
+  name: jwt-full-decode
   version: 1.0.0
 do:
-  - parseToken:
+  - decodeJWT:
       use: jwt-parser
       with:
         token: ${ .headers.authorization }
+        # Returns: { claims: {...}, result: {...} }
 ```
 
-### Extract Specific Claims
+### Specific Claim Extraction
 
 ```yaml
 document:
   dsl: 1.0.0-alpha1
-  namespace: examples  
-  name: jwt-user-extraction
+  namespace: technical
+  name: jwt-claim-extraction
   version: 1.0.0
 do:
-  - extractUsername:
+  - extractSubject:
       use: jwt-parser
       with:
         token: ${ .headers.authorization }
-        claimPath: ".preferred_username"
-  - extractEmail:
+        claimPath: ".sub"
+        # Returns: { claims: {...}, result: "user-id-123" }
+  - extractNestedClaim:
       use: jwt-parser
       with:
         token: ${ .headers.authorization }
-        claimPath: ".email"
+        claimPath: ".custom.department"
+        # Returns: { claims: {...}, result: "engineering" }
 ```
 
-### Multiple Claim Extraction
+### Token Format Handling
 
 ```yaml
 document:
   dsl: 1.0.0-alpha1
-  namespace: examples
-  name: jwt-multi-claims
+  namespace: technical
+  name: jwt-format-handling
   version: 1.0.0
 do:
-  - getUserInfo:
+  - parseRawToken:
       use: jwt-parser
       with:
-        token: ${ .headers["x-authorization-acme_financial_auth"] }
-  - processUserData:
-      use: set
-      set:
-        username: ${ .result.preferred_username }
-        email: ${ .result.email }
-        userId: ${ .result.sub }
-        message: ${ "Welcome " + .username + "! Your request has been processed." }
-```
-
-## Complete Example - Loan Approval with User Personalization
-
-```yaml
-document:
-  dsl: 1.0.0-alpha1
-  namespace: examples
-  name: loan-approval-jwt
-  version: 1.0.0
-do:
-  - extractUserInfo:
+        token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature"
+  - parseBearerToken:
       use: jwt-parser
       with:
-        token: ${ .headers["x-authorization-acme_financial_auth"] }
-  - processLoanApproval:
-      use: set
-      set:
-        user: ${ .result.preferred_username }
-        userId: ${ .result.sub }
-        email: ${ .result.email }
-        loanApproved: true
-        message: ${ "Congrats " + .user + "! Your loan has been approved!" }
+        token: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature"
+        # Both handle the token format automatically
 ```
 
-## Parameters
+## Function Specification
 
+### Input Parameters
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `token` | string | Yes | The JWT token to parse (Bearer prefix will be automatically handled) |
-| `claimPath` | string | No | jq path to extract specific claim (e.g., ".sub", ".preferred_username", ".email") |
-
-## Output
+| `token` | string | Yes | JWT token (raw or with "Bearer " prefix) |
+| `claimPath` | string | No | jq path expression for specific claim extraction |
+
+### Output Structure
+```json
+{
+  "claims": {
+    "sub": "user-123",
+    "preferred_username": "john.doe",
+    "email": "john@example.com",
+    "exp": 1234567890,
+    "iat": 1234567800
+  },
+  "result": "..." // Complete payload or specific claim based on claimPath
+}
+```
 
-The function returns:
-- `claims`: The complete decoded JWT payload as JSON object
-- `result`: Either the complete payload (if no claimPath) or the specific claim value (if claimPath provided)
+## Technical Details
 
-## Token Format Support
+### JWT Token Structure
+```
+header.payload.signature
+```
+The function processes the **payload** section (index 1 after splitting on ".")
 
-The function supports JWT tokens in various formats:
-- Raw JWT token: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
-- Bearer token: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
+### jq Expression Breakdown
 
-## jq Expression Details
+**Primary Expression:**
+```jq
+if (.token | startswith("Bearer ")) then
+  (.token[7:] | split(".")[1] | @base64d | fromjson)
+else
+  (.token | split(".")[1] | @base64d | fromjson)
+end
+```
 
-The function uses these jq expressions:
-- **Token cleanup**: Removes "Bearer " prefix if present
-- **JWT decoding**: Splits token, extracts payload (part 1), base64 decodes, and parses JSON
-- **Claim extraction**: Uses jq path navigation to extract specific claims
+**Claim Path Expression:**
+```jq
+if .claimPath then
+  .claims | getpath(.claimPath | split(".") | map(select(. != "")))
+else
+  .claims
+end
+```
 
-## Common Claim Paths
+### Supported Token Formats
+- **Raw JWT**: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0In0.sig`
+- **Bearer Format**: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0In0.sig`
 
-- `.sub` - Subject (user ID)
-- `.preferred_username` - Username  
-- `.email` - Email address
-- `.name` - Full name
-- `.given_name` - First name
-- `.family_name` - Last name
-- `.roles` - User roles array
-- `.exp` - Expiration timestamp
-- `.iat` - Issued at timestamp
+### Claim Path Examples
+| Path | Description | Example Result |
+|------|-------------|----------------|
+| `.sub` | Subject identifier | `"user-123"` |
+| `.preferred_username` | Username | `"john.doe"` |
+| `.custom.department` | Nested custom claim | `"engineering"` |
+| `.roles[0]` | First role in array | `"admin"` |
 
-## Error Handling
+## Error Conditions
 
-The jq expressions will fail if:
-- Token is null or empty
-- Token format is invalid (not 3 parts separated by dots)
-- JWT payload is not valid base64 or JSON
-- Specified claimPath does not exist
+The function will fail with jq errors if:
+- **Invalid token format**: Not exactly 3 parts separated by dots
+- **Invalid base64**: Payload section cannot be base64 decoded
+- **Invalid JSON**: Decoded payload is not valid JSON
+- **Invalid claim path**: Specified jq path does not exist in payload
 
-## Security Note
+## Implementation Notes
 
-This function extracts claims from JWT tokens without signature verification. In production environments, ensure proper token validation is performed at the API gateway or authentication layer before tokens reach the workflow.
+- **No signature verification**: Function extracts claims without cryptographic validation
+- **Base64URL decoding**: Uses jq's `@base64d` which handles base64url format
+- **Path navigation**: Uses jq's `getpath()` for safe claim extraction
+- **Prefix handling**: Automatically detects and strips "Bearer " prefix