forked from EduCraft/curriculum-project-hub
feat(hub): capability connection admin API + UI (ADR-0027)
Adds the admin surface for managing org-scoped capability credentials, so operators can configure the Aliyun docmind AccessKey from the web UI instead of needing a CLI or database access. Backend: - CapabilityConnectionService: rotate/list/read/disable, mirroring FeishuApplicationConnectionService but keyed by (orgId, capabilityId) - capabilityReadiness: probeDocmindCredential validates the AccessKey by calling QueryDocParserStatus with a dummy id (400 = auth ok, 401/403 = bad) - Admin routes: GET/PUT/DELETE /api/org/:slug/capability-connections/:capId + GET list, wired into orgRoutes Frontend: - api.ts: CapabilityConnection type + capabilityConnections/rotate/disable client methods - /admin/org/:slug/capabilities page: lists known capabilities (pdf_to_md_bundle, audio_video_to_text), shows status/version/keyId, inline rotate/disable forms with AccessKey ID/Secret/Endpoint fields - Nav item '能力' added to sidebar Version bump 0.0.31 → 0.0.32.
This commit is contained in:
@@ -168,6 +168,16 @@ export interface FeishuApplicationConnection {
|
||||
updatedAt: string;
|
||||
}
|
||||
|
||||
export interface CapabilityConnection {
|
||||
id: string;
|
||||
capabilityId: string;
|
||||
status: 'DRAFT' | 'ACTIVE' | 'DISABLED';
|
||||
activeVersion: number | null;
|
||||
keyId: string | null;
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
}
|
||||
|
||||
export interface UsageTotals {
|
||||
runCount: number;
|
||||
runsWithCost: number;
|
||||
@@ -381,6 +391,21 @@ export const api = {
|
||||
disableFeishuApplication: (slug: string) =>
|
||||
del(`${orgBase(slug)}/feishu-application-connection`) as Promise<FeishuApplicationConnection>,
|
||||
|
||||
capabilityConnections: (slug: string) =>
|
||||
get(`${orgBase(slug)}/capability-connections`) as Promise<{ connections: CapabilityConnection[] }>,
|
||||
capabilityConnection: (slug: string, capabilityId: string) =>
|
||||
get(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`) as Promise<{
|
||||
connection: CapabilityConnection | null;
|
||||
}>,
|
||||
rotateCapabilityConnection: (
|
||||
slug: string,
|
||||
capabilityId: string,
|
||||
body: { accessKeyId: string; accessKeySecret: string; endpoint: string },
|
||||
) =>
|
||||
put(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`, body) as Promise<CapabilityConnection>,
|
||||
disableCapabilityConnection: (slug: string, capabilityId: string) =>
|
||||
del(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`) as Promise<CapabilityConnection>,
|
||||
|
||||
capacityPolicy: (slug: string) => get(`${orgBase(slug)}/capacity-policy`) as Promise<CapacityPolicyView>,
|
||||
setCapacityPolicy: (slug: string, body: { limits: Partial<Record<CapacityDimension, number | null>> }) =>
|
||||
put(`${orgBase(slug)}/capacity-policy`, body) as Promise<CapacityPolicyView>,
|
||||
|
||||
@@ -28,6 +28,7 @@
|
||||
{ key: 'skills', label: '技能', icon: 'roles' as const },
|
||||
{ key: 'roles', label: '角色', icon: 'roles' as const },
|
||||
{ key: 'feishu', label: '飞书', icon: 'feishu' as const },
|
||||
{ key: 'capabilities', label: '能力', icon: 'provider' as const },
|
||||
];
|
||||
|
||||
function isAdmin(org: OrgMembership): boolean {
|
||||
|
||||
@@ -0,0 +1,202 @@
|
||||
<script lang="ts">
|
||||
import { page } from '$app/state';
|
||||
import { api, type CapabilityConnection } from '$lib/api';
|
||||
import { fmtDate } from '$lib/format';
|
||||
import { Label } from 'bits-ui';
|
||||
import PageHeader from '$lib/components/PageHeader.svelte';
|
||||
import LoadingState from '$lib/components/LoadingState.svelte';
|
||||
import ErrorBanner from '$lib/components/ErrorBanner.svelte';
|
||||
import { toastError, toastSuccess } from '$lib/toast';
|
||||
|
||||
const slug = $derived(page.params.slug ?? '');
|
||||
|
||||
const KNOWN_CAPABILITIES = [
|
||||
{ id: 'pdf_to_md_bundle', label: 'PDF → Markdown', description: '将 PDF 转换为带图片的 Markdown bundle（阿里云文档智能，含公式 LaTeX 识别）' },
|
||||
{ id: 'audio_video_to_text', label: '音视频 → 文本', description: '将音频/视频转写为文本（阿里云文档智能，按秒计费）' },
|
||||
] as const;
|
||||
|
||||
let connections = $state<Map<string, CapabilityConnection>>(new Map());
|
||||
let loading = $state(true);
|
||||
let error = $state<string | null>(null);
|
||||
|
||||
let editingCap = $state<string | null>(null);
|
||||
let accessKeyId = $state('');
|
||||
let accessKeySecret = $state('');
|
||||
let endpoint = $state('docmind-api.cn-hangzhou.aliyuncs.com');
|
||||
let saving = $state(false);
|
||||
let disabling = $state<string | null>(null);
|
||||
|
||||
async function load() {
|
||||
loading = true;
|
||||
error = null;
|
||||
try {
|
||||
const res = await api.capabilityConnections(slug);
|
||||
connections = new Map(res.connections.map((c) => [c.capabilityId, c]));
|
||||
} catch (err) {
|
||||
error = err instanceof Error ? err.message : String(err);
|
||||
} finally {
|
||||
loading = false;
|
||||
}
|
||||
}
|
||||
|
||||
function startEdit(capId: string) {
|
||||
editingCap = capId;
|
||||
accessKeyId = '';
|
||||
accessKeySecret = '';
|
||||
endpoint = 'docmind-api.cn-hangzhou.aliyuncs.com';
|
||||
}
|
||||
|
||||
function cancelEdit() {
|
||||
editingCap = null;
|
||||
}
|
||||
|
||||
async function save(capId: string) {
|
||||
if (accessKeyId.trim() === '' || accessKeySecret.trim() === '' || endpoint.trim() === '') {
|
||||
toastError('AccessKey ID、AccessKey Secret、Endpoint 均为必填');
|
||||
return;
|
||||
}
|
||||
saving = true;
|
||||
try {
|
||||
const result = await api.rotateCapabilityConnection(slug, capId, {
|
||||
accessKeyId: accessKeyId.trim(),
|
||||
accessKeySecret: accessKeySecret.trim(),
|
||||
endpoint: endpoint.trim(),
|
||||
});
|
||||
connections.set(capId, result);
|
||||
connections = new Map(connections);
|
||||
editingCap = null;
|
||||
toastSuccess('能力凭据已保存');
|
||||
} catch (err) {
|
||||
toastError(err instanceof Error ? err.message : String(err));
|
||||
} finally {
|
||||
saving = false;
|
||||
}
|
||||
}
|
||||
|
||||
async function disable(capId: string) {
|
||||
if (!confirm('停用后该能力将不可用，确定停用？')) return;
|
||||
disabling = capId;
|
||||
try {
|
||||
const result = await api.disableCapabilityConnection(slug, capId);
|
||||
connections.set(capId, result);
|
||||
connections = new Map(connections);
|
||||
toastSuccess('已停用能力连接');
|
||||
} catch (err) {
|
||||
toastError(err instanceof Error ? err.message : String(err));
|
||||
} finally {
|
||||
disabling = null;
|
||||
}
|
||||
}
|
||||
|
||||
function statusBadge(status: string): string {
|
||||
if (status === 'ACTIVE') return 'saas-badge-primary';
|
||||
if (status === 'DISABLED') return 'saas-badge-error';
|
||||
return 'saas-badge-muted';
|
||||
}
|
||||
|
||||
function statusLabel(status: string): string {
|
||||
if (status === 'ACTIVE') return '已启用';
|
||||
if (status === 'DISABLED') return '已停用';
|
||||
return '草稿';
|
||||
}
|
||||
|
||||
$effect(() => {
|
||||
if (slug) load();
|
||||
});
|
||||
</script>
|
||||
|
||||
<PageHeader
|
||||
title="外部能力"
|
||||
description="管理文档/媒体转换服务的组织级凭据（ADR-0027）。凭据按组织隔离、版本化信封存储，缺失或校验失败即 fail-closed。"
|
||||
/>
|
||||
|
||||
{#if loading}
|
||||
<LoadingState />
|
||||
{:else if error}
|
||||
<ErrorBanner message={error} onretry={load} />
|
||||
{:else}
|
||||
<div class="space-y-6">
|
||||
{#each KNOWN_CAPABILITIES as cap}
|
||||
{@const conn = connections.get(cap.id)}
|
||||
<div class="saas-card-pad">
|
||||
<div class="mb-3 flex items-start justify-between gap-3">
|
||||
<div>
|
||||
<div class="flex items-center gap-2">
|
||||
<h3 class="saas-section-title">{cap.label}</h3>
|
||||
{#if conn}
|
||||
<span class={statusBadge(conn.status)}>{statusLabel(conn.status)}</span>
|
||||
{:else}
|
||||
<span class="saas-badge-muted">未配置</span>
|
||||
{/if}
|
||||
</div>
|
||||
<p class="saas-muted mt-1 text-sm">{cap.description}</p>
|
||||
<p class="mt-0.5 font-mono text-xs text-surface-500">{cap.id}</p>
|
||||
</div>
|
||||
<div class="flex items-center gap-2">
|
||||
{#if conn?.status === 'ACTIVE'}
|
||||
<button
|
||||
class="saas-btn-ghost text-sm"
|
||||
onclick={() => disable(cap.id)}
|
||||
disabled={disabling === cap.id}
|
||||
>
|
||||
{disabling === cap.id ? '停用中…' : '停用'}
|
||||
</button>
|
||||
{/if}
|
||||
<button
|
||||
class="saas-btn-primary text-sm"
|
||||
onclick={() => startEdit(cap.id)}
|
||||
disabled={editingCap === cap.id}
|
||||
>
|
||||
{conn ? '轮换凭据' : '配置凭据'}
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{#if conn}
|
||||
<dl class="space-y-1.5 text-sm text-surface-700">
|
||||
<div class="flex justify-between">
|
||||
<dt class="text-surface-500">版本</dt>
|
||||
<dd class="font-mono">{conn.activeVersion ?? '—'}</dd>
|
||||
</div>
|
||||
<div class="flex justify-between">
|
||||
<dt class="text-surface-500">密钥 ID</dt>
|
||||
<dd class="font-mono text-xs">{conn.keyId ?? '—'}</dd>
|
||||
</div>
|
||||
<div class="flex justify-between">
|
||||
<dt class="text-surface-500">更新时间</dt>
|
||||
<dd>{fmtDate(conn.updatedAt)}</dd>
|
||||
</div>
|
||||
</dl>
|
||||
{/if}
|
||||
|
||||
{#if editingCap === cap.id}
|
||||
<div class="mt-4 border-t border-surface-100 pt-4">
|
||||
<p class="saas-muted mb-3 text-sm">
|
||||
阿里云 RAM 用户的 AccessKey。密钥仅写入新版本，旧版本归档。
|
||||
</p>
|
||||
<div class="grid gap-4">
|
||||
<div>
|
||||
<Label.Root class="saas-label" for="ak-id-{cap.id}">AccessKey ID</Label.Root>
|
||||
<input id="ak-id-{cap.id}" class="saas-input font-mono text-sm" bind:value={accessKeyId} />
|
||||
</div>
|
||||
<div>
|
||||
<Label.Root class="saas-label" for="ak-secret-{cap.id}">AccessKey Secret</Label.Root>
|
||||
<input id="ak-secret-{cap.id}" class="saas-input" type="password" bind:value={accessKeySecret} />
|
||||
</div>
|
||||
<div>
|
||||
<Label.Root class="saas-label" for="endpoint-{cap.id}">Endpoint</Label.Root>
|
||||
<input id="endpoint-{cap.id}" class="saas-input font-mono text-sm" bind:value={endpoint} />
|
||||
</div>
|
||||
</div>
|
||||
<div class="mt-4 flex items-center justify-end gap-3">
|
||||
<button class="saas-btn-ghost" onclick={cancelEdit} disabled={saving}>取消</button>
|
||||
<button class="saas-btn-primary" onclick={() => save(cap.id)} disabled={saving}>
|
||||
{saving ? '保存中…' : '保存'}
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
{/if}
|
||||
</div>
|
||||
{/each}
|
||||
</div>
|
||||
{/if}
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@paradigm/hub",
|
||||
"version": "0.0.31",
|
||||
"version": "0.0.32",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"engines": {
|
||||
|
||||
@@ -0,0 +1,131 @@
|
||||
/**
|
||||
* ADR-0027: Admin routes for organization-scoped capability connections.
|
||||
* GET /api/org/:orgSlug/capability-connections — list all
|
||||
* GET /api/org/:orgSlug/capability-connections/:capId — read one
|
||||
* PUT /api/org/:orgSlug/capability-connections/:capId — rotate/create
|
||||
* DELETE /api/org/:orgSlug/capability-connections/:capId — disable
|
||||
*/
|
||||
import type { PrismaClient } from "@prisma/client";
|
||||
import type { FastifyInstance } from "fastify";
|
||||
import { CapabilityConnectionService } from "../../capability/capabilityConnectionService.js";
|
||||
import { CapabilityReadinessError, type CapabilityReadinessProbe } from "../../capability/capabilityReadiness.js";
|
||||
import type { LocalSecretEnvelope } from "../../security/secretEnvelope.js";
|
||||
import { requireOrgRole, type GuardDeps } from "../auth/guards.js";
|
||||
import { handleRouteError } from "../errors.js";
|
||||
|
||||
export interface CapabilityConnectionRouteConfig {
|
||||
readonly prisma: PrismaClient;
|
||||
readonly sessionSecret: string;
|
||||
readonly secretEnvelope: LocalSecretEnvelope;
|
||||
readonly readinessProbe?: CapabilityReadinessProbe;
|
||||
}
|
||||
|
||||
export async function registerCapabilityConnectionRoutes(
|
||||
app: FastifyInstance,
|
||||
config: CapabilityConnectionRouteConfig,
|
||||
): Promise<void> {
|
||||
const guardDeps: GuardDeps = { prisma: config.prisma, sessionSecret: config.sessionSecret };
|
||||
const connections = new CapabilityConnectionService(
|
||||
config.prisma,
|
||||
config.secretEnvelope,
|
||||
config.readinessProbe,
|
||||
);
|
||||
|
||||
app.get("/api/org/:orgSlug/capability-connections", async (request, reply) => {
|
||||
try {
|
||||
const { orgSlug } = request.params as { orgSlug: string };
|
||||
const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
|
||||
if (auth === null) return;
|
||||
return { connections: await connections.list(auth.organization.id) };
|
||||
} catch (error) {
|
||||
request.log.error({ requestId: request.id, operation: "capability_connection.list" }, "list failed");
|
||||
return handleRouteError(reply, error);
|
||||
}
|
||||
});
|
||||
|
||||
app.get("/api/org/:orgSlug/capability-connections/:capabilityId", async (request, reply) => {
|
||||
try {
|
||||
const { orgSlug, capabilityId } = request.params as { orgSlug: string; capabilityId: string };
|
||||
const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
|
||||
if (auth === null) return;
|
||||
return { connection: await connections.read(auth.organization.id, capabilityId) };
|
||||
} catch (error) {
|
||||
request.log.error({ requestId: request.id, operation: "capability_connection.read" }, "read failed");
|
||||
return handleRouteError(reply, error);
|
||||
}
|
||||
});
|
||||
|
||||
app.put("/api/org/:orgSlug/capability-connections/:capabilityId", async (request, reply) => {
|
||||
try {
|
||||
const { orgSlug, capabilityId } = request.params as { orgSlug: string; capabilityId: string };
|
||||
const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
|
||||
if (auth === null) return;
|
||||
const body = parseBody(request.body);
|
||||
const result = await connections.rotate({
|
||||
organizationId: auth.organization.id,
|
||||
capabilityId,
|
||||
actorUserId: auth.user.id,
|
||||
...body,
|
||||
});
|
||||
request.log.info({
|
||||
organizationId: auth.organization.id,
|
||||
capabilityId,
|
||||
connectionId: result.id,
|
||||
status: result.status,
|
||||
secretVersion: result.activeVersion,
|
||||
}, result.created ? "Capability Connection created" : "Capability Connection rotated");
|
||||
const { created, ...metadata } = result;
|
||||
return reply.status(created ? 201 : 200).send(metadata);
|
||||
} catch (error) {
|
||||
const facts = error instanceof CapabilityReadinessError
|
||||
? {
|
||||
errorCode: error.code,
|
||||
failureCategory: error.category,
|
||||
...(error.upstreamStatus !== undefined ? { upstreamStatus: error.upstreamStatus } : {}),
|
||||
}
|
||||
: { errorCode: "capability_connection_write_failed" };
|
||||
request.log.error({ requestId: request.id, operation: "capability_connection.rotate", ...facts }, "rotate failed");
|
||||
return handleRouteError(reply, error);
|
||||
}
|
||||
});
|
||||
|
||||
app.delete("/api/org/:orgSlug/capability-connections/:capabilityId", async (request, reply) => {
|
||||
try {
|
||||
const { orgSlug, capabilityId } = request.params as { orgSlug: string; capabilityId: string };
|
||||
const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
|
||||
if (auth === null) return;
|
||||
const result = await connections.disable({
|
||||
organizationId: auth.organization.id,
|
||||
capabilityId,
|
||||
actorUserId: auth.user.id,
|
||||
});
|
||||
request.log.info({
|
||||
organizationId: auth.organization.id,
|
||||
capabilityId,
|
||||
connectionId: result.id,
|
||||
status: result.status,
|
||||
}, "Capability Connection disabled");
|
||||
return reply.send(result);
|
||||
} catch (error) {
|
||||
request.log.error({ requestId: request.id, operation: "capability_connection.disable" }, "disable failed");
|
||||
return handleRouteError(reply, error);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
function parseBody(value: unknown): { readonly accessKeyId: string; readonly accessKeySecret: string; readonly endpoint: string } {
|
||||
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
||||
throw new Error("invalid capability credential body");
|
||||
}
|
||||
const body = value as Record<string, unknown>;
|
||||
for (const name of ["accessKeyId", "accessKeySecret", "endpoint"] as const) {
|
||||
if (typeof body[name] !== "string" || (body[name] as string).trim() === "") {
|
||||
throw new Error(`${name} is required`);
|
||||
}
|
||||
}
|
||||
return {
|
||||
accessKeyId: body["accessKeyId"] as string,
|
||||
accessKeySecret: body["accessKeySecret"] as string,
|
||||
endpoint: body["endpoint"] as string,
|
||||
};
|
||||
}
|
||||
@@ -22,6 +22,8 @@ import type { LocalSecretEnvelope } from "../../security/secretEnvelope.js";
|
||||
import type { ProviderReadinessProbe } from "../../connections/providerReadiness.js";
|
||||
import type { FeishuReadinessProbe } from "../../connections/feishuReadiness.js";
|
||||
import { registerFeishuApplicationConnectionRoutes } from "./feishuApplicationConnectionRoutes.js";
|
||||
import { registerCapabilityConnectionRoutes } from "./capabilityConnectionRoutes.js";
|
||||
import type { CapabilityReadinessProbe } from "../../capability/capabilityReadiness.js";
|
||||
|
||||
export interface OrgRouteConfig {
|
||||
readonly prisma: PrismaClient;
|
||||
@@ -30,6 +32,7 @@ export interface OrgRouteConfig {
|
||||
readonly secretEnvelope: LocalSecretEnvelope;
|
||||
readonly providerReadinessProbe?: ProviderReadinessProbe;
|
||||
readonly feishuConnectionReadinessProbe?: FeishuReadinessProbe;
|
||||
readonly capabilityReadinessProbe?: CapabilityReadinessProbe;
|
||||
}
|
||||
|
||||
export async function registerOrgRoutes(app: FastifyInstance, config: OrgRouteConfig): Promise<void> {
|
||||
@@ -138,4 +141,12 @@ export async function registerOrgRoutes(app: FastifyInstance, config: OrgRouteCo
|
||||
? { readinessProbe: config.feishuConnectionReadinessProbe }
|
||||
: {}),
|
||||
});
|
||||
await registerCapabilityConnectionRoutes(app, {
|
||||
prisma: config.prisma,
|
||||
sessionSecret: config.sessionSecret,
|
||||
secretEnvelope: config.secretEnvelope,
|
||||
...(config.capabilityReadinessProbe !== undefined
|
||||
? { readinessProbe: config.capabilityReadinessProbe }
|
||||
: {}),
|
||||
});
|
||||
}
|
||||
|
||||
@@ -0,0 +1,266 @@
|
||||
/**
|
||||
* ADR-0027: Organization-scoped capability connection service. Manages the
|
||||
* lifecycle (rotate / read / disable) of capability credentials stored in
|
||||
* ADR-0024 encrypted envelopes with purpose="capability".
|
||||
*
|
||||
* Mirrors FeishuApplicationConnectionService, but keyed by (organizationId,
|
||||
* capabilityId) instead of 1:1 — an org may have multiple capabilities.
|
||||
*/
|
||||
import { randomUUID } from "node:crypto";
|
||||
import type { Prisma, PrismaClient } from "@prisma/client";
|
||||
import { lockActiveOrganization } from "../org/status.js";
|
||||
import { LocalSecretEnvelope } from "../security/secretEnvelope.js";
|
||||
import { probeDocmindCredential, type CapabilityReadinessProbe } from "./capabilityReadiness.js";
|
||||
import type { CapabilitySecretPayload } from "./types.js";
|
||||
|
||||
const CAPABILITY_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
|
||||
const KNOWN_CAPABILITY_IDS = new Set(["pdf_to_md_bundle", "audio_video_to_text"]);
|
||||
|
||||
export interface CapabilityCredentialInput {
|
||||
readonly accessKeyId: string;
|
||||
readonly accessKeySecret: string;
|
||||
readonly endpoint: string;
|
||||
}
|
||||
|
||||
export interface RotateCapabilityInput extends CapabilityCredentialInput {
|
||||
readonly organizationId: string;
|
||||
readonly capabilityId: string;
|
||||
readonly actorUserId: string;
|
||||
}
|
||||
|
||||
export interface CapabilityConnectionMetadata {
|
||||
readonly id: string;
|
||||
readonly capabilityId: string;
|
||||
readonly status: "DRAFT" | "ACTIVE" | "DISABLED";
|
||||
readonly activeVersion: number | null;
|
||||
readonly keyId: string | null;
|
||||
readonly createdAt: Date;
|
||||
readonly updatedAt: Date;
|
||||
}
|
||||
|
||||
export interface CapabilityConnectionWriteResult extends CapabilityConnectionMetadata {
|
||||
readonly created: boolean;
|
||||
}
|
||||
|
||||
export type CapabilitySecretPayloadV1 = CapabilitySecretPayload;
|
||||
|
||||
export class CapabilityConnectionService {
|
||||
constructor(
|
||||
private readonly prisma: PrismaClient,
|
||||
private readonly secrets: LocalSecretEnvelope,
|
||||
private readonly readinessProbe: CapabilityReadinessProbe = probeDocmindCredential,
|
||||
) {}
|
||||
|
||||
async rotate(input: RotateCapabilityInput): Promise<CapabilityConnectionWriteResult> {
|
||||
if (!CAPABILITY_ID_PATTERN.test(input.capabilityId)) {
|
||||
throw new Error(`invalid capabilityId: ${input.capabilityId}`);
|
||||
}
|
||||
const payload = validateCredential(input);
|
||||
await this.prisma.$transaction(async (tx) => {
|
||||
await requireCapabilityAdmin(tx, input);
|
||||
});
|
||||
await this.readinessProbe({
|
||||
endpoint: payload.endpoint,
|
||||
accessKeyId: payload.accessKeyId,
|
||||
accessKeySecret: payload.accessKeySecret,
|
||||
});
|
||||
|
||||
return this.prisma.$transaction(async (tx) => {
|
||||
await requireCapabilityAdmin(tx, input);
|
||||
const connection = await tx.organizationCapabilityConnection.upsert({
|
||||
where: {
|
||||
organizationId_capabilityId: {
|
||||
organizationId: input.organizationId,
|
||||
capabilityId: input.capabilityId,
|
||||
},
|
||||
},
|
||||
update: {},
|
||||
create: {
|
||||
id: randomUUID(),
|
||||
organizationId: input.organizationId,
|
||||
capabilityId: input.capabilityId,
|
||||
status: "DRAFT",
|
||||
},
|
||||
});
|
||||
await tx.$queryRaw`SELECT "id" FROM "OrganizationCapabilityConnection" WHERE "id" = ${connection.id} FOR UPDATE`;
|
||||
const locked = await tx.organizationCapabilityConnection.findUniqueOrThrow({
|
||||
where: { id: connection.id },
|
||||
include: {
|
||||
activeSecretVersion: true,
|
||||
secretVersions: { orderBy: { version: "desc" }, take: 1, select: { version: true } },
|
||||
},
|
||||
});
|
||||
if (locked.organizationId !== input.organizationId) {
|
||||
throw new Error("Capability Connection scope changed during rotation");
|
||||
}
|
||||
const version = (locked.secretVersions[0]?.version ?? 0) + 1;
|
||||
const secretVersionId = randomUUID();
|
||||
const envelope = this.secrets.encryptJson(
|
||||
{
|
||||
purpose: "capability",
|
||||
organizationId: input.organizationId,
|
||||
connectionId: locked.id,
|
||||
secretVersionId,
|
||||
},
|
||||
payload,
|
||||
);
|
||||
const now = new Date();
|
||||
const secretVersion = await tx.capabilityCredentialVersion.create({
|
||||
data: {
|
||||
id: secretVersionId,
|
||||
connectionId: locked.id,
|
||||
version,
|
||||
envelopeVersion: envelope.version,
|
||||
keyId: envelope.keyId,
|
||||
envelope: envelope as unknown as Prisma.InputJsonValue,
|
||||
createdByUserId: input.actorUserId,
|
||||
},
|
||||
});
|
||||
if (locked.activeSecretVersion !== null) {
|
||||
await tx.capabilityCredentialVersion.update({
|
||||
where: { id: locked.activeSecretVersion.id },
|
||||
data: { retiredAt: now },
|
||||
});
|
||||
}
|
||||
const activated = await tx.organizationCapabilityConnection.update({
|
||||
where: { id: locked.id },
|
||||
data: {
|
||||
status: "ACTIVE",
|
||||
activeSecretVersionId: secretVersion.id,
|
||||
activatedAt: now,
|
||||
disabledAt: null,
|
||||
},
|
||||
});
|
||||
await tx.auditEntry.create({
|
||||
data: {
|
||||
organizationId: input.organizationId,
|
||||
actorUserId: input.actorUserId,
|
||||
action: version === 1 ? "capability.created" : "capability.rotated",
|
||||
metadata: {
|
||||
connectionId: locked.id,
|
||||
capabilityId: input.capabilityId,
|
||||
status: "ACTIVE",
|
||||
secretVersion: version,
|
||||
keyId: envelope.keyId,
|
||||
},
|
||||
},
|
||||
});
|
||||
return {
|
||||
...toMetadata(activated, { version, keyId: secretVersion.keyId }),
|
||||
created: version === 1,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
async list(organizationId: string): Promise<CapabilityConnectionMetadata[]> {
|
||||
const connections = await this.prisma.organizationCapabilityConnection.findMany({
|
||||
where: { organizationId },
|
||||
include: { activeSecretVersion: { select: { version: true, keyId: true } } },
|
||||
orderBy: { capabilityId: "asc" },
|
||||
});
|
||||
return connections.map((c) => toMetadata(c, c.activeSecretVersion));
|
||||
}
|
||||
|
||||
async read(organizationId: string, capabilityId: string): Promise<CapabilityConnectionMetadata | null> {
|
||||
const connection = await this.prisma.organizationCapabilityConnection.findFirst({
|
||||
where: { organizationId, capabilityId },
|
||||
include: { activeSecretVersion: { select: { version: true, keyId: true } } },
|
||||
});
|
||||
return connection === null ? null : toMetadata(connection, connection.activeSecretVersion);
|
||||
}
|
||||
|
||||
async disable(input: {
|
||||
readonly organizationId: string;
|
||||
readonly capabilityId: string;
|
||||
readonly actorUserId: string;
|
||||
}): Promise<CapabilityConnectionMetadata> {
|
||||
return this.prisma.$transaction(async (tx) => {
|
||||
await requireCapabilityAdmin(tx, input);
|
||||
const connection = await tx.organizationCapabilityConnection.findFirst({
|
||||
where: { organizationId: input.organizationId, capabilityId: input.capabilityId },
|
||||
select: { id: true },
|
||||
});
|
||||
if (connection === null) throw new Error("Capability Connection not found");
|
||||
await tx.$queryRaw`SELECT "id" FROM "OrganizationCapabilityConnection" WHERE "id" = ${connection.id} FOR UPDATE`;
|
||||
const locked = await tx.organizationCapabilityConnection.findUniqueOrThrow({
|
||||
where: { id: connection.id },
|
||||
include: { activeSecretVersion: { select: { version: true, keyId: true } } },
|
||||
});
|
||||
if (locked.status === "DISABLED") return toMetadata(locked, locked.activeSecretVersion);
|
||||
const disabled = await tx.organizationCapabilityConnection.update({
|
||||
where: { id: locked.id },
|
||||
data: { status: "DISABLED", disabledAt: new Date() },
|
||||
});
|
||||
await tx.auditEntry.create({
|
||||
data: {
|
||||
organizationId: input.organizationId,
|
||||
actorUserId: input.actorUserId,
|
||||
action: "capability.disabled",
|
||||
metadata: {
|
||||
connectionId: locked.id,
|
||||
capabilityId: input.capabilityId,
|
||||
previousStatus: locked.status,
|
||||
status: "DISABLED",
|
||||
},
|
||||
},
|
||||
});
|
||||
return toMetadata(disabled, locked.activeSecretVersion);
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
function validateCredential(input: RotateCapabilityInput): CapabilitySecretPayloadV1 {
|
||||
if (!KNOWN_CAPABILITY_IDS.has(input.capabilityId)) {
|
||||
throw new Error(`unsupported capabilityId: ${input.capabilityId}`);
|
||||
}
|
||||
const accessKeyId = nonEmpty(input.accessKeyId, "accessKeyId");
|
||||
const accessKeySecret = nonEmpty(input.accessKeySecret, "accessKeySecret");
|
||||
const endpoint = nonEmpty(input.endpoint, "endpoint");
|
||||
return { schemaVersion: 1, accessKeyId, accessKeySecret, endpoint };
|
||||
}
|
||||
|
||||
function toMetadata(
|
||||
connection: {
|
||||
readonly id: string;
|
||||
readonly capabilityId: string;
|
||||
readonly status: string;
|
||||
readonly createdAt: Date;
|
||||
readonly updatedAt: Date;
|
||||
},
|
||||
secret: { readonly version: number; readonly keyId: string } | null,
|
||||
): CapabilityConnectionMetadata {
|
||||
return {
|
||||
id: connection.id,
|
||||
capabilityId: connection.capabilityId,
|
||||
status: connection.status as CapabilityConnectionMetadata["status"],
|
||||
activeVersion: secret?.version ?? null,
|
||||
keyId: secret?.keyId ?? null,
|
||||
createdAt: connection.createdAt,
|
||||
updatedAt: connection.updatedAt,
|
||||
};
|
||||
}
|
||||
|
||||
async function requireCapabilityAdmin(
|
||||
tx: Prisma.TransactionClient,
|
||||
input: { readonly organizationId: string; readonly actorUserId: string },
|
||||
): Promise<void> {
|
||||
await lockActiveOrganization(tx, input.organizationId);
|
||||
const membership = await tx.organizationMembership.findFirst({
|
||||
where: {
|
||||
organizationId: input.organizationId,
|
||||
userId: input.actorUserId,
|
||||
role: { in: ["OWNER", "ADMIN"] },
|
||||
revokedAt: null,
|
||||
},
|
||||
select: { id: true },
|
||||
});
|
||||
if (membership === null) {
|
||||
throw new Error("only Organization OWNER or ADMIN may manage capability connections");
|
||||
}
|
||||
}
|
||||
|
||||
function nonEmpty(value: string, label: string): string {
|
||||
const trimmed = value.trim();
|
||||
if (trimmed === "") throw new Error(`${label} must not be empty`);
|
||||
return trimmed;
|
||||
}
|
||||
@@ -0,0 +1,69 @@
|
||||
/**
|
||||
* ADR-0027: Capability readiness probe. Validates the Alibaba Cloud docmind
|
||||
* credential by calling QueryDocParserStatus with a dummy id — a 400 (bad
|
||||
* request) means the credential is valid (the API accepted auth but rejected
|
||||
* the id); a 401/403 means the credential is bad.
|
||||
*/
|
||||
import { classifyNetworkFailure, type NetworkFailureCategory } from "../connections/networkFailure.js";
|
||||
|
||||
export interface CapabilityReadinessInput {
|
||||
readonly endpoint: string;
|
||||
readonly accessKeyId: string;
|
||||
readonly accessKeySecret: string;
|
||||
}
|
||||
|
||||
export type CapabilityReadinessProbe = (input: CapabilityReadinessInput) => Promise<void>;
|
||||
|
||||
export class CapabilityReadinessError extends Error {
|
||||
constructor(
|
||||
readonly code: "capability_readiness_unsupported" | "capability_readiness_unreachable" | "capability_readiness_rejected",
|
||||
message: string,
|
||||
readonly category: NetworkFailureCategory | "configuration" | "http",
|
||||
readonly upstreamStatus?: number,
|
||||
) {
|
||||
super(message);
|
||||
this.name = "CapabilityReadinessError";
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Probe the Alibaba Cloud docmind credential. We call QueryDocParserStatus
|
||||
* with a dummy id. The API will return:
|
||||
* - 400 (InvalidParameter) → credential valid, just a bad id → probe passes
|
||||
* - 401/403 (InvalidAccessKey/Forbidden) → credential invalid → probe fails
|
||||
* - network error → unreachable
|
||||
*/
|
||||
export const probeDocmindCredential: CapabilityReadinessProbe = async (input) => {
|
||||
const url = `https://${input.endpoint}/?Action=QueryDocParserStatus&Id=probe-test&Version=2022-07-11`;
|
||||
const authHeader = makeBasicAuth(input.accessKeyId, input.accessKeySecret);
|
||||
|
||||
let response: Response;
|
||||
try {
|
||||
response = await fetch(url, {
|
||||
method: "GET",
|
||||
headers: { authorization: authHeader, accept: "application/json" },
|
||||
redirect: "manual",
|
||||
signal: AbortSignal.timeout(10_000),
|
||||
});
|
||||
} catch (error) {
|
||||
throw new CapabilityReadinessError(
|
||||
"capability_readiness_unreachable",
|
||||
"docmind credential readiness check could not reach the API",
|
||||
classifyNetworkFailure(error),
|
||||
);
|
||||
}
|
||||
await response.body?.cancel();
|
||||
if (response.status === 401 || response.status === 403) {
|
||||
throw new CapabilityReadinessError(
|
||||
"capability_readiness_rejected",
|
||||
`docmind credential rejected: status ${response.status}`,
|
||||
"http",
|
||||
response.status,
|
||||
);
|
||||
}
|
||||
};
|
||||
|
||||
function makeBasicAuth(accessKeyId: string, accessKeySecret: string): string {
|
||||
const credentials = Buffer.from(`${accessKeyId}:${accessKeySecret}`).toString("base64");
|
||||
return `Basic ${credentials}`;
|
||||
}
|
||||
Reference in New Issue
Block a user