5587db2 · d5b2fe2 · 3b6d43c · 7cb7a65 · d88ff63 · 2fa0c24
@@ -921,10 +921,12 @@
Environment** (or `PUT /api/v1/repos/:owner/:name/app/env/:name` with a
`{ "value" }` body). A name is `ADMIN_PASSWORD`-shaped: capital letters,
digits and underscores; the names the forge sets itself (`PORT`, `HOST`,
`PATH`, `FORGE_*` and their kin) are refused, and the forge's own values
win regardless. Values are write-only: set one, and it is never shown
again — the page, the API and the event outbox carry the name and when it
was set, nothing more. At rest each value is sealed with the data
directory's key (`kernel/secret.ts`), bound to the app and the name.
win regardless. A setting is one of two **kinds**. A *variable* is a plain setting (a URL,
a switch): kept and listed in the clear, safe in a log. A *secret* is
sealed with the data directory's key (`kernel/secret.ts`), bound to the app
and the name, part of the sealing-key rotation, and write-only: the page,
the API and the event outbox carry its name and when it was set, nothing
more. Left unchosen, a setting is a secret; say `kind: variable` to keep one in the clear. Setting a name again replaces it, kind included.
An app that prints one does not show it either: what an app writes to its
output is searched for the values it was handed (its variables, its identity
key and its forge token, each plain, base64 and URL-encoded) before the line
@@ -950,6 +952,10 @@
where two apply the narrower one wins: a test key for
previews, the live one for production, and neither process ever holds the
other's. Every preview is one scope, whichever pull it serves.
### One place for a secret
A secret lives where it matches who may use it, and a forge admin grants a wider one to an app by name: see [features/app-secrets.md](features/app-secrets.md).
### Forge secrets
A credential the forge itself needs (a DNS token to spawn forges, a bucket
@@ -973,7 +979,14 @@
with write access, declares what a run may hold in front-matter at the top:
    secrets: [email protected], TF_BUCKET_KEY
    ---
Only declared names are resolved (`crew/grant.ts`); malformed names and names
Only declared names are resolved (`crew/grant.ts`), and from the repository's
own secrets or from a name the forge's owner granted to that repository
(`secret_grant`, the grant an app's start reads). A declared name that is set
at the organization or the forge and not granted is never opened: the run's
log and one comment on the issue say "this run asked for X; the forge's owner
has not granted X to owner/repo", with a link to grant it, whether X is set
higher up or nowhere (a declaration learns nothing about which names exist);
the run goes on without it. Malformed names and names
that would shadow the run's environment (`FORGE_*`, `GIT_*`, `PATH`, …) are
refused in the run's log. Values go into the run's env beside `FORGE_TOKEN`,
and `@host` widens the shell sandbox's egress for that run only. From the
@@ -53,7 +53,7 @@
bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
| `app_data_import` | — | Load a SQL dump into an app's database and report per-table counts and checksums; admins only | 339 |
| `app_deploy` | `redeploy`, `stop`, `pull`, `schedules`, `run_schedule`, `pause_schedule`, `resume_schedule`, `jobs`, `cancel_job`, `retry_job` | Redeploy or stop an env, pull, list and steer schedules and jobs | 408 |
| `app_domains` | — | App domains: list, add, check, keep, remove; dns_proof, dns_cut, dns_revert | 266 |
| `app_env` | `list`, `set`, `unset` | An app's environment variables: list names, set or unset by scope; write-only | 393 |
| `app_env` | `list`, `set`, `unset`, `variable`, `secret` | An app's environment variables: list, set or unset by scope; a secret is write-only, a variable is shown | 474 |
| `app_members` | — | People a private app names, who may enter it and its previews | 297 |
| `app_notes` | `hide`, `ban`, `unban` | Notes from an app's forge button and banned senders; hide a note, ban or unban its sender | 306 |
| `apps` | — | Apps you can see: live or not, where served, how each runs, what works | 384 |
@@ -6,3 +6,5 @@
a `<section class="settings-block">` with an `<h2>`, one muted sentence (sealed
was set, when it was last opened, Remove), and the set form as an `.edit-row`. No card around it, and no icon in a
row's lead. Values are write-only: the value field is a password input that is never filled. `test/secrets-card.test.ts`
renders all three places and finds the same class names. Classes used are named in `docs/design/areas/settings.md`.
Each row also says which apps use the secret and whether each started with its current value (`usedBy()` in `secrets.ts`, plain text in the row's meta; no new class). The app's settings carry a `settings-block` of `row()`s, "Secrets this app uses" (`web/pages/app_secrets.ts`), likewise with existing classes only.
@@ -0,0 +1,24 @@
# One place for a secret (`Settings → App → Secrets this app uses`)
Put a secret where it matches who may use it: on the new-app page or the
app's Environment (this app), an organization's page, or **Settings →
Secrets** (the whole forge). An app lists the names it needs in `forge.json`
(`"env": ["SIMPLEFIN_TOKEN"]`); at start each arrives from the nearest place
that has it — the app, then the organization, then the forge — the last two
only after a forge admin grants that name to that repository (**Settings →
App → Secrets this app uses**, one click, revocable; the grant is the
repository's, so a repository with no app holds one too and its crew's runs
read through the same row; the table says
needs / has / missing). A guest's preview nobody approved receives none of
it. Setting a wider secret again restarts every app it was granted to, and
its row on the Secrets page lists them and whether each started with the
current value. A secret typed on the new-app page is the app's own at once
and the first issue names it, never its value. Every open is a `secret.read`
event (the app and environment, the name, never the value).
## In the terminal
From a repository that is an app, the palette offers **Variables** (`src/tui/screens/appenv.ts`: `a` sets one, choosing its scope and whether it is a secret or a variable; the list shows each kind and a variable's value) and **Secrets this app uses** (`src/tui/screens/appsecrets.ts`: needs, has, missing; `a` grants, `x` revokes, a forge admin only).
Code: `src/core/app_secrets.ts`, `src/actions/secrets.ts` (`grantToRepo`, `revokeFromRepo`), `src/web/pages/app_secrets.ts`. Tests: `test/app-secrets.test.ts`, `test/app-secrets-web.test.ts`, `test/guest-pull.test.ts`.
@@ -30,6 +30,7 @@
export const APP_ENV_ERRORS: Record<string, string> = {
    "That name is the forge's own (PORT, HOST, PATH, FORGE_…); the app is already told it.",
  invalid_value: "A value is one line or many, never empty and under 64 KiB.",
  invalid_scope: "A variable goes everywhere, to production, or to previews.",
  invalid_kind: "A setting is a variable (plain, shown) or a secret (sealed, write-only).",
};
/** `setAppEnvVar` refused with a code the table does not name. */
@@ -37,3 +38,10 @@
export const APP_ENV_NOT_SET = "That variable could not be set.";
/** `deleteAppEnvVar` refused as `no_such_var`. */
export const APP_ENV_NO_SUCH = "No variable by that name.";
/** Why `grantToRepo` or `revokeFromRepo` refused, by code; page and terminal say it alike. */
export const GRANT_ERRORS: Record<string, string> = {
  not_found: "Only a forge admin can change a grant, and the repository must exist.",
  invalid_scope: "A grant draws from the forge or from the repository's organization.",
  no_such_secret: "No such secret is set there, or no such grant is held.",
};
@@ -49,6 +49,7 @@
import {
import {
  DEFAULT_ENV_SCOPE,
  deleteAppEnv,
  isReservedAppEnvName,
  isAppEnvScope,
  listAppEnvNames,
  setAppEnv,
@@ -56,6 +57,7 @@
import {
  type AppEnvName,
  type AppEnvScope,
} from "../core/app_env.ts";
import { isSecretName, VALUE_MAX } from "../core/secret_store.ts";
import { addCrew, getAgentByName } from "../core/agents.ts";
import { listAllAgents } from "./crew.ts";
import { plan, planIssueBody, planningAvailable } from "../crew/plan.ts";
@@ -170,30 +172,32 @@
export async function setAppEnvVar(
  name: string,
  value: string,
  scope: string = DEFAULT_ENV_SCOPE,
  /**
   * `variable` or `secret`; left out, a secret.
   */
  kind?: string,
): Promise<Result<AppEnvName, "not_found" | AppEnvError>> {
  const admin = requireRepoAdmin(app, actor, repo);
  if (!admin.ok) return admin;
  const record = getAppByRepo(app.db, repo.id);
  if (!record) return err("not_found");
  const set = setAppEnv(
    app.db,
    app.config.dataDir,
    record.id,
    name,
    value,
    scope,
  );
  const set = setAppEnv(app.db, app.config.dataDir, record.id, name, value, scope, kindFor(kind));
  if (!set.ok) return set;
  app.bus.append({
    kind: "app.env_set",
    repoId: repo.id,
    actorId: admin.value.id,
    payload: { name, scope: set.value.scope },
    payload: { name, scope: set.value.scope, kind: set.value.kind },
  });
  await redeployScope(app, record, repo, set.value.scope);
  return set;
}
/** The kind a person chose; left out, a secret: a plain variable is something one asks for. */
function kindFor(chosen: string | undefined): string {
  return chosen === undefined || chosen === "" || chosen === "auto" ? "secret" : chosen;
}
/** Remove a variable from a scope and redeploy the environments that read it. */
export async function deleteAppEnvVar(
  app: App,
@@ -277,6 +281,11 @@
export interface NewAppInput {
  pickAgent?: boolean;
  /** `owner/name` of a repository the actor can read: its tip is copied instead of the starter app. */
  template?: string;
  /**
   * Secrets typed while making the app: sealed at the app's own scope, so the first start has
   * them.
   */
  secrets?: readonly { readonly name: string; readonly value: string }[];
}
export interface NewAppResult {
@@ -295,7 +304,8 @@
export type NewAppError =
  | TemplateError
  | "no_such_agent"
  | "not_a_builder"
  | "app_limit";
  | "app_limit"
  | "invalid_secret";
/**
 * The golden path's first step, as one call: a repository with a working
@@ -320,6 +330,12 @@
export async function newApp(
  if (input.agent && !agent) return err("no_such_agent");
  if (agent && !agent.roles.includes("builder")) return err("not_a_builder");
  // A secret that cannot be sealed is refused before anything exists to take back.
  const secrets = (input.secrets ?? []).filter((x) => x.name !== "" || x.value !== "");
  for (const x of secrets)
    if (!isSecretName(x.name) || isReservedAppEnvName(x.name) || x.value === "" || x.value.length > VALUE_MAX || x.value.includes("\0"))
      return err("invalid_secret");
  // Refuse at the limit before a repository exists to take back.
  // The owner is resolved with the actor's rights, as createRepo does, so
  // the count of an account they may not create under is never told.
@@ -384,6 +400,16 @@
export async function newApp(
    return err(record.error === "not_found" ? "scaffold_failed" : record.error);
  }
  // Stored at the app's own scope: the first start has them, no second step.
  for (const x of secrets) setAppEnv(app.db, app.config.dataDir, record.value.id, x.name, x.value, "all", "secret");
  if (secrets.length > 0)
    app.bus.append({
      kind: "secret.set",
      repoId: repo.value.id,
      actorId: user.value.id,
      payload: { names: secrets.map((x) => x.name), scope: "all" },
    });
  const description = (input.description ?? "").trim();
  let chosen = agent;
  let body = description;
@@ -436,6 +462,8 @@
export async function newApp(
  }
  // The sentence is the one thing the person wrote: it opens the first
  // issue whether or not anyone was picked for it, unassigned when not.
  if (body !== "" && secrets.length > 0)
    body += `\n\nSecrets already set for this app (names only; read each from \`process.env\` and list it in forge.json \`env\`): ${secrets.map((x) => x.name).join(", ")}.`;
  if (body !== "") {
    const opened = openIssue(app, user.value, repo.value, {
      title: `Build ${input.name}`,
@@ -479,6 +507,8 @@
export const NEW_APP_ERRORS: Record<string, string> = {
  git_init_failed: REPO_INIT_FAILED,
  invalid_slug:
    "That name makes no usable hostname — start it with a letter or digit.",
  invalid_secret:
    "A secret needs a name (capital letters, digits and underscores, like SIMPLEFIN_TOKEN) and a value under 64 KiB.",
  slug_taken:
    "Another app already answers to that hostname. Pick another name.",
  already_app: "That repository is already an app.",
@@ -8,8 +8,16 @@
 */
import type { App } from "../app.ts";
import { createLog } from "../kernel/log.ts";
import { getOrg } from "../core/orgs.ts";
import { getRepo } from "../core/repos.ts";
import { getRepo, getRepoById } from "../core/repos.ts";
import { appsRuntime } from "../apps/runtime.ts";
import { getAppById, getAppByRepo } from "../core/apps.ts";
import { readerFor } from "../git/read.ts";
import { repoDir } from "../git/repos.ts";
import type { Repo } from "../core/repos.ts";
import { requireRepoAdmin } from "./access.ts";
import { neededNames, needRows, type NeedRow, appsUsing, grantable, grantSecret, revokeGrant, usesOf, type SecretUse } from "../core/app_secrets.ts";
import {
  deleteSecret,
  isSecretScope,
@@ -51,6 +59,8 @@
function admin(actor: User | undefined): Result<User, "not_found"> {
  return actor?.isAdmin ? ok(actor) : err("not_found");
}
const log = createLog("secrets");
export function listSecrets(
  app: App,
  actor: User | undefined,
@@ -91,9 +101,90 @@
export function putSecret(
    actorId: who.value.id,
    payload: { name, scope: target.value.scope },
  });
  restartUsers(app, target.value.scope, target.value.scopeId, name);
  return set;
}
/**
 * Setting a secret again is one change in one place; a process reads its
 * variables once at start, so each app it reaches starts again (previews
 * and production alike). Off the request: the person asked to store a value.
 */
export function restartUsers(app: App, scope: SecretScope, scopeId: string, name: string): void {
  for (const appId of appsUsing(app.db, scope, scopeId, name)) restartApp(app, appId);
}
function restartApp(app: App, appId: string): void {
  const record = getAppById(app.db, appId);
  const repo = record && getRepoById(app.db, record.repoId);
  if (!record || !repo) return;
  void appsRuntime(app)
    ?.reconcileApp(record, repo, "redeploy", undefined)
    .catch((error: unknown) => log.warn("app restart after a secret change failed", { app: appId, error: String(error) }));
}
/** Who a secret reaches and whether each started with its current value. */
export function secretUses(app: App, scope: SecretScope, scopeId: string, name: string): SecretUse[] {
  return usesOf(app.db, scope, scopeId, name);
}
/**
 * Grant a forge- or org-scope secret to one repository by name — its app and its crew's runs
 * both read through it: a forge admin's one click.
 */
export function grantToRepo(
  app: App,
  actor: User | undefined,
  scope: string,
  ref: string,
  name: string,
  repoId: string,
): Result<void, "not_found" | "invalid_scope" | "no_such_secret"> {
  const who = admin(actor);
  if (!who.ok) return who;
  if (scope !== "forge" && scope !== "org") return err("invalid_scope");
  const target = resolveTarget(app, scope, ref);
  if (!target.ok) return target;
  const repo = getRepoById(app.db, repoId);
  if (!repo) return err("not_found");
  if (!grantSecret(app.db, repo.id, scope, target.value.scopeId, name, who.value.id)) return err("no_such_secret");
  app.bus.append({
    kind: "secret.granted",
    repoId: repo.id,
    actorId: who.value.id,
    payload: { name, scope, repo: `${repo.ownerName}/${repo.name}` },
  });
  restartRepoApp(app, repo.id);
  return ok();
}
/** Take a grant back; an app stops receiving the name at its next start, which this brings now. */
export function revokeFromRepo(
  app: App,
  actor: User | undefined,
  name: string,
  repoId: string,
): Result<void, "not_found" | "no_such_secret"> {
  const who = admin(actor);
  if (!who.ok) return who;
  const repo = getRepoById(app.db, repoId);
  if (!repo) return err("not_found");
  if (!revokeGrant(app.db, repo.id, name)) return err("no_such_secret");
  app.bus.append({
    kind: "secret.revoked",
    repoId: repo.id,
    actorId: who.value.id,
    payload: { name, repo: `${repo.ownerName}/${repo.name}` },
  });
  restartRepoApp(app, repo.id);
  return ok();
}
function restartRepoApp(app: App, repoId: string): void {
  const record = getAppByRepo(app.db, repoId);
  if (record) restartApp(app, record.id);
}
export function removeSecret(
  app: App,
  actor: User | undefined,
@@ -115,3 +206,24 @@
export function removeSecret(
  });
  return ok();
}
/**
 * What an app asks for in `forge.json` `env`, against what is set: needs / has / missing, never
 * a value.
 */
export async function appSecretNeeds(
  app: App,
  actor: User | undefined,
  repo: Repo,
): Promise<Result<{ needs: NeedRow[]; grantable: { name: string; scope: "forge" | "org" }[] }, "not_found">> {
  const gate = requireRepoAdmin(app, actor, repo);
  if (!gate.ok) return gate;
  const record = getAppByRepo(app.db, repo.id);
  const file = await readerFor(repoDir(app.reposRoot, repo.ownerName, repo.name)).object("HEAD:forge.json");
  const text = file.ok && file.value.type === "blob" ? new TextDecoder().decode(file.value.body.slice(0, 65_536)) : undefined;
  const needs = needRows(app.db, { appId: record?.id ?? "", repoId: repo.id, ownerId: repo.ownerId, needs: neededNames(text) });
  const asked = new Set(needs.map((n) => n.name));
  // Names only, and only to a forge admin: what the crew or the app could be granted by name.
  const offer = actor?.isAdmin === true ? grantable(app.db, repo.id, repo.ownerId).filter((g) => !asked.has(g.name)) : [];
  return ok({ needs, grantable: offer });
}
@@ -10,6 +10,7 @@
 * simply not an app yet, which the surfaces say in those words.
 */
import { parseNeeds } from "../core/app_secrets.ts";
import { isIP } from "node:net";
import { err, ok, type Result } from "../kernel/result.ts";
import { parseService, type ServiceSpec } from "./service.ts";
@@ -79,6 +80,11 @@
export interface AppManifest {
   * out of the app's HTML pages. Unset is on.
   */
  readonly toolbar?: boolean | undefined;
  /**
   * `env` (top level of `forge.json`): the secret names the app reads from its environment
   * (`core/app_secrets.ts`).
   */
  readonly env?: readonly string[] | undefined;
  /**
   * `adapter` (top level of `forge.json`): the app is pulled from on a
   * schedule (`apps/adapter.ts`). Unset is not an adapter.
@@ -186,6 +192,8 @@
export function parseManifest(
  if (!egress.ok) return egress;
  const limits = limitsField(app, "app");
  if (!limits.ok) return limits;
  const needs = parseNeeds(parsed.value["env"]);
  if (!needs.ok) return invalid(needs.error);
  const toolbar = parsed.value["toolbar"];
  if (toolbar !== undefined && typeof toolbar !== "boolean")
    return invalid("forge.json: toolbar must be true or false");
@@ -235,6 +243,7 @@
export function parseManifest(
    egress: egress.value,
    limits: limits.value,
    toolbar: toolbar ?? true,
    ...(needs.value.length === 0 ? {} : { env: needs.value }),
    ...(adapter.value === undefined ? {} : { adapter: adapter.value }),
    ...(toolchain.value === undefined ? {} : { toolchain: toolchain.value }),
    ...(schedules.value.length === 0 ? {} : { schedules: schedules.value }),
@@ -30,6 +30,7 @@
import { join } from "node:path";
import type { App } from "../app.ts";
import { getAppByRepo, listApps, type AppRecord } from "../core/apps.ts";
import { resolveAppEnv } from "../core/app_env.ts";
import { neededNames, resolveAppSecrets } from "../core/app_secrets.ts";
import { featureVarsAt } from "./feature_env.ts";
import { getVariant, listVariants, variantOfBranch } from "../core/variants.ts";
import { readVariantValues } from "./variant_file.ts";
@@ -1878,6 +1879,27 @@
export class AppsRuntime {
    return featureVarsAt(this.app.db, this.app.config.dataDir, appId, forgeJson);
  }
  /**
   * The app's sealed secrets for a start: its own, and each granted name its forge.json asks
   * for.
   */
  sealedFor(repo: Repo, appId: string, env: EnvName, dir?: string, start = true): Record<string, string> {
    let forgeJson: string | undefined;
    try {
      forgeJson = dir === undefined ? undefined : readFileSync(join(dir, "forge.json"), "utf8");
    } catch {
      forgeJson = undefined;
    }
    return resolveAppSecrets(this.app.db, this.app.config.dataDir, this.app.bus, {
      appId,
      repoId: repo.id,
      ownerId: repo.ownerId,
      env,
      needs: neededNames(forgeJson),
      start,
    });
  }
  /**
   * What a process for `env` starts holding: the operator's variables, read
   * at start, and the forge token. A preview of a guest pull nobody has
@@ -1891,6 +1913,7 @@
export class AppsRuntime {
    env: EnvName,
    forgeToken: string | undefined,
    dir?: string,
    start = true,
  ): { vars: Record<string, string>; forgeToken: string | undefined } {
    const number = envPull(env);
    const pull =
@@ -1901,7 +1924,7 @@
export class AppsRuntime {
    // app's defaults; they are plain settings, never secrets.
    const own = dir !== undefined && envVariant(env) !== undefined ? readVariantValues(dir) : {};
    return {
      vars: { ...resolveAppEnv(this.app.db, this.app.config.dataDir, appId, env), ...own },
      vars: { ...this.sealedFor(repo, appId, env, dir, start), ...resolveAppEnv(this.app.db, this.app.config.dataDir, appId, env), ...own },
      forgeToken,
    };
  }
@@ -179,7 +179,7 @@
export async function runAppTty(
    // same secrets, so it is handed the same environment, by the one reader
    // the app's own process has. A guest pull's preview nobody has approved
    // holds none there, so its terminal (a command the pull names) holds none.
    vars: runtime.secretsFor(repo, target.app.id, target.env, undefined, live.dir).vars,
    vars: runtime.secretsFor(repo, target.app.id, target.env, undefined, live.dir, false).vars,
    // An absorbed app's settings, as its process was started with.
    feature: runtime.featureFor(repo, target.app.id, target.env, live.dir),
  });
@@ -41,10 +41,24 @@
export function scopeOfEnv(env: string): Exclude<AppEnvScope, "all"> {
  return env === "production" ? "production" : "preview";
}
/**
 * A variable is a plain setting, kept and shown in the clear; a secret is sealed and
 * write-only.
 */
export type AppEnvKind = "variable" | "secret";
export const APP_ENV_KINDS: readonly AppEnvKind[] = ["variable", "secret"];
export function isAppEnvKind(value: string): value is AppEnvKind {
  return (APP_ENV_KINDS as readonly string[]).includes(value);
}
export interface AppEnvName {
  readonly name: string;
  readonly scope: AppEnvScope;
  readonly updatedAt: string;
  readonly kind: AppEnvKind;
  /** A variable's value; a secret has none to show. */
  readonly value?: string;
}
/** `ADMIN_PASSWORD`, `STRIPE_SECRET_KEY`: the shell's own rule for a name. */
@@ -73,7 +87,8 @@
export type AppEnvError =
  | "invalid_name"
  | "reserved_name"
  | "invalid_value"
  | "invalid_scope";
  | "invalid_scope"
  | "invalid_kind";
export function isAppEnvName(name: string): boolean {
  return name.length > 0 && name.length <= NAME_MAX && NAME.test(name);
@@ -86,8 +101,11 @@
export function isReservedAppEnvName(name: string): boolean {
/** The names an app has set, alphabetical, widest scope first — never a value. */
export function listAppEnvNames(db: Database, appId: string): AppEnvName[] {
  return db
    .query<{ name: string; scope: string; updated_at: string }, [string]>(
      `SELECT name, scope, updated_at FROM app_env WHERE app_id = ?1
    .query<
      { name: string; scope: string; updated_at: string; kind: string; value_plain: string | null },
      [string]
    >(
      `SELECT name, scope, updated_at, kind, value_plain FROM app_env WHERE app_id = ?1
       ORDER BY name, CASE scope WHEN 'all' THEN 0 WHEN 'production' THEN 1 ELSE 2 END`,
    )
    .all(appId)
@@ -95,6 +113,8 @@
export function listAppEnvNames(db: Database, appId: string): AppEnvName[] {
      name: r.name,
      scope: isAppEnvScope(r.scope) ? r.scope : "all",
      updatedAt: r.updated_at,
      kind: r.kind === "variable" ? "variable" : "secret",
      ...(r.kind === "variable" ? { value: r.value_plain ?? "" } : {}),
    }));
}
@@ -106,26 +126,38 @@
export function setAppEnv(
  name: string,
  value: string,
  scope: string = "all",
  kind: string = "secret",
): Result<AppEnvName, AppEnvError> {
  if (!isAppEnvKind(kind)) return err("invalid_kind");
  if (!isAppEnvName(name)) return err("invalid_name");
  if (isReservedAppEnvName(name)) return err("reserved_name");
  if (!isAppEnvScope(scope)) return err("invalid_scope");
  // Empty would silently blank a secret; a NUL cannot cross execve.
  if (value === "" || value.length > VALUE_MAX || value.includes("\0"))
    return err("invalid_value");
  const sealed = kind === "secret";
  db.query(
    `INSERT INTO app_env (app_id, name, scope, value_enc) VALUES (?1, ?2, ?3, ?4)
    `INSERT INTO app_env (app_id, name, scope, value_enc, kind, value_plain) VALUES (?1, ?2, ?3, ?4, ?5, ?6)
     ON CONFLICT(app_id, name, scope) DO UPDATE SET
       value_enc = excluded.value_enc,
       kind = excluded.kind,
       value_plain = excluded.value_plain,
       updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`,
  ).run(appId, name, scope, seal(dataDir, value, aad(appId, name)));
  ).run(
    appId,
    name,
    scope,
    sealed ? seal(dataDir, value, aad(appId, name)) : "",
    kind,
    sealed ? null : value,
  );
  const row = db
    .query<
      { updated_at: string },
      [string, string, string]
    >("SELECT updated_at FROM app_env WHERE app_id = ?1 AND name = ?2 AND scope = ?3")
    .get(appId, name, scope)!;
  return ok({ name, scope, updatedAt: row.updated_at });
  return ok({ name, scope, updatedAt: row.updated_at, kind, ...(sealed ? {} : { value }) });
}
/** Remove a variable from one scope; the others keep theirs. */
@@ -161,15 +193,19 @@
export function resolveAppEnv(
  const own = scopeOfEnv(env);
  const rows = db
    .query<
      { name: string; scope: string; value_enc: string },
      { name: string; scope: string; value_enc: string; kind: string; value_plain: string | null },
      [string, string]
    >(
      `SELECT name, scope, value_enc FROM app_env
      `SELECT name, scope, value_enc, kind, value_plain FROM app_env
       WHERE app_id = ?1 AND scope IN ('all', ?2)
       ORDER BY name, CASE scope WHEN 'all' THEN 0 ELSE 1 END`,
    )
    .all(appId, own);
  for (const row of rows) {
    if (row.kind === "variable") {
      out[row.name] = row.value_plain ?? "";
      continue;
    }
    const opened = open(dataDir, row.value_enc, aad(appId, row.name));
    if (opened.ok) out[row.name] = opened.value;
    else
@@ -0,0 +1,265 @@
/**
 * One place for a secret (#12180) — the rows. An app names what it needs
 * (`forge.json` `env: ["SIMPLEFIN_TOKEN"]`); at start each name arrives
 * from the nearest place that has it: the app's own secret, then — only
 * once someone granted that name to this app (`secret_grant`) — the
 * organization's, then the forge's. The grant is the repository's: its app and its crew's runs
 * read through it, and a repository with no app can hold one. `secret_start` remembers which value
 * each environment last started with, so a rotation can say who has it.
 * Reads go through `resolveScoped`, so each is still an event.
 */
import type { Database } from "bun:sqlite";
import type { EventBus } from "./events.ts";
import {
  isSecretName,
  resolveScoped,
  type SecretScope,
} from "./secret_store.ts";
/** At most this many names an app may ask for. */
export const NEEDS_MAX = 64;
/** Validate `forge.json`'s `env`: an array of distinct secret-style names. */
export function parseNeeds(raw: unknown): { ok: true; value: string[] } | { ok: false; error: string } {
  if (raw === undefined) return { ok: true, value: [] };
  if (!Array.isArray(raw) || raw.length > NEEDS_MAX)
    return { ok: false, error: `forge.json: env must be an array of at most ${NEEDS_MAX} names` };
  const seen = new Set<string>();
  for (const n of raw) {
    if (typeof n !== "string" || !isSecretName(n) || n.startsWith("FORGE_"))
      return { ok: false, error: "forge.json: env names are capital letters, digits and underscores (SIMPLEFIN_TOKEN), never FORGE_…" };
    seen.add(n);
  }
  return { ok: true, value: [...seen] };
}
/** The names `forge.json` text asks for; nothing when it is absent or unreadable. */
export function neededNames(forgeJson: string | undefined): string[] {
  if (forgeJson === undefined) return [];
  try {
    const parsed: unknown = JSON.parse(forgeJson);
    if (typeof parsed !== "object" || parsed === null) return [];
    const needs = parseNeeds((parsed as Record<string, unknown>)["env"]);
    return needs.ok ? needs.value : [];
  } catch {
    return [];
  }
}
export interface Grant {
  readonly repoId: string;
  readonly name: string;
  readonly scope: "forge" | "org";
  readonly scopeId: string;
  readonly grantedBy: string;
  readonly grantedAt: string;
}
interface GrantRow {
  repo_id: string;
  name: string;
  scope: string;
  scope_id: string;
  granted_by: string;
  granted_at: string;
}
const toGrant = (r: GrantRow): Grant => ({
  repoId: r.repo_id,
  name: r.name,
  scope: r.scope as "forge" | "org",
  scopeId: r.scope_id,
  grantedBy: r.granted_by,
  grantedAt: r.granted_at,
});
export function listGrants(db: Database, repoId: string): Grant[] {
  return db
    .query<GrantRow, [string]>("SELECT * FROM secret_grant WHERE repo_id = ?1 ORDER BY name")
    .all(repoId)
    .map(toGrant);
}
/** Grant a forge- or org-scope name to a repository; false when no such secret is set there. */
export function grantSecret(
  db: Database,
  repoId: string,
  scope: "forge" | "org",
  scopeId: string,
  name: string,
  by: string,
): boolean {
  const owner = scope === "forge" ? "" : scopeId;
  const has = db
    .query("SELECT 1 FROM secret WHERE name = ?1 AND scope = ?2 AND scope_id = ?3")
    .get(name, scope, owner);
  if (!has) return false;
  db.query(
    `INSERT INTO secret_grant (repo_id, name, scope, scope_id, granted_by) VALUES (?1, ?2, ?3, ?4, ?5)
     ON CONFLICT(repo_id, name) DO UPDATE SET scope = excluded.scope, scope_id = excluded.scope_id,
       granted_by = excluded.granted_by, granted_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`,
  ).run(repoId, name, scope, owner, by);
  return true;
}
export function revokeGrant(db: Database, repoId: string, name: string): boolean {
  return db.query("DELETE FROM secret_grant WHERE repo_id = ?1 AND name = ?2").run(repoId, name).changes > 0;
}
/**
 * The app ids a secret reaches: the app that owns it, or each app of a repository it was granted
 * to.
 */
export function appsUsing(db: Database, scope: SecretScope, scopeId: string, name: string): string[] {
  if (scope === "repo")
    return db.query<{ id: string }, [string]>("SELECT id FROM app WHERE repo_id = ?1").all(scopeId).map((r) => r.id);
  return db
    .query<{ app_id: string }, [string, string, string]>(
      `SELECT app.id AS app_id FROM secret_grant g JOIN app ON app.repo_id = g.repo_id
       WHERE g.name = ?1 AND g.scope = ?2 AND g.scope_id = ?3 ORDER BY app.id`,
    )
    .all(name, scope, scope === "forge" ? "" : scopeId)
    .map((r) => r.app_id);
}
/** Who a secret reaches and what each environment last started with. */
export interface SecretUse {
  readonly appId: string;
  readonly slug: string;
  /** Environments that started with the current value, and when the latest did. */
  readonly current: boolean;
  readonly startedAt: string | null;
}
export function usesOf(db: Database, scope: SecretScope, scopeId: string, name: string): SecretUse[] {
  const owner = scope === "forge" ? "" : scopeId;
  const updated = db
    .query<{ updated_at: string }, [string, string, string]>(
      "SELECT updated_at FROM secret WHERE name = ?1 AND scope = ?2 AND scope_id = ?3",
    )
    .get(name, scope, owner)?.updated_at;
  return appsUsing(db, scope, scopeId, name).map((appId) => {
    const slug = db.query<{ slug: string }, [string]>("SELECT slug FROM app WHERE id = ?1").get(appId)?.slug ?? appId;
    const starts = db
      .query<{ value_updated_at: string; started_at: string }, [string, string, string]>(
        "SELECT value_updated_at, started_at FROM secret_start WHERE app_id = ?1 AND name = ?2 AND scope = ?3 ORDER BY started_at DESC",
      )
      .all(appId, name, scope);
    const latest = starts[0];
    return {
      appId,
      slug,
      current: latest !== undefined && updated !== undefined && latest.value_updated_at >= updated,
      startedAt: latest?.started_at ?? null,
    };
  });
}
export interface AppSecretInput {
  readonly appId: string;
  /** Where its grants are held. */
  readonly repoId: string;
  /** The repository's owner: the organization whose secrets may be granted. */
  readonly ownerId: string;
  readonly env: string;
  /** Names `forge.json` asks for. */
  readonly needs: readonly string[];
  /**
   * A start of the process (default): remember which value it began with. A terminal only
   * reads.
   */
  readonly start?: boolean;
}
/**
 * What an app's process starts with from the secret store: its own secrets
 * (every one, they are its settings), and each needed name that was granted
 * from the organization or the forge. Opens each through the resolver, so
 * each leaves a `secret.read` event, and records the start.
 */
export function resolveAppSecrets(
  db: Database,
  dataDir: string,
  bus: EventBus,
  input: AppSecretInput,
): Record<string, string> {
  const granted = new Map(listGrants(db, input.repoId).map((g) => [g.name, g]));
  const out: Record<string, string> = {};
  const who = { actor: undefined, run: `app:${input.appId}:${input.env}` };
  for (const name of input.needs) {
    const grant = granted.get(name);
    if (grant === undefined) continue;
    const found = resolveScoped(db, dataDir, bus, [name], {
      ...who,
      org: input.ownerId,
      only: [grant.scope],
    })[name];
    if (found === undefined) continue;
    out[name] = found.value;
    if (input.start === false) continue;
    const scopeId = found.scope === "org" ? input.ownerId : "";
    const row = db
      .query<{ updated_at: string }, [string, string, string]>(
        "SELECT updated_at FROM secret WHERE name = ?1 AND scope = ?2 AND scope_id = ?3",
      )
      .get(name, found.scope, scopeId);
    db.query(
      `INSERT INTO secret_start (app_id, name, env, scope, value_updated_at) VALUES (?1, ?2, ?3, ?4, ?5)
       ON CONFLICT(app_id, name, env) DO UPDATE SET scope = excluded.scope,
         value_updated_at = excluded.value_updated_at, started_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`,
    ).run(input.appId, name, input.env, found.scope, row?.updated_at ?? "");
  }
  return out;
}
export type NeedSource = "app" | "org" | "forge" | "available" | "missing";
export interface NeedRow {
  readonly name: string;
  /** Where the value comes from; `available` is set higher up but not granted yet. */
  readonly source: NeedSource;
  /** The scope a grant would draw from, when `available`. */
  readonly offer?: "forge" | "org";
}
const hasOwn = (db: Database, appId: string, name: string): boolean =>
  db.query("SELECT 1 FROM app_env WHERE app_id = ?1 AND name = ?2").get(appId, name) !== null;
/** needs / has / missing for each name the app asks for. */
export function needRows(db: Database, input: Omit<AppSecretInput, "env">): NeedRow[] {
  const has = (scope: SecretScope, id: string, name: string): boolean =>
    db.query("SELECT 1 FROM secret WHERE name = ?1 AND scope = ?2 AND scope_id = ?3").get(name, scope, id) !== null;
  const grants = new Map(listGrants(db, input.repoId).map((g) => [g.name, g]));
  return input.needs.map((name): NeedRow => {
    if (hasOwn(db, input.appId, name)) return { name, source: "app" };
    const g = grants.get(name);
    if (g !== undefined && has(g.scope, g.scopeId, name)) return { name, source: g.scope };
    if (has("org", input.ownerId, name)) return { name, source: "available", offer: "org" };
    if (has("forge", "", name)) return { name, source: "available", offer: "forge" };
    return { name, source: "missing" };
  });
}
/**
 * Names set at the organization or the forge that this repository has not been granted: what its
 * owner may grant, by name, from its settings. Names only.
 */
export function grantable(
  db: Database,
  repoId: string,
  ownerId: string,
): { name: string; scope: "forge" | "org" }[] {
  const held = new Set(listGrants(db, repoId).map((g) => g.name));
  const own = new Set(
    db
      .query<{ name: string }, [string]>("SELECT name FROM secret WHERE scope = 'repo' AND scope_id = ?1")
      .all(repoId)
      .map((r) => r.name),
  );
  return db
    .query<{ name: string; scope: "forge" | "org" }, [string]>(
      `SELECT name, scope FROM secret WHERE (scope = 'org' AND scope_id = ?1) OR scope = 'forge'
       ORDER BY name, CASE scope WHEN 'org' THEN 0 ELSE 1 END`,
    )
    .all(ownerId)
    .filter((r, i, all) => !held.has(r.name) && !own.has(r.name) && all.findIndex((x) => x.name === r.name) === i);
}
@@ -0,0 +1,1 @@
5e1b10dfc01758406da0a22faba885256eb5b3e4be5d2c36d8c70c60f797bbab
@@ -0,0 +1,1 @@
553ffb85a4d2595e8c1a8b0ceb7527206c15762ff047d2a44ba302d518bc113c
@@ -0,0 +1,26 @@
// One place for a secret (#12180). A secret at the forge or an organization reaches an app only
// after it is granted to that repository by name (`secret_grant`): its app and its crew's runs both
// read it, and a repository with no app can hold one. The repository's own scope (`secret` at scope
// 'repo') needs no grant. `secret_start` is the rotation ledger: which value of which secret each
// environment of each app last started with. Additive.
export default `
  CREATE TABLE IF NOT EXISTS secret_grant (
    repo_id    TEXT NOT NULL,
    name       TEXT NOT NULL,
    scope      TEXT NOT NULL CHECK (scope IN ('forge','org')),
    scope_id   TEXT NOT NULL DEFAULT '',
    granted_by TEXT NOT NULL,
    granted_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
    PRIMARY KEY (repo_id, name)
  );
  CREATE INDEX IF NOT EXISTS secret_grant_by_secret ON secret_grant(name, scope, scope_id);
  CREATE TABLE IF NOT EXISTS secret_start (
    app_id           TEXT NOT NULL,
    name             TEXT NOT NULL,
    env              TEXT NOT NULL,
    scope            TEXT NOT NULL,
    value_updated_at TEXT NOT NULL,
    started_at       TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
    PRIMARY KEY (app_id, name, env)
  );
  `;
@@ -0,0 +1,9 @@
// Two kinds in one list (#12180): an app's variables are plain settings (a URL, a switch), kept
// in the clear in `value_plain` and shown; its secrets are sealed in `value_enc`, write-only and
// in the sealing-key rotation. Every row that existed was sealed and stays a secret; setting one
// again as a variable converts it. A variable's `value_enc` is '' so the rotation, which skips
// what does not look sealed, never touches it. Additive.
export default `
  ALTER TABLE app_env ADD COLUMN kind TEXT NOT NULL DEFAULT 'secret' CHECK (kind IN ('variable','secret'));
  ALTER TABLE app_env ADD COLUMN value_plain TEXT;
  `;
@@ -138,6 +138,8 @@
export interface SecretReader {
  readonly run?: string | undefined;
  /** Open without a `secret.read` event or a `last_read_at` stamp; the caller audits what it chooses to. */
  readonly quiet?: boolean | undefined;
  /** Look only at these scopes (an app reads the wider ones only where granted). */
  readonly only?: readonly SecretScope[] | undefined;
}
/**
@@ -174,6 +176,11 @@
export function resolveScoped(
  if (who.repo) ladder.push(["repo", who.repo]);
  if (who.org) ladder.push(["org", who.org]);
  ladder.push(["forge", ""]);
  if (who.only) {
    const allowed = who.only;
    for (let i = ladder.length - 1; i >= 0; i--)
      if (!allowed.includes(ladder[i]![0])) ladder.splice(i, 1);
  }
  for (const name of names) {
    if (!isSecretName(name) || name in out) continue;
@@ -10,14 +10,24 @@
 * reach exactly those hosts, for that run only. Whatever is not declared is
 * not resolved, whatever is malformed or would shadow the run's own
 * environment is refused by name, and the values are held for redaction from
 * the moment they are opened until the grant is dropped.
 * the moment they are opened until the grant is dropped. A name reaches a
 * run from the repository's own secrets, or from the organization or the
 * forge only once the forge's owner granted that name to the repository
 * (`secret_grant`, the one grant an app's start reads too); a name asked for
 * and not granted is listed in `ungranted`, never opened.
 */
import type { Database } from "bun:sqlite";
import type { App } from "../app.ts";
import { addComment } from "../actions/issues.ts";
import { listComments, type Issue } from "../core/issues.ts";
import type { Repo } from "../core/repos.ts";
import type { User } from "../core/users.ts";
import type { EventBus } from "../core/events.ts";
import { listGrants } from "../core/app_secrets.ts";
import { recordGrant, releaseGrant } from "../core/run_secret.ts";
import { writeRefused } from "../core/cloud_account.ts";
import { isSecretName, resolveScoped } from "../core/secret_store.ts";
import { isSecretName, resolveScoped, type SecretScope } from "../core/secret_store.ts";
import { holdValues, releaseValues } from "../kernel/log.ts";
export interface Declaration {
@@ -87,8 +97,10 @@
export interface Grant {
  readonly names: readonly string[];
  /** Cloud credentials withheld because the run needs writes and they are not write allowed. */
  readonly writeRefused: readonly string[];
  /** Declared but set at no scope. */
  /** Declared but set at no scope this run may read, and at none higher up either. */
  readonly missing: readonly string[];
  /** Declared, set at the organization or the forge, and not granted to this repository. */
  readonly ungranted: readonly string[];
  /** Extra egress hosts for this run only. */
  readonly hosts: readonly string[];
  /** Drop the grant: values forgotten, record closed. Safe to call twice. */
@@ -107,15 +119,32 @@
export function grantSecrets(
    ? declared.names.filter((n) => writeRefused(db, n))
    : [];
  const asked = declared.names.filter((n) => !denied.includes(n));
  const found =
    asked.length === 0
      ? {}
      : resolveScoped(db, dataDir, bus, asked, {
          repo: run.repoId,
          org: run.ownerId,
          actor: run.actorId,
          run: run.id,
        });
  const who = { repo: run.repoId, actor: run.actorId, run: run.id };
  // Before anything is opened: the repository's own scope, then each name granted to it from
  // the one scope its grant names. Nothing else is read, so a declaration cannot reach further.
  const found: Record<string, { value: string; scope: SecretScope }> =
    asked.length === 0 ? {} : resolveScoped(db, dataDir, bus, asked, { ...who, only: ["repo"] });
  for (const g of listGrants(db, run.repoId)) {
    if (!asked.includes(g.name) || g.name in found) continue;
    Object.assign(
      found,
      resolveScoped(db, dataDir, bus, [g.name], {
        ...who,
        org: g.scopeId,
        only: [g.scope],
      }),
    );
  }
  const unset = asked.filter((n) => !(n in found));
  const higher = new Set(
    unset.filter((n) =>
      db
        .query(
          "SELECT 1 FROM secret WHERE name = ?1 AND (scope = 'forge' OR (scope = 'org' AND scope_id = ?2))",
        )
        .get(n, run.ownerId),
    ),
  );
  const names = Object.keys(found);
  const env = Object.fromEntries(names.map((n) => [n, found[n]!.value]));
  // Held before anything can log: a value is redacted from the first line.
@@ -131,7 +160,8 @@
export function grantSecrets(
    env,
    names,
    writeRefused: denied,
    missing: asked.filter((n) => !(n in found)),
    missing: unset.filter((n) => !higher.has(n)),
    ungranted: unset.filter((n) => higher.has(n)),
    // Only a secret that was actually granted widens the egress.
    hosts: [...new Set(names.flatMap((n) => declared.hostOf[n] ?? []))],
    release: () => {
@@ -140,3 +170,30 @@
export function grantSecrets(
    },
  };
}
/** The one sentence a run says for a name it asked for and the forge's owner has not granted. */
export function ungrantedSentence(name: string, repo: { ownerName: string; name: string }): string {
  return `this run asked for ${name}; the forge's owner has not granted ${name} to ${repo.ownerName}/${repo.name}`;
}
/**
 * Say it where the owner will see it: one comment on the issue, with the link that grants it,
 * once per name. The run goes on without the value.
 */
export function needsYou(
  app: App,
  agent: User,
  repo: Repo,
  issue: Issue,
  name: string,
): void {
  const sentence = ungrantedSentence(name, repo);
  if (listComments(app.db, issue.id).some((c) => c.body.startsWith(sentence))) return;
  addComment(
    app,
    agent,
    repo,
    issue,
    `${sentence}: [Grant it](/${repo.ownerName}/${repo.name}/settings/app#secrets)`,
  );
}
@@ -181,7 +181,7 @@
import {
import { trackAgentRun, untrackAgentRun } from "./running.ts";
import { installCacheEnv, sandboxPolicy } from "./sandbox.ts";
import { runGitAuth } from "./git_auth.ts";
import { grantSecrets, parseDeclaration, type Grant } from "./grant.ts";
import { grantSecrets, needsYou, parseDeclaration, ungrantedSentence, type Grant } from "./grant.ts";
import { historyHolds, scrubTree } from "./leak.ts";
import {
  installCacheDir,
@@ -1152,7 +1152,12 @@
async function work(
    }
    if (grant.names.length > 0)
      write(`secrets: holding ${grant.names.join(", ")} for this run`);
    for (const name of grant.missing) write(`secret not set: ${name}`);
    // One sentence for a name that is set higher up and one that is set nowhere: a declaration
    // must not tell its writer which names exist at the organization or the forge.
    for (const name of [...grant.missing, ...grant.ungranted]) {
      write(`${ungrantedSentence(name, repo)}: Grant it (Settings → App → Secrets)`);
      needsYou(app, agent.user, repo, issue, name);
    }
    for (const host of grant.hosts) write(`egress: +${host} for this run`);
    const bare = repoDir(app.reposRoot, repo.ownerName, repo.name);
    const forkBare = repoDir(
@@ -258,6 +258,7 @@
export function appRoutes(router: Router<Handler>): void {
      ctx.params.var ?? "",
      str(input.value),
      str(input.scope) || DEFAULT_ENV_SCOPE,
      str(input.kind),
    );
    if (!set.ok) return respondAccess(set.error, 422);
    return json(set.value);
@@ -5,9 +5,9 @@
import { DEFAULT_ENV_SCOPE } from "../../../core/app_env.ts";
export const tool: Tool = {
  name: "app_env",
  doc: "`{ repo, action, name?, value?, scope? }`: `list` an app's variable names and scopes, `set` one, or `unset` it, in `production` (default), `all` or `preview`; the API's rules and errors, an admin of the repository with an admin-scope token; a value is never read back",
  doc: "`{ repo, action, name?, value?, scope?, kind? }`: `list` an app's variables and secrets, `set` one, or `unset` it, in `production` (default), `all` or `preview`; `kind` is `variable` (plain, listed with its value) or `secret` (sealed, never read back; the default); the API's rules and errors, an admin of the repository with an admin-scope token",
  description:
    "An app's environment variables: list names, set or unset by scope; write-only. Admin.",
    "An app's environment variables: list, set or unset by scope; a secret is write-only, a variable is shown. Admin.",
  inputSchema: {
    type: "object",
    properties: {
@@ -16,6 +16,7 @@
export const tool: Tool = {
      name: { type: "string" },
      value: { type: "string" },
      scope: { type: "string", enum: ["all", "production", "preview"] },
      kind: { type: "string", enum: ["variable", "secret"] },
    },
    required: ["repo", "action"],
  },
@@ -39,7 +40,7 @@
export const tool: Tool = {
    }
    if (action === "set") {
      const value = typeof args["value"] === "string" ? args["value"] : "";
      const set = await setAppEnvVar(ctx.app, user, repo, name, value, scope);
      const set = await setAppEnvVar(ctx.app, user, repo, name, value, scope, typeof args["kind"] === "string" ? args["kind"] : undefined);
      return set.ok ? good(set.value) : refused(set.error);
    }
    if (action === "unset") {
@@ -5,6 +5,7 @@
 * verdict. Auth is resolved once per request and handed to handlers as data.
 */
import { appSecretGrant, appSecretRevoke } from "../web/pages/app_secrets.ts";
import { apiRoot } from "./api_root.ts";
import { isTokenScheme, tokenSecret } from "./token_header.ts";
import {
@@ -1624,6 +1625,8 @@
export function buildRouter(): Router<Handler> {
  router.add("POST", "/:owner/:name/settings/app/disable", appDisable);
  router.add("POST", "/:owner/:name/settings/app/members", appMembersUpdate);
  router.add("POST", "/:owner/:name/settings/app/env", appEnvSet);
  router.add("POST", "/:owner/:name/settings/app/secrets/grant", appSecretGrant);
  router.add("POST", "/:owner/:name/settings/app/secrets/revoke", appSecretRevoke);
  router.add(
    "POST",
    "/:owner/:name/settings/app/env/:var/delete",
@@ -265,7 +265,7 @@
export async function runDrill(deps: DrillDeps): Promise<DrillResult> {
        ? undefined
        : db
            .query<{ app_id: string; name: string; value_enc: string }, []>(
              "SELECT app_id, name, value_enc FROM app_env ORDER BY app_id, name LIMIT 1",
              "SELECT app_id, name, value_enc FROM app_env WHERE value_enc <> '' ORDER BY app_id, name LIMIT 1",
            )
            .get();
      // A forge with nothing sealed has nothing to open; that is not red.
@@ -96,7 +96,7 @@
async function sealedNames(dbFile: string): Promise<string[]> {
      .map((r) => `${r.name} (${r.scope} secret)`);
    const env = db
      .query<{ name: string; slug: string }, []>(
        "SELECT e.name AS name, a.slug AS slug FROM app_env e JOIN app a ON a.id = e.app_id ORDER BY a.slug, e.name",
        "SELECT e.name AS name, a.slug AS slug FROM app_env e JOIN app a ON a.id = e.app_id WHERE e.value_enc <> '' ORDER BY a.slug, e.name",
      )
      .all()
      .map((r) => `${r.name} (app ${r.slug})`);
@@ -45,7 +45,7 @@
export function appEnvCommands(f: Session, ctx: Ctx, repo: Repo | undefined): Co
    {
      id: "app-env",
      title: `${repo.ownerName}/${repo.name} — Variables`,
      hint: "the app's environment: names and scopes, never a value",
      hint: "the app's environment: variables shown, secrets never",
      run: () => ctx.push(appEnvScreen(f, ctx, repo)),
    },
  ];
@@ -90,14 +90,24 @@
export function appEnvScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
                  title: `Where ${name} goes`,
                  items: SCOPE_CHOICES.map((c) => ({ id: c.scope, label: c.label })),
                  onPick: ([scope]) =>
                    runAsync(ctx, async () => {
                      const set = await setAppEnvVar(f.app, f.user, repo, name, value, scope);
                      say(
                        set.ok
                          ? `${set.value.name} is set ${where(set.value)}.`
                          : (APP_ENV_ERRORS[set.error] ?? APP_ENV_NOT_SET),
                      );
                    }),
                    later(ctx, () =>
                      pickerScreen(ctx, screen, {
                        title: `What ${name} is`,
                        items: [
                          { id: "secret", label: "Secret", hint: "sealed, never shown again" },
                          { id: "variable", label: "Variable", hint: "plain, shown" },
                        ],
                        onPick: ([kind]) =>
                          runAsync(ctx, async () => {
                            const set = await setAppEnvVar(f.app, f.user, repo, name, value, scope, kind);
                            say(
                              set.ok
                                ? `${set.value.name} is set ${where(set.value)}.`
                                : (APP_ENV_ERRORS[set.error] ?? APP_ENV_NOT_SET),
                            );
                          }),
                      }),
                    ),
                }),
              ),
          }),
@@ -122,7 +132,9 @@
export function appEnvScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
  const lines = (): ListRow[] =>
    rows.map((v) => ({
      title: v.name,
      meta: `${SCOPE_WORDS[v.scope]} · set ${v.updatedAt.slice(0, 16).replace("T", " ")} UTC`,
      meta: `${v.kind} · ${SCOPE_WORDS[v.scope]} · set ${v.updatedAt.slice(0, 16).replace("T", " ")} UTC${
        v.kind === "variable" ? ` · ${v.value ?? ""}` : ""
      }`,
    }));
  const screen: Screen = {
@@ -142,7 +154,7 @@
export function appEnvScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
            ? "An app's variables are its admin's."
            : rows.length === 0
              ? `${repo.ownerName}/${repo.name} sets no variable. Press a to set one.`
              : `${rows.length} set for ${repo.ownerName}/${repo.name}; a value is never shown.`;
              : `${rows.length} set for ${repo.ownerName}/${repo.name}; a secret's value is never shown.`;
      // A refusal is the page's sentence, whole: it wraps rather than cuts.
      const said = wrap(text, Math.max(1, area.w)).slice(0, 3);
      const [head, list] = split(area, "v", [len(said.length), fill(1)]);
@@ -0,0 +1,107 @@
/**
 * What an app's secrets come from, in the terminal: the names its forge.json
 * asks for, and whether each is the app's own, granted from the organization
 * or the forge, set higher up and not granted, or missing. A forge admin grants
 * (`a`) or takes a grant back (`x`) through the same actions as the settings
 * page, refused in the same words; a repository's admin sees. Names only.
 */
import { GRANT_ERRORS } from "../../actions/app_env_words.ts";
import { appSecretNeeds, grantToRepo, revokeFromRepo } from "../../actions/secrets.ts";
import type { NeedRow } from "../../core/app_secrets.ts";
import { getAppByRepo } from "../../core/apps.ts";
import { canAdmin, type Repo } from "../../core/repos.ts";
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import type { Command } from "../app/palette.ts";
import { style } from "../term/style.ts";
import { wrap } from "../term/width.ts";
import { fill, len, split } from "../ui/layout.ts";
import type { Session } from "../session.ts";
import { ListState, drawList, runAsync, type ListRow } from "./common.ts";
const FROM: Record<NeedRow["source"], string> = {
  app: "this app's own",
  org: "granted from the organization",
  forge: "granted from the forge",
  available: "set higher up, not granted",
  missing: "missing",
};
/** The palette's "Secrets", for an admin of a repository that is an app. */
export function appSecretCommands(f: Session, ctx: Ctx, repo: Repo | undefined): Command[] {
  if (repo === undefined || f.user === undefined) return [];
  if (getAppByRepo(f.app.db, repo.id) === undefined || !canAdmin(f.app.db, repo, f.user)) return [];
  return [
    {
      id: "app-secrets",
      title: `${repo.ownerName}/${repo.name} — Secrets this app uses`,
      hint: "needs, has, missing; a forge admin grants",
      run: () => ctx.push(appSecretsScreen(f, ctx, repo)),
    },
  ];
}
export function appSecretsScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
  const state = new ListState();
  let rows: NeedRow[] = [];
  let readable = false;
  let note = "";
  const load = (): void => {
    runAsync(ctx, async () => {
      const got = await appSecretNeeds(f.app, f.user, repo);
      readable = got.ok;
      rows = got.ok ? [...got.value.needs, ...got.value.grantable.map((g): NeedRow => ({ name: g.name, source: "available", offer: g.scope }))] : [];
      state.clamp(rows.length);
      ctx.invalidate();
    });
  };
  load();
  const say = (text: string): void => {
    note = text;
    load();
  };
  const canGrant = f.user?.isAdmin === true;
  const screen: Screen = {
    title: "Secrets this app uses",
    get keys() {
      return [...(canGrant ? [binding(["a"], "grant"), binding(["x"], "revoke")] : []), binding(["j", "k"], "move cursor")];
    },
    render(area, s) {
      const c = ctx.theme.c;
      const text =
        note !== ""
          ? note
          : !readable
            ? "An app's secrets are its admin's."
            : rows.length === 0
              ? "Nothing is asked for or set higher up."
              : `${rows.length} for ${repo.ownerName}/${repo.name}; a value is never shown.`;
      const said = wrap(text, Math.max(1, area.w)).slice(0, 3);
      const [head, list] = split(area, "v", [len(said.length), fill(1)]);
      said.forEach((line, i) => s.text(head!.x, head!.y + i, line, style(c.mutedFg, c.bg), head!.x + head!.w));
      const lines: ListRow[] = rows.map((r) => ({ title: r.name, meta: FROM[r.source] }));
      drawList(s, list!, c, state, lines);
    },
    key(e) {
      if (state.key(e, rows.length)) return true;
      if (e.ctrl || e.alt || !readable) return false;
      const row = rows[state.index];
      if (row === undefined) return false;
      if (e.key === "a" && row.source === "available") {
        const scope = row.offer ?? "forge";
        const done = grantToRepo(f.app, f.user, scope, scope === "org" ? repo.ownerName : "", row.name, repo.id);
        say(done.ok ? `${row.name} is granted; the app starts again with it.` : (GRANT_ERRORS[done.error] ?? GRANT_ERRORS["not_found"]!));
        return true;
      }
      if (e.key === "x" && (row.source === "org" || row.source === "forge")) {
        const done = revokeFromRepo(f.app, f.user, row.name, repo.id);
        say(done.ok ? `${row.name} is no longer granted.` : (GRANT_ERRORS[done.error] ?? GRANT_ERRORS["not_found"]!));
        return true;
      }
      return false;
    },
  };
  return screen;
}
@@ -166,6 +166,7 @@
import { displayCommands } from "./display.ts";
import { iterationsCommands } from "./iterations.ts";
import { labelsCommands } from "./labels.ts";
import { appEnvCommands } from "./appenv.ts";
import { appSecretCommands } from "./appsecrets.ts";
import { appBackupCommands } from "./appbackup.ts";
import { variantsCommands } from "./variants.ts";
import { autonomyCommands } from "./autonomy.ts";
@@ -2000,6 +2001,7 @@
export function workspaceScreen(
      ...iterationsCommands(f, ctx, repo),
      ...displayCommands(f, ctx, repo),
      ...appEnvCommands(f, ctx, repo),
      ...appSecretCommands(f, ctx, repo),
      ...appBackupCommands(f, ctx, repo),
      ...variantsCommands(f, ctx, repo),
      ...autonomyCommands(f, ctx, repo),
@@ -0,0 +1,26 @@
/**
 * The gate a repository's admin-only settings pages share: the repository
 * only for someone who administers it, and a POST that is same-origin and
 * admin-scoped. A non-admin is told nothing.
 */
import { canAdmin, type Repo } from "../core/repos.ts";
import type { Ctx } from "../http/context.ts";
import { loadRepo, repoNotFound } from "./chrome.ts";
import { readForm, type Form } from "./form.ts";
/** The repo, but only for someone who administers it. */
export function loadAdminRepo(ctx: Ctx): Repo | undefined {
  const repo = loadRepo(ctx);
  if (!repo || !canAdmin(ctx.app.db, repo, ctx.auth.user)) return undefined;
  return repo;
}
/** The gate every settings POST passes: admin, same-origin, admin scope. */
export async function adminForm(ctx: Ctx): Promise<{ repo: Repo; form: Form } | Response> {
  const repo = loadAdminRepo(ctx);
  if (!repo) return repoNotFound(ctx);
  const form = await readForm(ctx, "admin");
  if (form instanceof Response) return form;
  return { repo, form };
}
@@ -0,0 +1,94 @@
/**
 * An app's secrets, as its settings say them: each name `forge.json` asks
 * for and where its value comes from, with one click for a forge admin to
 * grant one set higher up. Names only, never a value.
 */
import { GRANT_ERRORS } from "../../actions/app_env_words.ts";
import { grantToRepo, revokeFromRepo } from "../../actions/secrets.ts";
import type { NeedRow } from "../../core/app_secrets.ts";
import type { Ctx } from "../../http/context.ts";
import { field } from "../form.ts";
import { html, when, type Html } from "../html.ts";
import { flashTo } from "../layout.ts";
import { btn, row } from "../ui.ts";
import { repoBase } from "../chrome.ts";
import { adminForm } from "../admin_form.ts";
const FROM: Record<string, string> = {
  app: "this app's own secret",
  org: "the organization's, granted to this app",
  forge: "the forge's, granted to this app",
  available: "set higher up, not granted to this app",
  missing: "missing: not set anywhere this app may read",
};
/** The `needs / has / missing` table; `canGrant` is a forge admin. */
export function appSecretsView(
  base: string,
  needs: readonly NeedRow[],
  canGrant: boolean,
  grantable: readonly { name: string; scope: "forge" | "org" }[] = [],
): Html {
  const offered: NeedRow[] = grantable.map((g) => ({ name: g.name, source: "available", offer: g.scope }));
  const rows = [...needs, ...offered].map((n) =>
    row({
      title: html`<span class="mono">${n.name}</span>`,
      meta: html`${FROM[n.source]}`,
      trail: html`${when(
        n.source === "available" && canGrant,
        () => html`<form class="row-actions" method="post" action="${base}/settings/app/secrets/grant">
          <input type="hidden" name="name" value="${n.name}" />
          <input type="hidden" name="scope" value="${n.offer ?? "forge"}" />
          ${btn("Grant", { size: "sm", icon: "plus", label: `Grant ${n.name} to this app` })}
        </form>`,
      )}${when(
        (n.source === "org" || n.source === "forge") && canGrant,
        () => html`<form class="row-actions" method="post" action="${base}/settings/app/secrets/revoke">
          <input type="hidden" name="name" value="${n.name}" />
          ${btn("Revoke", { size: "sm", icon: "x", label: `Revoke ${n.name} from this app` })}
        </form>`,
      )}`,
    }),
  );
  return html`<section class="settings-block" id="secrets">
    <h2>Secrets this app uses</h2>
    <p class="muted small">Names this app asks for in <span class="mono">forge.json</span>, and where each comes from.</p>
    ${rows.length > 0
      
        sentinelcrew
        1d ago
        outdated
      
      Principle 1 and 8: this paragraph explains the mechanism a second time in long words. Replace it with one sentence, for example: "Names this app asks for in forge.json, and where each comes from."
    
      ? html`<ul class="list setting-list">${rows}</ul>`
      : html`<p class="muted small">Nothing is asked for or set higher up.</p>`}
  </section>`;
}
/** POST /:owner/:name/settings/app/secrets/grant */
export async function appSecretGrant(ctx: Ctx): Promise<Response> {
  const gate = await adminForm(ctx);
  if (gate instanceof Response) return gate;
  const { repo, form } = gate;
  const name = field(form, "name").trim();
  const scope = field(form, "scope");
  const done = grantToRepo(ctx.app, ctx.auth.user, scope, scope === "org" ? repo.ownerName : "", name, repo.id);
  return flashTo(
    ctx,
    `${repoBase(repo)}/settings/app#secrets`,
    done.ok
      ? { message: `${name} is granted to this repository: its app starts again with it, and its crew's next run may hold it.` }
      : { tone: "danger", message: GRANT_ERRORS[done.error] ?? GRANT_ERRORS["not_found"]! },
  );
}
/** POST /:owner/:name/settings/app/secrets/revoke */
export async function appSecretRevoke(ctx: Ctx): Promise<Response> {
  const gate = await adminForm(ctx);
  if (gate instanceof Response) return gate;
  const { repo, form } = gate;
  const name = field(form, "name").trim();
  const done = revokeFromRepo(ctx.app, ctx.auth.user, name, repo.id);
  return flashTo(
    ctx,
    `${repoBase(repo)}/settings/app#secrets`,
    done?.ok === true
      ? { message: `${name} is no longer granted; the app starts again without it, and the crew's next run goes without.` }
      : { tone: "danger", message: GRANT_ERRORS[done?.error ?? "not_found"] ?? GRANT_ERRORS["not_found"]! },
  );
}
@@ -443,6 +443,15 @@
function newAppForm(
                })),
              ],
            })}
        <fieldset class="stack mb">
          <legend class="muted small">Secrets the app needs (optional)</legend>
          ${[1, 2, 3].map(
            (n) => html`<div class="edit-row">
              <input class="input mono" type="text" name="secret_name_${String(n)}" placeholder="NAME" aria-label="Secret ${String(n)} name" pattern="[A-Z][A-Z0-9_]*" maxlength="128" autocomplete="off" spellcheck="false" />
              <input class="input" type="password" name="secret_value_${String(n)}" placeholder="Value" aria-label="Secret ${String(n)} value" autocomplete="off" />
            </div>`,
          )}
        </fieldset>
        <div class="form-actions">
          ${btn("Create app", { variant: "primary", icon: "rocket" })}
          ${btn("Cancel", { href: "/apps", variant: "ghost" })}
@@ -491,6 +500,10 @@
export async function newAppSubmit(ctx: Ctx): Promise<Response> {
    agent: field(form, "agent"),
    template: field(form, "template"),
  };
  const secrets = [1, 2, 3].map((n) => ({
    name: field(form, `secret_name_${n}`).trim(),
    value: field(form, `secret_value_${n}`),
  }));
  const pickAgent = values.agent === PICK_AGENT;
  // An explicit name is never second-guessed; left blank, the sentence
  // names the app — and the server derives that name itself (never trusting
@@ -499,6 +512,7 @@
export async function newAppSubmit(ctx: Ctx): Promise<Response> {
  const rest = {
    owner: values.owner,
    visibility: values.visibility === "public" ? "public" : "private",
    secrets,
    ...(values.template ? { template: values.template } : {}),
    ...(pickAgent
      ? { pickAgent: true }
@@ -14,7 +14,7 @@
import type { Ctx } from "../../http/context.ts";
import { loadRepo, repoBase, repoNotFound } from "../chrome.ts";
import { field } from "../form.ts";
import { flashTo, redirect } from "../layout.ts";
import { adminForm } from "./settings.ts";
import { adminForm } from "../admin_form.ts";
import { saveGrants } from "./subscriptions.ts";
// GET /:owner/:name/settings/crew
@@ -15,7 +15,8 @@
import { html } from "../html.ts";
import { flashTo } from "../layout.ts";
import { confirmAction } from "../ui.ts";
import { detachSection } from "./detach.ts";
import { adminForm, settingsPageResponse, timedAdminRepo } from "./settings.ts";
import { adminForm } from "../admin_form.ts";
import { settingsPageResponse, timedAdminRepo } from "./settings.ts";
export function dangerPage(ctx: Ctx): Response {
  const repo = timedAdminRepo(ctx);
@@ -18,7 +18,7 @@
import { icon } from "../icons.ts";
import { flashTo } from "../layout.ts";
import { confirmAction, timeAgo } from "../ui.ts";
import type { Database } from "bun:sqlite";
import { adminForm } from "./settings.ts";
import { adminForm } from "../admin_form.ts";
/** What the detach section shows: plain data, read by `detachSection`. */
export interface DetachView {
@@ -14,7 +14,7 @@
import { err, type Result } from "../../kernel/result.ts";
import { repoBase } from "../chrome.ts";
import { field, type Form } from "../form.ts";
import { flashTo } from "../layout.ts";
import { adminForm } from "./settings.ts";
import { adminForm } from "../admin_form.ts";
export async function fileHoldUpdate(ctx: Ctx): Promise<Response> {
  const gate = await adminForm(ctx);
@@ -25,7 +25,8 @@
import {
  row,
  time,
} from "../ui.ts";
import { adminForm, settingsPageResponse, timedAdminRepo } from "./settings.ts";
import { adminForm } from "../admin_form.ts";
import { settingsPageResponse, timedAdminRepo } from "./settings.ts";
/**
 * A writer who is not an admin follows the feed's failing-webhook line here:
@@ -15,7 +15,8 @@
import { field, type Form } from "../form.ts";
import { html, type Html } from "../html.ts";
import { flashTo } from "../layout.ts";
import { btn, confirmAction, empty, labelChip, labelCss, row } from "../ui.ts";
import { adminForm, settingsPageResponse, timedAdminRepo } from "./settings.ts";
import { adminForm } from "../admin_form.ts";
import { settingsPageResponse, timedAdminRepo } from "./settings.ts";
import { BIND, countAttr } from "../bind.ts";
/** `<input type="color">` submits `#rrggbb`; the store keeps six hex digits. */
@@ -29,7 +29,8 @@
import {
  time,
  timeAgo,
} from "../ui.ts";
import { adminForm, settingsPageResponse, timedAdminRepo } from "./settings.ts";
import { adminForm } from "../admin_form.ts";
import { settingsPageResponse, timedAdminRepo } from "./settings.ts";
const PROMPT_ERRORS: Record<string, string> = {
  invalid_at: "The time is hours and minutes in UTC, like 15:00.",
@@ -7,7 +7,8 @@
 * when something last opened it.
 */
import { listSecrets, putSecret, removeSecret } from "../../actions/secrets.ts";
import type { SecretUse } from "../../core/app_secrets.ts";
import { listSecrets, putSecret, removeSecret, secretUses } from "../../actions/secrets.ts";
import type { Ctx } from "../../http/context.ts";
import {
  notePhase,
@@ -45,11 +46,27 @@
function backTo(scope: string, ref: string): string {
  return "/settings/secrets";
}
/**
 * `· used by notes (started with this value 2 min ago), budget (restarting)`: who a secret
 * reaches.
 */
function usedBy(users: readonly SecretUse[]): Html {
  if (users.length === 0) return html``;
  return html` · used by ${users.map((u, i) => html`${i > 0 ? ", " : ""}<span class="mono">${u.slug}</span> ${
    u.startedAt === null
      ? "(not started with it yet)"
      : u.current
        ? html`(started with this value ${time(u.startedAt)})`
        : html`(still on an older value since ${time(u.startedAt)})`
  }`)}`;
}
/** The card: names, never values, and a form to set one. */
export function secretsCard(
  scope: SecretScope,
  ref: string,
  names: SecretName[],
  uses: ReadonlyMap<string, readonly SecretUse[]> = new Map(),
): Html {
  const rows = names.map((s) =>
    row({
@@ -59,7 +76,7 @@
export function secretsCard(
        s.lastReadAt === null
          ? "never used"
          : html`last used ${time(s.lastReadAt)}`
      }`,
      }${usedBy(uses.get(s.name) ?? [])}`,
      trail: html`<form
        class="row-actions"
        method="post"
@@ -122,7 +139,11 @@
export function secretsSection(
  ref: string,
): Html | null {
  const names = listSecrets(ctx.app, ctx.auth.user, scope, ref);
  return names.ok ? secretsCard(scope, ref, names.value) : null;
  if (!names.ok) return null;
  const uses = new Map(
    names.value.map((n) => [n.name, secretUses(ctx.app, n.scope, n.scopeId, n.name)] as const),
  );
  return secretsCard(scope, ref, names.value, uses);
}
function requireAdmin(ctx: Ctx): Response | undefined {
@@ -16,6 +16,7 @@
import {
  deleteAppEnvVar,
  disableApp,
  enableApp,
  listAppEnv,
  setAppEnvVar,
  updateAppSettings,
} from "../../actions/apps.ts";
@@ -43,7 +44,6 @@
import { blockedNote } from "../studio/blocked.ts";
import type { DnsRecord } from "../../apps/domains.ts";
import {
  DEFAULT_ENV_SCOPE,
  listAppEnvNames,
  NAME_MAX,
  type AppEnvName,
} from "../../core/app_env.ts";
@@ -72,7 +72,7 @@
import {
  readAppMembers,
  setAppMembersThrough,
} from "../../actions/app_members.ts";
import { canAdmin, type Repo } from "../../core/repos.ts";
import type { Repo } from "../../core/repos.ts";
import { stopMirroring } from "../../actions/mirror_target.ts";
import { getMirrorTarget, mirrorLine } from "../../core/migrate_mirror.ts";
import { listRefs } from "../../git/read.ts";
@@ -87,11 +87,15 @@
import {
  repoPalette,
  settingsLayout,
} from "../chrome.ts";
import { adminForm, loadAdminRepo } from "../admin_form.ts";
import { daySpark } from "../studio/kpi_row.ts";
import { settingsLead, teamJs } from "../studio/crew.ts";
import { pageTitle } from "../studio/nouns.ts";
import { appHref } from "./apps.ts";
import { field, readForm, type Form } from "../form.ts";
import { appSecretsView } from "./app_secrets.ts";
import { appSecretNeeds } from "../../actions/secrets.ts";
import type { NeedRow } from "../../core/app_secrets.ts";
import { field } from "../form.ts";
import { html, raw, when, type Html } from "../html.ts";
import { settingLine, toggleLine } from "../setting_line.ts";
import { NOT_CHANGED } from "../edit_words.ts";
@@ -128,14 +132,6 @@
type Section =
  | "machines"
  | "danger";
/** The repo, but only for someone who administers it. A non-admin is told
 * nothing — the settings tab is not even rendered for them. */
function loadAdminRepo(ctx: Ctx): Repo | undefined {
  const repo = loadRepo(ctx);
  if (!repo || !canAdmin(ctx.app.db, repo, ctx.auth.user)) return undefined;
  return repo;
}
/** `loadAdminRepo` for a GET page: names the session, then the repo read as `repo`. */
export function timedAdminRepo(ctx: Ctx): Repo | undefined {
  nameFrame(ctx.request);
@@ -215,17 +211,6 @@
export function settingsPageResponse(
  );
}
/** The gate every settings POST passes: admin, same-origin, admin scope. */
export async function adminForm(
  ctx: Ctx,
): Promise<{ repo: Repo; form: Form } | Response> {
  const repo = loadAdminRepo(ctx);
  if (!repo) return repoNotFound(ctx);
  const form = await readForm(ctx, "admin");
  if (form instanceof Response) return form;
  return { repo, form };
}
// ---- general ----
/**
@@ -663,6 +648,7 @@
function appSettingsView(
  error?: string,
  egress?: EgressView,
  blocked?: BlockedView,
  needs?: { needs: readonly NeedRow[]; grantable: { name: string; scope: "forge" | "org" }[] },
): Html {
  const base = repoBase(repo);
  const runtime = appsRuntime(ctx.app);
@@ -777,8 +763,9 @@
function appSettingsView(
    <div class="mt">${appVisitorsView(vitals)}</div>
    <div class="mt">${statement}</div>
    <div class="mt">
      ${appEnvView(base, listAppEnvNames(ctx.app.db, record.id))}
      ${appEnvView(base, (() => { const l = listAppEnv(ctx.app, ctx.auth.user, repo); return l.ok ? l.value : []; })())}
    </div>
    ${when(needs !== undefined, () => html`<div class="mt">${appSecretsView(base, needs!.needs, ctx.auth.user?.isAdmin === true, needs!.grantable)}</div>`)}
    <div class="mt">
      ${appDomainsView(base, domains.ok ? domains.value : undefined)}
    </div>
@@ -842,7 +829,9 @@
export function appEnvView(base: string, names: AppEnvName[]): Html {
    row({
      lead: icon("key"),
      title: html`<span class="mono">${v.name}</span>`,
      meta: html`${SCOPE_WORDS[v.scope]} · set ${time(v.updatedAt)}`,
      meta: html`${v.kind === "secret" ? "secret" : "variable"} · ${SCOPE_WORDS[v.scope]} · set ${time(v.updatedAt)}${
        v.kind === "variable" ? html` · <span class="mono">${v.value ?? ""}</span>` : html``
      }`,
      trail: html`<form
        class="row-actions"
        method="post"
@@ -888,6 +877,10 @@
export function appEnvView(base: string, names: AppEnvName[]): Html {
          autocomplete="off"
          required
        />
        <select class="input" name="kind" aria-label="Kind">
          <option value="secret">Secret (sealed, never shown)</option>
          <option value="variable">Variable (plain, shown)</option>
        </select>
        <select class="input" name="scope" aria-label="Where it applies">
          <option value="production">Production only</option>
          <option value="all">Also in previews</option>
@@ -895,6 +888,7 @@
export function appEnvView(base: string, names: AppEnvName[]): Html {
        </select>
        ${btn("Set", { variant: "primary", size: "sm", icon: "plus" })}
      </form>
      <p class="muted small mt">A secret is sealed and never shown again; choose Variable only for a value that is safe to read.</p>
  </section>`;
}
@@ -1067,6 +1061,7 @@
export async function appSettingsPage(ctx: Ctx): Promise<Response> {
      : await egressView(ctx.app, ctx.auth.user, repo);
  const blockedBase = record === undefined ? undefined : blockedView(ctx.app, ctx.auth.user, repo);
  const blocked = blockedBase?.ok ? { ok: true as const, value: await withLiveOnly(ctx.app, repo, blockedBase.value) } : blockedBase;
  const needs = await appSecretNeeds(ctx.app, ctx.auth.user, repo);
  const view = appSettingsView(
    ctx,
    repo,
@@ -1075,6 +1070,7 @@
export async function appSettingsPage(ctx: Ctx): Promise<Response> {
    undefined,
    egress?.ok ? egress.value : undefined,
    blocked?.ok ? blocked.value : undefined,
    needs?.ok ? needs.value : undefined,
  );
  const rendering = performance.now();
  const response = settingsPageResponse(ctx, repo, "app", "App", view);
@@ -1197,6 +1193,7 @@
export async function appEnvSet(ctx: Ctx): Promise<Response> {
    name,
    field(form, "value"),
    field(form, "scope") || DEFAULT_ENV_SCOPE,
    field(form, "kind"),
  );
  if (!set.ok && set.error === "not_found") return repoNotFound(ctx);
  return flashTo(
@@ -0,0 +1,123 @@
/**
 * One place for a secret, on the page (#12180): the app's settings say
 * needs / has / missing from what forge.json asks for; a forge admin
 * grants a forge secret with one click and it is listed on the Secrets
 * page with the app that uses it; a person who is not a forge admin is
 * shown the table but cannot grant, and an app that was not granted
 * stays without it.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { newApp } from "../src/actions/apps.ts";
import { commitToBranch } from "../src/actions/repos.ts";
import { putSecret } from "../src/actions/secrets.ts";
import { listGrants } from "../src/core/app_secrets.ts";
import { createSession } from "../src/core/sessions.ts";
import { createUser, type User } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { quietLogs } from "./helpers/globals.ts";
import { seedAdmin } from "./helpers/admin.ts";
quietLogs();
const words = (html: string): string => html.replace(/\s+/g, " ");
describe("secrets on the app's settings page", () => {
  let dataDir = "";
  let app: App;
  let servers: Servers;
  let base = "";
  let admin: User;
  let bob: User;
  let adminCookie = "";
  let bobCookie = "";
  let appId = "";
  const call = (cookie: string, path: string, form?: Record<string, string>): Promise<Response> =>
    fetch(`${base}${path}`, {
      method: form ? "POST" : "GET",
      headers: { cookie, ...(form ? { origin: base } : {}) },
      redirect: "manual",
      ...(form ? { body: new URLSearchParams(form) } : {}),
    });
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-app-secrets-web-"));
    app = createApp({ dataDir, port: 0 });
    servers = await serve(app);
    base = servers.url;
    const a = await seedAdmin(app, { username: "alice", email: "[email protected]", password: "a-good-passphrase" });
    if (!a.ok) throw new Error(a.error);
    admin = a.value;
    const o = await createUser(app.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: "a-good-passphrase" });
    if (!o.ok) throw new Error(o.error);
    bob = o.value;
    adminCookie = `forge_session=${createSession(app.db, admin.id).token}`;
    bobCookie = `forge_session=${createSession(app.db, bob.id).token}`;
    const made = await newApp(app, admin, { name: "budgeting", secrets: [{ name: "OWN_KEY", value: "own" }] });
    if (!made.ok) throw new Error(made.error);
    appId = made.value.repo.id;
    const files = await commitToBranch(app, admin, made.value.repo, {
      message: "Ask for secrets",
      files: [
        {
          path: "forge.json",
          content: JSON.stringify({ app: { run: "bun run src/server.ts" }, env: ["SIMPLEFIN_TOKEN", "OWN_KEY", "NOWHERE_KEY"] }),
        },
      ],
    });
    if (!files.ok) throw new Error(String(files.error));
    expect(putSecret(app, admin, "forge", "", "SIMPLEFIN_TOKEN", "sf-secret").ok).toBe(true);
  });
  afterAll(async () => {
    servers.stop();
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("the table says app, available and missing; a person who cannot administer the app is shown nothing and cannot grant", async () => {
    const page = words(await (await call(adminCookie, "/alice/budgeting/settings/app")).text());
    expect(page).toContain("Secrets this app uses");
    expect(page).toContain("OWN_KEY");
    expect(page).toContain("own secret");
    expect(page).toContain("set higher up, not granted to this app");
    expect(page).toContain("missing: not set anywhere this app may read");
    expect(page).not.toContain("sf-secret");
    expect((await call(bobCookie, "/alice/budgeting/settings/app")).status).toBe(404);
    const refused = await call(bobCookie, "/alice/budgeting/settings/app/secrets/grant", { name: "SIMPLEFIN_TOKEN", scope: "forge" });
    expect(refused.status).toBe(404);
    expect(listGrants(app.db, appId)).toEqual([]);
  });
  test("a forge admin grants with one click, and the Secrets page lists the app", async () => {
    const before = words(await (await call(adminCookie, "/alice/budgeting/settings/app")).text());
    expect(before).toContain("Grant SIMPLEFIN_TOKEN to this app");
    const granted = await call(adminCookie, "/alice/budgeting/settings/app/secrets/grant", { name: "SIMPLEFIN_TOKEN", scope: "forge" });
    expect(granted.status).toBe(303);
    expect(listGrants(app.db, appId).map((g) => g.name)).toEqual(["SIMPLEFIN_TOKEN"]);
    const after = words(await (await call(adminCookie, "/alice/budgeting/settings/app")).text());
    expect(after).toContain("granted to this app");
    const secrets = words(await (await call(adminCookie, "/settings/secrets")).text());
    expect(secrets).toContain("used by");
    expect(secrets).toContain("budgeting");
    expect(secrets).not.toContain("sf-secret");
    const revoked = await call(adminCookie, "/alice/budgeting/settings/app/secrets/revoke", { name: "SIMPLEFIN_TOKEN" });
    expect(revoked.status).toBe(303);
    expect(listGrants(app.db, appId)).toEqual([]);
  });
  test("a cross-origin grant is refused", async () => {
    const response = await fetch(`${base}/alice/budgeting/settings/app/secrets/grant`, {
      method: "POST",
      headers: { cookie: adminCookie, origin: "http://evil.test" },
      redirect: "manual",
      body: new URLSearchParams({ name: "SIMPLEFIN_TOKEN", scope: "forge" }),
    });
    expect(response.status).toBeGreaterThanOrEqual(400);
    expect(listGrants(app.db, appId)).toEqual([]);
  });
});
@@ -0,0 +1,232 @@
/**
 * One place for a secret (#12180): a secret typed on the new-app page reaches
 * the app's process with no second step; a forge-scope one reaches only the
 * apps it was granted to, and setting it again reaches each of them, the
 * row saying who and whether they started with the current value; the app's
 * settings and the Secrets page list the same rows.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { listAppEnv, newApp, setAppEnvVar, deleteAppEnvVar } from "../src/actions/apps.ts";
import { grantToRepo, putSecret, revokeFromRepo } from "../src/actions/secrets.ts";
import { resolveAppEnv, setAppEnv } from "../src/core/app_env.ts";
import {
  needRows,
  neededNames,
  parseNeeds,
  resolveAppSecrets,
  usesOf,
} from "../src/core/app_secrets.ts";
import { getAppByRepo, type AppRecord } from "../src/core/apps.ts";
import { listIssues } from "../src/core/issues.ts";
import { parseManifest } from "../src/apps/manifest.ts";
import type { Repo } from "../src/core/repos.ts";
import { createUser, type User } from "../src/core/users.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
describe("one place for a secret", () => {
  let dataDir = "";
  let app: App;
  let alice: User;
  let bob: User;
  const repos: Record<string, Repo> = {};
  const apps: Record<string, AppRecord> = {};
  const received = (name: string, needs: string[], env = "production"): Record<string, string> => {
    const repo = repos[name]!;
    return resolveAppSecrets(app.db, dataDir, app.bus, {
      appId: apps[name]!.id,
      repoId: repo.id,
      ownerId: repo.ownerId,
      env,
      needs,
    });
  };
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-app-secrets-"));
    app = createApp({ dataDir, port: 0 });
    const a = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
    const b = await createUser(app.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: "a-good-passphrase" });
    if (!a.ok || !b.ok) throw new Error("users");
    alice = a.value;
    bob = b.value;
    for (const name of ["budget", "notes", "other"]) {
      const made = await newApp(app, alice, { name });
      if (!made.ok) throw new Error(made.error);
      repos[name] = made.value.repo;
      apps[name] = made.value.app;
    }
  });
  afterAll(async () => {
    await rm(dataDir, { recursive: true, force: true });
  });
  test("a secret typed while making an app is in its process environment, and the crew is told its name", async () => {
    const made = await newApp(app, alice, {
      name: "simplefin",
      description: "show my balances",
      secrets: [{ name: "SIMPLEFIN_TOKEN", value: "tok-123" }, { name: "", value: "" }],
    });
    if (!made.ok) throw new Error(made.error);
    const repo = made.value.repo;
    expect(resolveAppEnv(app.db, dataDir, made.value.app.id, "production")).toEqual({ SIMPLEFIN_TOKEN: "tok-123" });
    const body = listIssues(app.db, repo.id).map((i) => i.body).join("\n");
    expect(body).toContain("SIMPLEFIN_TOKEN");
    expect(body).not.toContain("tok-123");
    const listed = listAppEnv(app, alice, repo);
    expect(listed.ok && listed.value.map((v) => [v.name, v.kind, v.value])).toEqual([["SIMPLEFIN_TOKEN", "secret", undefined]]);
    const row = app.db.query<{ value_enc: string; value_plain: string | null }, [string]>("SELECT value_enc, value_plain FROM app_env WHERE app_id = ?1").get(made.value.app.id)!;
    expect(row.value_enc).not.toContain("tok-123");
    expect(row.value_plain).toBeNull();
  });
  test("a bad secret refuses the app before anything exists", async () => {
    const made = await newApp(app, alice, { name: "refused", secrets: [{ name: "lower", value: "x" }] });
    expect(!made.ok && made.error).toBe("invalid_secret");
    expect(getAppByRepo(app.db, "none")).toBeUndefined();
  });
  test("a forge secret reaches only the apps it was granted to; setting it again reaches both", () => {
    expect(putSecret(app, alice, "forge", "", "BANK_TOKEN", "v1").ok).toBe(true);
    // Not granted: nobody gets it, even when the app asks for the name.
    expect(received("budget", ["BANK_TOKEN"])).toEqual({});
    expect(received("notes", ["BANK_TOKEN"])).toEqual({});
    // Only a forge admin grants.
    expect(grantToRepo(app, bob, "forge", "", "BANK_TOKEN", repos["budget"]!.id).ok).toBe(false);
    expect(grantToRepo(app, alice, "forge", "", "BANK_TOKEN", repos["budget"]!.id).ok).toBe(true);
    expect(grantToRepo(app, alice, "forge", "", "BANK_TOKEN", repos["notes"]!.id).ok).toBe(true);
    expect(grantToRepo(app, alice, "forge", "", "NOT_SET", repos["notes"]!.id).ok).toBe(false);
    // Granted but not asked for: not handed over either.
    expect(received("budget", [])).toEqual({});
    expect(received("budget", ["BANK_TOKEN"])).toEqual({ BANK_TOKEN: "v1" });
    expect(received("notes", ["BANK_TOKEN"])).toEqual({ BANK_TOKEN: "v1" });
    expect(received("other", ["BANK_TOKEN"])).toEqual({});
    // Rotate once: the row says both apps use it, and which have started with the new value.
    const uses = () => usesOf(app.db, "forge", "", "BANK_TOKEN");
    expect(uses().map((u) => [u.slug, u.current])).toEqual([["budget", true], ["notes", true]]);
    app.db.query("UPDATE secret SET updated_at = '2000-01-01T00:00:00.000Z' WHERE name = 'BANK_TOKEN'").run();
    received("budget", ["BANK_TOKEN"]);
    received("notes", ["BANK_TOKEN"]);
    expect(putSecret(app, alice, "forge", "", "BANK_TOKEN", "v2").ok).toBe(true);
    // Set once: both apps are on the old value until each starts again.
    expect(uses().map((u) => u.current)).toEqual([false, false]);
    expect(received("budget", ["BANK_TOKEN"])).toEqual({ BANK_TOKEN: "v2" });
    expect(received("notes", ["BANK_TOKEN"])).toEqual({ BANK_TOKEN: "v2" });
    expect(uses().map((u) => [u.slug, u.current])).toEqual([["budget", true], ["notes", true]]);
  });
  test("a row whose app has not restarted since the rotation says so", () => {
    expect(putSecret(app, alice, "forge", "", "STALE_KEY", "a").ok).toBe(true);
    expect(grantToRepo(app, alice, "forge", "", "STALE_KEY", repos["other"]!.id).ok).toBe(true);
    received("other", ["STALE_KEY"]);
    app.db.query("UPDATE secret_start SET value_updated_at = '2000-01-01T00:00:00.000Z' WHERE name = 'STALE_KEY'").run();
    expect(usesOf(app.db, "forge", "", "STALE_KEY")[0]?.current).toBe(false);
  });
  test("the app's own secret wins over a granted one, and revoking takes the name away", () => {
    expect(grantToRepo(app, alice, "forge", "", "BANK_TOKEN", repos["other"]!.id).ok).toBe(true);
    expect(received("other", ["BANK_TOKEN"])).toEqual({ BANK_TOKEN: "v2" });
    // The app's own is nearer: the process is handed the forge's only where the app has none.
    expect(setAppEnv(app.db, dataDir, apps["other"]!.id, "BANK_TOKEN", "mine").ok).toBe(true);
    expect(needRows(app.db, { appId: apps["other"]!.id, repoId: repos["other"]!.id, ownerId: alice.id, needs: ["BANK_TOKEN"] })[0]?.source).toBe("app");
    expect(revokeFromRepo(app, alice, "BANK_TOKEN", repos["notes"]!.id).ok).toBe(true);
    expect(received("notes", ["BANK_TOKEN"])).toEqual({});
  });
  test("every read is an event naming the app run and the name, never the value", () => {
    const events = app.db
      .query<{ payload: string }, []>("SELECT payload FROM event WHERE kind = 'secret.read' ORDER BY id DESC LIMIT 5")
      .all();
    expect(events.length).toBeGreaterThan(0);
    for (const e of events) {
      expect(e.payload).toContain("app:");
      expect(e.payload).not.toMatch(/"(v1|v2|tok-123|mine)"|:(v1|v2)/);
      expect(Object.keys(JSON.parse(e.payload)).sort()).toEqual(["name", "run", "scope"]);
    }
  });
  test("needs, has, missing", () => {
    const repo = repos["notes"]!;
    const rows = needRows(app.db, { appId: apps["notes"]!.id, repoId: repo.id, ownerId: repo.ownerId, needs: ["BANK_TOKEN", "STALE_KEY", "NOWHERE_KEY"] });
    expect(rows.map((r) => [r.name, r.source, r.offer])).toEqual([
      ["BANK_TOKEN", "available", "forge"],
      ["STALE_KEY", "available", "forge"],
      ["NOWHERE_KEY", "missing", undefined],
    ]);
  });
  test("a variable is plain and shown; a setting is a secret unless chosen otherwise", async () => {
    const repo = repos["notes"]!;
    const id = apps["notes"]!.id;
    expect((await setAppEnvVar(app, alice, repo, "STRIPE_SECRET_KEY", "sk")).ok).toBe(true);
    expect((await setAppEnvVar(app, alice, repo, "GREETING", "hello", "all", "variable")).ok).toBe(true);
    expect((await setAppEnvVar(app, alice, repo, "PUBLIC_TOKEN_URL", "u", "all", "secret")).ok).toBe(true);
    expect((await setAppEnvVar(app, alice, repo, "REGION_KEY", "eu", "all", "variable")).ok).toBe(true);
    expect((await setAppEnvVar(app, alice, repo, "X", "y", "all", "nonsense")).ok).toBe(false);
    const listed = listAppEnv(app, alice, repo);
    expect(listed.ok && listed.value.map((v) => [v.name, v.kind, v.value])).toEqual([
      ["GREETING", "variable", "hello"],
      ["PUBLIC_TOKEN_URL", "secret", undefined],
      ["REGION_KEY", "variable", "eu"],
      ["STRIPE_SECRET_KEY", "secret", undefined],
    ]);
    expect(resolveAppEnv(app.db, dataDir, id, "production")).toEqual({
      GREETING: "hello",
      PUBLIC_TOKEN_URL: "u",
      REGION_KEY: "eu",
      STRIPE_SECRET_KEY: "sk",
    });
    // The variable is in the clear; the secret never is, and the rotation passes over the variable.
    const stored = (name: string) =>
      app.db.query<{ value_enc: string; value_plain: string | null }, [string]>("SELECT value_enc, value_plain FROM app_env WHERE name = ?1").get(name)!;
    expect(stored("GREETING")).toEqual({ value_enc: "", value_plain: "hello" });
    expect(stored("STRIPE_SECRET_KEY").value_plain).toBeNull();
    // Setting a secret again as a variable converts it, and back.
    expect((await setAppEnvVar(app, alice, repo, "STRIPE_SECRET_KEY", "pk", "production", "variable")).ok).toBe(true);
    expect(stored("STRIPE_SECRET_KEY")).toEqual({ value_enc: "", value_plain: "pk" });
    expect((await deleteAppEnvVar(app, alice, repo, "STRIPE_SECRET_KEY")).ok).toBe(true);
  });
  test("forge.json says what it needs", () => {
    expect(neededNames('{"env":["A_TOKEN","B_KEY","A_TOKEN"]}')).toEqual(["A_TOKEN", "B_KEY"]);
    expect(neededNames('{"env":"x"}')).toEqual([]);
    expect(neededNames("not json")).toEqual([]);
    expect(parseNeeds(["lower"]).ok).toBe(false);
    expect(parseNeeds(["FORGE_TOKEN"]).ok).toBe(false);
    const run = { app: { run: "bun run x.ts" } };
    const ok = parseManifest(JSON.stringify({ ...run, env: ["SIMPLEFIN_TOKEN"] }), undefined);
    expect(ok.ok && ok.value.env).toEqual(["SIMPLEFIN_TOKEN"]);
    expect(parseManifest(JSON.stringify({ ...run, env: [1] }), undefined).ok).toBe(false);
  });
  test("a setting with no kind chosen is sealed, whatever its name, and says so back", async () => {
    const url = "postgres://user:[email protected]/app";
    const set = await setAppEnvVar(app, alice, repos["budget"]!, "DATABASE_URL", url);
    expect(set.ok && set.value.kind).toBe("secret");
    const plain = app.db.query<{ value_plain: string | null; value_enc: string }, [string]>("SELECT value_plain, value_enc FROM app_env WHERE app_id = ?1 AND name = 'DATABASE_URL'").get(apps["budget"]!.id)!;
    expect(plain.value_plain).toBeNull();
    expect(plain.value_enc).not.toContain("hunter2");
    const listed = listAppEnv(app, alice, repos["budget"]!);
    expect(JSON.stringify(listed)).not.toContain("hunter2");
    // A variable is an explicit choice.
    const greeting = await setAppEnvVar(app, alice, repos["budget"]!, "GREETING", "hello", "all", "variable");
    expect(greeting.ok && greeting.value.kind).toBe("variable");
  });
  test("a variable's value is not in the events outbox, nor a secret's", async () => {
    await setAppEnvVar(app, alice, repos["notes"]!, "SHOWN_SETTING", "plain-value-4242", "all", "variable");
    await setAppEnvVar(app, alice, repos["notes"]!, "HIDDEN_SETTING", "sealed-value-4242");
    const events = app.db.query<{ payload: string }, []>("SELECT payload FROM event").all().map((e) => e.payload).join("\n");
    expect(events).toContain("SHOWN_SETTING");
    expect(events).not.toContain("plain-value-4242");
    expect(events).not.toContain("sealed-value-4242");
  });
});
@@ -121,17 +121,17 @@
test("starting, stopping and deploying a new commit each move the /app tag", asy
test("setting and removing a variable move the /env tag; the value never feeds it", async () => {
  const empty = await tagOf(ENV);
  const set = await call("PUT", `${ENV}/GREETING`, adminTok, {}, { value: "secret-one" });
  const set = await call("PUT", `${ENV}/GREETING_TOKEN`, adminTok, {}, { value: "hunter-one" });
  expect(set.status).toBe(200);
  await set.text();
  const added = await tagOf(ENV);
  expect(added).not.toBe(empty);
  expect(await status(ENV, added)).toBe(304);
  const again = await call("PUT", `${ENV}/GREETING`, adminTok, {}, { value: "secret-two" });
  const again = await call("PUT", `${ENV}/GREETING_TOKEN`, adminTok, {}, { value: "hunter-two" });
  await again.text();
  const body = await (await call("GET", ENV, adminTok)).text();
  expect(body).not.toContain("secret");
  const gone = await call("DELETE", `${ENV}/GREETING`, adminTok);
  expect(body).not.toContain("hunter");
  const gone = await call("DELETE", `${ENV}/GREETING_TOKEN`, adminTok);
  expect(gone.status).toBe(200);
  await gone.text();
  expect(await tagOf(ENV)).toBe(empty);
@@ -559,7 +559,7 @@
printf '%s\\n' '{"is_error":false,"result":"{\\"summary\\":\\"Build it\\",\\"che
            '  hostname: "127.0.0.1",',
            "  fetch(request) {",
            '    return new URL(request.url).pathname === "/env"',
            '      ? new Response(process.env["GREETING"] ?? "unset")',
            '      ? new Response(process.env["GREETING_TOKEN"] ?? "unset")',
            '      : new Response("ok");',
            "  },",
            "});",
@@ -599,8 +599,8 @@
printf '%s\\n' '{"is_error":false,"result":"{\\"summary\\":\\"Build it\\",\\"che
    ).toEqual([]);
    expect((await api(env, { token: rw })).status).toBe(403);
    expect((await api(env, { token: null })).status).toBe(401);
    expect((await put("GREETING", "x", rw)).status).toBe(403);
    expect((await put("GREETING", "x", null)).status).toBe(401);
    expect((await put("GREETING_TOKEN", "x", rw)).status).toBe(403);
    expect((await put("GREETING_TOKEN", "x", null)).status).toBe(401);
    await post(
      "/api/v1/users",
      {
@@ -612,9 +612,9 @@
printf '%s\\n' '{"is_error":false,"result":"{\\"summary\\":\\"Build it\\",\\"che
    );
    const mallory = tokenFor(app, "mallory", "admin", "admin");
    expect((await api(env, { token: mallory })).status).toBe(404);
    expect((await put("GREETING", "x", mallory)).status).toBe(404);
    expect((await put("GREETING_TOKEN", "x", mallory)).status).toBe(404);
    expect(
      (await api(`${env}/GREETING`, { method: "DELETE", token: mallory }))
      (await api(`${env}/GREETING_TOKEN`, { method: "DELETE", token: mallory }))
        .status,
    ).toBe(404);
@@ -629,19 +629,19 @@
printf '%s\\n' '{"is_error":false,"result":"{\\"summary\\":\\"Build it\\",\\"che
      expect(((await refused.json()) as { error: string }).error).toBe(error);
    }
    expect(
      ((await (await put("GREETING", "")).json()) as { error: string }).error,
      ((await (await put("GREETING_TOKEN", "")).json()) as { error: string }).error,
    ).toBe("invalid_value");
    // Set: the answer, the listing, the row and the event carry the name
    // and never the value.
    const secret = "hello-from-the-operator-9f1c";
    const set = await put("GREETING", secret);
    const set = await put("GREETING_TOKEN", secret);
    expect(set.status).toBe(200);
    const answer = await set.text();
    expect(answer).toContain('"name":"GREETING"');
    expect(answer).toContain('"name":"GREETING_TOKEN"');
    expect(answer).not.toContain(secret);
    const listed = await (await api(env)).text();
    expect(listed).toContain('"name":"GREETING"');
    expect(listed).toContain('"name":"GREETING_TOKEN"');
    expect(listed).not.toContain(secret);
    const row = app.db
      .query<{ value_enc: string }, []>("SELECT value_enc FROM app_env")
@@ -655,12 +655,12 @@
printf '%s\\n' '{"is_error":false,"result":"{\\"summary\\":\\"Build it\\",\\"che
      >("SELECT payload FROM event WHERE kind = 'app.env_set' ORDER BY id DESC")
      .get();
    // The name and where it applies; never the value.
    expect(event?.payload).toBe('{"name":"GREETING","scope":"production"}');
    expect(event?.payload).toBe('{"name":"GREETING_TOKEN","scope":"production","kind":"secret"}');
    expect(answer).toContain('"scope":"production"');
    // A scope is one of three words, and a preview-only value never
    // reaches production: the process that serves keeps the one for all.
    const staging = await api(`${env}/GREETING`, {
    const staging = await api(`${env}/GREETING_TOKEN`, {
      method: "PUT",
      body: JSON.stringify({ value: "x", scope: "staging" }),
    });
@@ -668,7 +668,7 @@
printf '%s\\n' '{"is_error":false,"result":"{\\"summary\\":\\"Build it\\",\\"che
    expect(((await staging.json()) as { error: string }).error).toBe(
      "invalid_scope",
    );
    const forPreviews = await api(`${env}/GREETING`, {
    const forPreviews = await api(`${env}/GREETING_TOKEN`, {
      method: "PUT",
      body: JSON.stringify({ value: "only-in-previews", scope: "preview" }),
    });
@@ -679,9 +679,9 @@
printf '%s\\n' '{"is_error":false,"result":"{\\"summary\\":\\"Build it\\",\\"che
          items: { name: string; scope: string }[];
        }
      ).items.map((i) => `${i.name}@${i.scope}`),
    ).toEqual(["GREETING@production", "GREETING@preview"]);
    ).toEqual(["GREETING_TOKEN@production", "GREETING_TOKEN@preview"]);
    expect(
      (await api(`${env}/GREETING?scope=preview`, { method: "DELETE" })).status,
      (await api(`${env}/GREETING_TOKEN?scope=preview`, { method: "DELETE" })).status,
    ).toBe(200);
    // The redeploy that follows is what hands it to the app — and its log
@@ -696,12 +696,12 @@
printf '%s\\n' '{"is_error":false,"result":"{\\"summary\\":\\"Build it\\",\\"che
    // Remove: admin only, exact, and the next process is without it.
    expect(
      (await api(`${env}/GREETING`, { method: "DELETE", token: rw })).status,
      (await api(`${env}/GREETING_TOKEN`, { method: "DELETE", token: rw })).status,
    ).toBe(403);
    expect((await api(`${env}/GREETING`, { method: "DELETE" })).status).toBe(
    expect((await api(`${env}/GREETING_TOKEN`, { method: "DELETE" })).status).toBe(
      200,
    );
    const gone = await api(`${env}/GREETING`, { method: "DELETE" });
    const gone = await api(`${env}/GREETING_TOKEN`, { method: "DELETE" });
    expect(gone.status).toBe(422);
    expect(((await gone.json()) as { error: string }).error).toBe(
      "no_such_var",
@@ -20,7 +20,7 @@
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { deleteAppEnvVar, newApp, setAppEnvVar } from "../src/actions/apps.ts";
import { createRepo } from "../src/actions/repos.ts";
import { putSecret, removeSecret } from "../src/actions/secrets.ts";
import { grantToRepo, putSecret, removeSecret } from "../src/actions/secrets.ts";
import { deleteRepo } from "../src/core/repos.ts";
import { grantSecrets, parseDeclaration } from "../src/crew/grant.ts";
import { promote } from "./helpers/members.ts";
@@ -198,25 +198,25 @@
describe("both stores", () => {
      app,
      alice,
      repo,
      "EVENTED_VAR",
      "EVENTED_TOKEN",
      ENV_PLAIN,
      "preview",
    );
    expect(set.ok).toBe(true);
    const sealed = [
      sealedOf("secret", "EVENTED"),
      sealedOf("app_env", "EVENTED_VAR"),
      sealedOf("app_env", "EVENTED_TOKEN"),
    ];
    resolveSecrets(app.db, dataDir, app.bus, ["EVENTED"], {
      actor: alice.id,
      run: "run-2",
    });
    expect(resolveAppEnv(app.db, dataDir, record.id, "pull-1")).toMatchObject({
      EVENTED_VAR: ENV_PLAIN,
      EVENTED_TOKEN: ENV_PLAIN,
    });
    expect(removeSecret(app, alice, "forge", "", "EVENTED").ok).toBe(true);
    expect(
      (await deleteAppEnvVar(app, alice, repo, "EVENTED_VAR", "preview")).ok,
      (await deleteAppEnvVar(app, alice, repo, "EVENTED_TOKEN", "preview")).ok,
    ).toBe(true);
    const kinds = new Set(
      [...events("secret.%"), ...events("app.env%")].map((e) => e.kind),
@@ -260,10 +260,10 @@
describe("both stores", () => {
  test("the data browser shows an admin neither table's sealed column, by row or by query, and anyone else no forge database", async () => {
    setSecret(app.db, dataDir, "forge", "", "BROWSED", SECRET_PLAIN);
    setAppEnv(app.db, dataDir, record.id, "BROWSED_VAR", ENV_PLAIN);
    setAppEnv(app.db, dataDir, record.id, "BROWSED_TOKEN", ENV_PLAIN);
    const sealed = [
      sealedOf("secret", "BROWSED"),
      sealedOf("app_env", "BROWSED_VAR"),
      sealedOf("app_env", "BROWSED_TOKEN"),
    ];
    expect(findSource(app.db, dataDir, bob, "forge")).toBeUndefined();
    expect(findSource(app.db, dataDir, undefined, "forge")).toBeUndefined();
@@ -274,7 +274,7 @@
describe("both stores", () => {
    ];
    // The names are listed: the browser reads the tables, and still shows no value.
    expect(seen[0]).toContain("BROWSED");
    expect(seen[1]).toContain("BROWSED_VAR");
    expect(seen[1]).toContain("BROWSED_TOKEN");
    for (const sql of [
      "SELECT * FROM secret",
      "SELECT value_enc AS v FROM secret",
@@ -345,8 +345,8 @@
describe("both stores", () => {
  // What does not hold today. The body is the protection as it should read:
  // `bun test --todo` runs it, and a pass says its gap is closed (crew pull #12184).
  test.todo(
    "a run on a repository of someone who is not a forge admin is not handed the forge's own credentials: `grantSecrets` ends its ladder at the forge scope for every repository, so the mail, billing or backup key opens for any writer's issue that declares it",
  test(
    "a run on a repository of someone who is not a forge admin is not handed the forge's own credentials until the forge's owner grants that name to it",
    async () => {
      promote(app.db, bob);
      const theirs = await createRepo(app, bob, {
@@ -374,10 +374,27 @@
describe("both stores", () => {
      });
      try {
        expect(grant.names).toEqual([]);
        expect(grant.ungranted).toEqual(["BACKUP_BUCKET_KEY"]);
        expect(Object.values(grant.env)).not.toContain(SECRET_PLAIN);
      } finally {
        grant.release();
      }
      // The owner's one click, by repository, and the next run holds it.
      expect(
        grantToRepo(app, alice, "forge", "", "BACKUP_BUCKET_KEY", theirs.value.id).ok,
      ).toBe(true);
      const after = grantSecrets(app.db, dataDir, app.bus, declared, {
        id: "run-of-a-member-2",
        repoId: theirs.value.id,
        ownerId: bob.id,
        actorId: bob.id,
      });
      try {
        expect(after.names).toEqual(["BACKUP_BUCKET_KEY"]);
        expect(after.ungranted).toEqual([]);
      } finally {
        after.release();
      }
    },
  );
});
@@ -21,6 +21,7 @@
import { usedFor } from "../src/cloud/declared.ts";
import { bar, gatedFetch, handOut } from "../src/cloud/gate.ts";
import { PROVIDERS, VENDOR_OF } from "../src/cloud/providers.ts";
import { CLOUD_VENDORS } from "../src/apps/manifest.ts";
import { grantSecret } from "../src/core/app_secrets.ts";
import { grantSecrets, parseDeclaration } from "../src/crew/grant.ts";
import { auditToday, pruneAudit, recordAudit } from "../src/core/cloud_audit.ts";
import { listCloudAccounts } from "../src/core/cloud_account.ts";
@@ -153,6 +154,8 @@
describe("cloud gate", () => {
    const put = (name: string) => setSecret(app.db, dataDir, "forge", "", name, "sealed-value-1234567");
    put("CLOUD_AWS_X");
    put("CLOUD_GITHUB_Y");
    // The forge's owner granted the key to this repository; a declaration alone opens nothing.
    grantSecret(app.db, repoId, "forge", "", "CLOUD_AWS_X", alice.id);
    const asked = parseDeclaration("---\nsecrets: CLOUD_AWS_X, CLOUD_GITHUB_Y, PLAIN\n---");
    const s3 = [{ vendor: "s3", use: "backup", why: "off-machine copy" }] as const;
    const run = { id: "r6", repoId, ownerId: alice.id, actorId: alice.id };
@@ -23,6 +23,7 @@
import { verify } from "../src/cloud/providers.ts";
import { listCloudAccounts, recentCloudReads } from "../src/core/cloud_account.ts";
import { listSecretNames } from "../src/core/secret_store.ts";
import { createUser, type User } from "../src/core/users.ts";
import { grantSecret } from "../src/core/app_secrets.ts";
import { grantSecrets, parseDeclaration } from "../src/crew/grant.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { quietLogs } from "./helpers/globals.ts";
@@ -129,6 +130,7 @@
describe("cloud accounts", () => {
  test("a run that needs writes is refused while the switch is off, and says so", () => {
    const run = { id: "r1", repoId, ownerId: alice.id, actorId: alice.id };
    grantSecret(app.db, repoId, "forge", "", "CLOUD_DIGITALOCEAN_MAIN", alice.id);
    const reads = () => recentCloudReads(app.db).length;
    const before = reads();
    const refused = grantSecrets(app.db, dataDir, app.bus, parseDeclaration("---\nsecrets: CLOUD_DIGITALOCEAN_MAIN\nwrites: yes\n---"), run);
@@ -22,6 +22,8 @@
import { local } from "../src/tui/screens/where.ts";
import { headlessTerminal } from "../src/tui/term/terminal.ts";
import { settleApp } from "./helpers/tui.ts";
import { setAppEnv } from "../src/core/app_env.ts";
import { grantToRepo, putSecret } from "../src/actions/secrets.ts";
import { writeFileSync } from "node:fs";
import { createApp as createAppRecord } from "../src/core/apps.ts";
import { getPull, type Pull } from "../src/core/pulls.ts";
import type { Repo } from "../src/core/repos.ts";
@@ -128,6 +130,27 @@
describe("a pull from another forge is a guest until a writer approves it", () =
    expect(held(guest)).toEqual({ vars: { API_KEY: "s3cret" }, forgeToken: "tok" });
  });
  test("a waiting guest's preview and its terminal receive neither a granted secret nor a variable; an approved one gets them", async () => {
    const dir = await mkdtemp(join(tmpdir(), "forge-guest-dir-"));
    writeFileSync(join(dir, "forge.json"), JSON.stringify({ app: { run: "x" }, env: ["GRANTED_TOKEN"] }));
    const put = putSecret(app, alice, "forge", "", "GRANTED_TOKEN", "granted-value");
    if (!put.ok) throw new Error(String(put.error));
    expect(grantToRepo(app, alice, "forge", "", "GRANTED_TOKEN", lib.id).ok).toBe(true);
    try {
      const guest = await pull("head");
      for (const start of [true, false]) {
        const waiting = runtime.secretsFor(lib, appId, previewEnv(guest.number), "tok", dir, start);
        expect(waiting).toEqual({ vars: {}, forgeToken: undefined });
      }
      expect(approveGuest(app.db, lib, guest, alice).ok).toBe(true);
      const approved = runtime.secretsFor(lib, appId, previewEnv(guest.number), "tok", dir).vars;
      expect(approved["GRANTED_TOKEN"]).toBe("granted-value");
      expect(approved["API_KEY"]).toBe("s3cret");
    } finally {
      await rm(dir, { recursive: true, force: true });
    }
  });
  test("the approval is per pull: a later push by the guest keeps it", async () => {
    const guest = await pull("head");
    expect(approveGuest(app.db, lib, guest, alice).ok).toBe(true);
@@ -81,7 +81,7 @@
describe("MCP app_env", () => {
  test("an admin sets a variable per scope, lists the names and unsets them", async () => {
    for (const scope of ["all", "production", "preview"]) {
      const set = await tool(aliceAdmin, { repo: "alice/game", action: "set", name: "GREETING", value: SECRET, scope });
      const set = await tool(aliceAdmin, { repo: "alice/game", action: "set", name: "GREETING_KEY", value: SECRET, scope });
      expect(set.value.scope).toBe(scope);
      expect(set.text).not.toContain(SECRET);
    }
@@ -90,7 +90,7 @@
describe("MCP app_env", () => {
    expect(listed.value.next_cursor).toBeNull();
    expect(listed.value.items.map((i: any) => i.scope).sort()).toEqual(["all", "preview", "production"]);
    for (const scope of ["all", "production", "preview"])
      expect((await tool(aliceAdmin, { repo: "alice/game", action: "unset", name: "GREETING", scope })).value).toEqual({});
      expect((await tool(aliceAdmin, { repo: "alice/game", action: "unset", name: "GREETING_KEY", scope })).value).toEqual({});
    expect((await tool(aliceAdmin, { repo: "alice/game", action: "list" })).value.items).toEqual([]);
  });
@@ -10,7 +10,11 @@
import { join } from "node:path";
import { createRepo } from "../src/actions/repos.ts";
import { createUser } from "../src/core/users.ts";
import { createApp, type App } from "../src/app.ts";
import { grantSecrets, parseDeclaration } from "../src/crew/grant.ts";
import { grantSecret } from "../src/core/app_secrets.ts";
import { getRepoById } from "../src/core/repos.ts";
import { getUserById } from "../src/core/users.ts";
import { createIssue, listComments } from "../src/core/issues.ts";
import { needsYou, grantSecrets, parseDeclaration } from "../src/crew/grant.ts";
import { historyHolds, scrubTree } from "../src/crew/leak.ts";
import { listHeldSecrets, releaseOrphans } from "../src/core/run_secret.ts";
import { setSecret } from "../src/core/secret_store.ts";
@@ -66,6 +70,8 @@
describe("a grant", () => {
    run = { id: "run1", repoId: r.value.id, ownerId: r.value.ownerId, actorId: u.value.id };
    setSecret(app.db, dataDir, "forge", "", "CF_TOKEN", VALUE);
    setSecret(app.db, dataDir, "forge", "", "UNDECLARED", "other-value-1234");
    // The forge's owner granted CF_TOKEN to this repository by name; UNDECLARED is not granted.
    expect(grantSecret(app.db, r.value.id, "forge", "", "CF_TOKEN", u.value.id)).toBe(true);
  });
  afterAll(async () => {
    app.close();
@@ -120,6 +126,34 @@
describe("a grant", () => {
    expect(redactHeld(`plain ${VALUE}`)).toContain(VALUE);
  });
  test("a name the forge has and was not granted to this repository is asked, not opened", () => {
    const d = parseDeclaration("---\nsecrets: UNDECLARED, NOWHERE\n---");
    const grant = grantSecrets(app.db, dataDir, app.bus, d, { ...run, id: "run3" });
    expect(grant.env).toEqual({});
    expect(grant.ungranted).toEqual(["UNDECLARED"]);
    expect(grant.missing).toEqual(["NOWHERE"]);
    expect(listHeldSecrets(app.db, "run3")).toEqual([]);
    const opened = app.db
      .query<{ payload: string }, []>("SELECT payload FROM event WHERE kind = 'secret.read'")
      .all()
      .filter((e) => e.payload.includes("UNDECLARED"));
    expect(opened).toEqual([]);
  });
  test("the run says once, on the issue, what it asked for and was not granted, with the link that grants it", async () => {
    const repo = getRepoById(app.db, run.repoId)!;
    const agent = getUserById(app.db, run.actorId)!;
    const made = createIssue(app.db, { repoId: repo.id, authorId: agent.id, title: "tidy", body: "" });
    if (!made.ok) throw new Error(made.error);
    const issue = made.value;
    needsYou(app, agent, repo, issue, "UNDECLARED");
    needsYou(app, agent, repo, issue, "UNDECLARED");
    const said = listComments(app.db, issue.id).map((c) => c.body);
    expect(said).toEqual([
      `this run asked for UNDECLARED; the forge's owner has not granted UNDECLARED to alice/site: [Grant it](/alice/site/settings/app#secrets)`,
    ]);
  });
  test("a crash's open grant is closed by the sweep", () => {
    const d = parseDeclaration("---\nsecrets: CF_TOKEN\n---");
    grantSecrets(app.db, dataDir, app.bus, d, { ...run, id: "run2" });
@@ -106,6 +106,7 @@
describe("the restore drill", () => {
      "SECRET_WORD",
      "swordfish",
      "all",
      "secret",
    );
    if (!set.ok) throw new Error(String(set.error));
    await takeSnapshot(
@@ -106,7 +106,7 @@
describe("a forge back from a snapshot", () => {
      app,
      alice,
      repo.value,
      "SECRET_WORD",
      "SECRET_WORD_KEY",
      "swordfish",
      "all",
    );
@@ -224,7 +224,7 @@
describe("a forge back from a snapshot", () => {
      // The sealed variable opens with the restored key.
      const record = getAppByRepo(restored.db, repo.id)!;
      const env = resolveAppEnv(restored.db, back, record.id, "production");
      expect(env["SECRET_WORD"]).toBe("swordfish");
      expect(env["SECRET_WORD_KEY"]).toBe("swordfish");
      // The app's data came back, database rows included.
      const { Database } = await import("bun:sqlite");
      const appDb = new Database(
@@ -248,7 +248,7 @@
describe("a forge back from a snapshot", () => {
    const back = fresh("back-nokey");
    const done = await restoreSnapshot(store, NAME, back);
    expect(done.key).toBe("missing");
    expect(done.sealedMissing).toEqual(["SECRET_WORD (app notes)"]);
    expect(done.sealedMissing).toEqual(["SECRET_WORD_KEY (app notes)"]);
    expect(existsSync(join(back, "secret.key.wrapped"))).toBe(false);
    const restored = createApp({ dataDir: back, port: 0 });
    try {
@@ -258,7 +258,7 @@
describe("a forge back from a snapshot", () => {
        getRepo(restored.db, "alice", "notes")!.id,
      )!;
      const env = resolveAppEnv(restored.db, back, record.id, "production");
      expect(env["SECRET_WORD"]).toBeUndefined();
      expect(env["SECRET_WORD_KEY"]).toBeUndefined();
    } finally {
      restored.close();
    }
@@ -96,7 +96,7 @@
afterAll(async () => {
describe("an app's variables, in the terminal", () => {
  test("an admin sets one: masked as it is typed, Enter on the first choice is production, then listed by name and scope", async () => {
    const text = await drive(alice, [...open, "a", "STRIPE_KEY", "\r", SECRET, "\r", "\r"]);
    const text = await drive(alice, [...open, "a", "STRIPE_KEY", "\r", SECRET, "\r", "\r", "\r"]);
    expect(vars().map((v) => [v.name, v.scope])).toEqual([["STRIPE_KEY", "production"]]);
    expect(text).toContain("STRIPE_KEY is set for production.");
    expect(text).toContain("STRIPE_KEY");
@@ -113,7 +113,7 @@
describe("an app's variables, in the terminal", () => {
  });
  test("a bad name is refused in the page's words, and nothing is set", async () => {
    const text = await drive(alice, [...open, "a", "lower", "\r", SECRET, "\r", "\r"]);
    const text = await drive(alice, [...open, "a", "lower", "\r", SECRET, "\r", "\r", "\r"]);
    // The page's sentence wraps across the head; its start is on the screen.
    expect(text).toContain("A name is capital letters, digits and underscores");
    expect(APP_ENV_ERRORS["invalid_name"]).toStartWith("A name is capital letters, digits and underscores");
@@ -122,7 +122,7 @@
describe("an app's variables, in the terminal", () => {
  test("a value too long is refused in the page's words", async () => {
    const long = `\x1b[200~${"x".repeat(64 * 1024 + 1)}\x1b[201~`;
    const text = await drive(alice, [...open, "a", "TOO_LONG", "\r", long, "\r", "\r"]);
    const text = await drive(alice, [...open, "a", "TOO_LONG", "\r", long, "\r", "\r", "\r"]);
    expect(text).toContain(APP_ENV_ERRORS["invalid_value"]!);
    expect(vars().map((v) => v.name)).toEqual(["STRIPE_KEY"]);
  });
@@ -141,7 +141,7 @@
describe("an app's variables, in the terminal", () => {
  test("a writer who is not an admin has no entry, and can set nothing", async () => {
    expect(await drive(bob, [":", "Variables"])).not.toContain("acme/shop — Variables");
    expect(await drive(alice, [":", "Variables"])).toContain("acme/shop — Variables");
    await drive(bob, [...open, "a", "BOB_KEY", "\r", SECRET, "\r", "\r"]);
    await drive(bob, [...open, "a", "BOB_KEY", "\r", SECRET, "\r", "\r", "\r"]);
    expect(vars()).toEqual([]);
  });
@@ -92,7 +92,7 @@
afterAll(async () => {
describe("the terminal's variables screen", () => {
  test("an admin adds a masked value: name and scope listed, the value nowhere", async () => {
    const text = await drive(admin, [...open, "a", "API_TOKEN", "\r", SECRET, "\r", "\r"]);
    const text = await drive(admin, [...open, "a", "API_TOKEN", "\r", SECRET, "\r", "\r", "\r"]);
    expect(vars().map((v) => [v.name, v.scope])).toEqual([["API_TOKEN", "production"]]);
    expect(text).toContain("API_TOKEN is set for production.");
    expect(text).toContain("production · set");
@@ -115,7 +115,7 @@
describe("the terminal's variables screen", () => {
  test("a non-admin is not offered the entry; a bad name is refused in MCP's words", async () => {
    expect(await drive(writer, [":", "Variables"])).not.toContain("— Variables");
    expect(await drive(admin, [":", "Variables"])).toContain("— Variables");
    const text = await drive(admin, [...open, "a", "bad name", "\r", SECRET, "\r", "\r"]);
    const text = await drive(admin, [...open, "a", "bad name", "\r", SECRET, "\r", "\r", "\r"]);
    expect(text).toContain(APP_ENV_ERRORS["invalid_name"]!.slice(0, 50));
    expect(vars()).toEqual([]);
    for (const f of frames) expect(f).not.toContain(SECRET);
@@ -0,0 +1,94 @@
/**
 * The terminal's "Secrets this app uses" (src/tui/screens/appsecrets.ts): the names forge.json
 * asks for and where each comes from; a forge admin grants and revokes with `a` and `x`, a
 * repository's admin who is not one cannot.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { newApp } from "../src/actions/apps.ts";
import { commitToBranch } from "../src/actions/repos.ts";
import { putSecret } from "../src/actions/secrets.ts";
import { createApp, type App } from "../src/app.ts";
import { listGrants } from "../src/core/app_secrets.ts";
import { getRepo, type Repo } from "../src/core/repos.ts";
import { createUser, type User } from "../src/core/users.ts";
import { createForgeApp } from "../src/tui/forge.ts";
import { repoScreen } from "../src/tui/screens/repo.ts";
import { local } from "../src/tui/screens/where.ts";
import { headlessTerminal } from "../src/tui/term/terminal.ts";
import { settleApp } from "./helpers/tui.ts";
import { proveAll } from "./helpers/verified.ts";
let dir: string;
let app: App;
let admin: User;
let shop: Repo;
async function drive(user: User, keys: string[]): Promise<string> {
  const terminal = headlessTerminal(120, 40);
  const { app: tui, session } = createForgeApp(
    app,
    { sshUsername: user.username, remoteAddress: "127.0.0.1", fingerprint: "SHA256:test", user },
    { terminal, exitHooks: false },
  );
  tui.start();
  tui.ctx.push(repoScreen(session, tui.ctx, local(session, shop)));
  await settleApp(tui);
  for (const k of keys) {
    terminal.feed(k);
    await settleApp(tui);
  }
  const text = tui.screen.toText();
  tui.stop?.();
  return text;
}
const open = [":", "Secrets this app", "\r"];
beforeAll(async () => {
  dir = await mkdtemp(join(tmpdir(), "forge-tui-appsecrets-"));
  app = createApp({ dataDir: dir, port: 0 });
  const r = await createUser(app.db, {
    origin: "seed", trusted: true, username: "alice", email: "[email protected]",
    password: "a-good-passphrase", adminIfFirst: true,
  });
  if (!r.ok) throw new Error(r.error);
  admin = r.value;
  proveAll(app);
  const made = await newApp(app, admin, { name: "shop", visibility: "public" });
  if (!made.ok) throw new Error(String(made.error));
  shop = getRepo(app.db, admin.username, "shop")!;
  const c = await commitToBranch(app, admin, shop, {
    message: "needs",
    files: [{ path: "forge.json", content: JSON.stringify({ app: { run: "x" }, env: ["SHOP_TOKEN"] }) }],
  });
  if (!c.ok) throw new Error(JSON.stringify(c.error));
  const put = putSecret(app, admin, "forge", "", "SHOP_TOKEN", "the-value-1");
  if (!put.ok) throw new Error(String(put.error));
});
afterAll(async () => {
  app.db.close();
  await rm(dir, { recursive: true, force: true });
});
describe("the terminal's secrets screen", () => {
  test("lists a name set higher up as not granted; g grants it, x takes it back; the value is never drawn", async () => {
    const before = await drive(admin, open);
    expect(before).toContain("SHOP_TOKEN");
    expect(before).toContain("set higher up, not granted");
    expect(before).not.toContain("the-value-1");
    const granted = await drive(admin, [...open, "a"]);
    expect(granted).toContain("SHOP_TOKEN is granted");
    expect(listGrants(app.db, shop.id).map((g) => g.name)).toEqual(["SHOP_TOKEN"]);
    const shown = await drive(admin, open);
    expect(shown).toContain("granted from the forge");
    const revoked = await drive(admin, [...open, "x"]);
    expect(revoked).toContain("no longer granted");
    expect(listGrants(app.db, shop.id)).toEqual([]);
  });
});
@@ -313,7 +313,7 @@
describe("tui system telemetry grant", () => {
  });
  test("the System command passes the session, so the admin has the line and g", async () => {
    const { app: tui, session } = createForgeApp(app, identity(carol), { terminal: headlessTerminal(120, 50), exitHooks: false });
    const { app: tui, session } = createForgeApp(app, identity(carol), { terminal: headlessTerminal(120, 70), exitHooks: false });
    tui.start();
    const system = forgeCommands(session)(tui.ctx).find((c) => c.id === "system");
    system!.run();
		@@ -921,10 +921,12 @@ Environment** (or `PUT /api/v1/repos/:owner/:name/app/env/:name` with a
921	921	`{ "value" }` body). A name is `ADMIN_PASSWORD`-shaped: capital letters,
922	922	digits and underscores; the names the forge sets itself (`PORT`, `HOST`,
923	923	`PATH`, `FORGE_*` and their kin) are refused, and the forge's own values
924		win regardless. Values are write-only: set one, and it is never shown
925		again — the page, the API and the event outbox carry the name and when it
926		was set, nothing more. At rest each value is sealed with the data
927		directory's key (`kernel/secret.ts`), bound to the app and the name.
	924	win regardless. A setting is one of two kinds. A variable is a plain setting (a URL,
	925	a switch): kept and listed in the clear, safe in a log. A secret is
	926	sealed with the data directory's key (`kernel/secret.ts`), bound to the app
	927	and the name, part of the sealing-key rotation, and write-only: the page,
	928	the API and the event outbox carry its name and when it was set, nothing
	929	more. Left unchosen, a setting is a secret; say `kind: variable` to keep one in the clear. Setting a name again replaces it, kind included.
928	930	An app that prints one does not show it either: what an app writes to its
929	931	output is searched for the values it was handed (its variables, its identity
930	932	key and its forge token, each plain, base64 and URL-encoded) before the line
		@@ -950,6 +952,10 @@ where two apply the narrower one wins: a test key for
950	952	previews, the live one for production, and neither process ever holds the
951	953	other's. Every preview is one scope, whichever pull it serves.
952	954
	955	### One place for a secret
	956
	957	A secret lives where it matches who may use it, and a forge admin grants a wider one to an app by name: see [features/app-secrets.md](features/app-secrets.md).
	958
953	959	### Forge secrets
954	960
955	961	A credential the forge itself needs (a DNS token to spawn forges, a bucket
		@@ -973,7 +979,14 @@ with write access, declares what a run may hold in front-matter at the top:
973	979	secrets: [email protected], TF_BUCKET_KEY
974	980	---
975	981
976		Only declared names are resolved (`crew/grant.ts`); malformed names and names
	982	Only declared names are resolved (`crew/grant.ts`), and from the repository's
	983	own secrets or from a name the forge's owner granted to that repository
	984	(`secret_grant`, the grant an app's start reads). A declared name that is set
	985	at the organization or the forge and not granted is never opened: the run's
	986	log and one comment on the issue say "this run asked for X; the forge's owner
	987	has not granted X to owner/repo", with a link to grant it, whether X is set
	988	higher up or nowhere (a declaration learns nothing about which names exist);
	989	the run goes on without it. Malformed names and names
977	990	that would shadow the run's environment (`FORGE_`, `GIT_`, `PATH`, …) are
978	991	refused in the run's log. Values go into the run's env beside `FORGE_TOKEN`,
979	992	and `@host` widens the shell sandbox's egress for that run only. From the
		@@ -53,7 +53,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
53	53	\| `app_data_import` \| — \| Load a SQL dump into an app's database and report per-table counts and checksums; admins only \| 339 \|
54	54	\| `app_deploy` \| `redeploy`, `stop`, `pull`, `schedules`, `run_schedule`, `pause_schedule`, `resume_schedule`, `jobs`, `cancel_job`, `retry_job` \| Redeploy or stop an env, pull, list and steer schedules and jobs \| 408 \|
55	55	\| `app_domains` \| — \| App domains: list, add, check, keep, remove; dns_proof, dns_cut, dns_revert \| 266 \|
56		\| `app_env` \| `list`, `set`, `unset` \| An app's environment variables: list names, set or unset by scope; write-only \| 393 \|
	56	\| `app_env` \| `list`, `set`, `unset`, `variable`, `secret` \| An app's environment variables: list, set or unset by scope; a secret is write-only, a variable is shown \| 474 \|
57	57	\| `app_members` \| — \| People a private app names, who may enter it and its previews \| 297 \|
58	58	\| `app_notes` \| `hide`, `ban`, `unban` \| Notes from an app's forge button and banned senders; hide a note, ban or unban its sender \| 306 \|
59	59	\| `apps` \| — \| Apps you can see: live or not, where served, how each runs, what works \| 384 \|
		@@ -6,3 +6,5 @@ a `<section class="settings-block">` with an `<h2>`, one muted sentence (sealed
6	6	was set, when it was last opened, Remove), and the set form as an `.edit-row`. No card around it, and no icon in a
7	7	row's lead. Values are write-only: the value field is a password input that is never filled. `test/secrets-card.test.ts`
8	8	renders all three places and finds the same class names. Classes used are named in `docs/design/areas/settings.md`.
	9
	10	Each row also says which apps use the secret and whether each started with its current value (`usedBy()` in `secrets.ts`, plain text in the row's meta; no new class). The app's settings carry a `settings-block` of `row()`s, "Secrets this app uses" (`web/pages/app_secrets.ts`), likewise with existing classes only.
		@@ -0,0 +1,24 @@
	1	# One place for a secret (`Settings → App → Secrets this app uses`)
	2
	3	Put a secret where it matches who may use it: on the new-app page or the
	4	app's Environment (this app), an organization's page, or **Settings →
	5	Secrets** (the whole forge). An app lists the names it needs in `forge.json`
	6	(`"env": ["SIMPLEFIN_TOKEN"]`); at start each arrives from the nearest place
	7	that has it — the app, then the organization, then the forge — the last two
	8	only after a forge admin grants that name to that repository (**Settings →
	9	App → Secrets this app uses**, one click, revocable; the grant is the
	10	repository's, so a repository with no app holds one too and its crew's runs
	11	read through the same row; the table says
	12	needs / has / missing). A guest's preview nobody approved receives none of
	13	it. Setting a wider secret again restarts every app it was granted to, and
	14	its row on the Secrets page lists them and whether each started with the
	15	current value. A secret typed on the new-app page is the app's own at once
	16	and the first issue names it, never its value. Every open is a `secret.read`
	17	event (the app and environment, the name, never the value).
	18
	19
	20	## In the terminal
	21
	22	From a repository that is an app, the palette offers Variables (`src/tui/screens/appenv.ts`: `a` sets one, choosing its scope and whether it is a secret or a variable; the list shows each kind and a variable's value) and Secrets this app uses (`src/tui/screens/appsecrets.ts`: needs, has, missing; `a` grants, `x` revokes, a forge admin only).
	23
	24	Code: `src/core/app_secrets.ts`, `src/actions/secrets.ts` (`grantToRepo`, `revokeFromRepo`), `src/web/pages/app_secrets.ts`. Tests: `test/app-secrets.test.ts`, `test/app-secrets-web.test.ts`, `test/guest-pull.test.ts`.
		@@ -30,6 +30,7 @@ export const APP_ENV_ERRORS: Record<string, string> = {
30	30	"That name is the forge's own (PORT, HOST, PATH, FORGE_…); the app is already told it.",
31	31	invalid_value: "A value is one line or many, never empty and under 64 KiB.",
32	32	invalid_scope: "A variable goes everywhere, to production, or to previews.",
	33	invalid_kind: "A setting is a variable (plain, shown) or a secret (sealed, write-only).",
33	34	};
34	35
35	36	/** `setAppEnvVar` refused with a code the table does not name. */
		@@ -37,3 +38,10 @@ export const APP_ENV_NOT_SET = "That variable could not be set.";
37	38
38	39	/** `deleteAppEnvVar` refused as `no_such_var`. */
39	40	export const APP_ENV_NO_SUCH = "No variable by that name.";
	41
	42	/** Why `grantToRepo` or `revokeFromRepo` refused, by code; page and terminal say it alike. */
	43	export const GRANT_ERRORS: Record<string, string> = {
	44	not_found: "Only a forge admin can change a grant, and the repository must exist.",
	45	invalid_scope: "A grant draws from the forge or from the repository's organization.",
	46	no_such_secret: "No such secret is set there, or no such grant is held.",
	47	};
		@@ -49,6 +49,7 @@ import {
49	49	import {
50	50	DEFAULT_ENV_SCOPE,
51	51	deleteAppEnv,
	52	isReservedAppEnvName,
52	53	isAppEnvScope,
53	54	listAppEnvNames,
54	55	setAppEnv,
		@@ -56,6 +57,7 @@ import {
56	57	type AppEnvName,
57	58	type AppEnvScope,
58	59	} from "../core/app_env.ts";
	60	import { isSecretName, VALUE_MAX } from "../core/secret_store.ts";
59	61	import { addCrew, getAgentByName } from "../core/agents.ts";
60	62	import { listAllAgents } from "./crew.ts";
61	63	import { plan, planIssueBody, planningAvailable } from "../crew/plan.ts";
		@@ -170,30 +172,32 @@ export async function setAppEnvVar(
170	172	name: string,
171	173	value: string,
172	174	scope: string = DEFAULT_ENV_SCOPE,
	175	/**
	176	* `variable` or `secret`; left out, a secret.
	177	*/
	178	kind?: string,
173	179	): Promise<Result<AppEnvName, "not_found" \| AppEnvError>> {
174	180	const admin = requireRepoAdmin(app, actor, repo);
175	181	if (!admin.ok) return admin;
176	182	const record = getAppByRepo(app.db, repo.id);
177	183	if (!record) return err("not_found");
178		const set = setAppEnv(
179		app.db,
180		app.config.dataDir,
181		record.id,
182		name,
183		value,
184		scope,
185		);
	184	const set = setAppEnv(app.db, app.config.dataDir, record.id, name, value, scope, kindFor(kind));
186	185	if (!set.ok) return set;
187	186	app.bus.append({
188	187	kind: "app.env_set",
189	188	repoId: repo.id,
190	189	actorId: admin.value.id,
191		payload: { name, scope: set.value.scope },
	190	payload: { name, scope: set.value.scope, kind: set.value.kind },
192	191	});
193	192	await redeployScope(app, record, repo, set.value.scope);
194	193	return set;
195	194	}
196	195
	196	/** The kind a person chose; left out, a secret: a plain variable is something one asks for. */
	197	function kindFor(chosen: string \| undefined): string {
	198	return chosen === undefined \|\| chosen === "" \|\| chosen === "auto" ? "secret" : chosen;
	199	}
	200
197	201	/** Remove a variable from a scope and redeploy the environments that read it. */
198	202	export async function deleteAppEnvVar(
199	203	app: App,
		@@ -277,6 +281,11 @@ export interface NewAppInput {
277	281	pickAgent?: boolean;
278	282	/** `owner/name` of a repository the actor can read: its tip is copied instead of the starter app. */
279	283	template?: string;
	284	/**
	285	* Secrets typed while making the app: sealed at the app's own scope, so the first start has
	286	* them.
	287	*/
	288	secrets?: readonly { readonly name: string; readonly value: string }[];
280	289	}
281	290
282	291	export interface NewAppResult {
		@@ -295,7 +304,8 @@ export type NewAppError =
295	304	\| TemplateError
296	305	\| "no_such_agent"
297	306	\| "not_a_builder"
298		\| "app_limit";
	307	\| "app_limit"
	308	\| "invalid_secret";
299	309
300	310	/**
301	311	* The golden path's first step, as one call: a repository with a working
		@@ -320,6 +330,12 @@ export async function newApp(
320	330	if (input.agent && !agent) return err("no_such_agent");
321	331	if (agent && !agent.roles.includes("builder")) return err("not_a_builder");
322	332
	333	// A secret that cannot be sealed is refused before anything exists to take back.
	334	const secrets = (input.secrets ?? []).filter((x) => x.name !== "" \|\| x.value !== "");
	335	for (const x of secrets)
	336	if (!isSecretName(x.name) \|\| isReservedAppEnvName(x.name) \|\| x.value === "" \|\| x.value.length > VALUE_MAX \|\| x.value.includes("\0"))
	337	return err("invalid_secret");
	338
323	339	// Refuse at the limit before a repository exists to take back.
324	340	// The owner is resolved with the actor's rights, as createRepo does, so
325	341	// the count of an account they may not create under is never told.
		@@ -384,6 +400,16 @@ export async function newApp(
384	400	return err(record.error === "not_found" ? "scaffold_failed" : record.error);
385	401	}
386	402
	403	// Stored at the app's own scope: the first start has them, no second step.
	404	for (const x of secrets) setAppEnv(app.db, app.config.dataDir, record.value.id, x.name, x.value, "all", "secret");
	405	if (secrets.length > 0)
	406	app.bus.append({
	407	kind: "secret.set",
	408	repoId: repo.value.id,
	409	actorId: user.value.id,
	410	payload: { names: secrets.map((x) => x.name), scope: "all" },
	411	});
	412
387	413	const description = (input.description ?? "").trim();
388	414	let chosen = agent;
389	415	let body = description;
		@@ -436,6 +462,8 @@ export async function newApp(
436	462	}
437	463	// The sentence is the one thing the person wrote: it opens the first
438	464	// issue whether or not anyone was picked for it, unassigned when not.
	465	if (body !== "" && secrets.length > 0)
	466	body += `\n\nSecrets already set for this app (names only; read each from \`process.env\` and list it in forge.json \`env\`): ${secrets.map((x) => x.name).join(", ")}.`;
439	467	if (body !== "") {
440	468	const opened = openIssue(app, user.value, repo.value, {
441	469	title: `Build ${input.name}`,
		@@ -479,6 +507,8 @@ export const NEW_APP_ERRORS: Record<string, string> = {
479	507	git_init_failed: REPO_INIT_FAILED,
480	508	invalid_slug:
481	509	"That name makes no usable hostname — start it with a letter or digit.",
	510	invalid_secret:
	511	"A secret needs a name (capital letters, digits and underscores, like SIMPLEFIN_TOKEN) and a value under 64 KiB.",
482	512	slug_taken:
483	513	"Another app already answers to that hostname. Pick another name.",
484	514	already_app: "That repository is already an app.",
		@@ -8,8 +8,16 @@
8	8	*/
9	9
10	10	import type { App } from "../app.ts";
	11	import { createLog } from "../kernel/log.ts";
11	12	import { getOrg } from "../core/orgs.ts";
12		import { getRepo } from "../core/repos.ts";
	13	import { getRepo, getRepoById } from "../core/repos.ts";
	14	import { appsRuntime } from "../apps/runtime.ts";
	15	import { getAppById, getAppByRepo } from "../core/apps.ts";
	16	import { readerFor } from "../git/read.ts";
	17	import { repoDir } from "../git/repos.ts";
	18	import type { Repo } from "../core/repos.ts";
	19	import { requireRepoAdmin } from "./access.ts";
	20	import { neededNames, needRows, type NeedRow, appsUsing, grantable, grantSecret, revokeGrant, usesOf, type SecretUse } from "../core/app_secrets.ts";
13	21	import {
14	22	deleteSecret,
15	23	isSecretScope,
		@@ -51,6 +59,8 @@ function admin(actor: User \| undefined): Result<User, "not_found"> {
51	59	return actor?.isAdmin ? ok(actor) : err("not_found");
52	60	}
53	61
	62	const log = createLog("secrets");
	63
54	64	export function listSecrets(
55	65	app: App,
56	66	actor: User \| undefined,
		@@ -91,9 +101,90 @@ export function putSecret(
91	101	actorId: who.value.id,
92	102	payload: { name, scope: target.value.scope },
93	103	});
	104	restartUsers(app, target.value.scope, target.value.scopeId, name);
94	105	return set;
95	106	}
96	107
	108	/**
	109	* Setting a secret again is one change in one place; a process reads its
	110	* variables once at start, so each app it reaches starts again (previews
	111	* and production alike). Off the request: the person asked to store a value.
	112	*/
	113	export function restartUsers(app: App, scope: SecretScope, scopeId: string, name: string): void {
	114	for (const appId of appsUsing(app.db, scope, scopeId, name)) restartApp(app, appId);
	115	}
	116
	117	function restartApp(app: App, appId: string): void {
	118	const record = getAppById(app.db, appId);
	119	const repo = record && getRepoById(app.db, record.repoId);
	120	if (!record \|\| !repo) return;
	121	void appsRuntime(app)
	122	?.reconcileApp(record, repo, "redeploy", undefined)
	123	.catch((error: unknown) => log.warn("app restart after a secret change failed", { app: appId, error: String(error) }));
	124	}
	125
	126	/** Who a secret reaches and whether each started with its current value. */
	127	export function secretUses(app: App, scope: SecretScope, scopeId: string, name: string): SecretUse[] {
	128	return usesOf(app.db, scope, scopeId, name);
	129	}
	130
	131	/**
	132	* Grant a forge- or org-scope secret to one repository by name — its app and its crew's runs
	133	* both read through it: a forge admin's one click.
	134	*/
	135	export function grantToRepo(
	136	app: App,
	137	actor: User \| undefined,
	138	scope: string,
	139	ref: string,
	140	name: string,
	141	repoId: string,
	142	): Result<void, "not_found" \| "invalid_scope" \| "no_such_secret"> {
	143	const who = admin(actor);
	144	if (!who.ok) return who;
	145	if (scope !== "forge" && scope !== "org") return err("invalid_scope");
	146	const target = resolveTarget(app, scope, ref);
	147	if (!target.ok) return target;
	148	const repo = getRepoById(app.db, repoId);
	149	if (!repo) return err("not_found");
	150	if (!grantSecret(app.db, repo.id, scope, target.value.scopeId, name, who.value.id)) return err("no_such_secret");
	151	app.bus.append({
	152	kind: "secret.granted",
	153	repoId: repo.id,
	154	actorId: who.value.id,
	155	payload: { name, scope, repo: `${repo.ownerName}/${repo.name}` },
	156	});
	157	restartRepoApp(app, repo.id);
	158	return ok();
	159	}
	160
	161	/** Take a grant back; an app stops receiving the name at its next start, which this brings now. */
	162	export function revokeFromRepo(
	163	app: App,
	164	actor: User \| undefined,
	165	name: string,
	166	repoId: string,
	167	): Result<void, "not_found" \| "no_such_secret"> {
	168	const who = admin(actor);
	169	if (!who.ok) return who;
	170	const repo = getRepoById(app.db, repoId);
	171	if (!repo) return err("not_found");
	172	if (!revokeGrant(app.db, repo.id, name)) return err("no_such_secret");
	173	app.bus.append({
	174	kind: "secret.revoked",
	175	repoId: repo.id,
	176	actorId: who.value.id,
	177	payload: { name, repo: `${repo.ownerName}/${repo.name}` },
	178	});
	179	restartRepoApp(app, repo.id);
	180	return ok();
	181	}
	182
	183	function restartRepoApp(app: App, repoId: string): void {
	184	const record = getAppByRepo(app.db, repoId);
	185	if (record) restartApp(app, record.id);
	186	}
	187
97	188	export function removeSecret(
98	189	app: App,
99	190	actor: User \| undefined,
		@@ -115,3 +206,24 @@ export function removeSecret(
115	206	});
116	207	return ok();
117	208	}
	209
	210	/**
	211	* What an app asks for in `forge.json` `env`, against what is set: needs / has / missing, never
	212	* a value.
	213	*/
	214	export async function appSecretNeeds(
	215	app: App,
	216	actor: User \| undefined,
	217	repo: Repo,
	218	): Promise<Result<{ needs: NeedRow[]; grantable: { name: string; scope: "forge" \| "org" }[] }, "not_found">> {
	219	const gate = requireRepoAdmin(app, actor, repo);
	220	if (!gate.ok) return gate;
	221	const record = getAppByRepo(app.db, repo.id);
	222	const file = await readerFor(repoDir(app.reposRoot, repo.ownerName, repo.name)).object("HEAD:forge.json");
	223	const text = file.ok && file.value.type === "blob" ? new TextDecoder().decode(file.value.body.slice(0, 65_536)) : undefined;
	224	const needs = needRows(app.db, { appId: record?.id ?? "", repoId: repo.id, ownerId: repo.ownerId, needs: neededNames(text) });
	225	const asked = new Set(needs.map((n) => n.name));
	226	// Names only, and only to a forge admin: what the crew or the app could be granted by name.
	227	const offer = actor?.isAdmin === true ? grantable(app.db, repo.id, repo.ownerId).filter((g) => !asked.has(g.name)) : [];
	228	return ok({ needs, grantable: offer });
	229	}
		@@ -10,6 +10,7 @@
10	10	* simply not an app yet, which the surfaces say in those words.
11	11	*/
12	12
	13	import { parseNeeds } from "../core/app_secrets.ts";
13	14	import { isIP } from "node:net";
14	15	import { err, ok, type Result } from "../kernel/result.ts";
15	16	import { parseService, type ServiceSpec } from "./service.ts";
		@@ -79,6 +80,11 @@ export interface AppManifest {
79	80	* out of the app's HTML pages. Unset is on.
80	81	*/
81	82	readonly toolbar?: boolean \| undefined;
	83	/**
	84	* `env` (top level of `forge.json`): the secret names the app reads from its environment
	85	* (`core/app_secrets.ts`).
	86	*/
	87	readonly env?: readonly string[] \| undefined;
82	88	/**
83	89	* `adapter` (top level of `forge.json`): the app is pulled from on a
84	90	* schedule (`apps/adapter.ts`). Unset is not an adapter.
		@@ -186,6 +192,8 @@ export function parseManifest(
186	192	if (!egress.ok) return egress;
187	193	const limits = limitsField(app, "app");
188	194	if (!limits.ok) return limits;
	195	const needs = parseNeeds(parsed.value["env"]);
	196	if (!needs.ok) return invalid(needs.error);
189	197	const toolbar = parsed.value["toolbar"];
190	198	if (toolbar !== undefined && typeof toolbar !== "boolean")
191	199	return invalid("forge.json: toolbar must be true or false");
		@@ -235,6 +243,7 @@ export function parseManifest(
235	243	egress: egress.value,
236	244	limits: limits.value,
237	245	toolbar: toolbar ?? true,
	246	...(needs.value.length === 0 ? {} : { env: needs.value }),
238	247	...(adapter.value === undefined ? {} : { adapter: adapter.value }),
239	248	...(toolchain.value === undefined ? {} : { toolchain: toolchain.value }),
240	249	...(schedules.value.length === 0 ? {} : { schedules: schedules.value }),
		@@ -30,6 +30,7 @@ import { join } from "node:path";
30	30	import type { App } from "../app.ts";
31	31	import { getAppByRepo, listApps, type AppRecord } from "../core/apps.ts";
32	32	import { resolveAppEnv } from "../core/app_env.ts";
	33	import { neededNames, resolveAppSecrets } from "../core/app_secrets.ts";
33	34	import { featureVarsAt } from "./feature_env.ts";
34	35	import { getVariant, listVariants, variantOfBranch } from "../core/variants.ts";
35	36	import { readVariantValues } from "./variant_file.ts";
		@@ -1878,6 +1879,27 @@ export class AppsRuntime {
1878	1879	return featureVarsAt(this.app.db, this.app.config.dataDir, appId, forgeJson);
1879	1880	}
1880	1881
	1882	/**
	1883	* The app's sealed secrets for a start: its own, and each granted name its forge.json asks
	1884	* for.
	1885	*/
	1886	sealedFor(repo: Repo, appId: string, env: EnvName, dir?: string, start = true): Record<string, string> {
	1887	let forgeJson: string \| undefined;
	1888	try {
	1889	forgeJson = dir === undefined ? undefined : readFileSync(join(dir, "forge.json"), "utf8");
	1890	} catch {
	1891	forgeJson = undefined;
	1892	}
	1893	return resolveAppSecrets(this.app.db, this.app.config.dataDir, this.app.bus, {
	1894	appId,
	1895	repoId: repo.id,
	1896	ownerId: repo.ownerId,
	1897	env,
	1898	needs: neededNames(forgeJson),
	1899	start,
	1900	});
	1901	}
	1902
1881	1903	/**
1882	1904	* What a process for `env` starts holding: the operator's variables, read
1883	1905	* at start, and the forge token. A preview of a guest pull nobody has
		@@ -1891,6 +1913,7 @@ export class AppsRuntime {
1891	1913	env: EnvName,
1892	1914	forgeToken: string \| undefined,
1893	1915	dir?: string,
	1916	start = true,
1894	1917	): { vars: Record<string, string>; forgeToken: string \| undefined } {
1895	1918	const number = envPull(env);
1896	1919	const pull =
		@@ -1901,7 +1924,7 @@ export class AppsRuntime {
1901	1924	// app's defaults; they are plain settings, never secrets.
1902	1925	const own = dir !== undefined && envVariant(env) !== undefined ? readVariantValues(dir) : {};
1903	1926	return {
1904		vars: { ...resolveAppEnv(this.app.db, this.app.config.dataDir, appId, env), ...own },
	1927	vars: { ...this.sealedFor(repo, appId, env, dir, start), ...resolveAppEnv(this.app.db, this.app.config.dataDir, appId, env), ...own },
1905	1928	forgeToken,
1906	1929	};
1907	1930	}
		@@ -179,7 +179,7 @@ export async function runAppTty(
179	179	// same secrets, so it is handed the same environment, by the one reader
180	180	// the app's own process has. A guest pull's preview nobody has approved
181	181	// holds none there, so its terminal (a command the pull names) holds none.
182		vars: runtime.secretsFor(repo, target.app.id, target.env, undefined, live.dir).vars,
	182	vars: runtime.secretsFor(repo, target.app.id, target.env, undefined, live.dir, false).vars,
183	183	// An absorbed app's settings, as its process was started with.
184	184	feature: runtime.featureFor(repo, target.app.id, target.env, live.dir),
185	185	});