@t4h.framework/jwks 0.3.0 → 0.5.0

package/.ai/skills/framework-jwks/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: framework-jwks
+description: >-
+  JWKS-backed authorization for T4H Framework workflows and apps. Use when
+  importing @t4h.framework/jwks, wiring JWKSAuthorization on Workflow or App,
+  validating RS256 JWTs against a JWKS endpoint, verifying detached signatures
+  with kid/algorithm/signatureFormat, configuring issuer/audience checks, or
+  implementing the @t4h.framework/jwks/authorize runtime handler. Requires
+  @t4h.framework/core. Package path: framework/packages/jwks.
+---
+
+# @t4h.framework/jwks
+
+JWKS-backed **Authorization** for workflows and apps. Exposes `JWKSAuthorization` (core manifest) and a default runtime handler at `@t4h.framework/jwks/authorize` that fetches signing keys from a JWKS URL and verifies credentials.
+
+**Peer dependency:** `@t4h.framework/core` (same major line).
+
+**Node:** `>=22`.
+
+Package path: `framework/packages/jwks`. See [README.md](../../../README.md) for overview (field names below match **source**, not older README examples that mention `value`).
+
+---
+
+## Imports
+
+| Entry | Purpose |
+|-------|---------|
+| `@t4h.framework/jwks` | `JWKSAuthorization`, `JWKSAuthorizationContext`, `JWKSAuthorizationManifest`, `JWKSAlgorithm`, re-exports authorize module |
+| `@t4h.framework/jwks/authorize` | Default async handler: `(context) => Promise<boolean>` |
+
+```typescript
+import {
+  JWKSAuthorization,
+  type JWKSAuthorizationContext,
+  JWKSAlgorithm,
+} from '@t4h.framework/jwks'
+```
+
+Do **not** assume OIDC discovery, env-variable mapping, or `credentialSource` helpers—this package does not read HTTP headers or env. Your app or hosting layer supplies `signature`, `rawPayload`, and `url`.
+
+---
+
+## Wiring authorization (core)
+
+`JWKSAuthorization` extends core `Authorization`. Attach to a **Workflow** or **App**; `toManifest()` registers the handler module for the platform.
+
+```typescript
+import { App, Workflow } from '@t4h.framework/core'
+import { JWKSAuthorization } from '@t4h.framework/jwks'
+
+const authorization = new JWKSAuthorization({
+  url: 'https://auth.example.com/.well-known/jwks.json',
+  signature: '<credential-from-runtime>',
+  rawPayload: '<payload-or-same-as-jwt>',
+  audience: 'https://api.example.com',
+})
+
+const workflow = new Workflow(
+  { id: 'protected/v1', authorization },
+  async () => ({ ok: true }),
+)
+
+const app = new App({
+  id: 'my-app',
+  workflows: [workflow],
+  authorization, // optional app-level default
+})
+```
+
+Manifest shape (from tests):
+
+```typescript
+{
+  pathToModule: '@t4h.framework/jwks/authorize',
+  context: {
+    url: string
+    signature: string
+    rawPayload: string
+    issuer?: string
+    audience?: string
+    kid?: string
+    algorithm?: string
+    signatureFormat?: string
+  },
+}
+```
+
+Optional manifest fields are still present as `undefined` when omitted (`toManifest` copies all keys).
+
+---
+
+## Context: `JWKSAuthorizationContext`
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `url` | Yes | JWKS document URL (`jwks-rsa` `jwksUri`). |
+| `signature` | Yes | Credential to verify: JWT string, or detached signature for non-JWT path. Empty string → handler returns `false`. |
+| `rawPayload` | Yes | Payload bytes as string for non-JWT verification; for JWT path, tests pass the same string as `signature` (handler only uses `signature` on JWT path). |
+| `issuer` | No | When set, passed to `jwt.verify` as expected `iss`. Mismatch **rejects** (throws). |
+| `audience` | No | When set, passed to `jwt.verify` as expected `aud`. |
+| `kid` | Conditional | Required when `signature` is **not** a decodable JWT (non-JWT path). |
+| `algorithm` | Conditional | Non-JWT path: **enum key** on `JWKSAlgorithm` (e.g. `RS256`), not the Node crypto string. |
+| `signatureFormat` | Conditional | Non-JWT path: encoding for the signature buffer (`hex`, `base64`, etc.—`BinaryToTextEncoding`). |
+
+---
+
+## Runtime handler (`@t4h.framework/jwks/authorize`)
+
+Default export:
+
+```typescript
+(options: JWKSAuthorizationContext) => Promise<boolean>
+```
+
+Behavior (from `jwks-authorize.ts` and tests):
+
+1. If `signature` is falsy → **`false`** (no throw).
+2. Build `JwksClient({ jwksUri: options.url })`.
+3. `jwt.decode(signature, { complete: true })`:
+   - **Decoded (JWT path)** → `validateJwt(signature, client, { issuer, audience })`.
+   - **Not decoded (non-JWT path)** → require `kid`, `algorithm`, `signatureFormat`; else **throw** with fixed messages (see below).
+
+### JWT path (`validateJwt`)
+
+- Algorithm must be **RS256** (`decoded.header.alg === 'RS256'`); otherwise **`false`** (e.g. HS256 tokens return `false`, not throw).
+- Header must include **`kid`**; used to `getSigningKey(kid)` from JWKS.
+- **`exp` enforced** (`ignoreExpiration: false`). Expired or wrong signing key → **`jwt.verify` rejects** (promise rejection / throw from handler).
+- Optional `issuer` / `audience` from context applied when present.
+
+### Non-JWT path
+
+Uses Node `crypto.createVerify` with public key from JWKS:
+
+```typescript
+verifier.update(options.rawPayload)
+verifier.verify(signingKey, options.signature, signatureFormat)
+```
+
+Throws if any required field is missing:
+
+| Missing | Error message |
+|---------|----------------|
+| `kid` | `KID is required for payload verification` |
+| `algorithm` | `Algorithm is required for payload verification` |
+| `signatureFormat` | `Signature format is required for payload verification` |
+
+`algorithm` must be a **key** of `JWKSAlgorithm`:
+
+```typescript
+export enum JWKSAlgorithm {
+  RS256 = 'RSA-SHA256',
+  RS384 = 'RSA-SHA384',
+  RS512 = 'RSA-SHA512',
+  PS256 = 'RSA-PSS-SHA256',
+  PS384 = 'RSA-PSS-SHA384',
+  PS512 = 'RSA-PSS-SHA512',
+  ES256 = 'ECDSA-SHA256',
+  ES384 = 'ECDSA-SHA384',
+  ES512 = 'ECDSA-SHA512',
+}
+```
+
+Handler uses `JWKSAlgorithm[algorithm]` as the `createVerify` algorithm name. Pass `algorithm: 'RS256'`, not `'RSA-SHA256'`.
+
+Returns **`true`** on successful verification, **`false`** when verification fails (non-JWT invalid signature).
+
+---
+
+## Examples
+
+### RS256 JWT (typical API Bearer token)
+
+```typescript
+import { JWKSAuthorization } from '@t4h.framework/jwks'
+
+const authorization = new JWKSAuthorization({
+  url: 'https://id.example.com/.well-known/jwks.json',
+  signature: bearerToken, // without "Bearer " prefix if your layer strips it
+  rawPayload: bearerToken,
+  issuer: 'https://issuer.example.com',
+  audience: 'my-api',
+})
+```
+
+Token must be signed RS256 with `kid` in header. Platform invokes `@t4h.framework/jwks/authorize` with manifest `context` when the protected workflow runs.
+
+### Detached signature (non-JWT)
+
+```typescript
+new JWKSAuthorization({
+  url: 'https://id.example.com/jwks',
+  signature: detachedSignatureHex,
+  rawPayload: canonicalPayloadString,
+  kid: 'key-1',
+  algorithm: 'RS256',
+  signatureFormat: 'hex',
+})
+```
+
+If `signature` accidentally looks like a JWT to `jwt.decode`, the JWT path runs instead—structure payloads accordingly.
+
+---
+
+## Return values vs errors
+
+| Situation | Result |
+|-----------|--------|
+| Empty `signature` | `false` |
+| Valid RS256 JWT, matching JWKS key | `true` |
+| JWT wrong alg (e.g. HS256), no `kid`, undecodable token | `false` |
+| Expired JWT, issuer mismatch, signature mismatch | **Rejected** (throw from `jwt.verify`) |
+| Non-JWT missing `kid` / `algorithm` / `signatureFormat` | **Throw** (configuration error) |
+| Non-JWT verify fails | `false` |
+
+Design callers so manifest context is complete **before** the handler runs; missing non-JWT fields are programmer errors, not silent denials.
+
+---
+
+## Testing the handler locally
+
+Unit tests mock `jwks-rsa` and use real RSA key pairs + `jsonwebtoken`:
+
+```typescript
+import jwks from '@t4h.framework/jwks/authorize'
+import jwt from 'jsonwebtoken'
+
+// Valid JWT
+const token = jwt.sign({ sub: 'user-1' }, privateKeyPem, {
+  algorithm: 'RS256',
+  keyid: 'kid-1',
+  expiresIn: '1h',
+})
+
+await expect(
+  jwks({
+    url: 'https://example.com/jwks',
+    signature: token,
+    rawPayload: token,
+  }),
+).resolves.toBe(true)
+```
+
+Test files: `src/__tests__/jwks-authorize.spec.ts`, `src/helpers/__tests__/validateJwt.spec.ts`, `src/models/__tests__/JWKSAuthorization.spec.ts`.
+
+`JWKSAuthorization` tests only assert `toManifest()` shape—handler tests cover verification behavior.
+
+---
+
+## Dependencies (implementation)
+
+- **`jwks-rsa`** — `JwksClient`, `getSigningKey(kid)`, `getPublicKey()`.
+- **`jsonwebtoken`** — decode/verify on JWT path.
+
+---
+
+## What this package does not do
+
+- No built-in OIDC discovery or `JWKS_ISSUER` env mapping.
+- No HTTP header / query / env extraction for credentials.
+- JWT path supports **RS256 only** (not RS384/ES256 via JWT path—those enum values apply to non-JWT `createVerify` only).
+- Does not define **Claims** or **Activities**—only **Authorization** manifests for core `Workflow` / `App`.
+
+For workflow orchestration and claims use **framework-core**; for the `TestWorkflowEnvironment` testing harness use **framework-workflow-testing**.
+
+---
+
+## Quick checklist for agents
+
+1. Add `@t4h.framework/jwks` and peer `@t4h.framework/core`.
+2. Build `JWKSAuthorizationContext` with `url`, `signature`, `rawPayload` at minimum.
+3. Attach `new JWKSAuthorization(context)` to `Workflow` and/or `App` `authorization` option.
+4. JWT: ensure RS256 + `kid`; optional `issuer` / `audience`.
+5. Non-JWT: set `kid`, `algorithm` (`JWKSAlgorithm` key), `signatureFormat`.
+6. Expect `false` for deny, throws for misconfiguration or JWT verify failures (expired, wrong iss).
+7. Do not reference APIs absent from `src/` and tests.

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @t4h.framework/jwks
+
+## 0.5.0
+
+### Minor Changes
+
+- Updated dependencies [[`8098041`](https://github.com/tech4humans-brasil/framework/commit/80980419d59a987378b7c94372ee2f7b7dcc00f5)]:
+  - @t4h.framework/core@0.10.0
+
+## 0.4.0
+
+### Patch Changes
+
+- Update skills ([`6d7e7bc`](https://github.com/tech4humans-brasil/framework/commit/6d7e7bca0c780a9c53a0c9e5aa0a865c5af67959))
+
+## 0.3.0
+
+### Minor Changes
+
+- Implements jwks package ([#52](https://github.com/tech4humans-brasil/framework/pull/52))
+- Adds .ai/skills in packages ([#88](https://github.com/tech4humans-brasil/framework/pull/88))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/jwks",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "JWKS module for the T4H Framework authorization",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/jwks",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -26,7 +26,8 @@
   "types": "./dist/jwks.d.ts",
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    ".ai"
   ],
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
@@ -36,13 +37,13 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.3.0",
+    "@t4h.framework/core": "^0.10.0",
     "@types/jsonwebtoken": "^9",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.3.0"
+    "@t4h.framework/core": "^0.10.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {