@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.10

package/dist/ai/keys/user-ai-keys.controller.js

@@ -0,0 +1,204 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserAiKeysController = void 0;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const index_1 = require("../../identity/index");
+const ai_constants_1 = require("../ai.constants");
+const index_2 = require("../../core/index");
+const index_3 = require("../../core/index");
+const ai_enabled_guard_1 = require("../config/ai-enabled.guard");
+const ai_org_enabled_interceptor_1 = require("../config/ai-org-enabled.interceptor");
+const usable_ai_model_dto_1 = require("./dto/usable-ai-model.dto");
+const user_ai_key_dto_1 = require("./dto/user-ai-key.dto");
+const usable_models_service_1 = require("./usable-models.service");
+const user_ai_keys_service_1 = require("./user-ai-keys.service");
+// =============================================================================
+// UserAiKeysController (issue #431, epic #419)
+// =============================================================================
+//
+// The caller's own AI surface under `/api/ai/*`:
+//
+//   GET    /api/ai/keys                    ai:use
+//   PUT    /api/ai/keys/:provider          ai:use
+//   DELETE /api/ai/keys/:provider          ai:use (204, idempotent)
+//   POST   /api/ai/keys/:provider/test     ai:use (always 200)
+//   GET    /api/ai/models                  ai:use
+//
+// `AiEnabledGuard` on the CLASS: while `ai.enabled` is false every route here
+// answers `403` with `details.reason: 'AI_DISABLED'` (docs/specs/ai-platform.md
+// §2.19). Only `GET /api/ai/config` (AiPublicController) escapes that guard.
+//
+// Every route acts on `@CurrentUser('id')` — there is no `:userId` anywhere, so
+// no request can name another user's key.
+//
+// ⚠ WRITE-ONLY KEYS. No response here carries key material.
+// =============================================================================
+const PROVIDER_PARAM = {
+    name: 'provider',
+    description: 'Provider id, e.g. `openai`.',
+    example: 'openai',
+};
+/**
+ * Exported for the reference app's wiring and tests (route discovery, contract
+ * and egress suites); not part of the slice's documented surface.
+ *
+ * @internal
+ */
+let UserAiKeysController = class UserAiKeysController {
+    keys;
+    usableModels;
+    constructor(keys, usableModels) {
+        this.keys = keys;
+        this.usableModels = usableModels;
+    }
+    async list(userId) {
+        return this.keys.list(userId);
+    }
+    async set(provider, dto, userId) {
+        return this.keys.set(userId, provider, dto.apiKey);
+    }
+    async remove(provider, userId) {
+        await this.keys.remove(userId, provider);
+    }
+    async test(provider, dto, userId) {
+        return this.keys.test(userId, provider, dto.apiKey);
+    }
+    async listModels(userId, orgId) {
+        return this.usableModels.listForUser(userId, { orgId });
+    }
+};
+exports.UserAiKeysController = UserAiKeysController;
+__decorate([
+    (0, common_1.Get)('keys'),
+    (0, index_1.Auth)({ permissions: [ai_constants_1.PERMISSIONS.AI_USE] }),
+    (0, swagger_1.ApiOperation)({
+        summary: 'List my AI provider keys',
+        description: 'One entry per enabled provider, whether or not you have stored a key for it. Each ' +
+            'entry is masked: `hint` shows the last four characters, never the key. ' +
+            '`lastErrorCode` records a key the provider has since rejected (it is kept, not ' +
+            'deleted). `403` with `details.reason: "AI_DISABLED"` while AI is disabled.',
+    }),
+    (0, index_2.ApiDataResponse)(user_ai_key_dto_1.UserAiKeyViewDto, { isArray: true, description: 'Your keys, masked' }),
+    (0, swagger_1.ApiResponse)({ status: 403, description: '`AI_DISABLED`, or missing `ai:use`', type: index_3.ErrorDto }),
+    __param(0, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], UserAiKeysController.prototype, "list", null);
+__decorate([
+    (0, common_1.Put)('keys/:provider'),
+    (0, index_1.Auth)({ permissions: [ai_constants_1.PERMISSIONS.AI_USE] }),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Set or replace my key for a provider',
+        description: 'The key is **verified against the provider first**, then the models it can reach ' +
+            'are computed, and only then is it stored (encrypted). A rejected key answers **400** ' +
+            'with `details.reason: "AI_KEY_INVALID"` and **nothing is stored**; an unreachable ' +
+            'provider answers with its own error (e.g. 503 `AI_PROVIDER_UNAVAILABLE`), also ' +
+            'storing nothing. **Write-only**: the response is the masked view, never the key.',
+    }),
+    (0, swagger_1.ApiParam)(PROVIDER_PARAM),
+    (0, index_2.ApiDataResponse)(user_ai_key_dto_1.UserAiKeyViewDto, { description: 'The stored key, masked' }),
+    (0, swagger_1.ApiResponse)({ status: 400, description: 'Validation error, or `AI_KEY_INVALID`', type: index_3.ErrorDto }),
+    (0, swagger_1.ApiResponse)({
+        status: 403,
+        description: '`AI_DISABLED`, `AI_PROVIDER_DISABLED`, or missing `ai:use`',
+        type: index_3.ErrorDto,
+    }),
+    (0, swagger_1.ApiResponse)({ status: 503, description: 'The provider could not be reached to verify the key', type: index_3.ErrorDto }),
+    __param(0, (0, common_1.Param)('provider')),
+    __param(1, (0, common_1.Body)()),
+    __param(2, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, user_ai_key_dto_1.SetUserAiKeyDto, String]),
+    __metadata("design:returntype", Promise)
+], UserAiKeysController.prototype, "set", null);
+__decorate([
+    (0, common_1.Delete)('keys/:provider'),
+    (0, index_1.Auth)({ permissions: [ai_constants_1.PERMISSIONS.AI_USE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.NO_CONTENT),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Remove my key for a provider',
+        description: 'Deletes your stored key. Idempotent: removing a key you do not have is a 204.',
+    }),
+    (0, swagger_1.ApiParam)(PROVIDER_PARAM),
+    (0, swagger_1.ApiResponse)({ status: 204, description: 'Removed (or there was nothing to remove)' }),
+    (0, swagger_1.ApiResponse)({ status: 403, description: '`AI_DISABLED`, or missing `ai:use`', type: index_3.ErrorDto }),
+    __param(0, (0, common_1.Param)('provider')),
+    __param(1, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:returntype", Promise)
+], UserAiKeysController.prototype, "remove", null);
+__decorate([
+    (0, common_1.Post)('keys/:provider/test'),
+    (0, index_1.Auth)({ permissions: [ai_constants_1.PERMISSIONS.AI_USE] }),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Test a key for a provider',
+        description: 'Runs two checks: `credentials` (the provider accepts the key) and `list_models` ' +
+            '(how many catalog models it can reach). A blank or absent `apiKey` tests **your ' +
+            'stored key** and also refreshes its verification time, `lastErrorCode` and ' +
+            'reachable models; a submitted key is used for this call only and never stored. No ' +
+            'test response is generated — that would bill your provider account.\n\n' +
+            '⚠ **Always HTTP 200** — a rejected key is a successful diagnosis. Read `success` ' +
+            'and each check’s `status`/`code`.',
+    }),
+    (0, swagger_1.ApiParam)(PROVIDER_PARAM),
+    (0, index_2.ApiDataResponse)(user_ai_key_dto_1.UserAiKeyTestResultDto, { description: 'The probe result (read `success`)' }),
+    (0, swagger_1.ApiResponse)({ status: 400, description: 'Validation error', type: index_3.ErrorDto }),
+    (0, swagger_1.ApiResponse)({
+        status: 403,
+        description: '`AI_DISABLED`, `AI_PROVIDER_DISABLED`, or missing `ai:use`',
+        type: index_3.ErrorDto,
+    }),
+    __param(0, (0, common_1.Param)('provider')),
+    __param(1, (0, common_1.Body)()),
+    __param(2, (0, index_1.CurrentUser)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, user_ai_key_dto_1.TestUserAiKeyDto, String]),
+    __metadata("design:returntype", Promise)
+], UserAiKeysController.prototype, "test", null);
+__decorate([
+    (0, common_1.Get)('models'),
+    (0, index_1.Auth)({ permissions: [ai_constants_1.PERMISSIONS.AI_USE] }),
+    (0, swagger_1.ApiOperation)({
+        summary: 'List the AI models I can use',
+        description: 'Every model you can call right now: admin-enabled, not deprecated, and reachable ' +
+            'with **your** key for its provider (`keySource: "user"`). When you have no key for ' +
+            'a provider and an organisation key is stored for it, every admin-enabled model of ' +
+            'that provider is listed with `keySource: "org"` when the deployment\'s key policy is ' +
+            '`byok_with_org_fallback`, or — under either policy — when you hold `ai_config:write` ' +
+            '(the administrator who configured the organisation key). Otherwise that provider ' +
+            'contributes nothing. Sorted by provider, ' +
+            'then model id. `403` with `details.reason: "AI_DISABLED"` while AI is disabled.',
+    }),
+    (0, index_2.ApiDataResponse)(usable_ai_model_dto_1.UsableAiModelDto, { isArray: true, description: 'The models you can use' }),
+    (0, swagger_1.ApiResponse)({ status: 403, description: '`AI_DISABLED`, or missing `ai:use`', type: index_3.ErrorDto }),
+    __param(0, (0, index_1.CurrentUser)('id')),
+    __param(1, (0, index_1.CurrentOrg)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:returntype", Promise)
+], UserAiKeysController.prototype, "listModels", null);
+exports.UserAiKeysController = UserAiKeysController = __decorate([
+    (0, swagger_1.ApiTags)('AI'),
+    (0, common_1.Controller)('ai'),
+    (0, common_1.UseGuards)(ai_enabled_guard_1.AiEnabledGuard),
+    (0, common_1.UseInterceptors)(ai_org_enabled_interceptor_1.AiOrgEnabledInterceptor),
+    __metadata("design:paramtypes", [user_ai_keys_service_1.UserAiKeysService,
+        usable_models_service_1.UsableModelsService])
+], UserAiKeysController);
+//# sourceMappingURL=user-ai-keys.controller.js.map

package/dist/ai/keys/user-ai-keys.controller.js.map

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

package/dist/ai/keys/user-ai-keys.service.d.ts

@@ -0,0 +1,143 @@
+import { JobsService } from '../../jobs/index';
+import type { AiPrisma } from '../data/ai-db';
+import { AiConfigService } from '../config/ai-config.service';
+import { AiError } from '../core/ai-error';
+import { AiProviderRegistry } from '../core/provider-registry';
+import type { UserAiKeyTestCheck, UserAiKeyTestResult, UserAiKeyView } from './dto/user-ai-key.dto';
+/** What one probe of a key found. Never carries the key. */
+export interface UserAiKeyProbe {
+    credentials: UserAiKeyTestCheck;
+    listModels: UserAiKeyTestCheck;
+    /** Catalog model ids reachable with the key, when `list_models` passed; otherwise null. */
+    reachableModelIds: string[] | null;
+    /** The first failure, as an `AiError`, or null when both checks passed. */
+    error: AiError | null;
+}
+/**
+ * Outcome of re-checking one stored key (`recheckReachable`).
+ *
+ * @stability experimental
+ */
+export type UserAiKeyRecheckOutcome = 'ok' | 'invalid' | 'missing' | 'failed';
+/**
+ * What one `recheckStale` sweep did, per outcome.
+ *
+ * @stability experimental
+ */
+export type UserAiKeyRecheckCounts = Record<UserAiKeyRecheckOutcome, number>;
+/**
+ * "Bring your own key": each user's own provider keys (`user_ai_keys`,
+ * encrypted under the `ai_user_key` purpose). The HTTP surface is
+ * `/api/ai/keys`; `importKey` lets a fork migrate keys it already holds.
+ *
+ * @stability experimental
+ */
+export declare class UserAiKeysService {
+    private readonly prisma;
+    private readonly aiConfig;
+    private readonly registry;
+    private readonly jobs?;
+    private readonly logger;
+    constructor(prisma: AiPrisma, aiConfig: AiConfigService, registry: AiProviderRegistry, jobs?: JobsService | undefined);
+    /**
+     * Imports a user's existing provider key from another system, for an app's
+     * one-off DATA MIGRATION (kvox, MemoriaHub). The key is encrypted through
+     * the same path as {@link set} and stored UNVERIFIED (`verifiedAt: null`,
+     * no reachable models yet), and the provider's `ai.keys.recheck` job is
+     * queued (deduplicated on the subject the recheck task uses), which
+     * verifies it and computes its reachable models. Audited
+     * `ai:user-key:import` with the `source`, never the key.
+     *
+     * Never exposed over HTTP. Replaces any key the user already stored for
+     * `provider`.
+     *
+     * @param userId - the key's owner.
+     * @param provider - a provider id (need not be enabled yet).
+     * @param plaintext - the key; never logged, returned or audited.
+     * @param opts - `source`: where it came from (`kvox`), recorded on the audit row.
+     *
+     * @stability experimental
+     */
+    importKey(userId: string, provider: string, plaintext: string, opts: {
+        source: string;
+    }): Promise<void>;
+    /**
+     * One view per ENABLED provider (enabled in settings and registered here),
+     * configured or not, in registry order. A key stored for a provider that is
+     * no longer enabled is not listed — it cannot be used — but is kept.
+     */
+    list(userId: string): Promise<UserAiKeyView[]>;
+    /**
+     * Verify, compute reachable models, then store — in that order, so a key the
+     * provider refuses is never stored (`400 AI_KEY_INVALID`) and a provider
+     * outage stores nothing either (its own error). Replaces any earlier key.
+     */
+    set(userId: string, provider: string, apiKey: string): Promise<UserAiKeyView>;
+    /** Delete the caller's key for `provider`. Idempotent: no key is not an error. */
+    remove(userId: string, provider: string): Promise<void>;
+    /**
+     * Probe a key. Blank `apiKey` probes the STORED key, and only that probe
+     * updates the stored row (verification, `lastErrorCode`, reachable models).
+     * Never throws for a key or provider problem — the route answers 200.
+     */
+    test(userId: string, provider: string, apiKey?: string | null): Promise<UserAiKeyTestResult>;
+    /**
+     * The caller's key for `provider`, decrypted, or null when none is stored.
+     *
+     * ⚠ PLAINTEXT. For `AiKeyResolver` and this service's own probes ONLY —
+     * never returned by a controller, never logged, never cached.
+     */
+    getDecrypted(userId: string, provider: string): Promise<string | null>;
+    /**
+     * Re-verify one stored key and refresh its reachable models. Used by the
+     * weekly `ai.keys.recheck` job.
+     *
+     * A revoked key (`AI_KEY_INVALID`) is RECORDED (`lastErrorCode`,
+     * `verifiedAt: null`), never deleted — the user decides what to do about it. A rate limit
+     * is rethrown so the job can defer; any other failure leaves the row as it
+     * was, to be retried next time.
+     */
+    recheckReachable(userId: string, provider: string): Promise<UserAiKeyRecheckOutcome>;
+    /**
+     * The cut-off below which a key's reachable list is stale for `provider`:
+     * older than AI_KEY_RECHECK_MAX_AGE_MS, OR computed before the newest model
+     * the catalog discovered for that provider — a key checked before a model
+     * existed in `ai_models` cannot list it, however recently it was checked.
+     */
+    staleCutoff(provider: string, now?: Date): Promise<Date>;
+    /**
+     * Re-check every `provider` key whose reachable list was computed before
+     * `olderThan` (or never), AI_KEY_RECHECK_BATCH_SIZE rows at a time, in id
+     * order. For the `ai.keys.recheck` job ONLY — each key is one provider
+     * round trip, which is exactly the work the queue exists to account for.
+     *
+     * A rate limit propagates (the job defers; rows already refreshed are no
+     * longer stale, so the retry resumes where this left off). AI or the
+     * provider being switched off mid-sweep propagates too — the handler treats
+     * that as a normal stop.
+     */
+    recheckStale(provider: string, olderThan: Date): Promise<UserAiKeyRecheckCounts>;
+    /**
+     * The adapter and the slot's call settings (endpoint and, #448, the other
+     * non-secret settings) for an enabled provider; throws `AI_DISABLED` /
+     * `AI_PROVIDER_DISABLED`.
+     */
+    private providerContext;
+    /**
+     * `verifyKey`, then `listModels` ∩ this provider's catalog rows (any row,
+     * enabled or not, so an admin enabling a model later needs no recheck).
+     * Never throws for a provider problem: failures come back in `error`.
+     */
+    private probe;
+    /**
+     * Write what a probe of the STORED key found. `updateMany`, scoped, so a key
+     * deleted mid-probe is simply not resurrected.
+     *
+     * Only a rejected key changes `verifiedAt`/`lastErrorCode` on failure: a rate
+     * limit or an outage says nothing about the key itself.
+     */
+    private recordProbe;
+    /** Audit a key lifecycle act. `meta` carries counts and the provider — never a key. */
+    private audit;
+}
+//# sourceMappingURL=user-ai-keys.service.d.ts.map

package/dist/ai/keys/user-ai-keys.service.d.ts.map

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