@agentproto/auth 0.1.0-alpha.0 → 0.1.1

package/dist/index.d.ts

@@ -1,5 +1,44 @@
 import { z } from 'zod';
 
+/**
+ * CredentialStore — pluggable backend for persisting AIP-50 credentials.
+ *
+ * Flow engines read/write through this interface instead of hard-coding a
+ * specific backend. `StoreRef.path` is the storage slot key — the macOS
+ * Keychain "service" name today, a Map key for `MemoryStore`, a JSON object
+ * key for `FileStore`.
+ */
+/** A persisted credential value plus the bookkeeping needed to use it again
+ *  without re-running the auth flow. */
+interface StoredCredential {
+    /** The raw credential string — a PAT, an identity assertion JWT, … */
+    value: string;
+    /** What `value` is. Mirrors `FlowResult.tokenKind`. */
+    kind: "pat" | "assertion" | "oat" | "daemon";
+    /** ISO 8601 expiry, when the credential has one. */
+    expiresAt?: string;
+    /** Backend- or flow-specific extras that don't fit `value`/`kind`/`expiresAt`. */
+    metadata?: Record<string, unknown>;
+}
+/** Where a credential lives, independent of backend. */
+interface StoreRef {
+    /** Storage slot key — a Keychain service name, a file-store map key, … */
+    path: string;
+    /** Sub-slot within `path` (a Keychain account, …). Defaults to `path`
+     *  itself when a backend needs *some* account and none was resolved. */
+    account?: string;
+}
+/** A pluggable credential backend. Flow engines depend on this interface,
+ *  never on a concrete backend — see `KeychainStore`, `MemoryStore`, `FileStore`. */
+interface CredentialStore {
+    /** Read the credential at `ref`, or `undefined` if none is stored. */
+    read(ref: StoreRef): Promise<StoredCredential | undefined>;
+    /** Write (or overwrite) the credential at `ref`. */
+    write(ref: StoreRef, cred: StoredCredential): Promise<void>;
+    /** Remove the credential at `ref`, if the backend supports deletion. */
+    delete?(ref: StoreRef): Promise<void>;
+}
+
 /**
  * AIP-50 auth-provider doctype — types.
  *
@@ -14,14 +53,19 @@ import { z } from 'zod';
  *
  * `id-jag` is reserved for a future agentproto-as-IdP scenario.
  */
+
 /** Discriminated union of all supported auth flow ids. */
-type FlowId = "pat" | "service-auth";
-/** Where a credential is stored in the platform Keychain. */
+type FlowId = "pat" | "service-auth" | "device-code";
+/** Where a credential is stored, backend-agnostic. */
 interface TokenStoreSpec {
-    /** macOS Keychain service name (or equivalent on other platforms). */
+    /** macOS Keychain service name (or equivalent on other platforms).
+     *  Back-compat alias for `path` — used when `path` is omitted. */
     keychain: string;
-    /** Keychain account. The literal `{server}` is substituted with the resolved
-     *  server URL. Defaults to the resolved server URL when omitted. */
+    /** Storage slot key, passed to `CredentialStore` as `StoreRef.path`.
+     *  Defaults to `keychain` when omitted. */
+    path?: string;
+    /** Storage account/sub-slot. The literal `{server}` is substituted with the
+     *  resolved server URL. Defaults to the resolved server URL when omitted. */
     account?: string;
 }
 /** PAT flow: read existing Keychain token or prompt for one interactively. */
@@ -44,7 +88,23 @@ interface ServiceAuthConfig {
      *  and MUST NOT be persisted; the claim_token is held in memory only. */
     tokenStore: TokenStoreSpec;
 }
-type AuthConfig = PATAuthConfig | ServiceAuthConfig;
+/** device-code flow: RFC 8628 device-authorization ceremony. Discovery
+ *  (/.well-known/) determines the actual endpoints at runtime; the static
+ *  fields here are used when discovery fails. Unlike service-auth, the stored
+ *  credential IS the durable access token (pat-class persistence), with an
+ *  optional refresh_token riding in `metadata`. */
+interface DeviceCodeAuthConfig {
+    flow: "device-code";
+    /** OAuth client id sent to the device-authorization endpoint. Default: "agentproto-cli". */
+    clientId?: string;
+    /** Optional scope requested at the device-authorization endpoint. */
+    scope?: string;
+    /** Optional human-readable label for the device, shown to the approving user. */
+    deviceLabel?: string;
+    /** Keychain destination for the durable access token. */
+    tokenStore: TokenStoreSpec;
+}
+type AuthConfig = PATAuthConfig | ServiceAuthConfig | DeviceCodeAuthConfig;
 /** AIP-19 companion: the provision endpoints on the server side. */
 interface InstallConfig {
     /** URL path for the seal-key endpoint (e.g. "/api/v1/connectors/seal-key"). */
@@ -64,6 +124,13 @@ interface AuthProviderDefinition {
     auth: AuthConfig;
     /** Optional AIP-19 provision target. */
     install?: InstallConfig;
+    /** Optional audience this provider's credentials are scoped to (recommended
+     *  values: "tunnel" | "api" | "mcp"; free-form strings are allowed). Folded
+     *  into the store key so credentials for different audiences don't collide.
+     *  This is defense-in-depth only — it is NOT a security boundary; the
+     *  normative isolation is server-side (grant-type dispatch + scope/`aud`
+     *  validation). Absent `audience` = today's behavior, unchanged. */
+    audience?: string;
 }
 type AuthProviderHandle = Readonly<AuthProviderDefinition>;
 /** Resolved endpoint set from the two-hop auth.md discovery chain. */
@@ -78,10 +145,14 @@ interface DiscoveredEndpoints {
     tokenEndpoint: string;
     /** Full revocation endpoint URL, if present. */
     revocationEndpoint?: string;
-    /** Full identity endpoint URL (POST /agent/identity). */
-    identityEndpoint: string;
+    /** Full identity endpoint URL (POST /agent/identity). Absent when discovery
+     *  resolved via the agentproto-host.json fallback, which doesn't carry
+     *  auth.md identity metadata. */
+    identityEndpoint?: string;
     /** Full claim endpoint URL (POST /agent/identity/claim), if present. */
     claimEndpoint?: string;
+    /** Full device-authorization endpoint URL (RFC 8628), if present. */
+    deviceAuthorizationEndpoint?: string;
     /** Supported identity types from agent_auth.identity_types_supported. */
     identityTypesSupported: string[];
     /** Supported grant types from AS metadata. */
@@ -99,12 +170,23 @@ interface FlowResult {
     /** ISO 8601 expiry of the identity assertion. */
     assertionExpires?: string;
     /** Access token to use for this invocation — `pat` returns the stored/typed
-     *  key; `service-auth` returns the freshly minted/refreshed `oat_*`. */
+     *  key; `service-auth` returns the freshly minted/refreshed `oat_*`;
+     *  `device-code` returns the durable `gdt_*`. */
     accessToken?: string;
     /** What `accessToken` is: `pat` (personal access key), `oat` (service-auth
-     *  access token). `assertion` is reserved for a future flow that returns a
-     *  bare assertion without an access token. */
-    tokenKind: "pat" | "assertion" | "oat";
+     *  access token), `daemon` (device-code access token). `assertion` is
+     *  reserved for a future flow that returns a bare assertion without an
+     *  access token. */
+    tokenKind: "pat" | "assertion" | "oat" | "daemon";
+    /** device-code flow: refresh token, when the AS issued one. */
+    refreshToken?: string;
+    /** device-code flow: granted scope, when the AS reports one. */
+    scope?: string;
+    /** device-code flow: subject identifier, when the AS reports one. */
+    subject?: string;
+    /** device-code flow: an id usable to revoke this credential later, when the
+     *  AS issues one. */
+    revocationId?: string;
 }
 interface FlowRunOptions {
     /** Resolved server URL for this invocation. May differ from provider.apiBase
@@ -113,6 +195,23 @@ interface FlowRunOptions {
     /** Force re-authentication even if a stored credential is found. */
     force?: boolean;
     signal?: AbortSignal;
+    /** Credential backend to read/write through. Defaults to a `KeychainStore`
+     *  when omitted — existing callers keep today's Keychain-only behavior. */
+    store?: CredentialStore;
+    /** Whether a device/claim ceremony should best-effort open the verification
+     *  URL in a browser. Default `true` (omitted = open) — existing callers are
+     *  unaffected. Set `false` for headless/remote sessions; the verification
+     *  URL and user code are still printed to stderr so the ceremony can be
+     *  completed manually. */
+    openBrowser?: boolean;
+    /** device-code flow only: attempt only the cached/refresh path (fresh
+     *  credential, or `grant_type=refresh_token` on an expired one) and NEVER
+     *  fall through to an interactive device-authorization ceremony. Throws
+     *  `CeremonyRequiredError` when no fresh or refreshable credential is
+     *  available. For callers (e.g. a headless `serve` boot) that must not
+     *  block on user interaction. Default `false` (omitted = ceremony allowed,
+     *  today's behavior). Ignored by other flows. */
+    refreshOnly?: boolean;
 }
 /** A flow engine implements one auth protocol. Dispatch by provider.auth.flow —
  *  no if/switch chains at call sites. */
@@ -142,12 +241,14 @@ declare const defineAuthProvider: (def: AuthProviderDefinition) => Readonly<Auth
 
 declare const tokenStoreSpecSchema: z.ZodObject<{
     keychain: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
     account: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 declare const authConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     flow: z.ZodLiteral<"pat">;
     tokenStore: z.ZodObject<{
         keychain: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
         account: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
@@ -156,6 +257,17 @@ declare const authConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     loginHint: z.ZodOptional<z.ZodString>;
     tokenStore: z.ZodObject<{
         keychain: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        account: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    flow: z.ZodLiteral<"device-code">;
+    clientId: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    deviceLabel: z.ZodOptional<z.ZodString>;
+    tokenStore: z.ZodObject<{
+        keychain: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
         account: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
 }, z.core.$strict>], "flow">;
@@ -171,6 +283,7 @@ declare const authProviderFrontmatterSchema: z.ZodObject<{
         flow: z.ZodLiteral<"pat">;
         tokenStore: z.ZodObject<{
             keychain: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
             account: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
@@ -179,6 +292,17 @@ declare const authProviderFrontmatterSchema: z.ZodObject<{
         loginHint: z.ZodOptional<z.ZodString>;
         tokenStore: z.ZodObject<{
             keychain: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
+            account: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        flow: z.ZodLiteral<"device-code">;
+        clientId: z.ZodOptional<z.ZodString>;
+        scope: z.ZodOptional<z.ZodString>;
+        deviceLabel: z.ZodOptional<z.ZodString>;
+        tokenStore: z.ZodObject<{
+            keychain: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
             account: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
     }, z.core.$strict>], "flow">;
@@ -186,6 +310,7 @@ declare const authProviderFrontmatterSchema: z.ZodObject<{
         sealKey: z.ZodString;
         secretBacked: z.ZodString;
     }, z.core.$strict>>;
+    audience: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 type AuthProviderFrontmatter = z.infer<typeof authProviderFrontmatterSchema>;
 
@@ -221,12 +346,18 @@ declare function listAuthProviders(): AuthProviderHandle[];
 declare function listAuthProviderIds(): string[];
 
 /**
- * Two-hop discovery per the auth.md standard (AIP-50 §Discovery algorithm).
+ * Two-hop discovery per the auth.md standard (AIP-50 §Discovery algorithm),
+ * with a second strategy for hosts that don't speak auth.md.
  *
- * Hop 1: GET {apiBase}/.well-known/oauth-protected-resource (PRM, RFC 8414)
- *   → extract authorization_servers[0] as authServerBase
- * Hop 2: GET {authServerBase}/.well-known/oauth-authorization-server (AS metadata)
- *   → extract token_endpoint + agent_auth block
+ * Strategy 1 (OAuth PRM chain):
+ *   Hop 1: GET {apiBase}/.well-known/oauth-protected-resource (PRM, RFC 8414)
+ *     → extract authorization_servers[0] as authServerBase
+ *   Hop 2: GET {authServerBase}/.well-known/oauth-authorization-server (AS metadata)
+ *     → extract token_endpoint + agent_auth block
+ *
+ * Strategy 2 (agentproto-host.json), tried when strategy 1 fails:
+ *   GET {apiBase}/.well-known/agentproto-host.json
+ *     → extract device_authorization_endpoint + token_endpoint
  *
  * Callers MUST catch DiscoveryError and fall back to static manifest config —
  * discovery failures are common (server predates auth.md) and MUST NOT prevent
@@ -271,6 +402,34 @@ declare function runAuthFlow(provider: AuthProviderHandle, opts: RunFlowOptions)
 
 declare const FLOW_ENGINES: Readonly<Record<string, FlowEngine>>;
 
+/**
+ * device-code flow engine — plain RFC 8628 device-authorization ceremony.
+ *
+ * Protocol:
+ *   POST {device_authorization_endpoint} { client_id, scope?, device_label? }
+ *     → device_code + user_code + verification_uri(_complete) + expires_in
+ *   User approves at verification_uri in browser.
+ *   Poll POST {token_endpoint} with grant_type=urn:ietf:params:oauth:grant-type:device_code
+ *     until approved / denied / expired.
+ *   On success: store the access_token as the durable credential (kind:"daemon")
+ *     — unlike service-auth, the access token IS the thing that's persisted;
+ *     refresh_token/scope/subject/revocation_id ride in `metadata`.
+ *
+ * Subsequent runs: a fresh stored credential (or one with no expiry) short-
+ * circuits the ceremony. An expired credential with a stored refresh_token is
+ * exchanged via `grant_type=refresh_token`; on failure (or when no
+ * refresh_token was stored) a new ceremony starts.
+ */
+
+/** Thrown by the device-code engine when `opts.refreshOnly` is set and no
+ *  fresh or refreshable credential is available — the only remaining path
+ *  would be an interactive ceremony, which `refreshOnly` callers explicitly
+ *  opt out of. Callers (e.g. `serve` boot on a headless host) catch this to
+ *  fall back to their own non-interactive behavior instead of hanging. */
+declare class CeremonyRequiredError extends Error {
+    constructor(message: string);
+}
+
 /**
  * Keychain helpers — read/write a token in the platform Keychain.
  *
@@ -285,6 +444,102 @@ declare function readKeychainToken(service: string, account: string): Promise<st
 /** Write a token to the Keychain (-U updates in place). */
 declare function writeKeychainToken(service: string, account: string, token: string): Promise<void>;
 
+/**
+ * KeychainStore — `CredentialStore` backed by the platform Keychain.
+ *
+ * Wraps the low-level `token-store.ts` helpers (macOS `security` CLI today).
+ * The Keychain only holds one opaque string per entry, so `kind`/`expiresAt`/
+ * `metadata` are packed into a small JSON envelope that IS that string.
+ *
+ * Back-compat: an entry written before this store existed (or by any other
+ * tool) is a bare token string, not an envelope. `read` falls back to
+ * treating the whole string as the value with kind `"pat"` — the only flow
+ * that pre-dates this store — rather than failing on non-JSON content.
+ */
+
+declare class KeychainStore implements CredentialStore {
+    read(ref: StoreRef): Promise<StoredCredential | undefined>;
+    write(ref: StoreRef, cred: StoredCredential): Promise<void>;
+}
+
+/**
+ * MemoryStore — in-process `CredentialStore` backed by a `Map`.
+ *
+ * Ephemeral: gone when the process exits. Used for tests and short-lived
+ * tooling that shouldn't touch a real backend.
+ */
+
+declare class MemoryStore implements CredentialStore {
+    private readonly entries;
+    read(ref: StoreRef): Promise<StoredCredential | undefined>;
+    write(ref: StoreRef, cred: StoredCredential): Promise<void>;
+    delete(ref: StoreRef): Promise<void>;
+}
+
+/**
+ * FileStore — encrypted-JSON-file `CredentialStore`.
+ *
+ * Every entry is sealed independently with AES-256-GCM under a key read from
+ * `AGENTPROTO_STORE_KEY` (hex or base64, 32 raw bytes). There is no plaintext
+ * fallback: a missing or malformed key throws rather than writing credentials
+ * to disk in the clear.
+ */
+
+declare class FileStore implements CredentialStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    read(ref: StoreRef): Promise<StoredCredential | undefined>;
+    write(ref: StoreRef, cred: StoredCredential): Promise<void>;
+    delete(ref: StoreRef): Promise<void>;
+    private readFile;
+    private writeFile;
+}
+
+/**
+ * Map a provider's `TokenStoreSpec` to a backend-agnostic `StoreRef`.
+ *
+ * Shared by every flow engine so the `path`/`keychain` back-compat alias and
+ * the `{server}` account template are resolved identically everywhere.
+ */
+
+/** When `audience` is declared, it's folded into the physical store key —
+ *  `${audience}:${path}` — so credentials scoped to different audiences
+ *  (e.g. "tunnel" vs "api") never collide under the same slot. Absent
+ *  `audience` = today's unprefixed path, unchanged. */
+declare function resolveStoreRef(spec: TokenStoreSpec, server: string, audience?: string): StoreRef;
+
+/**
+ * CredentialBroker — resolve ready-to-use auth headers for a `<providerId>`
+ * or `<providerId>/<account>` path, auto-refreshing via the flow engine when
+ * the stored credential is missing, expired, or not directly usable.
+ *
+ * Agent.pw-parity API: callers ask for headers by path and never touch
+ * tokens, flows, or the underlying store directly.
+ */
+
+interface CredentialBrokerOptions {
+    /** Backend to read cached credentials from and persist refreshed ones to. */
+    store: CredentialStore;
+    /** Provider lookup — pass `getAuthProvider` from the registry, or a custom
+     *  resolver (e.g. scoped to a single host's providers). */
+    getProvider: (id: string) => AuthProviderHandle | undefined;
+}
+declare class CredentialBroker {
+    private readonly store;
+    private readonly getProvider;
+    constructor(opts: CredentialBrokerOptions);
+    resolveHeaders(o: {
+        path: string;
+        server?: string;
+        signal?: AbortSignal;
+        /** Audience the caller expects this credential to be scoped to. Checked
+         *  only when the resolved provider also declares one — see the mismatch
+         *  error below. Does not itself change which store key is read; the
+         *  provider's own `audience` (not the caller's) determines that. */
+        audience?: string;
+    }): Promise<Record<string, string>>;
+}
+
 /** Guilde AI company platform.
  *
  *  Authenticates via the AIP-50 service-auth claim ceremony: browser opens,
@@ -306,12 +561,18 @@ declare const BUILTIN_AUTH_PROVIDERS: readonly AuthProviderHandle[];
  *   discoverEndpoints(apiBase)        — two-hop PRM → AS metadata discovery
  *   runAuthFlow(provider, opts)       — resolve + discover + dispatch to engine
  *   FLOW_ENGINES                      — registered flow engines (pat, …)
+ *   CeremonyRequiredError             — thrown by device-code's refreshOnly
+ *                                        mode when only an interactive
+ *                                        ceremony would satisfy the request
  *   writeKeychainToken(svc, acct, t)  — persist a credential to Keychain
  *   readKeychainToken(svc, acct)      — read a credential from Keychain
  *   resolveAccount(acct, server)      — expand {server} template
+ *   KeychainStore / MemoryStore / FileStore — built-in CredentialStore backends
+ *   resolveStoreRef(spec, server)     — map a TokenStoreSpec to a StoreRef
+ *   CredentialBroker                  — path → ready-to-use auth headers
  */
 
 declare const SPEC_NAME = "agentauth";
 declare const SPEC_VERSION = "v1";
 
-export { type AuthConfig, type AuthProviderDefinition, type AuthProviderFrontmatter, type AuthProviderHandle, type AuthProviderManifest, BUILTIN_AUTH_PROVIDERS, type DiscoveredEndpoints, DiscoveryError, FLOW_ENGINES, type FlowEngine, type FlowId, type FlowResult, type FlowRunOptions, type InstallConfig, type PATAuthConfig, type RunFlowOptions, SPEC_NAME, SPEC_VERSION, type ServiceAuthConfig, type TokenStoreSpec, authConfigSchema, authProviderFrontmatterSchema, defineAuthProvider, discoverEndpoints, getAuthProvider, guildeAuthProvider, installConfigSchema, listAuthProviderIds, listAuthProviders, parseAuthProviderManifest, parseAuthProviderManifestRaw, readKeychainToken, registerAuthProvider, resolveAccount, runAuthFlow, tokenStoreSpecSchema, writeKeychainToken };
+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 };