@oathmesh/sdk 1.0.2

package/dist/verify.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Core OathMesh token verification — framework-agnostic.
+ *
+ * This module contains the pure verification logic shared by all framework
+ * adapters (Express, Next.js App Router, Next.js Pages Router, Edge Middleware).
+ * It has no dependency on any HTTP framework.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractToken = extractToken;
+exports.verifyOathToken = verifyOathToken;
+const jose_1 = require("jose");
+const types_1 = require("./types");
+/**
+ * Module-level JWKS cache. Keys are issuer URLs, values are jose JWKS functions.
+ * Shared across all verifier instances within the same process to avoid
+ * redundant JWKS fetches in serverless (Next.js) environments where
+ * module scope persists across requests.
+ */
+const globalJWKSCache = new Map();
+function getJWKS(issuer) {
+    let jwks = globalJWKSCache.get(issuer);
+    if (!jwks) {
+        const url = new URL('/.well-known/jwks.json', issuer);
+        jwks = (0, jose_1.createRemoteJWKSet)(url, { cacheMaxAge: 300000 });
+        globalJWKSCache.set(issuer, jwks);
+    }
+    return jwks;
+}
+/**
+ * Extract the raw token string from an Authorization header value.
+ *
+ * Accepts:
+ *   - `OathMesh <token>` (canonical)
+ *   - `Bearer <token>` (compatibility — only when the token contains om+jwt typ)
+ *
+ * @returns The raw token string, or null if the header is missing/invalid.
+ */
+function extractToken(authHeader) {
+    if (!authHeader)
+        return null;
+    if (authHeader.startsWith('OathMesh '))
+        return authHeader.slice(9);
+    if (authHeader.startsWith('Bearer '))
+        return authHeader.slice(7);
+    return null;
+}
+/**
+ * Verify an OathMesh token string and return the verified caller context.
+ *
+ * This is the core verification function. Framework adapters call this
+ * and handle HTTP responses themselves.
+ *
+ * @param token - Raw token string (without "OathMesh " prefix)
+ * @param config - Verifier configuration
+ * @returns Verified caller context on success
+ * @throws OathMeshError on any verification failure
+ */
+async function verifyOathToken(token, config) {
+    const { audience, trustedIssuers } = config;
+    // Step 02: Decode and validate header
+    let header;
+    try {
+        header = (0, jose_1.decodeProtectedHeader)(token);
+    }
+    catch {
+        throw new types_1.OathMeshError('verification_failed', 'malformed token header', 'check token format');
+    }
+    if (header.typ !== 'om+jwt') {
+        throw new types_1.OathMeshError('algorithm_not_allowed', `invalid token type "${header.typ}"`, 'token typ must be om+jwt');
+    }
+    if (header.alg === 'none') {
+        throw new types_1.OathMeshError('algorithm_not_allowed', 'algorithm "none" is rejected — this is a security redline', 'use EdDSA or ES256');
+    }
+    if (!['EdDSA', 'ES256'].includes(header.alg)) {
+        throw new types_1.OathMeshError('algorithm_not_allowed', `algorithm "${header.alg}" is not allowed`, 'use EdDSA (preferred) or ES256');
+    }
+    // Step 03–04: Extract issuer and check trust
+    let claims;
+    try {
+        claims = (0, jose_1.decodeJwt)(token);
+    }
+    catch {
+        throw new types_1.OathMeshError('verification_failed', 'malformed token payload', 'check token format');
+    }
+    const iss = claims.iss;
+    if (!iss) {
+        throw new types_1.OathMeshError('claim_missing:iss', 'missing iss claim', 'include iss when minting');
+    }
+    if (!trustedIssuers.includes(iss)) {
+        throw new types_1.OathMeshError('issuer_untrusted', `issuer "${iss}" is not in the trusted issuers list`, 'add the issuer URL to your trustedIssuers configuration');
+    }
+    // Step 05–06: Load JWKS and verify signature
+    const jwks = getJWKS(iss);
+    let payload;
+    try {
+        const result = await (0, jose_1.jwtVerify)(token, jwks, {
+            audience,
+            issuer: iss,
+            clockTolerance: 10,
+        });
+        payload = result.payload;
+    }
+    catch (err) {
+        throw mapJoseError(err, audience);
+    }
+    // Step 11: Verify required claims
+    if (!payload.sub)
+        throw new types_1.OathMeshError('claim_missing:sub', 'missing sub claim', 'include sub when minting');
+    if (!payload.act)
+        throw new types_1.OathMeshError('claim_missing:act', 'missing act claim', 'include act when minting');
+    if (!payload.jti)
+        throw new types_1.OathMeshError('claim_missing:jti', 'missing jti claim', 'jti is auto-generated by the issuer');
+    // Step 12b: Enforce rqh if RequireRequestBinding is set
+    if (config.requireRequestBinding && !payload.rqh) {
+        throw new types_1.OathMeshError('binding_required', 'token missing rqh (request hash) claim', 'mint a token with rqh= sha256:<canonical-request> for write/mutate operations');
+    }
+    // Step 13: Check replay cache (if configured)
+    if (config.replayCache) {
+        const jti = payload.jti;
+        if (config.replayCache.check(jti)) {
+            throw new types_1.OathMeshError('replay_detected', `token ${jti} has already been used`, 'each Oath Token can only be used once — mint a new token');
+        }
+        config.replayCache.add(jti);
+    }
+    // Step 14: Evaluate policy (if configured)
+    if (config.policyEvaluator) {
+        const policyInput = {
+            iss,
+            sub: payload.sub,
+            aud: payload.aud,
+            act: payload.act,
+            scope: payload.scope,
+            env: payload.env,
+        };
+        const decision = await config.policyEvaluator.evaluate(policyInput);
+        if (decision.outcome === 'deny') {
+            throw new types_1.OathMeshError('policy_denied', decision.denyReason || 'policy evaluation denied', 'check policy rules for this request');
+        }
+    }
+    // Build verified context
+    return {
+        principal: {
+            issuer: iss,
+            subject: payload.sub,
+        },
+        action: payload.act,
+        tokenId: payload.jti,
+        environment: payload.env || '',
+        scope: payload.scope,
+        reason: payload.reason,
+        source: payload.src,
+    };
+}
+/**
+ * Map a jose library error to the OathMesh error taxonomy.
+ */
+function mapJoseError(err, audience) {
+    const msg = err.message || '';
+    if (msg.includes('expired') || err.name === 'JWTExpired') {
+        return new types_1.OathMeshError('token_expired', 'token has expired', 'mint a new token — Oath Tokens are short-lived');
+    }
+    if (msg.includes('audience') || err.name === 'JWTClaimValidationFailed') {
+        if (msg.includes('audience')) {
+            return new types_1.OathMeshError('audience_mismatch', 'token audience does not match', `mint with --aud ${audience}`);
+        }
+    }
+    if (msg.includes('signature') || err.name === 'JWSSignatureVerificationFailed') {
+        return new types_1.OathMeshError('signature_invalid', 'JWS signature verification failed', 'check that the token was signed by a trusted issuer');
+    }
+    if (msg.includes('issuer')) {
+        return new types_1.OathMeshError('issuer_untrusted', 'issuer verification failed', 'check trustedIssuers configuration');
+    }
+    return new types_1.OathMeshError('verification_failed', msg || 'token verification failed', 'check token format and issuer availability');
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@oathmesh/sdk",
+  "version": "1.0.2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oathmesh/oathmesh.git",
+    "directory": "sdk/node"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "OathMesh verification SDK for Express.js and Next.js — TypeScript-first",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "require": "./dist/next.js",
+      "import": "./dist/next.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "next": [
+        "dist/next.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "oathmesh",
+    "auth",
+    "middleware",
+    "express",
+    "nextjs",
+    "jwt",
+    "machine-identity",
+    "typescript"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "jose": "^5.2.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.11.0",
+    "@types/supertest": "^7.2.0",
+    "express": "^4.19.0",
+    "express-rate-limit": "^7.1.0",
+    "supertest": "^6.3.3",
+    "typescript": "^5.3.0",
+    "vitest": "^1.4.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0",
+    "next": ">=13.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}