@coffre/core 0.3.0 → 0.4.0

package/src/mcp.ts

@@ -0,0 +1,233 @@
+/**
+ * What MCP clients may be, and do: the scopes a person grants one, and the
+ * rules its identity and redirects must pass (docs/design/mcp.md, sections
+ * 4 and 5). Plain functions over strings, for the server and the consent
+ * page alike.
+ */
+
+/** In the order the consent page lists them; `browse` is always granted. */
+export const MCP_SCOPES = ['browse', 'write', 'read-values', 'manage-access'] as const;
+
+export type McpScope = (typeof MCP_SCOPES)[number];
+
+export const MCP_SCOPE_INFO: Record<McpScope, { label: string; description: string }> = {
+  browse: {
+    label: 'Browse',
+    description: 'Projects, environments, key names, history, access and the audit log. Never a value.',
+  },
+  write: {
+    label: 'Write',
+    description: 'Set, generate, rename, archive and restore secrets; create projects and environments. Each change waits for your approval on coffre.',
+  },
+  'read-values': {
+    label: 'Read values',
+    description: 'Secret values, sent to the app. They become part of its conversation, wherever it keeps it.',
+  },
+  'manage-access': {
+    label: 'Manage access',
+    description: 'Grants, members, service tokens and trusted workloads. Each change waits for your approval on coffre.',
+  },
+};
+
+/** What OAuth's `offline_access` asks for, a refresh token, every connection has: accepted and dropped. */
+const IGNORED_SCOPES = new Set(['offline_access']);
+
+export function isMcpScope(value: string): value is McpScope {
+  return (MCP_SCOPES as readonly string[]).includes(value);
+}
+
+/**
+ * The scopes a space-separated `scope` asks for, in catalogue order, with
+ * `browse` always among them; and the ones coffre does not know, which the
+ * caller refuses as `invalid_scope`.
+ */
+export function parseScopes(value: string | null | undefined): { scopes: McpScope[]; unknown: string[] } {
+  const asked = new Set((value ?? '').split(' ').filter((scope) => scope !== '' && !IGNORED_SCOPES.has(scope)));
+  const unknown = [...asked].filter((scope) => !isMcpScope(scope));
+  return { scopes: MCP_SCOPES.filter((scope) => scope === 'browse' || asked.has(scope)), unknown };
+}
+
+/** Scopes as one string, in catalogue order: how a connection stores them and a token answer says them. */
+export function scopeString(scopes: Iterable<McpScope>): string {
+  const held = new Set(scopes);
+  return MCP_SCOPES.filter((scope) => held.has(scope)).join(' ');
+}
+
+/** A person's choice at consent: what was asked, minus what they unticked, and never without `browse`. */
+export function grantedScopes(asked: readonly McpScope[], chosen: readonly string[]): McpScope[] {
+  const picked = new Set(chosen);
+  return MCP_SCOPES.filter((scope) => scope === 'browse' || (asked.includes(scope) && picked.has(scope)));
+}
+
+/**
+ * Whether a connection granted `granted` supersedes an earlier one of the
+ * same client that holds `held`: it grants all of that and more, as a
+ * step-up does. The earlier one then ends, once the new one's code is
+ * redeemed; one with the same scopes, a second laptop say, stays.
+ */
+export function supersedes(granted: readonly McpScope[], held: readonly McpScope[]): boolean {
+  return held.every((scope) => granted.includes(scope)) && granted.some((scope) => !held.includes(scope));
+}
+
+// --- redirect URIs ----------------------------------------------------------
+
+/** A client's redirect, refused: the message says why, for the consent page and the registration answer. */
+export class ClientInvalid extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ClientInvalid';
+  }
+}
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '[::1]', 'localhost']);
+
+export type RedirectKind = 'https' | 'loopback';
+
+/**
+ * Where a redirect may go: HTTPS anywhere, or plain HTTP on loopback, which
+ * a native client such as Claude Code listens on (RFC 8252). No custom
+ * scheme, no fragment, no user or password.
+ */
+export function redirectKind(value: string): RedirectKind {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ClientInvalid(`${value} is not a URL`);
+  }
+  if (url.username !== '' || url.password !== '') throw new ClientInvalid(`${value} carries a user or password`);
+  if (url.hash !== '' || value.includes('#')) throw new ClientInvalid(`${value} has a fragment`);
+  if (url.protocol === 'https:') return 'https';
+  if (url.protocol === 'http:' && LOOPBACK_HOSTS.has(url.hostname)) return 'loopback';
+  throw new ClientInvalid(`${value} is neither HTTPS nor HTTP on loopback (127.0.0.1, [::1] or localhost)`);
+}
+
+/**
+ * Whether a requested redirect is one a client registered. Both are parsed
+ * first, so `http://127.0.0.1:33418` and `http://127.0.0.1:33418/` are one
+ * URL. A loopback one matches on any port, as RFC 8252 lets a native client
+ * bind whichever it can; everything else exactly.
+ */
+export function redirectMatches(registered: string, requested: string): boolean {
+  let a: URL;
+  let b: URL;
+  try {
+    redirectKind(requested);
+    a = new URL(registered);
+    b = new URL(requested);
+  } catch {
+    return false;
+  }
+  if (a.protocol === 'http:' && LOOPBACK_HOSTS.has(a.hostname)) {
+    return b.protocol === 'http:' && a.hostname === b.hostname && a.pathname === b.pathname && a.search === b.search;
+  }
+  return a.href === b.href;
+}
+
+/** The redirect's host, as the consent page shows it: `localhost` for every loopback one. */
+export function redirectHost(value: string): string {
+  const url = new URL(value);
+  return redirectKind(value) === 'loopback' ? 'localhost' : url.host;
+}
+
+// --- clients ------------------------------------------------------------------
+
+/** What coffre knows of a client, from its metadata document or its registration. */
+export type ClientMetadata = {
+  /** The document's URL, or the ID a registration was given. */
+  clientId: string;
+  /** Its own claim: shown, never trusted. */
+  name: string;
+  /** For a document, its URL's host; for a registration, null: it has none to vouch for it. */
+  host: string | null;
+  redirectUris: string[];
+  registration: 'cimd' | 'dcr';
+};
+
+const MAX_REDIRECTS = 10;
+const MAX_NAME = 100;
+
+/**
+ * Whether `value` is a Client ID Metadata Document's URL: HTTPS, with a
+ * path, and nothing a document's address has no use for. On a loopback
+ * instance, a loopback one too, for development and conformance.
+ */
+export function isClientIdUrl(value: string, options: { allowLoopback: boolean }): boolean {
+  if (!value.startsWith('https://') && !(options.allowLoopback && value.startsWith('http://'))) return false;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.href !== value || url.pathname === '/' || url.search !== '' || url.hash !== '') return false;
+  if (url.username !== '' || url.password !== '' || /\/\.\.?(\/|$)/.test(url.pathname)) return false;
+  return url.protocol === 'https:' || LOOPBACK_HOSTS.has(url.hostname);
+}
+
+/**
+ * A fetched Client ID Metadata Document, checked: it names itself, a name
+ * and its redirects, and it is a public client. An HTTPS redirect must be on
+ * the document's own host, so the consent page names one host: Claude's
+ * `https://claude.ai/api/mcp/auth_callback` is on `claude.ai`, where its
+ * document is.
+ */
+export function clientFromDocument(clientId: string, document: unknown): ClientMetadata {
+  if (typeof document !== 'object' || document === null || Array.isArray(document)) {
+    throw new ClientInvalid('the client metadata document is not a JSON object');
+  }
+  const fields = document as Record<string, unknown>;
+  if (fields.client_id !== clientId) throw new ClientInvalid('the client metadata document names another client_id than its own URL');
+  const method = fields.token_endpoint_auth_method;
+  if (method !== undefined && method !== 'none') {
+    throw new ClientInvalid(`the client authenticates with ${String(method)}; coffre takes public clients only, with PKCE`);
+  }
+  const host = new URL(clientId).host;
+  const uris = redirectList(fields.redirect_uris);
+  for (const uri of uris) {
+    if (redirectKind(uri) === 'https' && new URL(uri).host !== host) {
+      throw new ClientInvalid(`${uri} is not on ${host}, where the client's metadata document is`);
+    }
+  }
+  return { clientId, name: clientName(fields.client_name, host), host, redirectUris: uris, registration: 'cimd' };
+}
+
+/**
+ * What a registration may keep of what it asked for (RFC 7591): the
+ * redirects coffre accepts, the others left out rather than failing it, as
+ * the RFC lets a server replace what was asked. Cursor registers a
+ * `cursor://` callback beside its loopback and HTTPS ones; refused whole,
+ * it could not connect at all.
+ */
+export function registrationRedirects(value: unknown): { kept: string[]; dropped: string[] } {
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_REDIRECTS || value.some((uri) => typeof uri !== 'string' || uri.length > 400)) {
+    throw new ClientInvalid(`redirect_uris must list 1 to ${MAX_REDIRECTS} URLs`);
+  }
+  const kept: string[] = [];
+  const dropped: string[] = [];
+  for (const uri of value as string[]) {
+    try {
+      redirectKind(uri);
+      if (!kept.includes(uri)) kept.push(uri);
+    } catch {
+      dropped.push(uri);
+    }
+  }
+  if (kept.length === 0) throw new ClientInvalid(`none of the redirect_uris is HTTPS or HTTP on loopback: ${dropped.join(', ')}`);
+  return { kept, dropped };
+}
+
+/** A client's name as shown: its own, cut short, or its host when it gives none. */
+export function clientName(value: unknown, fallback: string): string {
+  // Control and bidirectional characters could make one name look like another.
+  const name = typeof value === 'string' ? value.replace(/[\p{Cc}\p{Cf}]/gu, '').trim() : '';
+  return name === '' ? fallback : name.slice(0, MAX_NAME);
+}
+
+function redirectList(value: unknown): string[] {
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_REDIRECTS || value.some((uri) => typeof uri !== 'string')) {
+    throw new ClientInvalid(`the client metadata document must list 1 to ${MAX_REDIRECTS} redirect_uris`);
+  }
+  for (const uri of value as string[]) redirectKind(uri);
+  return value as string[];
+}

package/src/pages.ts

@@ -1,6 +1,7 @@
 // What coffre's server and its pages agree on outside the API: the
 // visitor's preferences, which the server reads from a request's cookies
-// and the browser from its own, to draw the same page; and what either says
+// and the browser from its own, to draw the same page; the names a
+// project's pages take, which no environment may; and what either says
 // when coffre's request middleware is missing.
 
 /**
@@ -12,6 +13,14 @@ export type Preferences = { theme: 'system' | 'light' | 'dark'; sidebar: 'expand
 /** The cookies that hold them. */
 export const PREFERENCE_COOKIES = { theme: 'coffre-theme', sidebar: 'coffre-sidebar' } as const;
 
+/**
+ * A project's pages beside its environments': `/projects/market/settings`
+ * sits where `/projects/market/prod` does, so no environment takes one of
+ * these names (`environmentSlug` in `./schemas.ts`). A tab a project gains
+ * adds its word here.
+ */
+export const PROJECT_PAGES = ['users', 'service-accounts', 'settings'] as const;
+
 /** The preferences in a `Cookie` header, or in `document.cookie`, which reads the same. */
 export function preferencesIn(cookies: string | null): Preferences {
   const value = (name: string) => {

package/src/schemas.ts

@@ -1,8 +1,45 @@
 import { z } from 'zod';
 
+import { PROJECT_PAGES } from './pages.ts';
+
 export const slug = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
+/** An environment's slug: any slug but the name of one of its project's pages. */
+export const environmentSlug = slug.refine((value) => !(PROJECT_PAGES as readonly string[]).includes(value), {
+  error: (issue) => `"${String(issue.input)}" is taken by a project's page, /projects/<project>/${String(issue.input)}: an environment cannot have it`,
+});
+
+/**
+ * A deleted project or environment keeps its row as a tombstone, under a
+ * slug no live place can hold: `market~deleted-2026-10-05`. The `~` is the
+ * whole rule: a place is deleted when its slug, or its project's, holds one.
+ * `@coffre/db/dialect`'s `tombstone()` is the same rule in SQL.
+ */
+export const TOMBSTONE = '~';
+
+export function isTombstone(slug: string): boolean {
+  return slug.includes(TOMBSTONE);
+}
+
+/** The slug a place deleted on `day` keeps: the `n`th that day is `market~deleted-2026-10-05-<n>`. */
+export function tombstoneOf(slug: string, day: Date, n = 1): string {
+  const base = `${slug}${TOMBSTONE}deleted-${day.toISOString().slice(0, 10)}`;
+  return n === 1 ? base : `${base}-${n}`;
+}
 export const displayName = z.string().trim().min(1).max(120);
+/** A folder: 1 to 64 characters, no `/`, no control character, no space at either end (the tables check it too). */
+export const folderName = z.string().min(1).max(64)
+  .refine((name) => name === name.trim(), 'a folder name cannot start or end with a space')
+  .refine((name) => !/[/\p{Cc}]/u.test(name), 'a folder name cannot hold "/" or a control character');
 export const secretKey = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,127}$/);
+/**
+ * A member as people read it, in a message or on a page: a service account
+ * as `service:<name>`, though the API, the vault and the log keep the
+ * `token:<name>` their signed entries hold.
+ */
+export function shownMember(member: string): string {
+  return member.startsWith('token:') ? `service:${member.slice('token:'.length)}` : member;
+}
+
 export const principalType = z.enum(['user', 'service']);
 export const principalId = z.string().trim().min(1).max(320);
 export const instanceRole = z.enum(['user', 'owner']);

package/src/vault.ts

@@ -1,5 +1,5 @@
 import type { AccessFault } from './access-fault.ts';
-import type { Role } from './access.ts';
+import type { GrantPlace, Role } from './access.ts';
 
 export { checkpointMessage, checkpointVerifier, verifyCheckpoint } from './checkpoint.ts';
 export { describeAccessFault, type AccessFault, type FaultGrant, type FaultNames } from './access-fault.ts';
@@ -36,6 +36,25 @@ export interface Vault {
    */
   rewrap(input: RewrapInput): Promise<Outcome<{ wrapped: WrappedKey[]; seqs: number[] }>>;
 
+  /**
+   * Make secrets references to others: whoever can read the holder's
+   * environment reads the source through it (docs/design/environments.md).
+   * The vault checks that `principal` reads each source and writes each
+   * holder, by their own grants, and logs a `reference.create` per item:
+   * that entry, under the vault's MAC, is the reference. `seqs` are the
+   * entries, which the app stores beside each reference and names when it
+   * reads through one (`UnwrapInput`'s `via`). All, or none.
+   */
+  reference(input: ReferenceInput): Promise<Outcome<{ seqs: number[] }>>;
+  /**
+   * End references, each with a `reference.end` naming its creation:
+   * `replaced` when the holder gets a value of its own, which takes write on
+   * the holder; `broken` otherwise, which takes write on the holder, or
+   * managing the source's project's access. An ended reference reads no
+   * more, whatever any row says. All, or none.
+   */
+  endReferences(input: EndReferencesInput): Promise<Outcome<{ seqs: number[] }>>;
+
   /**
    * What one principal holds right now: the app asks once per request. A
    * decision, its rows checked: lists of who holds what read the rows
@@ -112,8 +131,15 @@ export type RefusalCode =
   | 'expired'
   /** Too many unwraps in the window; see `BulkLimit`. */
   | 'bulk_limit'
-  /** The wrapped key does not belong to the secret it was presented as. */
+  /** The wrapped key does not belong to the secret it was presented as, or a reference is not the vault's. */
   | 'bad_claim'
+  /**
+   * The project or environment was deleted for good: nothing under it is
+   * opened or wrapped again, whatever grant would cover it.
+   */
+  | 'deleted'
+  /** The reference read through was ended: broken, or replaced by a value. */
+  | 'ended'
   /** Not allowed to manage access, members or the log. */
   | 'not_allowed'
   /** Root admins come from the vault's configuration and cannot be changed. */
@@ -162,8 +188,8 @@ export type WrappedKey = { kekProvider: string; kekId: string; kekVersion: strin
  */
 export type KeyChecks = { current: { kekProvider: string; kekId: string }; checks: (WrappedKey & { seq: number })[] };
 
-/** Why someone reads: shown in the log, and the same rules apply to each. */
-export type Purpose = 'reveal' | 'run' | 'compare';
+/** Why someone reads: shown in the log, and the same rules apply to each. A fork reads to `copy`. */
+export type Purpose = 'reveal' | 'run' | 'compare' | 'copy';
 
 /** Ties the vault's entries to the app's request and audit rows. */
 type Correlation = {
@@ -184,7 +210,31 @@ type Correlation = {
 export type UnwrapInput = Correlation & {
   principal: string;
   purpose: Purpose;
-  items: { secretVersionId: string }[];
+  /**
+   * `via` reads a source's current version through a reference: the vault
+   * checks the reader's grants on the holder's environment, as its
+   * `reference.create` entry names it, not on the source's.
+   */
+  items: { secretVersionId: string; via?: Via }[];
+};
+
+/** A reference, as a read names it: its id, and the seq of the vault's `reference.create` entry. */
+export type Via = { reference: string; seq: number };
+
+/** Where a reference is held: the holder's ids, and its path for the log. A new holder's row may not exist yet. */
+export type HolderRef = { projectId: string; environmentId: string; secretId: string; path: string };
+
+export type ReferenceInput = Correlation & {
+  principal: string;
+  /** `id` is the reference's, a fresh UUID; the vault reads the source by its id. */
+  items: { id: string; holder: HolderRef; source: { secretId: string } }[];
+};
+
+export type EndReferencesInput = Correlation & {
+  principal: string;
+  /** `abandoned`: sealed for a write that stored nothing, so that no row written later revives it. */
+  reason: 'replaced' | 'broken' | 'abandoned';
+  items: Via[];
 };
 
 export type WrapInput = Correlation & {
@@ -199,10 +249,12 @@ export type RewrapInput = Correlation & {
   items: { secret: SecretRef; secretVersionId: string }[];
 };
 
-export type Grant = {
-  projectId: string;
-  /** Null for the whole project. */
-  environmentId: string | null;
+/**
+ * A grant: on a project, one of its environments (`projectId` is the
+ * environment's project), every project, or one environment slug in every
+ * project (`GrantPlace` in @coffre/core/access).
+ */
+export type Grant = GrantPlace & {
   role: Role;
   /** ISO 8601, or null for no end. */
   expiresAt: string | null;
@@ -230,10 +282,13 @@ export type Access = {
   by: string | null;
 };
 
-/** One place: a role to hold there, with an optional end, or null for none. */
-export type GrantChange = {
-  projectId: string;
-  environmentId: string | null;
+/**
+ * One place: a role to hold there, with an optional end, or null for none.
+ * An environment's place names its project too; `environmentSlug` left out
+ * is null.
+ */
+export type GrantChange = Omit<GrantPlace, 'environmentSlug'> & {
+  environmentSlug?: string | null;
   role: Role | null;
   expiresAt: string | null;
 };