@ciromaciel/contract 1.1.0 → 1.2.0

package/README.md

@@ -13,7 +13,8 @@ described below.
 bun add @ciromaciel/contract
 ```
 
-`zod` is an **optional** peer, needed only by the `/schemas` entrypoint.
+`zod` is an **optional** peer, needed only by the `/schemas` entrypoint, and
+`jose` only by `/token`.
 
 ## Quick start
 
@@ -109,6 +110,29 @@ and answers with a reason (`stale_timestamp`, `bad_signature`, …) instead of a
 bare boolean. Also exports `signWebhook`, `secretPrefixOf` and
 `SIGNATURE_TOLERANCE_SECONDS`.
 
+### `@ciromaciel/contract/token`
+
+```js
+import { createTokenVerifier } from '@ciromaciel/contract/token'
+
+const tokens = createTokenVerifier({ authUrl: 'https://auth.worker.myinfrastructure.click' })
+
+await tokens.verifySession(bearer) // REST routes
+await tokens.verifyAccessToken(bearer, { audience: 'https://hoster.worker.myinfrastructure.click/mcp' }) // MCP server
+```
+
+The Auth signs sessions and OAuth access tokens with the same key and issuer;
+only the claims tell them apart. `verifySession` accepts a person's session and
+refuses an access token (`access_token_not_accepted`): a token consented for one
+resource and one scope must never act as the whole account on a REST route.
+`verifyAccessToken` accepts only an access token whose `aud` is this server
+(`wrong_audience` otherwise, RFC 8707) and returns its `scopes`.
+
+Both return `{ ok: true, subject, email, name, scopes, claims }` or
+`{ ok: false, reason }`, never throw on a bad credential, and accept RS256 with
+the `riligar-auth` issuer only. `jose` (5 or 6) is an **optional** peer, needed
+only by this entrypoint.
+
 ## Links
 
 - [Website](https://ciromaciel.click)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ciromaciel/contract",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "license": "MIT",
     "type": "module",
     "description": "A single response envelope, a closed catalogue of error codes, and helpers that make answering outside it impossible.",
@@ -14,21 +14,27 @@
         "./codes": "./src/codes.js",
         "./schemas": "./src/schemas.js",
         "./plan": "./src/plan/index.js",
-        "./webhooks": "./src/webhooks.js"
+        "./webhooks": "./src/webhooks.js",
+        "./token": "./src/token.js"
     },
     "scripts": {
         "test": "bun test tests/"
     },
     "peerDependencies": {
-        "zod": "^4.0.0"
+        "zod": "^4.0.0",
+        "jose": "^5.0.0 || ^6.0.0"
     },
     "peerDependenciesMeta": {
         "zod": {
             "optional": true
+        },
+        "jose": {
+            "optional": true
         }
     },
     "devDependencies": {
-        "zod": "^4.5.4"
+        "zod": "^4.5.4",
+        "jose": "^6.2.10"
     },
     "publishConfig": {
         "access": "public"

package/src/token.js

@@ -0,0 +1,146 @@
+// ============================================================================
+// @ciromaciel/contract/token — one way to read an Infrastructure Auth token
+// ============================================================================
+//
+//     import { createTokenVerifier } from '@ciromaciel/contract/token'
+//
+//     const tokens = createTokenVerifier({ authUrl: 'https://auth.worker.myinfrastructure.click' })
+//
+//     // REST routes: a person's session, and nothing else.
+//     const session = await tokens.verifySession(bearer)
+//
+//     // The MCP server: an OAuth access token issued for THIS resource.
+//     const access = await tokens.verifyAccessToken(bearer, { audience: 'https://hoster.worker.myinfrastructure.click/mcp' })
+//
+// The Auth signs two kinds of token with the same key and the same issuer:
+//
+//   session        `{ sub, email, name, role }`, no `aud`. Held by the person
+//                  (dashboard, CLI login, the e-mailed code flow).
+//   access token   `{ sub, aud, scope, client_id, token_type: 'access_token' }`.
+//                  Held by a third-party OAuth client, limited to one resource
+//                  (`aud`, RFC 8707) and to what the person consented to
+//                  (`scope`).
+//
+// Signature and issuer cannot tell them apart; only the claims can. Each
+// product used to verify tokens with its own copy of this code — twelve
+// copies — and the REST ones checked signature and issuer only. So an access
+// token consented as "read" for one product's MCP server worked as a full
+// session on the REST API of every product. This module is the one place that
+// knows the difference, so it can only be right or wrong once.
+//
+// Results are values, never exceptions: `{ ok: true, ... }` or
+// `{ ok: false, reason }`. A wrong credential is an answer the caller turns
+// into 401 or 403, not a failure. `reason` is for logs and for choosing the
+// status; the text shown to the caller stays generic.
+
+import { createRemoteJWKSet, jwtVerify } from 'jose'
+
+/**
+ * The `iss` the Auth writes into every token. It is a fixed name, not the
+ * Auth URL: passing the URL makes every verification fail.
+ */
+export const AUTH_TOKEN_ISSUER = 'riligar-auth'
+
+/** The only algorithm accepted. HS256 would let anyone holding a shared secret forge tokens. */
+const ALGORITHMS = ['RS256']
+
+/** Why a token was refused. */
+export const TOKEN_REFUSAL = {
+    /** Bad signature, unknown key, expired, wrong issuer or no subject. */
+    INVALID: 'invalid_token',
+    /** An OAuth access token presented where only a session is accepted. */
+    ACCESS_TOKEN_NOT_ACCEPTED: 'access_token_not_accepted',
+    /** An access token issued for another resource. */
+    WRONG_AUDIENCE: 'wrong_audience',
+}
+
+// One remote key set per JWKS URL, for the life of the process (or isolate).
+// `jose` caches the keys and refetches on an unknown `kid`, which is what keeps
+// a key rotation from turning into a wave of 401s.
+const remoteKeySets = new Map()
+
+function remoteKeySet(authUrl) {
+    const url = `${String(authUrl).replace(/\/+$/, '')}/.well-known/jwks.json`
+    if (!remoteKeySets.has(url)) remoteKeySets.set(url, createRemoteJWKSet(new URL(url)))
+    return remoteKeySets.get(url)
+}
+
+const audiencesOf = claims => (Array.isArray(claims.aud) ? claims.aud : [claims.aud]).filter(Boolean)
+
+/**
+ * Is this an OAuth access token?
+ *
+ * Either mark is enough: the Auth writes both, and a token with an audience
+ * was issued for one resource, whatever else it says.
+ */
+export const isAccessToken = claims => audiencesOf(claims).length > 0 || claims.token_type === 'access_token'
+
+const scopesOf = claims =>
+    String(claims.scope ?? '')
+        .split(' ')
+        .filter(Boolean)
+
+function identity(claims) {
+    return { subject: claims.sub, email: claims.email, name: claims.name, scopes: scopesOf(claims), claims }
+}
+
+/**
+ * Builds the verifier for one Auth.
+ *
+ * @param {object} options
+ * @param {string} [options.authUrl] The Auth base URL; its JWKS is fetched from `/.well-known/jwks.json`.
+ * @param {string} [options.issuer] The expected `iss`. Defaults to {@link AUTH_TOKEN_ISSUER}.
+ * @param {Function} [options.keySet] A `jose` key set to use instead of the remote JWKS (tests).
+ */
+export function createTokenVerifier({ authUrl, issuer = AUTH_TOKEN_ISSUER, keySet } = {}) {
+    if (!keySet && !authUrl) throw new Error('createTokenVerifier: authUrl is required')
+
+    async function verified(token) {
+        if (!token || typeof token !== 'string') return null
+        try {
+            const { payload } = await jwtVerify(token, keySet ?? remoteKeySet(authUrl), { algorithms: ALGORITHMS, issuer })
+            return payload.sub ? payload : null
+        } catch {
+            return null
+        }
+    }
+
+    return {
+        /**
+         * A person's session — what REST routes accept.
+         *
+         * An OAuth access token is refused here even though its signature is
+         * valid: it was consented for one resource and one scope, and a REST
+         * route would treat it as the person's whole account.
+         *
+         * @returns {Promise<{ok: true, subject: string, email?: string, name?: string, scopes: string[], claims: object} | {ok: false, reason: string}>}
+         */
+        async verifySession(token) {
+            const claims = await verified(token)
+            if (!claims) return { ok: false, reason: TOKEN_REFUSAL.INVALID }
+            if (isAccessToken(claims)) return { ok: false, reason: TOKEN_REFUSAL.ACCESS_TOKEN_NOT_ACCEPTED }
+            return { ok: true, ...identity(claims) }
+        },
+
+        /**
+         * An OAuth access token issued for `audience` — what an MCP server accepts.
+         *
+         * `audience` is the resource this server answers as (RFC 8707); a list
+         * is accepted when one server answers under more than one identifier.
+         * A session has no audience, so it is refused here as `wrong_audience`.
+         *
+         * @param {string} token
+         * @param {{ audience: string | string[] }} options
+         * @returns {Promise<{ok: true, subject: string, email?: string, name?: string, scopes: string[], claims: object} | {ok: false, reason: string}>}
+         */
+        async verifyAccessToken(token, { audience } = {}) {
+            const expected = (Array.isArray(audience) ? audience : [audience]).filter(Boolean)
+            if (expected.length === 0) throw new Error('verifyAccessToken: audience is required')
+
+            const claims = await verified(token)
+            if (!claims) return { ok: false, reason: TOKEN_REFUSAL.INVALID }
+            if (!audiencesOf(claims).some(aud => expected.includes(aud))) return { ok: false, reason: TOKEN_REFUSAL.WRONG_AUDIENCE }
+            return { ok: true, ...identity(claims) }
+        },
+    }
+}