Installable Plugins & Capability Packs

LAYER 1  REGISTRIES        mcp.registries (org-scoped + global default seed)
   │  Inngest sync (cursor + updated_since)  ┊  on-demand refresh
LAYER 2  CATALOG (cached)   mcp.catalog_servers  (icons, repo, packages, remotes, readme_html, categories)
   │  org admin installs / denies
LAYER 3  ORG GOVERNANCE     plugin.org_listings (allow-list + custom, enabled=false default)
   │                        plugin.org_denylist
   │  workspace enables (allow-list only)
LAYER 4  WORKSPACE INSTALL  agent.mcp_servers (existing table, repurposed) + health
   │  holds auth per (org_listing × workspace)
LAYER 5  RUNTIME + AUTH     mcp.credentials (encrypted) → materializeTools → agent toolchain
                            refresh-watcher → needs_reauth → notifications + email

interface PluginType {
  type: "mcp_server" | "integration" | "content_tool";
  syncCatalog(registry, ctx): Promise<CatalogUpsert[]>;   // registry-backed types only
  authKind(listing): "oauth" | "secret" | "none";
  startInstall(listing, ctx): Promise<InstallResult>;     // validation + auth bootstrap
  contributeTools(installed, ctx): Promise<AISdkToolMap>; // called by materializeTools
}

## Document — `2026-06-12-oxagen-plugins-capability-packs.md`

## Oxagen Plugins — first-party capability packs (Phase 1)

Status: Phase 1 implemented (this branch) · Author: Claude (planner) + Mac Anderson · Date: 2026-06-12
Related: ADR-013, `docs/architecture/installable-plugins/specs/2026-06-06-installable-plugins-mcp-design.md`

### What an Oxagen Plugin is

An **Oxagen Plugin** is a first-party *capability pack*: a named, versioned bundle of
existing capability contracts that an org installs from the marketplace instead of
having always-on. Examples: `oxagen/media-video` (premium), `oxagen/media-svg` (free).
Capabilities not claimed by any plugin remain **builtin** — always available, no
install required. Phase 1 makes the four media/document-generation families
installable; everything else stays builtin.

Three phases:

- **Phase 1 (this branch):** manifest + static registry, `capability` plugin type,
  kernel entitlement gate, agent tool-list filter, marketplace browse/install/enable,
  typed `capability_not_installed` error, docs, tests.
- **Phase 2 (Linear):** monetization — plan-tier install gates, premium meter rates in
  `pricing.ts`, preview-allowlist visibility, workspace-level enable/disable,
  low-balance UX integration.
- **Phase 3 (Linear):** partner plugins — Postgres-mirrored manifest catalog,
  out-of-process execution protocol (context envelope + scoped graph tokens),
  manifest review flow, rev-share settlement on ClickHouse telemetry.

### Architecture invariants (binding)

1. **The kernel is the enforcement point.** Entitlement is checked in
   `kernel.invoke()` (packages/oxagen/src/kernel.ts), beside the billing gate, so
   API, MCP, agent, and CLI surfaces inherit it identically. Tool-list filtering in
   `materializeTools()` is UX, not security.
2. **One install model.** Capability packs reuse `plugin.org_listings`
   (plugin_type `capability`, source `oxagen`) and the existing
   install / set_enabled / uninstall / denylist contracts. No parallel tables.
3. **Manifests are pure data.** The manifest zod schema is DB-mirrorable by design —
   Phase 3 syncs partner manifests into Postgres; first-party manifests stay in-repo
   as the source of truth.
4. **Uninstall blocks new invocations only.** Running async jobs complete; generated
   assets persist (they are customer data, served via the assets route).
5. **Unclaimed contracts are builtin.** A contract may be claimed by at most one
   plugin (registry validation enforces this).

### Directory scaffold

One directory per plugin: Phase 2/3 add per-plugin assets (icon, pricing, docs,
partner handler bindings) without restructuring.

#### Manifest schema

```ts
{
  id: `oxagen/${slug}`,            // unique, stable
  name: string,                    // display name, e.g. "Video Generation"
  description: string,
  version: string,                 // semver; first-party is always-latest, recorded for the DB mirror
  tier: "free" | "premium",        // builtin packs do not exist — builtin = unclaimed
  visibility: "hidden" | "preview" | "beta" | "ga",
  category: string,                // marketplace grouping, e.g. "media"
  icon?: string,                   // lucide icon name
  contracts: [string, ...],        // capability names claimed by this pack
  minPlanTier?: "free"|"build"|"scale"|"enterprise",  // recorded now, ENFORCED in Phase 2
  scopes: string[],                // reserved for Phase 3 partner protocol; [] for first-party
}

{
  "name": "@oxagen/plugins",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": "./src/index.ts",
    "./credentials": "./src/credentials/credential-service.ts"
  },
  "scripts": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint src --max-warnings 0",
    "test:unit": "vitest run",
    "test:coverage": "vitest run --coverage"
  },
  "dependencies": {
    "@oxagen/config": "workspace:*",
    "@oxagen/crypto": "workspace:*",
    "zod": "3.25.76"
  },
  "devDependencies": {
    "@types/node": "25.9.1",
    "typescript": "6.0.3",
    "@vitest/coverage-v8": "2.1.9",
    "vitest": "2.1.9"
  }
}

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    environment: "node",
    include: ["src/**/*.test.ts"],
  },
});

// @oxagen/plugins — installable-plugin spine.
// Plan 1 ships the credential service; the PluginType spine lands in Plan 3.
export {
  encryptCredentialSecrets,
  decryptCredentialSecrets,
  MCP_CREDENTIAL_KEY_ID,
} from "./credentials/credential-service";
export type {
  CredentialPlaintext,
  CredentialCiphertext,
} from "./credentials/credential-service";

git add packages/plugins/package.json packages/plugins/tsconfig.json packages/plugins/vitest.config.ts packages/plugins/src/index.ts pnpm-lock.yaml
git commit -m "chore(plugins): scaffold @oxagen/plugins package"

export const mcpSchema = pgSchema("mcp");
export const pluginSchema = pgSchema("plugin");
export const notificationSchema = pgSchema("notification");

git add packages/database/src/schema/_schemas.ts
git commit -m "feat(db): add mcp, plugin, notification schema namespaces"

import { sql } from "drizzle-orm";
import {
  boolean,
  index,
  jsonb,
  text,
  timestamp,
  uniqueIndex,
  uuid,
} from "drizzle-orm/pg-core";
import { mcpSchema } from "./_schemas";
import { auditMixin, bytea, idMixin, orgScopeMixin } from "./_mixins";

/**
 * mcp.registries — registry sources an org can sync from. A row with a NULL
 * org_id is a global default seed visible to every org (the official MCP
 * registry is seeded this way in migration 0007).
 */
export const mcpRegistries = mcpSchema.table(
  "registries",
  {
    ...idMixin("mreg"),
    ...auditMixin(),
    orgId: uuid("org_id"), // NULL ⇒ global default seed
    name: text("name").notNull(),
    baseUrl: text("base_url").notNull(),
    enabled: boolean("enabled").notNull().default(true),
    isDefaultSeed: boolean("is_default_seed").notNull().default(false),
    lastSyncedAt: timestamp("last_synced_at", { withTimezone: true, mode: "date" }),
    lastSyncedCursor: text("last_synced_cursor"),
  },
  (t) => ({
    orgIdx: index("registries_org_idx").on(t.orgId),
  }),
);

/**
 * mcp.catalog_servers — cached registry records. One row per
 * (registry_id, name, version); is_latest is maintained on upsert.
 * Heterogeneous registry payloads (repository/icons/packages/remotes/meta)
 * are stored as JSONB; transport_types/categories are denormalized arrays for
 * cheap filtering.
 */
export const mcpCatalogServers = mcpSchema.table(
  "catalog_servers",
  {
    ...idMixin("mcat"),
    ...auditMixin(),
    registryId: uuid("registry_id").notNull(),
    name: text("name").notNull(),
    version: text("version").notNull(),
    isLatest: boolean("is_latest").notNull().default(false),
    title: text("title"),
    description: text("description").notNull(),
    repository: jsonb("repository"),
    websiteUrl: text("website_url"),
    icons: jsonb("icons").notNull().default(sql`'[]'::jsonb`),
    packages: jsonb("packages").notNull().default(sql`'[]'::jsonb`),
    remotes: jsonb("remotes").notNull().default(sql`'[]'::jsonb`),
    transportTypes: text("transport_types").array().notNull().default(sql`'{}'::text[]`),
    authKind: text("auth_kind").notNull(),
    categories: text("categories").array().notNull().default(sql`'{}'::text[]`),
    readmeHtml: text("readme_html"),
    readmeFetchedAt: timestamp("readme_fetched_at", { withTimezone: true, mode: "date" }),
    status: text("status").notNull(),
    publishedAt: timestamp("published_at", { withTimezone: true, mode: "date" }),
    upstreamUpdatedAt: timestamp("upstream_updated_at", { withTimezone: true, mode: "date" }),
    statusChangedAt: timestamp("status_changed_at", { withTimezone: true, mode: "date" }),
    meta: jsonb("meta").notNull().default(sql`'{}'::jsonb`),
  },
  (t) => ({
    uniqueVersion: uniqueIndex("catalog_servers_name_version_uniq").on(
      t.registryId,
      t.name,
      t.version,
    ),
    registryNameIdx: index("catalog_servers_registry_name_idx").on(t.registryId, t.name),
  }),
);

/**
 * mcp.credentials — SOC2-encrypted auth per (org_listing × workspace).
 * Token columns are envelope-encrypted bytea (AES-256-GCM); the service layer
 * (@oxagen/plugins/credentials) is responsible for encrypt/decrypt. Org-level
 * shared credentials use the ORG_ONLY_WS sentinel workspace id.
 */
export const mcpCredentials = mcpSchema.table(
  "credentials",
  {
    ...idMixin("mcrd"),
    ...auditMixin(),
    ...orgScopeMixin(),
    orgListingId: uuid("org_listing_id").notNull(),
    authKind: text("auth_kind").notNull(), // oauth | secret
    accessTokenEnc: bytea("access_token_enc"),
    refreshTokenEnc: bytea("refresh_token_enc"),
    secretEnc: bytea("secret_enc"),
    oauthClientSecretEnc: bytea("oauth_client_secret_enc"),
    tokenKmsKeyId: text("token_kms_key_id"),
    oauthClientId: text("oauth_client_id"),
    scopes: text("scopes").array().notNull().default(sql`'{}'::text[]`),
    expiresAt: timestamp("expires_at", { withTimezone: true, mode: "date" }),
    status: text("status").notNull().default("active"), // active | needs_reauth | revoked
    lastRefreshedAt: timestamp("last_refreshed_at", { withTimezone: true, mode: "date" }),
  },
  (t) => ({
    uniqueListingWs: uniqueIndex("credentials_workspace_listing_uniq").on(
      t.workspaceId,
      t.orgListingId,
    ),
    orgIdx: index("credentials_org_idx").on(t.orgId),
  }),
);

git add packages/database/src/schema/mcp.ts
git commit -m "feat(db): mcp registries, catalog_servers, credentials tables"

import { sql } from "drizzle-orm";
import {
  boolean,
  index,
  jsonb,
  text,
  uniqueIndex,
  uuid,
} from "drizzle-orm/pg-core";
import { pluginSchema } from "./_schemas";
import { auditMixin, idMixin, softDeleteMixin } from "./_mixins";

/**
 * plugin.org_listings — the org allow-list. Polymorphic across plugin types
 * (mcp_server | integration | content_tool). A row with catalog_server_id set
 * came from a registry; NULL means a custom admin-added plugin. Newly added
 * listings are disabled by default but available to all child workspaces.
 */
export const pluginOrgListings = pluginSchema.table(
  "org_listings",
  {
    ...idMixin("porg"),
    ...auditMixin(),
    ...softDeleteMixin(),
    orgId: uuid("org_id").notNull(),
    pluginType: text("plugin_type").notNull(), // mcp_server | integration | content_tool
    catalogServerId: uuid("catalog_server_id"), // NULL ⇒ custom
    source: text("source").notNull(), // registry | custom
    name: text("name").notNull(),
    title: text("title"),
    description: text("description"),
    iconUrl: text("icon_url"),
    endpointUrl: text("endpoint_url"),
    transport: text("transport"),
    authKind: text("auth_kind").notNull(), // oauth | secret | none
    authConfig: jsonb("auth_config").notNull().default(sql`'{}'::jsonb`),
    enabled: boolean("enabled").notNull().default(false),
    config: jsonb("config").notNull().default(sql`'{}'::jsonb`),
  },
  (t) => ({
    uniqueName: uniqueIndex("org_listings_org_type_name_uniq").on(
      t.orgId,
      t.pluginType,
      t.name,
    ),
    orgTypeIdx: index("org_listings_org_type_idx").on(t.orgId, t.pluginType),
  }),
);

/**
 * plugin.org_denylist — servers an org admin has blocked. A denylisted name is
 * non-installable; the marketplace still shows it with a disabled/denied
 * treatment. Adding a denylist row disables any existing listing/install for
 * that name (enforced in the handler, Plan 3).
 */
export const pluginOrgDenylist = pluginSchema.table(
  "org_denylist",
  {
    ...idMixin("pden"),
    ...auditMixin(),
    orgId: uuid("org_id").notNull(),
    pluginType: text("plugin_type").notNull(),
    serverName: text("server_name").notNull(),
    reason: text("reason"),
  },
  (t) => ({
    uniqueName: uniqueIndex("org_denylist_org_type_name_uniq").on(
      t.orgId,
      t.pluginType,
      t.serverName,
    ),
  }),
);

git add packages/database/src/schema/plugin.ts
git commit -m "feat(db): plugin org_listings + org_denylist tables"

import {
  boolean,
  index,
  text,
  timestamp,
  uuid,
} from "drizzle-orm/pg-core";
import { notificationSchema } from "./_schemas";
import { auditMixin, idMixin } from "./_mixins";

/**
 * notification.notifications — in-app notification feed (also mirrored to email
 * for certain kinds). The MCP re-auth flow (Plan 5) is the first producer; the
 * table is generic so approval/run/security kinds can reuse it.
 */
export const notifications = notificationSchema.table(
  "notifications",
  {
    ...idMixin("ntf"),
    ...auditMixin(),
    orgId: uuid("org_id").notNull(),
    workspaceId: uuid("workspace_id"),
    userId: uuid("user_id").notNull(),
    kind: text("kind").notNull(), // system | approval | run | member | security
    title: text("title").notNull(),
    body: text("body"),
    deepLink: text("deep_link"),
    unread: boolean("unread").notNull().default(true),
    archived: boolean("archived").notNull().default(false),
    emailedAt: timestamp("emailed_at", { withTimezone: true, mode: "date" }),
  },
  (t) => ({
    userUnreadIdx: index("notifications_user_unread_idx").on(t.userId, t.unread),
    orgIdx: index("notifications_org_idx").on(t.orgId),
  }),
);

git add packages/database/src/schema/notification.ts
git commit -m "feat(db): notifications table"

    orgListingId: uuid("org_listing_id"),

export * from "./mcp";
export * from "./plugin";
export * from "./notification";

git add packages/database/src/schema/agent.ts packages/database/src/schema/index.ts
git commit -m "feat(db): wire org_listing into mcp_servers + export new schemas"

-- 0008_installable_plugins.sql
-- Installable plugins foundation: registries, catalog, org governance,
-- workspace install link, encrypted credentials, notifications.
-- Forward migration (immutable after merge). See spec
-- docs/superpowers/specs/2026-06-06-installable-plugins-mcp-design.md §4.

CREATE SCHEMA IF NOT EXISTS mcp;
CREATE SCHEMA IF NOT EXISTS plugin;
CREATE SCHEMA IF NOT EXISTS notification;

-- ---------------------------------------------------------------------------
-- mcp.registries
-- ---------------------------------------------------------------------------
CREATE TABLE mcp.registries (
  id                 uuid PRIMARY KEY DEFAULT COALESCE(
                       CASE WHEN to_regprocedure('public.uuid_generate_v7()') IS NOT NULL
                         THEN uuid_generate_v7() ELSE uuid_generate_v4() END,
                       uuid_generate_v4()),
  public_id          citext NOT NULL UNIQUE,
  created_at         timestamptz NOT NULL DEFAULT now(),
  updated_at         timestamptz NOT NULL DEFAULT now(),
  created_by_user_id uuid,
  updated_by_user_id uuid,
  org_id             uuid,
  name               text NOT NULL,
  base_url           text NOT NULL,
  enabled            boolean NOT NULL DEFAULT true,
  is_default_seed    boolean NOT NULL DEFAULT false,
  last_synced_at     timestamptz,
  last_synced_cursor text
);
CREATE INDEX registries_org_idx ON mcp.registries (org_id);
CREATE UNIQUE INDEX registries_org_baseurl_uniq ON mcp.registries (COALESCE(org_id, '00000000-0000-0000-0000-000000000000'::uuid), base_url);

-- ---------------------------------------------------------------------------
-- mcp.catalog_servers
-- ---------------------------------------------------------------------------
CREATE TABLE mcp.catalog_servers (
  id                  uuid PRIMARY KEY DEFAULT COALESCE(
                        CASE WHEN to_regprocedure('public.uuid_generate_v7()') IS NOT NULL
                          THEN uuid_generate_v7() ELSE uuid_generate_v4() END,
                        uuid_generate_v4()),
  public_id           citext NOT NULL UNIQUE,
  created_at          timestamptz NOT NULL DEFAULT now(),
  updated_at          timestamptz NOT NULL DEFAULT now(),
  created_by_user_id  uuid,
  updated_by_user_id  uuid,
  registry_id         uuid NOT NULL REFERENCES mcp.registries(id) ON DELETE CASCADE,
  name                text NOT NULL,
  version             text NOT NULL,
  is_latest           boolean NOT NULL DEFAULT false,
  title               text,
  description         text NOT NULL,
  repository          jsonb,
  website_url         text,
  icons               jsonb NOT NULL DEFAULT '[]'::jsonb,
  packages            jsonb NOT NULL DEFAULT '[]'::jsonb,
  remotes             jsonb NOT NULL DEFAULT '[]'::jsonb,
  transport_types     text[] NOT NULL DEFAULT '{}'::text[],
  auth_kind           text NOT NULL,
  categories          text[] NOT NULL DEFAULT '{}'::text[],
  readme_html         text,
  readme_fetched_at   timestamptz,
  status              text NOT NULL,
  published_at        timestamptz,
  upstream_updated_at timestamptz,
  status_changed_at   timestamptz,
  meta                jsonb NOT NULL DEFAULT '{}'::jsonb,
  CONSTRAINT catalog_servers_status_chk CHECK (status IN ('active','deprecated','deleted')),
  CONSTRAINT catalog_servers_auth_kind_chk CHECK (auth_kind IN ('oauth','secret','none'))
);
CREATE UNIQUE INDEX catalog_servers_name_version_uniq ON mcp.catalog_servers (registry_id, name, version);
CREATE INDEX catalog_servers_registry_name_idx ON mcp.catalog_servers (registry_id, name);
CREATE INDEX catalog_servers_categories_gin ON mcp.catalog_servers USING gin (categories);
CREATE INDEX catalog_servers_transport_gin ON mcp.catalog_servers USING gin (transport_types);

-- ---------------------------------------------------------------------------
-- plugin.org_listings
-- ---------------------------------------------------------------------------
CREATE TABLE plugin.org_listings (
  id                 uuid PRIMARY KEY DEFAULT COALESCE(
                       CASE WHEN to_regprocedure('public.uuid_generate_v7()') IS NOT NULL
                         THEN uuid_generate_v7() ELSE uuid_generate_v4() END,
                       uuid_generate_v4()),
  public_id          citext NOT NULL UNIQUE,
  created_at         timestamptz NOT NULL DEFAULT now(),
  updated_at         timestamptz NOT NULL DEFAULT now(),
  created_by_user_id uuid,
  updated_by_user_id uuid,
  deleted_at         timestamptz,
  deleted_by_user_id uuid,
  org_id             uuid NOT NULL,
  plugin_type        text NOT NULL,
  catalog_server_id  uuid REFERENCES mcp.catalog_servers(id) ON DELETE SET NULL,
  source             text NOT NULL,
  name               text NOT NULL,
  title              text,
  description        text,
  icon_url           text,
  endpoint_url       text,
  transport          text,
  auth_kind          text NOT NULL,
  auth_config        jsonb NOT NULL DEFAULT '{}'::jsonb,
  enabled            boolean NOT NULL DEFAULT false,
  config             jsonb NOT NULL DEFAULT '{}'::jsonb,
  CONSTRAINT org_listings_type_chk CHECK (plugin_type IN ('mcp_server','integration','content_tool')),
  CONSTRAINT org_listings_source_chk CHECK (source IN ('registry','custom')),
  CONSTRAINT org_listings_auth_kind_chk CHECK (auth_kind IN ('oauth','secret','none'))
);
CREATE UNIQUE INDEX org_listings_org_type_name_uniq ON plugin.org_listings (org_id, plugin_type, name);
CREATE INDEX org_listings_org_type_idx ON plugin.org_listings (org_id, plugin_type);

-- ---------------------------------------------------------------------------
-- plugin.org_denylist
-- ---------------------------------------------------------------------------
CREATE TABLE plugin.org_denylist (
  id                 uuid PRIMARY KEY DEFAULT COALESCE(
                       CASE WHEN to_regprocedure('public.uuid_generate_v7()') IS NOT NULL
                         THEN uuid_generate_v7() ELSE uuid_generate_v4() END,
                       uuid_generate_v4()),
  public_id          citext NOT NULL UNIQUE,
  created_at         timestamptz NOT NULL DEFAULT now(),
  updated_at         timestamptz NOT NULL DEFAULT now(),
  created_by_user_id uuid,
  updated_by_user_id uuid,
  org_id             uuid NOT NULL,
  plugin_type        text NOT NULL,
  server_name        text NOT NULL,
  reason             text,
  CONSTRAINT org_denylist_type_chk CHECK (plugin_type IN ('mcp_server','integration','content_tool'))
);
CREATE UNIQUE INDEX org_denylist_org_type_name_uniq ON plugin.org_denylist (org_id, plugin_type, server_name);

-- ---------------------------------------------------------------------------
-- mcp.credentials  (SOC2 encrypted)
-- ---------------------------------------------------------------------------
CREATE TABLE mcp.credentials (
  id                      uuid PRIMARY KEY DEFAULT COALESCE(
                            CASE WHEN to_regprocedure('public.uuid_generate_v7()') IS NOT NULL
                              THEN uuid_generate_v7() ELSE uuid_generate_v4() END,
                            uuid_generate_v4()),
  public_id               citext NOT NULL UNIQUE,
  created_at              timestamptz NOT NULL DEFAULT now(),
  updated_at              timestamptz NOT NULL DEFAULT now(),
  created_by_user_id      uuid,
  updated_by_user_id      uuid,
  org_id                  uuid NOT NULL,
  workspace_id            uuid NOT NULL,
  org_listing_id          uuid NOT NULL REFERENCES plugin.org_listings(id) ON DELETE CASCADE,
  auth_kind               text NOT NULL,
  access_token_enc        bytea,
  refresh_token_enc       bytea,
  secret_enc              bytea,
  oauth_client_secret_enc bytea,
  token_kms_key_id        text,
  oauth_client_id         text,
  scopes                  text[] NOT NULL DEFAULT '{}'::text[],
  expires_at              timestamptz,
  status                  text NOT NULL DEFAULT 'active',
  last_refreshed_at       timestamptz,
  CONSTRAINT credentials_auth_kind_chk CHECK (auth_kind IN ('oauth','secret')),
  CONSTRAINT credentials_status_chk CHECK (status IN ('active','needs_reauth','revoked'))
);
CREATE UNIQUE INDEX credentials_workspace_listing_uniq ON mcp.credentials (workspace_id, org_listing_id);
CREATE INDEX credentials_org_idx ON mcp.credentials (org_id);

-- ---------------------------------------------------------------------------
-- agent.mcp_servers — add org_listing_id link
-- ---------------------------------------------------------------------------
ALTER TABLE agent.mcp_servers ADD COLUMN org_listing_id uuid REFERENCES plugin.org_listings(id) ON DELETE CASCADE;
CREATE INDEX mcp_servers_org_listing_idx ON agent.mcp_servers (org_listing_id);

-- ---------------------------------------------------------------------------
-- notification.notifications
-- ---------------------------------------------------------------------------
CREATE TABLE notification.notifications (
  id                 uuid PRIMARY KEY DEFAULT COALESCE(
                       CASE WHEN to_regprocedure('public.uuid_generate_v7()') IS NOT NULL
                         THEN uuid_generate_v7() ELSE uuid_generate_v4() END,
                       uuid_generate_v4()),
  public_id          citext NOT NULL UNIQUE,
  created_at         timestamptz NOT NULL DEFAULT now(),
  updated_at         timestamptz NOT NULL DEFAULT now(),
  created_by_user_id uuid,
  updated_by_user_id uuid,
  org_id             uuid NOT NULL,
  workspace_id       uuid,
  user_id            uuid NOT NULL,
  kind               text NOT NULL,
  title              text NOT NULL,
  body               text,
  deep_link          text,
  unread             boolean NOT NULL DEFAULT true,
  archived           boolean NOT NULL DEFAULT false,
  emailed_at         timestamptz,
  CONSTRAINT notifications_kind_chk CHECK (kind IN ('system','approval','run','member','security'))
);
CREATE INDEX notifications_user_unread_idx ON notification.notifications (user_id, unread);
CREATE INDEX notifications_org_idx ON notification.notifications (org_id);

-- ---------------------------------------------------------------------------
-- Seed: the official public MCP registry, enabled by default for every org
-- (org_id NULL ⇒ global default seed).
-- ---------------------------------------------------------------------------
INSERT INTO mcp.registries (public_id, org_id, name, base_url, enabled, is_default_seed)
VALUES (
  'mreg_' || lower(translate(encode(gen_random_bytes(14), 'base32'), '=', '')),
  NULL,
  'Official MCP Registry',
  'https://registry.modelcontextprotocol.io',
  true,
  true
);

git add packages/database/drizzle/0008_installable_plugins.sql
git commit -m "feat(db): 0007 installable plugins migration + default registry seed"

psql "postgres://oxagen:oxagen@localhost:5433/oxagen" -c "\dt mcp.*" -c "\dt plugin.*" -c "\dt notification.*" -c "SELECT name, base_url, is_default_seed FROM mcp.registries WHERE is_default_seed;"

import { describe, expect, it, beforeEach, afterEach } from "vitest";
import { resolveCredentialKms } from "./kms";

const VALID_KEY = Buffer.alloc(32, 7).toString("base64");

describe("resolveCredentialKms", () => {
  const prev = process.env.AUTH_TOKEN_ENCRYPTION_KEY;
  beforeEach(() => {
    delete process.env.AUTH_TOKEN_ENCRYPTION_KEY;
  });
  afterEach(() => {
    if (prev === undefined) delete process.env.AUTH_TOKEN_ENCRYPTION_KEY;
    else process.env.AUTH_TOKEN_ENCRYPTION_KEY = prev;
  });

  it("returns null when no key is configured", () => {
    expect(resolveCredentialKms()).toBeNull();
  });

  it("returns an adapter when a valid key is configured", () => {
    process.env.AUTH_TOKEN_ENCRYPTION_KEY = VALID_KEY;
    const kms = resolveCredentialKms();
    expect(kms).not.toBeNull();
    expect(typeof kms!.adapter.generateDataKey).toBe("function");
    expect(kms!.keyId).toBe("mcp_cred_v1");
  });
});

/**
 * Resolves the KMS adapter used to envelope-encrypt plugin credentials.
 *
 * Mirrors packages/auth/src/auth.ts: the local KEK adapter sources its master
 * key from AUTH_TOKEN_ENCRYPTION_KEY (base64 256-bit). When the key is absent
 * (local dev / tests without secrets), this returns null and the caller stores
 * no ciphertext — exactly as the auth package degrades. NEVER log key material.
 */
import { createLocalKmsAdapter, loadMasterKey } from "@oxagen/crypto/kms";
import type { KmsAdapter } from "@oxagen/crypto";

/** Stable per-row key-version label; bump for rotation. */
export const MCP_CREDENTIAL_KEY_ID = "mcp_cred_v1";

export interface ResolvedKms {
  adapter: KmsAdapter;
  keyId: string;
}

export function resolveCredentialKms(): ResolvedKms | null {
  const key = process.env.AUTH_TOKEN_ENCRYPTION_KEY;
  if (!key) return null;
  return {
    adapter: createLocalKmsAdapter(loadMasterKey(key)),
    keyId: MCP_CREDENTIAL_KEY_ID,
  };
}

git add packages/plugins/src/credentials/kms.ts packages/plugins/src/credentials/kms.test.ts
git commit -m "feat(plugins): credential KMS adapter resolver"

import { describe, expect, it } from "vitest";
import { createLocalKmsAdapter, loadMasterKey } from "@oxagen/crypto/kms";
import {
  encryptCredentialSecrets,
  decryptCredentialSecrets,
  MCP_CREDENTIAL_KEY_ID,
} from "./credential-service";

const kms = {
  adapter: createLocalKmsAdapter(loadMasterKey(Buffer.alloc(32, 9).toString("base64"))),
  keyId: MCP_CREDENTIAL_KEY_ID,
};

describe("credential-service", () => {
  it("round-trips access + refresh + secret tokens", async () => {
    const enc = await encryptCredentialSecrets(
      { accessToken: "at-123", refreshToken: "rt-456", secret: null, oauthClientSecret: null },
      kms,
    );
    expect(enc.tokenKmsKeyId).toBe(MCP_CREDENTIAL_KEY_ID);
    expect(Buffer.isBuffer(enc.accessTokenEnc)).toBe(true);
    expect(enc.secretEnc).toBeNull();

    const dec = await decryptCredentialSecrets(
      {
        tokenKmsKeyId: enc.tokenKmsKeyId,
        accessTokenEnc: enc.accessTokenEnc,
        refreshTokenEnc: enc.refreshTokenEnc,
        secretEnc: enc.secretEnc,
        oauthClientSecretEnc: enc.oauthClientSecretEnc,
      },
      kms,
    );
    expect(dec.accessToken).toBe("at-123");
    expect(dec.refreshToken).toBe("rt-456");
    expect(dec.secret).toBeNull();
  });

  it("encrypts a header secret for the secret auth kind", async () => {
    const enc = await encryptCredentialSecrets(
      { accessToken: null, refreshToken: null, secret: "sk-live-789", oauthClientSecret: null },
      kms,
    );
    expect(Buffer.isBuffer(enc.secretEnc)).toBe(true);
    const dec = await decryptCredentialSecrets(
      { tokenKmsKeyId: enc.tokenKmsKeyId, secretEnc: enc.secretEnc },
      kms,
    );
    expect(dec.secret).toBe("sk-live-789");
  });

  it("returns null plaintext when no kms key id is present", async () => {
    const dec = await decryptCredentialSecrets(
      { tokenKmsKeyId: null, accessTokenEnc: Buffer.from("x") },
      kms,
    );
    expect(dec.accessToken).toBeNull();
  });
});

/**
 * Envelope-encrypts plugin credential secrets (OAuth access/refresh tokens,
 * API-key/header secrets, OAuth client secret) for storage in mcp.credentials.
 *
 * Modeled on packages/auth/src/token-encryption.ts: the service layer encrypts
 * before write and decrypts after read; the *_enc columns store opaque Buffers.
 * NEVER log plaintext secret values in this module.
 */
import { encrypt, decrypt } from "@oxagen/crypto";
import type { ResolvedKms } from "./kms";

export { MCP_CREDENTIAL_KEY_ID } from "./kms";

/** Plaintext secrets supplied by the caller for encryption. */
export interface CredentialPlaintext {
  accessToken?: string | null;
  refreshToken?: string | null;
  secret?: string | null;
  oauthClientSecret?: string | null;
}

/** Encrypted column values written to mcp.credentials. */
export interface CredentialCiphertext {
  accessTokenEnc: Buffer | null;
  refreshTokenEnc: Buffer | null;
  secretEnc: Buffer | null;
  oauthClientSecretEnc: Buffer | null;
  tokenKmsKeyId: string;
}

async function enc1(
  value: string | null | undefined,
  kms: ResolvedKms,
): Promise<Buffer | null> {
  if (value == null || value === "") return null;
  return encrypt(value, kms.keyId, { adapter: kms.adapter });
}

async function dec1(
  value: Buffer | null | undefined,
  keyId: string,
  kms: ResolvedKms,
): Promise<string | null> {
  if (value == null) return null;
  const buf = await decrypt(value, keyId, { adapter: kms.adapter });
  return buf.toString("utf8");
}

/** Encrypt all secret fields. Returns only the encrypted columns + key id. */
export async function encryptCredentialSecrets(
  data: CredentialPlaintext,
  kms: ResolvedKms,
): Promise<CredentialCiphertext> {
  const [accessTokenEnc, refreshTokenEnc, secretEnc, oauthClientSecretEnc] =
    await Promise.all([
      enc1(data.accessToken, kms),
      enc1(data.refreshToken, kms),
      enc1(data.secret, kms),
      enc1(data.oauthClientSecret, kms),
    ]);
  return {
    accessTokenEnc,
    refreshTokenEnc,
    secretEnc,
    oauthClientSecretEnc,
    tokenKmsKeyId: kms.keyId,
  };
}

/** Encrypted column values read from mcp.credentials, for decryption. */
export interface CredentialCiphertextRead {
  tokenKmsKeyId: string | null;
  accessTokenEnc?: Buffer | null;
  refreshTokenEnc?: Buffer | null;
  secretEnc?: Buffer | null;
  oauthClientSecretEnc?: Buffer | null;
}

/** Decrypt all secret fields. Rows without a key id predate encryption. */
export async function decryptCredentialSecrets(
  data: CredentialCiphertextRead,
  kms: ResolvedKms,
): Promise<{
  accessToken: string | null;
  refreshToken: string | null;
  secret: string | null;
  oauthClientSecret: string | null;
}> {
  const keyId = data.tokenKmsKeyId;
  if (!keyId) {
    return { accessToken: null, refreshToken: null, secret: null, oauthClientSecret: null };
  }
  const [accessToken, refreshToken, secret, oauthClientSecret] = await Promise.all([
    dec1(data.accessTokenEnc, keyId, kms),
    dec1(data.refreshTokenEnc, keyId, kms),
    dec1(data.secretEnc, keyId, kms),
    dec1(data.oauthClientSecretEnc, keyId, kms),
  ]);
  return { accessToken, refreshToken, secret, oauthClientSecret };
}

git add packages/plugins/src/credentials/credential-service.ts packages/plugins/src/credentials/credential-service.test.ts
git commit -m "feat(plugins): credential encrypt/decrypt service"

export { resolveCredentialKms } from "./credentials/kms";
export type { ResolvedKms } from "./credentials/kms";

git add packages/plugins/src/index.ts
git commit -m "chore(plugins): finalize credential service barrel exports"

  "dependencies": {
    "@oxagen/crypto": "workspace:*",
    "@oxagen/database": "workspace:*",
    "@oxagen/tenancy": "workspace:*",
    "zod": "3.25.76",
    "unified": "11.0.5",
    "remark-parse": "11.0.0",
    "remark-gfm": "4.0.1",
    "remark-rehype": "11.1.2",
    "rehype-sanitize": "6.0.0",
    "rehype-stringify": "10.0.1"
  },

git add packages/plugins/package.json pnpm-lock.yaml
git commit -m "chore(plugins): add registry-sync deps (zod, db, tenancy, unified markdown stack)"

import { z } from "zod";

/** A sized icon for UI rendering. */
export const iconSchema = z.object({
  src: z.string().url(),
  mimeType: z.string().optional(),
  sizes: z.array(z.string()).optional(),
  theme: z.enum(["light", "dark"]).optional(),
});

/** Source repository metadata. */
export const repositorySchema = z.object({
  url: z.string(),
  source: z.string(),
  id: z.string().optional(),
  subfolder: z.string().optional(),
});

/** A declared secret-bearing input (env var / header / remote variable). */
export const secretFlagSchema = z.object({
  isSecret: z.boolean().optional(),
  isRequired: z.boolean().optional(),
});

/** Local package install descriptor. */
export const packageSchema = z
  .object({
    registryType: z.string(),
    identifier: z.string(),
    version: z.string().optional(),
    transport: z.object({ type: z.string() }).passthrough().optional(),
    runtimeHint: z.string().optional(),
    environmentVariables: z
      .array(z.object({ name: z.string() }).merge(secretFlagSchema).passthrough())
      .optional(),
  })
  .passthrough();

/** Remote (hosted) transport descriptor. */
export const remoteSchema = z
  .object({
    type: z.string(),
    url: z.string(),
    headers: z
      .array(z.object({ name: z.string(), value: z.string().optional() }).merge(secretFlagSchema).passthrough())
      .optional(),
    variables: z.record(z.object({}).merge(secretFlagSchema).passthrough()).optional(),
  })
  .passthrough();

/** The publisher-authored server record. */
export const serverDetailSchema = z
  .object({
    name: z.string(),
    description: z.string(),
    version: z.string(),
    title: z.string().optional(),
    repository: repositorySchema.optional(),
    websiteUrl: z.string().optional(),
    icons: z.array(iconSchema).optional(),
    packages: z.array(packageSchema).optional(),
    remotes: z.array(remoteSchema).optional(),
  })
  .passthrough();

/** Registry-managed metadata wrapper. */
export const serverMetaSchema = z
  .object({
    status: z.enum(["active", "deprecated", "deleted"]).optional(),
    statusMessage: z.string().optional(),
    statusChangedAt: z.string().optional(),
    publishedAt: z.string().optional(),
    updatedAt: z.string().optional(),
    isLatest: z.boolean().optional(),
  })
  .passthrough();

export const serverResponseSchema = z.object({
  server: serverDetailSchema,
  _meta: serverMetaSchema.optional(),
});

export const listServersResponseSchema = z.object({
  servers: z.array(serverResponseSchema),
  metadata: z.object({ nextCursor: z.string().optional(), count: z.number().optional() }).optional(),
});

export type Icon = z.infer<typeof iconSchema>;
export type Repository = z.infer<typeof repositorySchema>;
export type ServerDetail = z.infer<typeof serverDetailSchema>;
export type ServerMeta = z.infer<typeof serverMetaSchema>;
export type ServerResponse = z.infer<typeof serverResponseSchema>;
export type ListServersResponse = z.infer<typeof listServersResponseSchema>;

import { describe, expect, it, vi, afterEach } from "vitest";
import { listServers, getServerVersion } from "./registry-client";

const BASE = "https://registry.example.com";

function mockFetchOnce(body: unknown, ok = true) {
  vi.stubGlobal(
    "fetch",
    vi.fn(async () => ({
      ok,
      status: ok ? 200 : 500,
      json: async () => body,
      text: async () => JSON.stringify(body),
    })) as unknown as typeof fetch,
  );
}

afterEach(() => vi.unstubAllGlobals());

describe("registry-client", () => {
  it("lists servers and returns the next cursor", async () => {
    mockFetchOnce({
      servers: [{ server: { name: "io.x/a", description: "d", version: "1.0.0" }, _meta: { isLatest: true } }],
      metadata: { nextCursor: "cur-2", count: 1 },
    });
    const res = await listServers(BASE, { limit: 50 });
    expect(res.servers).toHaveLength(1);
    expect(res.servers[0].server.name).toBe("io.x/a");
    expect(res.nextCursor).toBe("cur-2");
  });

  it("passes cursor/search/updatedSince as query params", async () => {
    const fetchMock = vi.fn(async () => ({ ok: true, status: 200, json: async () => ({ servers: [] }), text: async () => "{}" }));
    vi.stubGlobal("fetch", fetchMock as unknown as typeof fetch);
    await listServers(BASE, { cursor: "c1", search: "git", updatedSince: "2026-01-01T00:00:00Z" });
    const calledUrl = String(fetchMock.mock.calls[0][0]);
    expect(calledUrl).toContain("cursor=c1");
    expect(calledUrl).toContain("search=git");
    expect(calledUrl).toContain("updated_since=2026-01-01");
  });

  it("throws on a non-ok response", async () => {
    mockFetchOnce({ error: "boom" }, false);
    await expect(listServers(BASE, {})).rejects.toThrow(/registry list failed/i);
  });

  it("fetches a single server version", async () => {
    mockFetchOnce({ server: { name: "io.x/a", description: "d", version: "2.0.0" }, _meta: { isLatest: true } });
    const res = await getServerVersion(BASE, "io.x/a", "latest");
    expect(res.server.version).toBe("2.0.0");
  });
});

/**
 * Typed client for the MCP Registry OpenAPI (https://registry.modelcontextprotocol.io).
 * Discovery endpoints are unauthenticated; responses are Zod-validated. Cursor
 * pagination: follow metadata.nextCursor until absent.
 */
import {
  listServersResponseSchema,
  serverResponseSchema,
  type ServerResponse,
} from "./types";

export interface ListServersOptions {
  cursor?: string;
  limit?: number;
  search?: string;
  /** RFC3339 timestamp — incremental sync filter. */
  updatedSince?: string;
}

export interface ListServersResult {
  servers: ServerResponse[];
  nextCursor: string | undefined;
}

function joinUrl(baseUrl: string, path: string): string {
  return `${baseUrl.replace(/\/+$/, "")}${path}`;
}

export async function listServers(
  baseUrl: string,
  opts: ListServersOptions,
): Promise<ListServersResult> {
  const params = new URLSearchParams();
  if (opts.cursor) params.set("cursor", opts.cursor);
  if (opts.limit) params.set("limit", String(opts.limit));
  if (opts.search) params.set("search", opts.search);
  if (opts.updatedSince) params.set("updated_since", opts.updatedSince);
  const qs = params.toString();
  const url = joinUrl(baseUrl, `/v0.1/servers${qs ? `?${qs}` : ""}`);

  const res = await fetch(url, { headers: { accept: "application/json" } });
  if (!res.ok) {
    throw new Error(`registry list failed: ${res.status} ${await res.text()}`);
  }
  const parsed = listServersResponseSchema.parse(await res.json());
  return { servers: parsed.servers, nextCursor: parsed.metadata?.nextCursor };
}

export async function getServerVersion(
  baseUrl: string,
  name: string,
  version: string,
): Promise<ServerResponse> {
  const url = joinUrl(
    baseUrl,
    `/v0.1/servers/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}`,
  );
  const res = await fetch(url, { headers: { accept: "application/json" } });
  if (!res.ok) {
    throw new Error(`registry get failed: ${res.status} ${await res.text()}`);
  }
  return serverResponseSchema.parse(await res.json());
}

git add packages/plugins/src/registry/types.ts packages/plugins/src/registry/registry-client.ts packages/plugins/src/registry/registry-client.test.ts
git commit -m "feat(plugins): MCP registry OpenAPI client + Zod response types"

import { describe, expect, it } from "vitest";
import { deriveTransportTypes, deriveAuthKind, mapServerDetailToCatalogRow } from "./map-server";
import type { ServerDetail, ServerMeta } from "./types";

const REGISTRY_ID = "11111111-1111-1111-1111-111111111111";

describe("deriveTransportTypes", () => {
  it("collects distinct transport types from packages + remotes", () => {
    const sd: ServerDetail = {
      name: "io.x/a", description: "d", version: "1.0.0",
      packages: [{ registryType: "npm", identifier: "a", transport: { type: "stdio" } }],
      remotes: [{ type: "streamable-http", url: "https://x" }, { type: "sse", url: "https://y" }],
    };
    expect(deriveTransportTypes(sd).sort()).toEqual(["sse", "stdio", "streamable-http"]);
  });
});

describe("deriveAuthKind", () => {
  it("returns 'none' when nothing is secret", () => {
    const sd: ServerDetail = { name: "io.x/a", description: "d", version: "1.0.0", remotes: [{ type: "sse", url: "https://x" }] };
    expect(deriveAuthKind(sd)).toBe("none");
  });
  it("returns 'secret' when a remote variable is secret", () => {
    const sd: ServerDetail = {
      name: "io.x/a", description: "d", version: "1.0.0",
      remotes: [{ type: "streamable-http", url: "https://x", variables: { API_KEY: { isSecret: true } } }],
    };
    expect(deriveAuthKind(sd)).toBe("secret");
  });
  it("returns 'secret' when a package env var is secret", () => {
    const sd: ServerDetail = {
      name: "io.x/a", description: "d", version: "1.0.0",
      packages: [{ registryType: "npm", identifier: "a", transport: { type: "stdio" }, environmentVariables: [{ name: "TOKEN", isSecret: true }] }],
    };
    expect(deriveAuthKind(sd)).toBe("secret");
  });
});

describe("mapServerDetailToCatalogRow", () => {
  it("maps a ServerDetail + meta into catalog columns", () => {
    const sd: ServerDetail = {
      name: "io.x/weather", description: "Weather", version: "1.2.3", title: "Weather",
      repository: { url: "https://github.com/x/weather", source: "github" },
      icons: [{ src: "https://x/i.png" }],
      remotes: [{ type: "streamable-http", url: "https://api/mcp", variables: { K: { isSecret: true } } }],
    };
    const meta: ServerMeta = { status: "active", isLatest: true, publishedAt: "2026-01-01T00:00:00Z", updatedAt: "2026-02-01T00:00:00Z" };
    const row = mapServerDetailToCatalogRow(sd, meta, REGISTRY_ID);
    expect(row.registryId).toBe(REGISTRY_ID);
    expect(row.name).toBe("io.x/weather");
    expect(row.version).toBe("1.2.3");
    expect(row.isLatest).toBe(true);
    expect(row.status).toBe("active");
    expect(row.authKind).toBe("secret");
    expect(row.transportTypes).toEqual(["streamable-http"]);
    expect(row.upstreamUpdatedAt).toBeInstanceOf(Date);
  });
  it("defaults status to active and isLatest to false when meta is absent", () => {
    const sd: ServerDetail = { name: "io.x/a", description: "d", version: "1.0.0" };
    const row = mapServerDetailToCatalogRow(sd, undefined, REGISTRY_ID);
    expect(row.status).toBe("active");
    expect(row.isLatest).toBe(false);
    expect(row.authKind).toBe("none");
  });
});