buckyos 0.7.116 → 0.7.118

package/cli/README.md

@@ -44,16 +44,20 @@ build scripts. Set `SOURCE_DATE_EPOCH` for byte-reproducible Node/Deno PIKG buil
 
 ## Policy and identity
 
-The developer policy grants the package root, cwd, Tool config, and explicit input/output paths. It
-does not include `$BUCKYOS_ROOT` or scan system credentials. The system policy additionally grants
-its paired BuckyOS root. Both policies constrain environment names and subprocesses; only PIKG
-Docker inputs may invoke `docker`.
-
-An explicitly selected identity is tried once. Without an explicit identity, readable candidate
-roots are scanned in the frozen source order `explicit`, `tool`, `environment`, `buckyos-root`, with
-directories sorted and a maximum of eight usable candidates. Rotation occurs only during session
-creation and only for `IDENTITY_KIND_NOT_ACCEPTED` or `AUTHENTICATION_REJECTED`; timeouts, network
-errors, capability mismatches and RBAC denial never rotate. Private keys and tokens are never shown.
+The developer policy grants the package root, cwd, Tool config, the read-only `~/.buckyos` and
+`~/.buckycli` roots, and explicit non-identity input/output paths. It does not include
+`$BUCKYOS_ROOT` or scan system credentials. The system policy additionally grants its paired BuckyOS
+root. Both policies constrain environment names and subprocesses; only PIKG Docker inputs may invoke
+`docker`.
+
+`~/.buckyos` is the regular operations identity root and is always eligible. Before touching the
+developer-only `~/.buckycli` root, the Tool reads `system.dev_mode.get` from the target Zone and
+requires a valid `BuckyOSDevConfig` with `enabled: true`. Automatic discovery tries `~/.buckyos`
+first and consults developer mode only if no operations identity succeeds; the combined search is
+limited to eight usable candidates. An explicitly selected identity is tried once. Rotation occurs
+only during session creation and only for
+`IDENTITY_KIND_NOT_ACCEPTED` or `AUTHENTICATION_REJECTED`; timeouts, network errors, capability
+mismatches and RBAC denial never rotate. Private keys and tokens are never shown.
 
 ## Verification
 

package/cli/core/argv.ts

@@ -12,8 +12,6 @@ export interface GlobalOptions {
   zone?: string
   endpoint?: string
   identity?: string
-  identityRoot?: string
-  securityRoot?: string
   sessionToken?: string
   sessionTokenFile?: string
   cli?: boolean
@@ -50,8 +48,6 @@ const STRING_GLOBALS = new Map<string, keyof GlobalOptions>([
   ['zone', 'zone'],
   ['endpoint', 'endpoint'],
   ['identity', 'identity'],
-  ['identity-root', 'identityRoot'],
-  ['security-root', 'securityRoot'],
   ['session-token', 'sessionToken'],
   ['session-token-file', 'sessionTokenFile'],
   ['output', 'output'],

package/cli/core/auth.ts

@@ -5,9 +5,16 @@ import {
   VerifyHubClient,
 } from 'buckyos/node'
 import { type Environment, readEnvironment, type ResolvedConfig } from './config.ts'
+import {
+  type DevelopmentModeDecision,
+  type DevelopmentModeReader,
+  readTargetDevelopmentMode,
+} from './development_mode.ts'
 import { EXIT_AUTH, sanitizeMessage, ToolError } from './errors.ts'
 import {
+  IDENTITY_CANDIDATE_LIMIT,
   IDENTITY_REJECTION_CODES,
+  type IdentityCandidate,
   type IdentityMaterial,
   resolveIdentityMaterial,
   scanIdentityCandidates,
@@ -57,6 +64,7 @@ export interface AuthenticationDependencies {
   transport?: AuthenticationTransport
   readPassword?: (prompt: string) => Promise<string>
   readUsername?: (prompt: string) => Promise<string>
+  readDevelopmentMode?: DevelopmentModeReader
   now?: () => number
 }
 
@@ -78,9 +86,11 @@ export class AuthenticationSession implements SessionController {
   readonly #transport: AuthenticationTransport
   readonly #readPassword: (prompt: string) => Promise<string>
   readonly #readUsername: (prompt: string) => Promise<string>
+  readonly #readDevelopmentMode: DevelopmentModeReader
   readonly #now: () => number
   #session?: AuthenticatedSession
   #acceptedIdentity?: IdentityMaterial
+  #developmentMode?: DevelopmentModeDecision
   #identityAttempts: Array<{ identity: string; code: string; message: string }> = []
 
   constructor(
@@ -93,6 +103,7 @@ export class AuthenticationSession implements SessionController {
     this.#transport = dependencies.transport ?? new SdkAuthenticationTransport()
     this.#readPassword = dependencies.readPassword ?? readSecret
     this.#readUsername = dependencies.readUsername ?? readVisible
+    this.#readDevelopmentMode = dependencies.readDevelopmentMode ?? readTargetDevelopmentMode
     this.#now = dependencies.now ?? Date.now
   }
 
@@ -146,6 +157,7 @@ export class AuthenticationSession implements SessionController {
       renewable: session.renewable,
       expires_at: expiresAt ?? null,
       remaining_seconds: remainingSeconds,
+      developer_mode: this.#developmentMode?.state ?? null,
       identity_attempts: this.#identityAttempts,
     }
   }
@@ -180,34 +192,43 @@ export class AuthenticationSession implements SessionController {
     const injected = this.#environment.BUCKYOS_APPCLIENT_SESSION_TOKEN?.trim()
     if (injected) return externalSession(injected, 'environment', this.#now())
 
-    if (this.#acceptedIdentity) return await this.#loginWithIdentity(this.#acceptedIdentity)
+    if (this.#acceptedIdentity) {
+      if (this.#acceptedIdentity.source === 'buckycli-home') {
+        await this.#requireDeveloperIdentityAccess()
+      }
+      return await this.#loginWithIdentity(this.#acceptedIdentity)
+    }
 
     if (this.config.identity) {
-      const material = await resolveIdentityMaterial(
-        this.config.identity,
-        this.config,
-        this.#environment,
-      )
+      const material = await this.#resolveExplicitIdentity(this.config.identity)
       const session = await this.#loginWithIdentity(material)
       this.#acceptedIdentity = material
       return session
     }
 
-    const candidates = await scanIdentityCandidates(this.config, this.#environment)
     this.#identityAttempts = []
-    for (const candidate of candidates.candidates) {
-      try {
-        const session = await this.#loginWithIdentity(candidate.material)
-        this.#acceptedIdentity = candidate.material
-        return session
-      } catch (error) {
-        if (!isIdentityRejection(error)) throw error
-        this.#identityAttempts.push({
-          identity: candidate.material.did,
-          code: error.code,
-          message: sanitizeMessage(error.message),
-        })
-      }
+    const operations = await scanIdentityCandidates(this.config, this.#environment)
+    const operationsSession = await this.#tryIdentityCandidates(operations.candidates)
+    if (operationsSession) return operationsSession
+
+    const developmentMode = await this.#checkDevelopmentMode()
+    if (
+      developmentMode.state === 'enabled' &&
+      operations.candidates.length < IDENTITY_CANDIDATE_LIMIT
+    ) {
+      const operationsDids = new Set(
+        operations.candidates.map((candidate) => candidate.material.did),
+      )
+      const developer = await scanIdentityCandidates(this.config, this.#environment, {
+        includeOperations: false,
+        includeDeveloper: true,
+      })
+      const remaining = IDENTITY_CANDIDATE_LIMIT - operations.candidates.length
+      const candidates = developer.candidates.filter((candidate) =>
+        !operationsDids.has(candidate.material.did)
+      ).slice(0, remaining)
+      const developerSession = await this.#tryIdentityCandidates(candidates)
+      if (developerSession) return developerSession
     }
     if (this.#identityAttempts.length > 0) {
       throw new ToolError(
@@ -241,6 +262,44 @@ export class AuthenticationSession implements SessionController {
     return authenticatedSession(token, 'password', true, this.#now())
   }
 
+  async #resolveExplicitIdentity(selectedIdentity: string): Promise<IdentityMaterial> {
+    if (this.config.implicitDeviceIdentity) {
+      return await resolveIdentityMaterial(selectedIdentity, this.config, this.#environment)
+    }
+
+    try {
+      return await resolveIdentityMaterial(selectedIdentity, this.config, this.#environment)
+    } catch (error) {
+      if (!(error instanceof ToolError) || error.code !== 'IDENTITY_NOT_FOUND') throw error
+    }
+
+    await this.#requireDeveloperIdentityAccess()
+    return await resolveIdentityMaterial(selectedIdentity, this.config, this.#environment, {
+      includeOperations: false,
+      includeDeveloper: true,
+    })
+  }
+
+  async #tryIdentityCandidates(
+    candidates: readonly IdentityCandidate[],
+  ): Promise<AuthenticatedSession | undefined> {
+    for (const candidate of candidates) {
+      try {
+        const session = await this.#loginWithIdentity(candidate.material)
+        this.#acceptedIdentity = candidate.material
+        return session
+      } catch (error) {
+        if (!isIdentityRejection(error)) throw error
+        this.#identityAttempts.push({
+          identity: candidate.material.did,
+          code: error.code,
+          message: sanitizeMessage(error.message),
+        })
+      }
+    }
+    return undefined
+  }
+
   async #loginWithIdentity(material: IdentityMaterial): Promise<AuthenticatedSession> {
     const loginJwt = await createLoginJwt(
       material.subject,
@@ -256,6 +315,31 @@ export class AuthenticationSession implements SessionController {
     )
     return authenticatedSession(token, 'identity', true, this.#now())
   }
+
+  async #checkDevelopmentMode(): Promise<DevelopmentModeDecision> {
+    this.#developmentMode = await this.#readDevelopmentMode(this.config)
+    return this.#developmentMode
+  }
+
+  async #requireDeveloperIdentityAccess(): Promise<void> {
+    const decision = await this.#checkDevelopmentMode()
+    if (decision.state === 'enabled') return
+    this.#acceptedIdentity = undefined
+    if (decision.state === 'disabled') {
+      throw new ToolError(
+        'DEVELOPER_IDENTITY_DISABLED',
+        'the target Zone has developer mode disabled; local developer identities are unavailable',
+        EXIT_AUTH,
+      )
+    }
+    throw new ToolError(
+      'DEVELOPER_MODE_UNAVAILABLE',
+      'the target Zone developer-mode configuration could not be verified',
+      EXIT_AUTH,
+      true,
+      { reason: sanitizeMessage(decision.reason) },
+    )
+  }
 }
 
 function isIdentityRejection(error: unknown): error is ToolError {

package/cli/core/config.ts

@@ -69,8 +69,6 @@ export const ENVIRONMENT_NAMES = [
   'BUCKYOS_TOOL_ENDPOINT',
   'BUCKYOS_TOOL_IDENTITY',
   'BUCKYOS_TOOL_OUTPUT',
-  'BUCKYOS_IDENTITY_ROOT',
-  'BUCKYOS_SECURITY_ROOT',
   'BUCKYOS_APPCLIENT_SESSION_TOKEN',
   'BUCKYOS_ROOT',
 ] as const
@@ -229,38 +227,6 @@ export async function resolveConfig(
     undefined,
     sources,
   )
-  const identityRoot = select(
-    'identity_root',
-    explicit.identityRoot,
-    environment.BUCKYOS_IDENTITY_ROOT,
-    undefined,
-    undefined,
-    sources,
-  )
-  const securityRoot = select(
-    'security_root',
-    explicit.securityRoot,
-    environment.BUCKYOS_SECURITY_ROOT,
-    undefined,
-    undefined,
-    sources,
-  )
-  if (!!explicit.identityRoot !== !!explicit.securityRoot) {
-    throw new UsageError(
-      'IDENTITY_ROOT_PAIR_REQUIRED',
-      '--identity-root and --security-root must be provided together',
-    )
-  }
-  if (
-    !!environment.BUCKYOS_IDENTITY_ROOT !== !!environment.BUCKYOS_SECURITY_ROOT &&
-    !explicit.identityRoot
-  ) {
-    throw new UsageError(
-      'IDENTITY_ROOT_PAIR_REQUIRED',
-      'BUCKYOS_IDENTITY_ROOT and BUCKYOS_SECURITY_ROOT must be provided together',
-    )
-  }
-
   let output: OutputFormat
   if (options.interactive && explicit.output === undefined) {
     output = 'table'
@@ -297,8 +263,6 @@ export async function resolveConfig(
       zone,
       endpoint,
       identity,
-      identityRoot,
-      securityRoot,
       sessionToken,
       sessionTokenFile: explicit.sessionTokenFile,
       output,
@@ -347,8 +311,6 @@ export function localResolvedConfig(
       zone: explicit.zone ?? environment.BUCKYOS_TOOL_ZONE,
       endpoint: explicit.endpoint ?? environment.BUCKYOS_TOOL_ENDPOINT,
       identity: explicit.identity ?? environment.BUCKYOS_TOOL_IDENTITY,
-      identityRoot: explicit.identityRoot ?? environment.BUCKYOS_IDENTITY_ROOT,
-      securityRoot: explicit.securityRoot ?? environment.BUCKYOS_SECURITY_ROOT,
       sessionToken: explicit.sessionToken ?? environment.BUCKYOS_APPCLIENT_SESSION_TOKEN,
       sessionTokenFile: explicit.sessionTokenFile,
       output,

package/cli/core/development_mode.ts

@@ -0,0 +1,103 @@
+import { buckyos } from 'buckyos/node'
+import type { ResolvedConfig } from './config.ts'
+import { resolveServiceUrl } from './runtime.ts'
+
+export const BUCKYOS_DEV_CONFIG_KEY = 'system/buckyos_dev_config'
+export const BUCKYOS_DEV_CONFIG_SCHEMA_VERSION = 1
+
+export interface BuckyOSDevConfig {
+  schema_version: 1
+  enabled: boolean
+  enabled_at: number | null
+  enabled_by: string | null
+}
+
+export type DevelopmentModeDecision =
+  | { state: 'enabled'; config: BuckyOSDevConfig }
+  | { state: 'disabled'; config: BuckyOSDevConfig }
+  | { state: 'unavailable'; reason: string }
+
+export type DevelopmentModeReader = (
+  config: ResolvedConfig,
+) => Promise<DevelopmentModeDecision>
+
+interface PublicRpcClient {
+  call<T>(method: string, params: Record<string, unknown>): Promise<T>
+}
+
+/**
+ * Read the target Zone's public developer-mode setting.
+ *
+ * This deliberately uses control-panel's unauthenticated `system.dev_mode.get`
+ * endpoint: developer mode must be known before a local identity is touched or
+ * exchanged at verify-hub. Every error is converted to `unavailable`, which is
+ * a fail-closed result for the identity resolver.
+ */
+export async function readTargetDevelopmentMode(
+  config: ResolvedConfig,
+): Promise<DevelopmentModeDecision> {
+  try {
+    const url = resolveServiceUrl(config, 'control-panel')
+    const client = new buckyos.kRPCClient(url) as unknown as PublicRpcClient
+    const value = await withTimeout(
+      client.call<unknown>('system.dev_mode.get', {}),
+      config.timeoutMs,
+    )
+    const parsed = parseBuckyOSDevConfig(value)
+    return parsed.enabled
+      ? { state: 'enabled', config: parsed }
+      : { state: 'disabled', config: parsed }
+  } catch (error) {
+    return {
+      state: 'unavailable',
+      reason: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+export function parseBuckyOSDevConfig(value: unknown): BuckyOSDevConfig {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('BuckyOSDevConfig must be an object')
+  }
+  const config = value as Record<string, unknown>
+  const keys = Object.keys(config).sort()
+  const expectedKeys = ['enabled', 'enabled_at', 'enabled_by', 'schema_version']
+  if (JSON.stringify(keys) !== JSON.stringify(expectedKeys)) {
+    throw new Error('BuckyOSDevConfig contains missing or unsupported fields')
+  }
+  if (config.schema_version !== BUCKYOS_DEV_CONFIG_SCHEMA_VERSION) {
+    throw new Error(`unsupported BuckyOSDevConfig schema_version ${String(config.schema_version)}`)
+  }
+  if (typeof config.enabled !== 'boolean') {
+    throw new Error('BuckyOSDevConfig enabled must be a boolean')
+  }
+  const enabledAt = config.enabled_at
+  const enabledBy = config.enabled_by
+  const hasAuditFields = Number.isSafeInteger(enabledAt) && (enabledAt as number) > 0 &&
+    typeof enabledBy === 'string' && enabledBy.trim().length > 0
+  const hasNoAuditFields = enabledAt === null && enabledBy === null
+  if (!hasAuditFields && !hasNoAuditFields) {
+    throw new Error('BuckyOSDevConfig enabled_at and enabled_by must be valid and present together')
+  }
+  if (config.enabled && !hasAuditFields) {
+    throw new Error('enabled BuckyOSDevConfig requires enable audit fields')
+  }
+  return {
+    schema_version: 1,
+    enabled: config.enabled,
+    enabled_at: enabledAt as number | null,
+    enabled_by: enabledBy as string | null,
+  }
+}
+
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error('developer-mode lookup timed out')), timeoutMs)
+  })
+  try {
+    return await Promise.race([promise, timeout])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}

package/cli/core/identity.ts

@@ -17,12 +17,18 @@ export interface IdentityMaterial {
   documentPath: string
   privateKeyPath: string
   privateKeyPem: string
+  source: IdentityRootPair['source']
 }
 
 export interface IdentityRootPair {
   publicRoot: string
   securityRoot: string
-  source: 'explicit' | 'tool' | 'environment' | 'buckyos-root'
+  source: 'buckyos-home' | 'buckycli-home' | 'current-device'
+}
+
+export interface IdentityRootOptions {
+  includeOperations?: boolean
+  includeDeveloper?: boolean
 }
 
 export const IDENTITY_CANDIDATE_LIMIT = 8
@@ -137,37 +143,31 @@ export async function readCurrentDeviceIdentity(
 export function identityRootPairs(
   config: ResolvedConfig,
   environment: Environment = readEnvironment(),
+  options: IdentityRootOptions = {},
 ): IdentityRootPair[] {
+  const device = config.implicitDeviceIdentity
+  if (device) {
+    return [{
+      publicRoot: device.publicRoot,
+      securityRoot: device.securityRoot,
+      source: 'current-device',
+    }]
+  }
+
+  const home = environment.HOME ?? environment.USERPROFILE ?? getHost().homeDir()
   const pairs: IdentityRootPair[] = []
-  if (config.identityRoot && config.securityRoot) {
+  if (options.includeOperations ?? true) {
     pairs.push({
-      publicRoot: config.identityRoot,
-      securityRoot: config.securityRoot,
-      source: 'explicit',
+      publicRoot: join(home, '.buckyos', 'local', 'identity'),
+      securityRoot: join(home, '.buckyos', 'security'),
+      source: 'buckyos-home',
     })
   }
-  pairs.push({
-    publicRoot: join(config.configDir, 'local', 'identity'),
-    securityRoot: join(config.configDir, 'security'),
-    source: 'tool',
-  })
-  if (environment.BUCKYOS_IDENTITY_ROOT && environment.BUCKYOS_SECURITY_ROOT) {
-    const duplicate = config.identityRoot === environment.BUCKYOS_IDENTITY_ROOT &&
-      config.securityRoot === environment.BUCKYOS_SECURITY_ROOT
-    if (!duplicate) {
-      pairs.push({
-        publicRoot: environment.BUCKYOS_IDENTITY_ROOT,
-        securityRoot: environment.BUCKYOS_SECURITY_ROOT,
-        source: 'environment',
-      })
-    }
-  }
-  if (getHost().policy.distribution === 'system') {
-    const buckyosRoot = environment.BUCKYOS_ROOT ?? defaultBuckyOSRoot(environment)
+  if (options.includeDeveloper ?? false) {
     pairs.push({
-      publicRoot: join(buckyosRoot, 'local', 'identity'),
-      securityRoot: join(buckyosRoot, 'security'),
-      source: 'buckyos-root',
+      publicRoot: join(home, '.buckycli', 'local', 'identity'),
+      securityRoot: join(home, '.buckycli', 'security'),
+      source: 'buckycli-home',
     })
   }
   return deduplicatePairs(pairs)
@@ -177,11 +177,12 @@ export async function resolveIdentityMaterial(
   selectedIdentity: string,
   config: ResolvedConfig,
   environment: Environment = readEnvironment(),
+  options: IdentityRootOptions = {},
 ): Promise<IdentityMaterial> {
   const selected = selectedIdentity.trim()
   if (!selected) throw new UsageError('IDENTITY_REQUIRED', 'identity is empty')
 
-  for (const roots of identityRootPairs(config, environment)) {
+  for (const roots of identityRootPairs(config, environment, options)) {
     for (const directory of await candidateDirectories(roots.publicRoot, selected)) {
       const material = await loadIdentityMaterial(roots, directory, selected)
       if (material) return material
@@ -198,11 +199,12 @@ export async function resolveIdentityMaterial(
 export async function scanIdentityCandidates(
   config: ResolvedConfig,
   environment: Environment = readEnvironment(),
+  options: IdentityRootOptions = {},
 ): Promise<IdentityCandidateScan> {
   const candidates: IdentityCandidate[] = []
   const skipped: IdentityCandidateScan['skipped'] = []
   const seen = new Set<string>()
-  const roots = identityRootPairs(config, environment)
+  const roots = identityRootPairs(config, environment, options)
   for (const pair of roots) {
     let directories: string[]
     try {
@@ -256,7 +258,7 @@ export async function scanIdentityCandidates(
     if (candidates.length >= IDENTITY_CANDIDATE_LIMIT) break
   }
   return {
-    order: Object.freeze(['explicit', 'tool', 'environment', 'buckyos-root']),
+    order: Object.freeze(roots.map((pair) => pair.source)),
     limit: IDENTITY_CANDIDATE_LIMIT,
     candidates,
     skipped,
@@ -266,10 +268,13 @@ export async function scanIdentityCandidates(
 export async function identityCandidateView(
   config: ResolvedConfig,
   environment: Environment = readEnvironment(),
+  developerModeEnabled = false,
 ): Promise<Record<string, unknown>> {
   if (config.identity) {
     try {
-      const material = await resolveIdentityMaterial(config.identity, config, environment)
+      const material = await resolveIdentityMaterial(config.identity, config, environment, {
+        includeDeveloper: developerModeEnabled,
+      })
       return {
         mode: 'explicit',
         order: [material.did],
@@ -294,7 +299,9 @@ export async function identityCandidateView(
       }
     }
   }
-  const scan = await scanIdentityCandidates(config, environment)
+  const scan = await scanIdentityCandidates(config, environment, {
+    includeDeveloper: developerModeEnabled,
+  })
   return {
     mode: 'search',
     order: scan.order,
@@ -336,6 +343,7 @@ async function loadIdentityMaterial(
       documentPath,
       privateKeyPath,
       privateKeyPem,
+      source: roots.source,
     }
   } catch (error) {
     if (!isHostError(error, 'NotFound')) throw error

package/cli/core/registry.ts

@@ -17,8 +17,6 @@ const GLOBAL_OPTIONS = [
   { name: 'zone', property: 'zone', type: 'string', scope: 'session' },
   { name: 'endpoint', property: 'endpoint', type: 'string', scope: 'session' },
   { name: 'identity', property: 'identity', type: 'string', scope: 'session' },
-  { name: 'identity-root', property: 'identityRoot', type: 'string', scope: 'session' },
-  { name: 'security-root', property: 'securityRoot', type: 'string', scope: 'session' },
   {
     name: 'session-token',
     property: 'sessionToken',