@coffre/client 0.0.0 → 0.1.1

package/src/index.ts

@@ -0,0 +1,307 @@
+/**
+ * The coffre API as function calls, typed from the server's route table
+ * (`api.ts`, generated from it).
+ *
+ *   const coffre = createClient({ url: 'https://coffre.acme.example' });
+ *   await coffre.secrets.set('market/prod', { DATABASE_URL: '…', OLD_KEY: null });
+ *
+ * Every call is one `fetch`. Pass a `transport` to send requests somewhere
+ * else: the web app hands requests straight to its router, and the CLI adds
+ * its own handling of Cloudflare Access redirects.
+ */
+import type { Api, AuthInfo, DryRunOutcome, DryRunResult, SetResult } from './api.ts';
+
+export type {
+  AccessValue,
+  Api,
+  AuditEntryView,
+  AuthInfo,
+  DryRunOutcome,
+  DryRunResult,
+  IdentityRow,
+  Json,
+  Me,
+  Member,
+  OffboardingReport,
+  ProjectSummary,
+  RemovedMember,
+  RunOutcome,
+  SecretKey,
+  SecretVersion,
+  ServiceTokenRow,
+  SessionRow,
+  SetResult,
+  SyncField,
+  SyncProviderInfo,
+  SyncView,
+} from './api.ts';
+export { configFromArguments, configFromForm, firstMissing, initialValues, isAsked } from './sync-fields.ts';
+export type { FormValues } from './sync-fields.ts';
+
+export type RouteKey = keyof Api;
+/** What a caller sends: the body, or the query string for a GET. */
+export type RouteInput<K extends RouteKey> = Api[K]['input'];
+/** What comes back, as JSON. */
+export type RouteOutput<K extends RouteKey> = Api[K]['output'];
+
+type ParamNames<Pattern> = Pattern extends `${string}:${infer Name}/${infer Rest}`
+  ? Name | ParamNames<`/${Rest}`>
+  : Pattern extends `${string}:${infer Name}`
+    ? Name
+    : never;
+
+/** `GET /members/:member` takes `{ member }`. */
+export type Params<Key> = { [Name in ParamNames<Key>]: string };
+
+export type Transport = (request: Request) => Promise<Response>;
+
+export type ClientOptions = {
+  /** The instance's origin, e.g. `https://coffre.acme.example`. */
+  url: string;
+  /** Sent with every request: a bearer token, a Cloudflare Access header. */
+  headers?: () => HeadersInit | Promise<HeadersInit>;
+  transport?: Transport;
+};
+
+/** The API's error shape, `{ error, message }`, with the HTTP status. */
+const COFFRE_ERROR = Symbol.for('@coffre/client:CoffreError');
+
+export class CoffreError extends Error {
+  /**
+   * `@coffre/ui`'s prebuilt pages bundle a copy of this class, and a page is
+   * handed a client the server made with this package's. So `instanceof`
+   * asks for the mark every copy leaves, rather than for this copy's prototype.
+   */
+  static [Symbol.hasInstance](value: unknown): boolean {
+    return typeof value === 'object' && value !== null && COFFRE_ERROR in value;
+  }
+
+  readonly [COFFRE_ERROR] = true;
+  readonly status: number;
+  readonly code: string;
+  /** The vault's own code when it refused: `no_grant`, `removed`, `bulk_limit`, ... */
+  readonly reason: string | undefined;
+
+  constructor(status: number, code: string, message: string, reason?: string) {
+    super(message);
+    this.name = 'CoffreError';
+    this.status = status;
+    this.code = code;
+    this.reason = reason;
+  }
+}
+
+type Args<K extends RouteKey> =
+  RouteInput<K> extends undefined
+    ? [params: Params<K>, input?: undefined]
+    : Partial<RouteInput<K>> extends RouteInput<K>
+      ? [params: Params<K>, input?: RouteInput<K>]
+      : [params: Params<K>, input: RouteInput<K>];
+
+/** `market/prod/KEY` as route parameters. */
+function place(path: string): { project: string; environment: string; key: string } {
+  const [project = '', environment = '', key = ''] = path.replace(/^\/+|\/+$/g, '').split('/');
+  return { project, environment, key };
+}
+
+export function createClient(options: ClientOptions) {
+  const origin = options.url.replace(/\/+$/, '');
+  const transport = options.transport ?? ((request: Request) => fetch(request));
+
+  async function send(method: string, path: string, input: unknown): Promise<unknown> {
+    const url = new URL(`${origin}/api${path}`);
+    const headers = new Headers(await options.headers?.());
+    let body: string | undefined;
+    if (method === 'GET') {
+      for (const [name, value] of Object.entries(input ?? {})) {
+        if (value !== undefined && value !== null) url.searchParams.set(name, String(value));
+      }
+    } else if (input !== undefined) {
+      headers.set('content-type', 'application/json');
+      body = JSON.stringify(input);
+    }
+
+    const response = await transport(new Request(url, { method, headers, body }));
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+      const error = payload as { error?: unknown; message?: unknown; reason?: unknown } | null;
+      throw new CoffreError(
+        response.status,
+        typeof error?.error === 'string' ? error.error : 'http_error',
+        typeof error?.message === 'string' ? error.message : `request failed with status ${response.status}`,
+        typeof error?.reason === 'string' ? error.reason : undefined,
+      );
+    }
+    return payload;
+  }
+
+  /** A route key and its parameters as a method and a path. */
+  function address<K extends RouteKey>(key: K, params: Params<K>): [method: string, path: string] {
+    const [method, pattern] = key.split(' ') as [string, string];
+    const path = pattern.replace(/:(\w+)/g, (_, name: string) =>
+      encodeURIComponent((params as Record<string, string>)[name]),
+    );
+    return [method, path];
+  }
+
+  /** Any route by its key: `call('GET /secrets/:project/:environment', { project, environment })`. */
+  async function call<K extends RouteKey>(key: K, ...[params, input]: Args<K>): Promise<RouteOutput<K>> {
+    const [method, path] = address(key, params);
+    return (await send(method, path, input)) as RouteOutput<K>;
+  }
+
+  return {
+    call,
+
+    /** How this instance signs people in. Answers anyone, signed in or not. */
+    auth: () => send('GET', '/auth', undefined) as Promise<AuthInfo>,
+
+    /** Who I am, and every place I can reach. */
+    me: () => call('GET /me', {}),
+
+    projects: {
+      /** With their environments. */
+      list: () => call('GET /projects', {}),
+      create: (project: string, input: RouteInput<'PUT /projects/:project'>) =>
+        call('PUT /projects/:project', { project }, input),
+      update: (project: string, patch: RouteInput<'PATCH /projects/:project'>) =>
+        call('PATCH /projects/:project', { project }, patch),
+    },
+
+    environments: {
+      create: (path: string, input: RouteInput<'PUT /projects/:project/:environment'>) =>
+        call('PUT /projects/:project/:environment', place(path), input),
+      update: (path: string, patch: RouteInput<'PATCH /projects/:project/:environment'>) =>
+        call('PATCH /projects/:project/:environment', place(path), patch),
+    },
+
+    secrets: {
+      /** Keys, versions and who changed what; never values. */
+      list: (path: string) => call('GET /secrets/:project/:environment', place(path)),
+      /** Decrypts one secret, or every secret in an environment. Logged in your name. */
+      reveal: (path: string) => call('POST /reveals', {}, { path }),
+      /** One transaction, a version and an audit entry per key; `null` archives. */
+      set: (path: string, values: RouteInput<'PATCH /secrets/:project/:environment'>) =>
+        call('PATCH /secrets/:project/:environment', place(path), values) as Promise<SetResult>,
+      /**
+       * What `set` would do to each key, `added`, `changed`, `unchanged` or
+       * `archived`, and nothing else: no value comes back and nothing is
+       * written. Comparing opens the current values, logged as reads.
+       */
+      dryRun: (path: string, values: RouteInput<'PATCH /secrets/:project/:environment'>) => {
+        const [method, route] = address('PATCH /secrets/:project/:environment', place(path));
+        return send(method, `${route}?dryRun=1`, values) as Promise<DryRunResult>;
+      },
+      history: (path: string) => call('GET /secrets/:project/:environment/:key/versions', place(path)),
+      /** A new version holding the old one's value. */
+      restore: (path: string, version: number) =>
+        call('POST /secrets/:project/:environment/:key/restore', place(path), { version }),
+      rename: (path: string, key: string) =>
+        call('PATCH /secrets/:project/:environment/:key', place(path), { key }),
+      update: (path: string, patch: RouteInput<'PATCH /secrets/:project/:environment/:key'>) =>
+        call('PATCH /secrets/:project/:environment/:key', place(path), patch),
+    },
+
+    members: {
+      /** People and tokens, their role and their access; at a place, those who reach it. */
+      list: (path?: string) => call('GET /members', {}, { path }),
+      /** What they hold, and what to rotate if they leave. */
+      get: (member: string) => call('GET /members/:member', { member }),
+      add: (member: string, input: RouteInput<'PUT /members/:member'> = {}) =>
+        call('PUT /members/:member', { member }, input),
+      /** Offboards; returns what to rotate. */
+      remove: (member: string) => call('DELETE /members/:member', { member }),
+    },
+
+    tokens: {
+      list: (member: string) => call('GET /members/:member/tokens', { member }),
+      /** The value is in the answer, and only there. */
+      issue: (member: string, input: RouteInput<'POST /members/:member/tokens'>) =>
+        call('POST /members/:member/tokens', { member }, input),
+      revoke: (member: string, id: string) => call('DELETE /members/:member/tokens/:id', { member, id }),
+    },
+
+    access: {
+      /** What they should hold at each place; the server applies the difference. `null` revokes. */
+      set: (member: string, access: RouteInput<'PATCH /access/:member'>) =>
+        call('PATCH /access/:member', { member }, access),
+    },
+
+    /** Where I am signed in. Only where coffre runs its own sign-in. */
+    sessions: {
+      list: () => call('GET /sessions', {}),
+      revoke: (id: string) => call('DELETE /sessions/:id', { id }),
+    },
+
+    /** The accounts I sign in with. */
+    identities: {
+      list: () => call('GET /identities', {}),
+      unlink: (id: string) => call('DELETE /identities/:id', { id }),
+    },
+
+    /** A `coffre login` waiting for someone to approve it, by the code it shows. */
+    deviceLogins: {
+      get: (code: string) => call('GET /device-logins/:code', { code }),
+      decide: (code: string, approve: boolean) => call('POST /device-logins/:code', { code }, { approve }),
+    },
+
+    syncs: {
+      /** Where a sync can push on this instance, and what each asks for. */
+      providers: () => call('GET /syncs/providers', {}),
+      list: (path: string) => call('GET /syncs/:project/:environment', place(path)),
+      add: (path: string, input: RouteInput<'POST /syncs/:project/:environment'>) =>
+        call('POST /syncs/:project/:environment', place(path), input),
+      update: (id: string, patch: RouteInput<'PATCH /syncs/by-id/:id'>) =>
+        call('PATCH /syncs/by-id/:id', { id }, patch),
+      remove: (id: string) => call('DELETE /syncs/by-id/:id', { id }),
+      run: (id: string) => call('POST /syncs/by-id/:id/runs', { id }),
+    },
+
+    audit: {
+      list: (query: RouteInput<'GET /audit'> = {}) => call('GET /audit', {}, query),
+      verify: () => call('GET /audit/verification', {}),
+    },
+  };
+}
+
+export type CoffreClient = ReturnType<typeof createClient>;
+
+export type ImportAction = Exclude<DryRunOutcome, 'archived'>;
+
+/**
+ * What writing these entries (a parsed `.env` file) would do, from a dry run
+ * of the write: the server compares, so no value leaves it, and the values it
+ * opens to compare are logged as reads. `changes` is what to pass to
+ * `secrets.set`: the keys that differ, so an unchanged value does not become
+ * a new version.
+ */
+export async function planImport(
+  coffre: CoffreClient,
+  path: string,
+  entries: readonly { key: string; value: string }[],
+): Promise<{
+  plan: { key: string; action: ImportAction; version: number | null }[];
+  changes: Record<string, string>;
+}> {
+  // Null-prototype records: a key named __proto__ is a key like any other.
+  const values: Record<string, string> = Object.create(null);
+  for (const { key, value } of entries) values[key] = value;
+  // Settle both before throwing, so a refusal leaves no call still in flight.
+  const [listed, compared] = await Promise.allSettled([
+    coffre.secrets.list(path),
+    coffre.secrets.dryRun(path, { ...values }),
+  ]);
+  if (listed.status === 'rejected') throw listed.reason;
+  if (compared.status === 'rejected') throw compared.reason;
+  const [{ keys }, dryRun] = [listed.value, compared.value];
+  const versions = new Map(keys.map((entry) => [entry.key, entry.version]));
+  const plan: { key: string; action: ImportAction; version: number | null }[] = [];
+  const changes: Record<string, string> = Object.create(null);
+  for (const [key, value] of Object.entries(values)) {
+    // A patch without nulls archives nothing, so every outcome is one of these.
+    const action = dryRun.keys[key] as ImportAction;
+    plan.push({ key, action, version: versions.get(key) ?? null });
+    if (action !== 'unchanged') changes[key] = value;
+  }
+  return { plan, changes: { ...changes } };
+}

package/src/sync-fields.ts

@@ -0,0 +1,85 @@
+/**
+ * A sync provider's form, as the web page and `coffre sync add` fill it in.
+ *
+ * Each provider describes its fields (`GET /syncs/providers`); the server's
+ * parser validates every one of them (formats, lengths, combinations) and
+ * says what is wrong in a sentence. This only turns what someone typed into
+ * the JSON that parser expects.
+ */
+import type { SyncField, SyncProviderInfo } from './api.ts';
+
+export type FormValues = Record<string, string | string[]>;
+
+export function initialValues(provider: SyncProviderInfo): FormValues {
+  return Object.fromEntries(
+    provider.fields.map((field) => [field.name, field.type === 'text' ? '' : field.initial]),
+  );
+}
+
+/** Whether the rest of the form makes the field meaningful. */
+export function isAsked(field: SyncField, values: FormValues): boolean {
+  if (field.type === 'options' || field.when === undefined) return true;
+  const picked = values[field.when.field];
+  const list = Array.isArray(picked) ? picked : [];
+  return list.length === field.when.is.length && field.when.is.every((value) => list.includes(value));
+}
+
+/** The label of the first required field left empty, or null when the form can be sent. */
+export function firstMissing(provider: SyncProviderInfo, values: FormValues): string | null {
+  for (const field of provider.fields) {
+    if (!isAsked(field, values)) continue;
+    const value = values[field.name];
+    const empty = typeof value === 'string' ? value.trim() === '' : (value ?? []).length === 0;
+    if (empty && (field.type === 'options' || field.optional !== true)) return field.label;
+  }
+  return null;
+}
+
+/**
+ * The provider's config. Text is trimmed, and an optional field left empty
+ * is left out rather than sent as "", which the server rightly refuses.
+ */
+export function configFromForm(provider: SyncProviderInfo, values: FormValues): Record<string, unknown> {
+  const config: Record<string, unknown> = {};
+  for (const field of provider.fields) {
+    if (!isAsked(field, values)) continue;
+    const value = values[field.name];
+    if (field.type === 'options') {
+      const picked = Array.isArray(value) ? value : [];
+      config[field.name] = field.multiple ? picked : picked[0];
+    } else {
+      const text = typeof value === 'string' ? value.trim() : '';
+      if (text !== '') config[field.name] = text;
+    }
+  }
+  return config;
+}
+
+/**
+ * The config from `name=value` arguments, as the CLI takes them. A field with
+ * several options takes them comma-separated, and one left out gets what the
+ * form preselects. Text goes as typed, for the server to check.
+ */
+export function configFromArguments(provider: SyncProviderInfo, assignments: readonly string[]): Record<string, unknown> {
+  const config: Record<string, unknown> = {};
+  for (const assignment of assignments) {
+    const equals = assignment.indexOf('=');
+    const name = equals === -1 ? assignment : assignment.slice(0, equals);
+    const field = provider.fields.find((candidate) => candidate.name === name);
+    if (equals === -1 || field === undefined) {
+      const names = provider.fields.map((candidate) => candidate.name).join(', ');
+      throw new Error(`${provider.label} takes ${names} as name=value; got ${JSON.stringify(assignment)}`);
+    }
+    if (Object.hasOwn(config, name)) throw new Error(`${name} is given twice`);
+    const value = assignment.slice(equals + 1);
+    if (field.type === 'text') config[name] = value;
+    else if (field.multiple) config[name] = value.split(',').map((item) => item.trim()).filter((item) => item !== '');
+    else config[name] = value;
+  }
+  for (const field of provider.fields) {
+    if (field.type === 'options' && !Object.hasOwn(config, field.name)) {
+      config[field.name] = field.multiple ? field.initial : field.initial[0];
+    }
+  }
+  return config;
+}