@davidvornholt/standards 0.19.0 → 0.20.0

package/src/creds-add.ts

@@ -1,7 +1,12 @@
 import { commitCreatedCloudflareToken } from './creds-add-cloudflare-commit';
 import { findManagedDestinationCollision } from './creds-add-collision';
 import { resolveTokenPolicy } from './creds-add-policy';
+import {
+  inspectDestinations,
+  resolveResourceFlags,
+} from './creds-add-preflight';
 import { createAccountToken } from './creds-cloudflare';
+import type { TokenPolicy } from './creds-cloudflare-api';
 import { cloudflareExpiresOn } from './creds-cloudflare-expiry';
 import { resolveContext, selectAccount } from './creds-dest';
 import { tokenNameOf } from './creds-naming';
@@ -13,11 +18,7 @@ import {
   s3Endpoint,
   s3PairPaths,
 } from './creds-r2';
-import {
-  inspectSopsScalarDestination,
-  readEncryptedKeys,
-  setSopsValues,
-} from './creds-sops';
+import { readEncryptedKeys, setSopsValues } from './creds-sops';
 
 const DEFAULT_TTL_DAYS = 90;
 const DAY_MS = 86_400_000;
@@ -30,9 +31,16 @@ const printSuccess = (input: {
   readonly format: DestinationFormat;
   readonly accountId: string;
   readonly jurisdiction: R2Jurisdiction;
+  readonly policies: ReadonlyArray<TokenPolicy>;
 }): void => {
   console.log(`standards creds: minted Cloudflare token ${input.name}`);
   console.log(`  permissions: ${input.permissions.join(', ')}`);
+  // Read off the minted policies rather than the flags that asked for them:
+  // a selection can add an account policy the flags do not mention, and the
+  // reach of a token is the one thing worth stating from ground truth.
+  console.log(
+    `  resources: ${input.policies.flatMap((policy) => Object.keys(policy.resources)).join(', ')}`,
+  );
   console.log(
     `  expires: ${input.expiresOn} (rotate via \`standards creds apply\`)`,
   );
@@ -46,18 +54,6 @@ const printSuccess = (input: {
   }
 };
 
-const inspectDestinations = async (
-  consumer: string,
-  rel: string,
-  paths: ReadonlyArray<string>,
-): Promise<string | null> => {
-  const inspected = await Promise.all(
-    paths.map((path) => inspectSopsScalarDestination(consumer, rel, path)),
-  );
-  const blocked = inspected.find((result) => !result.ok);
-  return blocked !== undefined && !blocked.ok ? blocked.problem : null;
-};
-
 export const runCredsAddCloudflare = async (
   consumer: string,
   options: {
@@ -66,6 +62,7 @@ export const runCredsAddCloudflare = async (
     readonly account: string | undefined;
     readonly ttlDays: number | undefined;
     readonly bucket: string | undefined;
+    readonly zone: string | undefined;
     readonly jurisdiction?: R2Jurisdiction;
     readonly s3: boolean;
   },
@@ -76,6 +73,11 @@ export const runCredsAddCloudflare = async (
     );
     return false;
   }
+  const flags = resolveResourceFlags(options);
+  if (!flags.ok) {
+    console.error(`standards creds: ${flags.problem}`);
+    return false;
+  }
   const context = await resolveContext(consumer, options.dest);
   if (context === null) {
     return false;
@@ -102,7 +104,10 @@ export const runCredsAddCloudflare = async (
     return false;
   }
   const keys = new Set(encryptedKeys.keys);
-  const resolved = await resolveTokenPolicy(account, options);
+  const resolved = await resolveTokenPolicy(account, {
+    permissions: options.permissions,
+    resource: flags.resource,
+  });
   if (!resolved.ok) {
     console.error(`standards creds: ${resolved.problem}`);
     return false;
@@ -123,7 +128,7 @@ export const runCredsAddCloudflare = async (
     name,
     expiresOn,
     condition: null,
-    policies: [resolved.policy],
+    policies: resolved.policies,
   });
   if (!created.ok) {
     console.error(`standards creds: ${created.problem}`);
@@ -157,7 +162,11 @@ export const runCredsAddCloudflare = async (
     destination: `${context.rel} at ${context.dest.key}`,
     format,
     accountId: account.accountId,
-    jurisdiction: options.jurisdiction ?? DEFAULT_R2_JURISDICTION,
+    jurisdiction:
+      flags.resource.kind === 'bucket'
+        ? flags.resource.jurisdiction
+        : DEFAULT_R2_JURISDICTION,
+    policies: resolved.policies,
   });
   return true;
 };

package/src/creds-args.ts

@@ -17,6 +17,7 @@ export type CredsFlags = {
   account: string | undefined;
   ttlDays: number | undefined;
   bucket: string | undefined;
+  zone: string | undefined;
   jurisdiction: R2Jurisdiction;
   s3: boolean;
   org: string | undefined;
@@ -51,6 +52,7 @@ export const parseCredsArgs = (argv: ReadonlyArray<string>): CredsFlags => {
     account: undefined,
     ttlDays: undefined,
     bucket: undefined,
+    zone: undefined,
     jurisdiction: DEFAULT_R2_JURISDICTION,
     s3: false,
     org: undefined,
@@ -76,6 +78,9 @@ export const parseCredsArgs = (argv: ReadonlyArray<string>): CredsFlags => {
     '--bucket': (value) => {
       flags.bucket = value;
     },
+    '--zone': (value) => {
+      flags.zone = value;
+    },
     '--jurisdiction': (value) => {
       if (!isR2Jurisdiction(value)) {
         throw new Error('--jurisdiction must be default or eu');

package/src/creds-cloudflare-zone.ts

@@ -0,0 +1,40 @@
+// Zone resources for `standards creds add cloudflare`. Zones are named by ID,
+// never by domain name: resolving a name would need Zone Read on the bootstrap
+// token, which holds Account API Tokens / Edit and nothing else, so the lookup
+// would fail — or, worse, come back empty and read as a missing zone. A zone ID
+// is not a secret and is shown on the zone's dashboard overview.
+
+export const ZONE_SCOPE = 'com.cloudflare.api.account.zone';
+
+const ZONE_ID_PATTERN = /^[0-9a-f]{32}$/u;
+
+export const zoneResource = (zoneId: string): string =>
+  `${ZONE_SCOPE}.${zoneId}`;
+
+export type ParsedZoneArgument =
+  | {
+      readonly ok: true;
+      readonly zoneIds: readonly [string, ...ReadonlyArray<string>];
+    }
+  | { readonly ok: false; readonly problem: string };
+
+export const parseZoneArgument = (value: string): ParsedZoneArgument => {
+  const [first, ...rest] = value
+    .split(',')
+    .map((zone) => zone.trim())
+    .filter((zone) => zone.length > 0);
+  if (first === undefined) {
+    return {
+      ok: false,
+      problem: '--zone requires at least one zone ID',
+    };
+  }
+  const entries = [first, ...rest] as const;
+  const invalid = entries.filter((zone) => !ZONE_ID_PATTERN.test(zone));
+  return invalid.length === 0
+    ? { ok: true, zoneIds: entries }
+    : {
+        ok: false,
+        problem: `not a zone ID: ${invalid.join(', ')}; --zone takes the 32-character hexadecimal zone ID shown on the zone's dashboard overview, not its domain name`,
+      };
+};

package/src/creds-commands.ts

@@ -2,6 +2,7 @@ import { runCredsAddCloudflare } from './creds-add';
 import { runCredsAddGithub } from './creds-add-github';
 import { parseCredsArgs } from './creds-args';
 import { listPermissionGroups } from './creds-cloudflare';
+import { loadOwnedGithubStore } from './creds-github-apps';
 import { runCredsLoginCloudflare } from './creds-login-cloudflare';
 import { runCredsLoginGithub } from './creds-login-github';
 import { BROKER_IDENTITY_NAME } from './creds-naming';
@@ -15,10 +16,10 @@ import {
 const CREDS_USAGE = `Usage: standards creds <command> [options]
 
 Commands:
-  login github      Create the broker GitHub App via the manifest flow (one click) and store its credentials
+  login github      Create or replace one account's broker GitHub App via the manifest flow
   login cloudflare  Store a Cloudflare account's bootstrap token (one guided paste per account)
   add cloudflare    Mint a scoped, expiring account token and write it into a SOPS target
-  add github        Write the broker App's credentials into a SOPS target for runtime token minting
+  add github        Select the repository owner's App, verify its installation, and write it into SOPS
   plan              Show revocations and rotations reconciling SOPS keys against brokered tokens
   apply             Execute the plan: revoke orphaned tokens, roll expiring ones into SOPS
   permissions       List Cloudflare permission group names for --permissions
@@ -31,15 +32,21 @@ Options:
   --account <id>        Cloudflare account when more than one is configured
   --ttl-days <n>        Token lifetime in days (default: 90)
   --bucket <name>       Scope a Cloudflare token to one R2 bucket
+  --zone <zone-id>      Add a zone resource for zone-scoped groups (comma-separated IDs)
   --jurisdiction <name> R2 jurisdiction: default or eu (default: default)
   --s3                  Store the derived R2 S3 credential pair (<key>.access_key_id, <key>.secret_access_key) instead of the raw token
   --org <org>           Create the GitHub App under an organization
-  --name <name>         GitHub App name (default: ${BROKER_IDENTITY_NAME})
+  --name <name>         GitHub App name (default: ${BROKER_IDENTITY_NAME}, suffixed by --org)
 
 Secret values are written directly into SOPS-encrypted targets and never printed.`;
 const runCredsStatus = async (): Promise<boolean> => {
   const path = resolveBrokerPath();
-  const store = await readBrokerStore(path);
+  const loaded = await loadOwnedGithubStore(path);
+  if (!loaded.ok) {
+    console.error(`standards creds: ${loaded.problem}`);
+    return false;
+  }
+  const { value: store } = loaded;
   console.log(`broker store: ${path}`);
   const mode = inspectBrokerFileMode(path);
   if (!mode.exists) {
@@ -47,11 +54,16 @@ const runCredsStatus = async (): Promise<boolean> => {
   } else if (mode.problem !== null) {
     console.log(`  WARNING: ${mode.problem}`);
   }
-  console.log(
-    store.github === null
-      ? 'github: not configured (`standards creds login github`)'
-      : `github: App ${store.github.slug} (id ${store.github.appId}) — ${store.github.htmlUrl}`,
-  );
+  if (store.github.length === 0) {
+    console.log('github: not configured (`standards creds login github`)');
+  } else {
+    console.log('github:');
+    for (const app of store.github) {
+      console.log(
+        `  ${app.owner}: App ${app.slug} (id ${app.appId}) — ${app.htmlUrl}`,
+      );
+    }
+  }
   console.log(
     store.cloudflare.length === 0
       ? 'cloudflare: not configured (`standards creds login cloudflare`)'

package/src/creds-github-app-api.ts

@@ -0,0 +1,132 @@
+import { createSign } from 'node:crypto';
+import type { GithubBrokerApp } from './creds-store';
+import { type ApiResponse, apiError, HTTP_OK, request } from './github-api';
+import { isNonEmptyString, isRecord } from './github-settings-parse';
+
+const JWT_CLOCK_SKEW_SECONDS = 60;
+const SECONDS_PER_MINUTE = 60;
+const JWT_LIFETIME_MINUTES = 9;
+const JWT_LIFETIME_SECONDS = JWT_LIFETIME_MINUTES * SECONDS_PER_MINUTE;
+const MILLISECONDS_PER_SECOND = 1000;
+const HTTP_NOT_FOUND = 404;
+
+type GithubAppResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly problem: string };
+
+export const createGithubAppJwt = (
+  app: GithubBrokerApp,
+  now = Date.now(),
+): string => {
+  const seconds = Math.floor(now / MILLISECONDS_PER_SECOND);
+  const header = Buffer.from(
+    JSON.stringify({ alg: 'RS256', typ: 'JWT' }),
+  ).toString('base64url');
+  const payload = Buffer.from(
+    JSON.stringify({
+      iat: seconds - JWT_CLOCK_SKEW_SECONDS,
+      exp: seconds + JWT_LIFETIME_SECONDS,
+      iss: app.clientId,
+    }),
+  ).toString('base64url');
+  const unsigned = `${header}.${payload}`;
+  const signature = createSign('RSA-SHA256')
+    .update(unsigned)
+    .sign(app.privateKey, 'base64url');
+  return `${unsigned}.${signature}`;
+};
+
+const appRequest = async (
+  app: GithubBrokerApp,
+  path: string,
+): Promise<GithubAppResult<ApiResponse>> => {
+  try {
+    return {
+      ok: true,
+      value: await request(createGithubAppJwt(app), 'GET', path),
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      ok: false,
+      problem: `cannot authenticate as App ${app.slug}: ${message}`,
+    };
+  }
+};
+
+export const resolveGithubAppOwner = async (
+  app: GithubBrokerApp,
+): Promise<GithubAppResult<string>> => {
+  const result = await appRequest(app, '/app');
+  if (!result.ok) {
+    return result;
+  }
+  if (result.value.status !== HTTP_OK) {
+    return {
+      ok: false,
+      problem: apiError(`resolve owner for App ${app.slug}`, result.value),
+    };
+  }
+  const { body } = result.value;
+  if (
+    !isRecord(body) ||
+    body.id !== app.appId ||
+    !isRecord(body.owner) ||
+    !isNonEmptyString(body.owner.login)
+  ) {
+    return {
+      ok: false,
+      problem: `resolve owner for App ${app.slug}: unexpected response shape or App identity`,
+    };
+  }
+  return { ok: true, value: body.owner.login };
+};
+
+export const verifyGithubAppInstallation = async (
+  app: GithubBrokerApp,
+  repo: string,
+): Promise<GithubAppResult<true>> => {
+  const [owner, name, ...rest] = repo.split('/');
+  if (
+    owner === undefined ||
+    name === undefined ||
+    owner.length === 0 ||
+    name.length === 0 ||
+    rest.length > 0
+  ) {
+    return { ok: false, problem: `invalid GitHub repository: ${repo}` };
+  }
+  const result = await appRequest(
+    app,
+    `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/installation`,
+  );
+  if (!result.ok) {
+    return result;
+  }
+  if (result.value.status === HTTP_NOT_FOUND) {
+    return {
+      ok: false,
+      problem: `App ${app.slug} for ${owner} is not installed on ${repo}; install it for that selected repository at ${app.htmlUrl}/installations/new`,
+    };
+  }
+  if (result.value.status !== HTTP_OK) {
+    return {
+      ok: false,
+      problem: apiError(`verify App installation on ${repo}`, result.value),
+    };
+  }
+  const { body } = result.value;
+  if (
+    !isRecord(body) ||
+    body.app_id !== app.appId ||
+    !isRecord(body.account) ||
+    !isNonEmptyString(body.account.login) ||
+    body.account.login.toLowerCase() !== owner.toLowerCase()
+  ) {
+    return {
+      ok: false,
+      problem: `verify App installation on ${repo}: unexpected App or account identity`,
+    };
+  }
+  return { ok: true, value: true };
+};

package/src/creds-github-apps.ts

@@ -0,0 +1,107 @@
+import { resolveGithubAppOwner } from './creds-github-app-api';
+import {
+  type BrokerStore,
+  type GithubBrokerApp,
+  readBrokerStore,
+  updateBrokerStore,
+} from './creds-store';
+
+type GithubAppsResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly problem: string };
+
+export const sameGithubApp = (
+  left: GithubBrokerApp,
+  right: GithubBrokerApp,
+): boolean =>
+  left.owner?.toLowerCase() === right.owner?.toLowerCase() &&
+  left.appId === right.appId &&
+  left.slug === right.slug &&
+  left.htmlUrl === right.htmlUrl &&
+  left.clientId === right.clientId &&
+  left.privateKey === right.privateKey;
+
+export const loadOwnedGithubStore = async (
+  path: string,
+  lookupOwner: (
+    app: GithubBrokerApp,
+  ) => Promise<GithubAppsResult<string>> = resolveGithubAppOwner,
+): Promise<GithubAppsResult<BrokerStore>> => {
+  const initial = await readBrokerStore(path);
+  const legacy = initial.github.find((app) => app.owner === null);
+  if (legacy === undefined) {
+    return { ok: true, value: initial };
+  }
+  const owner = await lookupOwner(legacy);
+  if (!owner.ok) {
+    return {
+      ok: false,
+      problem: `cannot migrate the legacy singleton GitHub App in ${path}: ${owner.problem}`,
+    };
+  }
+  await updateBrokerStore(path, (current) => ({
+    ...current,
+    github: current.github.map((app) =>
+      app.owner === null && sameGithubApp(app, legacy)
+        ? { ...app, owner: owner.value }
+        : app,
+    ),
+  }));
+  const migrated = await readBrokerStore(path);
+  if (migrated.github.some((app) => app.owner === null)) {
+    return {
+      ok: false,
+      problem: `the GitHub App in ${path} changed while its legacy owner was being migrated; retry`,
+    };
+  }
+  return { ok: true, value: migrated };
+};
+
+export const selectGithubAppForRepo = (
+  apps: ReadonlyArray<GithubBrokerApp>,
+  repo: string,
+): GithubAppsResult<GithubBrokerApp> => {
+  const owner = repo.split('/')[0] ?? '';
+  const matches = apps.filter(
+    (app) => app.owner?.toLowerCase() === owner.toLowerCase(),
+  );
+  if (matches.length === 1 && matches[0] !== undefined) {
+    return { ok: true, value: matches[0] };
+  }
+  if (matches.length > 1) {
+    return {
+      ok: false,
+      problem: `multiple broker GitHub Apps are configured for repository owner ${owner}; keep exactly one entry for that owner`,
+    };
+  }
+  const loginHint =
+    apps.length === 0
+      ? 'no broker GitHub Apps are configured'
+      : `configured owners: ${apps.map((app) => app.owner).join(', ')}`;
+  return {
+    ok: false,
+    problem: `no broker GitHub App is configured for repository owner ${owner} (${loginHint}); run \`standards creds login github --org ${owner}\` for an organization, or run it without --org while signed in as ${owner}`,
+  };
+};
+
+export const upsertGithubApp = (
+  apps: ReadonlyArray<GithubBrokerApp>,
+  app: GithubBrokerApp,
+): {
+  readonly apps: ReadonlyArray<GithubBrokerApp>;
+  readonly replaced: GithubBrokerApp | null;
+} => {
+  if (app.owner === null || apps.some((entry) => entry.owner === null)) {
+    throw new Error('legacy GitHub Apps must be migrated before login');
+  }
+  const index = apps.findIndex(
+    (entry) => entry.owner?.toLowerCase() === app.owner?.toLowerCase(),
+  );
+  if (index === -1) {
+    return { apps: [...apps, app], replaced: null };
+  }
+  return {
+    apps: apps.map((entry, entryIndex) => (entryIndex === index ? app : entry)),
+    replaced: apps[index] ?? null,
+  };
+};

package/src/creds-login-github-manifest.ts

@@ -4,11 +4,35 @@
 // creds-login-github.ts.
 
 import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { BROKER_IDENTITY_NAME } from './creds-naming';
 import type { GithubBrokerApp } from './creds-store';
+import { isGithubBrokerApp } from './creds-store-github';
 import { apiError, HTTP_CREATED, request } from './github-api';
 import { isRecord } from './github-settings-parse';
 
 export const MANIFEST_STATE_BYTES = 32;
+const GITHUB_APP_NAME_MAX_LENGTH = 34;
+
+type GithubAppNameResult =
+  | { readonly ok: true; readonly value: string }
+  | { readonly ok: false; readonly problem: string };
+
+export const resolveGithubAppName = (
+  requested: string | undefined,
+  org: string | undefined,
+): GithubAppNameResult => {
+  const name =
+    requested ??
+    (org === undefined
+      ? BROKER_IDENTITY_NAME
+      : `${BROKER_IDENTITY_NAME}-${org}`);
+  return name.length <= GITHUB_APP_NAME_MAX_LENGTH
+    ? { ok: true, value: name }
+    : {
+        ok: false,
+        problem: `GitHub App names may contain at most ${GITHUB_APP_NAME_MAX_LENGTH} characters; pass --name with a shorter globally unique name`,
+      };
+};
 
 // Root-credential ceiling: everything the broker may ever delegate. The
 // `permission-*` inputs a workflow passes when minting are a request, not a
@@ -70,21 +94,20 @@ export const manifestFormHtml = (
 ): string =>
   `<!doctype html><html><body><form id="m" action="${escapeAttribute(`${action}?state=${encodeURIComponent(state)}`)}" method="post"><input type="hidden" name="manifest" value="${escapeAttribute(manifest)}"><noscript><button type="submit">Create GitHub App</button></noscript></form><script>document.getElementById("m").submit()</script></body></html>`;
 
-export const parseConversion = (body: unknown): GithubBrokerApp | null =>
-  isRecord(body) &&
-  typeof body.id === 'number' &&
-  typeof body.slug === 'string' &&
-  typeof body.html_url === 'string' &&
-  typeof body.client_id === 'string' &&
-  typeof body.pem === 'string'
-    ? {
-        appId: body.id,
-        slug: body.slug,
-        htmlUrl: body.html_url,
-        clientId: body.client_id,
-        privateKey: body.pem,
-      }
-    : null;
+export const parseConversion = (body: unknown): GithubBrokerApp | null => {
+  if (!(isRecord(body) && isRecord(body.owner))) {
+    return null;
+  }
+  const app = {
+    owner: body.owner.login,
+    appId: body.id,
+    slug: body.slug,
+    htmlUrl: body.html_url,
+    clientId: body.client_id,
+    privateKey: body.pem,
+  };
+  return isGithubBrokerApp(app) && app.owner !== null ? app : null;
+};
 
 export type ManifestConversion =
   | { readonly ok: true; readonly app: GithubBrokerApp }