@moretea-labs/forge 1.5.1 → 1.7.0

package/src/runtime/plugins/browser-session-authority.ts

@@ -0,0 +1,332 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'crypto';
+import { readdirSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+import {
+  listControlPlaneRecords,
+  readControlPlaneRecord,
+  readControlPlaneRecordWithinTransaction,
+  withControlPlaneTransaction,
+  writeControlPlaneRecordWithinTransaction,
+} from '../control-plane/persistence/sqlite-store';
+
+const SESSION_NAMESPACE = 'browser_session';
+const SESSION_SCOPE = 'controller';
+const IMPORT_NAMESPACE = 'browser_session_legacy_import';
+const MAX_AUTHORITY_RECORDS = 5_000;
+export const DEFAULT_BROWSER_SESSION_LIST_LIMIT = 50;
+export const MAX_BROWSER_SESSION_LIST_LIMIT = 200;
+
+export interface BrowserSessionAuthorityContext {
+  controllerHome: string;
+  repoId: string;
+}
+
+export interface BrowserSessionAuthoritySession {
+  schemaVersion: 1;
+  sessionId: string;
+  url: string;
+  title?: string;
+  createdAt: string;
+  updatedAt: string;
+  browser?: {
+    provider?: string;
+    browserProduct?: string;
+    tab?: {
+      windowId?: string;
+      tabId?: string;
+      ownership?: string;
+    };
+  };
+}
+
+interface BrowserSessionAuthorityEntry<T extends BrowserSessionAuthoritySession = BrowserSessionAuthoritySession> {
+  schemaVersion: 1;
+  status: 'active' | 'tombstoned';
+  session: T;
+  aliases: string[];
+  repositoryIds: string[];
+  nativeIdentity?: string;
+  tombstonedAt?: string;
+  importedFromLegacy?: boolean;
+}
+
+interface LegacyImportMarker {
+  schemaVersion: 1;
+  repoId: string;
+  repoRootFingerprint: string;
+  importedAt: string;
+  importedRecordCount: number;
+}
+
+export interface BrowserSessionAuthorityPage<T extends BrowserSessionAuthoritySession = BrowserSessionAuthoritySession> {
+  sessions: T[];
+  limit: number;
+  totalCount: number;
+  nextCursor?: string;
+}
+
+const authorityContextStorage = new AsyncLocalStorage<BrowserSessionAuthorityContext>();
+
+export function withBrowserSessionAuthorityContext<T>(
+  context: BrowserSessionAuthorityContext,
+  operation: () => T,
+): T {
+  return authorityContextStorage.run(context, operation);
+}
+
+export function currentBrowserSessionAuthorityContext(): BrowserSessionAuthorityContext | undefined {
+  return authorityContextStorage.getStore();
+}
+
+function digest(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function nativeIdentity(session: BrowserSessionAuthoritySession): string | undefined {
+  const browser = session.browser;
+  const tab = browser?.tab;
+  if (browser?.provider !== 'macos-apple-events' || !browser.browserProduct || !tab?.windowId || !tab.tabId) return undefined;
+  return `${browser.provider}:${browser.browserProduct}:${tab.windowId}:${tab.tabId}`;
+}
+
+function recordKey(repoId: string, session: BrowserSessionAuthoritySession): string {
+  const native = nativeIdentity(session);
+  return native ? `native-${digest(native).slice(0, 40)}` : `session-${digest(`${repoId}:${session.sessionId}`).slice(0, 40)}`;
+}
+
+function importMarkerKey(repoRoot: string): string {
+  return digest(resolve(repoRoot)).slice(0, 40);
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function parseLegacySession(path: string): BrowserSessionAuthoritySession {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`PLUGIN_BROWSER_SESSION_STATE_CORRUPT: ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`PLUGIN_BROWSER_SESSION_STATE_CORRUPT: ${path}: expected object`);
+  }
+  const session = parsed as Partial<BrowserSessionAuthoritySession>;
+  if (session.schemaVersion !== 1 || typeof session.sessionId !== 'string' || typeof session.url !== 'string'
+    || typeof session.createdAt !== 'string' || typeof session.updatedAt !== 'string') {
+    throw new Error(`PLUGIN_BROWSER_SESSION_STATE_CORRUPT: ${path}: required session fields are missing`);
+  }
+  return session as BrowserSessionAuthoritySession;
+}
+
+function legacySessions(repoRoot: string): BrowserSessionAuthoritySession[] {
+  const root = join(repoRoot, '.forge', 'browser', 'sessions');
+  let names: string[];
+  try {
+    names = readdirSync(root);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return [];
+    throw error;
+  }
+  return names.filter((name) => name.endsWith('.json')).sort().map((name) => parseLegacySession(join(root, name)));
+}
+
+function mergeEntry<T extends BrowserSessionAuthoritySession>(
+  existing: BrowserSessionAuthorityEntry<T> | undefined,
+  repoId: string,
+  session: T,
+  options: { importedFromLegacy?: boolean } = {},
+): BrowserSessionAuthorityEntry<T> {
+  const canonicalSessionId = existing?.session.sessionId ?? session.sessionId;
+  const canonicalCreatedAt = existing?.session.createdAt ?? session.createdAt;
+  const normalizedSession = {
+    ...session,
+    sessionId: canonicalSessionId,
+    createdAt: canonicalCreatedAt,
+  } as T;
+  return {
+    schemaVersion: 1,
+    status: 'active',
+    session: normalizedSession,
+    aliases: unique([...(existing?.aliases ?? []), existing?.session.sessionId ?? '', session.sessionId, canonicalSessionId]),
+    repositoryIds: unique([...(existing?.repositoryIds ?? []), repoId]),
+    nativeIdentity: nativeIdentity(session) ?? existing?.nativeIdentity,
+    importedFromLegacy: options.importedFromLegacy === true || existing?.importedFromLegacy === true,
+  };
+}
+
+export function ensureLegacyBrowserSessionsImported(controllerHome: string, repoId: string, repoRoot: string): number {
+  const markerKey = importMarkerKey(repoRoot);
+  if (readControlPlaneRecord<LegacyImportMarker>(controllerHome, IMPORT_NAMESPACE, repoId, markerKey)) return 0;
+  const sessions = legacySessions(repoRoot);
+  return withControlPlaneTransaction(controllerHome, (database) => {
+    const marker = readControlPlaneRecordWithinTransaction<LegacyImportMarker>(database, IMPORT_NAMESPACE, repoId, markerKey);
+    if (marker) return 0;
+    let imported = 0;
+    for (const session of sessions) {
+      const key = recordKey(repoId, session);
+      const current = readControlPlaneRecordWithinTransaction<BrowserSessionAuthorityEntry>(database, SESSION_NAMESPACE, SESSION_SCOPE, key);
+      const next = mergeEntry(current?.value, repoId, session, { importedFromLegacy: true });
+      writeControlPlaneRecordWithinTransaction(database, {
+        namespace: SESSION_NAMESPACE,
+        scope: SESSION_SCOPE,
+        key,
+        schemaVersion: 1,
+        value: next,
+        expectedRevision: current?.revision ?? null,
+        action: current ? 'legacy_merge' : 'legacy_import',
+      });
+      imported += 1;
+    }
+    writeControlPlaneRecordWithinTransaction(database, {
+      namespace: IMPORT_NAMESPACE,
+      scope: repoId,
+      key: markerKey,
+      schemaVersion: 1,
+      value: {
+        schemaVersion: 1,
+        repoId,
+        repoRootFingerprint: markerKey,
+        importedAt: new Date().toISOString(),
+        importedRecordCount: imported,
+      } satisfies LegacyImportMarker,
+      expectedRevision: null,
+      action: 'legacy_import_complete',
+    });
+    return imported;
+  });
+}
+
+function authorityEntries(controllerHome: string): BrowserSessionAuthorityEntry[] {
+  return listControlPlaneRecords<BrowserSessionAuthorityEntry>(controllerHome, {
+    namespace: SESSION_NAMESPACE,
+    scope: SESSION_SCOPE,
+    limit: MAX_AUTHORITY_RECORDS,
+  }).map((record) => record.value);
+}
+
+function visibleToRepository(entry: BrowserSessionAuthorityEntry, repoId: string): boolean {
+  return Boolean(entry.nativeIdentity) || entry.repositoryIds.includes(repoId);
+}
+
+function activeEntries(controllerHome: string, repoId: string, repoRoot: string): BrowserSessionAuthorityEntry[] {
+  ensureLegacyBrowserSessionsImported(controllerHome, repoId, repoRoot);
+  return authorityEntries(controllerHome)
+    .filter((entry) => entry.status === 'active' && visibleToRepository(entry, repoId))
+    .sort((left, right) => {
+      const updated = right.session.updatedAt.localeCompare(left.session.updatedAt);
+      return updated !== 0 ? updated : left.session.sessionId.localeCompare(right.session.sessionId);
+    });
+}
+
+export function saveBrowserSession<T extends BrowserSessionAuthoritySession>(
+  controllerHome: string,
+  repoId: string,
+  repoRoot: string,
+  session: T,
+): T {
+  ensureLegacyBrowserSessionsImported(controllerHome, repoId, repoRoot);
+  const key = recordKey(repoId, session);
+  return withControlPlaneTransaction(controllerHome, (database) => {
+    const current = readControlPlaneRecordWithinTransaction<BrowserSessionAuthorityEntry<T>>(database, SESSION_NAMESPACE, SESSION_SCOPE, key);
+    const next = mergeEntry(current?.value, repoId, session);
+    const written = writeControlPlaneRecordWithinTransaction(database, {
+      namespace: SESSION_NAMESPACE,
+      scope: SESSION_SCOPE,
+      key,
+      schemaVersion: 1,
+      value: next,
+      expectedRevision: current?.revision ?? null,
+      action: current ? 'save' : 'create',
+    });
+    return written.value.session;
+  });
+}
+
+export function findBrowserSession<T extends BrowserSessionAuthoritySession>(
+  controllerHome: string,
+  repoId: string,
+  repoRoot: string,
+  sessionId: string,
+): T | undefined {
+  return activeEntries(controllerHome, repoId, repoRoot)
+    .find((entry) => entry.session.sessionId === sessionId || entry.aliases.includes(sessionId))?.session as T | undefined;
+}
+
+export function listBrowserSessions<T extends BrowserSessionAuthoritySession>(
+  controllerHome: string,
+  repoId: string,
+  repoRoot: string,
+  options: { limit?: number; cursor?: string } = {},
+): BrowserSessionAuthorityPage<T> {
+  const entries = activeEntries(controllerHome, repoId, repoRoot);
+  const limit = Math.max(1, Math.min(Math.trunc(options.limit ?? DEFAULT_BROWSER_SESSION_LIST_LIMIT), MAX_BROWSER_SESSION_LIST_LIMIT));
+  let offset = 0;
+  if (options.cursor) {
+    try {
+      const parsed = JSON.parse(Buffer.from(options.cursor, 'base64url').toString('utf8')) as { offset?: unknown };
+      if (!Number.isInteger(parsed.offset) || Number(parsed.offset) < 0) throw new Error('invalid offset');
+      offset = Number(parsed.offset);
+    } catch {
+      throw new Error('PLUGIN_BROWSER_SESSION_CURSOR_INVALID: cursor is invalid or expired');
+    }
+  }
+  const page = entries.slice(offset, offset + limit);
+  const nextOffset = offset + page.length;
+  const nextCursor = nextOffset < entries.length
+    ? Buffer.from(JSON.stringify({ offset: nextOffset }), 'utf8').toString('base64url')
+    : undefined;
+  return {
+    sessions: page.map((entry) => entry.session as T),
+    limit,
+    totalCount: entries.length,
+    nextCursor,
+  };
+}
+
+export function listAllBrowserSessionsForRepository<T extends BrowserSessionAuthoritySession>(
+  controllerHome: string,
+  repoId: string,
+  repoRoot: string,
+): T[] {
+  return activeEntries(controllerHome, repoId, repoRoot).map((entry) => entry.session as T);
+}
+
+export function tombstoneBrowserSession(
+  controllerHome: string,
+  repoId: string,
+  repoRoot: string,
+  sessionId: string,
+): boolean {
+  ensureLegacyBrowserSessionsImported(controllerHome, repoId, repoRoot);
+  const record = listControlPlaneRecords<BrowserSessionAuthorityEntry>(controllerHome, {
+    namespace: SESSION_NAMESPACE,
+    scope: SESSION_SCOPE,
+    limit: MAX_AUTHORITY_RECORDS,
+  }).find((candidate) => {
+    const entry = candidate.value;
+    return entry.status === 'active' && visibleToRepository(entry, repoId)
+      && (entry.session.sessionId === sessionId || entry.aliases.includes(sessionId));
+  });
+  if (!record) return false;
+  return withControlPlaneTransaction(controllerHome, (database) => {
+    const current = readControlPlaneRecordWithinTransaction<BrowserSessionAuthorityEntry>(database, SESSION_NAMESPACE, SESSION_SCOPE, record.key);
+    if (!current || current.value.status !== 'active') return false;
+    writeControlPlaneRecordWithinTransaction(database, {
+      namespace: SESSION_NAMESPACE,
+      scope: SESSION_SCOPE,
+      key: record.key,
+      schemaVersion: 1,
+      value: {
+        ...current.value,
+        status: 'tombstoned',
+        tombstonedAt: new Date().toISOString(),
+      },
+      expectedRevision: current.revision,
+      action: 'tombstone',
+    });
+    return true;
+  });
+}

package/src/runtime/plugins/capability-authorization-grants.ts

@@ -0,0 +1,354 @@
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { controllerSystemRoot } from '../../cli/repositories/controller-home';
+import { ControllerLockContentionError, withControllerLock } from '../../cli/repositories/locks';
+import { readJsonFile, writeJsonAtomic } from '../shared/json-files';
+import type { AssistantPluginActionRisk, AssistantPluginAuthorizationTarget } from './types';
+
+export const DEFAULT_PLUGIN_CAPABILITY_GRANT_MINUTES = 30 * 24 * 60;
+const MAX_PLUGIN_CAPABILITY_GRANT_MINUTES = 90 * 24 * 60;
+
+export type PluginCapabilityAuthorizationGrantErrorCode =
+  | 'PLUGIN_CAPABILITY_GRANT_STORE_CORRUPT'
+  | 'PLUGIN_CAPABILITY_GRANT_STORE_BUSY'
+  | 'PLUGIN_CAPABILITY_GRANT_ARGUMENT_INVALID'
+  | 'PLUGIN_CAPABILITY_GRANT_DESTRUCTIVE_DENIED'
+  | 'PLUGIN_CAPABILITY_GRANT_NOT_FOUND'
+  | 'PLUGIN_CAPABILITY_GRANT_OWNER_MISMATCH';
+
+export class PluginCapabilityAuthorizationGrantError extends Error {
+  constructor(
+    public readonly code: PluginCapabilityAuthorizationGrantErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'PluginCapabilityAuthorizationGrantError';
+  }
+}
+
+export interface PluginCapabilityAuthorizationGrant {
+  schemaVersion: 1;
+  grantId: string;
+  ownerScope: string;
+  repoId: string;
+  pluginId: string;
+  capabilityId: string;
+  target: AssistantPluginAuthorizationTarget;
+  scopes: string[];
+  riskCeiling: Exclude<AssistantPluginActionRisk, 'destructive'>;
+  createdAt: string;
+  updatedAt: string;
+  expiresAt: string;
+  revokedAt?: string;
+  revokedReason?: string;
+}
+
+interface PluginCapabilityAuthorizationGrantStore {
+  schemaVersion: 1;
+  grants: PluginCapabilityAuthorizationGrant[];
+}
+
+export interface PluginCapabilityAuthorizationQuery {
+  ownerScope: string;
+  repoId: string;
+  pluginId: string;
+  capabilityId: string;
+  target: AssistantPluginAuthorizationTarget;
+  scopes: readonly string[];
+  risk: AssistantPluginActionRisk;
+  at?: Date;
+}
+
+export interface RecordPluginCapabilityAuthorizationInput extends Omit<PluginCapabilityAuthorizationQuery, 'risk' | 'at'> {
+  riskCeiling: AssistantPluginActionRisk;
+  expiresInMinutes?: number;
+  now?: Date;
+}
+
+export interface RevokePluginCapabilityAuthorizationInput {
+  grantId: string;
+  ownerScope: string;
+  reason: string;
+  now?: Date;
+}
+
+const RISK_RANK: Record<AssistantPluginActionRisk, number> = {
+  readonly: 0,
+  workspace_write: 1,
+  remote_write: 2,
+  destructive: 3,
+};
+
+const GENERIC_PLUGIN_AUTHORIZATION_ACTORS = new Set(['', 'anonymous', 'plugin_action_execute']);
+
+export function pluginCapabilityAuthorizationOwnerScope(origin: { surface: string; actor?: string }): string {
+  const actor = origin.actor?.trim() ?? '';
+  if (GENERIC_PLUGIN_AUTHORIZATION_ACTORS.has(actor)) return 'controller:shared';
+  return `${origin.surface}:${actor}`;
+}
+
+function required(value: string, label: string): string {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new PluginCapabilityAuthorizationGrantError(
+      'PLUGIN_CAPABILITY_GRANT_ARGUMENT_INVALID',
+      `${label} is required.`,
+    );
+  }
+  return normalized;
+}
+
+function normalizeScopes(scopes: readonly string[]): string[] {
+  return [...new Set(scopes.map((scope) => scope.trim()).filter(Boolean))].sort();
+}
+
+function normalizeTarget(target: AssistantPluginAuthorizationTarget): AssistantPluginAuthorizationTarget {
+  const kind = required(target.kind, 'target.kind');
+  const id = required(target.id, 'target.id');
+  const identityFingerprint = target.identityFingerprint?.trim();
+  return {
+    kind,
+    id,
+    ...(identityFingerprint ? { identityFingerprint } : {}),
+  };
+}
+
+function validateRisk(value: unknown, index: number): Exclude<AssistantPluginActionRisk, 'destructive'> {
+  if (value === 'readonly' || value === 'workspace_write' || value === 'remote_write') return value;
+  throw new Error(`grants[${index}].riskCeiling is invalid`);
+}
+
+function validatePersistedGrant(value: unknown, index: number): PluginCapabilityAuthorizationGrant {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`grants[${index}] must be an object`);
+  const record = value as Record<string, unknown>;
+  const string = (field: string) => {
+    const current = record[field];
+    if (typeof current !== 'string' || !current.trim()) throw new Error(`grants[${index}].${field} is invalid`);
+    return current.trim();
+  };
+  const targetValue = record.target;
+  if (!targetValue || typeof targetValue !== 'object' || Array.isArray(targetValue)) throw new Error(`grants[${index}].target is invalid`);
+  const targetRecord = targetValue as Record<string, unknown>;
+  if (typeof targetRecord.kind !== 'string' || !targetRecord.kind.trim() || typeof targetRecord.id !== 'string' || !targetRecord.id.trim()) {
+    throw new Error(`grants[${index}].target identity is invalid`);
+  }
+  if (targetRecord.identityFingerprint !== undefined && typeof targetRecord.identityFingerprint !== 'string') {
+    throw new Error(`grants[${index}].target.identityFingerprint is invalid`);
+  }
+  if (!Array.isArray(record.scopes) || record.scopes.some((scope) => typeof scope !== 'string')) {
+    throw new Error(`grants[${index}].scopes is invalid`);
+  }
+  const createdAt = string('createdAt');
+  const updatedAt = string('updatedAt');
+  const expiresAt = string('expiresAt');
+  if (![createdAt, updatedAt, expiresAt].every((timestamp) => Number.isFinite(Date.parse(timestamp)))) {
+    throw new Error(`grants[${index}] has invalid timestamps`);
+  }
+  if (Date.parse(expiresAt) < Date.parse(createdAt)) throw new Error(`grants[${index}] expires before creation`);
+  const revokedAt = record.revokedAt;
+  const revokedReason = record.revokedReason;
+  if (revokedAt !== undefined && (typeof revokedAt !== 'string' || !Number.isFinite(Date.parse(revokedAt)))) {
+    throw new Error(`grants[${index}].revokedAt is invalid`);
+  }
+  if (revokedReason !== undefined && typeof revokedReason !== 'string') throw new Error(`grants[${index}].revokedReason is invalid`);
+  return {
+    schemaVersion: 1,
+    grantId: string('grantId'),
+    ownerScope: string('ownerScope'),
+    repoId: string('repoId'),
+    pluginId: string('pluginId'),
+    capabilityId: string('capabilityId'),
+    target: normalizeTarget({
+      kind: targetRecord.kind,
+      id: targetRecord.id,
+      ...(typeof targetRecord.identityFingerprint === 'string' && targetRecord.identityFingerprint.trim()
+        ? { identityFingerprint: targetRecord.identityFingerprint.trim() }
+        : {}),
+    }),
+    scopes: normalizeScopes(record.scopes as string[]),
+    riskCeiling: validateRisk(record.riskCeiling, index),
+    createdAt,
+    updatedAt,
+    expiresAt,
+    ...(typeof revokedAt === 'string' ? { revokedAt } : {}),
+    ...(typeof revokedReason === 'string' ? { revokedReason } : {}),
+  };
+}
+
+export function pluginCapabilityAuthorizationGrantStorePath(controllerHome: string): string {
+  return join(controllerSystemRoot(controllerHome), 'plugin-capability-authorizations', 'grants.json');
+}
+
+function loadStore(controllerHome: string): PluginCapabilityAuthorizationGrantStore {
+  const path = pluginCapabilityAuthorizationGrantStorePath(controllerHome);
+  if (!existsSync(path)) return { schemaVersion: 1, grants: [] };
+  try {
+    const raw = readJsonFile<unknown>(path);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('store must be an object');
+    const record = raw as Record<string, unknown>;
+    if (record.schemaVersion !== 1 || !Array.isArray(record.grants)) throw new Error('schemaVersion/grants are invalid');
+    return { schemaVersion: 1, grants: record.grants.map(validatePersistedGrant) };
+  } catch (error) {
+    throw new PluginCapabilityAuthorizationGrantError(
+      'PLUGIN_CAPABILITY_GRANT_STORE_CORRUPT',
+      `Plugin capability authorization store is corrupt: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+function saveStore(controllerHome: string, store: PluginCapabilityAuthorizationGrantStore): void {
+  const path = pluginCapabilityAuthorizationGrantStorePath(controllerHome);
+  mkdirSync(join(controllerSystemRoot(controllerHome), 'plugin-capability-authorizations'), { recursive: true });
+  writeJsonAtomic(path, store);
+}
+
+function targetMatches(left: AssistantPluginAuthorizationTarget, right: AssistantPluginAuthorizationTarget): boolean {
+  return left.kind === right.kind
+    && left.id === right.id
+    && (left.identityFingerprint ?? '') === (right.identityFingerprint ?? '');
+}
+
+function scopesContain(granted: readonly string[], requested: readonly string[]): boolean {
+  const available = new Set(granted);
+  return requested.every((scope) => available.has(scope));
+}
+
+export function findActivePluginCapabilityAuthorization(
+  controllerHome: string,
+  query: PluginCapabilityAuthorizationQuery,
+): PluginCapabilityAuthorizationGrant | undefined {
+  if (query.risk === 'destructive') return undefined;
+  const ownerScope = required(query.ownerScope, 'ownerScope');
+  const repoId = required(query.repoId, 'repoId');
+  const pluginId = required(query.pluginId, 'pluginId');
+  const capabilityId = required(query.capabilityId, 'capabilityId');
+  const target = normalizeTarget(query.target);
+  const scopes = normalizeScopes(query.scopes);
+  const atMs = (query.at ?? new Date()).getTime();
+  return loadStore(controllerHome).grants
+    .filter((grant) => !grant.revokedAt && Date.parse(grant.expiresAt) > atMs)
+    .filter((grant) => grant.ownerScope === ownerScope
+      && grant.repoId === repoId
+      && grant.pluginId === pluginId
+      && grant.capabilityId === capabilityId
+      && targetMatches(grant.target, target)
+      && scopesContain(grant.scopes, scopes)
+      && RISK_RANK[grant.riskCeiling] >= RISK_RANK[query.risk])
+    .sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt))[0];
+}
+
+export function recordPluginCapabilityAuthorization(
+  controllerHome: string,
+  input: RecordPluginCapabilityAuthorizationInput,
+): PluginCapabilityAuthorizationGrant {
+  if (input.riskCeiling === 'destructive') {
+    throw new PluginCapabilityAuthorizationGrantError(
+      'PLUGIN_CAPABILITY_GRANT_DESTRUCTIVE_DENIED',
+      'Destructive plugin actions can never establish reusable capability authorization.',
+    );
+  }
+  const now = input.now ?? new Date();
+  const ownerScope = required(input.ownerScope, 'ownerScope');
+  const repoId = required(input.repoId, 'repoId');
+  const pluginId = required(input.pluginId, 'pluginId');
+  const capabilityId = required(input.capabilityId, 'capabilityId');
+  const target = normalizeTarget(input.target);
+  const scopes = normalizeScopes(input.scopes);
+  const rawMinutes = input.expiresInMinutes ?? DEFAULT_PLUGIN_CAPABILITY_GRANT_MINUTES;
+  if (!Number.isFinite(rawMinutes) || rawMinutes <= 0) {
+    throw new PluginCapabilityAuthorizationGrantError('PLUGIN_CAPABILITY_GRANT_ARGUMENT_INVALID', 'expiresInMinutes must be positive.');
+  }
+  const expiresInMinutes = Math.min(Math.max(1, Math.trunc(rawMinutes)), MAX_PLUGIN_CAPABILITY_GRANT_MINUTES);
+  const timestamp = now.toISOString();
+  const grant: PluginCapabilityAuthorizationGrant = {
+    schemaVersion: 1,
+    grantId: `plugin-grant-${randomUUID()}`,
+    ownerScope,
+    repoId,
+    pluginId,
+    capabilityId,
+    target,
+    scopes,
+    riskCeiling: input.riskCeiling,
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    expiresAt: new Date(now.getTime() + expiresInMinutes * 60_000).toISOString(),
+  };
+  try {
+    return withControllerLock(
+      controllerHome,
+      { scope: 'global', resource: 'plugin-capability-authorization-grants' },
+      `plugin-capability-grant:${ownerScope}`,
+      () => {
+        const store = loadStore(controllerHome);
+        store.grants = store.grants.filter((entry) => !(entry.ownerScope === ownerScope
+          && entry.repoId === repoId
+          && entry.pluginId === pluginId
+          && entry.capabilityId === capabilityId
+          && entry.target.kind === target.kind
+          && entry.target.id === target.id));
+        store.grants.push(grant);
+        saveStore(controllerHome, store);
+        return grant;
+      },
+      5_000,
+    );
+  } catch (error) {
+    if (error instanceof ControllerLockContentionError) {
+      throw new PluginCapabilityAuthorizationGrantError('PLUGIN_CAPABILITY_GRANT_STORE_BUSY', error.message);
+    }
+    throw error;
+  }
+}
+
+export function revokePluginCapabilityAuthorization(
+  controllerHome: string,
+  input: RevokePluginCapabilityAuthorizationInput,
+): PluginCapabilityAuthorizationGrant {
+  const grantId = required(input.grantId, 'grantId');
+  const ownerScope = required(input.ownerScope, 'ownerScope');
+  const reason = required(input.reason, 'reason');
+  const now = input.now ?? new Date();
+  try {
+    return withControllerLock(
+      controllerHome,
+      { scope: 'global', resource: 'plugin-capability-authorization-grants' },
+      `plugin-capability-revoke:${ownerScope}`,
+      () => {
+        const store = loadStore(controllerHome);
+        const index = store.grants.findIndex((grant) => grant.grantId === grantId);
+        if (index < 0) throw new PluginCapabilityAuthorizationGrantError('PLUGIN_CAPABILITY_GRANT_NOT_FOUND', `Grant ${grantId} was not found.`);
+        const current = store.grants[index]!;
+        if (current.ownerScope !== ownerScope) {
+          throw new PluginCapabilityAuthorizationGrantError('PLUGIN_CAPABILITY_GRANT_OWNER_MISMATCH', `Grant ${grantId} belongs to another owner scope.`);
+        }
+        const revoked: PluginCapabilityAuthorizationGrant = {
+          ...current,
+          updatedAt: now.toISOString(),
+          revokedAt: now.toISOString(),
+          revokedReason: reason,
+        };
+        store.grants[index] = revoked;
+        saveStore(controllerHome, store);
+        return revoked;
+      },
+      5_000,
+    );
+  } catch (error) {
+    if (error instanceof ControllerLockContentionError) {
+      throw new PluginCapabilityAuthorizationGrantError('PLUGIN_CAPABILITY_GRANT_STORE_BUSY', error.message);
+    }
+    throw error;
+  }
+}
+
+export function listPluginCapabilityAuthorizations(
+  controllerHome: string,
+  ownerScope?: string,
+): PluginCapabilityAuthorizationGrant[] {
+  const normalizedOwner = ownerScope?.trim();
+  return loadStore(controllerHome).grants
+    .filter((grant) => !normalizedOwner || grant.ownerScope === normalizedOwner)
+    .map((grant) => structuredClone(grant));
+}