Consent-time scope narrowing for MCP grants

src/lib/helpers/oauth2-mcp.ts

@@ -0,0 +1,209 @@
+import { env } from '$env/dynamic/public';
+import type { Models } from '@appwrite.io/console';
+import {
+    ALL_SCOPE,
+    PROJECT_ALL_SCOPE,
+    ORGANIZATION_ALL_SCOPE,
+    PROJECT_SCOPE_PREFIX,
+    ORGANIZATION_SCOPE_PREFIX,
+    scopeAction,
+    scopeResource,
+    type ConsentScopeModel,
+    type TierScopes
+} from '$lib/helpers/oauth2-scopes';
+
+/**
+ * MCP-grant detection and consent-time scope narrowing for the hosted Appwrite
+ * MCP server (granular MCP scopes design).
+ *
+ * The MCP server advertises the authorization server's full scope catalog, so
+ * MCP clients mechanically request *everything*. The consent screen detects
+ * those grants — the grant's RFC 8707 `resources` contains the MCP server's
+ * canonical resource URI — and only then offers a narrowing editor. Because
+ * every granular scope was literally requested, whatever the user narrows to is
+ * a plain subset that the approve endpoint's literal check already accepts.
+ *
+ * The detection signal is self-fulfilling: the resource value becomes the
+ * token's `aud`, and the MCP server hard-rejects foreign audiences, so a lying
+ * client gains nothing by claiming the MCP resource URI.
+ */
+
+/** Canonical resource URI of the hosted Appwrite MCP server. */
+export const DEFAULT_MCP_RESOURCE_URLS = ['https://mcp.appwrite.io/mcp'];
+
+/** Mirror of the authorization server's `scope` parameter length cap. */
+export const MAX_SCOPE_PARAM_LENGTH = 8192;
+
+/** Normalize an RFC 8707 resource URI for comparison: trailing slashes only —
+ *  resource indicators are canonical URIs, so anything else compares exactly. */
+export function normalizeResourceUrl(url: string): string {
+    return url.trim().replace(/\/+$/, '');
+}
+
+/**
+ * The MCP resource URIs this console recognizes. Defaults to the hosted MCP;
+ * extendable via the comma-separated `PUBLIC_MCP_RESOURCE_URLS` env var (e.g.
+ * `http://localhost:8000/mcp` for local development).
+ */
+export function mcpResourceUrls(raw?: string | null): string[] {
+    const configured = (raw ?? env.PUBLIC_MCP_RESOURCE_URLS ?? '')
+        .split(',')
+        .map(normalizeResourceUrl)
+        .filter((url) => url !== '');
+    return configured.length > 0 ? configured : DEFAULT_MCP_RESOURCE_URLS;
+}
+
+/** Whether any of the grant's requested resources is a known MCP resource URI. */
+export function isMcpResource(resources: string[], urls: string[] = mcpResourceUrls()): boolean {
+    const known = new Set(urls.map(normalizeResourceUrl));
+    return resources.some(
+        (resource) => typeof resource === 'string' && known.has(normalizeResourceUrl(resource))
+    );
+}
+
+/** MCP grants (and only MCP grants) get the consent-time narrowing editor. */
+export function isMcpGrant(grant: Models.Oauth2Grant, urls?: string[]): boolean {
+    return isMcpResource(grant.resources ?? [], urls ?? mcpResourceUrls());
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Grant composition — turn the editor's selection into the approve payload   */
+/* -------------------------------------------------------------------------- */
+
+/** Per-resource editor selection within one tier. Rows absent from the record
+ *  default to selected with full requested access. */
+export interface ResourceSelection {
+    selected: boolean;
+    /** `full` grants every requested action; `read` keeps only `.read`. */
+    level: 'full' | 'read';
+}
+
+export type TierSelection = Record<string, ResourceSelection>;
+
+export interface ComposeInput {
+    model: ConsentScopeModel;
+    project: TierSelection;
+    organization: TierSelection;
+    /** Master read-only toggle — treats every selected resource as `read`. */
+    readOnly: boolean;
+    /** True when the user narrowed the org/project resource pickers. */
+    resourcesNarrowed: boolean;
+}
+
+export interface ComposedGrant {
+    /**
+     * The `scope` value for the approve endpoint, or `undefined` to omit it.
+     * Omission means "grant the full literal requested list" — required so the
+     * consent-skip diff stays empty on the next re-authorization.
+     */
+    scope: string | undefined;
+    /** The user's selection is the full request — nothing was narrowed. */
+    untouched: boolean;
+    /** No non-identity scope remains; Authorize must be disabled. */
+    blocked: boolean;
+    /** A tier was collapsed to its umbrella to fit the scope length cap. */
+    lengthCollapsed: boolean;
+}
+
+/** The bare scope tokens (`tables.read`, …) one tier's selection emits. Every
+ *  emitted token is one of the tier's requested tokens — never synthesized —
+ *  so the result is a literal subset of the request by construction. */
+function tierEmission(
+    tier: TierScopes,
+    selection: TierSelection,
+    readOnly: boolean
+): { tokens: string[]; full: boolean } {
+    const tokens: string[] = [];
+    for (const token of tier.scopes) {
+        const resource = scopeResource(token);
+        const action = scopeAction(token);
+        const row = selection[resource] ?? { selected: true, level: 'full' };
+        if (!row.selected) continue;
+        const level = readOnly ? 'read' : row.level;
+        if (level === 'read' && action !== 'read') continue;
+        tokens.push(token);
+    }
+    return { tokens, full: tokens.length === tier.scopes.length };
+}
+
+/**
+ * Compose the scope narrowing to send to the approve endpoint.
+ *
+ * - Untouched selection → omit `scope` entirely: the server keeps the full
+ *   literal requested list, so re-authorizations skip consent (the diff against
+ *   the previously approved scopes stays empty).
+ * - Any narrowing → identity scopes plus the selected granular tokens; a tier
+ *   whose requested tokens all survive collapses to its requested umbrella
+ *   (`project:all` / `organization:all`). The console-wide `all` is never part
+ *   of a narrowed grant — it bypasses RFC 9396 resource restrictions.
+ * - `.write` never implies `.read`: a "Read + Write" row emits both tokens.
+ */
+export function composeGrantedScopes(input: ComposeInput): ComposedGrant {
+    const { model, readOnly, resourcesNarrowed } = input;
+
+    const project = tierEmission(model.project, input.project, readOnly);
+    const organization = tierEmission(model.organization, input.organization, readOnly);
+
+    const capabilitiesFull = project.full && organization.full && !readOnly;
+    if (capabilitiesFull && !resourcesNarrowed) {
+        return { scope: undefined, untouched: true, blocked: false, lengthCollapsed: false };
+    }
+
+    // A fully-kept tier collapses to its umbrella (when the umbrella was
+    // requested) — keeps the granted string short and re-consent diffs sane.
+    // Covers the degenerate umbrella-only request (`project:all` with no
+    // granular tokens) too: a full selection keeps the umbrella.
+    const tierScopes = (
+        tier: TierScopes,
+        emission: { tokens: string[]; full: boolean },
+        prefix: string,
+        umbrella: string
+    ): string[] => {
+        const requested = tier.all || tier.scopes.length > 0;
+        // Never collapse under read-only: the umbrella grants write, so a tier
+        // whose requested tokens are all `.read` (emission.full despite the
+        // toggle) must still emit the explicit token list.
+        if (requested && emission.full && tier.all && !readOnly) return [umbrella];
+        return emission.tokens.map((token) => prefix + token);
+    };
+
+    let projectScopes = tierScopes(model.project, project, PROJECT_SCOPE_PREFIX, PROJECT_ALL_SCOPE);
+    let organizationScopes = tierScopes(
+        model.organization,
+        organization,
+        ORGANIZATION_SCOPE_PREFIX,
+        ORGANIZATION_ALL_SCOPE
+    );
+
+    const blocked = projectScopes.length === 0 && organizationScopes.length === 0;
+
+    const identity = model.identity.map((scope) => scope.id);
+    const join = () => [...identity, ...projectScopes, ...organizationScopes].join(' ');
+
+    // Client-side mirror of the server's scope length cap. Unreachable in
+    // practice (the full catalog is ~2.6 KB), but if a selection ever exceeds
+    // it, collapse the larger tier to its requested umbrella and surface that.
+    // Umbrella collapse grants write, so it is off the table under read-only —
+    // the toggle already halves the token list, keeping it well under the cap.
+    let lengthCollapsed = false;
+    if (!readOnly && join().length > MAX_SCOPE_PARAM_LENGTH) {
+        const projectLength = projectScopes.join(' ').length;
+        const organizationLength = organizationScopes.join(' ').length;
+        if (projectLength >= organizationLength && model.project.all) {
+            projectScopes = [PROJECT_ALL_SCOPE];
+            lengthCollapsed = true;
+        } else if (model.organization.all) {
+            organizationScopes = [ORGANIZATION_ALL_SCOPE];
+            lengthCollapsed = true;
+        }
+        if (join().length > MAX_SCOPE_PARAM_LENGTH && model.project.all) {
+            projectScopes = [PROJECT_ALL_SCOPE];
+            lengthCollapsed = true;
+        }
+    }
+
+    return { scope: join(), untouched: false, blocked, lengthCollapsed };
+}
+
+/** Never granted by a narrowed MCP consent — documented here for tests. */
+export const NARROWED_GRANT_NEVER_INCLUDES = [ALL_SCOPE];

src/lib/helpers/oauth2-scopes.ts

@@ -192,6 +192,14 @@ const PROJECT_RESOURCE_COPY: Record<string, ResourceCopy> = {
         name: 'Project policies',
         desc: "This project's security and access policies."
     },
+    policies: {
+        name: 'Policies',
+        desc: "Legacy access to this project's security and backup policies."
+    },
+    'project.oauth2': {
+        name: 'OAuth2 configuration',
+        desc: "This project's OAuth2 authorization server configuration."
+    },
     templates: {
         name: 'Templates',
         desc: "The project's customizable email and SMS message templates."
@@ -236,6 +244,18 @@ const PROJECT_RESOURCE_COPY: Record<string, ResourceCopy> = {
         name: 'Rows',
         desc: 'The individual rows of data stored inside your database tables.'
     },
+    collections: {
+        name: 'Collections',
+        desc: 'Legacy database collections and their structure, replaced by tables.'
+    },
+    attributes: {
+        name: 'Attributes',
+        desc: 'Legacy collection attributes that define document structure, replaced by columns.'
+    },
+    documents: {
+        name: 'Documents',
+        desc: 'Legacy documents stored inside your collections, replaced by rows.'
+    },
     buckets: {
         name: 'Storage buckets',
         desc: 'Storage buckets and their file-level permission and security settings.'
@@ -256,6 +276,10 @@ const PROJECT_RESOURCE_COPY: Record<string, ResourceCopy> = {
         name: 'Executions',
         desc: 'The execution history and logs of your serverless functions.'
     },
+    execution: {
+        name: 'Executions (legacy)',
+        desc: 'Legacy access to function executions, replaced by Executions.'
+    },
     sites: {
         name: 'Sites',
         desc: 'Hosted sites and their deployments, builds, and configuration.'
@@ -371,6 +395,14 @@ const ORGANIZATION_RESOURCE_COPY: Record<string, ResourceCopy> = {
         name: 'Organization keys',
         desc: 'Organization-level API keys that authorize access across projects.'
     },
+    keys: {
+        name: 'Organization keys (legacy)',
+        desc: 'Legacy access to organization API keys, replaced by Organization keys.'
+    },
+    devKeys: {
+        name: 'Development keys',
+        desc: 'Development keys used to bypass rate limits while building locally.'
+    },
     domains: {
         name: 'Organization domains',
         desc: 'Custom domains owned and managed at the organization level.'
@@ -446,16 +478,21 @@ function actionRank(action: string): number {
     return 2;
 }
 
-function actionOf(scope: string): string {
+/** The action of a bare scope token — `read` in `tables.read`. */
+export function scopeAction(scope: string): string {
     const dot = scope.lastIndexOf('.');
     return dot === -1 ? scope : scope.slice(dot + 1);
 }
 
-function resourceOf(scope: string): string {
+/** The resource of a bare scope token — `tables` in `tables.read`. */
+export function scopeResource(scope: string): string {
     const dot = scope.lastIndexOf('.');
     return dot === -1 ? scope : scope.slice(0, dot);
 }
 
+const actionOf = scopeAction;
+const resourceOf = scopeResource;
+
 function tierLines(
     tier: TierScopes,
     prefix: string,
@@ -526,6 +563,63 @@ function tierLines(
     return lines;
 }
 
+/* -------------------------------------------------------------------------- */
+/*  Editor rows — per-resource rows for the MCP consent narrowing editor      */
+/* -------------------------------------------------------------------------- */
+
+export interface EditorRow {
+    /** Resource key (everything before the last dot), stable editor identity. */
+    resource: string;
+    /** Display title from the resource catalog, e.g. "Tables". */
+    title: string;
+    /** One-line description of what the resource covers. */
+    description?: string;
+    /** Requested actions for this resource, `read` before `write` before others. */
+    actions: string[];
+    hasRead: boolean;
+    hasWrite: boolean;
+    /** Access chip label for the full requested access, e.g. "Read + Write". */
+    access: string;
+    /** Whether the chip should read as elevated (write access). */
+    accessStrong: boolean;
+}
+
+/**
+ * Group one tier's requested scopes into per-resource editor rows for the MCP
+ * consent narrowing editor. Same grouping and copy as the read-only summary,
+ * but keyed by resource so each row can be toggled and its access level set.
+ */
+export function buildTierEditorRows(tier: TierScopes, prefix: string): EditorRow[] {
+    const copyMap =
+        prefix === PROJECT_SCOPE_PREFIX ? PROJECT_RESOURCE_COPY : ORGANIZATION_RESOURCE_COPY;
+    const groups = new Map<string, string[]>();
+    for (const scope of tier.scopes) {
+        const resource = resourceOf(scope);
+        const bucket = groups.get(resource);
+        if (bucket) bucket.push(scope);
+        else groups.set(resource, [scope]);
+    }
+    return [...groups.entries()].map(([resource, scopes]) => {
+        scopes.sort((a, b) => actionRank(actionOf(a)) - actionRank(actionOf(b)));
+        const actions = scopes.map(actionOf);
+        const { title, description, access, accessStrong } = describeResource(
+            resource,
+            actions,
+            copyMap
+        );
+        return {
+            resource,
+            title,
+            description,
+            actions,
+            hasRead: actions.includes('read'),
+            hasWrite: actions.includes('write'),
+            access,
+            accessStrong
+        };
+    });
+}
+
 /**
  * Build the read-only permission summary the consent screen displays. Scopes are
  * not individually selectable — the client decides what it requests — so this is