@zackbart/connecta 0.32.0 → 0.34.0

package/dist/oauth-callback-outcome.js

@@ -11,7 +11,7 @@ const OUTCOMES = {
         status: 400,
         tone: "declined",
         heading: "Authorization was declined",
-        message: "Consent was declined at the provider, so nothing was stored. Start authorization again whenever you are ready.",
+        message: "Consent was declined, so nothing was stored. Start again when ready.",
         fix: {
             problem: "Consent for a downstream OAuth connector was declined at the provider, so no grant was stored.",
             steps: [
@@ -72,7 +72,7 @@ const OUTCOMES = {
         fix: {
             problem: "A provider returned an authorization code, but exchanging it for tokens failed.",
             steps: [
-                "Check the OAuth client credentials the connector uses — client id and secret in the deployment's environment — and that they belong to the same OAuth app that showed the consent screen.",
+                "Check the OAuth client id and secret the connector reads from the deployment's environment, and that they belong to the OAuth app that showed the consent screen.",
                 "Check that the token endpoint and redirect URI the connector uses match the provider's registration exactly.",
                 "Find the [connecta] warning for this callback in the deployment logs; it records the exchange error the page withholds.",
             ],

package/dist/operator-record.d.ts

@@ -8,7 +8,7 @@ type FailureStep = "MCP handshake" | "tools/list" | "tools/call" | "resources/re
  */
 export declare const OAUTH_ERROR_CODES: ReadonlySet<string>;
 /** Inbound denial facts, never identity text or provider diagnostics. */
-export type AuthDenialReason = "authentication_failed" | "authorization_header_invalid" | "token_type_mismatch" | "oauth_verification_failed" | "oauth_client_not_allowed" | "oauth_binding_mismatch" | "session_origin_mismatch" | "user_missing" | "email_lookup_failed" | "verified_email_invalid" | "email_domain_denied" | "gate_denied" | "gate_failed" | "default_grant_denied" | "default_grant_threw" | "pool_not_declared" | "pool_grant_denied" | "pool_grant_threw";
+export type AuthDenialReason = "authentication_failed" | "authorization_header_invalid" | "token_type_mismatch" | "oauth_verification_failed" | "oauth_client_not_allowed" | "oauth_binding_mismatch" | "session_origin_mismatch" | "user_missing" | "email_lookup_failed" | "verified_email_invalid" | "email_domain_denied" | "gate_denied" | "gate_failed" | "not_maintainer" | "pool_not_declared" | "not_pool_member";
 /**
  * Name `ctor`'s instances `label` in records and fixed text. Call once, at
  * module scope, beside the class. An error whose prototype chain reaches no
@@ -104,7 +104,7 @@ export declare function failureRecord(subject: FailureSubject, failure?: unknown
  * The events an operator log reports failures as. Closed: a new one is a
  * reviewed line here, never a string assembled at the call site.
  */
-export type FailureEvent = "negotiation cache read failed" | "negotiation cache write failed" | "connectorAccess grant is unreachable" | "call failed" | "input schema unusable; arguments are not validated" | "catalog read failed" | "catalog persistence failed" | "catalog invalidation failed" | "catalog refresh observation failed" | "catalog refresh failed; serving stale catalog" | "deferred catalog refresh failed" | "deferred catalog refresh could not attach to the runtime" | "catalog drift check failed" | "schema digest check failed; serving digested reviews as writes" | "credential shape read failed" | "credential test failed" | "credential test threw" | "session termination refused or failed; the downstream session may remain until its provider timeout" | "activity record failed" | "catalog drift record failed" | "activity read failed" | "OAuth start failed" | "OAuth disconnect failed" | "OAuth callback verifyState threw; no authorization code was exchanged" | "OAuth callback handoff could not be consumed; no authorization code was exchanged" | "MCP default endpoint request denied" | "MCP pool request denied" | "OAuth error callback consent could not be consumed; no authorization code was exchanged" | "MCP handler error" | "operator status" | "result paging unavailable" | "request failed" | "Clerk request denied" | "Clerk authentication failed";
+export type FailureEvent = "negotiation cache read failed" | "negotiation cache write failed" | "pool tool grant is unreachable" | "call failed" | "input schema unusable; arguments are not validated" | "catalog read failed" | "catalog persistence failed" | "catalog invalidation failed" | "catalog refresh observation failed" | "catalog refresh failed; serving stale catalog" | "deferred catalog refresh failed" | "deferred catalog refresh could not attach to the runtime" | "catalog drift check failed" | "schema digest check failed; serving digested reviews as writes" | "credential shape read failed" | "credential test failed" | "credential test threw" | "session termination refused or failed; the downstream session may remain until its provider timeout" | "activity record failed" | "catalog drift record failed" | "activity read failed" | "OAuth start failed" | "OAuth disconnect failed" | "OAuth callback verifyState threw; no authorization code was exchanged" | "OAuth callback handoff could not be consumed; no authorization code was exchanged" | "MCP default endpoint request denied" | "MCP pool request denied" | "MCP agent endpoint request denied" | "OAuth error callback consent could not be consumed; no authorization code was exchanged" | "MCP handler error" | "operator status" | "operator agent slots read failed" | "result paging unavailable" | "request failed" | "Clerk request denied" | "Clerk authentication failed";
 /**
  * Log one failure as `[connecta] <event>` and its record. A record
  * `failureRecord` did not build is replaced, whatever its shape, by a fixed

package/dist/operator-record.js

@@ -112,11 +112,9 @@ const AUTH_DENIAL_REASONS = new Set([
     "email_domain_denied",
     "gate_denied",
     "gate_failed",
-    "default_grant_denied",
-    "default_grant_threw",
+    "not_maintainer",
     "pool_not_declared",
-    "pool_grant_denied",
-    "pool_grant_threw",
+    "not_pool_member",
 ]);
 /** The registry's connector id grammar (src/registry.ts). */
 const CONNECTOR_ID_RE = /^[a-z0-9_-]{1,64}$/;

package/dist/operator-ui/agents.d.ts

@@ -0,0 +1,74 @@
+import type { OperatorUiContractV2 } from "./contract.js";
+import { type Notice, type RequestFailureFacts, type Tone } from "./view.js";
+/**
+ * The Tokens page's rows, computed from the slot list and contract v2 alone.
+ * Agents are declared in code: a row's only controls are its token's issue,
+ * rotate and revoke, so nothing here creates, renames or rebinds one.
+ */
+/** One declared agent's token slot, as `GET /ui/access-tokens` returns it. */
+export type AgentSlot = ({
+    name: string;
+    state: "none";
+} | {
+    name: string;
+    state: "issued";
+    issuedAt: string;
+} | {
+    name: string;
+    state: "revoked";
+    revokedAt: string;
+}) & {
+    /**
+     * The route's opaque slot revision; it changes on every slot commit (P3b,
+     * #837). A slot read without one is unresolved and never acted on.
+     */
+    revision?: string;
+};
+/** Issue and rotate are the same request; the slot's state names it. */
+export type SlotAction = "issue" | "rotate" | "revoke";
+export interface AgentRow {
+    name: string;
+    /** Pools it belongs to, from `agents[].pools`; empty when the contract does not list it. */
+    pools: string[];
+    slot: AgentSlot;
+    /**
+     * Whether `slot` comes from the live slot list. Only a live slot can be
+     * acted on: one known only from the contract may be stale, so its controls
+     * are disabled until a refresh lists it.
+     */
+    live: boolean;
+    /** Why its controls are off, or null when they work. */
+    blocked: string | null;
+    /** Its latest activity row; null is "never" (or history that is off). */
+    lastSeenAt: string | null;
+    actions: SlotAction[];
+}
+export declare function slotActions(slot: Pick<AgentSlot, "state">): SlotAction[];
+/**
+ * One agent's slot, resolved once for both what the row shows and what an
+ * action may do. The live slot list is authoritative; the contract's copy is
+ * shown only for an agent the list does not have, and is never acted on.
+ */
+export declare function resolveSlot(contract: OperatorUiContractV2 | null, slots: AgentSlot[], name: string): {
+    slot: AgentSlot;
+    live: boolean;
+} | null;
+/**
+ * One row per declared agent, in the slot list's order, then any agent only
+ * the contract lists. The contract adds pools and last seen.
+ */
+export declare function agentRows(contract: OperatorUiContractV2 | null, slots: AgentSlot[], unresolved?: readonly string[]): AgentRow[];
+export declare function slotBadge(slot: Pick<AgentSlot, "state">): {
+    label: string;
+    tone: Tone;
+};
+/** When the slot last changed, issued or revoked (its badge says which); a dash when it never has. */
+export declare function slotSince(slot: AgentSlot, format: (value: string) => string): string;
+export declare function lastSeenLabel(lastSeenAt: string | null, format: (value: string) => string): string;
+/**
+ * Why a token operation did not land, in fixed sentences keyed by status.
+ * `outcome_unknown` (503) and `aborted` (499) are failures like any other and
+ * are never retried for the operator: an unknown rotation returned no secret,
+ * and only a new, deliberate rotation produces one.
+ */
+export declare function tokenFailureNotice(action: SlotAction, name: string, facts: RequestFailureFacts, productName: string): Notice;

package/dist/operator-ui/agents.js

@@ -0,0 +1,104 @@
+import { failure } from "./view.js";
+/** Why a row's controls are disabled when its slot is not in the live list. */
+const SLOT_UNAVAILABLE = "Token state unknown. Refresh.";
+/** Why a row's controls are disabled until a fresh list read resolves its slot. */
+const SLOT_UNRESOLVED = "Refresh to continue";
+export function slotActions(slot) {
+    return slot.state === "issued" ? ["rotate", "revoke"] : ["issue"];
+}
+function contractSlot(agent) {
+    return { name: agent.name, ...agent.token };
+}
+function maintainerAgents(contract) {
+    return contract?.role === "maintainer" ? contract.agents : [];
+}
+/**
+ * One agent's slot, resolved once for both what the row shows and what an
+ * action may do. The live slot list is authoritative; the contract's copy is
+ * shown only for an agent the list does not have, and is never acted on.
+ */
+export function resolveSlot(contract, slots, name) {
+    const listed = slots.find((slot) => slot.name === name);
+    if (listed)
+        return { slot: listed, live: true };
+    const agent = maintainerAgents(contract).find((candidate) => candidate.name === name);
+    return agent ? { slot: contractSlot(agent), live: false } : null;
+}
+/**
+ * One row per declared agent, in the slot list's order, then any agent only
+ * the contract lists. The contract adds pools and last seen.
+ */
+export function agentRows(contract, slots, unresolved = []) {
+    const agents = maintainerAgents(contract);
+    const declared = new Map(agents.map((agent) => [agent.name, agent]));
+    const names = [...slots.map((slot) => slot.name), ...agents.map((agent) => agent.name)];
+    return [...new Set(names)].map((name) => {
+        const { slot, live } = resolveSlot(contract, slots, name);
+        const agent = declared.get(name);
+        return {
+            name,
+            pools: agent?.pools ?? [],
+            slot,
+            live,
+            blocked: !live ? SLOT_UNAVAILABLE : unresolved.includes(name) || !slot.revision ? SLOT_UNRESOLVED : null,
+            lastSeenAt: agent?.lastSeenAt ?? null,
+            actions: slotActions(slot),
+        };
+    });
+}
+export function slotBadge(slot) {
+    if (slot.state === "issued")
+        return { label: "Issued", tone: "ok" };
+    if (slot.state === "revoked")
+        return { label: "Revoked", tone: "warn" };
+    return { label: "No token", tone: "neutral" };
+}
+/** When the slot last changed, issued or revoked (its badge says which); a dash when it never has. */
+export function slotSince(slot, format) {
+    if (slot.state === "issued")
+        return format(slot.issuedAt);
+    if (slot.state === "revoked")
+        return format(slot.revokedAt);
+    return "—";
+}
+export function lastSeenLabel(lastSeenAt, format) {
+    return lastSeenAt ? format(lastSeenAt) : "never";
+}
+/**
+ * Why a token operation did not land, in fixed sentences keyed by status.
+ * `outcome_unknown` (503) and `aborted` (499) are failures like any other and
+ * are never retried for the operator: an unknown rotation returned no secret,
+ * and only a new, deliberate rotation produces one.
+ */
+export function tokenFailureNotice(action, name, facts, productName) {
+    if (facts.kind === "session")
+        return failure("Session ended. Sign in again.");
+    if (facts.kind === "forbidden")
+        return failure("You can't manage agent tokens.");
+    if (facts.kind === "stale") {
+        return failure(`${name}'s token changed, so nothing was sent. Try again.`);
+    }
+    if (facts.kind === "network") {
+        return failure(`Couldn't reach ${productName}. Refresh to check ${name}'s token.`);
+    }
+    if (facts.status === 503) {
+        return failure(action === "revoke"
+            ? `Revoke result unknown for ${name}. Revoke again to be sure.`
+            : `${action === "issue" ? "Issue" : "Rotate"} result unknown for ${name}. No secret came back, so rotate again.`);
+    }
+    if (facts.status === 499) {
+        return failure(action === "revoke"
+            ? `The request ended before ${name}'s revoke finished. Refresh to check its token.`
+            : `The request ended before ${name}'s token arrived. Refresh to check its token.`);
+    }
+    // The route's compare-and-swap refused it: the slot moved after the list was read.
+    if (facts.status === 409 && facts.code === "slot_changed")
+        return failure("Changed since you looked. Refresh.");
+    if (facts.status === 409)
+        return failure(`${name}'s token changed. Reload and try again.`);
+    if (facts.status === 404)
+        return failure(`${name} is no longer declared in code. Reload the page.`);
+    return action === "revoke"
+        ? failure(`Couldn't revoke ${name}'s token. Reload and try again.`)
+        : failure(`Couldn't issue a token for ${name}. Reload and try again.`);
+}