@agentproto/auth 0.1.0-alpha.0 → 0.1.1

package/dist/index.mjs

@@ -4,6 +4,9 @@ import matter from 'gray-matter';
 import { createInterface } from 'readline';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
+import { createDecipheriv, randomBytes, createCipheriv } from 'crypto';
+import { readFile, mkdir, writeFile } from 'fs/promises';
+import { dirname } from 'path';
 
 /**
  * @agentproto/auth v0.1.0-alpha
@@ -12,6 +15,7 @@ import { promisify } from 'util';
 
 var tokenStoreSpecSchema = z.object({
   keychain: z.string().min(1),
+  path: z.string().min(1).optional(),
   account: z.string().min(1).optional()
 }).strict();
 var patAuthConfigSchema = z.object({
@@ -24,9 +28,17 @@ var serviceAuthConfigSchema = z.object({
   loginHint: z.string().min(1).optional(),
   tokenStore: tokenStoreSpecSchema
 }).strict();
+var deviceCodeAuthConfigSchema = z.object({
+  flow: z.literal("device-code"),
+  clientId: z.string().min(1).optional(),
+  scope: z.string().min(1).optional(),
+  deviceLabel: z.string().min(1).optional(),
+  tokenStore: tokenStoreSpecSchema
+}).strict();
 var authConfigSchema = z.discriminatedUnion("flow", [
   patAuthConfigSchema,
-  serviceAuthConfigSchema
+  serviceAuthConfigSchema,
+  deviceCodeAuthConfigSchema
 ]);
 var installConfigSchema = z.object({
   sealKey: z.string().min(1),
@@ -37,7 +49,9 @@ var authProviderFrontmatterSchema = z.object({
   description: z.string().min(1).max(2e3),
   apiBase: z.string().url(),
   auth: authConfigSchema,
-  install: installConfigSchema.optional()
+  install: installConfigSchema.optional(),
+  // Recommended values "tunnel" | "api" | "mcp" — free-form allowed, not an enum.
+  audience: z.string().min(1).optional()
 }).strict().describe(
   "AIP-50 auth-provider manifest: how a CLI tool authenticates to an API server and (optionally) where to call the AIP-19 provision endpoints."
 );
@@ -85,6 +99,7 @@ var guildeAuthProvider = defineAuthProvider({
   id: "guilde",
   description: "Guilde AI company platform. Authenticate via a browser-approve flow \u2014 no key to paste.",
   apiBase: "https://api.guilde.work",
+  audience: "api",
   auth: {
     flow: "service-auth",
     clientId: "agentproto-cli",
@@ -184,6 +199,7 @@ var asMetaSchema = z.object({
   issuer: z.string().optional(),
   token_endpoint: z.string().optional(),
   revocation_endpoint: z.string().optional(),
+  device_authorization_endpoint: z.string().optional(),
   grant_types_supported: z.array(z.string()).optional(),
   agent_auth: z.object({
     skill: z.string().optional(),
@@ -194,12 +210,12 @@ var asMetaSchema = z.object({
     identity_assertion: z.object({ assertion_types_supported: z.array(z.string()).optional() }).loose().optional()
   }).loose().optional()
 }).loose();
-async function discoverEndpoints(apiBase, opts = {}) {
-  const base = apiBase.replace(/\/$/, "");
-  const fetchOpts = {
-    signal: opts.signal,
-    redirect: "manual"
-  };
+var hostJsonSchema = z.object({
+  device_authorization_endpoint: z.string().optional(),
+  token_endpoint: z.string().optional(),
+  revocation_endpoint: z.string().optional()
+}).loose();
+async function discoverViaPRM(base, fetchOpts, opts) {
   const prmUrl = `${base}/.well-known/oauth-protected-resource`;
   let prm;
   try {
@@ -208,19 +224,19 @@ async function discoverEndpoints(apiBase, opts = {}) {
     if (!res.ok) {
       throw new DiscoveryError(
         `PRM returned ${res.status} ${res.statusText}`,
-        apiBase
+        base
       );
     }
     prm = prmSchema.parse(await res.json());
   } catch (err) {
     if (err instanceof DiscoveryError) throw err;
-    throw new DiscoveryError(`PRM fetch failed: ${err}`, apiBase);
+    throw new DiscoveryError(`PRM fetch failed: ${err}`, base);
   }
   const authServerBase = prm.authorization_servers?.[0]?.replace(/\/$/, "");
   if (!authServerBase) {
     throw new DiscoveryError(
       "PRM missing authorization_servers[0]",
-      apiBase
+      base
     );
   }
   const asUrl = `${authServerBase}/.well-known/oauth-authorization-server`;
@@ -231,23 +247,23 @@ async function discoverEndpoints(apiBase, opts = {}) {
     if (!res.ok) {
       throw new DiscoveryError(
         `AS metadata returned ${res.status} ${res.statusText}`,
-        apiBase
+        base
       );
     }
     as = asMetaSchema.parse(await res.json());
   } catch (err) {
     if (err instanceof DiscoveryError) throw err;
-    throw new DiscoveryError(`AS metadata fetch failed: ${err}`, apiBase);
+    throw new DiscoveryError(`AS metadata fetch failed: ${err}`, base);
   }
   const tokenEndpoint = as.token_endpoint;
   const identityEndpoint = as.agent_auth?.identity_endpoint;
   if (!tokenEndpoint) {
-    throw new DiscoveryError("AS metadata missing token_endpoint", apiBase);
+    throw new DiscoveryError("AS metadata missing token_endpoint", base);
   }
   if (!identityEndpoint) {
     throw new DiscoveryError(
       "AS metadata missing agent_auth.identity_endpoint",
-      apiBase
+      base
     );
   }
   return {
@@ -258,10 +274,67 @@ async function discoverEndpoints(apiBase, opts = {}) {
     revocationEndpoint: as.revocation_endpoint,
     identityEndpoint,
     claimEndpoint: as.agent_auth?.claim_endpoint,
+    deviceAuthorizationEndpoint: as.device_authorization_endpoint,
     identityTypesSupported: as.agent_auth?.identity_types_supported ?? [],
     grantTypesSupported: as.grant_types_supported ?? []
   };
 }
+async function discoverViaHostJson(base, fetchOpts, opts) {
+  const url = `${base}/.well-known/agentproto-host.json`;
+  let doc;
+  try {
+    assertSecureUrl(url);
+    const res = await fetchWithDeadline(url, fetchOpts, opts.timeoutMs);
+    if (!res.ok) {
+      throw new DiscoveryError(
+        `agentproto-host.json returned ${res.status} ${res.statusText}`,
+        base
+      );
+    }
+    doc = hostJsonSchema.parse(await res.json());
+  } catch (err) {
+    if (err instanceof DiscoveryError) throw err;
+    throw new DiscoveryError(`agentproto-host.json fetch failed: ${err}`, base);
+  }
+  if (!doc.token_endpoint) {
+    throw new DiscoveryError(
+      "agentproto-host.json missing token_endpoint",
+      base
+    );
+  }
+  if (!doc.device_authorization_endpoint) {
+    throw new DiscoveryError(
+      "agentproto-host.json missing device_authorization_endpoint",
+      base
+    );
+  }
+  return {
+    resource: base,
+    authServerBase: base,
+    tokenEndpoint: doc.token_endpoint,
+    revocationEndpoint: doc.revocation_endpoint,
+    deviceAuthorizationEndpoint: doc.device_authorization_endpoint,
+    identityTypesSupported: [],
+    grantTypesSupported: []
+  };
+}
+async function discoverEndpoints(apiBase, opts = {}) {
+  const base = apiBase.replace(/\/$/, "");
+  const fetchOpts = {
+    signal: opts.signal,
+    redirect: "manual"
+  };
+  try {
+    return await discoverViaPRM(base, fetchOpts, opts);
+  } catch (prmErr) {
+    if (opts.signal?.aborted) throw prmErr;
+    try {
+      return await discoverViaHostJson(base, fetchOpts, opts);
+    } catch {
+      throw prmErr;
+    }
+  }
+}
 var exec = promisify(execFile);
 function assertKeychainSupported() {
   if (process.platform !== "darwin") {
@@ -307,6 +380,64 @@ async function writeKeychainToken(service, account, token) {
   ]);
 }
 
+// src/store/keychain-store.ts
+var envelopeSchema = z.object({
+  v: z.string(),
+  k: z.enum(["pat", "assertion", "oat", "daemon"]),
+  e: z.string().optional(),
+  m: z.record(z.string(), z.unknown()).optional()
+});
+var KeychainStore = class {
+  async read(ref) {
+    const account = ref.account ?? ref.path;
+    const raw = await readKeychainToken(ref.path, account);
+    if (raw === void 0) return void 0;
+    try {
+      const envelope = envelopeSchema.parse(JSON.parse(raw));
+      return {
+        value: envelope.v,
+        kind: envelope.k,
+        ...envelope.e !== void 0 ? { expiresAt: envelope.e } : {},
+        ...envelope.m !== void 0 ? { metadata: envelope.m } : {}
+      };
+    } catch {
+      return { value: raw, kind: "pat" };
+    }
+  }
+  async write(ref, cred) {
+    const account = ref.account ?? ref.path;
+    const envelope = {
+      v: cred.value,
+      k: cred.kind,
+      ...cred.expiresAt !== void 0 ? { e: cred.expiresAt } : {},
+      ...cred.metadata !== void 0 ? { m: cred.metadata } : {}
+    };
+    await writeKeychainToken(ref.path, account, JSON.stringify(envelope));
+  }
+};
+
+// src/store/resolve-ref.ts
+function resolveStoreRef(spec, server, audience) {
+  const path = spec.path ?? spec.keychain;
+  return {
+    path: audience ? `${audience}:${path}` : path,
+    account: resolveAccount(spec.account, server)
+  };
+}
+function resolveStoreRefs(spec, server, audience) {
+  const ref = resolveStoreRef(spec, server, audience);
+  const legacyRef = audience ? resolveStoreRef(spec, server) : ref;
+  return { ref, legacyRef };
+}
+async function readStoreRefWithFallback(store, ref, legacyRef) {
+  const stored = await store.read(ref);
+  if (stored) return stored;
+  if (ref.path === legacyRef.path && ref.account === legacyRef.account) {
+    return void 0;
+  }
+  return store.read(legacyRef);
+}
+
 // src/flow-engines/pat.ts
 async function promptToken(label) {
   const input = process.stdin;
@@ -377,39 +508,37 @@ var patFlowEngine = {
     if (auth.flow !== "pat") {
       throw new Error(`patFlowEngine: invoked with flow="${auth.flow}"`);
     }
-    const account = resolveAccount(auth.tokenStore.account, opts.server);
+    const store = opts.store ?? new KeychainStore();
+    const { ref, legacyRef } = resolveStoreRefs(
+      auth.tokenStore,
+      opts.server,
+      provider.audience
+    );
     if (!opts.force) {
-      const existing = await readKeychainToken(auth.tokenStore.keychain, account);
+      const existing = await readStoreRefWithFallback(store, ref, legacyRef);
       if (existing) {
-        return { accessToken: existing, tokenKind: "pat" };
+        return { accessToken: existing.value, tokenKind: "pat" };
       }
     }
     const token = await promptToken(`${provider.id} personal access token`);
     if (!token) throw new Error("no token provided");
+    await store.write(ref, { value: token, kind: "pat" });
     return { accessToken: token, tokenKind: "pat" };
   }
 };
 var execAsync = promisify(execFile);
-var CLAIM_GRANT_TYPE = "urn:workos:agent-auth:grant-type:claim";
-var JWT_BEARER_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:jwt-bearer";
-var DEFAULT_POLL_INTERVAL_S = 5;
-var identityResponseSchema = z.object({
-  registration_id: z.string(),
-  claim_token: z.string(),
-  claim: z.object({
-    user_code: z.string(),
-    verification_uri: z.string(),
-    expires_in: z.number(),
-    interval: z.number().optional()
-  }).loose()
-}).loose();
 var tokenSuccessSchema = z.object({
   access_token: z.string(),
   token_type: z.string().optional(),
   refresh_token: z.string().optional(),
   identity_assertion: z.string().optional(),
   assertion_expires_in: z.number().optional(),
-  assertion_expires: z.string().optional()
+  assertion_expires: z.string().optional(),
+  // device-code flow fields (ignored by service-auth today; see WP-2).
+  expires_in: z.number().optional(),
+  scope: z.string().optional(),
+  subject: z.string().optional(),
+  revocation_id: z.string().optional()
 }).loose();
 var tokenErrorSchema = z.object({
   error: z.string(),
@@ -423,20 +552,7 @@ async function openBrowser(url) {
   } catch {
   }
 }
-async function postJson(url, body, schema, signal) {
-  const res = await fetchWithDeadline(url, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body),
-    signal
-  });
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`POST ${url} \u2192 ${res.status}: ${text}`);
-  }
-  return schema.parse(await res.json());
-}
-async function postForm(url, params, schema, signal) {
+async function postFormOAuth(url, params, schema, signal) {
   const res = await fetchWithDeadline(url, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded" },
@@ -445,21 +561,17 @@ async function postForm(url, params, schema, signal) {
   });
   return schema.parse(await res.json());
 }
-async function pollForToken(tokenEndpoint, claimToken, clientId, intervalS, expiresIn, signal) {
-  const deadline = Date.now() + expiresIn * 1e3;
-  let pollMs = intervalS * 1e3;
+async function pollDeviceGrant(o) {
+  const deadline = Date.now() + o.expiresIn * 1e3;
+  let pollMs = o.intervalS * 1e3;
   while (Date.now() < deadline) {
-    if (signal?.aborted) throw new Error("auth cancelled");
+    if (o.signal?.aborted) throw new Error("auth cancelled");
     await new Promise((r) => setTimeout(r, pollMs));
-    const data = await postForm(
-      tokenEndpoint,
-      {
-        grant_type: CLAIM_GRANT_TYPE,
-        claim_token: claimToken,
-        client_id: clientId
-      },
+    const data = await postFormOAuth(
+      o.tokenEndpoint,
+      { grant_type: o.grantType, ...o.params },
       tokenResponseSchema,
-      signal
+      o.signal
     );
     if (!("error" in data)) return data;
     const pollErr = data.error;
@@ -479,9 +591,37 @@ async function pollForToken(tokenEndpoint, claimToken, clientId, intervalS, expi
   }
   throw new Error("auth timeout \u2014 approval window closed");
 }
+
+// src/flow-engines/service-auth.ts
+var CLAIM_GRANT_TYPE = "urn:workos:agent-auth:grant-type:claim";
+var JWT_BEARER_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+var DEFAULT_POLL_INTERVAL_S = 5;
+var identityResponseSchema = z.object({
+  registration_id: z.string(),
+  claim_token: z.string(),
+  claim: z.object({
+    user_code: z.string(),
+    verification_uri: z.string(),
+    expires_in: z.number(),
+    interval: z.number().optional()
+  }).loose()
+}).loose();
+async function postJson(url, body, schema, signal) {
+  const res = await fetchWithDeadline(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`POST ${url} \u2192 ${res.status}: ${text}`);
+  }
+  return schema.parse(await res.json());
+}
 async function exchangeAssertion(tokenEndpoint, assertion, clientId, signal) {
   try {
-    const data = await postForm(
+    const data = await postFormOAuth(
       tokenEndpoint,
       {
         grant_type: JWT_BEARER_GRANT_TYPE,
@@ -511,24 +651,27 @@ var serviceAuthFlowEngine = {
     const tokenEndpoint = discovered?.tokenEndpoint ?? `${server}/oauth/token`;
     assertSecureUrl(identityEndpoint);
     assertSecureUrl(tokenEndpoint);
-    const primarySlot = config.tokenStore.keychain;
-    const account = resolveAccount(config.tokenStore.account, server);
+    const store = opts.store ?? new KeychainStore();
+    const { ref, legacyRef } = resolveStoreRefs(
+      config.tokenStore,
+      server,
+      provider.audience
+    );
     if (!opts.force) {
-      const storedAssertion = await readKeychainToken(primarySlot, account);
-      if (storedAssertion) {
+      const stored = await readStoreRefWithFallback(store, ref, legacyRef);
+      if (stored) {
         const exchanged = await exchangeAssertion(
           tokenEndpoint,
-          storedAssertion,
+          stored.value,
           clientId,
           opts.signal
         );
         if (exchanged) {
           if (exchanged.identity_assertion) {
-            await writeKeychainToken(
-              primarySlot,
-              account,
-              exchanged.identity_assertion
-            );
+            await store.write(ref, {
+              value: exchanged.identity_assertion,
+              kind: "assertion"
+            });
           }
           return {
             accessToken: exchanged.access_token,
@@ -561,23 +704,22 @@ var serviceAuthFlowEngine = {
     process.stderr.write(`  URL:   ${claim.verification_uri}
 
 `);
-    await openBrowser(claim.verification_uri);
+    if (opts.openBrowser !== false) {
+      await openBrowser(claim.verification_uri);
+    }
     process.stderr.write(`  Waiting for approval (${windowMin} min)\u2026
 
 `);
-    const tokenResult = await pollForToken(
+    const tokenResult = await pollDeviceGrant({
       tokenEndpoint,
-      claim_token,
-      clientId,
+      grantType: CLAIM_GRANT_TYPE,
+      params: { claim_token, client_id: clientId },
       intervalS,
-      claim.expires_in,
-      opts.signal
-    );
+      expiresIn: claim.expires_in,
+      signal: opts.signal
+    });
     const accessToken = tokenResult.access_token;
     const assertion = tokenResult.identity_assertion;
-    if (assertion) {
-      await writeKeychainToken(primarySlot, account, assertion);
-    }
     let assertionExpires;
     if (tokenResult.assertion_expires) {
       assertionExpires = tokenResult.assertion_expires;
@@ -586,6 +728,13 @@ var serviceAuthFlowEngine = {
         Date.now() + tokenResult.assertion_expires_in * 1e3
       ).toISOString();
     }
+    if (assertion) {
+      await store.write(ref, {
+        value: assertion,
+        kind: "assertion",
+        ...assertionExpires ? { expiresAt: assertionExpires } : {}
+      });
+    }
     return {
       accessToken,
       identityAssertion: assertion,
@@ -594,11 +743,217 @@ var serviceAuthFlowEngine = {
     };
   }
 };
+var DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+var REFRESH_GRANT_TYPE = "refresh_token";
+var DEFAULT_POLL_INTERVAL_S2 = 5;
+var CeremonyRequiredError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CeremonyRequiredError";
+  }
+};
+var deviceAuthorizationResponseSchema = z.object({
+  device_code: z.string(),
+  user_code: z.string(),
+  verification_uri: z.string(),
+  verification_uri_complete: z.string().optional(),
+  expires_in: z.number(),
+  interval: z.number().optional()
+}).loose();
+async function postDeviceAuthorization(url, params, signal) {
+  const res = await fetchWithDeadline(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(params).toString(),
+    signal
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`POST ${url} \u2192 ${res.status}: ${text}`);
+  }
+  return deviceAuthorizationResponseSchema.parse(await res.json());
+}
+function metaString(metadata, key) {
+  const v = metadata?.[key];
+  return typeof v === "string" ? v : void 0;
+}
+function isExpired(cred) {
+  if (!cred.expiresAt) return false;
+  const t = Date.parse(cred.expiresAt);
+  if (Number.isNaN(t)) return true;
+  return t <= Date.now();
+}
+function resultFromStored(cred) {
+  const refreshToken = metaString(cred.metadata, "refreshToken");
+  const scope = metaString(cred.metadata, "scope");
+  const subject = metaString(cred.metadata, "subject");
+  const revocationId = metaString(cred.metadata, "revocationId");
+  return {
+    accessToken: cred.value,
+    tokenKind: "daemon",
+    ...refreshToken ? { refreshToken } : {},
+    ...scope ? { scope } : {},
+    ...subject ? { subject } : {},
+    ...revocationId ? { revocationId } : {}
+  };
+}
+async function refreshAccessToken(tokenEndpoint, refreshToken, clientId, signal) {
+  try {
+    const data = await postFormOAuth(
+      tokenEndpoint,
+      {
+        grant_type: REFRESH_GRANT_TYPE,
+        refresh_token: refreshToken,
+        client_id: clientId
+      },
+      tokenResponseSchema,
+      signal
+    );
+    if ("error" in data) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+async function persistAndResult(store, ref, o) {
+  const expiresAt = o.expiresIn ? new Date(Date.now() + o.expiresIn * 1e3).toISOString() : void 0;
+  const metadata = {
+    obtainedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...o.refreshToken ? { refreshToken: o.refreshToken } : {},
+    ...o.scope ? { scope: o.scope } : {},
+    ...o.subject ? { subject: o.subject } : {},
+    ...o.deviceLabel ? { deviceLabel: o.deviceLabel } : {},
+    ...o.revocationId ? { revocationId: o.revocationId } : {}
+  };
+  await store.write(ref, {
+    value: o.accessToken,
+    kind: "daemon",
+    ...expiresAt ? { expiresAt } : {},
+    metadata
+  });
+  return {
+    accessToken: o.accessToken,
+    tokenKind: "daemon",
+    ...o.refreshToken ? { refreshToken: o.refreshToken } : {},
+    ...o.scope ? { scope: o.scope } : {},
+    ...o.subject ? { subject: o.subject } : {},
+    ...o.revocationId ? { revocationId: o.revocationId } : {}
+  };
+}
+var deviceCodeFlowEngine = {
+  id: "device-code",
+  async run(provider, discovered, opts) {
+    const { auth } = provider;
+    if (auth.flow !== "device-code") {
+      throw new Error(`deviceCodeFlowEngine: invoked with flow="${auth.flow}"`);
+    }
+    const config = auth;
+    const clientId = config.clientId ?? "agentproto-cli";
+    const server = opts.server.replace(/\/$/, "");
+    const deviceAuthorizationEndpoint = discovered?.deviceAuthorizationEndpoint ?? `${server}/oauth/device`;
+    const tokenEndpoint = discovered?.tokenEndpoint ?? `${server}/oauth/token`;
+    assertSecureUrl(deviceAuthorizationEndpoint);
+    assertSecureUrl(tokenEndpoint);
+    const store = opts.store ?? new KeychainStore();
+    const { ref, legacyRef } = resolveStoreRefs(
+      config.tokenStore,
+      server,
+      provider.audience
+    );
+    async function tryRefresh(stored) {
+      const refreshToken = metaString(stored.metadata, "refreshToken");
+      if (!refreshToken) return null;
+      const refreshed = await refreshAccessToken(
+        tokenEndpoint,
+        refreshToken,
+        clientId,
+        opts.signal
+      );
+      if (!refreshed) return null;
+      return persistAndResult(store, ref, {
+        accessToken: refreshed.access_token,
+        expiresIn: refreshed.expires_in,
+        refreshToken: refreshed.refresh_token ?? refreshToken,
+        scope: refreshed.scope ?? metaString(stored.metadata, "scope"),
+        subject: refreshed.subject ?? metaString(stored.metadata, "subject"),
+        deviceLabel: config.deviceLabel ?? metaString(stored.metadata, "deviceLabel"),
+        revocationId: refreshed.revocation_id ?? metaString(stored.metadata, "revocationId")
+      });
+    }
+    if (opts.refreshOnly) {
+      const stored = await readStoreRefWithFallback(store, ref, legacyRef);
+      if (stored) {
+        if (!isExpired(stored)) {
+          return resultFromStored(stored);
+        }
+        const refreshed = await tryRefresh(stored);
+        if (refreshed) return refreshed;
+      }
+      throw new CeremonyRequiredError(
+        `${provider.id}: no fresh or refreshable device-code credential \u2014 an interactive ceremony would be required, but refreshOnly was set`
+      );
+    }
+    if (!opts.force) {
+      const stored = await readStoreRefWithFallback(store, ref, legacyRef);
+      if (stored) {
+        if (!isExpired(stored)) {
+          return resultFromStored(stored);
+        }
+        const refreshed = await tryRefresh(stored);
+        if (refreshed) return refreshed;
+      }
+    }
+    const params = { client_id: clientId };
+    if (config.scope) params.scope = config.scope;
+    if (config.deviceLabel) params.device_label = config.deviceLabel;
+    const authz = await postDeviceAuthorization(
+      deviceAuthorizationEndpoint,
+      params,
+      opts.signal
+    );
+    const intervalS = authz.interval ?? DEFAULT_POLL_INTERVAL_S2;
+    const windowMin = Math.round(authz.expires_in / 60);
+    process.stderr.write(`
+`);
+    process.stderr.write(`  Approve ${provider.id} access in your browser
+
+`);
+    process.stderr.write(`  Code:  ${authz.user_code}
+`);
+    process.stderr.write(`  URL:   ${authz.verification_uri}
+
+`);
+    if (opts.openBrowser !== false) {
+      await openBrowser(authz.verification_uri_complete ?? authz.verification_uri);
+    }
+    process.stderr.write(`  Waiting for approval (${windowMin} min)\u2026
+
+`);
+    const tokenResult = await pollDeviceGrant({
+      tokenEndpoint,
+      grantType: DEVICE_CODE_GRANT_TYPE,
+      params: { device_code: authz.device_code, client_id: clientId },
+      intervalS,
+      expiresIn: authz.expires_in,
+      signal: opts.signal
+    });
+    return persistAndResult(store, ref, {
+      accessToken: tokenResult.access_token,
+      expiresIn: tokenResult.expires_in,
+      refreshToken: tokenResult.refresh_token,
+      scope: tokenResult.scope,
+      subject: tokenResult.subject,
+      deviceLabel: config.deviceLabel,
+      revocationId: tokenResult.revocation_id
+    });
+  }
+};
 
 // src/flow-engines/index.ts
 var FLOW_ENGINES = {
   [patFlowEngine.id]: patFlowEngine,
-  [serviceAuthFlowEngine.id]: serviceAuthFlowEngine
+  [serviceAuthFlowEngine.id]: serviceAuthFlowEngine,
+  [deviceCodeFlowEngine.id]: deviceCodeFlowEngine
 };
 
 // src/run-flow.ts
@@ -611,7 +966,7 @@ async function runAuthFlow(provider, opts) {
     );
   }
   let discovered = opts.discovered !== void 0 ? opts.discovered : null;
-  if (discovered === null && flowId === "service-auth") {
+  if (discovered === null && (flowId === "service-auth" || flowId === "device-code")) {
     try {
       discovered = await discoverEndpoints(opts.server, { signal: opts.signal });
     } catch (err) {
@@ -625,10 +980,194 @@ async function runAuthFlow(provider, opts) {
   return engine.run(provider, discovered, opts);
 }
 
+// src/store/memory-store.ts
+function keyOf(ref) {
+  return `${ref.path}\0${ref.account ?? ref.path}`;
+}
+var MemoryStore = class {
+  entries = /* @__PURE__ */ new Map();
+  async read(ref) {
+    const entry = this.entries.get(keyOf(ref));
+    return entry ? { ...entry } : void 0;
+  }
+  async write(ref, cred) {
+    this.entries.set(keyOf(ref), { ...cred });
+  }
+  async delete(ref) {
+    this.entries.delete(keyOf(ref));
+  }
+};
+var ALGORITHM = "aes-256-gcm";
+var KEY_ENV_VAR = "AGENTPROTO_STORE_KEY";
+var IV_BYTES = 12;
+var sealedEntrySchema = z.object({
+  iv: z.string(),
+  tag: z.string(),
+  ciphertext: z.string()
+});
+var sealedFileSchema = z.record(z.string(), sealedEntrySchema);
+var storedCredentialSchema = z.object({
+  value: z.string(),
+  kind: z.enum(["pat", "assertion", "oat", "daemon"]),
+  expiresAt: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional()
+});
+function keyOf2(ref) {
+  return `${ref.path} ${ref.account ?? ref.path}`;
+}
+function isEnoent(err) {
+  return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+function loadKey() {
+  const raw = process.env[KEY_ENV_VAR];
+  if (!raw) {
+    throw new Error(
+      `FileStore: missing ${KEY_ENV_VAR} \u2014 set a 32-byte key (64 hex chars, or base64) to use the encrypted file store. Refusing to store credentials in plaintext.`
+    );
+  }
+  const key = /^[0-9a-fA-F]{64}$/.test(raw) ? Buffer.from(raw, "hex") : Buffer.from(raw, "base64");
+  if (key.length !== 32) {
+    throw new Error(
+      `FileStore: ${KEY_ENV_VAR} must decode to exactly 32 bytes (got ${key.length}). Provide a 64-char hex string or base64 encoding 32 bytes.`
+    );
+  }
+  return key;
+}
+function seal(key, plaintext) {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(plaintext, "utf8"),
+    cipher.final()
+  ]);
+  return {
+    iv: iv.toString("base64"),
+    tag: cipher.getAuthTag().toString("base64"),
+    ciphertext: ciphertext.toString("base64")
+  };
+}
+function unseal(key, entry) {
+  const decipher = createDecipheriv(
+    ALGORITHM,
+    key,
+    Buffer.from(entry.iv, "base64")
+  );
+  decipher.setAuthTag(Buffer.from(entry.tag, "base64"));
+  const plaintext = Buffer.concat([
+    decipher.update(Buffer.from(entry.ciphertext, "base64")),
+    decipher.final()
+  ]);
+  return plaintext.toString("utf8");
+}
+var FileStore = class {
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+  filePath;
+  async read(ref) {
+    const key = loadKey();
+    const file = await this.readFile();
+    const sealed = file[keyOf2(ref)];
+    if (!sealed) return void 0;
+    return storedCredentialSchema.parse(JSON.parse(unseal(key, sealed)));
+  }
+  async write(ref, cred) {
+    const key = loadKey();
+    const file = await this.readFile();
+    file[keyOf2(ref)] = seal(key, JSON.stringify(cred));
+    await this.writeFile(file);
+  }
+  async delete(ref) {
+    const file = await this.readFile();
+    delete file[keyOf2(ref)];
+    await this.writeFile(file);
+  }
+  async readFile() {
+    try {
+      const raw = await readFile(this.filePath, "utf8");
+      return sealedFileSchema.parse(JSON.parse(raw));
+    } catch (err) {
+      if (isEnoent(err)) return {};
+      throw err;
+    }
+  }
+  async writeFile(file) {
+    await mkdir(dirname(this.filePath), { recursive: true });
+    await writeFile(this.filePath, JSON.stringify(file, null, 2), "utf8");
+  }
+};
+
+// src/broker.ts
+var EXPIRY_SKEW_MS = 6e4;
+function parsePath(path) {
+  const slash = path.indexOf("/");
+  if (slash === -1) return { providerId: path };
+  return { providerId: path.slice(0, slash), account: path.slice(slash + 1) };
+}
+function isFresh(cred) {
+  if (!cred.expiresAt) return true;
+  const expiresAtMs = Date.parse(cred.expiresAt);
+  if (Number.isNaN(expiresAtMs)) return false;
+  return expiresAtMs - EXPIRY_SKEW_MS > Date.now();
+}
+function bearerHeaders(value, kind) {
+  if (kind === "pat" || kind === "oat" || kind === "daemon") {
+    return { Authorization: `Bearer ${value}` };
+  }
+  return void 0;
+}
+var CredentialBroker = class {
+  store;
+  getProvider;
+  constructor(opts) {
+    this.store = opts.store;
+    this.getProvider = opts.getProvider;
+  }
+  async resolveHeaders(o) {
+    const { providerId, account } = parsePath(o.path);
+    const provider = this.getProvider(providerId);
+    if (!provider) {
+      throw new Error(`CredentialBroker: unknown auth provider "${providerId}"`);
+    }
+    if (o.audience !== void 0 && provider.audience !== void 0 && o.audience !== provider.audience) {
+      throw new Error(
+        `CredentialBroker: provider "${providerId}" is scoped to audience "${provider.audience}", requested "${o.audience}"`
+      );
+    }
+    const server = o.server ?? provider.apiBase;
+    const { ref, legacyRef } = resolveStoreRefs(
+      provider.auth.tokenStore,
+      server,
+      provider.audience
+    );
+    if (account !== void 0) {
+      ref.account = account;
+      legacyRef.account = account;
+    }
+    const stored = await readStoreRefWithFallback(this.store, ref, legacyRef);
+    if (stored && isFresh(stored)) {
+      const headers2 = bearerHeaders(stored.value, stored.kind);
+      if (headers2) return headers2;
+    }
+    const result = await runAuthFlow(provider, {
+      server,
+      store: this.store,
+      signal: o.signal
+    });
+    const headers = result.accessToken !== void 0 ? bearerHeaders(result.accessToken, result.tokenKind) : void 0;
+    if (!headers) {
+      throw new Error(
+        `CredentialBroker: auth flow for "${providerId}" produced no usable access token`
+      );
+    }
+    return headers;
+  }
+};
+
 // src/index.ts
 var SPEC_NAME = "agentauth";
 var SPEC_VERSION = "v1";
 
-export { BUILTIN_AUTH_PROVIDERS, DiscoveryError, FLOW_ENGINES, SPEC_NAME, SPEC_VERSION, authConfigSchema, authProviderFrontmatterSchema, defineAuthProvider, discoverEndpoints, getAuthProvider, guildeAuthProvider, installConfigSchema, listAuthProviderIds, listAuthProviders, parseAuthProviderManifest, parseAuthProviderManifestRaw, readKeychainToken, registerAuthProvider, resolveAccount, runAuthFlow, tokenStoreSpecSchema, writeKeychainToken };
+export { BUILTIN_AUTH_PROVIDERS, CeremonyRequiredError, CredentialBroker, DiscoveryError, FLOW_ENGINES, FileStore, KeychainStore, MemoryStore, SPEC_NAME, SPEC_VERSION, authConfigSchema, authProviderFrontmatterSchema, defineAuthProvider, discoverEndpoints, getAuthProvider, guildeAuthProvider, installConfigSchema, listAuthProviderIds, listAuthProviders, parseAuthProviderManifest, parseAuthProviderManifestRaw, readKeychainToken, registerAuthProvider, resolveAccount, resolveStoreRef, runAuthFlow, tokenStoreSpecSchema, writeKeychainToken };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map