@boopkit/cap-oauth-server 0.1.0

package/dist/config.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OauthServerConfigError = exports.REFRESH_TOKEN_TTL_BOUNDS = exports.ACCESS_TOKEN_TTL_BOUNDS = exports.DEFAULT_REFRESH_TOKEN_TTL_SECONDS = exports.DEFAULT_ACCESS_TOKEN_TTL_SECONDS = void 0;
+exports.clampTtlSeconds = clampTtlSeconds;
+exports.readServerConfig = readServerConfig;
+const client_registry_service_js_1 = require("./client-registry-service.js");
+const discovery_js_1 = require("./discovery.js");
+const rate_limit_js_1 = require("./rate-limit.js");
+/**
+ * Reading the capability's configuration out of the environment.
+ *
+ * ## Why the environment, and why here
+ *
+ * boop has no feature-flag system — the findings grepped every capability's
+ * `src/` and `scaffold/src/` for one and came back empty — so the `env` array in
+ * `capability.json` is the mechanism boop actually ships: it appends the
+ * declared variables to `.env` and records them in `.boop/config.json`.
+ *
+ * The parsing lives in the package rather than in the scaffold binding file for
+ * one reason: a value that is clamped, defaulted or warned about is behaviour,
+ * and behaviour in a scaffold file is behaviour that cannot be tested here and
+ * is copied into an application once and then never updated.
+ *
+ * ## Read once, at construction
+ *
+ * Every value here is read at boot, not per request, so a running process has
+ * one answer and a clamp warning fires once rather than on every token.
+ */
+/** RFC 6749 has no opinion; these are Decision 1's numbers. */
+exports.DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 900;
+exports.DEFAULT_REFRESH_TOKEN_TTL_SECONDS = 7776000;
+/**
+ * Clamps, not rejections.
+ *
+ * Above an hour the blast-radius argument for a short access token evaporates
+ * and we would be shipping a footgun as configuration; below a minute nothing
+ * works. But an application should not fail to boot over a token lifetime, so
+ * an out-of-range value is clamped and named in a warning.
+ */
+exports.ACCESS_TOKEN_TTL_BOUNDS = { min: 60, max: 3600 };
+exports.REFRESH_TOKEN_TTL_BOUNDS = { min: 3600, max: 31536000 };
+class OauthServerConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OauthServerConfigError';
+    }
+}
+exports.OauthServerConfigError = OauthServerConfigError;
+/**
+ * Bring a lifetime inside its documented bounds, naming the value and the bound
+ * if it was out of range.
+ *
+ * Exported because the *number* is clamped in two places for one reason: this
+ * module clamps what the environment said, and the token service clamps what it
+ * was constructed with. Those are not the same event — an application that
+ * builds the token service from a literal rather than from `readServerConfig`
+ * bypasses the first entirely — and a clamp that only one of them applies is a
+ * clamp a caller can walk around. One function, called twice, cannot disagree
+ * with itself about where the bounds are.
+ */
+function clampTtlSeconds(value, bounds, name, warn) {
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+        warn(`${name}=${String(value)} is not a positive whole number of seconds; using ${bounds.min}`);
+        return bounds.min;
+    }
+    if (value < bounds.min) {
+        warn(`${name}=${value} is below the ${bounds.min}s floor; using ${bounds.min}`);
+        return bounds.min;
+    }
+    if (value > bounds.max) {
+        warn(`${name}=${value} is above the ${bounds.max}s ceiling; using ${bounds.max}`);
+        return bounds.max;
+    }
+    return value;
+}
+function clampSeconds(raw, fallback, bounds, name, warn) {
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+        warn(`${name}="${raw}" is not a positive whole number of seconds; using ${fallback}`);
+        return fallback;
+    }
+    return clampTtlSeconds(value, bounds, name, warn);
+}
+function positiveInteger(raw, fallback, name, warn) {
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+        warn(`${name}="${raw}" is not a positive whole number; using ${fallback}`);
+        return fallback;
+    }
+    return value;
+}
+/** Trim one trailing slash so `https://app/` and `https://app` are one issuer. */
+function normaliseOrigin(value) {
+    return value.endsWith('/') ? value.slice(0, -1) : value;
+}
+/**
+ * Build the whole capability's configuration from an environment.
+ *
+ * Throws only for `OAUTH_ISSUER_URL`, which is `required: "boot"` in the
+ * manifest: every endpoint this capability serves is an absolute URL built from
+ * it, and a wrong issuer produces discovery documents that send clients
+ * somewhere else. That is worth refusing to boot over; a token lifetime is not.
+ */
+function readServerConfig(env, options = {}) {
+    const warn = options.warn ?? ((message) => console.warn(`[cap-oauth-server] ${message}`));
+    const issuerRaw = env.OAUTH_ISSUER_URL?.trim();
+    if (!issuerRaw) {
+        throw new OauthServerConfigError('OAUTH_ISSUER_URL is required: it is the origin every OAuth endpoint URL is built from');
+    }
+    let issuerUrl;
+    try {
+        issuerUrl = new URL(issuerRaw);
+    }
+    catch {
+        throw new OauthServerConfigError(`OAUTH_ISSUER_URL is not a URL: ${issuerRaw}`);
+    }
+    if (issuerUrl.protocol !== 'https:' && issuerUrl.hostname !== 'localhost') {
+        throw new OauthServerConfigError(`OAUTH_ISSUER_URL must be https (localhost excepted for development): ${issuerRaw}`);
+    }
+    const issuer = normaliseOrigin(issuerRaw);
+    // The protected resource is *not* the issuer. A client that connects to
+    // `https://app/api/mcp` has to read that exact string back out of the
+    // protected-resource document, so it is configured; the default is the
+    // issuer, which is right only for an app whose protected surface is its root.
+    const resource = normaliseOrigin(env.OAUTH_RESOURCE_URL?.trim() || issuer);
+    const scopesRaw = env.OAUTH_SCOPES_SUPPORTED?.trim();
+    const scopesSupported = scopesRaw
+        ? scopesRaw.split(/[\s,]+/).filter(Boolean)
+        : [...discovery_js_1.DEFAULT_SCOPES_SUPPORTED];
+    if (!scopesSupported.includes('offline_access')) {
+        // Without it a client cannot ask for a refresh token, and every connector
+        // in this ecosystem needs one — a connection the user has to re-approve
+        // every fifteen minutes is not a connection.
+        warn('OAUTH_SCOPES_SUPPORTED does not include offline_access; refresh tokens cannot be requested');
+    }
+    return {
+        issuer,
+        resource,
+        scopesSupported,
+        // Absent, empty, or anything other than the string "true" means off — and
+        // when off the grant type is absent from the metadata rather than
+        // advertised against an endpoint that answers 404. Slice 5 mounts the
+        // endpoints from this same value, so the two cannot drift.
+        deviceCodeEnabled: env.OAUTH_DEVICE_CODE_ENABLED === 'true',
+        documentationUri: env.OAUTH_DOCUMENTATION_URL?.trim() || undefined,
+        accessTokenTtlSeconds: clampSeconds(env.OAUTH_ACCESS_TOKEN_TTL_SECONDS, exports.DEFAULT_ACCESS_TOKEN_TTL_SECONDS, exports.ACCESS_TOKEN_TTL_BOUNDS, 'OAUTH_ACCESS_TOKEN_TTL_SECONDS', warn),
+        refreshTokenTtlSeconds: clampSeconds(env.OAUTH_REFRESH_TOKEN_TTL_SECONDS, exports.DEFAULT_REFRESH_TOKEN_TTL_SECONDS, exports.REFRESH_TOKEN_TTL_BOUNDS, 'OAUTH_REFRESH_TOKEN_TTL_SECONDS', warn),
+        maxRegisteredClients: positiveInteger(env.OAUTH_MAX_REGISTERED_CLIENTS, client_registry_service_js_1.DEFAULT_MAX_REGISTERED_CLIENTS, 'OAUTH_MAX_REGISTERED_CLIENTS', warn),
+        registrationRateLimit: positiveInteger(env.OAUTH_REGISTRATION_RATE_LIMIT, rate_limit_js_1.DEFAULT_REGISTRATION_RATE_LIMIT, 'OAUTH_REGISTRATION_RATE_LIMIT', warn),
+        registrationRateWindowMs: rate_limit_js_1.DEFAULT_REGISTRATION_RATE_WINDOW_MS,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/connections-controller.d.ts

@@ -0,0 +1,106 @@
+import { Router, type RequestHandler } from 'express';
+import type { ClientRegistryService } from './client-registry-service.js';
+import { type ConsentScopeView } from './consent-controller.js';
+import { type GrantService } from './grant-service.js';
+import { type RevocationService } from './revocation-service.js';
+import './express.js';
+/**
+ * `/connections` — the screen where a person sees what they have connected, and
+ * the confirmation page where they disconnect one.
+ *
+ * ## Three things here are decisions, not layout
+ *
+ * **The "previously connected" section.** Revocation is soft, and the audit
+ * trail is the reason it is soft. A screen that showed only live grants would
+ * make the ended rows invisible to the one person who has any use for them: the
+ * user who just disconnected something and wants to see that it stuck, and the
+ * user working out what a connector did last month. It is a quiet secondary
+ * section rather than a second list of equals — a disconnected client is
+ * history, not inventory.
+ *
+ * **The account-coverage statement.** Grants are keyed on the *user*, so a
+ * connected client reaches every account that user reaches, present and future.
+ * The consent screen says this before the Approve button; this screen has to say
+ * it too, because a user with more than one account who reads a list of client
+ * names will otherwise guess — and the natural guess, that a connector reaches
+ * the account they were looking at when they approved it, is wrong.
+ *
+ * **Disconnecting goes through its own page.** Not an inline delete on the row,
+ * and not a `confirm()`. Disconnecting is not undoable, and its consequence —
+ * an agent that stops working mid-conversation, and a whole authorization flow
+ * to walk again to undo it — is not visible from a row in a list. The dedicated
+ * page names the client and the consequence in the register the rest of the
+ * application already uses. `GET` renders it and changes nothing; only the
+ * `POST` revokes.
+ *
+ * ## Who may look
+ *
+ * The gate is cap-users' own `requireAuth`, injected. This is a cookie-session
+ * page in a browser, not a resource-server route, so it is gated the way every
+ * other page of the application is gated — and injecting the middleware rather
+ * than building a second one is what keeps this capability from having its own
+ * opinion about what "signed in" means. It is a required option for the same
+ * reason: an application cannot mount this screen and forget to gate it.
+ *
+ * Every read is narrowed by `req.user.id`, so a grant id belonging to somebody
+ * else resolves to nothing. There is no separate ownership check to forget.
+ */
+/** One connected client, as the screen shows it. */
+export interface ConnectionView {
+    grantId: string;
+    /** The client's display name, or its `client_id` when the row is gone. */
+    name: string;
+    logoUri?: string;
+    monogram: string;
+    provenance: string;
+    /** `static` / `metadata_document` / `dynamic`, for the provenance styling. */
+    mode?: string;
+    scopes: ConsentScopeView[];
+    connectedOn: string;
+    /** Present only in the previously-connected section. */
+    disconnectedOn?: string;
+    /** Why it ended. `user_revoked`, `client_revoked`, `refresh_reuse`. */
+    endedReason?: string;
+    /** Where the confirmation page for this connection lives. */
+    disconnectPath: string;
+}
+export interface ConnectionsHandlerDeps {
+    grantService: GrantService;
+    revocationService: RevocationService;
+    clientRegistry: ClientRegistryService;
+    /** cap-users' `requireAuth` middleware. Required — see the header. */
+    requireSignIn: RequestHandler;
+    /** Where this router is mounted. Every link on the page is built from it. */
+    basePath?: string;
+    /** View names, overridable so an application can ship its own pages. */
+    listViewName?: string;
+    confirmViewName?: string;
+    layout?: string;
+}
+export interface ConnectionsHandlers {
+    listConnections: RequestHandler;
+    showDisconnect: RequestHandler;
+    submitDisconnect: RequestHandler;
+}
+/**
+ * The coverage statement, in one place so the two screens cannot drift.
+ *
+ * Deliberately about reach rather than about mechanism. "Keyed on the user
+ * rather than the account" is true and is not what somebody deciding whether to
+ * disconnect a connector needs to read.
+ */
+export declare const ACCOUNT_COVERAGE_STATEMENT: string;
+export declare function createConnectionsHandlers(deps: ConnectionsHandlerDeps): ConnectionsHandlers;
+export interface ConnectionsRouterOptions extends ConnectionsHandlerDeps {
+    bodyLimit?: string;
+}
+/**
+ * `GET /connections`, `GET /connections/:grantId/disconnect`, `POST` the same.
+ *
+ * The `GET` on the disconnect path renders and revokes nothing. That split is
+ * the whole reason the confirmation page exists rather than a link — a `GET`
+ * that revoked would be triggered by a link prefetch, a crawler, or a browser
+ * restoring tabs, none of which is a person deciding anything.
+ */
+export declare function createConnectionsRouter(options: ConnectionsRouterOptions): Router;
+//# sourceMappingURL=connections-controller.d.ts.map

package/dist/connections-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections-controller.d.ts","sourceRoot":"","sources":["../src/connections-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAA4B,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAGhF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAML,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAiB,KAAK,YAAY,EAAyB,MAAM,oBAAoB,CAAC;AAC7F,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,cAAc,CAAC;AAGtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,YAAY,CAAC;IAC3B,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,cAAc,EAAE,qBAAqB,CAAC;IACtC,sEAAsE;IACtE,aAAa,EAAE,cAAc,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,cAAc,CAAC;IAChC,cAAc,EAAE,cAAc,CAAC;IAC/B,gBAAgB,EAAE,cAAc,CAAC;CAClC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAGlB,CAAC;AAUtB,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,sBAAsB,GAAG,mBAAmB,CA6H3F;AAED,MAAM,WAAW,wBAAyB,SAAQ,sBAAsB;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAejF"}

package/dist/connections-controller.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACCOUNT_COVERAGE_STATEMENT = void 0;
+exports.createConnectionsHandlers = createConnectionsHandlers;
+exports.createConnectionsRouter = createConnectionsRouter;
+const express_1 = require("express");
+const consent_controller_js_1 = require("./consent-controller.js");
+const grant_service_js_1 = require("./grant-service.js");
+const revocation_service_js_1 = require("./revocation-service.js");
+require("./express.js");
+/**
+ * The coverage statement, in one place so the two screens cannot drift.
+ *
+ * Deliberately about reach rather than about mechanism. "Keyed on the user
+ * rather than the account" is true and is not what somebody deciding whether to
+ * disconnect a connector needs to read.
+ */
+exports.ACCOUNT_COVERAGE_STATEMENT = 'A connected application can act anywhere you can — including any organisation or ' +
+    'team you belong to now or join later, not only the one you were looking at when ' +
+    'you connected it.';
+/** `March 28, 2026` — the same shape cap-web's `fmt_date` helper produces. */
+function formatDate(iso) {
+    if (!iso)
+        return '';
+    const date = new Date(iso);
+    if (Number.isNaN(date.getTime()))
+        return '';
+    return date.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
+}
+function createConnectionsHandlers(deps) {
+    const { grantService, revocationService, clientRegistry } = deps;
+    const basePath = deps.basePath ?? '/connections';
+    const listViewName = deps.listViewName ?? 'oauth-connected-clients';
+    const confirmViewName = deps.confirmViewName ?? 'oauth-disconnect-confirm';
+    const layout = deps.layout ?? 'main';
+    function userOf(req) {
+        return req.user;
+    }
+    /**
+     * The client behind a grant, or nothing.
+     *
+     * Nothing is a real state: dynamic registrations are pruned when they are
+     * abandoned, so a grant can outlive the registry row that described the
+     * client. The view falls back to the `client_id`, which is at least the string
+     * the client presented, rather than dropping the row — a connection the screen
+     * does not list is a connection nobody can disconnect.
+     */
+    async function clientFor(grant) {
+        try {
+            return await clientRegistry.findByClientId(grant.client_id);
+        }
+        catch {
+            return null;
+        }
+    }
+    async function toView(req, grant) {
+        const client = await clientFor(grant);
+        const view = {
+            grantId: grant.grant_id,
+            name: client?.name ?? grant.client_id,
+            logoUri: client ? (0, consent_controller_js_1.safeLogoUri)(client.logoUri) : undefined,
+            monogram: client
+                ? (0, consent_controller_js_1.monogramFor)(client)
+                : (([...grant.client_id].find((ch) => /[\p{L}\p{N}]/u.test(ch)) ?? '?').toUpperCase()),
+            provenance: client
+                ? (0, consent_controller_js_1.provenanceFor)(client)
+                : 'This application is no longer registered here.',
+            mode: client?.mode,
+            scopes: (0, consent_controller_js_1.toScopeViews)(grant.scopes, (0, consent_controller_js_1.scopeDescriptionsFrom)(req)),
+            connectedOn: formatDate(grant.created_at),
+            disconnectPath: `${basePath}/${encodeURIComponent(grant.grant_id)}/disconnect`,
+        };
+        if (!(0, grant_service_js_1.isGrantActive)(grant)) {
+            view.disconnectedOn = formatDate(grant.ended_at);
+            view.endedReason = grant.ended_reason ?? undefined;
+        }
+        return view;
+    }
+    const listConnections = async (req, res, next) => {
+        const user = userOf(req);
+        if (!user)
+            return next();
+        try {
+            const grants = await grantService.list(user.id);
+            const connected = await Promise.all(grants.filter(grant_service_js_1.isGrantActive).map((grant) => toView(req, grant)));
+            const previous = await Promise.all(grants.filter((grant) => !(0, grant_service_js_1.isGrantActive)(grant)).map((grant) => toView(req, grant)));
+            res.render(listViewName, {
+                layout,
+                connected,
+                previous,
+                hasConnected: connected.length > 0,
+                hasPrevious: previous.length > 0,
+                coverage: exports.ACCOUNT_COVERAGE_STATEMENT,
+                // Set by the redirect after a successful disconnect, so the page can
+                // confirm what just happened rather than silently re-rendering a list
+                // with one fewer row in it.
+                disconnected: typeof req.query.disconnected === 'string' ? req.query.disconnected : undefined,
+            });
+        }
+        catch (err) {
+            next(err);
+        }
+    };
+    const showDisconnect = async (req, res, next) => {
+        const user = userOf(req);
+        if (!user)
+            return next();
+        try {
+            const grant = await grantService.findById(user.id, String(req.params.grantId));
+            // Already gone, or never this user's. Both land on the list, which is
+            // where the answer is — and neither says which of the two it was.
+            if (!grant || !(0, grant_service_js_1.isGrantActive)(grant))
+                return res.redirect(302, basePath);
+            res.render(confirmViewName, {
+                layout,
+                connection: await toView(req, grant),
+                coverage: exports.ACCOUNT_COVERAGE_STATEMENT,
+                action: `${basePath}/${encodeURIComponent(grant.grant_id)}/disconnect`,
+                cancelPath: basePath,
+            });
+        }
+        catch (err) {
+            next(err);
+        }
+    };
+    const submitDisconnect = async (req, res, next) => {
+        const user = userOf(req);
+        if (!user)
+            return next();
+        try {
+            const revoked = await revocationService.revokeGrant(user.id, String(req.params.grantId), revocation_service_js_1.REVOKED_BY_USER);
+            if (!revoked)
+                return res.redirect(302, basePath);
+            const client = await clientFor(revoked.grant);
+            const name = client?.name ?? revoked.grant.client_id;
+            res.redirect(302, `${basePath}?disconnected=${encodeURIComponent(name)}`);
+        }
+        catch (err) {
+            next(err);
+        }
+    };
+    return { listConnections, showDisconnect, submitDisconnect };
+}
+/**
+ * `GET /connections`, `GET /connections/:grantId/disconnect`, `POST` the same.
+ *
+ * The `GET` on the disconnect path renders and revokes nothing. That split is
+ * the whole reason the confirmation page exists rather than a link — a `GET`
+ * that revoked would be triggered by a link prefetch, a crawler, or a browser
+ * restoring tabs, none of which is a person deciding anything.
+ */
+function createConnectionsRouter(options) {
+    const handlers = createConnectionsHandlers(options);
+    const basePath = options.basePath ?? '/connections';
+    const router = (0, express_1.Router)();
+    router.get(basePath, options.requireSignIn, handlers.listConnections);
+    router.get(`${basePath}/:grantId/disconnect`, options.requireSignIn, handlers.showDisconnect);
+    router.post(`${basePath}/:grantId/disconnect`, options.requireSignIn, (0, express_1.urlencoded)({ extended: false, limit: options.bodyLimit ?? '16kb' }), handlers.submitDisconnect);
+    return router;
+}
+//# sourceMappingURL=connections-controller.js.map

package/dist/connections-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections-controller.js","sourceRoot":"","sources":["../src/connections-controller.ts"],"names":[],"mappings":"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"}

package/dist/consent-controller.d.ts

@@ -0,0 +1,197 @@
+import { Router, type Request, type RequestHandler } from 'express';
+import type { BaseUserInfo, User } from '@boopkit/cap-users';
+import type { AuthorizationCodeService } from './authorization-code-service.js';
+import type { ClientRegistryService } from './client-registry-service.js';
+import './express.js';
+import type { OauthClient } from './types.js';
+/** Which of the three faces the page is wearing. */
+export type ConsentVariant = 'authenticated' | 'login' | 'signup';
+/** The authorization request, after parsing and before it is trusted. */
+export interface AuthorizationRequest {
+    responseType: string;
+    clientId: string;
+    redirectUri: string;
+    scopes: string[];
+    state?: string;
+    codeChallenge: string;
+    codeChallengeMethod: string;
+    resource?: string;
+}
+/** What the page collects on the login face, and hands to `signIn`. */
+export interface ConsentCredentials {
+    email: string;
+    password: string;
+    /**
+     * The session token the browser already carries, if any. cap-users' `login`
+     * takes it as its third argument and end-dates it, which is the session
+     * rotation OWASP asks for on a privilege change — an application's own
+     * sign-in should do the same with it.
+     */
+    sessionToken?: string;
+}
+/** What the page collects on the signup face, and hands to `register`. */
+export interface ConsentRegistration {
+    email: string;
+    password: string;
+    passwordConfirmation: string;
+}
+/**
+ * A signed-in person and the session token that proves it — the shape both
+ * cap-users' `login` and its `signup` already return.
+ */
+export interface ConsentSession {
+    user: User<BaseUserInfo>;
+    sessionToken: string;
+}
+/**
+ * How this application signs somebody in, and how it creates an account.
+ *
+ * Both are ports rather than a `cap-users` `AuthService`, and that is the same
+ * decision `createConnectionsRouter` makes with `requireSignIn`: the capability
+ * has no opinion about what signing in means here, because it cannot have a
+ * correct one.
+ *
+ * The failure that made these ports necessary: `authService.login` resolves
+ * credentials through a **proven `email` identity**, and an application is free
+ * to mint that identity later than signup — wishfleet does, so its own login
+ * controller tries `authService.login` and falls back to matching the unproven
+ * `profile.email` claim. When the consent screen called `authService.login`
+ * directly, the same person and the same password were admitted by the
+ * application's login form and refused here, and no wording could fix it:
+ * cap-users returns one generic failure on purpose, so that saying more would
+ * be a user-enumeration signal.
+ *
+ * An application with no such divergence passes cap-users straight through —
+ * see the scaffold binding, which is two one-line adapters.
+ *
+ * Rejecting is how both say no: throw. The login face shows one generic message
+ * whatever the reason, and the signup face shows the thrown `Error`'s message,
+ * so a validation failure a person can act on ("passwords do not match") should
+ * carry words worth reading.
+ */
+export type ConsentSignIn = (credentials: ConsentCredentials) => Promise<ConsentSession>;
+export type ConsentRegister = (registration: ConsentRegistration) => Promise<ConsentSession>;
+export interface ConsentHandlerDeps {
+    clientRegistry: ClientRegistryService;
+    authorizationCodeService: AuthorizationCodeService;
+    /**
+     * Sign in the person on the login face. Required, for the same reason
+     * `requireSignIn` is required on the connections router: an application must
+     * not be able to mount this page and inherit somebody else's answer.
+     */
+    signIn: ConsentSignIn;
+    /** Create the account on the signup face. Required, for the same reason. */
+    register: ConsentRegister;
+    /** Scopes this server advertises. A request may not exceed them. */
+    scopesSupported: string[];
+    /**
+     * Scope descriptions the application already had when this router was built.
+     *
+     * Optional, and rarely what an application uses: descriptions normally arrive
+     * on `app.locals`, which is late-bound and therefore the authority. Anything
+     * given here is a default that `app.locals` overrides key by key — so passing
+     * it can only add words, never take the application's own away.
+     */
+    scopeDescriptions?: ScopeDescriptions;
+    /** The view name. Overridable so an application can ship its own page. */
+    viewName?: string;
+    /** The layout the view is rendered into. `main` is cap-web's. */
+    layout?: string;
+    /** Where the form posts. Must be the mounted path of the POST handler. */
+    actionPath?: string;
+}
+/**
+ * The application's scope vocabulary, as published on `app.locals`.
+ *
+ * A plain `Record<scope, description>`. Absent entirely is a valid state for an
+ * application that has not got to it yet — the page still renders, and the boot
+ * warning is what tells the developer to.
+ */
+export type ScopeDescriptions = Record<string, string>;
+export declare const SCOPE_DESCRIPTIONS_LOCAL = "oauthScopeDescriptions";
+/**
+ * Turn a scope list into what a page shows, given the application's vocabulary.
+ *
+ * Exported because the consent screen and the connected-clients screen must
+ * describe the same scope with the same words. A user who approved "See your
+ * name and email address" and later reads "profile" on the management screen
+ * cannot tell they are looking at the same thing.
+ */
+export declare function toScopeViews(scopes: readonly string[], descriptions: ScopeDescriptions | undefined): ConsentScopeView[];
+/**
+ * The application's scope vocabulary, wherever it was published.
+ *
+ * `app.locals` wins over anything passed at construction, because it is written
+ * later and by the application itself. Merging rather than choosing means the
+ * two cannot silently disagree: a factory argument that the page ignored used to
+ * be enough to silence the boot warning while the page still showed raw strings.
+ */
+export declare function scopeDescriptionsFrom(req: Request, defaults?: ScopeDescriptions): ScopeDescriptions | undefined;
+/** One scope, as the page shows it. */
+export interface ConsentScopeView {
+    value: string;
+    description: string;
+    /** False when the application supplied no words for this scope. */
+    described: boolean;
+}
+/**
+ * Warn, once at boot, about every advertised scope the application has not
+ * described.
+ *
+ * Called from the router factory rather than left to the developer to remember,
+ * because the failure it prevents is silent: the page renders, the raw string
+ * appears where a sentence should be, and nothing anywhere says that a consent
+ * screen is asking an unanswerable question.
+ */
+export declare function warnUndescribedScopes(scopesSupported: readonly string[], descriptions: ScopeDescriptions | undefined, warn?: (message: string) => void): string[];
+/** What the page says about where this client's claims came from. */
+export declare function provenanceFor(client: OauthClient): string;
+/**
+ * An icon URL we are willing to put in an `<img src>`, or nothing.
+ *
+ * `https` only. `http` would break the page's padlock, and `data:` and
+ * `javascript:` are a stranger's payload rendered inside our own origin's page.
+ * The box's size is fixed in CSS regardless, so this decides only whether there
+ * is an image at all — never how much room it gets.
+ */
+export declare function safeLogoUri(value: string | null | undefined): string | undefined;
+/** The letter in the icon box when there is no usable image. */
+export declare function monogramFor(client: OauthClient): string;
+export interface ConsentHandlers {
+    showConsent: RequestHandler;
+    submitConsent: RequestHandler;
+}
+export declare function createConsentHandlers(deps: ConsentHandlerDeps): ConsentHandlers;
+export interface ConsentRouterOptions extends ConsentHandlerDeps {
+    /** Where the undescribed-scope warning goes. Defaults to `console.warn`. */
+    warn?(message: string): void;
+    bodyLimit?: string;
+}
+/**
+ * `GET` and `POST /oauth/authorize`.
+ *
+ * ## Why the undescribed-scope warning fires on the first request
+ *
+ * It used to fire here, at construction, on the argument that a warning a
+ * developer only sees when somebody reaches the consent screen is a warning they
+ * see in production. That reasoning is right and the placement was still wrong,
+ * because at construction there is nothing true to judge: the descriptions live
+ * on `app.locals`, an application publishes them after this router is built —
+ * boop injects every capability's mount above an application's own
+ * `app.locals` assignments — and the factory argument is one the shipped
+ * scaffold does not pass. So the check ran against `undefined` and named every
+ * advertised scope, on every boot, however carefully the application had
+ * described them. The wishfleet integration met exactly that: three scopes
+ * described, three scopes reported missing (boop-2vdy.8.5).
+ *
+ * A warning that always fires is worse than none, because it trains a developer
+ * to scroll past the line that would have told them their consent screen was
+ * asking an unanswerable question.
+ *
+ * So it fires on the first request this router serves, which is the earliest
+ * moment the value it must judge exists — and, since the router sits on the
+ * application's own mount, that is the first request to the site rather than the
+ * first one to reach the consent screen. Once per router, not once per request.
+ */
+export declare function createConsentRouter(options: ConsentRouterOptions): Router;
+//# sourceMappingURL=consent-controller.d.ts.map

package/dist/consent-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent-controller.d.ts","sourceRoot":"","sources":["../src/consent-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAc,KAAK,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,SAAS,CAAC;AAC/F,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAG1E,OAAO,cAAc,CAAC;AACtB,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,YAAY,CAAC;AAmE1D,oDAAoD;AACpD,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,OAAO,GAAG,QAAQ,CAAC;AAElE,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,WAAW,EAAE,kBAAkB,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;AACzF,MAAM,MAAM,eAAe,GAAG,CAAC,YAAY,EAAE,mBAAmB,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;AAE7F,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,qBAAqB,CAAC;IACtC,wBAAwB,EAAE,wBAAwB,CAAC;IACnD;;;;OAIG;IACH,MAAM,EAAE,aAAa,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,EAAE,eAAe,CAAC;IAC1B,oEAAoE;IACpE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEvD,eAAO,MAAM,wBAAwB,2BAA2B,CAAC;AAEjE;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,YAAY,EAAE,iBAAiB,GAAG,SAAS,GAC1C,gBAAgB,EAAE,CAMpB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,iBAAiB,GAAG,SAAS,CAK/B;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,eAAe,EAAE,SAAS,MAAM,EAAE,EAClC,YAAY,EAAE,iBAAiB,GAAG,SAAS,EAC3C,IAAI,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAiE,GAC3F,MAAM,EAAE,CAYV;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAezD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAQhF;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAWvD;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,cAAc,CAAC;IAC5B,aAAa,EAAE,cAAc,CAAC;CAC/B;AAqCD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe,CAoU/E;AAED,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D,4EAA4E;IAC5E,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAyBzE"}