shutro-erp 0.3.0 → 0.3.1

package/dist/server/api/openapi.js

@@ -282,7 +282,23 @@ export function openApiDocument(models, info) {
         openapi: '3.1.0',
         info,
         paths: Object.assign({}, ...list.map(modelPaths)),
+        // A session (sign-in) or an API key (RFC 0017 §5.1); cookie sessions also send X-CSRF-Token on changes.
+        security: [{ session: [] }, { apiKey: [] }, { cookie: [] }],
         components: {
+            securitySchemes: {
+                session: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    description: 'A session token from POST /api/v1/auth/login.',
+                },
+                apiKey: {
+                    type: 'apiKey',
+                    in: 'header',
+                    name: 'X-Api-Key',
+                    description: 'An API key (sk_…; also accepted as Authorization: Bearer). Its scopes — *, read:<app>, write:<app> — narrow the user’s rights.',
+                },
+                cookie: { type: 'apiKey', in: 'cookie', name: 'kosh_session' },
+            },
             schemas: {
                 Problem: {
                     type: 'object',
@@ -344,5 +360,5 @@ export function openApiDocument(models, info) {
  */
 export function openApiOf(modules) {
     const models = publicApiModels(buildKoshRegistry(modules));
-    return openApiDocument(models.values(), { title: 'Kosh API', version: KOSH_VERSION });
+    return openApiDocument(models.values(), { title: 'Shutro ERP API', version: KOSH_VERSION });
 }

package/dist/server/apps.js

@@ -132,7 +132,7 @@ const digestOf = (rows) => createHash('sha256')
  */
 export async function installedModules(source, catalogue, states = ['installed']) {
     const driver = typeof source === 'string'
-        ? pg.createDriver({ url: source, max: 1, applicationName: 'kosh apps' })
+        ? pg.createDriver({ url: source, max: 1, applicationName: 'shutro-erp apps' })
         : source;
     try {
         const rows = await readInstalledApps(driver);
@@ -188,7 +188,7 @@ export async function prepareApps(options) {
     await restoreAppMigrations(driver, options.dir);
     const pending = (await migrate.migrationStatus({ driver, dir: options.dir })).pending;
     if (pending.length > 0)
-        throw new AppPlanError(`${pending.length} migration file(s) are not applied yet (${pending.map((f) => `${f.version}_${f.name}`).join(', ')}).`, 'Run kosh migrate first.');
+        throw new AppPlanError(`${pending.length} migration file(s) are not applied yet (${pending.map((f) => `${f.version}_${f.name}`).join(', ')}).`, 'Run shutro-erp migrate first.');
     const current = await installedApps(driver, catalogue);
     const plan = planApps(catalogue, current, options.change, options.protect ?? ['base']);
     const registryOf = (rows, states) => buildKoshRegistry(servedModules(catalogue, rows, states));
@@ -201,7 +201,7 @@ export async function prepareApps(options) {
     });
     // An upgrade is exactly that difference: the upgraded modules' code ahead of the database.
     if (drift.statements.length > 0 && plan.upgrade.length === 0)
-        throw new AppPlanError(`The database does not match the installed modules (${drift.statements.length} change(s) not migrated).`, 'Run kosh migrate first.');
+        throw new AppPlanError(`The database does not match the installed modules (${drift.statements.length} change(s) not migrated).`, 'Run shutro-erp migrate first.');
     const runtime = registryOf(plan.after, ['installed']);
     const schema = registryOf(plan.after, ['installed', 'disabled']);
     const migration = await migrate.planMigration({
@@ -212,8 +212,8 @@ export async function prepareApps(options) {
     const removeData = options.removeData === true && plan.upgrade.length > 0;
     if (migration.destructive.length > 0 && !removeData)
         throw new AppPlanError(`The change would drop or alter data: ${migration.destructive.map((op) => migrate.renderOperation(op)).join('; ')}.`, plan.upgrade.length > 0
-            ? 'Upgrade with "remove data" (kosh apps upgrade --remove-data) to drop them, or keep the fields in the code.'
-            : 'App changes never destroy data; review the modules, or use kosh migrate --plan.');
+            ? 'Upgrade with "remove data" (shutro-erp apps upgrade --remove-data) to drop them, or keep the fields in the code.'
+            : 'App changes never destroy data; review the modules, or use shutro-erp migrate --plan.');
     // A disabled module's columns stay in other modules' tables: a NOT NULL one without a database default (a function
     // default or a compute lives in the ORM) would make every insert there fail.
     const orphaned = [];

package/dist/server/auth/api-keys.d.ts

@@ -0,0 +1,13 @@
+/**
+ * API keys and service accounts over HTTP (RFC 0017 §5.1). With a session only (a key cannot make keys):
+ *
+ * - `GET  /api/v1/auth/api-keys`              your keys (and every service account's, for administrators)
+ * - `POST /api/v1/auth/api-keys`              `{ name, scopes, expiresInDays?, user? }` → the key and its secret, once
+ * - `POST /api/v1/auth/api-keys/:id/revoke`   at once
+ * - `POST /api/v1/auth/service-accounts`      `{ login, name, groups }` (administrators)
+ * - `GET  /api/v1/auth/scopes`                the scopes a key may have: `*` and the installed apps'
+ */
+import type { FastifyInstance } from 'fastify';
+import type { KoshRegistry } from '../registry.js';
+import type { AuthService } from './service.js';
+export declare function registerApiKeyRoutes(app: FastifyInstance, auth: AuthService, registry: KoshRegistry): void;

package/dist/server/auth/api-keys.js

@@ -0,0 +1,65 @@
+import { HttpProblem } from '../errors.js';
+import { parseScopes } from './scopes.js';
+const body = (request) => typeof request.body === 'object' && request.body !== null
+    ? request.body
+    : {};
+export function registerApiKeyRoutes(app, auth, registry) {
+    const apps = () => new Set(registry.loaded.modules.map((m) => m.name));
+    const config = { config: { auth: false } };
+    app.get('/api/v1/auth/scopes', config, async (request) => {
+        await auth.requireSession(request);
+        return {
+            scopes: [
+                { scope: '*', label: 'Everything you may do' },
+                ...registry.loaded.modules.flatMap((m) => [
+                    { scope: `read:${m.name}`, label: `Read ${m.name}` },
+                    { scope: `write:${m.name}`, label: `Read and change ${m.name}` },
+                ]),
+            ],
+        };
+    });
+    app.get('/api/v1/auth/api-keys', config, async (request) => {
+        const session = await auth.requireSession(request);
+        return { keys: await auth.listApiKeys(session) };
+    });
+    app.post('/api/v1/auth/api-keys', config, async (request, reply) => {
+        const session = await auth.requireSession(request);
+        const input = body(request);
+        const scopes = parseScopes(Array.isArray(input['scopes'])
+            ? input['scopes'].map(String)
+            : String(input['scopes'] ?? ''), apps());
+        const user = input['user'] === undefined ? undefined : Number(input['user']);
+        if (user !== undefined && !(Number.isInteger(user) && user > 0))
+            throw new HttpProblem(400, 'invalid-body', 'Invalid body', 'user is a user id.');
+        const days = input['expiresInDays'] === undefined ? undefined : Number(input['expiresInDays']);
+        const created = await auth.createApiKey(session, {
+            name: String(input['name'] ?? ''),
+            scopes,
+            ...(user === undefined ? {} : { user }),
+            ...(days === undefined ? {} : { expiresInDays: days }),
+        }, request.ip);
+        return reply.status(201).send(created);
+    });
+    app.post('/api/v1/auth/api-keys/:id/revoke', config, async (request, reply) => {
+        const session = await auth.requireSession(request);
+        const id = Number(request.params.id);
+        if (!(Number.isInteger(id) && id > 0))
+            throw new HttpProblem(400, 'invalid-id', 'Invalid id', 'The key id is a positive integer.');
+        await auth.revokeApiKey(session, id, request.ip);
+        return reply.status(204).send();
+    });
+    app.post('/api/v1/auth/service-accounts', config, async (request, reply) => {
+        const session = await auth.requireSession(request);
+        const input = body(request);
+        const login = String(input['login'] ?? '').trim();
+        const name = String(input['name'] ?? '').trim();
+        if (!/^[A-Za-z0-9._@-]{3,64}$/.test(login) || name === '')
+            throw new HttpProblem(400, 'invalid-body', 'Invalid body', 'login (3–64 letters, digits, . _ @ -) and name are required.');
+        const groups = Array.isArray(input['groups']) ? input['groups'].map(String) : [];
+        const unknown = groups.filter((g) => !registry.registry.security.groups.has(g));
+        if (unknown.length > 0)
+            throw new HttpProblem(422, 'invalid-groups', 'Invalid roles', `Unknown roles: ${unknown.join(', ')}.`);
+        const created = await auth.createServiceAccount(session, { login, name, groups }, request.ip);
+        return reply.status(201).send(created);
+    });
+}

package/dist/server/auth/base.js

@@ -53,6 +53,8 @@ const ResUsers = defineModel('res.users', {
         companies: f.many2many('res.company'),
         lang: f.char({ default: 'en_US' }),
         tz: f.char({ default: 'UTC' }),
+        /** A service account (RFC 0017 §5.1): no password, no sign-in; acts only through API keys, with its roles. */
+        isService: f.boolean({ default: false, label: 'Service account' }),
     },
 });
 /** Password hash and TOTP state of a user. Private: never served by the generated API. */
@@ -81,6 +83,26 @@ const AuthSession = defineModel('auth.session', {
         userAgent: f.char(),
     },
 });
+/**
+ * An API key (RFC 0017 §5.1): acts as its user (a person or a service account) within its scopes, until it expires
+ * or is revoked. The secret is shown once and stored only as a SHA-256 digest; the prefix identifies it. Private.
+ */
+const AuthApiKey = defineModel('auth.api_key', {
+    fields: {
+        name: f.char({ required: true }),
+        user: f.many2one('res.users', { required: true, ondelete: 'cascade' }),
+        tokenHash: f.char({ required: true, index: 'unique' }),
+        /** The secret's start (`sk_ab12cd34`), to tell keys apart. */
+        prefix: f.char({ required: true }),
+        /** Space-separated: `*`, `read:<app>`, `write:<app>`. */
+        scopes: f.text({ required: true }),
+        expiresAt: f.datetime({ required: true }),
+        lastUsedAt: f.datetime(),
+        lastUsedIp: f.char(),
+        revoked: f.boolean({ default: false }),
+        issuedBy: f.many2one('res.users', { ondelete: 'set null' }),
+    },
+});
 /**
  * A group or role a user holds in one company (or every company when `company` is empty). Private. Users holding
  * any cannot be deleted (`restrict`): they are archived, which the "keep one administrator" guard checks.
@@ -171,6 +193,7 @@ export const baseShutro = defineModule({
         ResUsers,
         AuthCredential,
         AuthSession,
+        AuthApiKey,
         AuthUserGroup,
         AuthUserGrant,
         AuditEvent,
@@ -188,6 +211,7 @@ export const base = defineKoshModule({
     privateModels: [
         'auth.credential',
         'auth.session',
+        'auth.api_key',
         'auth.user_group',
         'auth.user_grant',
         'audit.event',

package/dist/server/auth/crypto.js

@@ -94,6 +94,6 @@ export function verifyTotp(secret, code, time = Date.now()) {
     });
 }
 /** The `otpauth://` URI authenticator apps scan. */
-export function otpauthUri(secret, account, issuer = 'Kosh') {
+export function otpauthUri(secret, account, issuer = 'Shutro ERP') {
     return `otpauth://totp/${encodeURIComponent(`${issuer}:${account}`)}?secret=${secret}&issuer=${encodeURIComponent(issuer)}&algorithm=SHA1&digits=6&period=30`;
 }

package/dist/server/auth/scopes.d.ts

@@ -0,0 +1,12 @@
+export type Access = 'read' | 'write';
+/** The scopes in `text` (space or comma separated), checked against the installed apps. */
+export declare function parseScopes(input: string | readonly string[], apps: ReadonlySet<string>): string[];
+/** Whether `scopes` allow `access` to `app` (`null`: a route of no app, which needs `*`). */
+export declare function scopesAllow(scopes: readonly string[], app: string | null, access: Access): boolean;
+/** The access a request method needs. */
+export declare const accessOf: (method: string) => Access;
+/**
+ * Refuses a request an API key's scopes do not cover. `route` is the route's pattern (`/api/v1/models/:model`),
+ * `app` the app it belongs to, or null.
+ */
+export declare function enforceScopes(scopes: readonly string[], method: string, route: string, app: string | null): void;

package/dist/server/auth/scopes.js

@@ -0,0 +1,51 @@
+/**
+ * API key scopes (RFC 0017 §5.1): they narrow what a key's user may do, never widen it. `*` is everything the user
+ * may do; `read:<app>` reads an app's models and routes; `write:<app>` also changes them (it implies read). A route
+ * belongs to an app when the app's module registered it, or when it serves one of the app's models; a route of no
+ * app needs `*`. Keys cannot manage credentials (sign-in, 2FA, passwords, keys): those need a session.
+ */
+import { HttpProblem } from '../errors.js';
+const SCOPE = /^(\*|(read|write):[a-z][a-z0-9_]*)$/;
+/** The scopes in `text` (space or comma separated), checked against the installed apps. */
+export function parseScopes(input, apps) {
+    const list = (typeof input === 'string' ? input.split(/[\s,]+/) : [...input])
+        .map((s) => s.trim())
+        .filter((s) => s !== '');
+    if (list.length === 0)
+        throw new HttpProblem(400, 'invalid-scopes', 'Invalid scopes', 'Give at least one scope: *, read:<app> or write:<app>.');
+    for (const scope of list) {
+        if (!SCOPE.test(scope))
+            throw new HttpProblem(400, 'invalid-scopes', 'Invalid scopes', `"${scope}" is not a scope: *, read:<app> or write:<app>.`);
+        const app = scope.split(':')[1];
+        if (app !== undefined && !apps.has(app))
+            throw new HttpProblem(400, 'invalid-scopes', 'Invalid scopes', `"${app}" is not an installed app.`);
+    }
+    return [...new Set(list)].sort();
+}
+/** Whether `scopes` allow `access` to `app` (`null`: a route of no app, which needs `*`). */
+export function scopesAllow(scopes, app, access) {
+    if (scopes.includes('*'))
+        return true;
+    if (app === null)
+        return false;
+    return scopes.includes(`write:${app}`) || (access === 'read' && scopes.includes(`read:${app}`));
+}
+/** The access a request method needs. */
+export const accessOf = (method) => method === 'GET' || method === 'HEAD' || method === 'OPTIONS' ? 'read' : 'write';
+/** Credential routes an API key may still use (who am I). */
+const KEY_AUTH_ROUTES = new Set(['GET /api/v1/auth/me']);
+/**
+ * Refuses a request an API key's scopes do not cover. `route` is the route's pattern (`/api/v1/models/:model`),
+ * `app` the app it belongs to, or null.
+ */
+export function enforceScopes(scopes, method, route, app) {
+    if (route.startsWith('/api/v1/auth/') && !KEY_AUTH_ROUTES.has(`${method} ${route}`))
+        throw new HttpProblem(403, 'api-key-not-allowed', 'Not with an API key', 'Signing in, two-factor, passwords and API keys are managed with a session, not an API key.');
+    if (KEY_AUTH_ROUTES.has(`${method} ${route}`))
+        return;
+    const access = accessOf(method);
+    if (!scopesAllow(scopes, app, access))
+        throw new HttpProblem(403, 'scope', 'Outside the API key’s scopes', app === null
+            ? 'This route belongs to no app: it needs a key with the * scope.'
+            : `This needs the ${access === 'read' ? `read:${app} or write:${app}` : `write:${app}`} scope.`, 'Create a key with the scope it needs.');
+}

package/dist/server/auth/service.d.ts

@@ -45,6 +45,20 @@ export interface UserInfo {
     /** Administrator rights are withheld until this session has a second factor (enable or verify 2FA). */
     readonly administratorNeedsSecondFactor: boolean;
 }
+/** An API key as listed (never its secret). */
+export interface ApiKeyInfo {
+    readonly id: number;
+    readonly name: string;
+    readonly user: number;
+    /** The user's name (yours, or a service account's). */
+    readonly userName: string;
+    readonly prefix: string;
+    readonly scopes: readonly string[];
+    readonly expiresAt: string;
+    readonly lastUsedAt: string | null;
+    readonly lastUsedIp: string | null;
+    readonly revoked: boolean;
+}
 export declare const SESSION_COOKIE = "kosh_session";
 /** Milliseconds of a datetime value as Shutro returns it (`Date`, or an ISO text), or `null`. */
 export declare function timeOf(value: unknown): number | null;
@@ -83,8 +97,50 @@ export declare class AuthService {
     requireSession(request: FastifyRequest, options?: {
         readonly allowPending?: boolean;
     }): Promise<SessionInfo>;
-    /** 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.
+     */
     authenticate(request: FastifyRequest): Promise<RequestIdentity | null>;
+    /**
+     * 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
+     */
+    apiKeyOf(request: FastifyRequest): Promise<{
+        id: number;
+        user: number;
+        scopes: string[];
+    } | null>;
+    /**
+     * 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.
+     */
+    createApiKey(session: SessionInfo, input: {
+        readonly user?: number;
+        readonly name: string;
+        readonly scopes: readonly string[];
+        readonly expiresInDays?: number;
+    }, ip?: string): Promise<ApiKeyInfo & {
+        token: string;
+    }>;
+    /** The session user's keys, and every service account's for administrators. */
+    listApiKeys(session: SessionInfo): Promise<ApiKeyInfo[]>;
+    /** Revokes a key at once (the session's own, or a service account's for administrators). */
+    revokeApiKey(session: SessionInfo, id: number, ip?: string): Promise<void>;
+    /**
+     * 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.
+     */
+    createServiceAccount(session: SessionInfo, input: {
+        readonly login: string;
+        readonly name: string;
+        readonly groups: readonly string[];
+    }, ip?: string): Promise<{
+        id: number;
+        login: string;
+        name: string;
+        groups: string[];
+    }>;
     /** Identity loader for Shutro (`createShutro({ identity })`): the user is active; companies and groups from the database. */
     verify(uid: number): Promise<VerifiedIdentity | null>;
     /** The signed-in user's state. */

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);

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;