Files
HealthLog/src/lib/ai/capabilities/gate.ts
T
Marc-André Bombeck a19900c854 feat(ai): re-check a capability at the wire
requireAiCapability answers at the top of a route, before a provider is
picked, and a job enqueued before an operator switch flipped runs long
after any route answered. aiEgressRefusal asks again about the providers a
caller is about to send to: the capability for the record (the request's
own resolution, or the job's for the record it names) and, for exactly
those providers, whether a consent receipt of the kinds the capability
table declares is active.

A pickDecides gate option leaves no_provider and consent_required to that
pick, for routes that read the chain in their own order.
2026-09-24 08:44:49 +02:00

169 lines
6.1 KiB
TypeScript

/**
* The AI capability gates: how a route or a job asks whether it may call a
* model, or serve text a model wrote.
*
* - `requireAiCapability(key)`: AI action routes (they call a model or
* enqueue a job that will). Call it right after auth, before rate limits
* and body parsing; it throws `AiUnavailableError`, which `apiHandler`
* turns into the refusal envelope.
* - `getAiCapability(key)`: mixed reads that serve data plus optional model
* text. Never throws; returns the state so the route can null the model
* field and say why.
* - `aiCapabilityForJob(userId, key)`: workers, before they build a
* snapshot. No request context, so the record comes in as an argument and
* the authority is the worker's own.
*
* Data routes never import this file. A measurement, a score, a statistic or
* a device record does not depend on AI.
*
* The refusal envelope keeps every code a shipped client branches on:
*
* 403 { data: null, error, meta: { errorCode, capability, reason, module? } }
*
* operator_disabled → `assistant.disabled.<switch>`, or
* `module.disabled` + `meta.module` when the
* operator's module availability closed it
* not_permitted_for_record → `ai.record.notPermitted`
* module_disabled → `module.disabled` + `meta.module`
* user_disabled → `module.disabled` + `meta.module`
* no_provider → the route's own typed code where a client
* already reads one, otherwise
* `ai.provider.none`; 422
* consent_required → `consent.ai.required`
* check_failed → `ai.unavailable`; 503
*/
import { findActiveGrant } from "@/lib/sharing/grants";
import { resolveGrantSections } from "@/lib/sharing/grant-view";
import { getEvent } from "@/lib/logging/context";
import { providerWorkAuthorityForRecord } from "@/lib/sharing/provider-work-authority";
import { loadAiCapabilityInputs, type AiCapabilityScope } from "./load";
import { explainAiCapability, resolveAiCapability } from "./resolve";
import { AiUnavailableError, type NoProviderRefusal } from "./refusal";
import {
PICK_DECIDED_REASONS,
type AiCapabilityKey,
type AiCapabilityState,
} from "./types";
export interface AiGateOptions {
/**
* The record to resolve for. Defaults to the record this request resolved
* (`acting_as`, else the caller).
*/
recordId?: string;
/** The route's own `no_provider` refusal, where a client already reads it. */
noProvider?: NoProviderRefusal;
/**
* Leave `no_provider` and `consent_required` to the provider the route
* actually picks. The resolver answers both from presence, which is right
* for the published payload but can differ from a route that reads the
* chain in its own order (a text-mode document read takes the chain head,
* not the first vision entry). A route that sets this must run the pick
* through `assertAiEgress` / `aiEgressRefusal`, which answers both exactly.
*/
pickDecides?: boolean;
}
/**
* The scope of the current request: the record it resolved, the authority
* stamped for it, and the sections the grant opens. `null` outside a request
* that authenticated anybody.
*/
async function requestScope(
recordOverride?: string,
): Promise<AiCapabilityScope | null> {
const auth = getEvent()?.getAuth();
const actorId = auth?.user_id;
if (!actorId) return null;
const recordId = recordOverride ?? auth.acting_as ?? actorId;
const authority = providerWorkAuthorityForRecord(recordId);
if (recordId === actorId) {
return { recordId, authority, sections: null, recordKind: "self" };
}
// Inside somebody else's record: mask modules to what the grant opens, as
// the account payload does. `null` sections are an unscoped grant; a grant
// that cannot be found opens nothing.
const grant = await findActiveGrant({
grantorId: recordId,
granteeId: actorId,
});
return {
recordId,
authority,
sections: grant ? resolveGrantSections(grant.scopeJson) : [],
recordKind: authority?.origin === "guardian" ? "managed" : "shared",
};
}
/**
* A mixed read's question: may this request serve this capability? Never
* throws; a request with no authenticated caller reads `check_failed`.
*/
export async function getAiCapability(
key: AiCapabilityKey,
options: Pick<AiGateOptions, "recordId"> = {},
): Promise<AiCapabilityState> {
try {
const scope = await requestScope(options.recordId);
if (scope === null) return resolveAiCapability(key, null);
return resolveAiCapability(key, await loadAiCapabilityInputs(scope));
} catch {
return resolveAiCapability(key, null);
}
}
/**
* An AI action's gate. Returns the (available) state, or throws
* `AiUnavailableError` with the outermost reason.
*/
export async function requireAiCapability(
key: AiCapabilityKey,
options: AiGateOptions = {},
): Promise<AiCapabilityState> {
let finding: ReturnType<typeof explainAiCapability>;
try {
const scope = await requestScope(options.recordId);
finding = explainAiCapability(
key,
scope === null ? null : await loadAiCapabilityInputs(scope),
);
} catch {
finding = { reason: "check_failed", module: null };
}
if (
finding.reason !== null &&
!(options.pickDecides && PICK_DECIDED_REASONS.has(finding.reason))
) {
throw new AiUnavailableError(
key,
finding.reason,
finding.module,
options.noProvider,
);
}
return { available: true, reason: null, onDeviceAllowed: true };
}
/**
* A worker's gate. Resolves for `userId` under the worker's own authority
* (the authority the job was enqueued with, or `system`), with the whole
* record in view. Never throws.
*/
export async function aiCapabilityForJob(
userId: string,
key: AiCapabilityKey,
): Promise<AiCapabilityState> {
try {
const inputs = await loadAiCapabilityInputs({
recordId: userId,
authority: providerWorkAuthorityForRecord(userId),
sections: null,
recordKind: "self",
});
return resolveAiCapability(key, inputs);
} catch {
return resolveAiCapability(key, null);
}
}