@t4h.framework/oidc 0.2.0 → 0.4.0

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

@@ -0,0 +1,282 @@
+---
+name: framework-oidc
+description: >-
+  Wire OpenID Connect authorization in T4H Framework apps and workflows using
+  @t4h.framework/oidc: OIDCAuthorization manifest, OIDCAuthorizationContext,
+  Bearer token introspection via OAuth client credentials, discoveryUrl,
+  scope, and resource. Use when securing App/Workflow with OIDC, token
+  validation, OpenID Provider discovery, introspection_endpoint, attaching
+  authorization to manifests, or 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** after obtaining a service token with the **OAuth 2.0 client credentials** grant.
+
+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`.
+
+```typescript
+import { App } from '@t4h.framework/core'
+import { OIDCAuthorization } from '@t4h.framework/oidc'
+
+export default new App({
+  id: 'my-app',
+  authorization: new OIDCAuthorization({
+    discoveryUrl:
+      'https://auth.example.com/.well-known/openid-configuration',
+    clientId: 'my-service',
+    clientSecret: process.env.OIDC_CLIENT_SECRET!,
+    token: 'Bearer <incoming-access-token-from-runtime>',
+    scope: ['introspection'],
+  }),
+  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 (including `scope` / `resource` as `undefined` when omitted)
+
+```typescript
+new OIDCAuthorization({
+  discoveryUrl: 'https://auth.example.com/.well-known/openid-configuration',
+  clientId: 'svc',
+  clientSecret: 'secret',
+  token: 'Bearer t',
+  scope: ['a', 'b'],           // optional
+  resource: 'https://api.example.com', // optional
+})
+```
+
+There is **no** built-in mapping from environment variables — supply `clientSecret`, `discoveryUrl`, etc. from your app/hosting layer when constructing 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 `token_endpoint` and `introspection_endpoint`). |
+| `clientId` | Yes | OAuth 2.0 client id for client credentials grant. |
+| `clientSecret` | Yes | OAuth 2.0 client secret for client credentials grant. |
+| `token` | Yes | Credential to verify. Must use a `Bearer ` prefix for the token value to be sent to introspection (see below). |
+| `scope` | No | Scopes for the client-credentials token (`string[]`, joined with spaces on the wire). |
+| `resource` | No | If set, sent as `resource` on the client credentials request (RFC 8707 style). |
+
+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 T as token_endpoint
+  participant I as introspection_endpoint
+
+  R->>D: GET discovery JSON
+  R->>T: POST client_credentials
+  T-->>R: access_token
+  R->>I: POST JSON { token } + Bearer access_token
+  I-->>R: { active }
+  R-->>R: true if active else false
+```
+
+1. **Discovery** — `GET` `discoveryUrl`; parse JSON as `{ token_endpoint, introspection_endpoint }`. Non-OK HTTP → throw `Discovery request failed: <status> <statusText>`.
+2. **Client credentials** — `POST` `token_endpoint` with `application/x-www-form-urlencoded` body:
+   - `grant_type=client_credentials`
+   - `client_id`, `client_secret`
+   - optional `scope` (space-joined from array)
+   - optional `resource`
+   Non-OK HTTP → throw `Token request failed: ...`.
+3. **Introspection** — `POST` `introspection_endpoint` with:
+   - `Content-Type: application/json`
+   - `Authorization: Bearer <access_token>` (from step 2)
+   - body `JSON.stringify({ token: <stripped incoming token or null> })`
+   Non-OK HTTP → throw `Introspection request failed: ...`.
+4. **Result** — parse `{ active: boolean }`:
+   - `active: true` → return `true`
+   - `active: false` → return `false`
+
+Network failures from `fetch` propagate as rejected promises (not converted to `false`).
+
+### Bearer prefix rules
+
+Incoming `token` is parsed with a simple prefix check:
+
+- Starts with `Bearer ` → introspection body uses the substring after the first `Bearer ` (e.g. `Bearer abc.def` → `"abc.def"`).
+- Does **not** start with `Bearer ` → introspection body sends `{ "token": null }` (typically yields `active: false`).
+
+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. Ensure IdP discovery document exposes `token_endpoint` and `introspection_endpoint`.
+5. Register a confidential OAuth client allowed to use **client credentials** and call **introspection**.
+6. Pass incoming caller token with `Bearer ` prefix (or use a runtime placeholder like `<<headers.authorization>>`).
+7. Optionally set `scope` (e.g. scopes required for introspection on the service token) and `resource` (audience/resource indicator for the CC token).
+
+Do **not** look for OIDC Activities or Claim classes in this package — they do not exist here.
+
+---
+
+## 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',
+    scope: undefined, // when omitted
+    resource: undefined,
+    token: 'Bearer t',
+  },
+})
+```
+
+### Handler (`import oidc from '@t4h.framework/oidc/authorize'`)
+
+Mock three `fetch` calls in order: discovery → token → 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({
+    token_endpoint: 'https://auth.example.com/oauth/token',
+    introspection_endpoint: 'https://auth.example.com/oauth/introspect',
+  }))
+  .mockResolvedValueOnce(jsonResponse({ access_token: 'cc-access-token' }))
+  .mockResolvedValueOnce(jsonResponse({ active: true }))
+
+await expect(oidc(baseContext)).resolves.toBe(true)
+```
+
+Verify wire format from tests:
+
+- Token request: `URLSearchParams` with `grant_type`, `client_id`, `client_secret`; optional `scope` (`openid profile` from `['openid','profile']`); optional `resource`.
+- Introspection: `Authorization: Bearer cc-access-token`, body `{ token: 'incoming-token' }` after stripping `Bearer `.
+- Missing Bearer prefix: body `{ token: null }`.
+- Inactive token: third response `{ active: false }` → `false`.
+- HTTP errors on discovery/token/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 | Introspection gets `token: null`; usually denied |
+| Expecting env auto-wiring | Secrets/URLs must be set when constructing `OIDCAuthorization` |
+| Missing `introspection_endpoint` on IdP | Discovery JSON incomplete; runtime fails at fetch/parse |
+| Treating `false` as HTTP error | `false` means inactive token; errors are thrown separately |
+| Adding OIDC as a Claim provider | Wrong abstraction — use `Authorization` on App/Workflow |
+| Importing handler from main entry | Use `@t4h.framework/oidc/authorize` (default export) |
+
+---
+
+## 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 + CC + introspection |
+
+See [README.md](../../../README.md) in this package for the same behavior described for humans.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/oidc",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "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",
@@ -26,7 +26,8 @@
   "types": "./dist/oidc.d.ts",
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    ".ai"
   ],
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
@@ -36,12 +37,12 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.2.0",
+    "@t4h.framework/core": "^0.8.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.2.0"
+    "@t4h.framework/core": "^0.8.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {