@north-light/crouter-identity 0.0.0 → 0.3.351

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { type JSONWebKeySet, type JWTPayload } from 'jose';
+export interface AccessTokenClaims extends JWTPayload {
+    sub: string;
+    grantee: string;
+    client_id: string;
+    grant: string;
+    exp: number;
+}
+export interface IdTokenClaims extends JWTPayload {
+    sub: string;
+}
+export type Scope = 'crtr:llm' | 'crtr:act' | 'crtr:schedule' | `crtr:memory:${'read' | 'rw'}:user${'' | `:${string}`}` | 'crtr:memory:manage:user' | `crtr:memory:${'read' | 'rw'}:app:${string}` | `crtr:files:${'read' | 'rw'}:${'user' | `app:${string}`}:${string}` | 'crtr:files:share' | `crtr:${'conversations' | 'objects'}:read:app:${string}` | `crtr:peer:${string}` | `${string}:${string}`;
+/** App-memory form keys omit the app id. */
+export declare const ENFORCED: ReadonlySet<string>;
+export declare function parseScope(value: string, grantee?: string): Scope;
+export declare function covers(held: string, requested: string): boolean;
+/** Keys are scoped to one configured issuer; failed refreshes keep the last successful set. */
+export declare class JwksCache {
+    readonly issuer: string;
+    private readonly fetcher;
+    private keys;
+    private lastUnknownRefresh;
+    private discovery;
+    constructor(issuer: string, fetcher?: typeof fetch, jwksUri?: string);
+    load(): Promise<JSONWebKeySet>;
+    forKid(kid: string | undefined): Promise<JSONWebKeySet>;
+}
+export declare function verifyAccessToken(options: {
+    token: string;
+    jwks: JSONWebKeySet | JwksCache;
+    issuer: string;
+    audience: string;
+}): Promise<AccessTokenClaims>;
+export interface SyncNoticeClaims extends JWTPayload {
+    purpose: 'grant_sync';
+    iat: number;
+    exp: number;
+    jti: string;
+}
+/** The directory's grant-sync notice: ES256 with the directory signing key named
+ *  by `kid`, no `typ`, `aud` = the runtime's registered URL, a lifetime of at most
+ *  five minutes, and a `jti` the runtime uses to answer replays without a sync. */
+export declare function verifySyncNotice(options: {
+    token: string;
+    jwks: JSONWebKeySet | JwksCache;
+    issuer: string;
+    audience: string;
+}): Promise<SyncNoticeClaims>;
+export declare function verifyIdToken(options: {
+    token: string;
+    jwks: JSONWebKeySet | JwksCache;
+    issuer: string;
+    audience: string;
+}): Promise<IdTokenClaims>;

package/dist/index.js

@@ -0,0 +1,166 @@
+import { createLocalJWKSet, decodeProtectedHeader, jwtVerify } from 'jose';
+/** App-memory form keys omit the app id. */
+export const ENFORCED = new Set(['crtr:llm', 'crtr:act', 'crtr:memory:read:app', 'crtr:memory:rw:app', 'crtr:files:read:user:.', 'crtr:files:rw:user:.']);
+const id = /^[A-Za-z0-9_-]{1,64}$/;
+function validPath(path, directoryOnly = false) {
+    if (path === '.' && directoryOnly)
+        return true;
+    return path.length > 0 && !path.startsWith('/') && !path.includes('..') && !path.includes(':') &&
+        !path.includes('\\') && !/\s/.test(path) &&
+        !path.split('/').some((part, index, parts) => part === '.' || (part === '' && index !== parts.length - 1)) &&
+        (!directoryOnly || !path.endsWith('/'));
+}
+function selector(value) {
+    if (value === 'crtr:llm' || value === 'crtr:act' || value === 'crtr:schedule')
+        return { kind: value.slice(5), value };
+    if (value === 'crtr:files:share')
+        return { kind: 'share', value };
+    if (value === 'crtr:memory:manage:user')
+        return { kind: 'memory', access: 'manage', holder: 'user' };
+    let match = /^crtr:memory:(read|rw):user(?::(.+))?$/.exec(value);
+    if (match && (match[2] === undefined || validPath(match[2])))
+        return { kind: 'memory', access: match[1], holder: 'user', path: match[2] };
+    match = /^crtr:memory:(read|rw):app:([A-Za-z0-9_-]{1,64})(?::profile:([A-Za-z0-9_-]{1,64})(?::(.+))?)?$/.exec(value);
+    if (match && (match[4] === undefined || validPath(match[4]))) {
+        return { kind: 'memory', access: match[1], holder: `app:${match[2]}`, profile: match[3], path: match[4] };
+    }
+    match = /^crtr:files:(read|rw):(user|app:[A-Za-z0-9_-]{1,64}):(.+)$/.exec(value);
+    if (match && validPath(match[3], true))
+        return { kind: 'files', access: match[1], holder: match[2], path: match[3] };
+    match = /^crtr:(conversations|objects):read:app:([A-Za-z0-9_-]{1,64})$/.exec(value);
+    if (match)
+        return { kind: match[1], value };
+    match = /^crtr:peer:([A-Za-z0-9_-]{1,64})$/.exec(value);
+    if (match)
+        return { kind: 'peer', value };
+    match = /^([^:]+):([^:]+)$/.exec(value);
+    if (match && match[1] !== 'crtr' && id.test(match[1]) && id.test(match[2]))
+        return { kind: 'provider', value };
+    throw new TypeError(`Unsupported scope: ${value}`);
+}
+export function parseScope(value, grantee) {
+    const parsed = selector(value);
+    if (grantee && (parsed.kind === 'memory' || parsed.kind === 'files') && parsed.holder.startsWith('app:') && parsed.holder !== grantee) {
+        throw new TypeError(`Unsupported scope: ${value}`);
+    }
+    return value;
+}
+function containsPath(held, requested) {
+    if (held === undefined)
+        return true;
+    if (requested === undefined)
+        return false;
+    return held === requested || (held.endsWith('/') && requested.startsWith(held));
+}
+export function covers(held, requested) {
+    const h = selector(held);
+    const r = selector(requested);
+    if (h.kind !== r.kind)
+        return false;
+    if (h.kind === 'memory' && r.kind === 'memory') {
+        return h.holder === r.holder && (h.access === r.access || h.access === 'manage' || (h.access === 'rw' && r.access === 'read')) &&
+            (h.profile === undefined || h.profile === r.profile) && containsPath(h.path, r.path);
+    }
+    if (h.kind === 'files' && r.kind === 'files') {
+        return h.holder === r.holder && (h.access === 'rw' || r.access === 'read') &&
+            (h.path === '.' || h.path === r.path || r.path.startsWith(`${h.path}/`));
+    }
+    return held === requested;
+}
+/** Keys are scoped to one configured issuer; failed refreshes keep the last successful set. */
+export class JwksCache {
+    issuer;
+    fetcher;
+    keys;
+    lastUnknownRefresh = -Infinity;
+    discovery;
+    constructor(issuer, fetcher = fetch, jwksUri) {
+        this.issuer = issuer;
+        this.fetcher = fetcher;
+        if (jwksUri)
+            this.discovery = { jwks_uri: jwksUri };
+    }
+    async load() {
+        if (!this.discovery) {
+            const response = await this.fetcher(`${this.issuer.replace(/\/$/, '')}/.well-known/openid-configuration`);
+            if (!response.ok)
+                throw new Error(`Directory discovery failed: ${response.status}`);
+            const value = await response.json();
+            if (!value || typeof value !== 'object' || !('jwks_uri' in value) || typeof value.jwks_uri !== 'string')
+                throw new Error('Directory discovery has no jwks_uri');
+            this.discovery = { jwks_uri: value.jwks_uri };
+        }
+        const response = await this.fetcher(this.discovery.jwks_uri);
+        if (!response.ok)
+            throw new Error(`Directory JWKS failed: ${response.status}`);
+        const keys = await response.json();
+        if (!keys || typeof keys !== 'object' || !('keys' in keys) || !Array.isArray(keys.keys))
+            throw new Error('Invalid directory JWKS');
+        this.keys = keys;
+        return this.keys;
+    }
+    async forKid(kid) {
+        if (!this.keys)
+            return this.load();
+        if (this.keys.keys.some((key) => key.kid === kid))
+            return this.keys;
+        if (Date.now() - this.lastUnknownRefresh >= 30_000) {
+            this.lastUnknownRefresh = Date.now();
+            await this.load();
+        }
+        return this.keys;
+    }
+}
+function validatePrincipal(value, kind) {
+    return typeof value === 'string' && value.startsWith(`${kind}:`) && id.test(value.slice(kind.length + 1));
+}
+function keySet(jwks, kid) {
+    return jwks instanceof JwksCache ? jwks.forKid(kid) : Promise.resolve(jwks);
+}
+export async function verifyAccessToken(options) {
+    const header = decodeProtectedHeader(options.token);
+    if (header.typ !== 'at+jwt' || header.alg !== 'ES256')
+        throw new Error('Invalid access token header');
+    const keys = await keySet(options.jwks, header.kid);
+    const { payload } = await jwtVerify(options.token, createLocalJWKSet(keys), {
+        issuer: options.issuer, audience: options.audience, algorithms: ['ES256'], typ: 'at+jwt',
+    });
+    if (payload.aud !== options.audience || !validatePrincipal(payload.sub, 'user') || !validatePrincipal(payload.grantee, 'app') ||
+        typeof payload.client_id !== 'string' || !id.test(payload.client_id) || typeof payload.grant !== 'string' ||
+        typeof payload.exp !== 'number') {
+        throw new Error('Invalid access token claims');
+    }
+    return payload;
+}
+/** The directory's grant-sync notice: ES256 with the directory signing key named
+ *  by `kid`, no `typ`, `aud` = the runtime's registered URL, a lifetime of at most
+ *  five minutes, and a `jti` the runtime uses to answer replays without a sync. */
+export async function verifySyncNotice(options) {
+    const header = decodeProtectedHeader(options.token);
+    if (header.alg !== 'ES256')
+        throw new Error('Invalid sync notice algorithm');
+    if (typeof header.kid !== 'string' || header.kid === '')
+        throw new Error('Sync notice has no key id');
+    const keys = await keySet(options.jwks, header.kid);
+    const { payload } = await jwtVerify(options.token, createLocalJWKSet(keys), {
+        issuer: options.issuer, audience: options.audience, algorithms: ['ES256'], requiredClaims: ['exp', 'iat', 'jti'],
+        maxTokenAge: 300, clockTolerance: 30,
+    });
+    if (payload.aud !== options.audience || payload.purpose !== 'grant_sync' || typeof payload.jti !== 'string' || payload.jti === '' ||
+        typeof payload.exp !== 'number' || typeof payload.iat !== 'number' || payload.exp - payload.iat > 300) {
+        throw new Error('Invalid sync notice claims');
+    }
+    return payload;
+}
+export async function verifyIdToken(options) {
+    const header = decodeProtectedHeader(options.token);
+    if (header.alg !== 'ES256')
+        throw new Error('Invalid ID token algorithm');
+    const keys = await keySet(options.jwks, header.kid);
+    const { payload } = await jwtVerify(options.token, createLocalJWKSet(keys), {
+        issuer: options.issuer, audience: options.audience, algorithms: ['ES256'],
+    });
+    if (payload.aud !== options.audience || typeof payload.exp !== 'number' || !validatePrincipal(payload.sub, 'user'))
+        throw new Error('Invalid ID token claims');
+    return payload;
+}

package/package.json

@@ -1,9 +1,33 @@
 {
   "name": "@north-light/crouter-identity",
-  "version": "0.0.0",
-  "description": "Placeholder. Real versions of Northlight access-token verification and scope rules are published from CI.",
-  "files": ["README.md"],
-  "publishConfig": {"access": "public"},
-  "repository": {"type": "git", "url": "git+https://github.com/vallum-security/crouter.git", "directory": "packages/crouter-identity"},
+  "version": "0.3.351",
+  "description": "Northlight access-token verification and scope rules",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "jose": "^6.2.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vallum-security/crouter.git",
+    "directory": "packages/crouter-identity"
+  },
   "license": "GPL-3.0-only"
 }

package/README.md

@@ -1,3 +0,0 @@
-# @north-light/crouter-identity
-
-This 0.0.0 version is an empty placeholder that reserves the package name. Real versions are published by the crouter release workflow. Do not install 0.0.0.