mikser-io-auth 0.9.0 → 0.10.1

package/index.js

@@ -28,7 +28,7 @@ export { grants }
  * store can only be opened once the working folder is known:
  *
  *     const identity = auth({
- *         capabilities: { editors: ['api:update', 'mcp:use'] },
+ *         capabilities: { editors: ['api:update', 'drive:documents:write'] },
  *         issuer: 'https://cms.example.com',
  *     })
  *
@@ -49,6 +49,10 @@ export function auth(options = {}) {
         groups       = 'groups.htgroup',
         key          = 'auth.key',
         capabilities = {},
+        // One line per role, in the words the person asking would use. Not
+        // required, and worth writing: it is what turns "you lack
+        // drive:styles:write" into a sentence an end user can forward.
+        roleSummaries = {},
         scopes       = {},
         issuer,
         audience     = issuer,
@@ -84,6 +88,15 @@ export function auth(options = {}) {
     const plugin = ({ runtime, onLoad, onLoaded, useLogger }) => {
         onLoad(async () => {
             const logger = useLogger()
+            // Published so any transport can say which role is acting and
+            // which others exist. The catalogue is not secret — naming the
+            // role that could do something is what makes a handoff possible,
+            // and it reveals nothing about how to obtain one.
+            runtime.options.roles = {
+                catalogue: capabilities,
+                summaries: roleSummaries,
+            }
+
             const workingFolder = runtime.options.workingFolder
             const resolve = (f) => (path.isAbsolute(f) ? f : path.join(workingFolder, f))
 

package/lib/routes.js

@@ -175,11 +175,12 @@ export function mountRoutes(router, ctx) {
         const { store, key } = ready()
         const capabilities = await store.capabilitiesOf(subject)
         const scope        = await store.scopeOf(subject)
+        const roles        = await store.groupsOf(subject)
         const issuer       = issuerFor(res.req)
 
         const accessToken = await issueToken({
             key, issuer, audience: audienceFor(res.req),
-            subject, capabilities, scope, ttl,
+            subject, capabilities, scope, roles, ttl,
         })
 
         const body = {

package/lib/tokens.js

@@ -8,7 +8,9 @@ import { ALG } from './keys.js'
 // asked for at /authorize. Enforcement downstream is scope-only with no
 // per-request re-read, which is safe precisely because a client cannot
 // influence what goes in.
-export async function issueToken({ key, issuer, audience, subject, capabilities = [], scope = null, ttl = '1h' }) {
+export async function issueToken({
+    key, issuer, audience, subject, capabilities = [], scope = null, roles = [], ttl = '1h',
+}) {
     // `scope` is already taken: in OAuth it is the space-separated capability
     // list, and a client library will parse it as one. The row filter travels
     // as a private claim so the two never collide. It is signed, so a client
@@ -16,6 +18,11 @@ export async function issueToken({ key, issuer, audience, subject, capabilities
     const signer = new SignJWT({
         scope: capabilities.join(' '),
         ...(scope ? { mks_scope: scope } : {}),
+        // The groups the capabilities came FROM. `scope` flattens them, which
+        // is all enforcement needs and leaves a session unable to say which
+        // role it holds — so an admin token and a system with no roles at all
+        // look identical from inside.
+        ...(roles?.length ? { mks_roles: roles } : {}),
     })
         .setProtectedHeader({ alg: ALG, kid: key.kid })
         .setIssuedAt()
@@ -40,6 +47,7 @@ export function createTokenVerifier({ key, issuer, audience }) {
             subject:      payload.sub,
             capabilities: payload.scope ? payload.scope.split(' ') : [],
             scope:        payload.mks_scope ?? null,
+            roles:        Array.isArray(payload.mks_roles) ? payload.mks_roles : [],
             claims:       payload,
         }
     }

package/lib/verifiers.js

@@ -1,3 +1,4 @@
+import { explainRefusal, actingRole, runtime } from 'mikser-io'
 // The two verifiers, both implementing the ADR-0012 contract:
 //
 //   { name, verify(req) → null | false | { subject, capabilities }, challenge? }
@@ -137,10 +138,20 @@ export function jwt({ verifyToken, issuer, audience, resource, scopes = [], requ
                 // 403, not 401: the token is perfectly good and a fresh one
                 // for the same subject would be refused identically. A client
                 // that reads this as an expiry refreshes in a loop.
+                // Cite the ROLE, not just the missing capability. An agent
+                // should be able to explain why it stopped without a second
+                // call to ping, and "connected as editors, which does not
+                // include drive:styles:write" is a sentence the end user can
+                // forward. "insufficient_scope" is not.
                 return reject(req, {
                     status: 403,
                     code: 'insufficient_scope',
-                    description: `This token does not carry ${requiredCapability}`,
+                    description: explainRefusal({
+                        capability: requiredCapability,
+                        role: actingRole(principal.roles ?? [], runtime.options?.roles?.catalogue ?? {}),
+                        catalogue: runtime.options?.roles?.catalogue ?? {},
+                        summaries: runtime.options?.roles?.summaries ?? {},
+                    }),
                     scope: requiredCapability,
                 }, `${principal.subject} lacks ${requiredCapability}`)
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-auth",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Authentication for mikser-io: an OAuth 2.1 authorization server (self-registering clients, authorization code + PKCE, refresh rotation) and HTTP Basic / JWT verifiers over Apache-format htpasswd and htgroup files in the working folder. Implements the ADR-0012 verifier contract, so it plugs in wherever a static token does — api, mcp, forms.",
   "main": "index.js",
   "type": "module",
@@ -26,7 +26,7 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-auth#readme",
   "peerDependencies": {
-    "mikser-io": "^9.4.0"
+    "mikser-io": "^9.50.0"
   },
   "dependencies": {
     "bcryptjs": "^3.0.0",