@coffre/core 0.0.0 → 0.1.0

package/dist/identity.d.ts

@@ -0,0 +1,433 @@
+import { JWTPayload } from "jose";
+//#region src/identity/signin/types.d.ts
+/**
+ * What a provider reports about the person who just signed in.
+ *
+ * `subject` is the provider's permanent id for the account: OIDC's `sub`,
+ * GitHub's numeric user id. coffre binds to it and to nothing else, since a
+ * login name can be renamed and an email address can be handed to someone new.
+ */
+export type SigninProfile = {
+  subject: string;
+  /** Verified addresses only, lowercased, the provider's primary first. */
+  emails: string[];
+  name: string | null;
+};
+/**
+ * What must survive the round trip through the provider: the anti-CSRF
+ * state, the PKCE verifier and, for OIDC, the nonce. coffre keeps it in an
+ * encrypted, short-lived cookie rather than in the database, so an
+ * unauthenticated visitor cannot make coffre write anything.
+ */
+export type PendingSignin = {
+  state: string;
+  codeVerifier: string;
+  nonce: string | null;
+};
+export type SigninErrorCode =
+/** The person cancelled, or the provider refused them. */
+'provider_denied' |
+/** The callback does not belong to the sign-in this browser started. */
+'state_mismatch' |
+/** The provider answered, but not in a way that can be trusted. */
+'invalid_response' |
+/** The provider could not be reached. */
+'provider_unavailable' |
+/** The account has no verified email address to match an invitation with. */
+'no_verified_email' |
+/** A Google account outside the configured Workspace domain. */
+'wrong_domain' |
+/** A GitHub account outside the configured organization. */
+'not_in_organization';
+export declare class SigninError extends Error {
+  readonly code: SigninErrorCode;
+  constructor(code: SigninErrorCode, message: string);
+}
+export type ProviderOptions = {
+  /** Injected by tests; defaults to globalThis.fetch. */
+  fetch?: typeof fetch;
+};
+/** Which mark the sign-in button carries: GitHub's, Google's, Microsoft's, or a plain key. */
+export type SigninBrand = 'github' | 'google' | 'microsoft' | 'oidc';
+/**
+ * A way to sign in: send the browser to whoever knows the person, and take
+ * back who they are. `github()`, `google()`, `microsoft()` and `oidc()` make
+ * one; so can a deployment, for a provider that is none of those. coffre
+ * does everything around it: the pending state, sealed in a cookie between
+ * the two calls, binding the profile to a member, sessions, CLI logins and
+ * service tokens.
+ *
+ *   const acme: SigninProvider = {
+ *     id: 'acme',
+ *     issuer: 'https://sso.acme.example',
+ *     label: 'Acme SSO',
+ *     brand: 'oidc',
+ *     async start(redirectUri) { … return { url, pending: { state, codeVerifier, nonce: null } }; },
+ *     async finish(callbackUrl, redirectUri, pending) { … return { subject, emails, name }; },
+ *   };
+ */
+export interface SigninProvider {
+  /** Stable: part of the callback URL, `/auth/callback/{id}`, and of every account bound through it. */
+  readonly id: string;
+  /** The authority whose subjects these are; changing it requires linking accounts again. */
+  readonly issuer: string;
+  /** Button text: "Continue with {label}". */
+  readonly label: string;
+  readonly brand: SigninBrand;
+  /** Where to send the browser, and what to remember until it comes back. */
+  start(redirectUri: string, options?: {
+    loginHint?: string;
+  }): Promise<{
+    url: URL;
+    pending: PendingSignin;
+  }>;
+  /**
+   * The person back from the provider, verified: check the callback against
+   * `pending`, and throw a SigninError for anything that does not hold.
+   */
+  finish(callbackUrl: URL, redirectUri: string, pending: PendingSignin): Promise<SigninProfile>;
+}
+//#endregion
+//#region src/identity/signin/github.d.ts
+/**
+ * GitHub's OAuth web flow, which is OAuth 2.0 without OpenID Connect: no ID
+ * token, so the profile comes from the REST API with the access token the
+ * code is exchanged for. That token is used for these two or three calls and
+ * then dropped; coffre never stores it.
+ *
+ * Works with an OAuth App or a GitHub App's user authorization, on github.com
+ * or GitHub Enterprise Server.
+ */
+export declare class GitHubSigninProvider implements SigninProvider {
+  #private;
+  readonly id: string;
+  readonly issuer: string;
+  readonly label: string;
+  readonly brand: SigninBrand;
+  /** What it was made from, as checked. */
+  readonly config: GitHubProviderConfig;
+  constructor(config: GitHubProviderConfig, options?: ProviderOptions);
+  start(redirectUri: string, options?: {
+    loginHint?: string;
+  }): Promise<{
+    url: URL;
+    pending: PendingSignin;
+  }>;
+  finish(callbackUrl: URL, redirectUri: string, pending: PendingSignin): Promise<SigninProfile>;
+}
+//#endregion
+//#region src/identity/signin/oidc.d.ts
+/**
+ * The authorization code flow with PKCE, against any OpenID Connect issuer.
+ *
+ * Protocol work is delegated to oauth4webapi: discovery with issuer
+ * validation, the RFC 9207 `iss` check on the callback, the token request and
+ * ID token claim validation (issuer, audience, expiry, nonce). The ID token is
+ * received straight from the token endpoint over TLS with client
+ * authentication, which OpenID Connect Core 3.1.3.7 accepts in place of
+ * checking its signature.
+ */
+export declare class OidcSigninProvider implements SigninProvider {
+  #private;
+  readonly id: string;
+  readonly issuer: string;
+  readonly label: string;
+  readonly brand: SigninBrand;
+  /** What it was made from, as checked. */
+  readonly config: OidcProviderConfig;
+  constructor(config: OidcProviderConfig, options?: ProviderOptions);
+  start(redirectUri: string, options?: {
+    loginHint?: string;
+  }): Promise<{
+    url: URL;
+    pending: PendingSignin;
+  }>;
+  finish(callbackUrl: URL, redirectUri: string, pending: PendingSignin): Promise<SigninProfile>;
+}
+//#endregion
+//#region src/identity/signin/config.d.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;
+};
+type Credentials = {
+  clientId: string;
+  clientSecret: string;
+};
+/**
+ * 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 declare function oidc(options: OidcOptions): OidcSigninProvider;
+type OidcOptions = Credentials & {
+  id: string;
+  label: string;
+  issuer: string;
+  scopes?: string[];
+  authorizationParams?: Record<string, string>;
+};
+/** Google accounts; with `domain`, only that Google Workspace's accounts. */
+export declare function google(options: Credentials & {
+  id?: string;
+  label?: string;
+  domain?: string;
+}): OidcSigninProvider;
+/**
+ * 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 declare function microsoft(options: Credentials & {
+  id?: string;
+  label?: string;
+  tenant: string;
+}): OidcSigninProvider;
+/** GitHub accounts; with `organization`, only that organization's members. */
+export declare function github(options: Credentials & {
+  id?: string;
+  label?: string;
+  organization?: string;
+  webUrl?: string;
+  apiUrl?: string;
+}): GitHubSigninProvider;
+export declare function publicOrigin(value: string): string;
+/** Sign-in configuration, checked: at least one provider, each whole, ids unique, lifetimes sane. */
+export declare function defineSignin(options: {
+  publicUrl: string;
+  providers: SigninProvider[];
+  page?: {
+    title?: string;
+    note?: string;
+  };
+  browserSessionHours?: number;
+  cliSessionDays?: number;
+}): SigninConfig;
+//#endregion
+//#region src/identity/types.d.ts
+/**
+ * An authenticated caller.
+ *
+ * Modelled as a tagged union rather than "a user with an optional email",
+ * because Cloudflare Access issues two structurally different tokens:
+ *
+ *   identity token  -> sub = user uuid, email = "admin@acme.example"
+ *   service token   -> sub = ""       , common_name = "<client-id>.access", NO email
+ *
+ * Machine callers (external-secrets, CI) are most of the real traffic, so the
+ * shape that cannot represent them is the wrong shape.
+ */
+export type Principal = {
+  type: 'user';
+  /** Stable identifier used in grants and in the audit log. */
+  id: string;
+  email: string;
+  subject: string;
+} | {
+  type: 'service';
+  /** Stable identifier used in grants and in the audit log. */
+  id: string;
+  commonName: string;
+};
+/**
+ * Verifies a bearer token and returns the caller it identifies.
+ *
+ * Cloudflare mode verifies Access JWTs against the team domain; signin mode
+ * looks up coffre's own credentials.
+ */
+export interface IdentityVerifier {
+  verify(token: string, request?: {
+    sourceIp: string | null;
+  }): Promise<Principal>;
+}
+/** Access delivers the JWT to the origin in this header. */
+export declare const ACCESS_JWT_HEADER = "cf-access-jwt-assertion";
+/** Where Access JWTs are checked: the team's keys, and the application's AUD tag. */
+export type AccessVerifierConfig = {
+  /** Cloudflare Access team domain, e.g. https://acme.cloudflareaccess.com */
+  issuer: string;
+  /** Usually `${issuer}/cdn-cgi/access/certs`. */
+  jwksUrl: string;
+  /** The AUD tag of the specific Access application. */
+  audience: string;
+  /** Seconds of clock skew tolerated. Kept at 0 by default deliberately. */
+  clockToleranceSeconds?: number;
+};
+//#endregion
+//#region src/identity/auth.d.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;
+};
+/**
+ * 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 declare function cloudflareAccess(options: {
+  teamDomain: string;
+  audience: string;
+}): Auth;
+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 declare function signin(options: SigninOptions): Auth;
+//#endregion
+//#region src/identity/signin/sealed.d.ts
+/**
+ * Derive a purpose-bound key from one of coffre's existing 32-byte secrets.
+ *
+ * HKDF with a distinct `info` string gives a key that is independent of the
+ * source for every practical purpose, so the sign-in cookie needs no new
+ * secret to provision and a leak of one derived key says nothing about the
+ * others.
+ */
+export declare function deriveKey(secret: Uint8Array, purpose: string): Buffer;
+/**
+ * Encrypt a small JSON value for a round trip through the browser.
+ *
+ * AES-256-GCM authenticates as well as hides, so a tampered or forged value
+ * fails to open rather than decoding into something else. The expiry sits
+ * inside the ciphertext, which keeps an old cookie from being replayed past
+ * it even by a client that ignores Max-Age.
+ */
+export declare function seal(key: Uint8Array, value: unknown, ttlSeconds: number, now?: number): string;
+/** The sealed value, or null when it is malformed, forged, tampered with or expired. */
+export declare function unseal<T>(key: Uint8Array, sealed: string | undefined | null, now?: number): T | null;
+//#endregion
+//#region src/identity/tokens.d.ts
+/**
+ * Bearer credentials coffre issues itself: browser sessions, CLI sessions and
+ * service tokens.
+ *
+ * A token is a kind prefix and 32 random bytes, e.g.
+ * `coffre_cli_Qm9Y...`. The prefix tells a person (or a secret scanner) what a
+ * leaked string is; the database stores only its SHA-256, which is enough
+ * for lookups and useless to anyone who reads the table. A plain hash is the
+ * right tool here, unlike for passwords: 256 bits of randomness leave nothing
+ * to brute-force.
+ */
+export type CredentialKind = 'browser' | 'cli' | 'service';
+export declare function generateToken(kind: CredentialKind): string;
+/** Whether a string has the shape of a coffre token, before any lookup. */
+export declare function isCoffreToken(value: string): boolean;
+export declare function hashToken(token: string): Buffer;
+/**
+ * Enough of a token to recognize it in a list, never enough to use it: the
+ * kind prefix and the last four characters. The prefix is matched rather than
+ * cut at the last underscore, because base64url uses `_` too.
+ */
+export declare function tokenHint(token: string): string;
+//#endregion
+//#region src/identity/verifier.d.ts
+type AccessClaims = JWTPayload & {
+  email?: unknown;
+  common_name?: unknown;
+};
+/**
+ * Verifies Cloudflare Access JWTs.
+ *
+ * Signature and claim verification for the TanStack request boundary. The
+ * boundary also rejects `x-middleware-subrequest` before calling this verifier.
+ */
+export declare class AccessIdentityVerifier implements IdentityVerifier {
+  #private;
+  constructor(config: AccessVerifierConfig);
+  verify(token: string): Promise<Principal>;
+}
+/**
+ * Derive the caller from verified claims.
+ *
+ * Order matters. A service token is identified by `common_name` and carries an
+ * empty `sub`; an identity token carries both `sub` and `email`. Anything else
+ * is rejected rather than being allowed through as an authenticated caller
+ * with no name -- an audit row with a null actor answers no question worth
+ * asking.
+ */
+export declare function toPrincipal(claims: AccessClaims): Principal;
+//#endregion