@pdpp/cli 0.1.0-beta.7 → 0.1.0-beta.8

package/src/owner-agent/control.js

@@ -0,0 +1,138 @@
+// Non-secret owner-agent control discovery for the `pdpp owner-agent control`
+// subcommand.
+//
+// A trusted local owner agent (Daisy/Simon-style) needs a typed, route-guess-
+// free way to answer two questions before it operates an owner's instance:
+//   1. "What owner-agent control actions does this build support?" — the
+//      bearer-authed capability document `GET /v1/owner/control`.
+//   2. "Which connection instances are configured, and which still need an
+//      owner-meaningful label?" — the bearer-authed listing
+//      `GET /v1/owner/connections`.
+//
+// Both surfaces are projected server-side from one control catalog, so this
+// module only consumes them; it never invents action families or routes. The
+// owner bearer is read from the stored credential and sent as an Authorization
+// header. It is NEVER printed: this command emits only non-secret capability
+// and connection metadata.
+
+import { OwnerAgentError } from './errors.js';
+import { getOwnerAgentAccessToken } from './lifecycle.js';
+
+/**
+ * Fetch the owner-agent control capability document and the configured
+ * connection listing, returning the non-secret subset each surface exposes.
+ * The bearer is sent as `Authorization: Bearer` and never returned.
+ *
+ * @param {object} args
+ * @param {typeof fetch} args.fetchFn
+ * @param {object} args.record  stored owner-agent credential record
+ * @returns {Promise<{ control: object, connections: object[] }>}
+ */
+export async function discoverOwnerAgentControl({ fetchFn, record }) {
+  const token = getOwnerAgentAccessToken(record);
+  if (!token) {
+    throw new OwnerAgentError('credential_invalid', 'Stored credential is missing an access token.');
+  }
+  const resource = typeof record?.resource === 'string' ? record.resource.replace(/\/$/, '') : null;
+  if (!resource) {
+    throw new OwnerAgentError(
+      'credential_invalid',
+      'Stored credential has no resource origin; re-run `pdpp owner-agent onboard`.'
+    );
+  }
+  const headers = { Accept: 'application/json', Authorization: `Bearer ${token}` };
+
+  const control = await getJson(fetchFn, `${resource}/v1/owner/control`, headers, 'control_failed');
+  const connectionsBody = await getJson(
+    fetchFn,
+    `${resource}/v1/owner/connections`,
+    headers,
+    'connections_failed'
+  );
+  const connections = Array.isArray(connectionsBody?.data) ? connectionsBody.data : [];
+  return { control, connections };
+}
+
+/**
+ * Format the control capability document and connection listing into a
+ * non-secret, token-efficient text report. Returns the string the command
+ * writes to stdout. Asserts nothing about the bearer; the caller has already
+ * ensured it is never included.
+ */
+export function formatOwnerAgentControl({ control, connections }) {
+  const lines = [];
+  lines.push('Owner-agent control capabilities (non-secret):');
+  if (control?.entrypoint) {
+    lines.push(`  entrypoint: ${control.entrypoint}`);
+  }
+  lines.push(`  /mcp owner bearer: rejected (use owner-bearer /v1/* REST, not /mcp)`);
+  lines.push('');
+  lines.push('  Action families:');
+  const actions = Array.isArray(control?.actions) ? control.actions : [];
+  for (const action of actions) {
+    const family = action?.family ?? 'unknown';
+    const status = action?.status ?? 'unknown';
+    const route = action?.method && action?.url ? `${action.method} ${action.url}` : '(owner-mediated / not a route)';
+    lines.push(`    - ${family} [${status}] ${route}`);
+    if (action?.reason) {
+      lines.push(`        ${action.reason}`);
+    }
+  }
+
+  lines.push('');
+  lines.push(`Configured connections (${connections.length}):`);
+  if (connections.length === 0) {
+    lines.push('  (none yet — initiate one with the initiate_connection action above)');
+  }
+  for (const connection of connections) {
+    const connectionId = connection?.connection_id ?? '(no connection_id)';
+    const connectorId = connection?.connector_id ?? connection?.connector_key ?? '(unknown connector)';
+    lines.push(`  - ${connectionId}  connector=${connectorId}`);
+    const label = formatLabel(connection);
+    lines.push(`      label: ${label}`);
+    if (connection?.status) {
+      lines.push(`      status: ${connection.status}`);
+    }
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+// An owner-meaningful label (`owner_set`) is printed as-is. A `fallback` label
+// is the storage-layer placeholder (e.g. a registry URL) — surface it as
+// label-needed, not as a final name, so the agent knows to rename it before
+// relying on it. Never invent a label here.
+function formatLabel(connection) {
+  const labelStatus = connection?.label_status;
+  const displayName = typeof connection?.display_name === 'string' ? connection.display_name : null;
+  if (labelStatus === 'owner_set' && displayName) {
+    return `"${displayName}" (owner_set)`;
+  }
+  if (displayName) {
+    return `label-needed (fallback: "${displayName}" — rename with rename_connection)`;
+  }
+  return 'label-needed (no display_name — rename with rename_connection)';
+}
+
+async function getJson(fetchFn, url, headers, errorCode) {
+  let response;
+  try {
+    response = await fetchFn(url, { headers });
+  } catch (error) {
+    throw new OwnerAgentError(errorCode, `Failed to fetch ${url}: ${error.message}.`);
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new OwnerAgentError(
+      'control_unauthorized',
+      `Owner-agent control is not authorized (HTTP ${response.status}). The credential may be revoked or inactive; run \`pdpp owner-agent status\`.`,
+      4
+    );
+  }
+  if (!response.ok) {
+    throw new OwnerAgentError(errorCode, `Failed to fetch ${url}: HTTP ${response.status}.`);
+  }
+  try {
+    return await response.json();
+  } catch {
+    throw new OwnerAgentError(errorCode, `Response from ${url} was not valid JSON.`);
+  }
+}

package/src/owner-agent/credential-store.js

@@ -0,0 +1,126 @@
+// Local credential target for the trusted owner-agent profile.
+//
+// Owner-agent credentials are owner-level local automation. They are written to
+// a local file with restrictive permissions and are NEVER printed to stdout,
+// stderr, logs, or dashboard status tables.
+//
+// Target resolution:
+//   - An explicit `--credential-file <path>` always wins. Daisy's first
+//     supported target is `~/applications/daisy/.pi/agent/pdpp-owner-agent.json`;
+//     the operator passes it explicitly.
+//   - Otherwise a safe default under the user home is used:
+//     `~/.pdpp/owner-agents/<host>.json`. This is intentionally rooted in the
+//     home directory, not a project-local `.pdpp/`, so an owner-level bearer is
+//     never accidentally committed alongside project files.
+
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+export const DEFAULT_OWNER_AGENT_DIR = join('.pdpp', 'owner-agents');
+
+/**
+ * Resolve the absolute credential-file path for an owner-agent credential.
+ *
+ * @param {object} args
+ * @param {string} [args.credentialFile]  explicit target (e.g. Daisy's path)
+ * @param {string} args.resource          normalized resource origin
+ * @param {string} [args.home]            home dir override (tests)
+ * @returns {string} absolute path
+ */
+export function resolveCredentialFile({ credentialFile, resource, home } = {}) {
+  const base = home ?? homedir();
+  if (credentialFile) {
+    const expanded = expandHome(credentialFile, base);
+    return isAbsolute(expanded) ? expanded : resolve(expanded);
+  }
+  const host = hostSlug(resource);
+  return join(base, DEFAULT_OWNER_AGENT_DIR, `${host}.json`);
+}
+
+/**
+ * Write owner-agent credential material to the target file with 0600 perms.
+ * Returns the absolute path written. The bearer is stored on disk only; it is
+ * the caller's responsibility never to print it.
+ *
+ * @param {string} targetPath  absolute path
+ * @param {object} payload     credential record (must include access_token)
+ * @returns {Promise<string>}
+ */
+export async function writeOwnerAgentCredential(targetPath, payload) {
+  const dir = dirname(targetPath);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  // Best-effort tighten on the directory we own; ignore EPERM on shared parents.
+  await chmod(dir, 0o700).catch(() => {});
+  await writeFile(targetPath, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+  // writeFile honors the mode only on creation; enforce 0600 if the file
+  // pre-existed with looser perms.
+  await chmod(targetPath, 0o600).catch(() => {});
+  return targetPath;
+}
+
+/**
+ * Build the on-disk credential record. Includes the bearer (for the agent to
+ * use) plus non-secret metadata for status/introspection/revocation.
+ */
+export function buildCredentialRecord({
+  resource,
+  authorizationServer,
+  credential,
+  clientId,
+  introspectionEndpoint,
+  registrationEndpoint,
+  registrationClientUri,
+  schemaCompactEndpoint,
+  schemaEndpoint,
+  streamsEndpoint,
+  createdAt,
+}) {
+  const tokenType = credential.token_type ?? 'Bearer';
+  const expiresAt = credential.expires_at ?? null;
+  const scope = credential.scope ?? null;
+  return {
+    profile: 'trusted_owner_agent',
+    pdpp_token_kind: 'owner',
+    resource,
+    authorization_server: authorizationServer ?? null,
+    client_id: clientId ?? null,
+    introspection_endpoint: introspectionEndpoint ?? null,
+    schema_endpoint: schemaEndpoint ?? null,
+    schema_compact_endpoint: schemaCompactEndpoint ?? null,
+    streams_endpoint: streamsEndpoint ?? null,
+    // RFC 7592 client-delete revocation handle, when the credential was bound
+    // to a dynamically registered client. The reference implementation gates
+    // DELETE with an owner session, not a registration access token.
+    registration_client_uri: registrationClientUri ?? credential.registration_client_uri ?? null,
+    registration_endpoint: registrationEndpoint ?? null,
+    access_token: credential.access_token,
+    token_type: tokenType,
+    expires_at: expiresAt,
+    scope,
+    // Backward-compatible nested credential block for callers that adopted the
+    // first CLI preview. Daisy and the owner-agent runbook read the top-level
+    // access_token.
+    credential: {
+      access_token: credential.access_token,
+      token_type: tokenType,
+      expires_at: expiresAt,
+      scope,
+    },
+    created_at: createdAt,
+  };
+}
+
+function expandHome(p, base) {
+  if (p === '~') return base;
+  if (p.startsWith('~/')) return join(base, p.slice(2));
+  return p;
+}
+
+function hostSlug(resource) {
+  try {
+    return new URL(resource).host.replace(/[^a-zA-Z0-9.-]/g, '_');
+  } catch {
+    return 'owner-agent';
+  }
+}

package/src/owner-agent/device-flow.js

@@ -0,0 +1,145 @@
+// RFC 8628 device-authorization handling for the trusted owner-agent flow.
+//
+// The owner approves in a browser; the CLI prints only the verification URL,
+// the user code, and non-secret polling status. The bearer returned by the
+// token endpoint is NEVER printed here — it is returned to the caller for
+// non-printing storage.
+
+import { OwnerAgentError } from './errors.js';
+
+const DEVICE_CODE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+const DEFAULT_POLL_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Initiate device authorization. Returns the public RFC 8628 envelope.
+ */
+export async function initiateDeviceAuthorization({ fetchFn, endpoint, clientId }) {
+  const body = new URLSearchParams();
+  if (clientId) {
+    body.set('client_id', clientId);
+  }
+  const result = await postForm(fetchFn, endpoint, body);
+  const verificationUri = result.verification_uri_complete ?? result.verification_uri;
+  if (!result.device_code || !verificationUri) {
+    throw new OwnerAgentError(
+      'device_authorization_invalid',
+      'Device authorization response did not include a device_code and verification URI.'
+    );
+  }
+  return {
+    deviceCode: result.device_code,
+    userCode: result.user_code ?? null,
+    verificationUri,
+    verificationUriComplete: result.verification_uri_complete ?? null,
+    intervalMs: Number.isFinite(Number(result.interval)) ? Number(result.interval) * 1000 : DEFAULT_POLL_INTERVAL_MS,
+    expiresInMs: Number.isFinite(Number(result.expires_in)) ? Number(result.expires_in) * 1000 : DEFAULT_POLL_TIMEOUT_MS,
+  };
+}
+
+/**
+ * Poll the token endpoint until the owner approves, denies, or it expires.
+ * Honors RFC 8628 `authorization_pending` / `slow_down` / `access_denied` /
+ * `expired_token`.
+ */
+export async function pollForOwnerAgentToken({
+  fetchFn,
+  endpoint,
+  clientId,
+  deviceCode,
+  intervalMs = DEFAULT_POLL_INTERVAL_MS,
+  timeoutMs = DEFAULT_POLL_TIMEOUT_MS,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  now = () => Date.now(),
+  onPending,
+}) {
+  const startedAt = now();
+  let currentInterval = intervalMs;
+
+  while (now() - startedAt <= timeoutMs) {
+    const body = new URLSearchParams();
+    body.set('grant_type', DEVICE_CODE_GRANT_TYPE);
+    body.set('device_code', deviceCode);
+    if (clientId) {
+      body.set('client_id', clientId);
+    }
+
+    const { status, json } = await postFormRaw(fetchFn, endpoint, body);
+    const errorCode = json?.error?.code ?? json?.error ?? json?.code;
+
+    if (status >= 200 && status < 300 && json?.access_token) {
+      return {
+        access_token: json.access_token,
+        token_type: json.token_type ?? 'Bearer',
+        expires_at: expiresAt(json.expires_in, now),
+        scope: json.scope ?? null,
+        registration_client_uri: json.registration_client_uri ?? null,
+      };
+    }
+
+    if (errorCode === 'authorization_pending') {
+      onPending?.('pending');
+      await sleep(currentInterval);
+      continue;
+    }
+    if (errorCode === 'slow_down') {
+      currentInterval += 5000;
+      onPending?.('slow_down');
+      await sleep(currentInterval);
+      continue;
+    }
+    if (errorCode === 'access_denied') {
+      throw new OwnerAgentError('approval_denied', 'Owner denied the trusted owner-agent onboarding request.');
+    }
+    if (errorCode === 'expired_token') {
+      throw new OwnerAgentError('approval_expired', 'Owner-agent approval expired before it was granted. Run onboarding again.');
+    }
+    if (errorCode === 'invalid_client' || errorCode === 'invalid_grant') {
+      throw new OwnerAgentError('token_exchange_failed', `Token endpoint rejected the device-code exchange (${errorCode}).`);
+    }
+
+    throw new OwnerAgentError('token_exchange_failed', `Unexpected token endpoint response (HTTP ${status}).`);
+  }
+
+  throw new OwnerAgentError('approval_expired', 'Timed out waiting for owner approval of the owner-agent credential.');
+}
+
+function expiresAt(expiresIn, now) {
+  const seconds = Number(expiresIn);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    return null;
+  }
+  return new Date(now() + seconds * 1000).toISOString();
+}
+
+async function postForm(fetchFn, url, body) {
+  const { status, json } = await postFormRaw(fetchFn, url, body);
+  if (status < 200 || status >= 300) {
+    const errorCode = json?.error?.code ?? json?.error ?? json?.code ?? `http_${status}`;
+    throw new OwnerAgentError('device_authorization_failed', `Device authorization failed (${errorCode}).`);
+  }
+  return json ?? {};
+}
+
+async function postFormRaw(fetchFn, url, body) {
+  let response;
+  try {
+    response = await fetchFn(url, {
+      method: 'POST',
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: body.toString(),
+    });
+  } catch (error) {
+    throw new OwnerAgentError('request_failed', `Request to ${url} failed: ${error.message}.`);
+  }
+  let json = null;
+  try {
+    json = await response.json();
+  } catch {
+    json = null;
+  }
+  return { status: response.status, json };
+}

package/src/owner-agent/discovery.js

@@ -0,0 +1,233 @@
+// Discovery for the trusted owner-agent onboarding profile.
+//
+// A trusted local owner agent (e.g. Daisy) starts from an entrypoint URL and
+// must learn, without route guessing, where to:
+//   - initiate browser-mediated owner approval (device authorization),
+//   - poll for the issued owner-agent credential (token endpoint),
+//   - introspect the credential, and
+//   - revoke it (RFC 7592 client delete).
+//
+// Two discovery sources are honored, in priority order:
+//   1. The advisory `pdpp_owner_agent_onboarding` block, when the deployment
+//      advertises it in protected-resource metadata or the `GET /` root pointer.
+//      This is the explicit, owner-level profile described in the
+//      add-trusted-owner-agent-onboarding OpenSpec change.
+//   2. A fallback to the existing RFC 8628 device-authorization shape advertised
+//      in authorization-server metadata (`device_authorization_endpoint`,
+//      `token_endpoint`, `introspection_endpoint`, `registration_endpoint`).
+//      This lets the CLI work against the current reference server before the
+//      advisory block is emitted server-side.
+//
+// This module does NOT emit server metadata. It only consumes it.
+
+import { OwnerAgentError } from './errors.js';
+
+const PROTECTED_RESOURCE_METADATA_PATH = '/.well-known/oauth-protected-resource';
+const AUTHORIZATION_SERVER_METADATA_PATH = '/.well-known/oauth-authorization-server';
+
+export function normalizeEntrypointUrl(value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    return null;
+  }
+  try {
+    const parsed = new URL(value.includes('://') ? value : `https://${value}`);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+      return null;
+    }
+    parsed.username = '';
+    parsed.password = '';
+    parsed.hash = '';
+    parsed.search = '';
+    parsed.pathname = parsed.pathname.length > 1 ? parsed.pathname.replace(/\/+$/, '') : parsed.pathname;
+    if (parsed.pathname === '/') {
+      parsed.pathname = '';
+    }
+    return parsed.toString().replace(/\/$/, '');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the owner-agent onboarding endpoints starting from an entrypoint URL.
+ *
+ * @param {string} entrypointUrl
+ * @param {object} [options]
+ * @param {typeof fetch} [options.fetch]
+ * @returns {Promise<OwnerAgentOnboardingProfile>}
+ */
+export async function discoverOwnerAgentProfile(entrypointUrl, options = {}) {
+  const resource = normalizeEntrypointUrl(entrypointUrl);
+  if (!resource) {
+    throw new OwnerAgentError('invalid_entrypoint', `Invalid entrypoint URL: ${entrypointUrl}`, 64);
+  }
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  if (typeof fetchFn !== 'function') {
+    throw new OwnerAgentError('fetch_unavailable', 'This Node runtime does not provide fetch().');
+  }
+
+  const resourceMetadata = await getJson(
+    fetchFn,
+    new URL(PROTECTED_RESOURCE_METADATA_PATH, resource).toString(),
+    'metadata_failure'
+  );
+
+  // The root pointer (GET /) may also carry the advisory block. We only fetch
+  // it if protected-resource metadata did not already surface onboarding info.
+  let onboarding = readOnboardingBlock(resourceMetadata);
+  if (!onboarding) {
+    const rootMetadata = await getJsonOptional(fetchFn, resource);
+    onboarding = rootMetadata ? readOnboardingBlock(rootMetadata) : null;
+  }
+
+  const authorizationServerUrl = selectAuthorizationServer(resourceMetadata, resource);
+  const authorizationMetadata = authorizationServerUrl
+    ? await getJsonOptional(
+        fetchFn,
+        new URL(AUTHORIZATION_SERVER_METADATA_PATH, authorizationServerUrl).toString()
+      )
+    : null;
+
+  const profile = buildProfile({
+    resource,
+    authorizationServerUrl,
+    onboarding,
+    authorizationMetadata,
+  });
+
+  if (!profile.deviceAuthorizationEndpoint || !profile.tokenEndpoint) {
+    throw new OwnerAgentError(
+      'onboarding_unavailable',
+      'This deployment does not advertise a trusted owner-agent onboarding flow. ' +
+        'Expected a pdpp_owner_agent_onboarding block or an RFC 8628 device_authorization_endpoint + token_endpoint.'
+    );
+  }
+
+  return profile;
+}
+
+function readOnboardingBlock(metadata) {
+  if (!metadata || typeof metadata !== 'object') {
+    return null;
+  }
+  const block =
+    metadata.pdpp_owner_agent_onboarding ??
+    metadata.pdpp_agent_discovery?.owner_agent_onboarding ??
+    null;
+  return block && typeof block === 'object' ? block : null;
+}
+
+function buildProfile({ resource, authorizationServerUrl, onboarding, authorizationMetadata }) {
+  const issuer = normalizeEntrypointUrl(
+    onboarding?.authorization_server ?? authorizationMetadata?.issuer ?? authorizationServerUrl ?? resource
+  );
+  const base = issuer ?? resource;
+
+  const deviceAuthorizationEndpoint = resolveEndpoint(
+    onboarding?.device_authorization_endpoint ?? authorizationMetadata?.device_authorization_endpoint,
+    base
+  );
+  const tokenEndpoint = resolveEndpoint(
+    onboarding?.token_endpoint ?? authorizationMetadata?.token_endpoint,
+    base
+  );
+  const introspectionEndpoint = resolveEndpoint(
+    onboarding?.introspection_endpoint ?? authorizationMetadata?.introspection_endpoint,
+    base
+  );
+  const registrationEndpoint = resolveEndpoint(
+    onboarding?.registration_endpoint ?? authorizationMetadata?.registration_endpoint,
+    base
+  );
+  const approvalUrl = resolveEndpoint(onboarding?.owner_approval_url ?? onboarding?.approval_url, base);
+  const schemaEndpoint = resolveEndpoint(onboarding?.schema_endpoint, resource);
+  const schemaCompactEndpoint = resolveEndpoint(
+    onboarding?.schema_compact_endpoint ?? (schemaEndpoint ? `${schemaEndpoint}?view=compact` : null),
+    resource
+  );
+  const streamsEndpoint = resolveEndpoint(onboarding?.streams_endpoint, resource);
+  const revocationPathTemplate =
+    typeof onboarding?.revocation_path_template === 'string' ? onboarding.revocation_path_template : null;
+
+  return {
+    profile: onboarding?.profile ?? 'trusted_owner_agent',
+    advisory: Boolean(onboarding),
+    resource,
+    authorizationServer: issuer,
+    deviceAuthorizationEndpoint,
+    tokenEndpoint,
+    introspectionEndpoint,
+    registrationEndpoint,
+    revocationPathTemplate,
+    approvalUrl,
+    schemaEndpoint,
+    schemaCompactEndpoint,
+    streamsEndpoint,
+    mcpRejectsOwnerBearer: onboarding?.mcp_owner_bearer_rejected ?? onboarding?.mcp_rejects_owner_bearer ?? true,
+  };
+}
+
+function selectAuthorizationServer(resourceMetadata, resource) {
+  const servers = resourceMetadata?.authorization_servers;
+  const selected = Array.isArray(servers) ? servers[0] : resourceMetadata?.authorization_server;
+  return normalizeEntrypointUrl(selected ?? resource);
+}
+
+function resolveEndpoint(value, base) {
+  if (!value || typeof value !== 'string') {
+    return null;
+  }
+  try {
+    return new URL(value, base ? `${base}/` : undefined).toString();
+  } catch {
+    return null;
+  }
+}
+
+async function getJson(fetchFn, url, errorCode) {
+  let response;
+  try {
+    response = await fetchFn(url, { headers: { Accept: 'application/json' } });
+  } catch (error) {
+    throw new OwnerAgentError(errorCode, `Failed to fetch ${url}: ${error.message}.`);
+  }
+  if (!response.ok) {
+    throw new OwnerAgentError(errorCode, `Failed to fetch ${url}: HTTP ${response.status}.`);
+  }
+  return response.json();
+}
+
+async function getJsonOptional(fetchFn, url) {
+  let response;
+  try {
+    response = await fetchFn(url, { headers: { Accept: 'application/json' } });
+  } catch {
+    return null;
+  }
+  if (!response.ok) {
+    return null;
+  }
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @typedef {object} OwnerAgentOnboardingProfile
+ * @property {string} profile
+ * @property {boolean} advisory  true when discovered from an advisory block
+ * @property {string} resource
+ * @property {string|null} authorizationServer
+ * @property {string|null} deviceAuthorizationEndpoint
+ * @property {string|null} tokenEndpoint
+ * @property {string|null} introspectionEndpoint
+ * @property {string|null} registrationEndpoint
+ * @property {string|null} revocationPathTemplate
+ * @property {string|null} approvalUrl
+ * @property {string|null} schemaEndpoint
+ * @property {string|null} schemaCompactEndpoint
+ * @property {string|null} streamsEndpoint
+ * @property {boolean} mcpRejectsOwnerBearer
+ */

package/src/owner-agent/errors.js

@@ -0,0 +1,13 @@
+// Bounded error type for the trusted owner-agent onboarding flow.
+//
+// Carries a stable machine code and a process exit code so callers can map
+// failures to terminal status without parsing free-form messages. Messages
+// MUST NOT contain bearer material.
+export class OwnerAgentError extends Error {
+  constructor(code, message, exitCode = 69) {
+    super(message);
+    this.name = 'OwnerAgentError';
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}