@t4h.framework/jwks 0.7.7 → 0.7.8

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

@@ -1,267 +1,108 @@
 ---
 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.
+  Verifies RS256 JWTs and detached public-key signatures against a JWKS
+  endpoint with @t4h.framework/jwks. Use when a T4H Framework workflow or App
+  needs JWKSAuthorization, when an async activity such as webhook() declares
+  auth { type: 'jwt' } or auth { type: 'jwks' } for its callbacks, or when the
+  user mentions a JWKS URL, .well-known/jwks.json, kid, issuer, audience,
+  JWKSAlgorithm, a bearer JWT (Google Pub/Sub push, Cloud Tasks) or a signature
+  verified with a key published in a 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.
+The package has two uses. Pick the one that matches the task:
 
-**Peer dependency:** `@t4h.framework/core` (same major line).
+- **Protect a workflow or an `App`**: `new JWKSAuthorization(context)`.
+- **Verify the callbacks of an async activity**: declare
+  `auth: { type: 'jwt', … }` or `auth: { type: 'jwks', … }` on the activity
+  (for `webhook()`, see the **framework-webhook** skill). The host verifies
+  each callback with `@t4h.framework/jwks/callback`. You do not import it.
 
-**Node:** `>=22`.
+## Protect a workflow or an App
 
-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>` |
-| `@t4h.framework/jwks/callback` | Default export `jwksCallback`: `(auth, delivery) => Promise<boolean>`, the authorizer hosts pass to the core `AsyncActivityCallback.authorize` for `jwt` (bearer JWT) and `jwks` (detached signature over the body, key resolved by `kid` from a JWKS URL) |
-
-```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.
+The handler picks the path from `signature`: a value that decodes as a JWT
+takes the JWT path, any other value takes the raw-payload path.
 
 ```typescript
-import { App, Workflow } from '@t4h.framework/core'
 import { JWKSAuthorization } from '@t4h.framework/jwks'
 
-const authorization = new JWKSAuthorization({
+export const authorization = new JWKSAuthorization({
   url: 'https://auth.example.com/.well-known/jwks.json',
-  signature: '<credential-from-runtime>',
-  rawPayload: '<payload-or-same-as-jwt>',
+  signature: '<jwt-from-the-request>',
+  rawPayload: '',
+  issuer: 'https://auth.example.com/',
   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` | Non-JWT path | Key id to look up in the JWKS. Used when `signature` is **not** a decodable JWT. |
-| `algorithm` | Non-JWT path | **Enum key** on `JWKSAlgorithm` (e.g. `RS256`), not the Node crypto string. |
-| `signatureFormat` | 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)** → verify the detached signature with `kid`, `algorithm` and `signatureFormat`.
-
-### 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
-authorizer.update(options.rawPayload)
-authorizer.verify(signingKey, options.signature, signatureFormat)
 ```
 
-A missing `kid`, `algorithm` or `signatureFormat` throws (`jwks-authorize.ts`).
+Attach it to the `authorization` option of a `Workflow` or an `App`. For a
+detached signature, give the signed bytes in `rawPayload` and set `kid`,
+`algorithm` and `signatureFormat`.
 
-`algorithm` must be a **key** of `JWKSAlgorithm`:
+## Verify async activity callbacks
 
 ```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',
+auth: {
+  type: ('jwt', jwksUri, issuer, audience)
 }
 ```
 
-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 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, {
+auth: {
+  type: 'jwks',
+  jwksUri: 'https://partner.example.com/.well-known/jwks.json',
+  header: 'x-signature',
+  kidHeader: 'x-key-id',
   algorithm: 'RS256',
-  keyid: 'kid-1',
-  expiresIn: '1h',
-})
-
-await expect(
-  jwks({
-    url: 'https://example.com/jwks',
-    signature: token,
-    rawPayload: token,
-  }),
-).resolves.toBe(true)
+  signatureFormat: 'base64',
+  timestampHeader: 'x-timestamp',
+  toleranceInSeconds: 300,
+  signedPayload: '{timestamp}.{body}',
+}
 ```
 
-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. Expect `false` for deny, throws for misconfiguration or JWT verify failures (expired, wrong iss).
+On `jwks`, each of `kid`, `algorithm` and `signatureFormat` is a fixed value or
+a `*Header` name. A fixed value wins. `signatureFormat` defaults to `'hex'`.
+
+## Traps
+
+- The field is `signature`. There is no `value` field.
+- The JWT path accepts only RS256 tokens with a `kid` in the header. HS256 or
+  ES256 tokens give `false`.
+- On the JWT path `rawPayload` is not used. Pass `''`.
+- `algorithm` is a `JWKSAlgorithm` KEY such as `'RS256'`, not the Node name
+  `'RSA-SHA256'`. Today only `RS256`, `RS384` and `RS512` verify; the `PS*` and
+  `ES*` keys throw `Invalid digest`.
+- A detached signature that happens to decode as a JWT takes the JWT path.
+- `JWKSAuthorization`: a denied raw-payload signature gives `false`, but an
+  expired JWT, an `issuer` or `audience` mismatch, a bad JWT signature or a
+  missing `kid`/`algorithm`/`signatureFormat` THROWS. On a callback each error
+  becomes a refusal.
+- Always set `issuer` and `audience` for a JWT. Without them a token minted for
+  another service passes.
+- Callback timestamps: all digits with 13 or more digits are milliseconds,
+  fewer are seconds. Other strings go through `Date.parse`.
+- The package does not read HTTP headers or env, and has no OIDC discovery. For
+  a token from an OIDC provider, see **framework-oidc**.
+
+## Test
+
+The handler fetches keys over HTTP from `url`. Serve a JWKS from a local HTTP
+server in the test (export the public key with
+`publicKey.export({ format: 'jwk' })` and add `kid`), sign a token with
+`jsonwebtoken` (`algorithm: 'RS256'`, `keyid`), and call the default export of
+`@t4h.framework/jwks/authorize`.
+
+## Related skills
+
+- **framework-hmac**: shared-secret signatures.
+- **framework-webhook**: wait for a partner callback that uses this `auth`.
+
+## Reference
+
+- Guide: <https://tech4humans-brasil.github.io/framework/jwks/>
+- Types: `node_modules/@t4h.framework/jwks/dist/jwks.d.ts`
+- Callback `auth` types: `AsyncActivityCallbackAuthJwt` and
+  `AsyncActivityCallbackAuthJwks` in `node_modules/@t4h.framework/core/dist/`

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @t4h.framework/jwks
 
+## 0.7.8
+
+### Patch Changes
+
+- [#257](https://github.com/tech4humans-brasil/framework/pull/257) [`586bfb4`](https://github.com/tech4humans-brasil/framework/commit/586bfb4663f4a478527ee0c8db360603f034d615) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The jwks README is now short and links to the site. The site page now describes the `jwt` and `jwks` callback `auth`, the results and errors, and says that only the `RS*` keys verify a detached signature.
+
 ## 0.7.7
 
 ### Patch Changes

package/README.md

@@ -1,76 +1,31 @@
 # @t4h.framework/jwks
 
-JWKS-backed authorization for the T4H Framework. It exposes a core `Authorization` manifest and a runtime handler that validates credentials against keys from a JWKS endpoint.
+JWKS authorization for the T4H Framework. It verifies an RS256 JWT, or a
+detached signature over a raw payload, against the public keys of a JWKS
+endpoint, for a workflow, an app or the callbacks of an async activity.
 
-## Peer dependency
+## Install
 
-Requires `@t4h.framework/core` (same major line as this package).
-
-## Exports
-
-| Entry            | Purpose |
-|------------------|---------|
-| `@t4h.framework/jwks` | `JWKSAuthorization`, `JWKSAuthorizationContext`, and related types |
-| `@t4h.framework/jwks/authorize` | Default async handler invoked by the runtime with the manifest context |
-| `@t4h.framework/jwks/callback` | Default export `jwksCallback`: the `jwt` (bearer JWT) and `jwks` (detached signature verified with a JWKS key) callback authorizer for the core `AsyncActivityCallback.authorize` |
-
-## `JWKSAuthorization`
-
-Subclass of [`Authorization`](https://github.com/tech4humans-brasil/framework/tree/main/packages/core) from core. `toManifest()` points the runtime at `@t4h.framework/jwks/authorize` and passes a `JWKSAuthorizationContext`.
-
-Construct it with a full `JWKSAuthorizationContext`. `url`, `signature` and `rawPayload` are required. Your app or deployment pipeline supplies `signature` and `rawPayload`, for example from a request header or by runtime injection. This package does not read HTTP or env.
-
-## Context: `JWKSAuthorizationContext`
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `url` | Yes | JWKS document URL (`jwks-rsa` `jwksUri`). |
-| `signature` | Yes | Credential to verify: a JWT, or a detached signature for the non-JWT path. An empty string gives `false`. |
-| `rawPayload` | Yes | The signed payload for the non-JWT path. The JWT path does not use it; pass an empty string. |
-| `issuer` | No | JWT path: the expected `iss`. |
-| `audience` | No | JWT path: the expected `aud`. |
-| `kid` | Non-JWT path | Key id to find in the JWKS. Required when `signature` is **not** a JWT that decodes. |
-| `algorithm` | Non-JWT path | A key of `JWKSAlgorithm` (`RS256`, `PS256`, `ES256`, …). |
-| `signatureFormat` | Non-JWT path | Encoding of `signature` (`hex`, `base64`, …). |
-
-There is no OIDC discovery (`JWKS_ISSUER`), no environment-variable mapping in this package, and no `credentialSource` helper. Your application or hosting layer gives `signature` and `rawPayload`.
-
-## Runtime handler (`jwks/authorize`)
-
-The default export is an async function:
-
-```ts
-(options: JWKSAuthorizationContext) => Promise<boolean>
+```bash
+npm install @t4h.framework/jwks @t4h.framework/core
 ```
 
-- Returns `false` if `signature` is empty.
-- Returns `true` if verification succeeds.
-
-### JWT path
-
-If `signature` decodes as a JWT (`jsonwebtoken` `decode` with `complete: true` succeeds), the handler verifies it with `validateJwt` ([source](https://github.com/tech4humans-brasil/framework/blob/main/packages/jwks/src/helpers/validateJwt.ts)):
-
-- The algorithm must be **RS256**. A different `alg` in the header gives `false`.
-- The header must have a `kid`, which selects the signing key in the JWKS. No `kid` gives `false`.
-- `exp` is enforced.
-- `issuer` and `audience` from the context apply when you set them.
-- An expired token, an `issuer` or `audience` mismatch, or a bad signature makes `jwt.verify` throw, so the handler throws.
-
-### Non-JWT path
-
-If `signature` does not decode as a JWT, the handler needs `kid`, `algorithm` and `signatureFormat` on the context. If one of them is missing, it **throws**. It gets the public key from the JWKS by `kid`, and verifies `signature` over `rawPayload` with Node `crypto.createVerify`. A signature that does not match gives `false`.
-
-## Example
+## Usage
 
 ```typescript
 import { JWKSAuthorization } from '@t4h.framework/jwks'
 
 const authorization = new JWKSAuthorization({
   url: 'https://auth.example.com/.well-known/jwks.json',
-  signature: '<credential-from-runtime>',
+  signature: '<jwt-from-the-request>',
   rawPayload: '',
+  issuer: 'https://auth.example.com/',
   audience: 'https://api.example.com',
 })
 ```
 
-Wire `authorization` on an `App` or `Workflow` per the core package. The platform loads `@t4h.framework/jwks/authorize` with the manifest context when a protected workflow runs.
+Attach `authorization` to a `Workflow` or an `App`.
+
+## Documentation
+
+<https://tech4humans-brasil.github.io/framework/jwks/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/jwks",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "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",
@@ -43,7 +43,7 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.20.0",
+    "@t4h.framework/core": "^0.21.0",
     "@types/jsonwebtoken": "^9",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"