@coffre/core 0.3.0 → 0.4.0

package/dist/schemas.js

@@ -1,12 +1,40 @@
+import { PROJECT_PAGES } from "./pages.js";
 import { z } from "zod";
 //#region src/schemas.ts
 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. */
+const environmentSlug = slug.refine((value) => !PROJECT_PAGES.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.
+*/
+const TOMBSTONE = "~";
+function isTombstone(slug) {
+	return slug.includes("~");
+}
+/** The slug a place deleted on `day` keeps: the `n`th that day is `market~deleted-2026-10-05-<n>`. */
+function tombstoneOf(slug, day, n = 1) {
+	const base = `${slug}~deleted-${day.toISOString().slice(0, 10)}`;
+	return n === 1 ? base : `${base}-${n}`;
+}
 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). */
+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");
 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.
+*/
+function shownMember(member) {
+	return member.startsWith("token:") ? `service:${member.slice(6)}` : member;
+}
 const principalType = z.enum(["user", "service"]);
 const principalId = z.string().trim().min(1).max(320);
 const instanceRole = z.enum(["user", "owner"]);
 const grantId = z.string().uuid();
 const emailAddress = z.string().email().max(320);
 //#endregion
-export { displayName, emailAddress, grantId, instanceRole, principalId, principalType, secretKey, slug };
+export { TOMBSTONE, displayName, emailAddress, environmentSlug, folderName, grantId, instanceRole, isTombstone, principalId, principalType, secretKey, shownMember, slug, tombstoneOf };

package/dist/vault.d.ts

@@ -1,4 +1,4 @@
-import { Role } from "./access.js";
+import { GrantPlace, Role } from "./access.js";
 //#region src/access-fault.d.ts
 /**
  * Why the vault's members and grants do not follow from its log, as facts
@@ -48,15 +48,14 @@ type AccessFault =
   principal: string;
   why: 'mac' | 'stale';
 };
-type FaultGrant = {
+type FaultGrant = GrantPlace & {
   principal: string;
-  projectId: string;
-  environmentId: string | null;
   role: string;
 };
 /** How to name a principal (`user:ada@…`) and a place; ids by default. */
 type FaultNames = {
   principal?: (principal: string) => string;
+  /** Asked only of a project's or an environment's place: a grant on every project is named by its path. */
   place?: (projectId: string, environmentId: string | null) => string;
 };
 /** The fault in a sentence, with whatever names the caller can give. */
@@ -114,6 +113,28 @@ export interface Vault {
     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
@@ -203,8 +224,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. */
@@ -266,8 +294,8 @@ export type KeyChecks = {
     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 = {
   requestId?: string | null;
@@ -286,10 +314,45 @@ type Correlation = {
 export type UnwrapInput = Correlation & {
   principal: string;
   purpose: Purpose;
+  /**
+   * `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 & {
   principal: string;
   /** `key` is a fresh 32-byte data key, base64. */
@@ -306,10 +369,12 @@ export type RewrapInput = Correlation & {
     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;
@@ -335,10 +400,13 @@ export type Access = {
   since: string | null;
   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;
 };

package/dist/vault.js

@@ -1,3 +1,4 @@
+import { everyProjectPath, grantKind } from "./access.js";
 //#region src/checkpoint.ts
 /** What a checkpoint's signature covers: the prefix of the log up to entry `seq`, and when. */
 function checkpointMessage(checkpoint) {
@@ -23,7 +24,11 @@ async function checkpointVerifier(publicKey) {
 function describeAccessFault(fault, names = {}) {
 	const who = names.principal ?? ((principal) => principal);
 	const where = names.place ?? ((projectId, environmentId) => environmentId === null ? projectId : `${projectId}/${environmentId}`);
-	const grant = ({ principal, projectId, environmentId, role }) => `${who(principal)} as ${role} on ${where(projectId, environmentId)}`;
+	const grant = (held) => {
+		const { principal, projectId, environmentId, environmentSlug, role } = held;
+		const place = grantKind(held) === "every-project" ? everyProjectPath(environmentSlug) : where(projectId ?? "no project", environmentId);
+		return `${who(principal)} as ${role} on ${place}`;
+	};
 	switch (fault.kind) {
 		case "unadmitted-change": return `entry ${fault.seq} changes ${who(fault.principal)}, whom the log never admitted`;
 		case "unlogged-member": return `the store has ${who(fault.principal)} as a member, whom the log never admitted`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "What coffre's packages share: roles, envelopes, identity, the audit chain and the vault's contract.",
   "license": "MIT",
   "repository": {
@@ -47,6 +47,11 @@
       "types": "./dist/kek.d.ts",
       "default": "./dist/kek.js"
     },
+    "./mcp": {
+      "coffre:source": "./src/mcp.ts",
+      "types": "./dist/mcp.d.ts",
+      "default": "./dist/mcp.js"
+    },
     "./schemas": {
       "coffre:source": "./src/schemas.ts",
       "types": "./dist/schemas.d.ts",
@@ -79,7 +84,7 @@
     "@types/node": "26.1.1",
     "tsdown": "0.23.0",
     "typescript": "5.9.3",
-    "@coffre/conformance": "0.3.0"
+    "@coffre/conformance": "0.4.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/access-fault.ts

@@ -1,3 +1,5 @@
+import { everyProjectPath, grantKind, type GrantPlace } from './access.ts';
+
 /**
  * Why the vault's members and grants do not follow from its log, as facts
  * rather than a sentence. The vault knows only ids; the app knows what the
@@ -23,11 +25,12 @@ export type AccessFault =
    */
   | { kind: 'tampered-member'; principal: string; why: 'mac' | 'stale' };
 
-export type FaultGrant = { principal: string; projectId: string; environmentId: string | null; role: string };
+export type FaultGrant = GrantPlace & { principal: string; role: string };
 
 /** How to name a principal (`user:ada@…`) and a place; ids by default. */
 export type FaultNames = {
   principal?: (principal: string) => string;
+  /** Asked only of a project's or an environment's place: a grant on every project is named by its path. */
   place?: (projectId: string, environmentId: string | null) => string;
 };
 
@@ -38,8 +41,11 @@ export function describeAccessFault(fault: AccessFault, names: FaultNames = {}):
     names.place ??
     ((projectId: string, environmentId: string | null) =>
       environmentId === null ? projectId : `${projectId}/${environmentId}`);
-  const grant = ({ principal, projectId, environmentId, role }: FaultGrant) =>
-    `${who(principal)} as ${role} on ${where(projectId, environmentId)}`;
+  const grant = (held: FaultGrant) => {
+    const { principal, projectId, environmentId, environmentSlug, role } = held;
+    const place = grantKind(held) === 'every-project' ? everyProjectPath(environmentSlug) : where(projectId ?? 'no project', environmentId);
+    return `${who(principal)} as ${role} on ${place}`;
+  };
   switch (fault.kind) {
     case 'unadmitted-change':
       return `entry ${fault.seq} changes ${who(fault.principal)}, whom the log never admitted`;

package/src/access.ts

@@ -85,8 +85,51 @@ export function assignableToEnvironment(role: Role): boolean {
   );
 }
 
-/** A place a permission applies to: a project, or one of its environments. */
-export type Place = { projectId: string; environmentId?: string | null };
+/**
+ * A place a permission applies to: a project, or one of its environments,
+ * named by its slug too, which grants on every project match by. A slug
+ * not read (null) matches no grant on a slug.
+ */
+export type Place =
+  | { projectId: string; environmentId?: null }
+  | { projectId: string; environmentId: string; environmentSlug: string | null };
+
+/**
+ * Where a grant applies, by the fields it fills (`grantKind`):
+ *
+ *   market        projectId
+ *   market/dev    projectId and environmentId
+ *   *             neither: every project, the ones created later too
+ *   *, on dev     environmentSlug only: the environment of that slug in every project
+ */
+export type GrantPlace = {
+  /** The project, also of an environment's grant; null only on every project. */
+  projectId: string | null;
+  environmentId: string | null;
+  /** On every project, the one environment slug it covers; null for all of them, and on a project's grant. */
+  environmentSlug: string | null;
+};
+
+/**
+ * What a grant's fields say it is on, or null when they say nothing
+ * coherent: an environment without its project, as a grant whose
+ * environment row is gone reads, or a slug beside an id. A grant is on
+ * every project only when it names no place at all; anything else that
+ * lacks a field covers nothing.
+ */
+export function grantKind(grant: GrantPlace): 'project' | 'environment' | 'every-project' | null {
+  if (grant.environmentId !== null) return grant.projectId !== null && grant.environmentSlug === null ? 'environment' : null;
+  if (grant.projectId !== null) return grant.environmentSlug === null ? 'project' : null;
+  return 'every-project';
+}
+
+/** Every project, as a path names it. */
+export const EVERY_PROJECT = '*';
+
+/** A grant on every project as a path: `*`, or `*` and the environment slug it covers in each. */
+export function everyProjectPath(environmentSlug: string | null): string {
+  return environmentSlug === null ? EVERY_PROJECT : `${EVERY_PROJECT}/${environmentSlug}`;
+}
 
 /**
  * What someone holds: everything a permission check reads. The app builds
@@ -100,33 +143,54 @@ export type Holdings = {
   /** Root admins and active users with the instance `owner` role. */
   isOwner: boolean;
   /** Live grants only. */
-  grants: readonly { projectId: string; environmentId: string | null; role: Role }[];
+  grants: readonly (GrantPlace & { role: Role })[];
 };
 
 /**
- * Whether `holder` may do `permission` at `place`.
+ * Whether a grant at `grant` reaches `place`:
  *
- *   on a project       its project grant; owners also manage every project
- *   on an environment  its environment grant or its project's grant
+ *   market        market and each of its environments
+ *   market/dev    market/dev
+ *   *             every project and every environment
+ *   *, on dev     each environment whose slug is dev, in every project
  *
- * An environment grant never reaches up to the project: `developer` on
- * `market/prod` does not let anyone rename `market`.
+ * An environment's grant never reaches up to its project, whether it names
+ * the environment or its slug.
+ */
+export function covers(grant: GrantPlace, place: Place): boolean {
+  switch (grantKind(grant)) {
+    case 'environment':
+      return grant.projectId === place.projectId && grant.environmentId === (place.environmentId ?? null);
+    case 'project':
+      return grant.projectId === place.projectId;
+    case 'every-project':
+      return grant.environmentSlug === null || (place.environmentId != null && place.environmentSlug !== null && place.environmentSlug === grant.environmentSlug);
+    case null:
+      return false;
+  }
+}
+
+/**
+ * Whether `holder` may do `permission` at `place`: a grant that covers it
+ * gives the role's permissions there, and grants add up. Owners also manage
+ * every project. `developer` on `market/prod` does not let anyone rename
+ * `market`.
  */
 export function allows(holder: Holdings, permission: Permission, place: Place): boolean {
   if (holder.isRootAdmin) return true;
-  const environmentId = place.environmentId ?? null;
-  if (environmentId === null && holder.isOwner && PROJECT_ONLY_PERMISSIONS.includes(permission)) {
+  if (place.environmentId == null && holder.isOwner && PROJECT_ONLY_PERMISSIONS.includes(permission)) {
     return true;
   }
-  return holder.grants.some(
-    (grant) =>
-      grant.projectId === place.projectId &&
-      (grant.environmentId === null || grant.environmentId === environmentId) &&
-      roleGrants(grant.role, permission),
-  );
+  return holder.grants.some((grant) => covers(grant, place) && roleGrants(grant.role, permission));
 }
 
-/** Whether the actor may manage grants on this project. */
-export function mayManageAccess(actor: Holdings, place: Place): boolean {
-  return allows(actor, 'grant.manage', { projectId: place.projectId });
+/**
+ * Whether the actor may manage grants at this place: on a project or its
+ * environments, with `grant.manage` on the project; on every project, as an
+ * instance owner or a root admin only.
+ */
+export function mayManageAccess(actor: Holdings, place: GrantPlace): boolean {
+  const kind = grantKind(place);
+  if (kind === 'every-project') return actor.isOwner || actor.isRootAdmin;
+  return kind !== null && place.projectId !== null && allows(actor, 'grant.manage', { projectId: place.projectId });
 }

package/src/identity/auth.ts

@@ -1,4 +1,4 @@
-import { defineSignin, type SigninConfig, type WorkloadsOptions } from './signin/config.ts';
+import { defineSignin, type McpOptions, type SigninConfig, type WorkloadsOptions } from './signin/config.ts';
 import type { SigninProvider } from './signin/types.ts';
 import type { AccessVerifierConfig } from './types.ts';
 
@@ -101,6 +101,8 @@ export type SigninOptions = {
   cliSessionDays?: number;
   /** Lets CI runs sign in as services with their platform's ID token: `{}` turns it on. */
   workloads?: WorkloadsOptions;
+  /** Lets MCP clients, Claude among them, act as the people who connect them (docs/mcp.md). */
+  mcp?: McpOptions;
 };
 
 /**
@@ -125,5 +127,6 @@ function toSignin(options: SigninOptions) {
     browserSessionHours: options.browserSessionHours,
     cliSessionDays: options.cliSessionDays,
     workloads: options.workloads,
+    mcp: options.mcp,
   };
 }

package/src/identity/signin/config.ts

@@ -70,6 +70,8 @@ export type SigninConfig = {
   cliSessionDays: number;
   /** CI runs signing in as services with their platform's ID token, when on (`workloads.ts`). */
   workloads: WorkloadsConfig | null;
+  /** MCP clients acting as the people who connect them, when on (docs/design/mcp.md). */
+  mcp: McpConfig | null;
 };
 
 /**
@@ -102,6 +104,32 @@ export type WorkloadLimits = { perSource: RateLimiter; total: RateLimiter };
 
 export type WorkloadsConfig = { allowLoopback: boolean; limits: WorkloadLimits };
 
+/**
+ * MCP clients, Claude among them, acting as the people who connect them,
+ * with coffre as their OAuth authorization server (docs/design/mcp.md). Off
+ * unless the deployment turns it on.
+ */
+export type McpOptions = {
+  /**
+   * The limits every unauthenticated OAuth request passes before coffre does
+   * any work for it, one per source address and one for all together, and
+   * the one each connection's tool calls pass. On Workers, three
+   * rate-limiting bindings; on Node, `processLimits()` from
+   * `@coffre/server/node`. Required.
+   */
+  limits: McpLimits;
+  /**
+   * Lets a client's metadata document be plain HTTP on loopback: for local
+   * development and conformance. Refused unless the public URL is loopback
+   * too.
+   */
+  allowLoopbackClientsForDevelopment?: boolean;
+};
+
+export type McpLimits = { perSource: RateLimiter; perConnection: RateLimiter; total: RateLimiter };
+
+export type McpConfig = { allowLoopback: boolean; limits: McpLimits };
+
 const PROVIDER_ID = /^[a-z0-9][a-z0-9-]{0,31}$/;
 const BRANDS: readonly SigninBrand[] = ['github', 'google', 'microsoft', 'oidc'];
 
@@ -286,6 +314,7 @@ export function defineSignin(options: {
   browserSessionHours?: number;
   cliSessionDays?: number;
   workloads?: WorkloadsOptions;
+  mcp?: McpOptions;
 }): SigninConfig {
   if (options.providers.length === 0) {
     throw new Error('sign-in needs at least one provider');
@@ -306,9 +335,27 @@ export function defineSignin(options: {
     browserSessionHours: lifetime(options.browserSessionHours, 'browserSessionHours', 12, 24 * 7),
     cliSessionDays: lifetime(options.cliSessionDays, 'cliSessionDays', 30, 365),
     workloads: options.workloads === undefined ? null : workloadsConfig(options.workloads, publicOrigin(options.publicUrl)),
+    mcp: options.mcp === undefined ? null : mcpConfig(options.mcp, publicOrigin(options.publicUrl)),
   };
 }
 
+/** MCP, checked: its three limits given, each one a limiter; loopback clients only on a loopback instance. */
+function mcpConfig(options: McpOptions, publicUrl: string): McpConfig {
+  const limiter = (value: unknown) => typeof (value as RateLimiter | undefined)?.limit === 'function';
+  if (!limiter(options.limits?.perSource) || !limiter(options.limits?.perConnection) || !limiter(options.limits?.total)) {
+    throw new Error(
+      'mcp needs its limits, per source, per connection and in total: on Workers, three rate-limiting bindings; on Node, processLimits()',
+    );
+  }
+  const loopback = options.allowLoopbackClientsForDevelopment === true;
+  if (loopback && !isLoopback(new URL(publicUrl))) {
+    throw new Error(
+      `mcp.allowLoopbackClientsForDevelopment is for an instance on loopback, and ${publicUrl} is not one: turn it off`,
+    );
+  }
+  return { allowLoopback: loopback, limits: options.limits };
+}
+
 /** Workloads, checked: both limits given, each one a limiter; loopback issuers only on a loopback instance. */
 function workloadsConfig(options: WorkloadsOptions, publicUrl: string): WorkloadsConfig {
   const limiter = (value: unknown) => typeof (value as RateLimiter | undefined)?.limit === 'function';