@crouter/identity 0.3.377

package/README.md

@@ -0,0 +1,90 @@
+# @crouter/identity — verify directory-issued tokens and evaluate crouter scopes
+
+![crouter](https://raw.githubusercontent.com/crouton-labs/crouter/main/assets/banner.svg)
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@crouter/identity"><img alt="npm" src="https://img.shields.io/npm/v/@crouter/identity?label=npm"></a>
+  <a href="https://github.com/crouton-labs/crouter/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/license-GPL--3.0-blue"></a>
+</p>
+
+`@crouter/identity` is the token contract shared by crouter's runtime, [`@crouter/sdk`](../crouter-sdk) and [`@crouter/plugin`](../crouter-plugin). It does two things: it verifies the signed JWTs that a crouter cloud directory issues (access tokens, ID tokens, outbound provider tokens and grant-sync notices) against the directory's published keys, and it parses and compares scope strings such as `crtr:llm` or `crtr:memory:read:user:work/`. It is ESM-only, depends only on [`jose`](https://github.com/panva/jose), and has no side effects on import.
+
+It is a verifier, not an identity provider. It never issues, signs or stores tokens, and it does not run a login flow; the directory does that. Most applications do not import it directly: the SDK's OAuth helpers and the plugin kit's `auth` option call it for you. Use it when you write your own provider or service that receives these tokens.
+
+[Docs](https://docs.crouter.ai/docs/concepts/scopes-and-trust) · [Plugin authentication](https://docs.crouter.ai/docs/plugin/deploying) · [Apps with many users](https://docs.crouter.ai/docs/sdk/guides/apps-with-many-users) · [crouter repository](https://github.com/crouton-labs/crouter)
+
+## Install
+
+```bash
+npm install @crouter/identity
+```
+
+## Verify a token
+
+Every verifier takes `{ token, jwks, issuer, audience }` and returns the typed claims or throws. `jwks` is either a static JWKS object or a `JwksCache`.
+
+```ts
+import { JwksCache, verifyOutboundToken } from '@crouter/identity';
+
+const issuer = 'https://directory.example.com';
+const jwks = new JwksCache(issuer, fetch, `${issuer}/.well-known/jwks.json`);
+
+export async function authorize(request: Request) {
+  const token = request.headers.get('authorization')?.replace(/^Bearer /, '') ?? '';
+  const claims = await verifyOutboundToken({
+    token,
+    jwks,
+    issuer,
+    audience: 'https://provider.example.com/crtr', // exactly the URL the provider registered
+  });
+  return claims.scope.split(' '); // the provider's `<provider>:<group>` strings the caller holds
+}
+```
+
+`JwksCache` keeps the last good key set for one issuer. When a token names a `kid` it has not seen, it refetches, at most once every 30 seconds, and concurrent requests share that fetch. A failed refresh leaves the previous keys in place. If you omit the third argument, it discovers `jwks_uri` from `<issuer>/.well-known/openid-configuration`.
+
+| Function | Checks | Returns |
+|---|---|---|
+| `verifyAccessToken` | `typ: at+jwt`, ES256, signature, `iss`, `aud`, `exp`; `sub` is `user:<id>`, `grantee` is `app:<id>` | `AccessTokenClaims` (`sub`, `grantee`, `client_id`, `grant`, `exp`) |
+| `verifyOutboundToken` | `typ: at+jwt`, ES256 or RS256 with a `kid`, signature, `iss`, `aud`, `exp`; claim presence and types, including `scope`, `initiating_app`, `act`, `jti` | `OutboundTokenClaims` |
+| `verifyIdToken` | ES256, signature, `iss`, `aud`, `exp`; `sub` is `user:<id>` | `IdTokenClaims` (`email*` when `email` was granted; `name`, `given_name`, `family_name` when `profile` was) |
+| `verifySyncNotice` | ES256 with a `kid`, `purpose: grant_sync`, lifetime of at most five minutes, 30 s clock tolerance | `SyncNoticeClaims` (`jti`, `iat`, `exp`) |
+
+`aud` must match exactly; a trailing-slash difference is refused. The `act` claim of an outbound token is for audit only: nothing in this package authorizes on it.
+
+## Parse and compare scopes
+
+```ts
+import { parseScope, covers } from '@crouter/identity';
+
+parseScope('crtr:files:rw:user:reports');            // returns the string, typed as Scope
+parseScope('crtr:files:rw:user:../etc');             // throws TypeError: Unsupported scope
+
+covers('crtr:memory:rw:user', 'crtr:memory:read:user:work'); // true: rw covers read, no path covers any path
+covers('crtr:memory:read:user', 'crtr:memory:rw:user');      // false
+covers('crtr:files:rw:user:.', 'crtr:files:read:user:a/b');  // true: `.` is the whole directory
+```
+
+The grammar `parseScope` accepts:
+
+| Scope | Meaning |
+|---|---|
+| `crtr:llm`, `crtr:act`, `crtr:schedule` | Model calls and starting runs; acting on nodes, files and bash; scheduling crons |
+| `crtr:memory:read:user[:path]`, `crtr:memory:rw:user[:path]`, `crtr:memory:manage:user` | The person's documents, optionally limited to a path; `manage` covers both access levels |
+| `crtr:memory:read\|rw:app:<id>[:profile:<profile>[:path]]` | An app's documents |
+| `crtr:files:read\|rw:user:<dir>`, `crtr:files:read\|rw:app:<id>:<dir>`, `crtr:files:share` | Host files a run may mount, and sharing them |
+| `crtr:conversations:read:app:<id>`, `crtr:objects:read:app:<id>` | Reading another app's conversations or node objects |
+| `crtr:peer:<id>` | A peer grant |
+| `<provider>:<group>` | A capability provider's own scope, such as the ones in an outbound token's `scope` |
+
+Paths are relative and refuse `..`, `:`, backslashes, whitespace and empty segments. A memory path ending in `/` covers that directory and everything below it; a file path names a directory and covers it and everything below, with `.` meaning the whole root. Passing `grantee` as the second argument to `parseScope` also refuses an `app:` holder other than the grantee. `ENFORCED` is the set of scopes `crtr sys connect --scopes` accepts when it mints a token. What each scope allows is in [Scopes and trust](https://docs.crouter.ai/docs/concepts/scopes-and-trust).
+
+## Related
+
+- [`@crouter/sdk`](../crouter-sdk): uses this package for ID-token verification and scope validation in its OAuth helpers.
+- [`@crouter/plugin`](../crouter-plugin): verifies the directory's outbound tokens for providers registered in the directory.
+- [Main repository](https://github.com/crouton-labs/crouter): the `crtr` CLI, the `crtrd` daemon, and [contributing guidelines](https://github.com/crouton-labs/crouter/blob/main/CONTRIBUTING.md).
+
+## License
+
+[GPL-3.0-only](https://github.com/crouton-labs/crouter/blob/main/LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+import { type JSONWebKeySet, type JWTPayload } from 'jose';
+export interface AccessTokenClaims extends JWTPayload {
+    sub: string;
+    grantee: string;
+    client_id: string;
+    grant: string;
+    exp: number;
+}
+/** `email*` appear when `email` was granted; `name`, `given_name`, `family_name` when `profile` was granted and the person has a name. A person with no name has none of the three: never the phone number. `picture` (an https URL of the person's Google photo) when `profile` was granted and the account has one. */
+export interface IdTokenClaims extends JWTPayload {
+    sub: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    picture?: 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 loading;
+    private discovery;
+    constructor(issuer: string, fetcher?: typeof fetch, jwksUri?: string);
+    load(): Promise<JSONWebKeySet>;
+    private fetchKeys;
+    forKid(kid: string | undefined): Promise<JSONWebKeySet>;
+}
+export declare function verifyAccessToken(options: {
+    token: string;
+    jwks: JSONWebKeySet | JwksCache;
+    issuer: string;
+    audience: string;
+}): Promise<AccessTokenClaims>;
+/** One level of the outbound token's RFC 8693 `act` nesting: the actor, and the actor it acted for. */
+export interface OutboundActor {
+    sub: string;
+    act?: OutboundActor;
+}
+/** The claims of the outbound token the directory mints for one provider call (contract 3). */
+export interface OutboundTokenClaims extends JWTPayload {
+    iss: string;
+    aud: string;
+    /** The user the call is made for, `user:<id>`. */
+    sub: string;
+    /** The principal the grant was issued to, `app:<id>` or the user. */
+    grantee: string;
+    /** The runtime's registered OAuth client id. */
+    client_id: string;
+    /** The provider's `<provider>:<group>` strings the caller holds, space-separated; may be empty. */
+    scope: string;
+    initiating_app: string;
+    /** Audit only; nothing authorizes on it. */
+    act: OutboundActor;
+    iat: number;
+    exp: number;
+    jti: string;
+}
+/**
+ * Verifies the outbound token a provider receives (contract 3 D3-TOK-12): ES256 or RS256 with
+ * a `kid`, typ `at+jwt`, signature against `jwks` (a `JwksCache` refetches once on an unknown
+ * `kid`), `iss` = `issuer`, `aud` exactly `audience` (a trailing-slash difference is refused),
+ * and `exp`. `sub` must be a `user:` principal and `grantee` and `initiating_app`
+ * an `app:` or `user:` principal; the remaining claims are checked for presence and type only; which of them gates a
+ * call is the caller's rule (D3-TOK-13 gates on `scope` alone, and nothing gates on `act`).
+ */
+export declare function verifyOutboundToken(options: {
+    token: string;
+    jwks: JSONWebKeySet | JwksCache;
+    issuer: string;
+    audience: string;
+}): Promise<OutboundTokenClaims>;
+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,218 @@
+import { createLocalJWKSet, decodeProtectedHeader, jwtVerify } from 'jose';
+/** App-memory form keys omit the app id. */
+export const ENFORCED = new Set(['crtr:llm', 'crtr:act', 'crtr:schedule', 'crtr:memory:read:user', '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;
+    loading;
+    discovery;
+    constructor(issuer, fetcher = fetch, jwksUri) {
+        this.issuer = issuer;
+        this.fetcher = fetcher;
+        if (jwksUri)
+            this.discovery = { jwks_uri: jwksUri };
+    }
+    async load() {
+        if (this.loading)
+            return this.loading;
+        const loading = this.fetchKeys();
+        this.loading = loading;
+        try {
+            return await loading;
+        }
+        finally {
+            this.loading = undefined;
+        }
+    }
+    async fetchKeys() {
+        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;
+        // Concurrent requests for a newly published kid must await the same refetch, not use
+        // the stale set while the 30-second unknown-kid throttle is running.
+        if (this.loading)
+            return this.loading;
+        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;
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}
+function appOrUser(value) {
+    return validatePrincipal(value, 'app') || validatePrincipal(value, 'user');
+}
+function isActor(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && nonEmptyString(value.sub);
+}
+/**
+ * Verifies the outbound token a provider receives (contract 3 D3-TOK-12): ES256 or RS256 with
+ * a `kid`, typ `at+jwt`, signature against `jwks` (a `JwksCache` refetches once on an unknown
+ * `kid`), `iss` = `issuer`, `aud` exactly `audience` (a trailing-slash difference is refused),
+ * and `exp`. `sub` must be a `user:` principal and `grantee` and `initiating_app`
+ * an `app:` or `user:` principal; the remaining claims are checked for presence and type only; which of them gates a
+ * call is the caller's rule (D3-TOK-13 gates on `scope` alone, and nothing gates on `act`).
+ */
+export async function verifyOutboundToken(options) {
+    const header = decodeProtectedHeader(options.token);
+    if (header.typ !== 'at+jwt' || (header.alg !== 'ES256' && header.alg !== 'RS256'))
+        throw new Error('Invalid outbound token header');
+    if (!nonEmptyString(header.kid))
+        throw new Error('Outbound token 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', 'RS256'], typ: 'at+jwt', requiredClaims: ['exp'],
+    });
+    if (payload.aud !== options.audience || typeof payload.exp !== 'number' || typeof payload.iat !== 'number' ||
+        !validatePrincipal(payload.sub, 'user') || !appOrUser(payload.grantee) || !nonEmptyString(payload.client_id) ||
+        typeof payload.scope !== 'string' || !appOrUser(payload.initiating_app) || !isActor(payload.act) ||
+        !nonEmptyString(payload.jti)) {
+        throw new Error('Invalid outbound 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

@@ -0,0 +1,33 @@
+{
+  "name": "@crouter/identity",
+  "version": "0.3.377",
+  "description": "crouter cloud 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/crouton-labs/crouter.git",
+    "directory": "packages/crouter-identity"
+  },
+  "license": "GPL-3.0-only"
+}