@t4h.framework/oidc 0.6.10 → 0.6.11

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

@@ -49,18 +49,32 @@ type AuthorizationManifest<TContext extends object = any> = {
 
 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:
-      'https://auth.example.com/.well-known/openid-configuration',
-    clientId: 'my-service',
-    clientSecret: process.env.OIDC_CLIENT_SECRET!,
-    token: 'Bearer <incoming-access-token-from-runtime>',
+    discoveryUrl: environments.OIDC_DISCOVERY_URL,
+    clientId: environments.OIDC_CLIENT,
+    clientSecret: environments.OIDC_SECRET,
+    token: '<<headers.authorization>>',
   }),
   workflows: [/* ... */],
 })
@@ -94,14 +108,14 @@ Subclass of `Authorization<OIDCAuthorizationContext>`. Constructor stores contex
 
 ```typescript
 new OIDCAuthorization({
-  discoveryUrl: 'https://auth.example.com/.well-known/openid-configuration',
-  clientId: 'svc',
-  clientSecret: 'secret',
-  token: 'Bearer t',
+  discoveryUrl: environments.OIDC_DISCOVERY_URL,
+  clientId: environments.OIDC_CLIENT,
+  clientSecret: environments.OIDC_SECRET,
+  token: '<<headers.authorization>>',
 })
 ```
 
-There is **no** built-in mapping from environment variables — supply `clientSecret`, `discoveryUrl`, etc. from your app/hosting layer when constructing the instance.
+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
 
@@ -175,11 +189,8 @@ Always author/runtime-resolve credentials as `Bearer <access-token>` when you ex
 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 `introspection_endpoint`.
-5. Register a confidential OAuth client allowed to call **introspection** with **`client_secret_basic`**.
-6. Pass incoming caller token with `Bearer ` prefix (or use a runtime placeholder like `<<headers.authorization>>`).
-
-Do **not** look for OIDC Activities or Claim classes in this package — they do not exist here.
+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>>`).
 
 ---
 
@@ -244,10 +255,8 @@ Workflow-level authorization behavior in process is owned by the **runtime** (ou
 |---------|-------------|
 | 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 | Discovery JSON incomplete; runtime fails at fetch/parse |
+| 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 |
-| 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) |
 
 ---
 

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @t4h.framework/oidc
 
+## 0.6.11
+
+### Patch Changes
+
+- [#241](https://github.com/tech4humans-brasil/framework/pull/241) [`f6b8454`](https://github.com/tech4humans-brasil/framework/commit/f6b845484d22e7c8e7240fe2e113f1cdea7c8ce3) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Adds seven rules to `@t4h.framework/core/eslint` and turns them on in `configs.recommended`:
+  - `no-io-in-workflow` reports `fetch` and calls to network, file, database and mail modules in a workflow and in the `constructor`, `toInput` and `toOutput` of an activity. It also reports `zlib` and `stream` calls there, because they work on the content in memory on each replay.
+  - `no-binary-subclass` reports a class that extends `Binary`.
+  - `no-framework-activity-in-app` reports `new` and `extends` on an activity of a framework package other than the core.
+  - `no-testing-import-in-source` reports an import of a `@t4h.framework/<package>/testing` entry out of a test file.
+  - `require-workflow-id` reports a `Workflow` with no `id`.
+  - `no-secret-to-string` reports a `Secret` that becomes a string.
+  - `no-literal-secret-in-authorization` reports a string literal in the `secret` or `clientSecret` field of an `Authorization`.
+
+  The package skills now name these rules in place of the text that the rules enforce. The docs and skills give each `Workflow` an `id`, read the HMAC secret from `EnvDesign`, and do not document a custom HTTP activity.
+
+- [#243](https://github.com/tech4humans-brasil/framework/pull/243) [`0ffd663`](https://github.com/tech4humans-brasil/framework/commit/0ffd663ce8369edd7b54206cb3216568ad1de471) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The README examples read each value from `environments`, an `EnvDesign` in `src/constants/environments.ts`, and pass each credential as a `Secret`. They no longer use `process.env`, the raw `env` from the core or a literal in a `Secret` field. The jwks README describes the real context fields (`signature`, `rawPayload`) and says that a token that `jwt.verify` rejects throws.
+
+- [#240](https://github.com/tech4humans-brasil/framework/pull/240) [`0606115`](https://github.com/tech4humans-brasil/framework/commit/0606115e2e0baa994e9f0ed3559ee54ecac88e44) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The skills do not repeat a rule that a lint rule, `tsc` or a runtime error already enforces. Each such rule is now one line that names the gate. The examples that broke a gate (`process.env`, `as any`, an inline secret, an `EnvDesign` in a workflow file, `ref.output` before `wait()`) are correct now.
+
+- [#228](https://github.com/tech4humans-brasil/framework/pull/228) [`d29e1ab`](https://github.com/tech4humans-brasil/framework/commit/d29e1ab29a039b13c3e4b075472bd615566ae75e) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Uses exact types and `unknown` in place of `any`, and checks external data with guards.
+  - harness: the fix-issues prompt lists each sensor as `- checkTypes: PASS`. Before, it printed `- 0: [object Object]`.
+  - hmac: an algorithm name such as `constructor` throws `Unsupported algorithm`.
+  - oidc: a discovery response with no `introspection_endpoint`, or a null introspection body, throws a clear error.
+  - `HttpRequestActivity.toOutput` takes `HttpRequestActivityOutput` in place of `any`.
+
 ## 0.6.10
 
 ## 0.6.9

package/README.md

@@ -52,14 +52,29 @@ There is no built-in mapping from environment variables; all configuration comes
 
 ## 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 },
+})
+```
+
 ```typescript
 import { OIDCAuthorization } from '@t4h.framework/oidc'
 
+import { environments } from './constants/environments.js'
+
 const 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>',
+  discoveryUrl: environments.OIDC_DISCOVERY_URL,
+  clientId: environments.OIDC_CLIENT,
+  clientSecret: environments.OIDC_SECRET,
+  token: '<<headers.authorization>>',
 })
 ```
 

package/dist/oidc-authorize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oidc-authorize.d.ts","sourceRoot":"","sources":["../src/oidc-authorize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AAmCzD,wBAA8B,IAAI,CAChC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,OAAO,CAAC,CA6ClB"}
+{"version":3,"file":"oidc-authorize.d.ts","sourceRoot":"","sources":["../src/oidc-authorize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AAyCzD,wBAA8B,IAAI,CAChC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,OAAO,CAAC,CA8ClB"}

package/dist/oidc-authorize.js

@@ -1,11 +1,28 @@
 const BEARER_CREDENTIAL = /^Bearer +(?<token>[^ ]+) *$/i;
+const CREDENTIAL_PREFIX = 'value=';
 function getAccessToken(token) {
     const match = BEARER_CREDENTIAL.exec(token);
     return match?.groups?.token ?? null;
 }
 function encodeCredential(value) {
-    const [, encoded] = new URLSearchParams({ value }).toString().split('=');
-    return encoded;
+    return new URLSearchParams({ value })
+        .toString()
+        .slice(CREDENTIAL_PREFIX.length);
+}
+function getIntrospectionEndpoint(discovery) {
+    if (typeof discovery === 'object' &&
+        discovery !== null &&
+        'introspection_endpoint' in discovery &&
+        typeof discovery.introspection_endpoint === 'string')
+        return discovery.introspection_endpoint;
+    throw new Error('Discovery response has no introspection_endpoint');
+}
+function isActive(introspection) {
+    if (introspection === null)
+        throw new Error('Introspection response body is null');
+    return (typeof introspection === 'object' &&
+        'active' in introspection &&
+        introspection.active === true);
 }
 export default async function oidc(context) {
     const accessToken = getAccessToken(context.token);
@@ -18,10 +35,11 @@ export default async function oidc(context) {
         },
     });
     if (!discoveryResponse.ok)
-        throw new Error(`Discovery request failed: ${discoveryResponse.status} ${discoveryResponse.statusText}`);
-    const discovery = (await discoveryResponse.json());
+        throw new Error(`Discovery request failed: ${String(discoveryResponse.status)} ${discoveryResponse.statusText}`);
+    const discovery = await discoveryResponse.json();
+    const introspectionEndpoint = getIntrospectionEndpoint(discovery);
     const credentials = Buffer.from(`${encodeCredential(context.clientId)}:${encodeCredential(context.clientSecret)}`).toString('base64');
-    const introspectionResponse = await fetch(discovery.introspection_endpoint, {
+    const introspectionResponse = await fetch(introspectionEndpoint, {
         body: new URLSearchParams({
             token: accessToken,
             token_type_hint: 'access_token',
@@ -34,8 +52,8 @@ export default async function oidc(context) {
         },
     });
     if (!introspectionResponse.ok)
-        throw new Error(`Introspection request failed: ${introspectionResponse.status} ${introspectionResponse.statusText}`);
-    const introspection = (await introspectionResponse.json());
-    return introspection.active === true;
+        throw new Error(`Introspection request failed: ${String(introspectionResponse.status)} ${introspectionResponse.statusText}`);
+    const introspection = await introspectionResponse.json();
+    return isActive(introspection);
 }
 //# sourceMappingURL=oidc-authorize.js.map

package/dist/oidc-authorize.js.map

@@ -1 +1 @@
-{"version":3,"file":"oidc-authorize.js","sourceRoot":"","sources":["../src/oidc-authorize.ts"],"names":[],"mappings":"AAqBA,MAAM,iBAAiB,GAAG,8BAA8B,CAAA;AAExD,SAAS,cAAc,CAAC,KAAa;IACnC,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAE3C,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,IAAI,CAAA;AACrC,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC,GAAG,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAExE,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,IAAI,CAChC,OAAiC;IAEjC,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAEjD,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAA;IAE9B,MAAM,iBAAiB,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,YAAY,EAAE;QAC1D,MAAM,EAAE,KAAK;QACb,OAAO,EAAE;YACP,MAAM,EAAE,kBAAkB;SAC3B;KACF,CAAC,CAAA;IAEF,IAAI,CAAC,iBAAiB,CAAC,EAAE;QACvB,MAAM,IAAI,KAAK,CACb,6BAA6B,iBAAiB,CAAC,MAAM,IAAI,iBAAiB,CAAC,UAAU,EAAE,CACxF,CAAA;IAEH,MAAM,SAAS,GAAG,CAAC,MAAM,iBAAiB,CAAC,IAAI,EAAE,CAAwB,CAAA;IAEzE,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAC7B,GAAG,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAClF,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAEpB,MAAM,qBAAqB,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,sBAAsB,EAAE;QAC1E,IAAI,EAAE,IAAI,eAAe,CAAC;YACxB,KAAK,EAAE,WAAW;YAClB,eAAe,EAAE,cAAc;SAChC,CAAC;QACF,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,cAAc,EAAE,mCAAmC;YACnD,MAAM,EAAE,kBAAkB;YAC1B,aAAa,EAAE,SAAS,WAAW,EAAE;SACtC;KACF,CAAC,CAAA;IAEF,IAAI,CAAC,qBAAqB,CAAC,EAAE;QAC3B,MAAM,IAAI,KAAK,CACb,iCAAiC,qBAAqB,CAAC,MAAM,IAAI,qBAAqB,CAAC,UAAU,EAAE,CACpG,CAAA;IAEH,MAAM,aAAa,GACjB,CAAC,MAAM,qBAAqB,CAAC,IAAI,EAAE,CAA0B,CAAA;IAE/D,OAAO,aAAa,CAAC,MAAM,KAAK,IAAI,CAAA;AACtC,CAAC"}
+{"version":3,"file":"oidc-authorize.js","sourceRoot":"","sources":["../src/oidc-authorize.ts"],"names":[],"mappings":"AAEA,MAAM,iBAAiB,GAAG,8BAA8B,CAAA;AAExD,MAAM,iBAAiB,GAAG,QAAQ,CAAA;AAElC,SAAS,cAAc,CAAC,KAAa;IACnC,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAE3C,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,IAAI,CAAA;AACrC,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa;IACrC,OAAO,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC;SAClC,QAAQ,EAAE;SACV,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAA;AACpC,CAAC;AAED,SAAS,wBAAwB,CAAC,SAAkB;IAClD,IACE,OAAO,SAAS,KAAK,QAAQ;QAC7B,SAAS,KAAK,IAAI;QAClB,wBAAwB,IAAI,SAAS;QACrC,OAAO,SAAS,CAAC,sBAAsB,KAAK,QAAQ;QAEpD,OAAO,SAAS,CAAC,sBAAsB,CAAA;IAEzC,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAA;AACrE,CAAC;AAED,SAAS,QAAQ,CAAC,aAAsB;IACtC,IAAI,aAAa,KAAK,IAAI;QACxB,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAA;IAExD,OAAO,CACL,OAAO,aAAa,KAAK,QAAQ;QACjC,QAAQ,IAAI,aAAa;QACzB,aAAa,CAAC,MAAM,KAAK,IAAI,CAC9B,CAAA;AACH,CAAC;AAED,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,IAAI,CAChC,OAAiC;IAEjC,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAEjD,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAA;IAE9B,MAAM,iBAAiB,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,YAAY,EAAE;QAC1D,MAAM,EAAE,KAAK;QACb,OAAO,EAAE;YACP,MAAM,EAAE,kBAAkB;SAC3B;KACF,CAAC,CAAA;IAEF,IAAI,CAAC,iBAAiB,CAAC,EAAE;QACvB,MAAM,IAAI,KAAK,CACb,6BAA6B,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI,iBAAiB,CAAC,UAAU,EAAE,CAChG,CAAA;IAEH,MAAM,SAAS,GAAY,MAAM,iBAAiB,CAAC,IAAI,EAAE,CAAA;IAEzD,MAAM,qBAAqB,GAAG,wBAAwB,CAAC,SAAS,CAAC,CAAA;IAEjE,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAC7B,GAAG,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAClF,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAEpB,MAAM,qBAAqB,GAAG,MAAM,KAAK,CAAC,qBAAqB,EAAE;QAC/D,IAAI,EAAE,IAAI,eAAe,CAAC;YACxB,KAAK,EAAE,WAAW;YAClB,eAAe,EAAE,cAAc;SAChC,CAAC;QACF,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,cAAc,EAAE,mCAAmC;YACnD,MAAM,EAAE,kBAAkB;YAC1B,aAAa,EAAE,SAAS,WAAW,EAAE;SACtC;KACF,CAAC,CAAA;IAEF,IAAI,CAAC,qBAAqB,CAAC,EAAE;QAC3B,MAAM,IAAI,KAAK,CACb,iCAAiC,MAAM,CAAC,qBAAqB,CAAC,MAAM,CAAC,IAAI,qBAAqB,CAAC,UAAU,EAAE,CAC5G,CAAA;IAEH,MAAM,aAAa,GAAY,MAAM,qBAAqB,CAAC,IAAI,EAAE,CAAA;IAEjE,OAAO,QAAQ,CAAC,aAAa,CAAC,CAAA;AAChC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/oidc",
-  "version": "0.6.10",
+  "version": "0.6.11",
   "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",
@@ -32,12 +32,14 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "check-types": "tsc --noEmit",
+    "check-package": "publint --strict && attw --pack . --profile esm-only",
+    "lint": "eslint . --max-warnings 0",
     "prepublishOnly": "yarn build",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.19.0",
+    "@t4h.framework/core": "^0.20.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },