shutro-erp 0.3.3 → 0.3.4

package/dist/server/auth/oauth.js

@@ -0,0 +1,579 @@
+/**
+ * Shutro ERP as an OAuth 2.0 provider (RFC 0017 §5.2): third-party apps act for a user who consented, within scopes
+ * — the API keys' scopes (`*`, `read:<app>`, `write:<app>`), narrowing the user's own rights, never widening them.
+ * Authorization code with PKCE (S256; required of public apps), access tokens for an hour, refresh tokens rotated at
+ * each use (a reused one revokes the grant), everything stored as digests and audited.
+ *
+ * - `GET  /.well-known/oauth-authorization-server`   discovery (RFC 8414)
+ * - `GET  /api/v1/oauth/authorize?…`                  the consent screen's data: the app, the scopes in words
+ * - `POST /api/v1/oauth/authorize`                    `{ …the same, decision: 'allow' | 'deny' }` → `{ redirect }`
+ * - `POST /api/v1/oauth/token`                        `authorization_code` and `refresh_token` grants (form or JSON)
+ * - `POST /api/v1/oauth/revoke`                       an access or refresh token (RFC 7009)
+ * - `GET  /api/v1/auth/oauth/grants`                  the apps you allowed; `POST …/grants/:id/revoke`
+ * - `GET / POST /api/v1/oauth/apps`, `PATCH …/:id`, `POST …/:id/secret`   the apps (administrators and
+ *   Integrations managers, with a session)
+ *
+ * The consent page itself is the back-office's `/oauth/authorize` (the address in the discovery document).
+ */
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { audit } from '../audit.js';
+import { HttpProblem } from '../errors.js';
+import { digest, randomToken } from './crypto.js';
+import { parseScopes } from './scopes.js';
+import { timeOf } from './service.js';
+export const ACCESS_SECONDS = 3600;
+const REFRESH_DAYS = 30;
+const CODE_MINUTES = 10;
+/** Access tokens start with it: the server tells them from sessions and API keys at a glance. */
+export const ACCESS_PREFIX = 'oat_';
+const REFRESH_PREFIX = 'ort_';
+const model = (env, name) => env.model(name);
+async function find(env, name, where, keys) {
+    const set = await model(env, name).search({ where, order: ['id asc'] });
+    return set.length === 0 ? [] : (await set.load(keys)).read(['id', ...keys]);
+}
+const words = (text) => String(text ?? '')
+    .split(/\s+/)
+    .filter((w) => w !== '');
+const same = (a, b) => {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+};
+const s256 = (verifier) => createHash('sha256').update(verifier).digest('base64url');
+/** An OAuth error as RFC 6749 §5.2 shapes it. */
+class OAuthError extends Error {
+    code;
+    description;
+    status;
+    constructor(code, description, status = 400) {
+        super(description);
+        this.code = code;
+        this.description = description;
+        this.status = status;
+    }
+}
+/** Finds the access token `token` (`oat_…`), live, of an active app and a grant not revoked. */
+export async function resolveAccessToken(env, token) {
+    const [row] = await find(env, 'oauth.token', { accessHash: digest(token), revoked: false }, [
+        'grant',
+        'accessExpiresAt',
+    ]);
+    if (row === undefined || (timeOf(row['accessExpiresAt']) ?? 0) <= Date.now())
+        return null;
+    const [grant] = await find(env, 'oauth.grant', { id: row['grant'], revoked: false }, [
+        'user',
+        'app',
+        'scopes',
+        'lastUsedAt',
+    ]);
+    if (grant === undefined)
+        return null;
+    const [app] = await find(env, 'oauth.app', { id: grant['app'], active: true }, ['name']);
+    // Archived users' tokens stop working with them.
+    if (app === undefined ||
+        (await model(env, 'res.users').search({ where: { id: grant['user'] } })).length === 0)
+        return null;
+    if ((timeOf(grant['lastUsedAt']) ?? 0) + 5 * 60_000 < Date.now())
+        await model(env, 'oauth.grant')
+            .browse([grant['id']])
+            .write({ lastUsedAt: new Date() });
+    return {
+        token: row['id'],
+        user: grant['user'],
+        app: grant['app'],
+        scopes: words(grant['scopes']),
+    };
+}
+export function registerOAuthRoutes(app, auth, shutro, registry, options) {
+    const system = (reason, fn) => shutro().bootstrap({ reason: `oauth: ${reason}` }, fn);
+    const installed = () => new Set(registry.loaded.modules.map((m) => m.name));
+    const appLabel = (name) => registry.loaded.modules.find((m) => m.name === name)?.app?.label ?? name;
+    /** A scope in words, for the consent screen. */
+    const describe = (scope) => {
+        if (scope === '*')
+            return 'Everything you may do';
+        const [access, name] = scope.split(':');
+        return access === 'read' ? `Read ${appLabel(name)}` : `Read and change ${appLabel(name)}`;
+    };
+    const base = options.baseUrl.replace(/\/$/, '');
+    // ------------------------------------------------------------------------------------- discovery
+    app.get('/.well-known/oauth-authorization-server', { config: { auth: false } }, async (request) => {
+        const api = `${request.protocol}://${request.host}`;
+        return {
+            issuer: base,
+            authorization_endpoint: `${base}/oauth/authorize`,
+            token_endpoint: `${api}/api/v1/oauth/token`,
+            revocation_endpoint: `${api}/api/v1/oauth/revoke`,
+            response_types_supported: ['code'],
+            grant_types_supported: ['authorization_code', 'refresh_token'],
+            code_challenge_methods_supported: ['S256'],
+            token_endpoint_auth_methods_supported: [
+                'client_secret_basic',
+                'client_secret_post',
+                'none',
+            ],
+            scopes_supported: ['*', ...[...installed()].flatMap((m) => [`read:${m}`, `write:${m}`])],
+        };
+    });
+    // ------------------------------------------------------------------------------------- consent
+    /** Checks an authorization request; problems before the redirect is trusted are 400s, never redirects. */
+    const checkRequest = async (env, q) => {
+        const bad = (detail) => new HttpProblem(400, 'invalid-request', 'Invalid request', detail);
+        if (q['response_type'] !== 'code')
+            throw bad("response_type must be 'code'.");
+        const [client] = await find(env, 'oauth.app', { clientId: String(q['client_id'] ?? ''), active: true }, ['name', 'homepage', 'confidential', 'redirectUris', 'scopes']);
+        if (client === undefined)
+            throw bad('Unknown or inactive client_id.');
+        const redirect = String(q['redirect_uri'] ?? '');
+        if (!words(client['redirectUris']).includes(redirect))
+            throw bad('redirect_uri is not one of the app’s registered addresses.');
+        const allowed = new Set(words(client['scopes']));
+        const asked = q['scope'] === undefined || q['scope'] === ''
+            ? [...allowed]
+            : parseScopes(String(q['scope']), installed());
+        const outside = asked.filter((s) => !allowed.has(s));
+        if (outside.length > 0)
+            throw bad(`The app may not ask for ${outside.join(', ')}.`);
+        const challenge = typeof q['code_challenge'] === 'string' ? q['code_challenge'] : '';
+        if (challenge === '' && client['confidential'] !== true)
+            throw bad('A public app must send a PKCE code_challenge (S256).');
+        if (challenge !== '' && q['code_challenge_method'] !== 'S256')
+            throw bad("code_challenge_method must be 'S256'.");
+        if (challenge !== '' && !/^[A-Za-z0-9_-]{43}$/.test(challenge))
+            throw bad('code_challenge is a base64url SHA-256 (43 characters).');
+        return {
+            client,
+            redirect,
+            scopes: asked.sort(),
+            challenge,
+            state: typeof q['state'] === 'string' ? q['state'] : undefined,
+        };
+    };
+    const redirectTo = (uri, params) => {
+        const url = new URL(uri);
+        for (const [k, v] of Object.entries(params))
+            if (v !== undefined)
+                url.searchParams.set(k, v);
+        return url.toString();
+    };
+    app.get('/api/v1/oauth/authorize', { config: { auth: false } }, async (request) => {
+        const session = await auth.requireSession(request);
+        return system('consent screen', async (env) => {
+            const r = await checkRequest(env, (request.query ?? {}));
+            const [grant] = await find(env, 'oauth.grant', { user: session.user, app: r.client['id'], revoked: false }, ['scopes']);
+            const granted = new Set(words(grant?.['scopes']));
+            return {
+                app: {
+                    name: String(r.client['name']),
+                    homepage: typeof r.client['homepage'] === 'string' ? r.client['homepage'] : null,
+                },
+                redirectHost: new URL(r.redirect).host,
+                scopes: r.scopes.map((scope) => ({ scope, label: describe(scope) })),
+                // Everything asked was allowed before: the screen may say so.
+                alreadyAllowed: r.scopes.every((s) => granted.has(s)),
+            };
+        });
+    });
+    app.post('/api/v1/oauth/authorize', { config: { auth: false } }, async (request) => {
+        const session = await auth.requireSession(request);
+        const body = (request.body ?? {});
+        return system('consent', async (env) => {
+            const r = await checkRequest(env, body);
+            if (body['decision'] !== 'allow')
+                return {
+                    redirect: redirectTo(r.redirect, {
+                        error: 'access_denied',
+                        error_description: 'The user declined.',
+                        state: r.state,
+                    }),
+                };
+            const grants = await model(env, 'oauth.grant').search({
+                where: { user: session.user, app: r.client['id'] },
+            });
+            let grant;
+            if (grants.length === 0)
+                grant = (await model(env, 'oauth.grant').create([
+                    { user: session.user, app: r.client['id'], scopes: r.scopes.join(' ') },
+                ])).ids[0];
+            else {
+                grant = grants.ids[0];
+                await model(env, 'oauth.grant')
+                    .browse([grant])
+                    .write({ scopes: r.scopes.join(' '), revoked: false });
+            }
+            const code = randomToken();
+            await model(env, 'oauth.code').create([
+                {
+                    codeHash: digest(code),
+                    grant,
+                    redirectUri: r.redirect,
+                    challenge: r.challenge === '' ? null : r.challenge,
+                    expiresAt: new Date(Date.now() + CODE_MINUTES * 60_000),
+                },
+            ]);
+            await audit(env, {
+                kind: 'oauth.consent',
+                summary: `Allowed ${String(r.client['name'])}: ${r.scopes.join(' ')}.`,
+                actor: session.user,
+                targetModel: 'oauth.app',
+                targetId: r.client['id'],
+                ip: request.ip,
+            });
+            return { redirect: redirectTo(r.redirect, { code, state: r.state }) };
+        });
+    });
+    // ------------------------------------------------------------------------------------- tokens
+    /** The client of a token or revoke request: `client_secret_basic`, `client_secret_post`, or public (`none`). */
+    const clientOf = async (env, request, body) => {
+        let id = typeof body['client_id'] === 'string' ? body['client_id'] : '';
+        let secret = typeof body['client_secret'] === 'string' ? body['client_secret'] : '';
+        const basic = /^Basic\s+(\S+)$/i.exec(String(request.headers.authorization ?? ''))?.[1];
+        if (basic !== undefined) {
+            const [user, pass] = Buffer.from(basic, 'base64').toString('utf8').split(':');
+            id = decodeURIComponent(user ?? '');
+            secret = decodeURIComponent(pass ?? '');
+        }
+        const [client] = await find(env, 'oauth.app', { clientId: id, active: true }, [
+            'name',
+            'confidential',
+            'secretHash',
+        ]);
+        if (client === undefined)
+            throw new OAuthError('invalid_client', 'Unknown client.', 401);
+        if (client['confidential'] === true) {
+            if (secret === '' || !same(digest(secret), String(client['secretHash'] ?? '')))
+                throw new OAuthError('invalid_client', 'Wrong client credentials.', 401);
+        }
+        return client;
+    };
+    const issue = async (env, grant) => {
+        const access = `${ACCESS_PREFIX}${randomToken()}`;
+        const refresh = `${REFRESH_PREFIX}${randomToken()}`;
+        const now = Date.now();
+        await model(env, 'oauth.token').create([
+            {
+                grant,
+                accessHash: digest(access),
+                refreshHash: digest(refresh),
+                accessExpiresAt: new Date(now + ACCESS_SECONDS * 1000),
+                refreshExpiresAt: new Date(now + REFRESH_DAYS * 86_400_000),
+            },
+        ]);
+        const [row] = await find(env, 'oauth.grant', { id: grant }, ['scopes']);
+        return {
+            access_token: access,
+            token_type: 'Bearer',
+            expires_in: ACCESS_SECONDS,
+            refresh_token: refresh,
+            scope: String(row?.['scopes'] ?? ''),
+        };
+    };
+    /** Revokes a grant's tokens (a replayed code or refresh token: someone else may hold them). */
+    const revokeGrantTokens = async (env, grant) => {
+        const tokens = await model(env, 'oauth.token').search({ where: { grant, revoked: false } });
+        if (tokens.length > 0)
+            await tokens.write({ revoked: true });
+    };
+    const tokenEndpoint = async (request, body) => {
+        const out = await system('token', async (env) => {
+            const client = await clientOf(env, request, body);
+            if (body['grant_type'] === 'authorization_code') {
+                const [code] = await find(env, 'oauth.code', { codeHash: digest(String(body['code'] ?? '')) }, ['grant', 'redirectUri', 'challenge', 'expiresAt', 'used']);
+                if (code === undefined)
+                    throw new OAuthError('invalid_grant', 'Unknown code.');
+                const [grant] = await find(env, 'oauth.grant', { id: code['grant'] }, [
+                    'app',
+                    'user',
+                    'revoked',
+                ]);
+                if (grant === undefined || grant['app'] !== client['id'])
+                    throw new OAuthError('invalid_grant', 'The code was issued to another client.');
+                if (code['used'] === true) {
+                    // A code used twice: its tokens may be in the wrong hands.
+                    await revokeGrantTokens(env, code['grant']);
+                    return { failure: new OAuthError('invalid_grant', 'The code was already used.') };
+                }
+                if ((timeOf(code['expiresAt']) ?? 0) <= Date.now() || grant['revoked'] === true)
+                    throw new OAuthError('invalid_grant', 'The code expired.');
+                if (body['redirect_uri'] !== code['redirectUri'])
+                    throw new OAuthError('invalid_grant', 'redirect_uri differs from the authorization request.');
+                if (typeof code['challenge'] === 'string') {
+                    const verifier = typeof body['code_verifier'] === 'string' ? body['code_verifier'] : '';
+                    if (!/^[A-Za-z0-9._~-]{43,128}$/.test(verifier) ||
+                        !same(s256(verifier), code['challenge']))
+                        throw new OAuthError('invalid_grant', 'The PKCE code_verifier does not match.');
+                }
+                await model(env, 'oauth.code')
+                    .browse([code['id']])
+                    .write({ used: true });
+                return issue(env, code['grant']);
+            }
+            if (body['grant_type'] === 'refresh_token') {
+                const [token] = await find(env, 'oauth.token', { refreshHash: digest(String(body['refresh_token'] ?? '')) }, ['grant', 'refreshExpiresAt', 'revoked', 'rotated']);
+                if (token === undefined)
+                    throw new OAuthError('invalid_grant', 'Unknown refresh token.');
+                const [grant] = await find(env, 'oauth.grant', { id: token['grant'] }, [
+                    'app',
+                    'revoked',
+                ]);
+                if (grant === undefined || grant['app'] !== client['id'])
+                    throw new OAuthError('invalid_grant', 'The token was issued to another client.');
+                if (token['rotated'] === true) {
+                    // A rotated refresh token used again: revoke the grant's tokens (RFC 9700 §4.14.2).
+                    await revokeGrantTokens(env, token['grant']);
+                    await audit(env, {
+                        kind: 'oauth.refresh_reused',
+                        summary: `A used refresh token of ${String(client['name'])} came back: its tokens are revoked.`,
+                        targetModel: 'oauth.app',
+                        targetId: client['id'],
+                        ip: request.ip,
+                    });
+                    return {
+                        failure: new OAuthError('invalid_grant', 'The refresh token was already used.'),
+                    };
+                }
+                if (token['revoked'] === true ||
+                    (timeOf(token['refreshExpiresAt']) ?? 0) <= Date.now() ||
+                    grant['revoked'] === true)
+                    throw new OAuthError('invalid_grant', 'The refresh token expired or was revoked.');
+                await model(env, 'oauth.token')
+                    .browse([token['id']])
+                    .write({ revoked: true, rotated: true });
+                return issue(env, token['grant']);
+            }
+            throw new OAuthError('unsupported_grant_type', 'Use authorization_code or refresh_token.');
+        });
+        if ('failure' in out)
+            throw out.failure;
+        return out;
+    };
+    // The token and revoke endpoints take form bodies (RFC 6749 §4.1.3) as well as JSON.
+    app.register(async (scope) => {
+        scope.addContentTypeParser('application/x-www-form-urlencoded', { parseAs: 'string', bodyLimit: 16_384 }, (_req, body, done) => done(null, Object.fromEntries(new URLSearchParams(String(body)))));
+        const answer = async (reply, run) => {
+            reply.header('cache-control', 'no-store').header('pragma', 'no-cache');
+            try {
+                return await run();
+            }
+            catch (e) {
+                if (!(e instanceof OAuthError))
+                    throw e;
+                if (e.status === 401)
+                    reply.header('www-authenticate', 'Basic realm="oauth"');
+                return reply.status(e.status).send({ error: e.code, error_description: e.description });
+            }
+        };
+        scope.post('/api/v1/oauth/token', { config: { auth: false } }, async (request, reply) => answer(reply, () => tokenEndpoint(request, (request.body ?? {}))));
+        scope.post('/api/v1/oauth/revoke', { config: { auth: false } }, async (request, reply) => answer(reply, () => system('revoke', async (env) => {
+            const body = (request.body ?? {});
+            const client = await clientOf(env, request, body);
+            const hash = digest(String(body['token'] ?? ''));
+            for (const where of [{ accessHash: hash }, { refreshHash: hash }]) {
+                const [token] = await find(env, 'oauth.token', where, ['grant']);
+                if (token === undefined)
+                    continue;
+                const [grant] = await find(env, 'oauth.grant', { id: token['grant'] }, ['app']);
+                // Another client's token: answered the same way (RFC 7009 §2.2), left alone.
+                if (grant?.['app'] === client['id'])
+                    await model(env, 'oauth.token')
+                        .browse([token['id']])
+                        .write({ revoked: true });
+            }
+            return {};
+        })));
+    });
+    // ------------------------------------------------------------------------------------- the user's grants
+    app.get('/api/v1/auth/oauth/grants', { config: { auth: false } }, async (request) => {
+        const session = await auth.requireSession(request);
+        return system('grants', async (env) => {
+            const grants = await find(env, 'oauth.grant', { user: session.user, revoked: false }, [
+                'app',
+                'scopes',
+                'createdAt',
+                'lastUsedAt',
+            ]);
+            const apps = new Map((await find(env, 'oauth.app', { id: { in: grants.map((g) => g['app']) } }, [
+                'name',
+                'homepage',
+            ])).map((a) => [a['id'], a]));
+            const iso = (v) => timeOf(v) === null ? null : new Date(timeOf(v)).toISOString();
+            return {
+                grants: grants.map((g) => ({
+                    id: g['id'],
+                    app: String(apps.get(g['app'])?.['name'] ?? ''),
+                    homepage: apps.get(g['app'])?.['homepage'] ?? null,
+                    scopes: words(g['scopes']).map((scope) => ({ scope, label: describe(scope) })),
+                    createdAt: iso(g['createdAt']),
+                    lastUsedAt: iso(g['lastUsedAt']),
+                })),
+            };
+        });
+    });
+    app.post('/api/v1/auth/oauth/grants/:id/revoke', { config: { auth: false } }, async (request, reply) => {
+        const session = await auth.requireSession(request);
+        const id = Number(request.params.id);
+        await system('revoke grant', async (env) => {
+            const grants = await model(env, 'oauth.grant').search({
+                where: { id, user: session.user },
+            });
+            if (grants.length === 0)
+                throw new HttpProblem(404, 'missing-record', 'Not found', `You have no grant ${id}.`);
+            await grants.write({ revoked: true });
+            await revokeGrantTokens(env, id);
+            await audit(env, {
+                kind: 'oauth.revoked',
+                summary: `Access of an app revoked (grant ${id}).`,
+                actor: session.user,
+                targetModel: 'oauth.grant',
+                targetId: id,
+                ip: request.ip,
+            });
+        });
+        return reply.status(204).send();
+    });
+    // ------------------------------------------------------------------------------------- the apps
+    /** Administrators and Integrations managers, with a session (no API key or token manages apps). */
+    const manager = async (request) => {
+        if (request.identity?.scopes !== undefined)
+            throw new HttpProblem(403, 'session-only', 'With a session only', 'OAuth apps are managed with a session.');
+        const session = await auth.requireSession(request);
+        const allowed = await request.env(async (env) => env.administrator || env.groups.has('integrations.manager'));
+        if (!allowed)
+            throw new HttpProblem(403, 'access', 'OAuth apps', 'Managing OAuth apps needs the Administrator role or the Integrations manager access.');
+        return session;
+    };
+    const appKeys = [
+        'name',
+        'clientId',
+        'confidential',
+        'redirectUris',
+        'scopes',
+        'homepage',
+        'active',
+    ];
+    const shape = (a) => ({
+        id: a['id'],
+        name: String(a['name']),
+        clientId: String(a['clientId']),
+        confidential: a['confidential'] === true,
+        redirectUris: words(a['redirectUris']),
+        scopes: words(a['scopes']),
+        homepage: a['homepage'] ?? null,
+        active: a['active'] === true,
+    });
+    const appValues = (body, creating) => {
+        const values = {};
+        const bad = (detail) => new HttpProblem(422, 'invalid-app', 'Invalid app', detail);
+        if (creating || body['name'] !== undefined) {
+            const name = String(body['name'] ?? '').trim();
+            if (name === '' || name.length > 120)
+                throw bad('The app needs a name.');
+            values['name'] = name;
+        }
+        if (creating || body['redirectUris'] !== undefined) {
+            const uris = Array.isArray(body['redirectUris']) ? body['redirectUris'].map(String) : [];
+            if (uris.length === 0)
+                throw bad('Give at least one redirect address.');
+            for (const uri of uris) {
+                let url;
+                try {
+                    url = new URL(uri);
+                }
+                catch {
+                    throw bad(`"${uri}" is not an address.`);
+                }
+                const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+                if (url.hash !== '' || (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)))
+                    throw bad(`"${uri}" must be https (http only for localhost), without a #fragment.`);
+            }
+            values['redirectUris'] = uris.join('\n');
+        }
+        if (creating || body['scopes'] !== undefined)
+            values['scopes'] = parseScopes(Array.isArray(body['scopes']) ? body['scopes'].map(String) : String(body['scopes'] ?? ''), installed()).join(' ');
+        if (body['homepage'] !== undefined)
+            values['homepage'] = body['homepage'] === null ? null : String(body['homepage']);
+        if (body['active'] !== undefined)
+            values['active'] = body['active'] === true;
+        return values;
+    };
+    app.get('/api/v1/oauth/apps', async (request) => {
+        await manager(request);
+        return system('apps', async (env) => ({
+            apps: (await find(env, 'oauth.app', {}, appKeys)).map(shape),
+        }));
+    });
+    app.post('/api/v1/oauth/apps', async (request, reply) => {
+        const session = await manager(request);
+        const body = (request.body ?? {});
+        const values = appValues(body, true);
+        const confidential = body['confidential'] !== false;
+        const secret = confidential ? `ks_${randomToken()}` : null;
+        const made = await system('new app', async (env) => {
+            const created = await model(env, 'oauth.app').create([
+                {
+                    ...values,
+                    clientId: `kc_${randomToken(12)}`,
+                    confidential,
+                    secretHash: secret === null ? null : digest(secret),
+                    owner: session.user,
+                },
+            ]);
+            const id = created.ids[0];
+            await audit(env, {
+                kind: 'oauth.app_created',
+                summary: `OAuth app ${String(values['name'])} created.`,
+                actor: session.user,
+                targetModel: 'oauth.app',
+                targetId: id,
+                ip: request.ip,
+            });
+            const [row] = await find(env, 'oauth.app', { id }, appKeys);
+            return shape(row);
+        });
+        // The secret once: only its digest is kept.
+        return reply.status(201).send({ ...made, clientSecret: secret });
+    });
+    app.patch('/api/v1/oauth/apps/:id', async (request) => {
+        const session = await manager(request);
+        const id = Number(request.params.id);
+        const values = appValues((request.body ?? {}), false);
+        return system('change app', async (env) => {
+            const set = await model(env, 'oauth.app').search({ where: { id } });
+            if (set.length === 0)
+                throw new HttpProblem(404, 'missing-record', 'Not found', `There is no app ${id}.`);
+            if (Object.keys(values).length > 0)
+                await set.write(values);
+            await audit(env, {
+                kind: 'oauth.app_changed',
+                summary: `OAuth app ${id} changed: ${Object.keys(values).join(', ')}.`,
+                actor: session.user,
+                targetModel: 'oauth.app',
+                targetId: id,
+                ip: request.ip,
+            });
+            const [row] = await find(env, 'oauth.app', { id }, appKeys);
+            return shape(row);
+        });
+    });
+    app.post('/api/v1/oauth/apps/:id/secret', async (request) => {
+        const session = await manager(request);
+        const id = Number(request.params.id);
+        const secret = `ks_${randomToken()}`;
+        await system('new secret', async (env) => {
+            const set = await model(env, 'oauth.app').search({ where: { id, confidential: true } });
+            if (set.length === 0)
+                throw new HttpProblem(404, 'missing-record', 'Not found', `There is no confidential app ${id}.`);
+            await set.write({ secretHash: digest(secret) });
+            await audit(env, {
+                kind: 'oauth.app_secret',
+                summary: `A new client secret for OAuth app ${id}; the old one stops working.`,
+                actor: session.user,
+                targetModel: 'oauth.app',
+                targetId: id,
+                ip: request.ip,
+            });
+        });
+        return { clientSecret: secret };
+    });
+}

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

@@ -41,6 +41,10 @@ export interface UserInfo {
     readonly groupings: Readonly<Record<string, 'international' | 'lakh'>>;
     /** The brand colour of each of the user's companies that has one (RFC 0018): `#rrggbb`. */
     readonly accents: Readonly<Record<string, string>>;
+    /** The user's photo version (`/api/v1/images/user/<id>?v=<version>`), or null without one. */
+    readonly avatar: string | null;
+    /** Each of the user's companies' logo version, when it has one. */
+    readonly logos: Readonly<Record<string, string>>;
     readonly twoFactorEnabled: boolean;
     /** Holds an administrator role (in some company). */
     readonly administrator: boolean;

package/dist/server/auth/service.js

@@ -1,7 +1,9 @@
 import { audit } from '../audit.js';
 import { HttpProblem } from '../errors.js';
+import { imageVersions } from '../images.js';
 import { keepingAdministrator } from './admins.js';
 import { digest, hashPassword, newTotpSecret, otpauthUri, randomToken, verifyPassword, verifyTotp, } from './crypto.js';
+import { resolveAccessToken } from './oauth.js';
 export const SESSION_COOKIE = 'kosh_session';
 const MIN_PASSWORD = 12;
 const model = (env, name) => env.model(name);
@@ -228,6 +230,18 @@ export class AuthService {
                 scopes: key.scopes,
                 apiKey: key.id,
             });
+        // An OAuth access token (RFC 0017 §5.2): the consenting user, within the grant's scopes.
+        const bearer = /^Bearer\s+(oat_\S+)$/i.exec(String(request.headers.authorization ?? ''))?.[1];
+        if (bearer !== undefined) {
+            const access = await this.#system('oauth token', (env) => resolveAccessToken(env, bearer));
+            if (access === null)
+                throw unauthenticated('invalid-token', 'The access token is unknown, expired or revoked.', 'Refresh it, or ask the user to allow the app again.');
+            return this.#identity(request, access.user, {
+                elevated: false,
+                scopes: access.scopes,
+                oauthToken: access.token,
+            });
+        }
         const session = await this.session(request);
         if (session === null)
             return null;
@@ -270,6 +284,7 @@ export class AuthService {
             tz: info.tz,
             ...(options.scopes === undefined ? {} : { scopes: options.scopes }),
             ...(options.apiKey === undefined ? {} : { apiKey: options.apiKey }),
+            ...(options.oauthToken === undefined ? {} : { oauthToken: options.oauthToken }),
             // A session without the second factor the policy asks of everyone (RFC 0019 §3.5): the server allows only
             // setting it up. API keys are not sessions: their owner signed in to make them.
             ...(options.session === true &&
@@ -574,6 +589,8 @@ export class AuthService {
                 companies: companyIds,
                 groupings,
                 accents,
+                avatar: (await imageVersions(env, 'user', [session.user]))[String(session.user)] ?? null,
+                logos: await imageVersions(env, 'company', companyIds),
                 twoFactorEnabled,
                 administrator,
                 administratorNeedsSecondFactor: administrator && !(session.secondFactor && twoFactorEnabled),

package/dist/server/identity.d.ts

@@ -24,6 +24,8 @@ export interface RequestIdentity {
     readonly scopes?: readonly string[];
     /** The API key the request carries. */
     readonly apiKey?: number;
+    /** The OAuth access token the request carries (RFC 0017 §5.2): its app acts for the user, within `scopes`. */
+    readonly oauthToken?: number;
     /** A session without the second factor the security policy asks of everyone (RFC 0019 §3.5). */
     readonly twoFactorMissing?: true;
 }

package/dist/server/images.d.ts

@@ -0,0 +1,12 @@
+import type { FastifyInstance } from 'fastify';
+import type { AuthService } from './auth/service.js';
+import type { Env } from './orm.js';
+declare const KINDS: {
+    readonly user: 'res.users';
+    readonly company: 'res.company';
+};
+type Kind = keyof typeof KINDS;
+/** The image versions of `ids` of a kind (a short digest), for URLs that change when the image does. */
+export declare function imageVersions(env: Env, kind: Kind, ids: readonly number[]): Promise<Record<string, string>>;
+export declare function registerImageRoutes(app: FastifyInstance, auth: AuthService): void;
+export {};