@rakomi/node 0.0.0 → 0.1.0

package/dist/verify-token.js

@@ -0,0 +1,148 @@
+import { decodeProtectedHeader, errors as joseErrors, jwtVerify } from 'jose';
+import { AUTH_ENVIRONMENT_MISMATCH, TOKEN_EXPIRED, TOKEN_INVALID_ALGORITHM, TOKEN_INVALID_AUDIENCE, TOKEN_INVALID_ISSUER, TOKEN_INVALID_SIGNATURE, TOKEN_MALFORMED, TOKEN_MISSING_CLAIMS, TOKEN_NOT_YET_VALID, TOKEN_REVOKED, } from './errors.js';
+const ISSUER = 'https://rakomi.com';
+const AUDIENCE = 'https://rakomi.com';
+const ALLOWED_ALGORITHMS = ['RS256'];
+const REQUIRED_CLAIMS = ['sub', 'tenant_id', 'iss', 'aud', 'exp', 'iat', 'jti'];
+const USER_REQUIRED_CLAIMS = ['email', 'sid'];
+export async function verifyToken(token, jwksCache, clockTolerance, sdkEnvironment) {
+    let kid;
+    try {
+        const header = decodeProtectedHeader(token);
+        if (header.alg !== 'RS256') {
+            return { ok: false, error: TOKEN_INVALID_ALGORITHM() };
+        }
+        kid = header.kid;
+    }
+    catch {
+        return { ok: false, error: TOKEN_MALFORMED() };
+    }
+    if (!kid) {
+        return { ok: false, error: TOKEN_MALFORMED() };
+    }
+    const keyResult = await jwksCache.getKey(kid);
+    if (!keyResult.ok) {
+        return keyResult;
+    }
+    try {
+        const { payload } = await jwtVerify(token, keyResult.data, {
+            algorithms: [...ALLOWED_ALGORITHMS],
+            issuer: ISSUER,
+            audience: AUDIENCE,
+            clockTolerance,
+            maxTokenAge: '3660s',
+        });
+        if (Array.isArray(payload.aud)) {
+            return { ok: false, error: TOKEN_INVALID_AUDIENCE() };
+        }
+        for (const claim of REQUIRED_CLAIMS) {
+            if (payload[claim] === undefined || payload[claim] === null) {
+                return { ok: false, error: TOKEN_MISSING_CLAIMS() };
+            }
+        }
+        const isM2MToken = payload.m2m === true;
+        if (!isM2MToken) {
+            for (const claim of USER_REQUIRED_CLAIMS) {
+                if (payload[claim] === undefined || payload[claim] === null) {
+                    return { ok: false, error: TOKEN_MISSING_CLAIMS() };
+                }
+            }
+        }
+        const epoch = jwksCache.getRevocationEpoch();
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        if (epoch && epoch > 0 && epoch <= nowSeconds) {
+            if (payload.iat === undefined || payload.iat < epoch) {
+                return { ok: false, error: TOKEN_REVOKED() };
+            }
+        }
+        if (sdkEnvironment && payload.rkm_env) {
+            const tokenEnv = payload.rkm_env;
+            const sdkIsLive = sdkEnvironment === 'live';
+            const tokenIsLive = tokenEnv === 'live';
+            if (sdkIsLive !== tokenIsLive) {
+                return { ok: false, error: AUTH_ENVIRONMENT_MISMATCH() };
+            }
+        }
+        const mapped = {
+            userId: payload.sub,
+            ...(payload.email ? { email: payload.email } : {}),
+            tenantId: payload.tenant_id,
+            ...(payload.sid ? { sessionId: payload.sid } : {}),
+            iss: payload.iss,
+            aud: (Array.isArray(payload.aud) ? payload.aud[0] : payload.aud),
+            exp: payload.exp,
+            iat: payload.iat,
+            jti: payload.jti,
+            ...(payload.mfa_verified === true ? {
+                mfaVerified: true,
+                mfaVerifiedAt: payload.mfa_verified_at,
+            } : {}),
+            ...(payload.amr ? { amr: payload.amr } : {}),
+            ...(payload.acr ? { acr: payload.acr } : {}),
+            ...(payload.auth_time != null ? { authTime: payload.auth_time } : {}),
+            roles: payload.roles ?? [],
+            permissions: payload.permissions ?? [],
+            ...(payload.rkm_env ? { environment: payload.rkm_env } : {}),
+            ...(payload.public_metadata ? { publicMetadata: payload.public_metadata } : {}),
+            ...(typeof payload.is_minor === 'boolean' ? { isMinor: payload.is_minor } : {}),
+            ...(payload.subscription ? { subscription: payload.subscription } : {}),
+            ...(payload.m2m === true ? { isM2M: true } : {}),
+            ...(payload.client_id ? { clientId: payload.client_id } : {}),
+            ...(payload.scope ? { scopes: payload.scope.split(' ').filter(Boolean) } : {}),
+        };
+        const actClaim = payload.act;
+        if (actClaim && typeof actClaim === 'object' && typeof actClaim.sub === 'string') {
+            mapped.isAgentToken = true;
+            const tokenScopes = typeof payload.scope === 'string'
+                ? payload.scope.split(' ').filter(Boolean)
+                : [];
+            mapped.agent = { clientId: actClaim.sub, scopes: tokenScopes };
+        }
+        if (!mapped.isM2M) {
+            const nowSecondsForMeta = Math.floor(Date.now() / 1000);
+            const expiresIn = Math.max(0, payload.exp - nowSecondsForMeta);
+            const tokenMeta = { expiresIn };
+            const session = {
+                expiresAt: new Date(payload.exp * 1000).toISOString(),
+                isExpiringSoon: false,
+            };
+            if (typeof payload.session_max_lifetime_exp === 'number') {
+                session.maxLifetimeExpiresAt = new Date(payload.session_max_lifetime_exp * 1000).toISOString();
+            }
+            const maxLifeRemaining = typeof payload.session_max_lifetime_exp === 'number'
+                ? Math.max(0, payload.session_max_lifetime_exp - nowSecondsForMeta)
+                : Infinity;
+            session.isExpiringSoon = Math.min(tokenMeta.expiresIn, maxLifeRemaining) < 300;
+            mapped.session = session;
+            mapped.token = tokenMeta;
+        }
+        return { ok: true, data: mapped };
+    }
+    catch (err) {
+        return { ok: false, error: mapJoseError(err) };
+    }
+}
+function mapJoseError(err) {
+    if (err instanceof joseErrors.JWTExpired) {
+        return TOKEN_EXPIRED();
+    }
+    if (err instanceof joseErrors.JWSSignatureVerificationFailed) {
+        return TOKEN_INVALID_SIGNATURE();
+    }
+    if (err instanceof joseErrors.JWTClaimValidationFailed) {
+        if (err.claim === 'iss') {
+            return TOKEN_INVALID_ISSUER();
+        }
+        if (err.claim === 'aud') {
+            return TOKEN_INVALID_AUDIENCE();
+        }
+        if (err.claim === 'nbf') {
+            return TOKEN_NOT_YET_VALID();
+        }
+        return TOKEN_MISSING_CLAIMS();
+    }
+    if (err instanceof joseErrors.JOSEError) {
+        return TOKEN_MALFORMED();
+    }
+    return TOKEN_MALFORMED();
+}

package/dist/verify-webhook.d.ts

@@ -0,0 +1,7 @@
+import type { VerifyResult, WebhookEvent, WebhookVerifyData } from './types.js';
+/**
+ * Case-insensitive header lookup (RFC 9110 §5.1). Exported so the publisher wrapper can read the
+ * `X-Rakomi-Event` header with the identical lookup semantics (no second header parser to drift).
+ */
+export declare function getHeader(headers: Record<string, string | string[] | undefined>, name: string): string | undefined;
+export declare function verifyWebhook<T = WebhookEvent>(body: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string, tolerance: number): Promise<VerifyResult<WebhookVerifyData<T>>>;

package/dist/verify-webhook.js

@@ -0,0 +1,101 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { WEBHOOK_INVALID_BODY, WEBHOOK_INVALID_SECRET, WEBHOOK_INVALID_SIGNATURE, WEBHOOK_MISSING_HEADER, WEBHOOK_TIMESTAMP_TOO_NEW, WEBHOOK_TIMESTAMP_TOO_OLD, } from './errors.js';
+const RKSEC_PREFIX = 'rksec_';
+const EXPECTED_KEY_LENGTH = 32;
+/**
+ * Case-insensitive header lookup (RFC 9110 §5.1). Exported so the publisher wrapper can read the
+ * `X-Rakomi-Event` header with the identical lookup semantics (no second header parser to drift).
+ */
+export function getHeader(headers, name) {
+    const lower = name.toLowerCase();
+    let value = headers[lower];
+    if (value === undefined) {
+        for (const key of Object.keys(headers)) {
+            if (key.toLowerCase() === lower) {
+                value = headers[key];
+                break;
+            }
+        }
+    }
+    if (Array.isArray(value))
+        return value[0]?.trim();
+    return value?.trim();
+}
+/**
+ * Derive the raw HMAC key from a webhook signing secret.
+ * Prefixed secrets (`rksec_<base64url>`) are stripped and base64url-decoded
+ * to recover the original 32-byte key. Plain strings are used as-is.
+ * Validates decoded key is exactly 32 bytes.
+ */
+function deriveKey(secret) {
+    if (secret.startsWith(RKSEC_PREFIX)) {
+        const key = Buffer.from(secret.slice(RKSEC_PREFIX.length), 'base64url');
+        if (key.length !== EXPECTED_KEY_LENGTH) {
+            return null;
+        }
+        return key;
+    }
+    return Buffer.from(secret, 'utf8');
+}
+export async function verifyWebhook(body, headers, secret, tolerance) {
+    try {
+        const signature = getHeader(headers, 'webhook-signature');
+        const timestampStr = getHeader(headers, 'webhook-timestamp');
+        const webhookId = getHeader(headers, 'webhook-id');
+        const deliveryId = getHeader(headers, 'x-rakomi-delivery-id');
+        if (!signature || !timestampStr || !webhookId) {
+            return { ok: false, error: WEBHOOK_MISSING_HEADER() };
+        }
+        const timestamp = parseInt(timestampStr, 10);
+        if (isNaN(timestamp)) {
+            return { ok: false, error: WEBHOOK_MISSING_HEADER() };
+        }
+        const now = Math.floor(Date.now() / 1000);
+        const diff = now - timestamp;
+        if (diff > tolerance) {
+            return { ok: false, error: WEBHOOK_TIMESTAMP_TOO_OLD(tolerance) };
+        }
+        if (diff < -tolerance) {
+            return { ok: false, error: WEBHOOK_TIMESTAMP_TOO_NEW(tolerance) };
+        }
+        const key = deriveKey(secret);
+        if (!key) {
+            return { ok: false, error: WEBHOOK_INVALID_SECRET() };
+        }
+        const bodyString = typeof body === 'string' ? body : body.toString('utf-8');
+        const signedContent = `${webhookId}.${timestampStr}.${bodyString}`;
+        const expectedSig = createHmac('sha256', key)
+            .update(signedContent)
+            .digest('base64');
+        const signatureEntries = signature.split(' ').map((s) => s.trim()).filter(Boolean);
+        let matched = false;
+        for (const entry of signatureEntries) {
+            if (!entry.startsWith('v1,'))
+                continue;
+            const receivedSig = entry.slice(3);
+            try {
+                const expectedRaw = Buffer.from(expectedSig, 'base64');
+                const receivedRaw = Buffer.from(receivedSig, 'base64');
+                if (expectedRaw.length === 32 &&
+                    receivedRaw.length === 32 &&
+                    timingSafeEqual(expectedRaw, receivedRaw)) {
+                    matched = true;
+                    break;
+                }
+            }
+            catch {
+            }
+        }
+        if (!matched) {
+            return { ok: false, error: WEBHOOK_INVALID_SIGNATURE() };
+        }
+        const parsed = JSON.parse(bodyString);
+        return {
+            ok: true,
+            data: { webhookId, deliveryId: deliveryId ?? webhookId, timestamp, payload: parsed },
+        };
+    }
+    catch {
+        return { ok: false, error: WEBHOOK_INVALID_BODY() };
+    }
+}

package/package.json

@@ -1,7 +1,63 @@
 {
   "name": "@rakomi/node",
-  "version": "0.0.0",
-  "description": "Reserved placeholder — first stable release published via OIDC provenance. Do not install.",
-  "license": "Apache-2.0",
-  "private": false
-}
+  "version": "0.1.0",
+  "description": "Server-side Node.js SDK for Rakomi — verify access tokens and webhook signatures. EU-native auth-as-a-service.",
+  "keywords": [
+    "rakomi",
+    "authentication",
+    "auth",
+    "oauth",
+    "oidc",
+    "jwt",
+    "jwks",
+    "webhook",
+    "sdk",
+    "nodejs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rakomidev/rakomi-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rakomidev/rakomi-js/issues"
+  },
+  "homepage": "https://github.com/rakomidev/rakomi-js#readme",
+  "rakomi": {
+    "apiVersion": "2026-03-01"
+  },
+  "publishConfig": {
+    "provenance": true
+  },
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "rakomi-doctor": "./dist/doctor.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "author": "CRE8EVE Sp. z o.o.",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "sbom.cdx.json"
+  ],
+  "dependencies": {
+    "jose": "^6.2.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.typetest.json",
+    "lint": "eslint src/ test/ --max-warnings=0",
+    "test": "vitest run"
+  }
+}

package/sbom.cdx.json

@@ -0,0 +1,52 @@
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.6",
+  "version": 1,
+  "metadata": {
+    "authors": [
+      {
+        "name": "CRE8EVE"
+      }
+    ],
+    "tools": {
+      "components": [
+        {
+          "type": "application",
+          "group": "rakomi",
+          "name": "generate-sbom",
+          "version": "sha256:6612f58a07b8"
+        }
+      ]
+    },
+    "component": {
+      "type": "library",
+      "bom-ref": "pkg:npm/%40rakomi%2Fnode@0.1.0",
+      "name": "@rakomi/node",
+      "version": "0.1.0",
+      "purl": "pkg:npm/%40rakomi%2Fnode@0.1.0",
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT"
+          }
+        }
+      ]
+    }
+  },
+  "components": [
+    {
+      "type": "library",
+      "bom-ref": "pkg:npm/jose@6.2.3",
+      "name": "jose",
+      "version": "6.2.3",
+      "purl": "pkg:npm/jose@6.2.3",
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT"
+          }
+        }
+      ]
+    }
+  ]
+}