app/lib/mcp/scopes.ts

Functions

Imports

It imports no other module of this repo. Imported by app/lib/mcp/door.ts, app/lib/mcp/tools.ts.

Source

1// Scopes (ruling capsid/rulings/mcp-2026-10-10.md, rule 12.3). A client that asks for carrel:read
2// alone gets read alone. A client that asks for carrel:write, or names no Carrel scope at all, gets
3// read and write (Dustin, 2026-10-10: a client that names no scope must not lose drafts and flags),
4// and the person can always narrow it to reading on the consent page. What a session may do is still
5// decided by the person's role below this layer: a scope can only narrow that, never widen it.
6//
7// The one scope a grant carried before 2026-10-10, "carrel", was approved on a consent page that
8// named writing, so it reads as both until that grant is replaced at the next sign-in.
9
10export const SCOPE_READ = "carrel:read";
11export const SCOPE_WRITE = "carrel:write";
12const LEGACY_SCOPE = "carrel";
13
14/** The scopes the authorization server offers, in the order the consent page names them. */
15export const SCOPES_SUPPORTED = [SCOPE_READ, SCOPE_WRITE];
16
17/**
18 * What a new grant carries. Reading only, when the person chose it on the consent page or the client
19 * asked for carrel:read and nothing more. Otherwise read and write: the client asked for write (or
20 * for the legacy scope, which a client that connected before may still send), or it named no Carrel
21 * scope at all, which defaults to both.
22 */
23export function grantScopes(requested: readonly string[], opts: { readOnly?: boolean } = {}): string[] {
24  if (opts.readOnly) return [SCOPE_READ];
25  const asked = new Set(requested);
26  if (asked.has(SCOPE_WRITE) || asked.has(LEGACY_SCOPE)) return [SCOPE_READ, SCOPE_WRITE];
27  // Naming no Carrel scope at all defaults to both.
28  if (!asked.has(SCOPE_READ)) return [SCOPE_READ, SCOPE_WRITE];
29  return [SCOPE_READ];
30}
31
32/** The scopes a token's grant carries, with the legacy scope read as both. */
33export function effectiveScopes(granted: readonly string[]): string[] {
34  const out = new Set<string>();
35  for (const scope of granted) {
36    if (scope === LEGACY_SCOPE) {
37      out.add(SCOPE_READ);
38      out.add(SCOPE_WRITE);
39    } else if (SCOPES_SUPPORTED.includes(scope)) out.add(scope);
40  }
41  return [...out];
42}
43
44/** Every scope, for a named agent key: its reach is its People row's role, set by Dustin. */
45export const AGENT_SCOPES = [SCOPE_READ, SCOPE_WRITE];