@t4h.framework/oidc 0.6.11 → 0.6.12

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

@@ -1,272 +1,88 @@
 ---
 name: framework-oidc
 description: >-
-  Wire OpenID Connect authorization in T4H Framework apps and workflows using
-  @t4h.framework/oidc: OIDCAuthorization manifest, OIDCAuthorizationContext,
-  RFC 7662 bearer token introspection with client_secret_basic, and
-  discoveryUrl. Use when securing App/Workflow with OIDC, token
-  validation, OpenID Provider discovery, introspection_endpoint, attaching
-  authorization to manifests, or testing @t4h.framework/oidc/authorize.
+  Protects a T4H Framework App or Workflow with OpenID Connect using
+  @t4h.framework/oidc: `OIDCAuthorization` with `discoveryUrl`, `clientId`,
+  `clientSecret` and a `token` placeholder such as
+  '<<headers.authorization>>', checked by RFC 7662 token introspection with
+  client_secret_basic. Use when an app or workflow must run only for callers
+  with an active access token from an OpenID Provider (Keycloak, Auth0,
+  Zitadel), when setting the `authorization` option, or when testing
+  `@t4h.framework/oidc/authorize`.
 ---
 
 # @t4h.framework/oidc
 
-OpenID Connect–oriented **authorization** for the T4H Framework. This package does **not** define Activities or Claims; it extends core’s `Authorization` and supplies a runtime handler that validates an incoming credential via **token introspection** (**RFC 7662**), authenticating that call with **`client_secret_basic`**.
-
-Package path: `framework/packages/oidc`. Peer dependency: `@t4h.framework/core` (same major line). Node `>=22`.
-
-For workflow Activities, Claims, and `History.reconciler`, use the **framework-core** skill. OIDC only gates access at the App/Workflow authorization layer.
-
----
-
-## Imports
-
-| Entry | Import | Purpose |
-|--------|--------|---------|
-| `@t4h.framework/oidc` | `OIDCAuthorization`, `OIDCAuthorizationContext`, `OIDCAuthorizationManifest` | Author-time manifest |
-| `@t4h.framework/oidc/authorize` | default `oidc` handler | Runtime/tests only — `(context) => Promise<boolean>` |
-
-```typescript
-import { OIDCAuthorization } from '@t4h.framework/oidc'
-import type { OIDCAuthorizationContext } from '@t4h.framework/oidc'
-
-// Direct handler import (unit tests, custom runtime wiring):
-import oidc from '@t4h.framework/oidc/authorize'
-```
-
----
-
-## Where it fits (core `Authorization`)
-
-Core exposes an abstract `Authorization` with `toManifest(): AuthorizationManifest`:
-
-```typescript
-type AuthorizationManifest<TContext extends object = any> = {
-  context?: TContext
-  pathToModule: string
-}
-```
-
-Attach `OIDCAuthorization` on **`App`** or **`Workflow`** options; `toManifest()` embeds `authorization` in the published manifest. The deployed runtime resolves dynamic fields (especially `token`), then loads `@t4h.framework/oidc/authorize` with the manifest `context`.
-
-Declare the values in the `EnvDesign` in `src/constants/environments.ts`. The context types `clientSecret` as `string`, so declare the entry with `type: String`, not `type: Secret`. This is an exception to the `type: Secret` rule of **framework-core**.
-
-```typescript
-// src/constants/environments.ts
-import { EnvDesign } from '@t4h.framework/core'
-
-export const environments = EnvDesign({
-  OIDC_DISCOVERY_URL: { type: String },
-  OIDC_CLIENT: { type: String },
-  OIDC_SECRET: { type: String },
-})
-```
-
-```typescript
-import { App } from '@t4h.framework/core'
-import { OIDCAuthorization } from '@t4h.framework/oidc'
-
-import { environments } from './constants/environments.js'
-
-export default new App({
-  id: 'my-app',
-  authorization: new OIDCAuthorization({
-    discoveryUrl: environments.OIDC_DISCOVERY_URL,
-    clientId: environments.OIDC_CLIENT,
-    clientSecret: environments.OIDC_SECRET,
-    token: '<<headers.authorization>>',
-  }),
-  workflows: [/* ... */],
-})
-```
-
-Per-workflow override:
-
-```typescript
-import { Workflow } from '@t4h.framework/core'
-import { OIDCAuthorization } from '@t4h.framework/oidc'
-
-const secured = new Workflow(
-  {
-    id: 'orders/v1',
-    authorization: new OIDCAuthorization({ /* same context shape */ }),
-  },
-  async input => ({ ok: true }),
-)
-```
-
-**App-level vs workflow-level:** set on whichever manifest should enforce OIDC. Workflow `authorization` in `toManifest()` is `authorization?.toManifest() ?? null`; App forwards `authorization?.toManifest()` at app scope.
-
----
-
-## `OIDCAuthorization`
-
-Subclass of `Authorization<OIDCAuthorizationContext>`. Constructor stores context; `toManifest()` always sets:
-
-- `pathToModule: '@t4h.framework/oidc/authorize'`
-- `context`: full context object (`discoveryUrl`, `clientId`, `clientSecret`, `token`)
-
-```typescript
-new OIDCAuthorization({
-  discoveryUrl: environments.OIDC_DISCOVERY_URL,
-  clientId: environments.OIDC_CLIENT,
-  clientSecret: environments.OIDC_SECRET,
-  token: '<<headers.authorization>>',
-})
-```
-
-The package does not read env. `@t4h.framework/core/no-literal-secret-in-authorization` rejects a literal `clientSecret`. Pass `discoveryUrl`, `clientSecret` and the other values from the `EnvDesign` when you construct the instance.
-
-### Runtime token placeholder
-
-`token` is authored as a manifest placeholder the runtime replaces:
-
-```typescript
-token: '<<headers.authorization>>',
-```
-
-Author with whatever placeholder or value your deployment pipeline documents; the handler always receives the resolved string at runtime.
-
----
-
-## `OIDCAuthorizationContext`
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `discoveryUrl` | Yes | OpenID Provider configuration document URL (JSON with `introspection_endpoint`). |
-| `clientId` | Yes | OAuth 2.0 client id used as the Basic username on introspection. |
-| `clientSecret` | Yes | OAuth 2.0 client secret used as the Basic password on introspection. |
-| `token` | Yes | Credential to verify. Must use a `Bearer ` prefix for the token value to be sent to introspection (see below). |
-
-Types exported: `OIDCAuthorizationContext`, `OIDCAuthorizationManifest` (`AuthorizationManifest<OIDCAuthorizationContext>`).
-
----
-
-## Runtime handler (`@t4h.framework/oidc/authorize`)
-
-Default export: async function `(context: OIDCAuthorizationContext) => Promise<boolean>`.
-
-### Flow
-
-```mermaid
-sequenceDiagram
-  participant R as Runtime handler
-  participant D as discoveryUrl
-  participant I as introspection_endpoint
-
-  R->>D: GET discovery JSON
-  R->>I: POST form { token, token_type_hint } + Basic client credentials
-  I-->>R: { active }
-  R-->>R: true if active else false
-```
-
-1. **Discovery** — `GET` `discoveryUrl`; parse JSON as `{ introspection_endpoint }`. Non-OK HTTP → throw `Discovery request failed: <status> <statusText>`.
-2. **Introspection** — `POST` `introspection_endpoint` per **RFC 7662** with:
-   - `Content-Type: application/x-www-form-urlencoded`
-   - `Accept: application/json`
-   - `Authorization: Basic base64(<form-urlencoded clientId>:<form-urlencoded clientSecret>)` (`client_secret_basic`, RFC 6749 section 2.3.1)
-   - body `URLSearchParams` with `token=<stripped incoming token>` and `token_type_hint=access_token`
-   Non-OK HTTP → throw `Introspection request failed: ...`.
-3. **Result** — parse the RFC 7662 response (`active` plus optional `scope`, `client_id`, `exp`, `sub`, `aud`, …):
-   - `active: true` → return `true`
-   - anything else, including a missing `active` → return `false`
-
-Network failures from `fetch` propagate as rejected promises (not converted to `false`).
-
-### Bearer prefix rules
-
-Incoming `token` is parsed as an RFC 6750 bearer credential (scheme matched case-insensitively):
-
-- `Bearer <token>` → introspection sends the token value (e.g. `Bearer abc.def` → `token=abc.def`).
-- Anything else → the handler returns `false` immediately, with **no** discovery, token or introspection request (`token` is a required RFC 7662 parameter).
-
-Always author/runtime-resolve credentials as `Bearer <access-token>` when you expect introspection of the caller’s token.
-
----
-
-## Authoring checklist
-
-1. Add `@t4h.framework/oidc` dependency alongside `@t4h.framework/core`.
-2. Construct `new OIDCAuthorization({ discoveryUrl, clientId, clientSecret, token, ... })`.
-3. Attach to `App` and/or `Workflow` `authorization` option.
-4. Register a confidential OAuth client allowed to call **introspection** with **`client_secret_basic`**.
-5. Pass incoming caller token with `Bearer ` prefix (or use a runtime placeholder like `<<headers.authorization>>`).
-
----
-
-## Testing
-
-Package tests use **Vitest** with `vi.stubGlobal('fetch', ...)`.
-
-### `OIDCAuthorization.toManifest()`
-
-Assert manifest shape:
-
-```typescript
-expect(authorization.toManifest()).toEqual({
-  pathToModule: '@t4h.framework/oidc/authorize',
-  context: {
-    discoveryUrl: '...',
-    clientId: 'svc',
-    clientSecret: 'secret',
-    token: 'Bearer t',
-  },
-})
-```
-
-### Handler (`import oidc from '@t4h.framework/oidc/authorize'`)
-
-Mock two `fetch` calls in order: discovery → introspection.
-
-```typescript
-const baseContext = {
-  discoveryUrl: 'https://auth.example.com/.well-known/openid-configuration',
-  clientId: 'client-id',
-  clientSecret: 'client-secret',
-  token: 'Bearer incoming-token',
-}
-
-// Happy path: true
-fetchMock
-  .mockResolvedValueOnce(jsonResponse({
-    introspection_endpoint: 'https://auth.example.com/oauth/introspect',
-  }))
-  .mockResolvedValueOnce(jsonResponse({ active: true }))
-
-await expect(oidc(baseContext)).resolves.toBe(true)
-```
-
-Verify wire format from tests:
-
-- Introspection: `Authorization: Basic <base64 client-id:client-secret>`, form body `token=incoming-token&token_type_hint=access_token` after stripping `Bearer `.
-- Missing Bearer prefix: resolves `false` with `fetch` never called.
-- Inactive token: second response `{ active: false }` → `false`; a response without `active` also yields `false`.
-- HTTP errors on discovery/introspection: thrown `Error` messages as documented above.
-
-Run package tests: `yarn test` in `packages/oidc`.
-
-Workflow-level authorization behavior in process is owned by the **runtime** (outside this package); this package only defines manifest + handler contract.
-
----
-
-## Common mistakes
-
-| Mistake | Consequence |
-|---------|-------------|
-| Raw JWT without `Bearer ` prefix | Denied up front; no provider request is made |
-| Expecting env auto-wiring | Secrets/URLs must be set when constructing `OIDCAuthorization` |
-| Missing `introspection_endpoint` on IdP | The handler throws `Discovery response has no introspection_endpoint` (`oidc-authorize.ts`) |
-| Treating `false` as HTTP error | `false` means inactive token; errors are thrown separately |
-
----
-
-## API summary
-
-| Symbol | Kind | Role |
-|--------|------|------|
-| `OIDCAuthorization` | class | `Authorization` subclass; `toManifest()` → oidc authorize module |
-| `OIDCAuthorizationContext` | type | Manifest/runtime context |
-| `OIDCAuthorizationManifest` | type | `AuthorizationManifest<OIDCAuthorizationContext>` |
-| default `oidc` | function | `@t4h.framework/oidc/authorize` — discovery + RFC 7662 introspection |
-
-See [README.md](../../../README.md) in this package for the same behavior described for humans.
+`OIDCAuthorization` gates the incoming call of an `App` or a `Workflow`. Before
+the run starts, the check reads the discovery document, sends the caller's
+token to the provider's `introspection_endpoint`, and allows the run only when
+the response has `"active": true`.
+
+This package does not authenticate outgoing calls. To call an API with an
+OAuth2 token, use the **framework-http** skill. To check a JWT locally against
+the provider's keys, with no introspection call, use the **framework-jwks**
+skill.
+
+## Protect an app or a workflow
+
+1. Declare the values in the `EnvDesign` in `src/constants/environments.ts`.
+   Use `type: String` for the secret: `clientSecret` is a `string`, not a
+   `Secret`.
+
+   ```typescript
+   export const environments = EnvDesign({
+     OIDC_DISCOVERY_URL: { type: String },
+     OIDC_CLIENT: { type: String },
+     OIDC_SECRET: { type: String },
+   })
+   ```
+
+2. Set `authorization` on the `App` (all its workflows) or on one `Workflow`:
+
+   ```typescript
+   import { OIDCAuthorization } from '@t4h.framework/oidc'
+
+   const authorization = new OIDCAuthorization({
+     discoveryUrl: environments.OIDC_DISCOVERY_URL,
+     clientId: environments.OIDC_CLIENT,
+     clientSecret: environments.OIDC_SECRET,
+     token: '<<headers.authorization>>',
+   })
+
+   export default new App({
+     id: 'my-app',
+     workflows: [cashback],
+     authorization,
+   })
+   ```
+
+## Traps
+
+- `token` is a placeholder, not a value. The runtime replaces
+  `<<headers.authorization>>` with the `Authorization` header of the incoming
+  request before the check runs.
+- The token must be `Bearer <token>` (any letter case, no spaces in the
+  token). Any other form is denied without a call to the provider.
+- `@t4h.framework/core/no-literal-secret-in-authorization` rejects a literal
+  `clientSecret`. The package reads no env by itself: pass each value from the
+  `EnvDesign`.
+- `discoveryUrl` is the well-known document
+  (`.../.well-known/openid-configuration`), not the introspection endpoint.
+- The provider must let the client call introspection with
+  `client_secret_basic`.
+- `false` means "denied". An HTTP error from the provider, a missing
+  `introspection_endpoint` or a network failure throws instead.
+
+## Test
+
+- `OIDCAuthorization`: compare `toManifest()` with
+  `{ pathToModule: '@t4h.framework/oidc/authorize', context: { ... } }`.
+- The check: `import oidc from '@t4h.framework/oidc/authorize'`, stub the
+  global `fetch` with `vi.stubGlobal`, and resolve it two times in order:
+  the discovery document, then the introspection response.
+
+## Reference
+
+- Guide, errors and testing: https://tech4humans-brasil.github.io/framework/oidc/
+- Types: `node_modules/@t4h.framework/oidc/dist/oidc.d.ts` and
+  `node_modules/@t4h.framework/oidc/dist/oidc-authorize.d.ts`

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @t4h.framework/oidc
 
+## 0.6.12
+
+### 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 oidc docs now describe the errors of the check and how to test it, and no longer say that it uses the client credentials grant. The README is short and the skill keeps only the traps and links to the site.
+
 ## 0.6.11
 
 ### Patch Changes

package/README.md

@@ -1,81 +1,38 @@
 # @t4h.framework/oidc
 
-OpenID Connect–oriented authorization for the T4H Framework. It exposes a core `Authorization` manifest and a runtime handler that validates an incoming credential through the **token introspection** endpoint ([RFC 7662](https://www.rfc-editor.org/rfc/rfc7662)) from the issuer’s OpenID configuration.
+OpenID Connect authorization for T4H Framework apps and workflows. It lets a
+run start only when the OpenID Provider reports the caller's token as active,
+through token introspection ([RFC 7662](https://www.rfc-editor.org/rfc/rfc7662)).
 
-## Peer dependency
+## Install
 
-Requires `@t4h.framework/core` (same major line as this package).
-
-## Exports
-
-| Entry | Purpose |
-|--------|---------|
-| `@t4h.framework/oidc` | `OIDCAuthorization`, `OIDCAuthorizationContext`, and related types |
-| `@t4h.framework/oidc/authorize` | Default async handler invoked by the runtime with the manifest context |
-
-## `OIDCAuthorization`
-
-Subclass of [`Authorization`](https://github.com/tech4humans-brasil/framework/tree/main/packages/core) from core. `toManifest()` points the runtime at `@t4h.framework/oidc/authorize` and passes an `OIDCAuthorizationContext`.
-
-You construct it with a context object; your app or hosting layer is responsible for supplying the credential string (`token`) when the workflow runs.
-
-## Context: `OIDCAuthorizationContext`
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `discoveryUrl` | Yes | OpenID Provider configuration document URL (must return JSON with at least `introspection_endpoint`). |
-| `clientId` | Yes | OAuth 2.0 client identifier used to authenticate the introspection call. |
-| `clientSecret` | Yes | OAuth 2.0 client secret used to authenticate the introspection call. |
-| `token` | Yes | Credential to verify. Must use a `Bearer ` prefix (see below). |
-
-## Runtime handler (`oidc/authorize`)
-
-The default export is an async function:
-
-```ts
-(context: OIDCAuthorizationContext) => Promise<boolean>
+```bash
+npm install @t4h.framework/oidc
 ```
 
-Behavior:
-
-1. **Discovery** — `GET` `discoveryUrl` and read JSON with `introspection_endpoint`.
-2. **Introspection** — `POST` the introspection endpoint following [RFC 7662](https://www.rfc-editor.org/rfc/rfc7662), with `token` and `token_type_hint=access_token` as `application/x-www-form-urlencoded`, where `token` is taken from the context `token` after stripping the `Bearer ` prefix (the scheme is matched case-insensitively).
-3. **Client authentication** — RFC 7662 requires the caller to authorize itself; the handler uses `client_secret_basic` (RFC 6749 section 2.3.1), sending `Authorization: Basic base64(clientId:clientSecret)` with both values form-urlencoded. Your client must be allowed to call introspection with this method.
+Peer dependency: `@t4h.framework/core`.
 
-Result:
-
-- Returns `true` only if the introspection response includes `"active": true`.
-- Returns `false` for any other response, including a missing `active` member.
-- If the incoming credential does not carry a `Bearer ` prefix, the handler returns `false` without contacting the provider — `token` is a required introspection parameter.
-
-There is no built-in mapping from environment variables; all configuration comes from the manifest context.
-
-## Example
-
-Declare the values in the `EnvDesign` in `src/constants/environments.ts`. The context types `clientSecret` as `string`, so declare the entry with `type: String`, not `type: Secret`.
-
-```typescript
-// src/constants/environments.ts
-import { EnvDesign } from '@t4h.framework/core'
-
-export const environments = EnvDesign({
-  OIDC_DISCOVERY_URL: { type: String },
-  OIDC_CLIENT: { type: String },
-  OIDC_SECRET: { type: String },
-})
-```
+## Usage
 
 ```typescript
+import { App } from '@t4h.framework/core'
 import { OIDCAuthorization } from '@t4h.framework/oidc'
 
 import { environments } from './constants/environments.js'
 
-const authorization = new OIDCAuthorization({
-  discoveryUrl: environments.OIDC_DISCOVERY_URL,
-  clientId: environments.OIDC_CLIENT,
-  clientSecret: environments.OIDC_SECRET,
-  token: '<<headers.authorization>>',
+export default new App({
+  id: 'my-app',
+  workflows: [cashback],
+  authorization: new OIDCAuthorization({
+    discoveryUrl: environments.OIDC_DISCOVERY_URL,
+    clientId: environments.OIDC_CLIENT,
+    clientSecret: environments.OIDC_SECRET,
+    token: '<<headers.authorization>>',
+  }),
 })
 ```
 
-Wire `authorization` on an `App` or `Workflow` per the core package; the deployed runtime fills `token` (and any other fields you resolve dynamically) and invokes `@t4h.framework/oidc/authorize`.
+## Documentation
+
+Configuration, the validation steps, errors and testing:
+https://tech4humans-brasil.github.io/framework/oidc/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/oidc",
-  "version": "0.6.11",
+  "version": "0.6.12",
   "description": "OIDC module for the T4H Framework authorization",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/oidc",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -39,7 +39,7 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.20.0",
+    "@t4h.framework/core": "^0.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },