@palettelab/cli 0.3.30 → 0.3.31

package/README.md

@@ -441,6 +441,36 @@ Environment variables:
 | `PALETTE_DEV_DATABASE_URL` | `.palette/dev/<plugin-id>.sqlite3` | Override the local dev database URL |
 | `APPSTORE_AUTO_APPROVE_SANDBOX_PREVIEWS` | `false` | Backend setting for hosted sandboxes; auto-approve passing preview publishes so developers can test full OS behavior without manual review |
 
+### `pltt secrets`
+
+Palette secrets are declared in `palette-plugin.json` and resolved through
+`ctx.secret("NAME")`.
+
+```json
+{
+  "secrets": {
+    "OPENAI_API_KEY": { "scope": "install", "required": true },
+    "STRIPE_SECRET": { "scope": "plugin", "required": true },
+    "DEBUG_PROBE_URL": { "scope": "dev", "required": false }
+  },
+  "platform_services": ["llm", "kv", "storage"]
+}
+```
+
+Commands:
+
+```bash
+pltt secrets init
+pltt secrets set STRIPE_SECRET --env staging --value sk_live_...
+pltt secrets list --env staging
+pltt publish --env staging --secrets-file plugin-secrets.env
+```
+
+`dev` secrets live in `.palette/.env.local`, are loaded by `pltt dev`, and are
+never uploaded. `plugin` secrets are encrypted by the platform and attached to
+the plugin/environment. `install` secrets are filled by the installing org.
+Frontend bundles may only receive public values such as `NEXT_PUBLIC_*`.
+
 ### `pltt login`
 
 Save a Palette sandbox or production environment URL plus token in `~/.palette/config.json` with file mode `0600`. Environment variables still override the stored token when present.

package/backend-sdk/palette_sdk/__init__.py

@@ -1,7 +1,7 @@
 """Palette Platform SDK for building backend plugins."""
 
 from palette_sdk.plugin_router import PluginRouter
-from palette_sdk.plugin_context import PluginContext, get_plugin_context
+from palette_sdk.plugin_context import MissingSecretError, PluginContext, get_plugin_context
 from palette_sdk.data_rooms import DataRoomsClient
 from palette_sdk.repository import OrgRepository
 from palette_sdk.lifecycle import LifecycleHooks
@@ -33,6 +33,7 @@ from palette_sdk.testing import route_permission_issues
 __all__ = [
     "PluginRouter",
     "PluginContext",
+    "MissingSecretError",
     "get_plugin_context",
     "DataRoomsClient",
     "OrgRepository",

package/backend-sdk/palette_sdk/manifest.py

@@ -6,7 +6,7 @@ import json
 from pathlib import Path
 from typing import Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class AgentDefinition(BaseModel):
@@ -73,6 +73,21 @@ class RateLimit(BaseModel):
     per_minute: int = 60
 
 
+class SecretSpec(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    scope: Literal["dev", "plugin", "install", "platform"] | list[Literal["dev", "plugin", "install", "platform"]] = "dev"
+    required: bool = False
+    label: str | None = None
+    help: str | None = None
+    validate_pattern: str | None = Field(default=None, alias="validate")
+
+
+class PlatformServiceSpec(BaseModel):
+    required: bool = False
+    billing: Literal["org_wallet", "plugin_owner", "platform"] | None = None
+
+
 class PluginManifest(BaseModel):
     """Validated plugin manifest from palette-plugin.json."""
 
@@ -97,6 +112,8 @@ class PluginManifest(BaseModel):
     agents: list[AgentDefinition] = Field(default_factory=list)
     tools: list[ToolEntry] = Field(default_factory=list)
     permissions: list[str] = Field(default_factory=list)
+    secrets: dict[str, SecretSpec] = Field(default_factory=dict)
+    platform_services: list[Literal["llm", "kv", "storage"]] | dict[str, PlatformServiceSpec] = Field(default_factory=list)
     rating: float = 0.0
     reviews: int = 0
     featured: bool = False

package/backend-sdk/palette_sdk/plugin_context.py

@@ -13,6 +13,10 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from palette_sdk.data_rooms import DataRoomsClient
 
 
+class MissingSecretError(KeyError):
+    """Raised when a declared required plugin secret is not configured."""
+
+
 @dataclass
 class PluginContext:
     """Context provided to plugin endpoints by the platform.
@@ -63,6 +67,15 @@ class PluginContext:
         secrets = self.config.get("secrets")
         if isinstance(secrets, dict) and key in secrets:
             return secrets[key]
+        specs = self.config.get("secret_specs")
+        spec = specs.get(key) if isinstance(specs, dict) else None
+        if isinstance(spec, dict):
+            if default is not None:
+                return default
+            if spec.get("required"):
+                help_text = spec.get("help") or spec.get("label") or "Configure this secret before using the plugin."
+                raise MissingSecretError(f"missing plugin secret {key}: {help_text}")
+            return default
         return os.environ.get(key, default)
 
     def repo(self, model: type[Any]):

package/docs/python-backend-sdk.md

@@ -478,8 +478,32 @@ async def sync_config(ctx: PluginContext = Depends(get_plugin_context)):
     }
 ```
 
-`ctx.secret("KEY")` first checks app config secrets and then falls back to the
-process environment variable named `KEY`.
+Declare secret ownership in `palette-plugin.json`:
+
+```json
+{
+  "secrets": {
+    "FINANCE_API_KEY": {
+      "scope": "install",
+      "required": true,
+      "help": "Provided by the installing organization."
+    },
+    "AUTHOR_STRIPE_SECRET": {
+      "scope": "plugin",
+      "required": true
+    },
+    "DEBUG_PROBE_URL": {
+      "scope": "dev",
+      "required": false
+    }
+  }
+}
+```
+
+`ctx.secret("KEY")` resolves declared secrets from the configured scope:
+install config, plugin-scope encrypted secrets, or local `.palette/.env.local`
+during `pltt dev`. Undeclared keys still fall back to the process environment
+for local compatibility.
 
 ## 10. Lifecycle Hooks
 

package/lib/cli.js

@@ -10,6 +10,7 @@ const login = require("./commands/login")
 const pkg = require("./commands/package")
 const status = require("./commands/status")
 const logs = require("./commands/logs")
+const secrets = require("./commands/secrets")
 
 const COMMANDS = {
   init: { run: init, help: "Scaffold a new plugin directory from the template" },
@@ -41,6 +42,10 @@ const COMMANDS = {
     run: logs,
     help: "Tail telemetry events for a plugin (--follow to stream)",
   },
+  secrets: {
+    run: secrets,
+    help: "Initialize local env files and manage plugin-scope secrets",
+  },
 }
 
 function printHelp() {
@@ -68,6 +73,10 @@ function printHelp() {
   console.log("\nLogs flags:")
   console.log("  --tail <n>       Tail last n events (default 50)")
   console.log("  -f, --follow     Stream events (poll every 3s)")
+  console.log("\nSecrets:")
+  console.log("  pltt secrets init")
+  console.log("  pltt secrets set NAME --value <secret> --env staging")
+  console.log("  pltt secrets list --env staging")
   console.log("\nExamples:")
   console.log("  pltt init my-app --template database")
   console.log("  pltt login --env staging --url https://sandbox.pltt.ai --token <token>")
@@ -78,6 +87,7 @@ function printHelp() {
   console.log("  pltt publish --env staging")
   console.log("  pltt status")
   console.log("  pltt logs --follow")
+  console.log("  pltt secrets init")
 }
 
 async function run(argv) {

package/lib/commands/dev.js

@@ -7,6 +7,7 @@ const { watchFrontend } = require("../bundler")
 const { parseFlags } = require("../environments")
 const { resolveDevPorts } = require("../ports")
 const { startSimulator } = require("../dev-simulator")
+const { loadLocalEnv } = require("../secrets")
 const publish = require("./publish")
 
 const DEFAULT_PLATFORM_IMAGE = "ghcr.io/palette-lab/platform-dev:latest"
@@ -78,6 +79,7 @@ async function run(args, { cwd }) {
   const { flags, rest } = parseFlags(args)
   const cloud = rest.includes("--cloud") || rest.includes("--sandbox")
   const platform = rest.includes("--platform")
+  loadLocalEnv(cwd)
   if (cloud) {
     const json = args.includes("--json")
     const publishArgs = []

package/lib/commands/doctor.js

@@ -6,6 +6,7 @@ const { spawnSync } = require("child_process")
 const { loadManifest, validateManifest } = require("../manifest")
 const { bundleFrontend } = require("../bundler")
 const { resolveDevPorts } = require("../ports")
+const { declaredSecrets, loadLocalEnv } = require("../secrets")
 
 const DEFAULT_IMAGE =
   process.env.PALETTE_DEV_IMAGE || "ghcr.io/palette-lab/platform-dev:latest"
@@ -120,6 +121,25 @@ async function run(args, { cwd }) {
       failures += checkEntry(cwd, `tool[${tool.name}]`, tool.entry)
     }
 
+    const secrets = declaredSecrets(manifest)
+    const localSecrets = loadLocalEnv(cwd, { apply: false })
+    if (Object.keys(secrets).length === 0) {
+      ok("no manifest secrets declared")
+    } else {
+      ok(`manifest declares ${Object.keys(secrets).length} secret(s)`)
+      for (const [name, spec] of Object.entries(secrets)) {
+        if (spec.scope.includes("dev") && !localSecrets[name]) {
+          warn(`local dev secret missing: ${name}`, "Run pltt secrets init and fill .palette/.env.local.")
+        }
+        if (spec.scope.includes("plugin") && spec.required && !localSecrets[name] && !process.env[name]) {
+          warn(
+            `plugin secret missing locally: ${name}`,
+            "Set an env var, pass --secrets-file to publish, or run pltt secrets set after first publish.",
+          )
+        }
+      }
+    }
+
     if (manifest.frontend?.entry) {
       try {
         const bundle = await bundleFrontend(cwd, manifest.frontend.entry, manifest.frontend)

package/lib/commands/init.js

@@ -4,6 +4,7 @@ const fs = require("fs")
 const path = require("path")
 const { spawnSync } = require("child_process")
 const os = require("os")
+const { initLocalEnv } = require("../secrets")
 
 const DEFAULT_TEMPLATE_REPO = "palette-lab/plugin-template"
 const TEMPLATE_REPO = process.env.PALETTE_TEMPLATE_REPO || DEFAULT_TEMPLATE_REPO
@@ -165,6 +166,12 @@ async function run(args, { cwd }) {
   fs.cpSync(tmp, destDir, { recursive: true })
   fs.rmSync(tmp, { recursive: true, force: true })
   rewriteScaffold(destDir, slug, displayName)
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(destDir, "palette-plugin.json"), "utf8"))
+    initLocalEnv(destDir, manifest)
+  } catch (_err) {
+    // The scaffold is still usable; `pltt secrets init` can repair env files.
+  }
 
   console.log(`[pltt] created ${destDir}`)
   console.log("[pltt] next steps:")

package/lib/commands/publish.js

@@ -11,6 +11,13 @@ const {
   parseFlags,
   confirmProduction,
 } = require("../environments")
+const {
+  declaredSecrets,
+  loadLocalEnv,
+  parseDotEnv,
+  readDotEnvFile,
+  redactValue,
+} = require("../secrets")
 
 function sha256(buf) {
   return crypto.createHash("sha256").update(buf).digest("hex")
@@ -77,6 +84,43 @@ async function put(url, buf, contentType) {
   }
 }
 
+function collectPluginSecrets(cwd, manifest, env, flags, log) {
+  const declared = declaredSecrets(manifest)
+  const pluginSecrets = Object.entries(declared).filter(([, spec]) => spec.scope.includes("plugin"))
+  const devRequired = Object.entries(declared).filter(([, spec]) => spec.scope.includes("dev") && spec.required)
+  if (devRequired.length) {
+    log(
+      `[pltt]   dev-only secrets are not uploaded: ${devRequired.map(([name]) => name).join(", ")}`,
+    )
+  }
+
+  let fileValues = {}
+  if (flags.secretsFile) {
+    fileValues = parseDotEnv(fs.readFileSync(path.resolve(cwd, flags.secretsFile), "utf8"))
+  }
+  const localValues = readDotEnvFile(path.join(cwd, ".palette", ".env.local"))
+  const values = {}
+  const missing = []
+  for (const [name, spec] of pluginSecrets) {
+    const value = fileValues[name] ?? process.env[name] ?? localValues[name]
+    if (value) {
+      values[name] = value
+      continue
+    }
+    if (spec.required) missing.push(name)
+  }
+  if (missing.length) {
+    throw new Error(
+      `missing required plugin-scope secret(s): ${missing.join(", ")}. ` +
+        `Set env vars, pass --secrets-file, or run pltt secrets set <NAME> --env ${env.name}.`,
+    )
+  }
+  for (const [name, value] of Object.entries(values)) {
+    log(`[pltt]   plugin secret ${name}=${redactValue(value)} (${env.name})`)
+  }
+  return values
+}
+
 async function run(argv, { cwd }) {
   const { flags } = parseFlags(argv)
   const log = (...args) => {
@@ -109,6 +153,7 @@ async function run(argv, { cwd }) {
   }
 
   const manifest = loadManifest(cwd)
+  loadLocalEnv(cwd)
   const errors = validateManifest(manifest)
   if (errors.length) {
     console.error("[pltt] manifest invalid:")
@@ -137,6 +182,13 @@ async function run(argv, { cwd }) {
 
   const backendSha = sha256(backend)
   const api = makeApi(env)
+  let pluginSecrets = {}
+  try {
+    pluginSecrets = collectPluginSecrets(cwd, manifest, env, flags, log)
+  } catch (err) {
+    console.error(`[pltt] ${err instanceof Error ? err.message : String(err)}`)
+    process.exit(1)
+  }
 
   log("[pltt]   requesting signed URLs")
   const signed = await api("/api/v1/appstore/sign-upload", {
@@ -169,7 +221,9 @@ async function run(argv, { cwd }) {
     bundle_path: signed.bundle_path,
     bundle_sha256: backendSha,
     manifest,
+    environment: env.name,
   }
+  if (Object.keys(pluginSecrets).length) publishBody.plugin_secrets = pluginSecrets
   if (Number.isFinite(flags.ttlHours) && flags.ttlHours > 0) {
     publishBody.preview_ttl_hours = flags.ttlHours
   }

package/lib/commands/secrets.js

@@ -0,0 +1,124 @@
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+const { loadManifest } = require("../manifest")
+const { parseFlags, resolveEnvironment } = require("../environments")
+const {
+  declaredSecrets,
+  initLocalEnv,
+  parseDotEnv,
+  readDotEnvFile,
+  redactValue,
+} = require("../secrets")
+
+function parseOwnFlags(argv) {
+  const out = { value: undefined, secretsFile: undefined }
+  const rest = []
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === "--value") out.value = argv[++i]
+    else if (arg.startsWith("--value=")) out.value = arg.slice("--value=".length)
+    else if (arg === "--secrets-file") out.secretsFile = argv[++i]
+    else if (arg.startsWith("--secrets-file=")) out.secretsFile = arg.slice("--secrets-file=".length)
+    else rest.push(arg)
+  }
+  return { own: out, rest }
+}
+
+function makeApi(env) {
+  return async function api(pathname, { method = "GET", body } = {}) {
+    const res = await fetch(`${env.url}${pathname}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${env.token}`,
+        "Content-Type": "application/json",
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    })
+    if (!res.ok) throw new Error(`${method} ${pathname} -> ${res.status}: ${await res.text()}`)
+    const ct = res.headers.get("content-type") || ""
+    return ct.includes("application/json") ? res.json() : res.text()
+  }
+}
+
+function loadFileValues(cwd, file) {
+  if (!file) return {}
+  const abs = path.resolve(cwd, file)
+  return parseDotEnv(fs.readFileSync(abs, "utf8"))
+}
+
+async function run(args, { cwd }) {
+  const [subcommand, ...tail] = args
+  const manifest = loadManifest(cwd)
+  const declared = declaredSecrets(manifest)
+
+  if (!subcommand || subcommand === "help" || subcommand === "--help") {
+    console.log("Usage: pltt secrets <init|list|set|rotate> [NAME] [--env staging]")
+    console.log("       pltt secrets set NAME --value <secret> --env staging")
+    console.log("       pltt secrets set NAME --secrets-file plugin-secrets.env --env staging")
+    return
+  }
+
+  if (subcommand === "init") {
+    const result = initLocalEnv(cwd, manifest)
+    console.log(`[pltt] wrote ${path.relative(cwd, result.localPath)}`)
+    console.log(`[pltt] wrote ${path.relative(cwd, result.examplePath)}`)
+    console.log("[pltt] updated .gitignore for local env files")
+    return
+  }
+
+  const { own, rest } = parseOwnFlags(tail)
+  const { flags } = parseFlags(rest)
+  let env
+  try {
+    env = resolveEnvironment({ cwd, flags })
+  } catch (err) {
+    console.error(`[pltt] ${err.message}`)
+    process.exit(1)
+  }
+  if (!env.token) {
+    console.error(`[pltt] no publish token for "${env.name}". Set $${env.token_env}.`)
+    process.exit(1)
+  }
+  const api = makeApi(env)
+
+  if (subcommand === "list") {
+    const response = await api(`/api/v1/appstore/plugins/${encodeURIComponent(manifest.id)}/secrets?env=${encodeURIComponent(env.name)}`)
+    for (const item of response.secrets || []) {
+      console.log(`${item.key}\tconfigured=${item.configured ? "yes" : "no"}\tupdated=${item.updated_at || "-"}`)
+    }
+    return
+  }
+
+  if (subcommand !== "set" && subcommand !== "rotate") {
+    console.error(`[pltt] unknown secrets command: ${subcommand}`)
+    process.exit(1)
+  }
+
+  const name = rest.find((item) => !item.startsWith("-"))
+  if (!name) {
+    console.error("[pltt] usage: pltt secrets set NAME --value <secret> [--env staging]")
+    process.exit(1)
+  }
+  const spec = declared[name]
+  if (spec && !spec.scope.includes("plugin")) {
+    console.error(`[pltt] ${name} is declared with scope ${spec.scope.join(",")}; only plugin-scope secrets are managed by this command.`)
+    process.exit(1)
+  }
+  const fileValues = loadFileValues(cwd, own.secretsFile)
+  const localValues = readDotEnvFile(path.join(cwd, ".palette", ".env.local"))
+  const value = own.value ?? fileValues[name] ?? process.env[name] ?? localValues[name]
+  if (!value) {
+    console.error(`[pltt] no value for ${name}. Pass --value, --secrets-file, or set $${name}.`)
+    process.exit(1)
+  }
+
+  await api(`/api/v1/appstore/plugins/${encodeURIComponent(manifest.id)}/secrets/${encodeURIComponent(name)}`, {
+    method: "PUT",
+    body: { value, environment: env.name },
+  })
+  console.log(`[pltt] ${subcommand === "rotate" ? "rotated" : "set"} ${name}=${redactValue(value)} for ${manifest.id} (${env.name})`)
+}
+
+module.exports = run

package/lib/commands/test.js

@@ -5,6 +5,7 @@ const path = require("path")
 const { spawnSync } = require("child_process")
 const { loadManifest, validateManifest, KNOWN_PERMISSIONS } = require("../manifest")
 const { bundleFrontend, bundleBackend } = require("../bundler")
+const { declaredSecrets, loadLocalEnv } = require("../secrets")
 const buildCommand = require("./build")
 
 const DEFAULT_FRONTEND_BUNDLE_LIMIT = 512 * 1024
@@ -601,6 +602,64 @@ function sandboxBridgeSmoke(cwd, manifest, out) {
   return 0
 }
 
+function checkDeclaredSecrets(cwd, manifest, out) {
+  const declared = declaredSecrets(manifest)
+  const names = Object.keys(declared)
+  if (names.length === 0) {
+    out.ok("no manifest secrets declared")
+    return 0
+  }
+  const localValues = loadLocalEnv(cwd, { apply: false })
+  let failures = 0
+  for (const [name, spec] of Object.entries(declared)) {
+    if (spec.scope.includes("dev") && spec.required && !localValues[name]) {
+      out.warn(
+        `required dev secret ${name} is missing from .palette/.env.local`,
+        "Run pltt secrets init and fill the local value before pltt dev.",
+        { secret: name, scope: spec.scope },
+      )
+    }
+    if (spec.scope.includes("plugin") && spec.required && !localValues[name] && !process.env[name]) {
+      out.warn(
+        `required plugin secret ${name} has no local value`,
+        "Set it before publish with an env var, --secrets-file, or pltt secrets set.",
+        { secret: name, scope: spec.scope },
+      )
+    }
+  }
+  if (!fs.existsSync(path.join(cwd, ".palette", ".env.local"))) {
+    out.warn(
+      ".palette/.env.local is missing",
+      "Run pltt secrets init to create local developer env files.",
+    )
+  } else {
+    out.ok(".palette/.env.local is present")
+  }
+  out.ok(`manifest declares ${names.length} secret(s)`, { secrets: names })
+  return failures
+}
+
+function checkFrontendSecretLeaks(cwd, frontendBuffer, manifest, out) {
+  const localValues = loadLocalEnv(cwd, { apply: false })
+  const declared = declaredSecrets(manifest)
+  let failures = 0
+  const bundleText = frontendBuffer.toString("utf8")
+  for (const [name, value] of Object.entries(localValues)) {
+    if (!value || String(value).length < 8) continue
+    const spec = declared[name]
+    const publicAllowed = name.startsWith("NEXT_PUBLIC_")
+    if (!publicAllowed && bundleText.includes(String(value))) {
+      failures += out.fail(
+        `frontend bundle contains local secret value for ${name}`,
+        "Move this value to backend ctx.secret(...) or rename it NEXT_PUBLIC_* only if it is intentionally public.",
+        { secret: name, declared_scope: spec?.scope },
+      )
+    }
+  }
+  if (failures === 0) out.ok("frontend local-secret leak scan passed")
+  return failures
+}
+
 async function run(args, { cwd }) {
   const json = args.includes("--json")
   let failures = 0
@@ -630,6 +689,7 @@ async function run(args, { cwd }) {
   failures += checkSdkCompatibility(cwd, manifest, out)
   failures += scanForbiddenImports(cwd, manifest, out)
   failures += checkSemverBump(cwd, manifest, out)
+  failures += checkDeclaredSecrets(cwd, manifest, out)
 
   for (const permission of manifest.permissions || []) {
     if (!KNOWN_PERMISSIONS.has(permission)) {
@@ -662,6 +722,7 @@ async function run(args, { cwd }) {
       const frontend = await bundleFrontend(cwd, manifest.frontend.entry, manifest.frontend)
       out.ok(`frontend bundles successfully (${frontend.length} bytes)`, { bytes: frontend.length })
       failures += checkBundleSize("frontend", frontend.length, out)
+      failures += checkFrontendSecretLeaks(cwd, frontend, manifest, out)
       failures += sandboxBridgeSmoke(cwd, manifest, out)
     } catch (err) {
       failures += out.fail(

package/lib/dev-simulator.js

@@ -7,6 +7,7 @@ const { spawn, spawnSync } = require("child_process")
 
 const { loadManifest } = require("./manifest")
 const { frontendBuildConfig } = require("./bundler")
+const { loadLocalEnv } = require("./secrets")
 
 function loadEsbuild() {
   try {
@@ -95,6 +96,7 @@ function writeBackendRunner(cwd, devDir, manifest, backendEntry) {
   const runner = path.join(devDir, "backend_runner.py")
   const sdkPath = localBackendSdkPath()
   const databasePath = path.join(devDir, `${manifest.id}.sqlite3`)
+  const devSecrets = loadLocalEnv(cwd, { apply: false })
   const content = `from __future__ import annotations
 
 import importlib
@@ -115,6 +117,7 @@ MANIFEST = json.loads(${JSON.stringify(JSON.stringify(manifest))})
 SDK_PATH = ${JSON.stringify(sdkPath || "")}
 DATABASE_ENABLED = bool(MANIFEST.get("database") or MANIFEST.get("capabilities", {}).get("database"))
 DATABASE_URL = os.environ.get("PALETTE_DEV_DATABASE_URL", "sqlite+aiosqlite:///${databasePath.replace(/\\/g, "/")}")
+DEV_SECRETS = json.loads(${JSON.stringify(JSON.stringify(devSecrets))})
 
 if SDK_PATH:
     sys.path.insert(0, SDK_PATH)
@@ -153,7 +156,11 @@ class DevPluginContextMiddleware(BaseHTTPMiddleware):
         request.state.org_role = "owner"
         request.state.plugin_id = MANIFEST.get("id", "")
         request.state.plugin_permissions = MANIFEST.get("permissions", [])
-        request.state.plugin_config = {}
+        request.state.plugin_config = {
+            "secrets": DEV_SECRETS,
+            "secret_specs": MANIFEST.get("secrets") or {},
+            "secret_scope": "dev",
+        }
         request.state.storage = None
         if SessionLocal is None:
             request.state.db = None

package/lib/environments.js

@@ -173,6 +173,7 @@ function parseFlags(argv) {
     url: undefined,
     token: undefined,
     default: true,
+    secretsFile: undefined,
   }
   const rest = []
   for (let i = 0; i < argv.length; i++) {
@@ -201,6 +202,10 @@ function parseFlags(argv) {
       flags.token = a.slice("--token=".length)
     } else if (a === "--no-default") {
       flags.default = false
+    } else if (a === "--secrets-file") {
+      flags.secretsFile = argv[++i]
+    } else if (a.startsWith("--secrets-file=")) {
+      flags.secretsFile = a.slice("--secrets-file=".length)
     } else {
       rest.push(a)
     }

package/lib/manifest.js

@@ -2,6 +2,7 @@
 
 const fs = require("fs")
 const path = require("path")
+const { SECRET_SCOPES } = require("./secrets")
 
 const MANIFEST_FILE = "palette-plugin.json"
 const SUPPORTED_MANIFEST_VERSIONS = ["1"]
@@ -46,6 +47,8 @@ const TOP_LEVEL_KEYS = new Set([
   "rate_limit",
   "database",
   "scheduled_jobs",
+  "secrets",
+  "platform_services",
 ])
 
 function loadManifest(cwd) {
@@ -104,6 +107,71 @@ function validateArray(value, label, errors) {
   if (value !== undefined && !Array.isArray(value)) errors.push(`${label} must be an array`)
 }
 
+function validateSecrets(value, errors) {
+  if (value === undefined) return
+  if (!isObject(value)) {
+    errors.push("secrets must be an object")
+    return
+  }
+  const allowed = new Set(["scope", "required", "label", "help", "validate"])
+  for (const [name, spec] of Object.entries(value)) {
+    const label = `secrets.${name}`
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(name)) {
+      errors.push(`${label} must be an uppercase environment-style name`)
+    }
+    if (!isObject(spec)) {
+      errors.push(`${label} must be an object`)
+      continue
+    }
+    unknownKeys(spec, allowed, label, errors)
+    const scopes = Array.isArray(spec.scope) ? spec.scope : [spec.scope || "dev"]
+    for (const scope of scopes) {
+      if (!SECRET_SCOPES.has(scope)) {
+        errors.push(`${label}.scope must be one of ${Array.from(SECRET_SCOPES).join(", ")}`)
+      }
+    }
+    requireBoolean(spec, "required", label, errors)
+    requireString(spec, "label", label, errors)
+    requireString(spec, "help", label, errors)
+    requireString(spec, "validate", label, errors)
+    if (spec.validate !== undefined) {
+      try {
+        new RegExp(spec.validate)
+      } catch (err) {
+        errors.push(`${label}.validate must be a valid regular expression`)
+      }
+    }
+  }
+}
+
+function validatePlatformServices(value, errors) {
+  if (value === undefined) return
+  const known = new Set(["llm", "kv", "storage"])
+  if (Array.isArray(value)) {
+    for (const service of value) {
+      if (!known.has(service)) errors.push(`platform_services contains unknown service: ${service}`)
+    }
+    return
+  }
+  if (!isObject(value)) {
+    errors.push("platform_services must be an array or object")
+    return
+  }
+  for (const [name, spec] of Object.entries(value)) {
+    if (!known.has(name)) errors.push(`platform_services.${name} is not supported`)
+    if (!isObject(spec)) {
+      errors.push(`platform_services.${name} must be an object`)
+      continue
+    }
+    unknownKeys(spec, new Set(["required", "billing"]), `platform_services.${name}`, errors)
+    requireBoolean(spec, "required", `platform_services.${name}`, errors)
+    requireString(spec, "billing", `platform_services.${name}`, errors)
+    if (spec.billing !== undefined && !["org_wallet", "plugin_owner", "platform"].includes(spec.billing)) {
+      errors.push(`platform_services.${name}.billing must be org_wallet, plugin_owner, or platform`)
+    }
+  }
+}
+
 function validateManifest(m) {
   const errors = []
   if (!isObject(m)) return ["manifest must be an object"]
@@ -169,6 +237,9 @@ function validateManifest(m) {
     errors.push("at least one of frontend, backend, or tools is required")
   }
 
+  validateSecrets(m.secrets, errors)
+  validatePlatformServices(m.platform_services, errors)
+
   if (m.sdk) {
     if (!isObject(m.sdk)) errors.push("sdk must be an object")
     else {

package/lib/secrets.js

@@ -0,0 +1,155 @@
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+
+const LOCAL_ENV_PATH = path.join(".palette", ".env.local")
+const EXAMPLE_ENV_PATH = path.join(".palette", ".env.example")
+const SECRET_SCOPES = new Set(["dev", "plugin", "install", "platform"])
+
+function parseDotEnv(src) {
+  const values = {}
+  for (const rawLine of String(src || "").split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (!line || line.startsWith("#")) continue
+    const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/)
+    if (!match) continue
+    let value = match[2] || ""
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+    values[match[1]] = value
+  }
+  return values
+}
+
+function readDotEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) return {}
+  return parseDotEnv(fs.readFileSync(filePath, "utf8"))
+}
+
+function writeDotEnvFile(filePath, values, manifest) {
+  const lines = [
+    "# Palette local developer secrets.",
+    "# This file is for pltt dev only and must not be committed.",
+    "",
+  ]
+  for (const [name, meta] of Object.entries(values)) {
+    const scope = Array.isArray(meta.scope) ? meta.scope.join(",") : meta.scope
+    lines.push(`# ${name}`)
+    lines.push(`# scope: ${scope || "dev"}`)
+    if (meta.label) lines.push(`# label: ${meta.label}`)
+    if (meta.help) lines.push(`# help: ${meta.help}`)
+    lines.push(`${name}=`)
+    lines.push("")
+  }
+  if (Object.keys(values).length === 0 && manifest?.id) {
+    lines.push(`# No secrets are declared by ${manifest.id}.`)
+    lines.push("")
+  }
+  fs.writeFileSync(filePath, lines.join("\n"))
+}
+
+function ensurePaletteDir(cwd) {
+  const dir = path.join(cwd, ".palette")
+  fs.mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+function ensureGitignore(cwd) {
+  const gitignorePath = path.join(cwd, ".gitignore")
+  const required = [
+    ".palette/.env.local",
+    ".palette/*.env",
+    ".env",
+    ".env.local",
+    ".env.production",
+  ]
+  let existing = ""
+  if (fs.existsSync(gitignorePath)) existing = fs.readFileSync(gitignorePath, "utf8")
+  const lines = existing ? existing.split(/\r?\n/) : []
+  let changed = false
+  for (const entry of required) {
+    if (!lines.includes(entry)) {
+      lines.push(entry)
+      changed = true
+    }
+  }
+  if (changed || !fs.existsSync(gitignorePath)) {
+    fs.writeFileSync(gitignorePath, lines.filter((line, index) => line || index < lines.length - 1).join("\n") + "\n")
+  }
+}
+
+function normalizeScope(scope) {
+  if (Array.isArray(scope)) return scope
+  if (typeof scope === "string") return [scope]
+  return ["dev"]
+}
+
+function declaredSecrets(manifest) {
+  const raw = manifest?.secrets || {}
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {}
+  const out = {}
+  for (const [name, meta] of Object.entries(raw)) {
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(name)) continue
+    const item = meta && typeof meta === "object" && !Array.isArray(meta) ? meta : {}
+    out[name] = {
+      ...item,
+      scope: normalizeScope(item.scope).filter((scope) => SECRET_SCOPES.has(scope)),
+      required: Boolean(item.required),
+    }
+    if (out[name].scope.length === 0) out[name].scope = ["dev"]
+  }
+  return out
+}
+
+function secretsForScope(manifest, scope) {
+  return Object.fromEntries(
+    Object.entries(declaredSecrets(manifest)).filter(([, meta]) => meta.scope.includes(scope)),
+  )
+}
+
+function initLocalEnv(cwd, manifest, { overwrite = false } = {}) {
+  ensurePaletteDir(cwd)
+  ensureGitignore(cwd)
+  const declared = declaredSecrets(manifest)
+  const localPath = path.join(cwd, LOCAL_ENV_PATH)
+  const examplePath = path.join(cwd, EXAMPLE_ENV_PATH)
+  if (overwrite || !fs.existsSync(localPath)) writeDotEnvFile(localPath, declared, manifest)
+  writeDotEnvFile(examplePath, declared, manifest)
+  return { localPath, examplePath, declared }
+}
+
+function loadLocalEnv(cwd, { apply = true } = {}) {
+  const values = readDotEnvFile(path.join(cwd, LOCAL_ENV_PATH))
+  if (apply) {
+    for (const [key, value] of Object.entries(values)) {
+      if (process.env[key] === undefined) process.env[key] = value
+    }
+  }
+  return values
+}
+
+function redactValue(value) {
+  if (!value) return ""
+  const str = String(value)
+  if (str.length <= 8) return "********"
+  return `${str.slice(0, 3)}…${str.slice(-3)}`
+}
+
+module.exports = {
+  EXAMPLE_ENV_PATH,
+  LOCAL_ENV_PATH,
+  SECRET_SCOPES,
+  declaredSecrets,
+  ensureGitignore,
+  initLocalEnv,
+  loadLocalEnv,
+  parseDotEnv,
+  readDotEnvFile,
+  redactValue,
+  secretsForScope,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.30",
+  "version": "0.3.31",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"