@coffre/core 0.0.0 → 0.1.0

package/src/envelope.ts

@@ -0,0 +1,127 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import type { SecretContext } from './context.ts';
+import { encodeAad } from './context.ts';
+import type { KekRegistry } from './kek/registry.ts';
+import { DEK_BYTES } from './kek/types.ts';
+
+export * from './context.ts';
+
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+
+/**
+ * Current envelope format version. Stored on every row so the format can change
+ * without a bulk re-encryption.
+ */
+export const ENVELOPE_VERSION = 1;
+
+/**
+ * One sealed secret value, exactly as it is stored in `secret_versions`.
+ *
+ * The AAD binding is implemented here, in our own envelope layer, rather than
+ * via a provider "encryption context" feature. That keeps the stored format
+ * portable: moving to a different KMS changes only how `wrappedDek` is produced.
+ */
+export type Envelope = {
+  envelopeVersion: number;
+  kekProvider: string;
+  kekId: string;
+  kekVersion: string;
+  wrappedDek: Buffer;
+  iv: Buffer;
+  authTag: Buffer;
+  ciphertext: Buffer;
+};
+
+/** The part of an envelope the data key produces: everything but the wrapped key. */
+export type Sealed = Pick<Envelope, 'envelopeVersion' | 'iv' | 'authTag' | 'ciphertext'>;
+
+/** A fresh data key. One per version, so no key ever encrypts two values. */
+export function freshDek(): Buffer {
+  return randomBytes(DEK_BYTES);
+}
+
+/**
+ * Encrypt a secret value under `dek`, bound to `ctx`. Whoever holds the key
+ * encryption key wraps `dek` separately: the vault, in coffre.
+ */
+export function encrypt(plaintext: Buffer, ctx: SecretContext, dek: Buffer): Sealed {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv('aes-256-gcm', dek, iv);
+  cipher.setAAD(encodeAad(ctx));
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  return { envelopeVersion: ENVELOPE_VERSION, iv, authTag: cipher.getAuthTag(), ciphertext };
+}
+
+/**
+ * Decrypt with an unwrapped `dek`. Throws if the envelope was sealed for a
+ * different project, environment or secret than `ctx` describes, because
+ * the AAD will not match. This is the property that makes relocating a
+ * ciphertext across environments fail closed.
+ */
+export function decrypt(envelope: Sealed, ctx: SecretContext, dek: Buffer): Buffer {
+  if (envelope.envelopeVersion !== ENVELOPE_VERSION) {
+    throw new Error(`unsupported envelope version: ${envelope.envelopeVersion}`);
+  }
+  if (envelope.iv.length !== IV_BYTES) {
+    throw new Error('envelope IV has the wrong length');
+  }
+  if (envelope.authTag.length !== TAG_BYTES) {
+    throw new Error('envelope auth tag has the wrong length');
+  }
+  const decipher = createDecipheriv('aes-256-gcm', dek, envelope.iv);
+  decipher.setAAD(encodeAad(ctx));
+  decipher.setAuthTag(envelope.authTag);
+  return Buffer.concat([decipher.update(envelope.ciphertext), decipher.final()]);
+}
+
+/**
+ * Encrypt a secret value under a fresh DEK, and wrap that DEK under the
+ * registry's primary KEK: `encrypt` and the wrap in one, where both halves
+ * are in one place.
+ */
+export async function seal(
+  plaintext: Buffer,
+  ctx: SecretContext,
+  keks: KekRegistry,
+): Promise<Envelope> {
+  const dek = freshDek();
+  try {
+    const sealed = encrypt(plaintext, ctx, dek);
+    const wrapped = await keks.wrap(dek, ctx);
+    return {
+      ...sealed,
+      kekProvider: wrapped.kekProvider,
+      kekId: wrapped.kekId,
+      kekVersion: wrapped.kekVersion,
+      wrappedDek: wrapped.bytes,
+    };
+  } finally {
+    dek.fill(0);
+  }
+}
+
+/** Unwrap the envelope's DEK under the registry and decrypt: `decrypt` and the unwrap in one. */
+export async function open(
+  envelope: Envelope,
+  ctx: SecretContext,
+  keks: KekRegistry,
+): Promise<Buffer> {
+  if (envelope.envelopeVersion !== ENVELOPE_VERSION) {
+    throw new Error(`unsupported envelope version: ${envelope.envelopeVersion}`);
+  }
+  const dek = await keks.unwrap(
+    {
+      kekProvider: envelope.kekProvider,
+      kekId: envelope.kekId,
+      kekVersion: envelope.kekVersion,
+      bytes: envelope.wrappedDek,
+    },
+    ctx,
+  );
+  try {
+    return decrypt(envelope, ctx, dek);
+  } finally {
+    dek.fill(0);
+  }
+}

package/src/identity/auth.ts

@@ -0,0 +1,124 @@
+import { defineSignin, type SigninConfig } from './signin/config.ts';
+import type { SigninProvider } from './signin/types.ts';
+import type { AccessVerifierConfig } from './types.ts';
+
+/**
+ * Who vouches for the person at the other end of a request.
+ *
+ * - `signin`: coffre itself, after the person signs in with one of the
+ *   deployment's providers: GitHub, Google, Microsoft, any OIDC issuer, or
+ *   one of its own.
+ * - `cloudflare`: Cloudflare Access, in front of coffre.
+ *
+ * Either way, coffre decides who is a member, and issues its own sessions,
+ * CLI logins and service tokens.
+ */
+export type AuthConfig =
+  | {
+      mode: 'signin';
+      signin: SigninConfig;
+    }
+  | {
+      mode: 'cloudflare';
+      access: AccessVerifierConfig;
+    };
+
+/**
+ * What a deployment writes as `auth`: `signin(…)` or `cloudflareAccess(…)`.
+ * Each checks its own options when called; sign-in is finished against the
+ * deployment's public URL, which its callbacks are built from.
+ */
+export type Auth = {
+  resolve(publicUrl: string): AuthConfig;
+};
+
+function httpsOrigin(what: string, value: string): URL {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${what} must be an absolute URL`);
+  }
+  if (
+    url.protocol !== 'https:' ||
+    url.username !== '' ||
+    url.password !== '' ||
+    url.pathname !== '/' ||
+    url.search !== '' ||
+    url.hash !== ''
+  ) {
+    throw new Error(`${what} must be an HTTPS origin, with no path, query or credentials`);
+  }
+  return url;
+}
+
+function checkAudience(audience: string): string {
+  if (audience.length === 0 || audience.length > 64 || /\s/.test(audience)) {
+    throw new Error('the Access audience must be a non-whitespace Access AUD tag of at most 64 characters');
+  }
+  return audience;
+}
+
+/**
+ * Cloudflare Access in front of coffre: every request carries Access's
+ * signed assertion, checked against the team's keys and the application's
+ * AUD tag.
+ *
+ *   cloudflareAccess({ teamDomain: 'acme.cloudflareaccess.com', audience: env.ACCESS_AUD })
+ */
+export function cloudflareAccess(options: { teamDomain: string; audience: string }): Auth {
+  const domain = options.teamDomain.trim();
+  const issuerUrl = httpsOrigin('the Access team domain', domain.includes('://') ? domain : `https://${domain}`);
+  if (
+    issuerUrl.port !== '' ||
+    !issuerUrl.hostname.endsWith('.cloudflareaccess.com') ||
+    issuerUrl.hostname === 'cloudflareaccess.com'
+  ) {
+    throw new Error('the Access team domain must be <team>.cloudflareaccess.com');
+  }
+  const issuer = issuerUrl.origin;
+  const config: AuthConfig = {
+    mode: 'cloudflare',
+    access: {
+      issuer,
+      jwksUrl: `${issuer}/cdn-cgi/access/certs`,
+      audience: checkAudience(options.audience.trim()),
+    },
+  };
+  return { resolve: () => config };
+}
+
+export type SigninOptions = {
+  /** At least one: `github`, `google`, `microsoft`, `oidc`, or the deployment's own `SigninProvider`. */
+  providers: SigninProvider[];
+  /** Heading on the sign-in page, e.g. "Acme secrets". */
+  title?: string;
+  /** One line under it, e.g. "Use your acme.example Google account." */
+  note?: string;
+  /** Absolute lifetime of a browser session; 12 hours unless set, at most a week. */
+  browserSessionHours?: number;
+  /** Absolute lifetime of a CLI session; 30 days unless set, at most a year. */
+  cliSessionDays?: number;
+};
+
+/**
+ * coffre's own sign-in page, with these providers:
+ *
+ *   signin({ providers: [github({ clientId, clientSecret, organization: 'acme' })] })
+ */
+export function signin(options: SigninOptions): Auth {
+  // Checked now, where the deployment wrote it, and again with the URL.
+  defineSignin({ ...toSignin(options), publicUrl: 'https://coffre.invalid' });
+  return {
+    resolve: (publicUrl) => ({ mode: 'signin', signin: defineSignin({ ...toSignin(options), publicUrl }) }),
+  };
+}
+
+function toSignin(options: SigninOptions) {
+  return {
+    providers: options.providers,
+    page: { title: options.title, note: options.note },
+    browserSessionHours: options.browserSessionHours,
+    cliSessionDays: options.cliSessionDays,
+  };
+}

package/src/identity/index.ts

@@ -0,0 +1,6 @@
+// `@coffre/core/identity`: who is asking, and how coffre's sign-in finds out.
+export * from './auth.ts';
+export * from './signin/index.ts';
+export * from './tokens.ts';
+export * from './types.ts';
+export * from './verifier.ts';

package/src/identity/signin/config.ts

@@ -0,0 +1,301 @@
+/**
+ * Sign-in providers, and the sign-in they make up.
+ *
+ * coffre speaks two protocols: OpenID Connect, which covers Google, Microsoft,
+ * Okta, Auth0, Keycloak, Authentik, Clerk, WorkOS and nearly everyone else,
+ * and GitHub's own OAuth, because GitHub is the one provider people want that
+ * does not speak OIDC. Everything named here is a preset of one of those two:
+ * `google()` is OIDC with Google's issuer and a Workspace-domain check,
+ * `microsoft()` is OIDC with a tenant's issuer. A provider that is not listed
+ * needs no code, only `oidc()` and its issuer URL.
+ *
+ * A deployment writes them in its own code, where a misspelt option fails
+ * the typecheck:
+ *
+ *   signin({ providers: [github({ clientId, clientSecret: env.GITHUB_SECRET, organization: 'acme' })] })
+ *
+ * Each returns a `SigninProvider`, and a provider that speaks neither can be
+ * one of the deployment's own, in the same list.
+ */
+import { GitHubSigninProvider } from './github.ts';
+import { OidcSigninProvider } from './oidc.ts';
+import type { SigninBrand, SigninProvider } from './types.ts';
+
+type ProviderBase = {
+  id: string;
+  label: string;
+  brand: SigninBrand;
+  clientId: string;
+  clientSecret: string;
+};
+
+export type OidcProviderConfig = ProviderBase & {
+  /** Issuer identifier; discovery is fetched from `${issuer}/.well-known/openid-configuration`. */
+  issuer: string;
+  scopes: string[];
+  /** Extra authorization request parameters, such as Google's `hd` hint. */
+  authorizationParams: Record<string, string>;
+  /**
+   * The Google Workspace domain the ID token's `hd` claim must equal. The
+   * `hd` request parameter only filters Google's account picker; the claim is
+   * what proves membership.
+   */
+  hostedDomain: string | null;
+};
+
+export type GitHubProviderConfig = ProviderBase & {
+  /** https://github.com, or a GitHub Enterprise Server host. */
+  webUrl: string;
+  /** https://api.github.com, or `${host}/api/v3` on Enterprise Server. */
+  apiUrl: string;
+  /** When set, only active members of this organization may sign in. */
+  organization: string | null;
+};
+
+export type SigninPage = {
+  /** Heading on the sign-in page, e.g. "Acme secrets". */
+  title: string;
+  /** One line under it, e.g. "Use your acme.example Google account." */
+  note: string | null;
+};
+
+export type SigninConfig = {
+  /** The origin people reach coffre at. Callback URLs are built from it, never from the Host header. */
+  publicUrl: string;
+  providers: SigninProvider[];
+  page: SigninPage;
+  /** Absolute lifetime of a browser session. */
+  browserSessionHours: number;
+  /** Absolute lifetime of a CLI session. */
+  cliSessionDays: number;
+};
+
+const PROVIDER_ID = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const BRANDS: readonly SigninBrand[] = ['github', 'google', 'microsoft', 'oidc'];
+
+type Credentials = { clientId: string; clientSecret: string };
+
+function checkId(id: string): string {
+  if (typeof id !== 'string' || !PROVIDER_ID.test(id)) {
+    throw new Error(
+      `sign-in provider id "${id}" must be 1-32 lowercase letters, digits or dashes`,
+    );
+  }
+  return id;
+}
+
+function credentials(id: string, options: Credentials): Credentials {
+  if (!options.clientId || !options.clientSecret) {
+    throw new Error(`sign-in provider ${id} needs a client id and a client secret`);
+  }
+  return { clientId: options.clientId, clientSecret: options.clientSecret };
+}
+
+/**
+ * Any OpenID Connect provider, by issuer URL.
+ *
+ * Okta, Auth0, Keycloak, Authentik, Zitadel, Clerk, WorkOS, Dex and the like
+ * all live here; so does a broker, for providers that only speak SAML or LDAP.
+ */
+export function oidc(options: OidcOptions): OidcSigninProvider {
+  return new OidcSigninProvider(oidcConfig(options));
+}
+
+type OidcOptions = Credentials & {
+  id: string;
+  label: string;
+  issuer: string;
+  scopes?: string[];
+  authorizationParams?: Record<string, string>;
+};
+
+function oidcConfig(options: OidcOptions): OidcProviderConfig {
+  const id = checkId(options.id);
+  return {
+    id,
+    label: options.label,
+    brand: 'oidc',
+    ...credentials(id, options),
+    issuer: issuerUrl(options.issuer, `sign-in provider ${id}`),
+    scopes: options.scopes ?? ['openid', 'email', 'profile'],
+    authorizationParams: options.authorizationParams ?? {},
+    hostedDomain: null,
+  };
+}
+
+/** Google accounts; with `domain`, only that Google Workspace's accounts. */
+export function google(
+  options: Credentials & { id?: string; label?: string; domain?: string },
+): OidcSigninProvider {
+  const domain = options.domain?.trim().toLowerCase() || null;
+  return new OidcSigninProvider({
+    ...oidcConfig({
+      id: options.id ?? 'google',
+      label: options.label ?? 'Google',
+      issuer: 'https://accounts.google.com',
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+      // `select_account` stops Google from silently reusing whichever of
+      // several signed-in accounts was used last.
+      authorizationParams: domain
+        ? { hd: domain, prompt: 'select_account' }
+        : { prompt: 'select_account' },
+    }),
+    brand: 'google',
+    hostedDomain: domain,
+  });
+}
+
+const TENANT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Microsoft Entra ID, for one tenant.
+ *
+ * The tenant must be its GUID. Entra's multi-tenant endpoints (`common`,
+ * `organizations`) publish an issuer template rather than an issuer, which
+ * standard OIDC validation rejects, and "any work account in the world" is not
+ * an audience a secrets manager wants anyway.
+ *
+ * Entra email claims do not prove address ownership. Sign in through another
+ * provider and link the Microsoft account first; later sign-ins use its subject.
+ */
+export function microsoft(
+  options: Credentials & { id?: string; label?: string; tenant: string },
+): OidcSigninProvider {
+  const tenant = options.tenant.trim();
+  if (!TENANT_ID.test(tenant)) {
+    throw new Error(
+      'the Microsoft sign-in tenant must be the directory (tenant) ID, a GUID, not a domain or "common"',
+    );
+  }
+  return new OidcSigninProvider({
+    ...oidcConfig({
+      id: options.id ?? 'microsoft',
+      label: options.label ?? 'Microsoft',
+      issuer: `https://login.microsoftonline.com/${tenant.toLowerCase()}/v2.0`,
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+      authorizationParams: { prompt: 'select_account' },
+    }),
+    brand: 'microsoft',
+  });
+}
+
+/** GitHub accounts; with `organization`, only that organization's members. */
+export function github(
+  options: Credentials & {
+    id?: string;
+    label?: string;
+    organization?: string;
+    webUrl?: string;
+    apiUrl?: string;
+  },
+): GitHubSigninProvider {
+  const id = checkId(options.id ?? 'github');
+  return new GitHubSigninProvider({
+    id,
+    label: options.label ?? 'GitHub',
+    brand: 'github',
+    ...credentials(id, options),
+    webUrl: baseUrl(options.webUrl ?? 'https://github.com', `sign-in provider ${id} web URL`),
+    apiUrl: baseUrl(options.apiUrl ?? 'https://api.github.com', `sign-in provider ${id} API URL`),
+    organization: options.organization?.trim() || null,
+  });
+}
+
+function isLoopback(url: URL): boolean {
+  return url.hostname === '127.0.0.1' || url.hostname === 'localhost' || url.hostname === '[::1]';
+}
+
+/** HTTPS, except on loopback, where the dev IdP runs. */
+function checkedUrl(value: string, what: string): URL {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${what} must be an absolute URL`);
+  }
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopback(url))) {
+    throw new Error(`${what} must use HTTPS`);
+  }
+  if (url.username !== '' || url.password !== '' || url.search !== '' || url.hash !== '') {
+    throw new Error(`${what} must not carry credentials, a query or a fragment`);
+  }
+  return url;
+}
+
+/**
+ * Issuers are compared byte for byte with the `iss` of every token, so the
+ * configured value is kept as written, less a trailing slash nobody means.
+ */
+function issuerUrl(value: string, what: string): string {
+  checkedUrl(value, `${what} issuer`);
+  return value.endsWith('/') ? value.slice(0, -1) : value;
+}
+
+function baseUrl(value: string, what: string): string {
+  const url = checkedUrl(value, what);
+  return url.href.endsWith('/') ? url.href.slice(0, -1) : url.href;
+}
+
+export function publicOrigin(value: string): string {
+  const url = checkedUrl(value, 'the public URL');
+  if (url.pathname !== '/') {
+    throw new Error('the public URL must be an origin, with no path');
+  }
+  return url.origin;
+}
+
+/** Sign-in configuration, checked: at least one provider, each whole, ids unique, lifetimes sane. */
+export function defineSignin(options: {
+  publicUrl: string;
+  providers: SigninProvider[];
+  page?: { title?: string; note?: string };
+  browserSessionHours?: number;
+  cliSessionDays?: number;
+}): SigninConfig {
+  if (options.providers.length === 0) {
+    throw new Error('sign-in needs at least one provider');
+  }
+  const seen = new Set<string>();
+  for (const provider of options.providers) {
+    checkProvider(provider);
+    if (seen.has(provider.id)) throw new Error(`sign-in provider id "${provider.id}" is used twice`);
+    seen.add(provider.id);
+  }
+  return {
+    publicUrl: publicOrigin(options.publicUrl),
+    providers: options.providers,
+    page: {
+      title: options.page?.title ?? 'Sign in to coffre',
+      note: options.page?.note ?? null,
+    },
+    browserSessionHours: lifetime(options.browserSessionHours, 'browserSessionHours', 12, 24 * 7),
+    cliSessionDays: lifetime(options.cliSessionDays, 'cliSessionDays', 30, 365),
+  };
+}
+
+/** A deployment's own provider is checked like coffre's: it is only typed, not trusted. */
+function checkProvider(provider: SigninProvider): void {
+  checkId(provider?.id);
+  if (typeof provider.issuer !== 'string' || provider.issuer.trim() === '') {
+    throw new Error(`sign-in provider ${provider.id} needs a stable issuer`);
+  }
+  if (typeof provider.label !== 'string' || provider.label.trim() === '') {
+    throw new Error(`sign-in provider ${provider.id} needs a label`);
+  }
+  if (!BRANDS.includes(provider.brand)) {
+    throw new Error(`sign-in provider ${provider.id}'s brand must be one of ${BRANDS.join(', ')}`);
+  }
+  if (typeof provider.start !== 'function' || typeof provider.finish !== 'function') {
+    throw new Error(`sign-in provider ${provider.id} needs start() and finish()`);
+  }
+}
+
+function lifetime(value: number | undefined, name: string, fallback: number, max: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isFinite(value) || value <= 0 || value > max) {
+    throw new Error(`${name} must be a number above 0 and at most ${max}`);
+  }
+  return value;
+}