@davidvornholt/standards 0.18.0 → 0.20.0

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 }

package/src/creds-login-github.ts

@@ -1,15 +1,20 @@
 import { randomBytes } from 'node:crypto';
 import { openInBrowser } from './creds-browser';
+import {
+  loadOwnedGithubStore,
+  sameGithubApp,
+  upsertGithubApp,
+} from './creds-github-apps';
 import {
   buildAppManifest,
   convertManifestCode,
   createManifestState,
   MANIFEST_STATE_BYTES,
   manifestFormHtml,
+  resolveGithubAppName,
 } from './creds-login-github-manifest';
-import { BROKER_IDENTITY_NAME } from './creds-naming';
 import {
-  readBrokerStore,
+  type GithubBrokerApp,
   resolveBrokerPath,
   updateBrokerStore,
 } from './creds-store';
@@ -84,50 +89,99 @@ export const waitForCode = (
 };
 export const githubInstallMessage = (installUrl: string): string =>
   `Install it only on the selected repositories that need broker credentials: ${installUrl}`;
-export const runCredsLoginGithub = async (options: {
-  readonly name: string | undefined;
-  readonly org: string | undefined;
-}): Promise<boolean> => {
+
+type GithubLoginDependencies = {
+  readonly waitForCode: typeof waitForCode;
+  readonly convertManifestCode: typeof convertManifestCode;
+  readonly openInBrowser: typeof openInBrowser;
+};
+
+const DEFAULT_LOGIN_DEPENDENCIES: GithubLoginDependencies = {
+  waitForCode,
+  convertManifestCode,
+  openInBrowser,
+};
+
+export const runCredsLoginGithub = async (
+  options: {
+    readonly name: string | undefined;
+    readonly org: string | undefined;
+  },
+  dependencies: GithubLoginDependencies = DEFAULT_LOGIN_DEPENDENCIES,
+): Promise<boolean> => {
+  const resolvedName = resolveGithubAppName(options.name, options.org);
+  if (!resolvedName.ok) {
+    console.error(`standards creds: ${resolvedName.problem}`);
+    return false;
+  }
   const storePath = resolveBrokerPath();
-  const store = await readBrokerStore(storePath);
-  if (store.github !== null) {
-    console.error(
-      `standards creds: a broker GitHub App is already configured (${store.github.htmlUrl}); remove the "github" section from ${storePath} to re-run login`,
-    );
+  const loaded = await loadOwnedGithubStore(storePath);
+  if (!loaded.ok) {
+    console.error(`standards creds: ${loaded.problem}`);
     return false;
   }
   const action =
     options.org === undefined
       ? 'https://github.com/settings/apps/new'
       : `https://github.com/organizations/${options.org}/settings/apps/new`;
-  const name = options.name ?? BROKER_IDENTITY_NAME;
-  const code = await waitForCode((port, state) =>
+  const code = await dependencies.waitForCode((port, state) =>
     manifestFormHtml(
       action,
       JSON.stringify(
-        buildAppManifest(name, `http://127.0.0.1:${port}/callback`),
+        buildAppManifest(
+          resolvedName.value,
+          `http://127.0.0.1:${port}/callback`,
+        ),
       ),
       state,
     ),
   );
-  const conversion = await convertManifestCode(code);
+  const conversion = await dependencies.convertManifestCode(code);
   if (!conversion.ok) {
     console.error(`standards creds: ${conversion.problem}`);
     return false;
   }
   const { app } = conversion;
-  await updateBrokerStore(storePath, (current) => {
-    if (current.github !== null) {
-      throw new Error(
-        `a broker GitHub App was configured while login was in progress (${current.github.htmlUrl}); the newly created App ${app.htmlUrl} was not stored and should be deleted`,
+  const observed = loaded.value.github.find(
+    (entry) => entry.owner?.toLowerCase() === app.owner?.toLowerCase(),
+  );
+  let replaced: GithubBrokerApp | undefined;
+  try {
+    await updateBrokerStore(storePath, (current) => {
+      const currentEntry = current.github.find(
+        (entry) => entry.owner?.toLowerCase() === app.owner?.toLowerCase(),
       );
-    }
-    return { ...current, github: app };
-  });
-  console.log(`standards creds: created App ${app.slug} (${app.htmlUrl})`);
+      const unchanged =
+        observed === undefined
+          ? currentEntry === undefined
+          : currentEntry !== undefined && sameGithubApp(currentEntry, observed);
+      if (!unchanged) {
+        throw new Error(
+          `the broker App for ${app.owner} changed while this App was being created`,
+        );
+      }
+      const upserted = upsertGithubApp(current.github, app);
+      replaced = upserted.replaced ?? undefined;
+      return { ...current, github: upserted.apps };
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(
+      `standards creds: the newly created App ${app.htmlUrl} was not stored (${message}); retry login, and delete the new App if it is still absent from \`creds status\``,
+    );
+    return false;
+  }
+  console.log(
+    `standards creds: created App ${app.slug} for ${app.owner} (${app.htmlUrl})`,
+  );
   console.log(`  credentials stored in ${storePath}`);
+  if (replaced !== undefined) {
+    console.log(
+      `  replaced App ${replaced.slug} for ${app.owner}; update its SOPS destinations, verify token minting, then delete the old App`,
+    );
+  }
   const installUrl = `${app.htmlUrl}/installations/new`;
   console.log(githubInstallMessage(installUrl));
-  openInBrowser(installUrl);
+  dependencies.openInBrowser(installUrl);
   return true;
 };

package/src/creds-plan-renew.ts

@@ -7,11 +7,8 @@ import { createAccountToken, deleteAccountToken } from './creds-cloudflare';
 import { resolveTargetRel } from './creds-dest';
 import type { PlannedAction } from './creds-plan-types';
 import { destinationWrites, s3AccessKeyPath, s3PairPaths } from './creds-r2';
-import {
-  inspectSopsScalarDestination,
-  setSopsValues,
-  verifySopsStoredValue,
-} from './creds-sops';
+import { inspectSopsScalarDestination, setSopsValues } from './creds-sops';
+import { verifySopsStoredValue } from './creds-sops-value';
 import type { CloudflareBrokerAccount } from './creds-store';
 
 type RenewAction = Extract<PlannedAction, { readonly kind: 'renew' }>;

package/src/creds-sops-value.ts

@@ -0,0 +1,89 @@
+// Proving that a stored secret matches the value that was just minted, without
+// that value reaching a return type, a log line, or an error message. Callers
+// destroy the new credential on a proven mismatch and keep it on an
+// unverifiable read, so the two negative answers must stay distinct: anything
+// that is not a leaf we can read as a scalar string is unverifiable.
+
+import { isContainedSopsPath, parseSopsKeyPath } from './creds-sops-structure';
+import { runSops } from './sops-exec';
+
+export type SopsStoredValueVerification =
+  | { readonly ok: true; readonly matches: boolean }
+  | { readonly ok: false; readonly problem: string };
+type SopsStoredValueInput = {
+  readonly consumer: string;
+  readonly rel: string;
+  readonly dottedPath: string;
+  readonly expectedValue: string;
+};
+
+// Extracting a scalar leaf prints the stored value itself, with no quoting and
+// no framing of any kind — probed against sops 3.13.0 and 3.13.3. Every byte of
+// stdout is therefore value, which makes exact equality the only sound
+// comparison: a trailing newline is a difference in the stored secret, not
+// output framing.
+//
+// Once equality has been ruled out, output that parses as JSON is output we
+// cannot read as this leaf's own value. It is a branch or list rather than a
+// scalar; or a typed leaf, which a stored string could equally have produced;
+// or a quoted rendering of exactly the value expected, which is either stray
+// quoting in storage or framing from some sops we have not probed. None of
+// those can be told apart from what was printed, and the wrong answer deletes a
+// credential, so all of them stay unverifiable.
+const isUnreadableOutput = (stdout: string, expectedValue: string): boolean => {
+  if (stdout === '') {
+    return true;
+  }
+  try {
+    const parsed: unknown = JSON.parse(stdout);
+    return typeof parsed !== 'string' || parsed === expectedValue;
+  } catch {
+    // Not JSON at all, which is the normal case: an opaque token value, or a
+    // hex access key ID that reads as a malformed number.
+    return false;
+  }
+};
+
+export const verifySopsStoredValueWith = (
+  runner: typeof runSops,
+  input: SopsStoredValueInput,
+): SopsStoredValueVerification => {
+  const { consumer, rel, dottedPath, expectedValue } = input;
+  const path = parseSopsKeyPath(dottedPath);
+  const problem = `could not verify stored SOPS value at ${dottedPath} in ${rel}`;
+  if (path === null || !isContainedSopsPath(consumer, rel, 'file')) {
+    return { ok: false, problem };
+  }
+  const extract = path
+    .map((segment) => `[${JSON.stringify(segment)}]`)
+    .join('');
+  const result = runner(
+    ['decrypt', '--extract', extract, '--output-type', 'json', rel],
+    consumer,
+  );
+  if (result.status !== 0) {
+    return { ok: false, problem };
+  }
+  // Equality is decided before anything is classified, so a secret whose own
+  // text happens to be valid JSON — an all-digit token — is proven by the bytes
+  // rather than second-guessed by their shape.
+  if (result.stdout === expectedValue) {
+    return { ok: true, matches: true };
+  }
+  return isUnreadableOutput(result.stdout, expectedValue)
+    ? { ok: false, problem }
+    : { ok: true, matches: false };
+};
+
+export const verifySopsStoredValue = (
+  consumer: string,
+  rel: string,
+  dottedPath: string,
+  expectedValue: string,
+): SopsStoredValueVerification =>
+  verifySopsStoredValueWith(runSops, {
+    consumer,
+    rel,
+    dottedPath,
+    expectedValue,
+  });

package/src/creds-sops.ts

@@ -15,7 +15,6 @@ import {
 import {
   inspectSopsStructure,
   isContainedSopsPath,
-  parseSopsKeyPath,
   type SopsShapeFailure,
 } from './creds-sops-structure';
 import { runSops } from './sops-exec';
@@ -36,15 +35,6 @@ export type SopsScalarDestinationResult = SopsScalarStructureResult | ReadError;
 export type SopsWriteResult =
   | { readonly ok: true }
   | { readonly ok: false; readonly problem: string };
-export type SopsStoredValueVerification =
-  | { readonly ok: true; readonly matches: boolean }
-  | { readonly ok: false; readonly problem: string };
-type SopsStoredValueInput = {
-  readonly consumer: string;
-  readonly rel: string;
-  readonly dottedPath: string;
-  readonly expectedValue: string;
-};
 
 export const listEncryptedKeys = (text: string): EncryptedKeysReadResult => {
   const result = inspectSopsStructure(text, true);
@@ -123,49 +113,6 @@ const editorCommand = (): string => {
   return `"${process.execPath}" "${editor}"`;
 };
 
-export const verifySopsStoredValueWith = (
-  runner: typeof runSops,
-  input: SopsStoredValueInput,
-): SopsStoredValueVerification => {
-  const { consumer, rel, dottedPath, expectedValue } = input;
-  const path = parseSopsKeyPath(dottedPath);
-  const problem = `could not verify stored SOPS value at ${dottedPath} in ${rel}`;
-  if (path === null || !isContainedSopsPath(consumer, rel, 'file')) {
-    return { ok: false, problem };
-  }
-  const extract = path
-    .map((segment) => `[${JSON.stringify(segment)}]`)
-    .join('');
-  const result = runner(
-    ['decrypt', '--extract', extract, '--output-type', 'json', rel],
-    consumer,
-  );
-  if (result.status !== 0) {
-    return { ok: false, problem };
-  }
-  try {
-    const stored: unknown = JSON.parse(result.stdout);
-    return typeof stored === 'string'
-      ? { ok: true, matches: stored === expectedValue }
-      : { ok: false, problem };
-  } catch {
-    return { ok: false, problem };
-  }
-};
-
-export const verifySopsStoredValue = (
-  consumer: string,
-  rel: string,
-  dottedPath: string,
-  expectedValue: string,
-): SopsStoredValueVerification =>
-  verifySopsStoredValueWith(runSops, {
-    consumer,
-    rel,
-    dottedPath,
-    expectedValue,
-  });
-
 export const setSopsValues = (
   consumer: string,
   rel: string,