@agentproto/auth 0.1.1 → 1.0.0

package/README.md

@@ -10,7 +10,7 @@ Aligned to the WorkOS [auth.md](https://github.com/workos/auth.md) open standard
 two-hop `.well-known` discovery, the `agent_auth` metadata block, and the
 service-auth claim ceremony (`urn:workos:agent-auth:grant-type:claim`).
 
-> **Status: 0.1.0-alpha.** Two flows specified in v1 (`pat`, `service-auth`);
+> **Status: 0.2.0-alpha.** Two flows specified in v1 (`pat`, `service-auth`);
 > `id-jag` (agentproto-as-IdP) is reserved.
 
 Spec: <https://agentproto.sh/docs/aip-50> · Standard: <https://github.com/workos/auth.md>
@@ -240,6 +240,7 @@ through that structural seam. See `@agentproto/secrets`' README.
 | `runAuthFlow` | resolve → discover → dispatch |
 | `FLOW_ENGINES` | registered flow engines (`pat`, `service-auth`) |
 | `CredentialBroker` / `CredentialBrokerOptions` | path → fresh `resolveHeaders` |
+| `eligibleProfiles` | `(adapter × route) → vendor + profile eligibility predicate` |
 | `CredentialStore` / `StoreRef` / `StoredCredential` | pluggable-store interface + shapes |
 | `KeychainStore` / `MemoryStore` / `FileStore` / `resolveStoreRef` | built-in backends + ref resolver |
 | `readKeychainToken` / `writeKeychainToken` / `resolveAccount` | Keychain helpers |

package/dist/index.d.ts

@@ -443,6 +443,10 @@ declare function resolveAccount(account: string | undefined, server: string): st
 declare function readKeychainToken(service: string, account: string): Promise<string | undefined>;
 /** Write a token to the Keychain (-U updates in place). */
 declare function writeKeychainToken(service: string, account: string, token: string): Promise<void>;
+/** Remove a token from the Keychain. Returns true if an entry was deleted,
+ *  false when none existed (a delete of an absent entry is not an error —
+ *  the desired end state, "no credential at this slot", already holds). */
+declare function deleteKeychainToken(service: string, account: string): Promise<boolean>;
 
 /**
  * KeychainStore — `CredentialStore` backed by the platform Keychain.
@@ -460,6 +464,7 @@ declare function writeKeychainToken(service: string, account: string, token: str
 declare class KeychainStore implements CredentialStore {
     read(ref: StoreRef): Promise<StoredCredential | undefined>;
     write(ref: StoreRef, cred: StoredCredential): Promise<void>;
+    delete(ref: StoreRef): Promise<void>;
 }
 
 /**
@@ -540,6 +545,439 @@ declare class CredentialBroker {
     }): Promise<Record<string, string>>;
 }
 
+/**
+ * Named auth-profile types (SPEC §1c/§3.1 — `agentproto-session-config-axes`).
+ *
+ * A profile is a named credential `{ endpoint, method, credentialRef }` that
+ * lives independently of any adapter, generalizing `providers-store`'s
+ * `ProviderEntry` (one api-key per provider, `packages/providers-store/src/
+ * index.ts:68-80`) to N named profiles per billing endpoint. `subscription|api-key` is
+ * not a session property — it demotes to the `method` facet of a profile.
+ *
+ * The secret itself is NEVER inlined here — `credentialRef` is an opaque
+ * handle into this package's own credential storage (`store/types.ts`'s
+ * `CredentialStore` / `token-store.ts`), matching how the rest of
+ * `@agentproto/auth` already fingerprints rather than echoes secrets
+ * (`broker.ts`, `KeychainStore`).
+ */
+/** How a profile authenticates — the narrow eligibility gate (not adapter
+ *  identity). Mirrors `@agentproto/auth`'s `FlowResult.tokenKind`
+ *  (`types.ts:151`): `pat` → `api-key`, `oat` → `oauth-bearer`. Extensible —
+ *  new methods are additive. */
+type AuthMethod = "oauth-bearer" | "api-key";
+/** Per-profile model curation (the allowlist). `mode: "all"` (or an ABSENT
+ *  {@link AuthProfile.models}) services every model the profile is otherwise
+ *  eligible for — today's behavior. `mode: "allow"` narrows the profile to
+ *  exactly `ids`: it services a model only when the model's catalog identity
+ *  (its `vendor/product` or its route-qualified `ref`) is in the list. The
+ *  intersection is applied INSIDE the catalog eligibility join
+ *  (`catalog-models.ts`), never at the endpoint/method predicate here, so a
+ *  curated profile stays endpoint-eligible but only makes its chosen model
+ *  refs runnable. */
+interface ModelCuration {
+    mode: "all" | "allow";
+    /** Model identities allowed when `mode === "allow"` — each a catalog
+     *  `vendor/product` or route-qualified `ref`. Empty ⇒ services nothing. */
+    ids: string[];
+}
+/** Which spend surface a {@link CostBudget} caps. `"session"` bounds the
+ *  windowed spend of the ONE session the budget is evaluated against;
+ *  `"profile"` bounds the aggregate windowed spend of every session that
+ *  resolved to the same auth profile (the session's `accessProfile.profileRef`).
+ *  Additive — new scopes are back-compat. */
+type CostBudgetScope = "session" | "profile";
+/** A windowed spend cap. DISTINCT from the scalar `maxCostUsd` session-kill
+ *  (`sessions.ts` turn-end) — a `CostBudget` never kills a session; it trips a
+ *  governance policy (`policy:failed` on the completion-policy bus) when the
+ *  ROLLING windowed spend for its {@link scope} crosses `maxCostUsd`. `window`
+ *  is a rolling spec (`parseWindow` shorthand `"5h"`/`"7d"` or ISO-8601 `"P7D"`);
+ *  spend is the priced local-estimate rollup over durable usage snapshots. */
+interface CostBudget {
+    /** Windowed spend ceiling in USD. The budget trips when the window's priced
+     *  spend strictly exceeds this. */
+    maxCostUsd: number;
+    /** Rolling window spec — `parseWindow`-parseable (`"5h"`, `"7d"`, `"P7D"`). */
+    window: string;
+    /** Which spend surface the window is summed over. See {@link CostBudgetScope}. */
+    scope: CostBudgetScope;
+}
+/** A named, billing-endpoint-scoped credential reference. */
+interface AuthProfile {
+    /** Stable id, unique across all profiles (the `profileRef` a session
+     *  attaches). */
+    id: string;
+    /** Which billing endpoint this credential authenticates against
+     *  (`anthropic`, `openrouter`, `moonshot`, …). This deliberately does NOT
+     *  mean the model builder: OpenRouter can serve a z-ai model, for example.
+     *  Kept as `string` here to stay decoupled from
+     *  `@agentproto/model-catalog`, same rationale as the driver's
+     *  `AgentCliDefinition.provider`. */
+    endpoint: string;
+    /** How this profile authenticates. */
+    method: AuthMethod;
+    /** Opaque handle into this package's credential storage — NEVER the secret
+     *  itself. Resolved through `CredentialStore` / `token-store.ts` at use
+     *  time, not stored inline. Set for a credential-backed profile; absent for
+     *  a source-backed profile. Mutually exclusive with {@link source}. */
+    credentialRef?: string;
+    /** Self-refreshing credential source (`oauth-bearer` only) — same value
+     *  spawn's subscription resolution accepts (today, only
+     *  `"claude-code-oauth"`, `spawn-defaults.ts`'s `CLAUDE_CODE_OAUTH_SOURCE`).
+     *  A source-backed profile has no stored secret: the credential is resolved
+     *  fresh at spawn time instead. Mutually exclusive with
+     *  {@link credentialRef}. */
+    source?: string;
+    /** Optional human-readable name ("Jeremy Max", "work OpenRouter"). */
+    label?: string;
+    /** Whole-profile enable/disable. ABSENT (or `false`) ⇒ enabled (today's
+     *  behavior). `true` ⇒ the profile is skipped by {@link eligibleProfiles}
+     *  entirely, so every model it would otherwise service drops to
+     *  non-runnable. A REAL persisted state, distinct from the derived
+     *  `runnable` flag the catalog computes. */
+    disabled?: boolean;
+    /** Optional per-model curation (the allowlist). ABSENT ⇒ `{ mode: "all" }`
+     *  — services every eligible model, byte-identical to a profile that
+     *  predates this field. See {@link ModelCuration}. */
+    models?: ModelCuration;
+    /** Optional windowed spend cap attached to this profile (SPEC §1c). ABSENT ⇒
+     *  no profile-level budget — byte-identical to a profile that predates this
+     *  field. When present with `scope: "profile"`, a governance policy evaluates
+     *  the aggregate windowed spend of every session on this profile at each
+     *  turn-end and trips `policy:failed` on overage. Distinct from the scalar
+     *  session-kill `maxCostUsd` — see {@link CostBudget}. */
+    costBudget?: CostBudget;
+    /** Provenance: where this profile's credential was IMPORTED from, when it
+     *  was materialized by the WS6 discovery→import flow
+     *  (`auth_profile_import`) rather than created by hand. One of the discovery
+     *  origins (`claude-code`, `hermes-config`, `env`, `codex`, `gemini`). Purely
+     *  informational — it drives the panel's "imported from <origin>" badge and
+     *  nothing in the spawn/eligibility path. ABSENT for a hand-created profile.
+     *  Kept as `string` (not a union) to stay decoupled, same rationale as
+     *  {@link endpoint}. */
+    origin?: string;
+}
+
+/**
+ * Named auth-profile store — CRUD over `~/.agentproto/auth-profiles.json`
+ * (mode 0600), generalizing `providers-store`'s single-key-per-provider file
+ * (`packages/providers-store/src/index.ts:68-90`, `ProviderEntry`/
+ * `ProvidersFile`) to N named `AuthProfile`s per billing endpoint, keyed by `id`.
+ *
+ * This is the profile-metadata store, not the credential store: entries hold
+ * `credentialRef` (a pointer), never a secret, so — unlike `FileStore`
+ * (`store/file-store.ts`) — this file needs no encryption. Reuses the exact
+ * persistence primitives `providers-store` already established (a versioned
+ * JSON file under `~/.agentproto/`, `node:fs/promises`, mode 0600) rather
+ * than inventing a new format, just relocated to `@agentproto/auth` — the
+ * correct home for named profiles per SPEC §1c (`providers.json` is the
+ * degenerate one-key-per-provider case this generalizes).
+ */
+
+declare const authProfilesFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    profiles: z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodObject<{
+        id: z.ZodString;
+        vendor: z.ZodString;
+        method: z.ZodEnum<{
+            "oauth-bearer": "oauth-bearer";
+            "api-key": "api-key";
+        }>;
+        credentialRef: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+        models: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                allow: "allow";
+                all: "all";
+            }>;
+            ids: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+        costBudget: z.ZodOptional<z.ZodObject<{
+            maxCostUsd: z.ZodNumber;
+            window: z.ZodString;
+            scope: z.ZodEnum<{
+                session: "session";
+                profile: "profile";
+            }>;
+        }, z.core.$strip>>;
+        origin: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodTransform<AuthProfile, {
+        id: string;
+        vendor: string;
+        method: "oauth-bearer" | "api-key";
+        credentialRef?: string | undefined;
+        source?: string | undefined;
+        label?: string | undefined;
+        disabled?: boolean | undefined;
+        models?: {
+            mode: "allow" | "all";
+            ids: string[];
+        } | undefined;
+        costBudget?: {
+            maxCostUsd: number;
+            window: string;
+            scope: "session" | "profile";
+        } | undefined;
+        origin?: string | undefined;
+    }>>>;
+}, z.core.$strip>;
+type AuthProfilesFile = z.infer<typeof authProfilesFileSchema>;
+declare function authProfilesPath(): string;
+declare function loadAuthProfiles(): Promise<AuthProfilesFile>;
+/** List all profiles, optionally filtered to one billing endpoint. */
+declare function listAuthProfiles(endpoint?: string): Promise<AuthProfile[]>;
+/** Look up a single profile by id, or undefined if none exists. */
+declare function getAuthProfile(id: string): Promise<AuthProfile | undefined>;
+/** Add (or replace) a profile, keyed by its `id`. */
+declare function addAuthProfile(profile: AuthProfile): Promise<void>;
+/** Remove a profile by id. Returns true if it existed. */
+declare function removeAuthProfile(id: string): Promise<boolean>;
+
+/**
+ * Auth-profile provisioning — the create/delete flow the store CRUD
+ * (`profile-store.ts`) deliberately leaves out.
+ *
+ * `profile-store.ts` writes only profile *metadata* (`credentialRef`, a
+ * pointer). Provisioning is the two-sided operation nobody else owned: write
+ * the *secret* to the credential store at a derived slot, THEN record the
+ * metadata pointing at it — and, on delete, tear both down together. This is
+ * the single place that knows the `agentproto.auth.<vendor>[.<qualifier>]`
+ * keychain-slot convention (matching the entries seeded by hand in
+ * `~/.agentproto/auth-profiles.json`).
+ *
+ * The secret is INPUT-only. It is written to the `CredentialStore` and never
+ * echoed back: `createAuthProfile` returns non-secret metadata plus a
+ * one-way `fingerprint` (same "fingerprint, don't echo" discipline as
+ * `broker.ts` / `KeychainStore`), so a caller can confirm *which* credential
+ * landed without ever seeing it.
+ *
+ * Dependency-injected (`ProfileProvisionDeps`) so it's unit-testable against
+ * a `MemoryStore` + an in-memory profile map, with no keychain or filesystem.
+ */
+
+/** Input to {@link createAuthProfile}. `credential` is the raw secret — it is
+ *  written to the store and NEVER returned. Exactly one of `credential` /
+ *  `source` must be given for an `oauth-bearer` profile; `api-key` always
+ *  requires `credential` (a source-backed profile only makes sense for a
+ *  self-refreshing subscription bearer). */
+interface CreateAuthProfileInput {
+    /** Stable id, unique across all profiles. */
+    id: string;
+    /** Billing endpoint / vendor this credential authenticates against
+     *  (`anthropic`, `openrouter`, `moonshot`, …). */
+    endpoint: string;
+    /** How this profile authenticates. */
+    method: AuthMethod;
+    /** The raw secret (a subscription OAuth bearer, an API key). INPUT-ONLY.
+     *  Mutually exclusive with `source`. */
+    credential?: string;
+    /** Self-refreshing credential source (`oauth-bearer` only, e.g.
+     *  `"claude-code-oauth"`) — the profile stores no secret; the credential is
+     *  resolved fresh at spawn time instead. Mutually exclusive with
+     *  `credential`. */
+    source?: string;
+    /** Optional human-readable name. */
+    label?: string;
+    /** Optional explicit credential-store slot. Omitted ⇒ derived from
+     *  `endpoint` + `method` (see {@link deriveCredentialRef}). Ignored for a
+     *  source-backed profile (nothing is written to the credential store). */
+    credentialRef?: string;
+    /** Optional provenance — where the credential was imported from (a WS6
+     *  discovery origin). Stamped verbatim on the created profile; purely
+     *  informational. */
+    origin?: string;
+}
+/** The non-secret result of a create — safe to log, return over the wire, or
+ *  render in a UI. Carries a fingerprint, never the credential. */
+interface CreatedAuthProfile {
+    id: string;
+    endpoint: string;
+    method: AuthMethod;
+    /** Set for a credential-backed profile; absent for a source-backed one. */
+    credentialRef?: string;
+    /** Set for a source-backed profile; absent for a credential-backed one. */
+    source?: string;
+    label?: string;
+    /** Provenance stamped at import time, when given. */
+    origin?: string;
+    /** One-way fingerprint of the stored credential (sha256, truncated) — lets
+     *  a caller confirm *which* secret was stored without exposing it. Absent
+     *  for a source-backed profile — there is no stored secret to fingerprint. */
+    fingerprint?: string;
+}
+/** The result of a delete. `deleted` is false when no profile had that id
+ *  (idempotent — the desired end state already held). */
+interface DeletedAuthProfile {
+    deleted: boolean;
+    id: string;
+    /** The slot the credential lived at, when a profile was actually removed. */
+    credentialRef?: string;
+}
+/** Injectable persistence surface — production wires these to
+ *  `profile-store.ts` + a `KeychainStore`; tests pass in-memory doubles. */
+interface ProfileProvisionDeps {
+    /** Where secrets live (a `KeychainStore` in production). */
+    store: CredentialStore;
+    getProfile: (id: string) => Promise<AuthProfile | undefined>;
+    listProfiles: () => Promise<AuthProfile[]>;
+    addProfile: (profile: AuthProfile) => Promise<void>;
+    removeProfile: (id: string) => Promise<boolean>;
+}
+/** Raised when create/delete input fails validation. Distinct type so a host
+ *  (HTTP route, MCP tool) can map it to a 400 rather than a 500. */
+declare class AuthProfileValidationError extends Error {
+    constructor(message: string);
+}
+/** Normalized, validated create input — every field trimmed and checked.
+ *  Exactly one of `credential` / `source` is present. */
+interface ValidatedCreateInput {
+    id: string;
+    endpoint: string;
+    method: AuthMethod;
+    credential?: string;
+    source?: string;
+    label?: string;
+    credentialRef?: string;
+    origin?: string;
+}
+/**
+ * Validate + normalize raw create input. Pure — no I/O. Throws
+ * {@link AuthProfileValidationError} with a specific message on the first
+ * problem it finds, so the surface layer can surface a clear 400.
+ */
+declare function validateCreateInput(input: CreateAuthProfileInput): ValidatedCreateInput;
+/**
+ * Derive the credential-store slot for a profile. Matches the convention of
+ * the hand-seeded entries: `agentproto.auth.<endpoint>` for an api-key,
+ * `agentproto.auth.<endpoint>.sub` for a subscription (oauth-bearer), plus an
+ * optional `<qualifier>` to disambiguate a second profile on the same
+ * endpoint+method. Pure.
+ */
+declare function deriveCredentialRef(input: {
+    endpoint: string;
+    method: AuthMethod;
+    qualifier?: string;
+}): string;
+/** One-way fingerprint of a secret — sha256, first 12 hex chars. Enough to
+ *  distinguish credentials by eye; not reversible. */
+declare function fingerprintCredential(secret: string): string;
+/** Non-secret identity of a STORED credential — a one-way {@link
+ *  fingerprintCredential} plus the trailing 4 characters (the standard
+ *  "which key is this" affordance, like a card's last four). Neither is
+ *  reversible to the secret. `last4` is omitted for a secret too short to
+ *  reveal a tail safely (see {@link MIN_LEN_FOR_LAST4}) — fail closed rather
+ *  than expose. */
+interface CredentialIdentity {
+    fingerprint: string;
+    last4?: string;
+}
+/** Compute the non-secret {@link CredentialIdentity} of a stored secret.
+ *  Money-safety: returns ONLY the one-way fingerprint + a trailing tail —
+ *  never the secret, and never the tail when the secret is too short to
+ *  reveal one safely. */
+declare function credentialIdentity(secret: string): CredentialIdentity;
+/**
+ * Create a profile end-to-end: validate, derive the credential slot (avoiding
+ * collision with an existing profile's slot), write the secret to the store,
+ * then record the metadata. Rejects a duplicate id rather than silently
+ * overwriting. Returns non-secret metadata + a fingerprint; the credential is
+ * never echoed back.
+ */
+declare function createAuthProfile(input: CreateAuthProfileInput, deps: ProfileProvisionDeps): Promise<CreatedAuthProfile>;
+/**
+ * Delete a profile and its credential. Idempotent: a missing id returns
+ * `{ deleted: false }` rather than throwing. The keychain entry is removed
+ * only when no OTHER profile still references the same slot — two profiles
+ * can legitimately share a `credentialRef`, and dropping one must not strand
+ * the other.
+ */
+declare function deleteAuthProfile(id: string, deps: ProfileProvisionDeps): Promise<DeletedAuthProfile>;
+/**
+ * Enable or disable a whole profile (WS2). Metadata-only — never touches the
+ * credential store. Enabling CLEARS the `disabled` field entirely rather than
+ * writing `disabled: false`, so a re-enabled profile is byte-identical on
+ * disk to one that was never disabled (the ABSENT-means-enabled invariant).
+ * Throws {@link AuthProfileValidationError} for an unknown id so a host can map
+ * it to a 404/400. Returns the updated (non-secret) profile.
+ */
+declare function setAuthProfileEnabled(id: string, enabled: boolean, deps: ProfileProvisionDeps): Promise<AuthProfile>;
+/**
+ * Set a profile's per-model curation allowlist (WS3). Metadata-only. `mode:
+ * "all"` CLEARS the `models` field entirely (curation off ⇒ absent, the
+ * byte-identical "services everything" default), so only a genuine `mode:
+ * "allow"` persists a `models` object. `ids` are trimmed, de-duped, and
+ * blanks dropped. Throws {@link AuthProfileValidationError} for an unknown id.
+ * Returns the updated (non-secret) profile.
+ */
+declare function setAuthProfileModels(id: string, curation: ModelCuration, deps: ProfileProvisionDeps): Promise<AuthProfile>;
+
+/**
+ * (adapter × route) → billing-endpoint resolution + the profile eligibility predicate
+ * (SPEC §1c, `agentproto-session-config-axes/SPEC.md:102-125`).
+ *
+ *   profile eligible for (adapter, route) iff
+ *        profile.endpoint == resolveEndpoint(adapter, route).endpoint
+ *    AND profile.method  ∈ methodsPresentable(adapter, route)
+ *
+ * `route` is the endpoint selector (SPEC axis #4 — direct vs a gateway mode
+ * like `moonshot`/`openrouter`), so access is deliberately downstream of it:
+ * which endpoint (and thus which profiles) are eligible changes when route
+ * changes. `AdapterAuthManifest` is a narrow, package-local projection of
+ * exactly what this predicate needs from an adapter's real AIP-45 manifest
+ * (`packages/driver/agent-cli/src/types.ts`'s `AgentCliDefinition`) — this
+ * package intentionally does not depend on `@agentproto/driver-agent-cli`
+ * (wrong dependency direction; drivers consume auth, not vice versa), so the
+ * runtime is the one that will later project a real manifest into this
+ * shape (out of scope here — foundation only, no live spawn-path wiring).
+ *
+ * `methodsByRoute` is the static per-endpoint method table ADR'd in SPEC §3.4:
+ * "which auth methods this adapter can present for a resolved route." It is
+ * the derivable replacement for two hand-maintained artifacts SPEC §1c calls
+ * out for eventual removal — the per-adapter `authSubscription` boolean
+ * (`adapters/claude-code/src/index.ts:90-95`) and curatorial vendor deny
+ * lists (`adapters/hermes/HERMES.md:40-42`) — neither of which this PR
+ * touches; `authSubscription` stays exactly as-is (see the comment on it in
+ * `spawn-defaults.ts:345` — this module is additive, not a replacement).
+ *
+ * ACP `authenticate` is NOT a live discovery source for this table (the
+ * server handler is a stub, `packages/acp/src/server/index.ts:69`) — method
+ * discovery is this static table, not runtime negotiation (SPEC §3.7).
+ */
+
+/** A narrow, package-local projection of an adapter's declared auth
+ *  capability — enough to resolve (adapter, route) → endpoint and the auth
+ *  methods presentable on that route. Not the real AIP-45 manifest type. */
+interface AdapterAuthManifest {
+    /** Adapter id (e.g. "claude-code", "hermes"), for error messages only. */
+    id: string;
+    /** route id (e.g. "direct", or a gateway mode id like "moonshot") →
+     *  the billing endpoint used when spawned on that route. */
+    endpointByRoute: Readonly<Record<string, string>>;
+    /** route id → the auth methods this adapter can present when spawned on
+     *  that route — the method-side of the eligibility predicate. */
+    methodsByRoute: Readonly<Record<string, readonly AuthMethod[]>>;
+}
+/** Resolve which billing endpoint a given (adapter, route) pair uses. Throws
+ *  when the manifest declares no endpoint for `route` — an unresolvable route
+ *  is a caller bug (a bad/unknown route id), not a "no profiles eligible"
+ *  case, so this fails loud rather than returning an empty endpoint. */
+declare function resolveEndpoint(manifest: AdapterAuthManifest, route: string): {
+    endpoint: string;
+};
+/** Which auth methods `manifest`'s adapter can present on `route`. Empty
+ *  (never throws) when the route is declared for vendor resolution but has
+ *  no methods table entry — that's "no eligible profiles", a legitimate
+ *  eligibility outcome, not an error. */
+declare function methodsPresentable(manifest: AdapterAuthManifest, route: string): AuthMethod[];
+/** The eligibility predicate: profiles whose endpoint matches the route's
+ *  resolved endpoint AND whose method the adapter can present on that route.
+ *  A whole-profile-disabled profile (`disabled: true`) is skipped outright —
+ *  every model it would otherwise service drops to non-runnable (WS2). This is
+ *  the profile-level gate; per-model curation (`models`) is intersected
+ *  downstream in the catalog join, not here (SPEC §1c / catalog-models.ts). */
+declare function eligibleProfiles(profiles: readonly AuthProfile[], manifest: AdapterAuthManifest, route: string): AuthProfile[];
+
 /** Guilde AI company platform.
  *
  *  Authenticates via the AIP-50 service-auth claim ceremony: browser opens,
@@ -570,9 +1008,15 @@ declare const BUILTIN_AUTH_PROVIDERS: readonly AuthProviderHandle[];
  *   KeychainStore / MemoryStore / FileStore — built-in CredentialStore backends
  *   resolveStoreRef(spec, server)     — map a TokenStoreSpec to a StoreRef
  *   CredentialBroker                  — path → ready-to-use auth headers
+ *   AuthProfile / AuthMethod          — named, endpoint-scoped credential ref
+ *   listAuthProfiles/getAuthProfile/
+ *   addAuthProfile/removeAuthProfile  — named-profile store CRUD
+ *   resolveEndpoint/methodsPresentable/
+ *   eligibleProfiles                  — (adapter × route) → endpoint + the
+ *                                        profile eligibility predicate
  */
 
 declare const SPEC_NAME = "agentauth";
 declare const SPEC_VERSION = "v1";
 
-export { type AuthConfig, type AuthProviderDefinition, type AuthProviderFrontmatter, type AuthProviderHandle, type AuthProviderManifest, BUILTIN_AUTH_PROVIDERS, CeremonyRequiredError, CredentialBroker, type CredentialBrokerOptions, type CredentialStore, type DeviceCodeAuthConfig, type DiscoveredEndpoints, DiscoveryError, FLOW_ENGINES, FileStore, type FlowEngine, type FlowId, type FlowResult, type FlowRunOptions, type InstallConfig, KeychainStore, MemoryStore, type PATAuthConfig, type RunFlowOptions, SPEC_NAME, SPEC_VERSION, type ServiceAuthConfig, type StoreRef, type StoredCredential, type TokenStoreSpec, authConfigSchema, authProviderFrontmatterSchema, defineAuthProvider, discoverEndpoints, getAuthProvider, guildeAuthProvider, installConfigSchema, listAuthProviderIds, listAuthProviders, parseAuthProviderManifest, parseAuthProviderManifestRaw, readKeychainToken, registerAuthProvider, resolveAccount, resolveStoreRef, runAuthFlow, tokenStoreSpecSchema, writeKeychainToken };
+export { type AdapterAuthManifest, type AuthConfig, type AuthMethod, type AuthProfile, AuthProfileValidationError, type AuthProfilesFile, type AuthProviderDefinition, type AuthProviderFrontmatter, type AuthProviderHandle, type AuthProviderManifest, BUILTIN_AUTH_PROVIDERS, CeremonyRequiredError, type CostBudget, type CostBudgetScope, type CreateAuthProfileInput, type CreatedAuthProfile, CredentialBroker, type CredentialBrokerOptions, type CredentialIdentity, type CredentialStore, type DeletedAuthProfile, type DeviceCodeAuthConfig, type DiscoveredEndpoints, DiscoveryError, FLOW_ENGINES, FileStore, type FlowEngine, type FlowId, type FlowResult, type FlowRunOptions, type InstallConfig, KeychainStore, MemoryStore, type ModelCuration, type PATAuthConfig, type ProfileProvisionDeps, type RunFlowOptions, SPEC_NAME, SPEC_VERSION, type ServiceAuthConfig, type StoreRef, type StoredCredential, type TokenStoreSpec, type ValidatedCreateInput, addAuthProfile, authConfigSchema, authProfilesPath, authProviderFrontmatterSchema, createAuthProfile, credentialIdentity, defineAuthProvider, deleteAuthProfile, deleteKeychainToken, deriveCredentialRef, discoverEndpoints, eligibleProfiles, fingerprintCredential, getAuthProfile, getAuthProvider, guildeAuthProvider, installConfigSchema, listAuthProfiles, listAuthProviderIds, listAuthProviders, loadAuthProfiles, methodsPresentable, parseAuthProviderManifest, parseAuthProviderManifestRaw, readKeychainToken, registerAuthProvider, removeAuthProfile, resolveAccount, resolveEndpoint, resolveStoreRef, runAuthFlow, setAuthProfileEnabled, setAuthProfileModels, tokenStoreSpecSchema, validateCreateInput, writeKeychainToken };