@coffre/core 0.1.15 → 0.1.17

package/dist/identity.d.ts

@@ -1,4 +1,5 @@
-import { JWTPayload } from "jose";
+import { BindingClaims, BindingInvalid, BindingPolicy, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, REQUIRED_CLAIMS, WORKLOAD_PROFILES, WorkloadProfile, canonicalClaims, checkBinding, checkFetchUrl, defaultIssuer, fullRef, githubReusable, githubWorkflow, gitlabProject, workflowRef } from "./workloads.js";
+import { JSONWebKeySet, JWTPayload } from "jose";
 //#region src/identity/signin/types.d.ts
 /**
  * What a provider reports about the person who just signed in.
@@ -189,6 +190,46 @@ export type SigninConfig = {
   browserSessionHours: number;
   /** Absolute lifetime of a CLI session. */
   cliSessionDays: number;
+  /** CI runs signing in as services with their platform's ID token, when on (`workloads.ts`). */
+  workloads: WorkloadsConfig | null;
+};
+/**
+ * Workload identity: CI runs that sign in as a service with the ID token
+ * their platform signs for them, through the trust bindings an owner sets
+ * on the service (docs/design/oidc.md). Off unless the deployment turns it on.
+ */
+export type WorkloadsOptions = {
+  /**
+   * The two limits every exchange passes before coffre does any work for
+   * it: one per source address, and one for all sources together. On
+   * Workers, two rate-limiting bindings (`env.WORKLOADS_PER_SOURCE`,
+   * `env.WORKLOADS_TOTAL`), which Cloudflare counts per location; on Node,
+   * `processLimits()` from `@coffre/server/node`, which counts per process.
+   * Required: an exchange is never without them.
+   */
+  limits: WorkloadLimits;
+  /**
+   * Lets a binding's issuer be plain HTTP on loopback, as the dev IdP's is:
+   * for local development and conformance. Refused unless the public URL is
+   * loopback too, so no instance anyone else can reach ever trusts one.
+   */
+  allowLoopbackIssuersForDevelopment?: boolean;
+};
+/** Cloudflare's rate-limiting binding, as coffre calls it; `processLimits()` has the same shape. */
+export type RateLimiter = {
+  limit(options: {
+    key: string;
+  }): Promise<{
+    success: boolean;
+  }>;
+};
+export type WorkloadLimits = {
+  perSource: RateLimiter;
+  total: RateLimiter;
+};
+export type WorkloadsConfig = {
+  allowLoopback: boolean;
+  limits: WorkloadLimits;
 };
 type Credentials = {
   clientId: string;
@@ -249,6 +290,7 @@ export declare function defineSignin(options: {
   };
   browserSessionHours?: number;
   cliSessionDays?: number;
+  workloads?: WorkloadsOptions;
 }): SigninConfig;
 //#endregion
 //#region src/identity/types.d.ts
@@ -350,6 +392,8 @@ export type SigninOptions = {
   browserSessionHours?: number;
   /** Absolute lifetime of a CLI session; 30 days unless set, at most a year. */
   cliSessionDays?: number;
+  /** Lets CI runs sign in as services with their platform's ID token: `{}` turns it on. */
+  workloads?: WorkloadsOptions;
 };
 /**
  * coffre's own sign-in page, with these providers:
@@ -430,4 +474,77 @@ export declare class AccessIdentityVerifier implements IdentityVerifier {
  * asking.
  */
 export declare function toPrincipal(claims: AccessClaims): Principal;
-//#endregion
+//#endregion
+//#region src/identity/workload-token.d.ts
+/**
+ * An ID token a CI platform signed for a run, as the exchange checks it
+ * (docs/design/oidc.md, section 3). The checks run in this order; each
+ * refusal says which, as a reason a CI user can act on.
+ */
+/** A compact JWS is three base64url parts; the whole token at most this long. */
+export declare const MAX_TOKEN_BYTES: number;
+/** Each side of every time check. */
+export declare const CLOCK_TOLERANCE_SECONDS = 30;
+/** The oldest token accepted, by its `iat`: tokens handed to a job at its start fit, day-old ones do not. */
+export declare const MAX_TOKEN_AGE_SECONDS = 3600;
+/** RS256 and ES256 (P-256), as for Access assertions: never `none`, never HS*. */
+export declare const WORKLOAD_ALGORITHMS: readonly ["RS256", "ES256"];
+export type WorkloadRefusal =
+/** Not a compact JWS, or claims that are not the right types. */
+'malformed' |
+/** The signature does not verify under the issuer's keys. */
+'signature' |
+/** Signed by a key the issuer's set does not hold, now. */
+'unknown_key' |
+/** Past its `exp`. */
+'expired' |
+/** Its `iat` is more than an hour ago, or not yet. */
+'too_old' |
+/** Its `nbf` is still to come. */
+'not_yet_valid' |
+/** Its audience is not this instance alone. */
+'audience';
+export declare class WorkloadTokenRefused extends Error {
+  readonly reason: WorkloadRefusal;
+  constructor(reason: WorkloadRefusal, message: string);
+}
+/** What a token says before anything about it is trusted: enough to find the binding it would match. */
+export type DecodedToken = {
+  header: Record<string, unknown>;
+  claims: Record<string, unknown> & {
+    iss: string;
+    sub: string;
+    exp: number;
+    iat: number;
+  };
+  /**
+   * SHA-256 of `header.payload`, exactly as received: what the signature
+   * covers, and so the one spelling of the token. Hashing the whole token
+   * would not do: an ES256 signature (r, s) has a twin, (r, n − s), that
+   * verifies the same claims, so the whole token has two spellings.
+   */
+  signingInputHash: Buffer;
+};
+/** A token's parts and claims, checked for shape and types only. Throws `WorkloadTokenRefused('malformed')`. */
+export declare function decodeWorkloadToken(token: string): DecodedToken;
+/**
+ * Verify a token under an issuer's keys: the signature by jose, with the
+ * algorithms fixed and nothing taken from the header but `alg` and `kid`;
+ * the issuer exactly; `exp`, `nbf` and `iat` within the tolerance, `iat` at
+ * most an hour old; and the audience, this instance's public URL alone.
+ * Returns the verified claims.
+ */
+export declare function verifyWorkloadToken(token: string, keys: JSONWebKeySet, expected: {
+  issuer: string;
+  audience: string;
+  now: Date;
+}): Promise<JWTPayload & DecodedToken['claims']>;
+/**
+ * Why a token issued at `iat` may not be exchanged at `now`, both in
+ * seconds, or null: issued an hour ago at most, exactly, and no further
+ * ahead than the clock tolerance. Verification and the exchange's commit
+ * both ask it.
+ */
+export declare function issuedRefusal(iat: number, now: number): WorkloadTokenRefused | null;
+//#endregion
+export { BindingClaims, BindingInvalid, BindingPolicy, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, type JSONWebKeySet, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, REQUIRED_CLAIMS, WORKLOAD_PROFILES, WorkloadProfile, canonicalClaims, checkBinding, checkFetchUrl, defaultIssuer, fullRef, githubReusable, githubWorkflow, gitlabProject, workflowRef };

package/dist/identity.js

@@ -1,6 +1,7 @@
+import { BindingInvalid, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, REQUIRED_CLAIMS, WORKLOAD_PROFILES, canonicalClaims, checkBinding, checkFetchUrl, defaultIssuer, fullRef, githubReusable, githubWorkflow, gitlabProject, workflowRef } from "./workloads.js";
 import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes } from "node:crypto";
 import * as oauth from "oauth4webapi";
-import { createRemoteJWKSet, jwtVerify } from "jose";
+import { createLocalJWKSet, createRemoteJWKSet, errors, jwtVerify } from "jose";
 //#region src/identity/signin/types.ts
 var SigninError = class extends Error {
 	code;
@@ -450,7 +451,19 @@ function defineSignin(options) {
 			note: options.page?.note ?? null
 		},
 		browserSessionHours: lifetime(options.browserSessionHours, "browserSessionHours", 12, 168),
-		cliSessionDays: lifetime(options.cliSessionDays, "cliSessionDays", 30, 365)
+		cliSessionDays: lifetime(options.cliSessionDays, "cliSessionDays", 30, 365),
+		workloads: options.workloads === void 0 ? null : workloadsConfig(options.workloads, publicOrigin(options.publicUrl))
+	};
+}
+/** Workloads, checked: both limits given, each one a limiter; loopback issuers only on a loopback instance. */
+function workloadsConfig(options, publicUrl) {
+	const limiter = (value) => typeof value?.limit === "function";
+	if (!limiter(options.limits?.perSource) || !limiter(options.limits?.total)) throw new Error("workloads need their limits, per source and in total: on Workers, two rate-limiting bindings; on Node, processLimits()");
+	const loopback = options.allowLoopbackIssuersForDevelopment === true;
+	if (loopback && !isLoopback(new URL(publicUrl))) throw new Error(`workloads.allowLoopbackIssuersForDevelopment is for an instance on loopback, and ${publicUrl} is not one: turn it off`);
+	return {
+		allowLoopback: loopback,
+		limits: options.limits
 	};
 }
 /** A deployment's own provider is checked like coffre's: it is only typed, not trusted. */
@@ -512,7 +525,7 @@ function cloudflareAccess(options) {
 function signin(options) {
 	defineSignin({
 		...toSignin(options),
-		publicUrl: "https://coffre.invalid"
+		publicUrl: "http://127.0.0.1"
 	});
 	return { resolve: (publicUrl) => ({
 		mode: "signin",
@@ -530,7 +543,8 @@ function toSignin(options) {
 			note: options.note
 		},
 		browserSessionHours: options.browserSessionHours,
-		cliSessionDays: options.cliSessionDays
+		cliSessionDays: options.cliSessionDays,
+		workloads: options.workloads
 	};
 }
 //#endregion
@@ -688,4 +702,111 @@ function toPrincipal(claims) {
 	throw new Error("token verified but carries no usable identity: expected common_name (service) or sub+email (user)");
 }
 //#endregion
-export { ACCESS_JWT_HEADER, AccessIdentityVerifier, GitHubSigninProvider, OidcSigninProvider, SigninError, cloudflareAccess, defineSignin, deriveKey, generateToken, github, google, hashToken, isCoffreToken, microsoft, oidc, publicOrigin, seal, signin, toPrincipal, tokenHint, unseal };
+//#region src/identity/workload-token.ts
+/**
+* An ID token a CI platform signed for a run, as the exchange checks it
+* (docs/design/oidc.md, section 3). The checks run in this order; each
+* refusal says which, as a reason a CI user can act on.
+*/
+/** A compact JWS is three base64url parts; the whole token at most this long. */
+const MAX_TOKEN_BYTES = 8192;
+/** Each side of every time check. */
+const CLOCK_TOLERANCE_SECONDS = 30;
+/** The oldest token accepted, by its `iat`: tokens handed to a job at its start fit, day-old ones do not. */
+const MAX_TOKEN_AGE_SECONDS = 3600;
+/** RS256 and ES256 (P-256), as for Access assertions: never `none`, never HS*. */
+const WORKLOAD_ALGORITHMS = ["RS256", "ES256"];
+var WorkloadTokenRefused = class extends Error {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.name = "WorkloadTokenRefused";
+		this.reason = reason;
+	}
+};
+const PART = /^[A-Za-z0-9_-]+$/;
+/** A token's parts and claims, checked for shape and types only. Throws `WorkloadTokenRefused('malformed')`. */
+function decodeWorkloadToken(token) {
+	const malformed = (why) => new WorkloadTokenRefused("malformed", `the token ${why}`);
+	if (typeof token !== "string" || token.length === 0) throw malformed("is empty");
+	if (token.length > 8192) throw malformed(`is longer than ${MAX_TOKEN_BYTES} bytes`);
+	const parts = token.split(".");
+	if (parts.length !== 3 || !parts.every((part) => PART.test(part))) throw malformed("is not a compact JWS");
+	const json = (part) => {
+		let value;
+		try {
+			value = JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+		} catch {
+			throw malformed("has a part that is not JSON");
+		}
+		if (typeof value !== "object" || value === null || Array.isArray(value)) throw malformed("has a part that is not an object");
+		return value;
+	};
+	const [header, claims] = [json(parts[0]), json(parts[1])];
+	for (const name of ["iss", "sub"]) if (typeof claims[name] !== "string" || claims[name] === "") throw malformed(`has no ${name}, as a nonempty string`);
+	for (const name of ["exp", "iat"]) if (typeof claims[name] !== "number" || !Number.isFinite(claims[name])) throw malformed(`has no ${name}, as a finite number`);
+	if (claims.nbf !== void 0 && (typeof claims.nbf !== "number" || !Number.isFinite(claims.nbf))) throw malformed("has an nbf that is not a finite number");
+	return {
+		header,
+		claims,
+		signingInputHash: createHash("sha256").update(`${parts[0]}.${parts[1]}`, "ascii").digest()
+	};
+}
+/**
+* Verify a token under an issuer's keys: the signature by jose, with the
+* algorithms fixed and nothing taken from the header but `alg` and `kid`;
+* the issuer exactly; `exp`, `nbf` and `iat` within the tolerance, `iat` at
+* most an hour old; and the audience, this instance's public URL alone.
+* Returns the verified claims.
+*/
+async function verifyWorkloadToken(token, keys, expected) {
+	let payload;
+	try {
+		({payload} = await jwtVerify(token, createLocalJWKSet(keys), {
+			algorithms: [...WORKLOAD_ALGORITHMS],
+			issuer: expected.issuer,
+			clockTolerance: 30,
+			requiredClaims: [
+				"iss",
+				"sub",
+				"exp",
+				"iat"
+			],
+			currentDate: expected.now
+		}));
+	} catch (error) {
+		throw refusalOf(error);
+	}
+	const issued = issuedRefusal(payload.iat, expected.now.getTime() / 1e3);
+	if (issued !== null) throw issued;
+	const { aud } = payload;
+	if (!(aud === expected.audience || Array.isArray(aud) && aud.length === 1 && aud[0] === expected.audience)) throw new WorkloadTokenRefused("audience", `the token is for ${JSON.stringify(aud ?? null)}, not ${expected.audience} alone`);
+	return payload;
+}
+/**
+* Why a token issued at `iat` may not be exchanged at `now`, both in
+* seconds, or null: issued an hour ago at most, exactly, and no further
+* ahead than the clock tolerance. Verification and the exchange's commit
+* both ask it.
+*/
+function issuedRefusal(iat, now) {
+	if (now - iat > 3600) return new WorkloadTokenRefused("too_old", `the token was issued more than ${MAX_TOKEN_AGE_SECONDS / 60} minutes ago`);
+	if (iat - now > 30) return new WorkloadTokenRefused("too_old", "the token says it was issued in the future");
+	return null;
+}
+function refusalOf(error) {
+	if (error instanceof errors.JWKSNoMatchingKey) return new WorkloadTokenRefused("unknown_key", "the token's key is not among the issuer's");
+	if (error instanceof errors.JWTExpired) return error.claim === "iat" ? new WorkloadTokenRefused("too_old", `the token was issued more than ${MAX_TOKEN_AGE_SECONDS / 60} minutes ago`) : new WorkloadTokenRefused("expired", "the token has expired");
+	if (error instanceof errors.JWTClaimValidationFailed) {
+		if (error.claim === "nbf") return new WorkloadTokenRefused("not_yet_valid", "the token is not valid yet");
+		if (error.claim === "iat") return new WorkloadTokenRefused("too_old", "the token says it was issued in the future");
+		if (error.claim === "iss") return new WorkloadTokenRefused("signature", "the token is not from the binding's issuer");
+		return new WorkloadTokenRefused("malformed", `the token's ${error.claim} is not as required`);
+	}
+	if (error instanceof errors.JOSEAlgNotAllowed || error instanceof errors.JOSENotSupported) return new WorkloadTokenRefused("signature", "the token is signed with an algorithm coffre does not accept");
+	if (error instanceof errors.JWSSignatureVerificationFailed || error instanceof errors.JWSInvalid || error instanceof errors.JWTInvalid) return new WorkloadTokenRefused("signature", "the token's signature does not verify");
+	if (error instanceof errors.JOSEError) return new WorkloadTokenRefused("signature", `the token does not verify: ${error.code}`);
+	return new WorkloadTokenRefused("signature", "the token does not verify");
+}
+//#endregion
+export { ACCESS_JWT_HEADER, AccessIdentityVerifier, BindingInvalid, CLOCK_TOLERANCE_SECONDS, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, GitHubSigninProvider, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, MAX_TOKEN_AGE_SECONDS, MAX_TOKEN_BYTES, OidcSigninProvider, REQUIRED_CLAIMS, SigninError, WORKLOAD_ALGORITHMS, WORKLOAD_PROFILES, WorkloadTokenRefused, canonicalClaims, checkBinding, checkFetchUrl, cloudflareAccess, decodeWorkloadToken, defaultIssuer, defineSignin, deriveKey, fullRef, generateToken, github, githubReusable, githubWorkflow, gitlabProject, google, hashToken, isCoffreToken, issuedRefusal, microsoft, oidc, publicOrigin, seal, signin, toPrincipal, tokenHint, unseal, verifyWorkloadToken, workflowRef };

package/dist/vault.d.ts

@@ -276,6 +276,12 @@ type Correlation = {
    * reads, a write's versions, an access change. Its entries share it.
    */
   operationId?: string | null;
+  /**
+   * The credential the request came in on, when a trust binding issued it
+   * for a CI run: the vault copies it into the entries it writes, and never
+   * decides on it, so that a read leads back to its run (docs/design/oidc.md).
+   */
+  credentialId?: string | null;
 };
 export type UnwrapInput = Correlation & {
   principal: string;

package/dist/workloads.d.ts

@@ -0,0 +1,123 @@
+//#region src/identity/workloads.d.ts
+/**
+ * Trust bindings: which CI runs may sign in as a service, by the ID token
+ * their platform signs for them (docs/design/oidc.md).
+ *
+ * A binding names a profile, an issuer, and claims a token must carry, each
+ * a top-level string matched exactly. The profile sets the minimum: the
+ * server refuses a binding that lacks a claim its profile requires, from the
+ * UI, the CLI or the API alike. Say a service is bound to `deploy.yml`,
+ * pushed to `main` of `acme/api`:
+ *
+ *   { profile: 'github', issuer: 'https://token.actions.githubusercontent.com',
+ *     claims: { repository_owner_id: '9919', repository_id: '41532',
+ *               workflow_ref: 'acme/api/.github/workflows/deploy.yml@refs/heads/main',
+ *               ref: 'refs/heads/main', event_name: 'push' } }
+ */
+export declare const GITHUB_ISSUER = "https://token.actions.githubusercontent.com";
+export declare const GITLAB_ISSUER = "https://gitlab.com";
+/**
+ * - `github`: a workflow of the repository.
+ * - `github-reusable`: a reusable workflow, pinned to one commit, called from
+ *   one repository at one ref.
+ * - `github-reusable-organization`: the same, called from any repository of
+ *   the organization: an explicit choice, never what a missing claim means.
+ * - `gitlab`: a project's pipelines, outside merge requests.
+ * - `custom`: any other issuer, by its subject, which the owner vouches for.
+ */
+export type WorkloadProfile = 'github' | 'github-reusable' | 'github-reusable-organization' | 'gitlab' | 'custom';
+export declare const WORKLOAD_PROFILES: readonly WorkloadProfile[];
+/** The claims each profile requires; a binding may add more, to narrow it. */
+export declare const REQUIRED_CLAIMS: Record<WorkloadProfile, readonly string[]>;
+/**
+ * Events triggered by someone with write access, at a ref the binding names
+ * exactly. `pull_request`, `pull_request_target`, `workflow_run` and the
+ * rest are refused, even when their ref happens to match: their runs can
+ * carry a stranger's code.
+ */
+export declare const GITHUB_EVENTS: readonly ["push", "workflow_dispatch", "schedule", "release"];
+/** Pipelines that run the project's own code, at its own ref: never a merge request's. */
+export declare const GITLAB_PIPELINE_SOURCES: readonly ["push", "web", "schedule"];
+/** At most this many live bindings per service, and claims per binding. */
+export declare const MAX_BINDINGS = 16;
+export declare const MAX_CLAIMS = 16;
+/** The longest claim value, in bytes. */
+export declare const MAX_CLAIM_BYTES = 256;
+export type BindingClaims = Record<string, string>;
+/** What makes a binding, checked: its profile, its issuer as a URL, and its claims, sorted. */
+export type BindingPolicy = {
+  profile: WorkloadProfile;
+  issuer: string;
+  claims: BindingClaims;
+};
+/** A binding that breaks a rule, said so an owner can fix it. */
+export declare class BindingInvalid extends Error {
+  constructor(message: string);
+}
+/** The issuer a profile means when none is given: github.com's or gitlab.com's. A GitHub Enterprise Server or a self-managed GitLab names its own. */
+export declare function defaultIssuer(profile: WorkloadProfile): string | null;
+/**
+ * Check a binding against its profile, and return it as stored: the
+ * issuer as given, the claims sorted by name. Throws `BindingInvalid`.
+ */
+export declare function checkBinding(input: {
+  profile: string;
+  issuer: string | null;
+  claims: Record<string, unknown>;
+}, options?: {
+  allowLoopback?: boolean;
+}): BindingPolicy;
+/** The claims as the MAC and the database hold them: JSON, sorted by name. */
+export declare function canonicalClaims(claims: BindingClaims): string;
+/**
+ * A URL coffre may fetch for a binding: an issuer, or the keys its
+ * discovery names. `https` on port 443, a host name rather than an address,
+ * and nothing that names this machine or its network. Loopback over plain
+ * HTTP only where the deployment allows it, for the dev IdP. Where the name
+ * resolves is checked again when connecting, on Node (`addresses.ts` in the
+ * server).
+ */
+export declare function checkFetchUrl(value: string, what: string, options: {
+  allowLoopback?: boolean;
+  path: boolean;
+  query: boolean;
+}): URL;
+/** `refs/heads/main`, or `refs/tags/v1`, as GitHub names a ref. */
+export declare function fullRef(kind: 'branch' | 'tag', name: string): string;
+/** A workflow file at a ref, as GitHub's tokens name it: `acme/api/.github/workflows/deploy.yml@refs/heads/main`. */
+export declare function workflowRef(repository: string, file: string, ref: string): string;
+/** A workflow of the repository, run by `event` at `ref`. */
+export declare function githubWorkflow(input: {
+  repository: string;
+  repositoryId: string;
+  ownerId: string;
+  workflow: string;
+  ref: string;
+  event: string;
+}): Omit<BindingPolicy, 'issuer'>;
+/**
+ * A reusable workflow at one commit, called at `ref`: from one repository,
+ * or, with `repositoryId` null, from any repository of the organization. A
+ * `caller` workflow narrows it to one calling workflow.
+ */
+export declare function githubReusable(input: {
+  repositoryId: string | null;
+  ownerId: string;
+  ref: string;
+  event: string;
+  called: string;
+  sha: string;
+  caller?: {
+    repository: string;
+    workflow: string;
+  };
+}): Omit<BindingPolicy, 'issuer'>;
+/** A GitLab project's pipelines from `source`, at a branch or tag. */
+export declare function gitlabProject(input: {
+  namespaceId: string;
+  projectId: string;
+  refType: 'branch' | 'tag';
+  ref: string;
+  source: string;
+}): Omit<BindingPolicy, 'issuer'>;
+//#endregion