shutro-erp 0.2.1 → 0.3.1

package/dist/server/auth/service.js

@@ -36,6 +36,7 @@ export class AuthService {
     #shutro;
     #options;
     #cache = new Map();
+    #keyCache = new Map();
     #dummy = hashPassword(randomToken());
     constructor(shutro, options = {}) {
         this.#shutro = shutro;
@@ -212,14 +213,27 @@ export class AuthService {
             throw unauthenticated('two-factor-required', 'Enter the code from your authenticator app first.', 'POST /api/v1/auth/2fa/verify.');
         return session;
     }
-    /** Authenticator for the server (RFC 0002 §6.2): the session's user, company from `X-Company`, groups for it. */
+    /**
+     * Authenticator for the server (RFC 0002 §6.2): the session's user — or the API key's (RFC 0017 §5.1), with its
+     * scopes —, company from `X-Company`, groups for it.
+     */
     async authenticate(request) {
+        const key = await this.apiKeyOf(request);
+        if (key !== null)
+            return this.#identity(request, key.user, {
+                elevated: false,
+                scopes: key.scopes,
+                apiKey: key.id,
+            });
         const session = await this.session(request);
         if (session === null)
             return null;
         if (session.twoFactorRequired)
             throw unauthenticated('two-factor-required', 'Enter the code from your authenticator app first.', 'POST /api/v1/auth/2fa/verify.');
-        const info = await this.#identityOf(session.user);
+        return this.#identity(request, session.user, { elevated: session.secondFactor });
+    }
+    async #identity(request, user, options) {
+        const info = await this.#identityOf(user);
         if (info === null)
             return null;
         const asked = Number(request.headers['x-company']);
@@ -229,8 +243,8 @@ export class AuthService {
         if (company === undefined)
             throw new HttpProblem(403, 'no-company', 'No company', 'This user is not allowed in any company.', 'An administrator assigns the companies of the user.');
         // Mandatory 2FA for administrators (RFC 0003 §5.2): their administrator groups count only in sessions that
-        // entered a second factor, while 2FA is on. The user keeps every other group.
-        const elevated = session.secondFactor && info.twoFactorEnabled;
+        // entered a second factor, while 2FA is on — never through an API key. The user keeps every other group.
+        const elevated = options.elevated && info.twoFactorEnabled;
         const groups = info.assignments
             .filter((a) => a.company === null || a.company === company)
             .map((a) => a.group)
@@ -241,15 +255,225 @@ export class AuthService {
             (g.expiresAt === null || g.expiresAt > now))
             .map((g) => g.grant);
         return {
-            user: session.user,
+            user,
             company,
             companies: info.companies,
             groups: [...new Set(groups)],
             grants: [...new Set(grants)],
             lang: info.lang,
             tz: info.tz,
+            ...(options.scopes === undefined ? {} : { scopes: options.scopes }),
+            ...(options.apiKey === undefined ? {} : { apiKey: options.apiKey }),
         };
     }
+    /**
+     * The request's API key (RFC 0017 §5.1): `X-Api-Key: sk_…` or `Authorization: Bearer sk_…`; null without one.
+     * @throws {HttpProblem} 401 for an `X-Api-Key` that is unknown, revoked or expired
+     */
+    async apiKeyOf(request) {
+        const header = request.headers['x-api-key'];
+        const explicit = typeof header === 'string' && header !== '' ? header : undefined;
+        const bearer = /^Bearer\s+(sk_\S+)$/i.exec(String(request.headers.authorization ?? ''))?.[1];
+        const token = explicit ?? bearer;
+        if (token === undefined)
+            return null;
+        const tokenHash = digest(token);
+        const cached = this.#keyCache.get(tokenHash);
+        if (cached !== undefined && Date.now() - cached.at < this.#options.cacheMs)
+            return cached.key;
+        const key = await this.#system('api key', async (env) => {
+            const row = one(await fetch(model(env, 'auth.api_key').search({ where: { tokenHash, revoked: false } }), [
+                'user',
+                'scopes',
+                'expiresAt',
+                'lastUsedAt',
+            ]));
+            if (row === undefined)
+                return null;
+            const now = Date.now();
+            if ((timeOf(row['expiresAt']) ?? 0) <= now)
+                return null;
+            // Archived users' keys stop working with them.
+            if ((await model(env, 'res.users').search({ where: { id: row['user'] } })).length === 0)
+                return null;
+            if ((timeOf(row['lastUsedAt']) ?? 0) + 5 * 60_000 < now)
+                await model(env, 'auth.api_key')
+                    .browse([row['id']])
+                    .write({ lastUsedAt: new Date(now), lastUsedIp: request.ip });
+            return {
+                id: row['id'],
+                user: row['user'],
+                scopes: String(row['scopes'])
+                    .split(' ')
+                    .filter((x) => x !== ''),
+            };
+        });
+        if (key === null) {
+            this.#keyCache.delete(tokenHash);
+            // A bearer token that is no key may still be a session's.
+            if (explicit === undefined)
+                return null;
+            throw unauthenticated('invalid-api-key', 'The API key is unknown, revoked or expired.', 'Create a new key (Settings › API keys).');
+        }
+        this.#keyCache.set(tokenHash, { at: Date.now(), key });
+        return key;
+    }
+    /** May `actor` manage `user`'s keys: their own, or a service account's when the actor is an administrator. */
+    async #mayManageKeysOf(env, session, user) {
+        if (user === session.user)
+            return true;
+        const [target] = await fetch(model(env, 'res.users').search({ where: { id: user } }), [
+            'isService',
+        ]);
+        return (target?.['isService'] === true &&
+            session.secondFactor &&
+            (await this.#holdsAdministrator(env, session.user)));
+    }
+    /**
+     * A new API key for `user` (the session's own, or a service account's for administrators), with `scopes` already
+     * checked against the installed apps. The secret is returned once.
+     */
+    async createApiKey(session, input, ip) {
+        const days = input.expiresInDays ?? 365;
+        if (!Number.isInteger(days) || days < 1 || days > 730)
+            throw new HttpProblem(400, 'invalid-body', 'Invalid body', 'expiresInDays is 1 to 730.');
+        const name = input.name.trim();
+        if (name === '' || name.length > 100)
+            throw new HttpProblem(400, 'invalid-body', 'Invalid body', 'A key has a name of up to 100 characters.');
+        const user = input.user ?? session.user;
+        return this.#system('create api key', async (env) => {
+            if (!(await this.#mayManageKeysOf(env, session, user)))
+                throw new HttpProblem(403, 'access', 'Forbidden', 'Keys are made for yourself, or by an administrator for a service account.');
+            const token = `sk_${randomToken(30)
+                .replace(/[^A-Za-z0-9]/g, '')
+                .slice(0, 40)}`;
+            const prefix = token.slice(0, 11);
+            const created = await model(env, 'auth.api_key').create([
+                {
+                    name,
+                    user,
+                    tokenHash: digest(token),
+                    prefix,
+                    scopes: input.scopes.join(' '),
+                    expiresAt: new Date(Date.now() + days * 86_400_000),
+                    issuedBy: session.user,
+                },
+            ]);
+            const id = created.ids[0];
+            await audit(env, {
+                kind: 'auth.api_key_created',
+                summary: `API key "${name}" (${prefix}…) created for user ${user}: ${input.scopes.join(' ')}.`,
+                actor: session.user,
+                company: null,
+                details: { key: id, user, scopes: [...input.scopes], expiresInDays: days },
+                ...(ip === undefined ? {} : { ip }),
+            });
+            const [info] = await this.#keys(env, [id]);
+            return { ...info, token };
+        });
+    }
+    async #keys(env, ids, users) {
+        const where = ids !== undefined ? { id: { in: [...ids] } } : { user: { in: [...(users ?? [])] } };
+        const rows = await fetch(model(env, 'auth.api_key').search({ where, order: ['id desc'] }), [
+            'name',
+            'user',
+            'prefix',
+            'scopes',
+            'expiresAt',
+            'lastUsedAt',
+            'lastUsedIp',
+            'revoked',
+            'createdAt',
+        ]);
+        const userIds = [...new Set(rows.map((r) => r['user']))];
+        const names = new Map((userIds.length === 0
+            ? []
+            : await fetch(model(env, 'res.users').search({ where: { id: { in: userIds } } }), ['name'])).map((u) => [u['id'], String(u['name'])]));
+        return rows.map((r) => ({
+            id: r['id'],
+            name: String(r['name']),
+            user: r['user'],
+            userName: names.get(r['user']) ?? '',
+            prefix: String(r['prefix']),
+            scopes: String(r['scopes'])
+                .split(' ')
+                .filter((x) => x !== ''),
+            expiresAt: new Date(timeOf(r['expiresAt']) ?? 0).toISOString(),
+            lastUsedAt: timeOf(r['lastUsedAt']) === null
+                ? null
+                : new Date(timeOf(r['lastUsedAt']) ?? 0).toISOString(),
+            lastUsedIp: typeof r['lastUsedIp'] === 'string' ? r['lastUsedIp'] : null,
+            revoked: r['revoked'] === true,
+        }));
+    }
+    /** The session user's keys, and every service account's for administrators. */
+    async listApiKeys(session) {
+        return this.#system('list api keys', async (env) => {
+            const users = [session.user];
+            if (session.secondFactor && (await this.#holdsAdministrator(env, session.user)))
+                users.push(...(await model(env, 'res.users').search({ where: { isService: true } })).ids);
+            return this.#keys(env, undefined, users);
+        });
+    }
+    /** Revokes a key at once (the session's own, or a service account's for administrators). */
+    async revokeApiKey(session, id, ip) {
+        await this.#system('revoke api key', async (env) => {
+            const [key] = await fetch(model(env, 'auth.api_key').search({ where: { id } }), [
+                'user',
+                'prefix',
+                'tokenHash',
+            ]);
+            if (key === undefined || !(await this.#mayManageKeysOf(env, session, key['user'])))
+                throw new HttpProblem(404, 'missing-record', 'Not found', `There is no API key ${id} of yours.`);
+            await model(env, 'auth.api_key').browse([id]).write({ revoked: true });
+            this.#keyCache.delete(String(key['tokenHash']));
+            await audit(env, {
+                kind: 'auth.api_key_revoked',
+                summary: `API key ${String(key['prefix'])}… revoked.`,
+                actor: session.user,
+                company: null,
+                details: { key: id },
+                ...(ip === undefined ? {} : { ip }),
+            });
+        });
+    }
+    /**
+     * A service account (RFC 0017 §5.1): a user without a password who acts only through API keys, with `groups`
+     * (checked by the caller) in the administrator's companies. Administrators only.
+     */
+    async createServiceAccount(session, input, ip) {
+        return this.#system(`create service account ${input.login}`, async (env) => {
+            if (!(session.secondFactor && (await this.#holdsAdministrator(env, session.user))))
+                throw new HttpProblem(403, 'access', 'Forbidden', 'Service accounts are created by administrators.');
+            const administrators = new Set(env.access.administratorGroups());
+            if (input.groups.some((g) => administrators.has(g)))
+                throw new HttpProblem(422, 'invalid-groups', 'Invalid roles', 'A service account cannot be an administrator.');
+            const [me] = await fetch(model(env, 'res.users').search({ where: { id: session.user } }), [
+                'company',
+            ]);
+            const company = typeof me?.['company'] === 'number' ? me['company'] : undefined;
+            const created = await model(env, 'res.users').create([
+                {
+                    login: input.login,
+                    name: input.name,
+                    isService: true,
+                    ...(company === undefined ? {} : { company, companies: { set: [company] } }),
+                },
+            ]);
+            const id = created.ids[0];
+            if (input.groups.length > 0)
+                await model(env, 'auth.user_group').create(input.groups.map((group) => ({ user: id, group })));
+            await audit(env, {
+                kind: 'auth.service_account_created',
+                summary: `Service account ${input.login} created with ${input.groups.join(', ') || 'no roles'}.`,
+                actor: session.user,
+                company: null,
+                details: { user: id, groups: [...input.groups] },
+                ...(ip === undefined ? {} : { ip }),
+            });
+            return { id, login: input.login, name: input.name, groups: [...input.groups] };
+        });
+    }
     /** Identity loader for Shutro (`createShutro({ identity })`): the user is active; companies and groups from the database. */
     async verify(uid) {
         const info = await this.#identityOf(uid);
@@ -320,12 +544,18 @@ export class AuthService {
             const [credential] = await fetch(model(env, 'auth.credential').search({ where: { user: session.user } }), ['totpEnabled']);
             const administrator = await this.#holdsAdministrator(env, session.user);
             const twoFactorEnabled = credential?.['totpEnabled'] === true;
+            const companyIds = user?.['companies'] ?? [];
+            const groupings = {};
+            if (companyIds.length > 0)
+                for (const c of await fetch(model(env, 'res.company').search({ where: { id: { in: companyIds } } }), ['numberGrouping']))
+                    groupings[String(c['id'])] = c['numberGrouping'] === 'lakh' ? 'lakh' : 'international';
             return {
                 id: session.user,
                 login: String(user?.['login']),
                 name: String(user?.['name']),
                 company: typeof user?.['company'] === 'number' ? user['company'] : null,
-                companies: user?.['companies'] ?? [],
+                companies: companyIds,
+                groupings,
                 twoFactorEnabled,
                 administrator,
                 administratorNeedsSecondFactor: administrator && !(session.secondFactor && twoFactorEnabled),

package/dist/server/demo.d.ts

@@ -8,7 +8,7 @@ import type { KoshModule } from '../modules-sdk/index.js';
 import type { AuthService } from './auth/service.js';
 import type { Driver, Shutro } from './orm.js';
 /** The demo users' password (every demo user; printed by `kosh init --demo`). */
-export declare const DEMO_PASSWORD = "kosh demo 2026";
+export declare const DEMO_PASSWORD = "shutro demo 2026";
 /** What one module's seeder did. */
 export interface DemoResult {
     readonly module: string;

package/dist/server/demo.js

@@ -1,6 +1,6 @@
 import { APPS_TABLE, appTableStatements } from './apps.js';
 /** The demo users' password (every demo user; printed by `kosh init --demo`). */
-export const DEMO_PASSWORD = 'kosh demo 2026';
+export const DEMO_PASSWORD = 'shutro demo 2026';
 const model = (env, name) => env.model(name);
 /** Loads the demo data of the modules that have none yet. Returns a line per module that seeded something. */
 export async function installDemo(options) {

package/dist/server/env-names.d.ts

@@ -0,0 +1,2 @@
+/** Copies `SHUTRO_ERP_*` variables to their `KOSH_*` names in `env` (the process's by default); returns `env`. */
+export declare function applyEnvironmentNames(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/server/env-names.js

@@ -0,0 +1,16 @@
+/**
+ * The environment's names: installations set `SHUTRO_ERP_*` (the product's name, as in the docs and new projects);
+ * the code reads the older `KOSH_*` names, which keep working. Applied once where a process starts (the server, the
+ * CLI): each `SHUTRO_ERP_X` that is set fills `KOSH_X` unless that one is set too.
+ */
+const PREFIX = 'SHUTRO_ERP_';
+/** Copies `SHUTRO_ERP_*` variables to their `KOSH_*` names in `env` (the process's by default); returns `env`. */
+export function applyEnvironmentNames(env = process.env) {
+    for (const [name, value] of Object.entries(env))
+        if (name.startsWith(PREFIX) && value !== undefined) {
+            const old = `KOSH_${name.slice(PREFIX.length)}`;
+            if (env[old] === undefined)
+                env[old] = value;
+        }
+    return env;
+}

package/dist/server/host.js

@@ -152,7 +152,11 @@ export async function createAppHost(options) {
         current.server.app.server.emit('upgrade', req, socket, head);
     });
     const listener = listen
-        ? pg.createDriver({ url: options.databaseUrl, max: 1, applicationName: 'kosh apps listener' })
+        ? pg.createDriver({
+            url: options.databaseUrl,
+            max: 1,
+            applicationName: 'shutro-erp apps listener',
+        })
         : undefined;
     const stopListening = await listener?.listen(APPS_CHANNEL, (digest) => {
         if (digest !== current.digest)

package/dist/server/identity.d.ts

@@ -17,6 +17,13 @@ export interface RequestIdentity {
     readonly grants?: readonly string[];
     readonly lang?: string;
     readonly tz?: string;
+    /**
+     * An API key's scopes (RFC 0017 §5.1), when the request carries one: they narrow what the user may do (`*`,
+     * `read:<app>`, `write:<app>`); the user's rights still apply. Absent for sessions.
+     */
+    readonly scopes?: readonly string[];
+    /** The API key the request carries. */
+    readonly apiKey?: number;
 }
 /**
  * The single explicit bypass (CLAUDE.md "superuser mode", RFC 0003 §5.2): the user holds an administrator role

package/dist/server/index.d.ts

@@ -5,7 +5,7 @@
  */
 export { announceChange, CHANGES_CHANNEL, parseChange, type RecordChange } from './api/changes.js';
 export { generateClient, typeOf } from './api/client.js';
-export { IDEMPOTENCY_TABLE, idempotencyTableStatements, type Outcome } from './api/idempotency.js';
+export { IDEMPOTENCY_TABLE, idempotencyTableStatements, idempotent, type Outcome, } from './api/idempotency.js';
 export { type ApiField, type ApiModel, apiModels, defaultFields, publicApiModels, schemaName, } from './api/metadata.js';
 export { type FoundRecord, type MenuNode, moduleVisible, Navigation } from './api/navigation.js';
 export { fieldSchema, openApiDocument, openApiOf } from './api/openapi.js';
@@ -20,6 +20,7 @@ export { type InstallBaseOptions, installBase } from './auth/install.js';
 export { registerAuthRoutes } from './auth/routes.js';
 export { type AuthOptions, AuthService, cookieOf, SESSION_COOKIE, type SessionInfo, timeOf, type UserInfo, } from './auth/service.js';
 export { DEMO_PASSWORD, type DemoResult, installDemo } from './demo.js';
+export { applyEnvironmentNames } from './env-names.js';
 export { HttpProblem, type Problem, problemOf, ServerConfigError } from './errors.js';
 export { type AppHost, type AppHostOptions, createAppHost, startAppHost } from './host.js';
 export { type Authenticator, denyAll, isSuperuser, languageOf, type RequestIdentity, type RequestRunOptions, runOptionsOf, } from './identity.js';

package/dist/server/index.js

@@ -5,7 +5,7 @@
  */
 export { announceChange, CHANGES_CHANNEL, parseChange } from './api/changes.js';
 export { generateClient, typeOf } from './api/client.js';
-export { IDEMPOTENCY_TABLE, idempotencyTableStatements } from './api/idempotency.js';
+export { IDEMPOTENCY_TABLE, idempotencyTableStatements, idempotent, } from './api/idempotency.js';
 export { apiModels, defaultFields, publicApiModels, schemaName, } from './api/metadata.js';
 export { moduleVisible, Navigation } from './api/navigation.js';
 export { fieldSchema, openApiDocument, openApiOf } from './api/openapi.js';
@@ -20,6 +20,7 @@ export { installBase } from './auth/install.js';
 export { registerAuthRoutes } from './auth/routes.js';
 export { AuthService, cookieOf, SESSION_COOKIE, timeOf, } from './auth/service.js';
 export { DEMO_PASSWORD, installDemo } from './demo.js';
+export { applyEnvironmentNames } from './env-names.js';
 export { HttpProblem, problemOf, ServerConfigError } from './errors.js';
 export { createAppHost, startAppHost } from './host.js';
 export { denyAll, isSuperuser, languageOf, runOptionsOf, } from './identity.js';

package/dist/server/registry.js

@@ -53,6 +53,6 @@ export function buildKoshRegistry(modules, options = {}) {
     });
     for (const name of registry.loadOrder)
         if (!loaded.byName.has(name) && name !== CHANGE_EVENTS_MODULE)
-            throw new ServerConfigError(`The Shutro module '${name}' has no Kosh manifest.`, 'Wrap it with defineModule() from shutro-erp/modules-sdk (its access levels are required) and depend on it.');
+            throw new ServerConfigError(`The Shutro module '${name}' has no Shutro ERP manifest.`, 'Wrap it with defineModule() from shutro-erp/modules-sdk (its access levels are required) and depend on it.');
     return { loaded, registry };
 }

package/dist/server/server.d.ts

@@ -1,3 +1,8 @@
+/**
+ * The Kosh server (RFC 0002, CLAUDE.md robustness): Fastify with Pino logs (request ids, redacted credentials),
+ * authentication through an {@link Authenticator}, one Shutro transaction per request (`request.env`), RFC 9457
+ * errors, rate limiting on Valkey, OpenTelemetry spans, health checks, and graceful shutdown.
+ */
 import type { KoshModule } from '../modules-sdk/index.js';
 import type { Span } from '@opentelemetry/api';
 import { type FastifyInstance, type FastifyServerFactory, type FastifyServerOptions } from 'fastify';

package/dist/server/server.js

@@ -12,9 +12,12 @@ import { Navigation } from './api/navigation.js';
 import { openApiDocument } from './api/openapi.js';
 import { registerRestApi } from './api/rest.js';
 import { ViewRegistry } from './api/views.js';
+import { registerApiKeyRoutes } from './auth/api-keys.js';
 import { registerAuthRoutes } from './auth/routes.js';
+import { enforceScopes } from './auth/scopes.js';
 import { AuthService } from './auth/service.js';
-import { HttpProblem, problemOf } from './errors.js';
+import { applyEnvironmentNames } from './env-names.js';
+import { HttpProblem, problemOf, ServerConfigError } from './errors.js';
 import { denyAll, runOptionsOf } from './identity.js';
 import { orm, pg } from './orm.js';
 import { buildKoshRegistry, KOSH_VERSION } from './registry.js';
@@ -25,8 +28,25 @@ const REDACT = [
     'req.headers["x-api-key"]',
     'res.headers["set-cookie"]',
 ];
+/** What a portal user reaches: the portal API, and signing in and out (RFC 0015 §5.1). */
+const PORTAL_PATHS = ['/api/portal/', '/api/v1/auth/'];
+/**
+ * The external groups the modules declare (RFC 0015 §5.1). @throws {ServerConfigError} for one implying
+ * `base.user`: its holders would be internal users.
+ */
+function externalGroupsOf(registry) {
+    const groups = new Set(registry.loaded.modules.flatMap((m) => m.externalGroups ?? []));
+    for (const group of groups) {
+        if (!registry.registry.security.groups.has(group))
+            throw new ServerConfigError(`The external group '${group}' is not defined.`, 'Define it in the module that declares it.');
+        if (registry.registry.security.closure([group]).has('base.user'))
+            throw new ServerConfigError(`The external group '${group}' implies base.user: its users would be internal.`, 'Remove base.user from what it implies.');
+    }
+    return groups;
+}
 /** Creates the server (not listening yet). @throws {ServerConfigError} for modules that cannot load together */
 export async function createServer(options) {
+    applyEnvironmentNames(); // SHUTRO_ERP_* settings, read under their KOSH_* names
     const registry = buildKoshRegistry(options.modules, {
         ...(options.security === undefined ? {} : { security: options.security }),
     });
@@ -37,6 +57,7 @@ export async function createServer(options) {
         applicationName: 'kosh',
     });
     const hasBase = registry.registry.models.has('auth.session');
+    const external = externalGroupsOf(registry);
     let shutro;
     const auth = hasBase ? new AuthService(() => shutro, options.auth) : undefined;
     const verify = auth !== undefined && (options.verifyIdentities ?? options.authenticate === undefined);
@@ -85,6 +106,15 @@ export async function createServer(options) {
             }
         });
     });
+    // The app each module route belongs to (API key scopes, RFC 0017 §5.1): set while a module registers its routes.
+    const routeApps = new Map();
+    let routeModule = null;
+    app.addHook('onRoute', (route) => {
+        if (routeModule === null)
+            return;
+        for (const method of [route.method].flat())
+            routeApps.set(`${method} ${route.url}`, routeModule);
+    });
     app.addHook('onRequest', async (request, reply) => {
         reply.header('x-request-id', request.id);
         request.span = tracer.startSpan(`HTTP ${request.method}`, {
@@ -101,6 +131,25 @@ export async function createServer(options) {
         if (config.public === true || config.auth === false)
             return;
         request.identity = await authenticate(request);
+        // An API key's scopes (RFC 0017 §5.1): the route's app is the module that registered it, or its model's.
+        const scopes = request.identity?.scopes;
+        if (scopes !== undefined) {
+            const route = request.routeOptions.url ?? '';
+            const model = request.params?.model;
+            const owner = routeApps.get(`${request.method} ${route}`) ??
+                (typeof model === 'string'
+                    ? (registry.registry.models.get(model)?.module ?? null)
+                    : null);
+            enforceScopes(scopes, request.method, route, owner);
+        }
+        // Customers and vendors of the portal (RFC 0015 §5.1): the portal API and signing in, nothing else.
+        if (request.identity !== null &&
+            external.size > 0 &&
+            request.identity.groups.length > 0 &&
+            request.identity.groups.every((g) => external.has(g)) &&
+            !PORTAL_PATHS.some((p) => request.url.startsWith(p)) &&
+            request.url.startsWith('/api/'))
+            throw new HttpProblem(403, 'internal-only', 'For the company’s users only', 'Portal users reach the portal only.');
     });
     if (options.rateLimit?.max !== 0)
         await app.register(rateLimit, {
@@ -108,7 +157,11 @@ export async function createServer(options) {
             max: options.rateLimit?.max ?? 600,
             timeWindow: options.rateLimit?.timeWindow ?? '1 minute',
             ...(valkey === undefined ? {} : { redis: valkey, nameSpace: 'kosh:ratelimit:' }),
-            keyGenerator: (request) => request.identity === null ? `ip:${request.ip}` : `user:${request.identity.user}`,
+            keyGenerator: (request) => request.identity === null
+                ? `ip:${request.ip}`
+                : request.identity.apiKey !== undefined
+                    ? `key:${request.identity.apiKey}`
+                    : `user:${request.identity.user}`,
             allowList: (request) => request.routeOptions.config.public === true,
             errorResponseBuilder: (_request, context) => new HttpProblem(429, 'rate-limited', 'Too many requests', `Limit of ${context.max} requests per ${context.after} reached.`, `Retry after ${context.after}.`),
         });
@@ -145,8 +198,10 @@ export async function createServer(options) {
             detail: `No route ${request.method} ${request.url.split('?')[0] ?? ''}.`,
         });
     });
-    if (auth !== undefined)
+    if (auth !== undefined) {
         registerAuthRoutes(app, auth, { loginLimit: options.auth?.loginLimit ?? 10 });
+        registerApiKeyRoutes(app, auth, registry);
+    }
     // The generated REST API and its OpenAPI document (RFC 0002 §6.3–6.4).
     for (const statement of idempotencyTableStatements())
         await driver.query(statement);
@@ -157,7 +212,10 @@ export async function createServer(options) {
         models,
         driver,
         openapi: () => {
-            openapi ??= openApiDocument(models.values(), { title: 'Kosh API', version: KOSH_VERSION });
+            openapi ??= openApiDocument(models.values(), {
+                title: 'Shutro ERP API',
+                version: KOSH_VERSION,
+            });
             return openapi;
         },
     });
@@ -173,8 +231,15 @@ export async function createServer(options) {
         ...(options.apps === undefined ? {} : { apps: options.apps }),
     };
     for (const m of registry.loaded.modules)
-        if (m.routes !== undefined)
-            await m.routes(context);
+        if (m.routes !== undefined) {
+            routeModule = m.name;
+            try {
+                await m.routes(context);
+            }
+            finally {
+                routeModule = null;
+            }
+        }
     // Health checks: public, not rate limited. Liveness: the process answers. Readiness: dependencies answer.
     app.get('/health/live', { config: { public: true } }, async () => ({ status: 'ok' }));
     app.get('/health/ready', { config: { public: true } }, async (_request, reply) => {

package/dist/settings/routes.js

@@ -64,7 +64,7 @@ export function registerAppRoutes(context) {
     const { app, driver } = context;
     const appsOf = () => {
         if (context.apps === undefined)
-            throw new HttpProblem(503, 'app-manager-unavailable', 'App manager unavailable', 'This server does not run in an app host, so it cannot change the installed apps.', 'Start the server with createAppHost (the starter project does), or use npx kosh apps.');
+            throw new HttpProblem(503, 'app-manager-unavailable', 'App manager unavailable', 'This server does not run in an app host, so it cannot change the installed apps.', 'Start the server with createAppHost (the starter project does), or use npx shutro-erp apps.');
         return context.apps;
     };
     /** Administrators and App managers only; returns the caller's user id. */

package/dist/settings/web/ApiKeysPage.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Settings › API keys (RFC 0017 §5.1): your keys — and the service accounts' for administrators —, a new key with its
+ * scopes and expiry, its secret shown once, revocation. The server decides what each key may do; scopes only narrow
+ * the user's own rights.
+ */
+import { type PageProps } from '../../ui/index.js';
+import { type ReactElement } from 'react';
+export declare function ApiKeysPage({ api }: PageProps): ReactElement;