shutro-erp 0.2.1 → 0.3.1

package/dist/sales/module.js

@@ -5,9 +5,14 @@
  */
 import { contactsShutro } from '../contacts/index.js';
 import { messagingShutro } from '../messaging/index.js';
-import { productShutro } from '../product/index.js';
+import { computeTaxes, productShutro, taxRule } from '../product/index.js';
 import { orm } from '../server/orm.js';
 import { check, compute, defineModel, defineModule, f, onchange, records, } from './.kosh/bindings.js';
+/** A line's taxes through the engine (RFC 0016): its amount after discount, its taxes in order. */
+function taxesOf(l) {
+    const amount = l.quantity.times(l.priceUnit).times(orm.toDecimal(100).minus(l.discount)).div(100);
+    return computeTaxes(amount, l.quantity, [...l.taxes].map(taxRule));
+}
 const amounts = compute('sale.order', ['amountUntaxed', 'amountTax', 'amountTotal'], ['lines.subtotal', 'lines.taxAmount'], (orders) => {
     for (const o of orders) {
         // A new order has no currency until its partner is chosen: no amounts yet.
@@ -124,7 +129,10 @@ export const SaleOrderLine = defineModel('sale.order.line', {
         priceUnit: f.decimal({ scale: 2, required: true, default: '0', label: 'Unit price' }),
         /** Percent off the unit price (0–100). */
         discount: f.decimal({ scale: 2, required: true, default: '0', label: 'Discount %' }),
-        tax: f.many2one('account.tax'),
+        /** The line's taxes, applied in order (RFC 0016). */
+        taxes: f.many2many('account.tax'),
+        /** Before 0.2.0, one tax per line: copied into `taxes` by the migration; dropped later. */
+        tax: f.many2one('account.tax', { label: 'Tax (before 0.2.0)', readonly: true }),
         /** The order's currency, so line amounts are Money in it. */
         currency: f.many2one('res.currency', {
             store: true,
@@ -136,33 +144,54 @@ export const SaleOrderLine = defineModel('sale.order.line', {
         subtotal: f.monetary({
             currency: 'currency',
             store: true,
-            ...compute('sale.order.line', 'subtotal', ['quantity', 'priceUnit', 'discount'], (lines) => {
+            ...compute('sale.order.line', 'subtotal', [
+                'quantity',
+                'priceUnit',
+                'discount',
+                'taxes.rate',
+                'taxes.sequence',
+                'taxes.amountType',
+                'taxes.fixedAmount',
+                'taxes.affectsBase',
+                'taxes.priceIncluded',
+                'taxes.reverseCharge',
+            ], (lines) => {
                 for (const l of lines)
-                    l.subtotal = l.quantity
-                        .times(l.priceUnit)
-                        .times(orm.toDecimal(100).minus(l.discount))
-                        .div(100);
+                    l.subtotal = taxesOf(l).untaxed;
             }),
         }),
         taxAmount: f.monetary({
             currency: 'currency',
             store: true,
             label: 'Tax',
-            ...compute('sale.order.line', 'taxAmount', ['subtotal', 'tax.rate'], (lines) => {
+            ...compute('sale.order.line', 'taxAmount', [
+                'quantity',
+                'priceUnit',
+                'discount',
+                'taxes.rate',
+                'taxes.sequence',
+                'taxes.amountType',
+                'taxes.fixedAmount',
+                'taxes.affectsBase',
+                'taxes.priceIncluded',
+                'taxes.reverseCharge',
+            ], (lines) => {
                 for (const l of lines)
-                    l.taxAmount = (l.subtotal?.amount ?? orm.toDecimal(0)).times(l.tax?.rate ?? 0);
+                    l.taxAmount = taxesOf(l).taxTotal;
             }),
         }),
     },
     onchange: {
-        product: onchange('sale.order.line', async (d) => {
+        product: onchange('sale.order.line', async (d, env) => {
             const p = await d.record('product');
             if (p === null)
                 return;
             d.set('name', p.name);
             d.set('priceUnit', p.listPrice);
             d.set('uom', p.uom?.id ?? null);
-            d.set('tax', p.tax?.id ?? null);
+            // The product's taxes, loaded (a draft's related record has its plain fields only).
+            const [taxed] = await env.model('product.product').browse([p.id]).load({ taxes: true });
+            d.set('taxes', { set: [...(taxed?.taxes.ids ?? [])] });
         }),
     },
     constraints: {
@@ -178,7 +207,17 @@ export const SaleOrderLine = defineModel('sale.order.line', {
 });
 export const salesShutro = defineModule({
     name: 'sales',
-    version: '0.1.0',
+    version: '0.2.0',
+    migrations: [
+        {
+            version: '0.2.0',
+            description: 'Several taxes per line: the single tax of each line becomes its first',
+            up: async (ctx) => {
+                await ctx.sql `INSERT INTO sale_order_line_account_tax_rel (sale_order_line_id, account_tax_id)
+          SELECT id, tax_id FROM sale_order_line WHERE tax_id IS NOT NULL ON CONFLICT DO NOTHING`;
+            },
+        },
+    ],
     depends: [contactsShutro, productShutro, messagingShutro],
     groups: [
         orm.defineGroup({

package/dist/server/api/client.js

@@ -93,7 +93,7 @@ export function generateClient(document) {
     const schemas = asSchema(asSchema(document['components'])['schemas']);
     const models = modelsOf(asSchema(document['paths']));
     const out = [];
-    out.push(`// Generated by \`kosh generate client\` from ${JSON.stringify(String(info['title'] ?? 'Kosh API'))} ${String(info['version'] ?? '')}. Do not edit: regenerate.`, '', '// ------------------------------------------------------------------------------------------------- schemas', '');
+    out.push(`// Generated by \`shutro-erp generate client\` from ${JSON.stringify(String(info['title'] ?? 'Shutro ERP API'))} ${String(info['version'] ?? '')}. Do not edit: regenerate.`, '', '// ------------------------------------------------------------------------------------------------- schemas', '');
     for (const name of Object.keys(schemas).sort()) {
         const schema = asSchema(schemas[name]);
         const body = typeOf(schema);

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

@@ -20,6 +20,8 @@ const ResCompany = defineModel('res.company', {
     fields: {
         name: f.char({ required: true }),
         currency: f.many2one('res.currency', { required: true }),
+        /** How numbers are grouped on screen and in documents (RFC 0016): 1,234,567 or 12,34,567 (lakh and crore). */
+        numberGrouping: f.selection({ international: 'International (1,234,567)', lakh: 'Lakh and crore (12,34,567)' }, { required: true, default: 'international', label: 'Number grouping' }),
     },
 });
 const readRows = async (env, model, ids, keys) => env.asSuperuser({ reason: 'check administrators' }, async (su) => {
@@ -51,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. */
@@ -79,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.
@@ -169,6 +193,7 @@ export const baseShutro = defineModule({
         ResUsers,
         AuthCredential,
         AuthSession,
+        AuthApiKey,
         AuthUserGroup,
         AuthUserGrant,
         AuditEvent,
@@ -186,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

@@ -37,12 +37,28 @@ export interface UserInfo {
     readonly name: string;
     readonly company: number | null;
     readonly companies: readonly number[];
+    /** The number grouping of each of the user's companies (RFC 0016): `lakh` or `international`. */
+    readonly groupings: Readonly<Record<string, 'international' | 'lakh'>>;
     readonly twoFactorEnabled: boolean;
     /** Holds an administrator role (in some company). */
     readonly administrator: boolean;
     /** 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;
@@ -81,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. */