@spacefast/common 0.0.26 → 0.2.1

package/dist/utils/credential-policy.d.ts

@@ -1,3 +1,4 @@
+import { type ApprovableScope } from "../contracts/access-profiles.js";
 import { type ApiKeyPreset, type ApiCredentialPolicy, type StatticAction } from "../contracts/api-keys.js";
 type RequestCondition = NonNullable<ApiCredentialPolicy["statements"][number]["conditions"]>;
 export type PolicyCompileInput = {
@@ -8,21 +9,64 @@ export type PolicyAuthorizeInput = {
     policy: ApiCredentialPolicy;
     action: StatticAction;
     /**
-     * Candidate resource URIs for one request target, evaluated together: spaces
-     * are addressed by their canonical site-rooted URI AND a principal-scoped
-     * candidate so principal wildcards cover them. A deny matching ANY candidate
-     * wins; otherwise an allow matching any candidate permits.
+     * Candidate URIs for one request target: a space is addressed both by its
+     * site-rooted URI and by a principal-scoped one. A deny on any candidate
+     * wins; an allow on any candidate permits.
      */
     resource: string | readonly string[];
     conditions?: RequestCondition;
 };
-export declare const publishActions: ("spaces:read" | "spaces:write" | "spaces:publish" | "builds:trigger" | "spaces:create" | "versions:read" | "versions:promote" | "versions:download" | "builds:read" | "builds:create")[];
+/**
+ * What a publishing credential may do — the same set the `publish:write` OAuth
+ * scope grants, derived from the one scope⇄action table so an API-key preset
+ * and an OAuth client of the same tier can never drift apart.
+ */
+export declare const publishActions: ("teams:read" | "teams:create" | "spaces:read" | "spaces:write" | "spaces:rename" | "domains:read" | "spaces:publish" | "builds:trigger" | "*" | "spaces:create" | "spaces:delete" | "spaces:transfer" | "spaces:export" | "spaces:import" | "spaces:policy.write" | "versions:read" | "versions:promote" | "versions:delete" | "versions:download" | "domains:create" | "domains:verify" | "domains:assign" | "domains:bind" | "domains:delete" | "domains:dns.write" | "domains:dns.credentials.write" | "domains:purchase" | "webhooks:read" | "webhooks:write" | "builds:read" | "builds:create" | "variables:read" | "variables:write" | "tenants:read" | "tenants:write" | "principals:read" | "principals:write" | "infrastructure:read" | "teams:write" | "teams:members.write" | "billing:read" | "billing:write" | "tokens:read" | "tokens:create" | "tokens:revoke" | "runtime:manage")[];
+/** The canonical policy resource for a team principal's subtree. */
+export declare function teamResource(input: PolicyCompileInput): string;
 export declare function compileApiKeyPreset(preset: ApiKeyPreset, input: PolicyCompileInput): ApiCredentialPolicy;
-/** Expand a named API-key preset into the finite permissions sent on the public wire contract. */
+/**
+ * Expand a named API-key preset into the finite permissions sent on the public
+ * wire contract. Deduplicated, because presets compose overlapping action
+ * groups and `allowPolicy` dedupes what it compiles — the wire list and the
+ * compiled statement must name the same actions.
+ */
 export declare function apiKeyPresetPermissions(preset: ApiKeyPreset): StatticAction[];
+export declare function compileTenantRootedPolicy(input: {
+    tenantId: string;
+    preset: ApiKeyPreset;
+}): ApiCredentialPolicy;
+export declare function compilePartnerPrincipalPolicy(input: {
+    tenantId: string;
+    normalizedPrincipalId: string;
+}): ApiCredentialPolicy;
 export declare function compileTeamRolePolicy(input: PolicyCompileInput & {
     role: string;
 }): ApiCredentialPolicy;
+/**
+ * The authority a membership-following key resolves to for one team: an action
+ * set bounded by the member's live role.
+ *
+ * Takes the action set rather than a preset name because a key's authority is
+ * not always its preset's CURRENT meaning. A key whose stored preset was
+ * redefined under it carries an explicit pin of the actions it was granted
+ * (`preset_actions_pin`), and that pin is what it keeps authorizing by.
+ */
+export declare function compileBoundedActionsPolicy(actions: readonly StatticAction[], input: PolicyCompileInput & {
+    role: string;
+}): ApiCredentialPolicy;
+/**
+ * Whether a person holding `role` in a team can currently exercise `scope`
+ * there. Account-plane scopes are admission the person always holds for
+ * themselves — no team role could bound them. Team-plane scopes need every
+ * action they grant inside the role's compiled policy.
+ *
+ * Informational, not a gate: approval no longer fails on role (authority is
+ * bounded live, per request, by `compileBoundedActionsPolicy`); the approval
+ * page uses this to tell the approver what a grant will actually do under
+ * their current role.
+ */
+export declare function scopeGrantableByRole(scope: ApprovableScope, role: string): boolean;
 export declare function compileBoundedPresetPolicy(preset: ApiKeyPreset, input: PolicyCompileInput & {
     role: string;
 }): ApiCredentialPolicy;

package/dist/utils/credential-policy.js

@@ -1,16 +1,12 @@
+import { SCOPE_PLANES } from "../contracts/access-profiles.js";
 import { SPACEFAST_ACCESS_POLICY_VERSION, parseStatticResource, } from "../contracts/api-keys.js";
-export const publishActions = [
-    "spaces:read",
-    "spaces:create",
-    "spaces:write",
-    "spaces:publish",
-    "versions:read",
-    "versions:promote",
-    "versions:download",
-    "builds:read",
-    "builds:trigger",
-    "builds:create",
-];
+import { oauthScopeActions, oauthScopeActionsFor } from "../contracts/oauth-scope-actions.js";
+/**
+ * What a publishing credential may do — the same set the `publish:write` OAuth
+ * scope grants, derived from the one scope⇄action table so an API-key preset
+ * and an OAuth client of the same tier can never drift apart.
+ */
+export const publishActions = oauthScopeActionsFor("publish:write");
 const spaceAdminActions = [
     ...publishActions,
     "spaces:rename",
@@ -19,22 +15,13 @@ const spaceAdminActions = [
     "spaces:export",
     "spaces:import",
     "versions:delete",
-    // Resolving the owning team (name/slug) is part of administering its spaces:
-    // the CLI resolves teams before every publish, so admin-tier presets carry
-    // read access to the team resource itself.
+    // The CLI resolves the owning team before every publish, so admin-tier
+    // presets need read access to the team resource itself.
     "teams:read",
 ];
-const domainActions = [
-    "domains:read",
-    "domains:create",
-    "domains:verify",
-    "domains:assign",
-    "domains:bind",
-    "domains:delete",
-    "domains:dns.write",
-    "domains:purchase",
-];
-function teamResource(input) {
+const domainActions = oauthScopeActionsFor("domains:write");
+/** The canonical policy resource for a team principal's subtree. */
+export function teamResource(input) {
     return `stt://tenant/${input.tenantId}/principal/team/${input.teamId}/*`;
 }
 function spaceResource(input) {
@@ -43,21 +30,29 @@ function spaceResource(input) {
 export function compileApiKeyPreset(preset, input) {
     return allowPolicy(apiKeyPresetPermissions(preset), [teamResource(input)]);
 }
-/** Expand a named API-key preset into the finite permissions sent on the public wire contract. */
+/**
+ * Expand a named API-key preset into the finite permissions sent on the public
+ * wire contract. Deduplicated, because presets compose overlapping action
+ * groups and `allowPolicy` dedupes what it compiles — the wire list and the
+ * compiled statement must name the same actions.
+ */
 export function apiKeyPresetPermissions(preset) {
+    return [...new Set(presetActions(preset))];
+}
+function presetActions(preset) {
     switch (preset) {
         case "ci_deploy":
         case "space_publisher":
-            return [...publishActions];
+            // `sf publish` resolves the owning team before it creates a Space, so a
+            // publishing key that cannot read its own team cannot publish a new one
+            // at all - the CLI's team pre-flight sees an empty list and stops before
+            // the API, which would have resolved the team from the key itself.
+            // `publishActions` stays the pure set of publish actions: claim
+            // continuation checks a team role against it.
+            return [...publishActions, "teams:read"];
         case "space_admin":
-            return [...spaceAdminActions];
-        case "site_admin":
             return [
-                "sites:read",
-                "sites:create",
-                "sites:write",
-                "sites:delete",
-                "sites:policy.write",
+                "spaces:policy.write",
                 ...spaceAdminActions,
                 ...domainActions,
                 "webhooks:read",
@@ -69,9 +64,54 @@ export function apiKeyPresetPermissions(preset) {
             return ["teams:read", "billing:read"];
         case "team_admin":
             return ["*"];
+        // The partner tier: everything a partner needs to run its own customers'
+        // spaces on our infrastructure, and nothing that mints credentials, edits
+        // team membership, or moves money.
+        case "partner_admin":
+            return [
+                "tenants:read",
+                "tenants:write",
+                "principals:read",
+                "principals:write",
+                "infrastructure:read",
+                "spaces:policy.write",
+                ...spaceAdminActions,
+                ...domainActions,
+                "webhooks:read",
+                "webhooks:write",
+                "teams:read",
+                "billing:read",
+            ];
     }
     throw new Error("Unsupported API key preset.");
 }
+// A partner credential is rooted at the tenant, not at a team principal: it
+// reaches every principal the tenant owns — teams and external customers alike —
+// and stops at the tenant boundary. `compileApiKeyPreset` stays the team-rooted
+// compiler; it needs a teamId this shape has no meaning for.
+export function compileTenantRootedPolicy(input) {
+    return allowPolicy(apiKeyPresetPermissions(input.preset), [`stt://tenant/${input.tenantId}`]);
+}
+export function compilePartnerPrincipalPolicy(input) {
+    if (input.normalizedPrincipalId.includes("*") || input.normalizedPrincipalId.includes("/")) {
+        throw new Error("Partner principal id contains a reserved policy character.");
+    }
+    return allowPolicy([
+        "spaces:read",
+        "spaces:create",
+        "spaces:write",
+        "spaces:rename",
+        "spaces:publish",
+        "versions:read",
+        "versions:promote",
+        "versions:download",
+        "builds:read",
+        "builds:trigger",
+        "builds:create",
+        "variables:read",
+        "variables:write",
+    ], [`stt://tenant/${input.tenantId}/principal/external/${input.normalizedPrincipalId}/*`]);
+}
 export function compileTeamRolePolicy(input) {
     switch (input.role) {
         case "owner":
@@ -79,7 +119,6 @@ export function compileTeamRolePolicy(input) {
             return compileApiKeyPreset("team_admin", input);
         case "member":
             return allowPolicy([
-                "sites:read",
                 "spaces:read",
                 "spaces:create",
                 "spaces:write",
@@ -99,24 +138,56 @@ export function compileTeamRolePolicy(input) {
             return denyAllPolicy();
     }
 }
-export function compileBoundedPresetPolicy(preset, input) {
-    const presetPolicy = compileApiKeyPreset(preset, input);
+/**
+ * The authority a membership-following key resolves to for one team: an action
+ * set bounded by the member's live role.
+ *
+ * Takes the action set rather than a preset name because a key's authority is
+ * not always its preset's CURRENT meaning. A key whose stored preset was
+ * redefined under it carries an explicit pin of the actions it was granted
+ * (`preset_actions_pin`), and that pin is what it keeps authorizing by.
+ */
+export function compileBoundedActionsPolicy(actions, input) {
     const rolePolicy = compileTeamRolePolicy(input);
-    const presetActions = new Set(presetPolicy.statements
-        .filter((statement) => statement.effect === "allow")
-        .flatMap((statement) => statement.actions));
+    const presetActions = new Set(actions);
     const roleActions = new Set(rolePolicy.statements
         .filter((statement) => statement.effect === "allow")
         .flatMap((statement) => statement.actions));
-    const actions = presetActions.has("*")
+    const bounded = presetActions.has("*")
         ? [...roleActions]
         : roleActions.has("*")
             ? [...presetActions]
             : [...presetActions].filter((action) => roleActions.has(action));
-    if (actions.length === 0) {
+    if (bounded.length === 0) {
         return { version: SPACEFAST_ACCESS_POLICY_VERSION, statements: [] };
     }
-    return allowPolicy(actions, [teamResource(input)]);
+    return allowPolicy(bounded, [teamResource(input)]);
+}
+/**
+ * Whether a person holding `role` in a team can currently exercise `scope`
+ * there. Account-plane scopes are admission the person always holds for
+ * themselves — no team role could bound them. Team-plane scopes need every
+ * action they grant inside the role's compiled policy.
+ *
+ * Informational, not a gate: approval no longer fails on role (authority is
+ * bounded live, per request, by `compileBoundedActionsPolicy`); the approval
+ * page uses this to tell the approver what a grant will actually do under
+ * their current role.
+ */
+export function scopeGrantableByRole(scope, role) {
+    if (SCOPE_PLANES[scope] === "account") {
+        return true;
+    }
+    const roleActions = new Set(compileTeamRolePolicy({ tenantId: "-", teamId: "-", role })
+        .statements.filter((statement) => statement.effect === "allow")
+        .flatMap((statement) => statement.actions));
+    if (roleActions.has("*")) {
+        return true;
+    }
+    return oauthScopeActions([scope]).every((action) => roleActions.has(action));
+}
+export function compileBoundedPresetPolicy(preset, input) {
+    return compileBoundedActionsPolicy(apiKeyPresetPermissions(preset), input);
 }
 export function compileSpaceContinuationPolicy(input) {
     return allowPolicy(publishActions.filter((action) => action !== "spaces:create"), [spaceResource(input)]);
@@ -189,9 +260,8 @@ export function grantedPrincipalsFromPolicy(policy, input) {
             if (!parsed || (parsed.tenantId !== input.tenantId && parsed.tenantId !== "*")) {
                 continue;
             }
-            // Tenant-rooted grants (both `stt://tenant/*` and a concrete
-            // `stt://tenant/{t}` already filtered to this tenant) are scope-wide:
-            // they reach every principal in the tenant.
+            // A tenant-rooted grant is scope-wide: `stt://tenant/*` and a concrete
+            // `stt://tenant/{t}` both reach every principal in the tenant.
             if (parsed.kind === "tenant") {
                 all = true;
             }
@@ -226,9 +296,8 @@ export function grantedPrincipalsFromPolicy(policy, input) {
         ],
     };
 }
-// Whether the policy's allow statements reach a resource subtree at all —
-// either a statement resource covers the base, or it lives inside the base.
-// This is a visibility/scoping check (404 vs 403), never an action grant.
+// Whether the policy's allow statements reach a resource subtree at all. This
+// is a visibility/scoping check (404 vs 403), never an action grant.
 export function policyReaches(policy, resourceBase) {
     return policy.statements.some((statement) => statement.effect === "allow" &&
         statement.resources.some((resource) => resourceMatches(resource, resourceBase) ||
@@ -259,10 +328,8 @@ function resourceMatches(pattern, resource) {
     if (pattern.endsWith("/*")) {
         return resource === pattern.slice(0, -2) || resource.startsWith(pattern.slice(0, -1));
     }
-    // A tenant-rooted resource is scope-wide (the platform spec:
-    // `stt://tenant/{t}` is a grantable StatticResource and resource grants cover
-    // their subtree): it covers every resource inside that tenant. This is the
-    // tenant-scoped (partner/agency) credential shape.
+    // A tenant-rooted resource covers every resource inside that tenant. This is
+    // the tenant-scoped (partner/agency) credential shape.
     if (parseStatticResource(pattern)?.kind === "tenant") {
         return resource.startsWith(`${pattern}/`);
     }
@@ -276,9 +343,8 @@ function conditionsMatch(statementConditions, contextConditions, effect, mode) {
         // SAFETY: Object.entries obtains key from the named RequestCondition object immediately above.
         const resolved = contextConditions?.[key];
         if (resolved === undefined && mode === "request") {
-            // Fail closed on unresolvable condition attributes: the condition never
-            // matches for allow statements and always matches for deny statements, so
-            // callers cannot dodge a deny by stripping request context.
+            // Fail closed: a caller cannot dodge a deny by stripping the request
+            // context its condition reads.
             return effect === "deny";
         }
         return resolved === value;

package/dist/utils/egress-policy.fixtures.json

@@ -45,7 +45,7 @@
         { "host": "sub.localhost", "allowed": false },
         { "host": "169.254.169.254", "allowed": false },
         { "host": "view.fast", "allowed": false },
-        { "host": "wpc-manage-site-123.view.fast", "allowed": false },
+        { "host": "site-123.view.fast", "allowed": false },
         { "host": "example.com", "allowed": true }
     ]
 }

package/dist/utils/generate-space-name.d.ts

@@ -1,12 +1,7 @@
 /**
- * Generates a short, readable space title.
- *
- * The pool mixes a little WordPress and web flavor with broad nature, color,
- * motion, and craft vocabulary. The result should suit any site instead of
- * reading like a CMS inside joke, while staying compact enough for a hostname.
- *
- * The generator is intentionally dependency-free so it can be shared by the
- * control-plane, dashboard, CLI, and future publishing surfaces.
+ * Short, readable space titles. Keep the pools site-neutral and short enough
+ * for a hostname. Dependency-free so the control plane, dashboard and CLI can
+ * all share it.
  */
 export declare const SPACE_TITLE_COMBINATION_COUNT: number;
 export declare function generateSpaceTitle(random?: () => number): string;

package/dist/utils/generate-space-name.js

@@ -1,12 +1,7 @@
 /**
- * Generates a short, readable space title.
- *
- * The pool mixes a little WordPress and web flavor with broad nature, color,
- * motion, and craft vocabulary. The result should suit any site instead of
- * reading like a CMS inside joke, while staying compact enough for a hostname.
- *
- * The generator is intentionally dependency-free so it can be shared by the
- * control-plane, dashboard, CLI, and future publishing surfaces.
+ * Short, readable space titles. Keep the pools site-neutral and short enough
+ * for a hostname. Dependency-free so the control plane, dashboard and CLI can
+ * all share it.
  */
 const ADJECTIVES = [
     "Atomic",

package/dist/utils/grants.d.ts

@@ -44,7 +44,6 @@ export type GrantEvaluation = {
     matches: GrantMatch[];
 };
 export declare function grantResourcePatternMatches(pattern: string, resource: string, resourceKind?: "route" | "artifact"): boolean;
-/** Does a Grant's resource set reach this path? Include, minus exclude. */
 export declare function grantResourceSetMatches(resources: Grant["resources"], resource: string, resourceKind?: "route" | "artifact"): boolean;
 export type GrantEvaluationExplanation = {
     grantId: string;

package/dist/utils/grants.js

@@ -73,12 +73,10 @@ export function grantResourcePatternMatches(pattern, resource, resourceKind = "r
     return matches(0, 0);
 }
 /**
- * Exclude patterns read wider than include patterns, and that asymmetry is the
- * rule, not an accident: the route lane collapses a terminal `index.html`
- * (normalizeAccessScopePath) while the artifact lane keeps it, so an exclude
- * naming an index artifact must also close the route that artifact serves.
- * Include never gets the same courtesy — granting the stripped route would hand
- * out access nobody wrote down. The serving engine compiles the identical pair
+ * Exclude reads wider than include, deliberately: the route lane collapses a
+ * terminal `index.html`, so an exclude naming an index artifact must also close
+ * the route it serves. Include must not, or it would grant a route nobody wrote
+ * down. The serving engine compiles the same pair
  * (access-rules.php _stattic_grant_exclude_pattern_variants).
  */
 function grantExcludePatternMatches(pattern, resource, resourceKind) {
@@ -90,7 +88,6 @@ function grantExcludePatternMatches(pattern, resource, resourceKind) {
     const stripped = canonical.slice(0, -"/index.html".length);
     return grantResourcePatternMatches(stripped === "" ? "/" : stripped, resource, resourceKind);
 }
-/** Does a Grant's resource set reach this path? Include, minus exclude. */
 export function grantResourceSetMatches(resources, resource, resourceKind = "route") {
     return (resources.include.some((pattern) => grantResourcePatternMatches(pattern, resource, resourceKind)) &&
         !resources.exclude.some((pattern) => grantExcludePatternMatches(pattern, resource, resourceKind)));

package/dist/utils/gravatar.d.ts

@@ -1,9 +1,7 @@
-/** Gravatar's canonical address form: trimmed and lowercased. */
 export declare function normalizeGravatarEmail(email: string | null | undefined): string | null;
-/** The canonical avatar URL for an already-computed SHA-256 hash. */
 export declare function gravatarUrlFromHash(hashHex: string): string;
 /**
- * SHA-256 hex of a normalized email — Gravatar's identifier. Uses WebCrypto so
- * a browser can derive it locally and never send the raw address anywhere.
+ * Gravatar's identifier, the SHA-256 hex of a normalized email. WebCrypto lets
+ * a browser derive it locally and never send the raw address anywhere.
  */
 export declare function gravatarEmailHash(email: string | null | undefined): Promise<string | null>;

package/dist/utils/gravatar.js

@@ -1,26 +1,20 @@
 /**
- * The one Gravatar URL shape Spacefast emits. Every surface — control-plane
- * profiles, the Comments SDK, Slack notifications — derives the same address
- * for the same person, so an avatar is recognizable wherever it appears and
- * Cast can validate a guest avatar against a single pattern.
- *
- * `d=404` is deliberate: a person without a Gravatar gets no image at all, and
- * the consumer renders its own initials/palette fallback instead of a stock
- * silhouette. `s=160` covers the largest avatar we render, retina included.
+ * The one Gravatar URL shape Spacefast emits, so Cast can validate a guest
+ * avatar against a single pattern. `d=404` returns no image for a person
+ * without a Gravatar, leaving the consumer's own fallback to render; `s=160`
+ * covers the largest avatar we render, retina included.
  */
 const GRAVATAR_AVATAR_QUERY = "d=404&r=g&s=160";
-/** Gravatar's canonical address form: trimmed and lowercased. */
 export function normalizeGravatarEmail(email) {
     const normalized = email?.trim().toLowerCase();
     return normalized ? normalized : null;
 }
-/** The canonical avatar URL for an already-computed SHA-256 hash. */
 export function gravatarUrlFromHash(hashHex) {
     return `https://gravatar.com/avatar/${hashHex}?${GRAVATAR_AVATAR_QUERY}`;
 }
 /**
- * SHA-256 hex of a normalized email — Gravatar's identifier. Uses WebCrypto so
- * a browser can derive it locally and never send the raw address anywhere.
+ * Gravatar's identifier, the SHA-256 hex of a normalized email. WebCrypto lets
+ * a browser derive it locally and never send the raw address anywhere.
  */
 export async function gravatarEmailHash(email) {
     const normalized = normalizeGravatarEmail(email);

package/dist/utils/id-hints.js

@@ -1,17 +1,12 @@
-// Shared not-found self-correction (W1). One source for the closest-candidate
-// ranking used by every resource's 404 hint builder (spaces, versions, teams,
-// domains). Resources differ only in which caller-scoped rows they feed in and
-// which keys they expose for matching; keeping the levenshtein/closeness/ranking
-// here prevents per-resource drift. Callers are responsible for scoping the rows
-// to the caller principal — this module never touches the DB or auth.
-// How many caller-scoped rows a hint builder will scan to rank candidates. Above
-// this the collection is treated as too large to rank for free, so the builder
-// returns only the recovery hint (no candidate ids).
+// One closest-candidate ranking for every resource's 404 hint builder (spaces,
+// versions, teams, domains). Callers scope the rows to the caller principal;
+// this module never touches the DB or auth.
+// Above this many rows the collection is too large to rank for free, and the
+// builder returns the recovery hint without candidate ids.
 export const HINT_SCAN_CAP = 200;
 export const HINT_MAX_CANDIDATES = 5;
-// All supported hint keys (ids, slugs, hostnames, and numeric version refs) fit
-// within this ceiling. Rejecting larger values keeps best-effort 404 recovery
-// from turning attacker-controlled refs or stored labels into quadratic work.
+// Every hint key (ids, slugs, hostnames, version refs) fits here. Rejecting
+// larger values keeps attacker-controlled refs out of quadratic work.
 export const HINT_MAX_KEY_LENGTH = 256;
 function boundedLevenshtein(a, b, maxDistance) {
     if (Math.abs(a.length - b.length) > maxDistance)
@@ -48,9 +43,8 @@ export function levenshtein(a, b) {
     }
     return boundedLevenshtein(a, b, Math.max(a.length, b.length));
 }
-// Returns a small finite score the closer `candidate` is to `needle`, or
-// +Infinity when they are not genuinely close. Exact match = 0; substring
-// containment = 1; otherwise a typo within a length-bounded edit distance.
+// Lower is closer, +Infinity when not close at all: exact = 0, substring
+// containment = 1, otherwise 1 + a length-bounded edit distance.
 export function refCloseness(needle, candidate) {
     if (!candidate)
         return Number.POSITIVE_INFINITY;
@@ -61,22 +55,19 @@ export function refCloseness(needle, candidate) {
         return 0;
     if (candidate.includes(needle) || needle.includes(candidate))
         return 1;
-    // Only surface genuinely close typos: bound the allowed distance by the shorter
-    // string so short refs don't match everything.
+    // Bound the distance by the shorter string so short refs don't match everything.
     const tolerance = Math.max(2, Math.floor(Math.min(needle.length, candidate.length) / 3));
     const distance = boundedLevenshtein(needle, candidate, tolerance);
     return distance <= tolerance ? 1 + distance : Number.POSITIVE_INFINITY;
 }
-// Rank `rows` by how close any of their keys are to `ref`, returning at most
-// `max` closest rows. A row whose every key is far (or absent) is dropped, so
-// only genuine near-matches surface. Ties break by the optional comparator
-// (e.g. recency); keys are matched case-insensitively.
+// Rank `rows` by their closest key to `ref`, at most `max` rows. Rows with no
+// close key are dropped. Ties break by the optional comparator; keys match
+// case-insensitively.
 export function rankCandidates(ref, rows, keysOf, options) {
     if (rows.length > HINT_SCAN_CAP || ref.length > HINT_MAX_KEY_LENGTH)
         return [];
     const needle = ref.toLowerCase();
-    // Unicode case conversion can expand a string (for example, U+0130). Keep
-    // that normalized representation under the same work ceiling too.
+    // Lowercasing can expand a string (U+0130), so re-check the ceiling.
     if (needle.length > HINT_MAX_KEY_LENGTH)
         return [];
     const max = options?.max ?? HINT_MAX_CANDIDATES;

package/dist/utils/idempotency.d.ts

@@ -1,6 +1,6 @@
 /**
- * Stable, secret-safe key for one exact logical mutation attempt. Shared by
- * every client surface: the same publish issued through the CLI and through
- * MCP must land on one key or the API stops deduplicating the retry.
+ * Stable, secret-safe key for one logical mutation attempt. The same publish
+ * from the CLI and from MCP must land on one key, or the API stops
+ * deduplicating the retry.
  */
 export declare function stableIdempotencyKey(prefix: string, parts: unknown): string;

package/dist/utils/idempotency.js

@@ -1,9 +1,8 @@
 import { createHash } from "node:crypto";
 /**
- * Key-sorted JSON that treats an absent key and an `undefined` value as the
- * same thing. Deliberately *not* `canonicalJson`: a key the CLI omits and one
- * the MCP server sets to `undefined` describe the same mutation, so they have
- * to hash alike. Merging the two spellings would change every minted key.
+ * Key-sorted JSON that treats an absent key and an `undefined` value alike: a
+ * key the CLI omits and one MCP sets to `undefined` are the same mutation.
+ * Deliberately not `canonicalJson`; merging the two would change every key.
  */
 function keyJson(value) {
     if (Array.isArray(value)) {
@@ -19,9 +18,9 @@ function keyJson(value) {
     return JSON.stringify(value ?? null);
 }
 /**
- * Stable, secret-safe key for one exact logical mutation attempt. Shared by
- * every client surface: the same publish issued through the CLI and through
- * MCP must land on one key or the API stops deduplicating the retry.
+ * Stable, secret-safe key for one logical mutation attempt. The same publish
+ * from the CLI and from MCP must land on one key, or the API stops
+ * deduplicating the retry.
  */
 export function stableIdempotencyKey(prefix, parts) {
     return `${prefix}-${createHash("sha256").update(keyJson(parts)).digest("hex")}`;