@t4h.framework/oidc 0.0.0-experimental-858514c-40d427e3f546ef29ce9e

package/README.md

@@ -0,0 +1,62 @@
+# @t4h.framework/jwks
+
+JWT authorization module backed by a JWKS endpoint.
+
+## Behavior
+
+The authorization handler validates a JWT using a JWKS endpoint and returns:
+
+- `undefined` when the token is valid
+- `401 Unauthorized` when the token is missing or invalid
+- `500 JWKS authorization failed` when infrastructure/configuration fails
+
+## JWKS configuration
+
+Set one of:
+
+- `JWKS_URI`: direct JWKS endpoint URL
+- `JWKS_ISSUER`: OIDC issuer URL (the module discovers metadata and resolves `jwks_uri`)
+
+Optional:
+
+- `JWKS_CLIENT_ID`: client id used during issuer discovery when `JWKS_ISSUER` is used (default: `jwks-resource-server`)
+
+You can also define these values in `JWKSAuthorization` options (`jwksUri`, `jwksIssuer`, `clientId`) instead of environment variables.
+
+## Credential source (customizable)
+
+The token source is configured in `JWKSAuthorization` through `credentialSource`.
+
+- default: `Authorization: Bearer <token>`
+- custom header: e.g. `x-webhook-jwt`
+- query string: e.g. `?token=<jwt>`
+
+### Examples
+
+Default bearer:
+
+```typescript
+import { JWKSAuthorization } from '@t4h.framework/jwks'
+
+const authorization = new JWKSAuthorization()
+```
+
+Webhook header (raw token, no Bearer prefix):
+
+```typescript
+import { JWKSAuthorization } from '@t4h.framework/jwks'
+
+const authorization = new JWKSAuthorization({
+  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
+  credentialSource: {
+    type: 'header',
+    name: 'x-webhook-jwt',
+  },
+})
+```
+
+## Validation currently enforced
+
+- Token extraction from configured source
+- JWT signature using a key from JWKS
+- Required `exp` claim (must be in the future)

package/dist/helpers/client-credentials.d.ts

@@ -0,0 +1,3 @@
+import type { OIDCAuthorizationOptions } from '../oidc.js';
+export declare function clientCredentials(options: OIDCAuthorizationOptions): Promise<boolean>;
+//# sourceMappingURL=client-credentials.d.ts.map

package/dist/helpers/client-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-credentials.d.ts","sourceRoot":"","sources":["../../src/helpers/client-credentials.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAE1D,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,oBA0BxE"}

package/dist/helpers/client-credentials.js

@@ -0,0 +1,18 @@
+import * as client from 'openid-client';
+export async function clientCredentials(options) {
+    const discovery = await client.discovery(new URL(options.url), options.clientId, options.clientSecret);
+    const scope = Array.isArray(options.scope)
+        ? options.scope.join(' ')
+        : options.scope;
+    const params = new URLSearchParams();
+    if (scope)
+        params.set('scope', scope);
+    if (options.resource)
+        params.set('resource', options.resource);
+    const { access_token } = await client.clientCredentialsGrant(discovery, params);
+    const token = await client.tokenIntrospection(discovery, access_token);
+    if (!token.active)
+        return false;
+    return true;
+}
+//# sourceMappingURL=client-credentials.js.map

package/dist/helpers/client-credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-credentials.js","sourceRoot":"","sources":["../../src/helpers/client-credentials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAiC;IACvE,MAAM,SAAS,GAAyB,MAAM,MAAM,CAAC,SAAS,CAC5D,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,EACpB,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,YAAY,CACrB,CAAA;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;QACxC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;QACzB,CAAC,CAAC,OAAO,CAAC,KAAK,CAAA;IAEjB,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAA;IAEpC,IAAI,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACrC,IAAI,OAAO,CAAC,QAAQ;QAAE,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IAE9D,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAC1D,SAAS,EACT,MAAM,CACP,CAAA;IAED,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,SAAS,EAAE,YAAY,CAAC,CAAA;IAEtE,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAE/B,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/models/OIDCAuthorization.d.ts

@@ -0,0 +1,15 @@
+import { Authorization, type AuthenticationManifest } from '@t4h.framework/core';
+export type OIDCAuthorizationContext = {
+    url: string;
+    clientId: string;
+    clientSecret: string;
+    scope?: string[];
+    resource?: string;
+};
+export type OIDCAuthorizationManifest = AuthenticationManifest<OIDCAuthorizationContext>;
+export declare class OIDCAuthorization extends Authorization<OIDCAuthorizationContext> {
+    private readonly context;
+    constructor(context: OIDCAuthorizationContext);
+    toManifest(): OIDCAuthorizationManifest;
+}
+//# sourceMappingURL=OIDCAuthorization.d.ts.map

package/dist/models/OIDCAuthorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OIDCAuthorization.d.ts","sourceRoot":"","sources":["../../src/models/OIDCAuthorization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AAEhF,MAAM,MAAM,wBAAwB,GAAG;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,yBAAyB,GACnC,sBAAsB,CAAC,wBAAwB,CAAC,CAAA;AAElD,qBAAa,iBAAkB,SAAQ,aAAa,CAAC,wBAAwB,CAAC;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,wBAAwB;IAIvD,UAAU,IAAI,yBAAyB;CAW/C"}

package/dist/models/OIDCAuthorization.js

@@ -0,0 +1,20 @@
+import { Authorization } from '@t4h.framework/core';
+export class OIDCAuthorization extends Authorization {
+    context;
+    constructor(context) {
+        super();
+        this.context = context;
+    }
+    toManifest() {
+        return {
+            context: {
+                url: this.context.url,
+                clientId: this.context.clientId,
+                clientSecret: this.context.clientSecret,
+                scope: this.context.scope,
+            },
+            pathToModule: '@t4h.framework/oidc/authorize',
+        };
+    }
+}
+//# sourceMappingURL=OIDCAuthorization.js.map

package/dist/models/OIDCAuthorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OIDCAuthorization.js","sourceRoot":"","sources":["../../src/models/OIDCAuthorization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAA+B,MAAM,qBAAqB,CAAA;AAahF,MAAM,OAAO,iBAAkB,SAAQ,aAAuC;IAC/C;IAA7B,YAA6B,OAAiC;QAC5D,KAAK,EAAE,CAAA;QADoB,YAAO,GAAP,OAAO,CAA0B;IAE9D,CAAC;IAEM,UAAU;QACf,OAAO;YACL,OAAO,EAAE;gBACP,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG;gBACrB,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ;gBAC/B,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,YAAY;gBACvC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;aAC1B;YACD,YAAY,EAAE,+BAA+B;SAC9C,CAAA;IACH,CAAC;CACF"}

package/dist/oidc-authorize.d.ts

@@ -0,0 +1,3 @@
+import type { OIDCAuthorizationContext } from './oidc.js';
+export default function oidc(context: OIDCAuthorizationContext): Promise<boolean>;
+//# sourceMappingURL=oidc-authorize.d.ts.map

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

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

package/dist/oidc-authorize.js

@@ -0,0 +1,18 @@
+import * as client from 'openid-client';
+export default async function oidc(context) {
+    const discovery = await client.discovery(new URL(context.url), context.clientId, context.clientSecret);
+    const scope = Array.isArray(context.scope)
+        ? context.scope.join(' ')
+        : context.scope;
+    const params = new URLSearchParams();
+    if (scope)
+        params.set('scope', scope);
+    if (context.resource)
+        params.set('resource', context.resource);
+    const { access_token } = await client.clientCredentialsGrant(discovery, params);
+    const token = await client.tokenIntrospection(discovery, access_token);
+    if (!token.active)
+        return false;
+    return true;
+}
+//# sourceMappingURL=oidc-authorize.js.map

package/dist/oidc-authorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc-authorize.js","sourceRoot":"","sources":["../src/oidc-authorize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,IAAI,CAChC,OAAiC;IAEjC,MAAM,SAAS,GAAyB,MAAM,MAAM,CAAC,SAAS,CAC5D,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,EACpB,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,YAAY,CACrB,CAAA;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;QACxC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;QACzB,CAAC,CAAC,OAAO,CAAC,KAAK,CAAA;IAEjB,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAA;IAEpC,IAAI,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACrC,IAAI,OAAO,CAAC,QAAQ;QAAE,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IAE9D,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAC1D,SAAS,EACT,MAAM,CACP,CAAA;IAED,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,SAAS,EAAE,YAAY,CAAC,CAAA;IAEtE,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAE/B,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/oidc.d.ts

@@ -0,0 +1,3 @@
+export * from './oidc-authorize.js';
+export * from './models/OIDCAuthorization.js';
+//# sourceMappingURL=oidc.d.ts.map

package/dist/oidc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../src/oidc.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,+BAA+B,CAAA"}

package/dist/oidc.js

@@ -0,0 +1,3 @@
+export * from './oidc-authorize.js';
+export * from './models/OIDCAuthorization.js';
+//# sourceMappingURL=oidc.js.map

package/dist/oidc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc.js","sourceRoot":"","sources":["../src/oidc.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,+BAA+B,CAAA"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@t4h.framework/oidc",
+  "version": "0.0.0-experimental-858514c-40d427e3f546ef29ce9e",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tech4humans-brasil/framework.git",
+    "directory": "packages/oidc"
+  },
+  "license": "MIT",
+  "author": "Tech4Humans <contact@tech4h.com.br> (https://tech4h.com.br)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/oidc.d.ts",
+      "import": "./dist/oidc.js"
+    },
+    "./authorize": {
+      "types": "./dist/oidc-authorize.d.ts",
+      "import": "./dist/oidc-authorize.js"
+    }
+  },
+  "module": "./dist/oidc.js",
+  "types": "./dist/oidc.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "prepublishOnly": "yarn build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@t4h.framework/core": "^0.0.0-experimental-858514c-40d427e3f546ef29ce9e",
+    "@types/jsonwebtoken": "^9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@t4h.framework/core": "^0.0.0-experimental-858514c-40d427e3f546ef29ce9e"
+  },
+  "packageManager": "yarn@4.12.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "jsonwebtoken": "^9.0.3",
+    "jwks-rsa": "^4.0.1",
+    "openid-client": "^6.8.2"
+  },
+  "stableVersion": "0.0.0"
+}