@atcute/oauth-crypto 0.1.0

package/dist/jwk/keys.js

@@ -0,0 +1,13 @@
+import { exportPkcs8PrivateKey as exportPkcs8 } from '../internal/jwk.js';
+import { getCachedKeyMaterial } from '../internal/key-cache.js';
+/**
+ * exports a private JWK to PKCS8 PEM format.
+ *
+ * @param jwk private JWK to export
+ * @returns PKCS8 PEM string
+ */
+export const exportPkcs8PrivateKey = async (jwk) => {
+    const { cryptoKey } = await getCachedKeyMaterial(jwk);
+    return exportPkcs8(cryptoKey);
+};
+//# sourceMappingURL=keys.js.map

package/dist/jwk/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../lib/jwk/keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAIhE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,EAAE,GAAe,EAAmB,EAAE,CAAC;IAChF,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,oBAAoB,CAAC,GAAG,CAAC,CAAC;IACtD,OAAO,WAAW,CAAC,SAAS,CAAC,CAAC;AAAA,CAC9B,CAAC"}

package/dist/jwk/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * signing algorithms supported by atproto oauth.
+ */
+export type SigningAlgorithm = 'ES256' | 'ES384' | 'ES512' | 'PS256' | 'PS384' | 'PS512' | 'RS256' | 'RS384' | 'RS512';
+export interface EcPublicJwk {
+    kty: 'EC';
+    crv: 'P-256' | 'P-384' | 'P-521';
+    x: string;
+    y: string;
+    alg?: SigningAlgorithm;
+    use?: 'sig';
+    kid?: string;
+}
+export interface RsaPublicJwk {
+    kty: 'RSA';
+    n: string;
+    e: string;
+    alg?: SigningAlgorithm;
+    use?: 'sig';
+    kid?: string;
+}
+export type PublicJwk = EcPublicJwk | RsaPublicJwk;
+export interface EcPrivateJwk extends EcPublicJwk {
+    alg: SigningAlgorithm;
+    d: string;
+}
+export interface RsaPrivateJwk extends RsaPublicJwk {
+    alg: SigningAlgorithm;
+    d: string;
+    p?: string;
+    q?: string;
+    dp?: string;
+    dq?: string;
+    qi?: string;
+}
+export type PrivateJwk = EcPrivateJwk | RsaPrivateJwk;
+//# sourceMappingURL=types.d.ts.map

package/dist/jwk/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../lib/jwk/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACzB,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,CAAC;AAEX,MAAM,WAAW,WAAW;IAC3B,GAAG,EAAE,IAAI,CAAC;IACV,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACjC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,GAAG,CAAC,EAAE,KAAK,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC5B,GAAG,EAAE,KAAK,CAAC;IACX,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,GAAG,CAAC,EAAE,KAAK,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,YAAY,CAAC;AAEnD,MAAM,WAAW,YAAa,SAAQ,WAAW;IAChD,GAAG,EAAE,gBAAgB,CAAC;IACtB,CAAC,EAAE,MAAM,CAAC;CACV;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IAClD,GAAG,EAAE,gBAAgB,CAAC;IACtB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,aAAa,CAAC"}

package/dist/jwk/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/jwk/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../lib/jwk/types.ts"],"names":[],"mappings":""}

package/dist/jwt/index.d.ts

@@ -0,0 +1,26 @@
+import type { SigningAlgorithm } from '../jwk/types.js';
+/**
+ * signs a jwt using webcrypto.
+ *
+ * @param params signing parameters
+ * @returns signed jwt
+ */
+export declare const signJwt: (params: {
+    header: Record<string, unknown>;
+    payload: Record<string, unknown>;
+    key: CryptoKey;
+    alg: SigningAlgorithm;
+}) => Promise<string>;
+/**
+ * verifies a jwt and returns its payload.
+ *
+ * @param jwt jwt string
+ * @param options verification options
+ * @returns decoded payload
+ */
+export declare const verifyJwt: (jwt: string, options: {
+    key: CryptoKey;
+    alg: SigningAlgorithm;
+    typ?: string | undefined;
+}) => Promise<Record<string, unknown>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/jwt/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/jwt/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,OAAO;;;;;qBAqBnB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,SAAS;;;;sCAkCrB,CAAC"}

package/dist/jwt/index.js

@@ -0,0 +1,56 @@
+import { fromBase64Url, toBase64Url } from '@atcute/multibase';
+import { decodeUtf8From, encodeUtf8 } from '@atcute/uint8array';
+import { getSignAlgorithm } from '../internal/crypto.js';
+/**
+ * signs a jwt using webcrypto.
+ *
+ * @param params signing parameters
+ * @returns signed jwt
+ */
+export const signJwt = async (params) => {
+    const { header, payload, key, alg } = params;
+    const fullHeader = { ...header, alg };
+    const headerSegment = encodeSegment(fullHeader);
+    const payloadSegment = encodeSegment(payload);
+    const signingInput = `${headerSegment}.${payloadSegment}`;
+    const signature = await crypto.subtle.sign(getSignAlgorithm(alg), key, encodeUtf8(signingInput));
+    const signatureSegment = toBase64Url(new Uint8Array(signature));
+    return `${signingInput}.${signatureSegment}`;
+};
+/**
+ * verifies a jwt and returns its payload.
+ *
+ * @param jwt jwt string
+ * @param options verification options
+ * @returns decoded payload
+ */
+export const verifyJwt = async (jwt, options) => {
+    const { key, alg, typ } = options;
+    const parts = jwt.split('.');
+    if (parts.length !== 3) {
+        throw new Error(`invalid jwt format`);
+    }
+    const header = decodeSegment(parts[0]);
+    if (header.alg !== alg) {
+        throw new Error(`invalid jwt alg`);
+    }
+    if (typ && header.typ !== typ) {
+        throw new Error(`invalid jwt typ`);
+    }
+    const payload = decodeSegment(parts[1]);
+    const signature = fromBase64Url(parts[2]);
+    const signingInput = `${parts[0]}.${parts[1]}`;
+    const ok = await crypto.subtle.verify(getSignAlgorithm(alg), key, signature, encodeUtf8(signingInput));
+    if (!ok) {
+        throw new Error(`invalid jwt signature`);
+    }
+    return payload;
+};
+const encodeSegment = (value) => {
+    return toBase64Url(encodeUtf8(JSON.stringify(value)));
+};
+const decodeSegment = (value) => {
+    const bytes = fromBase64Url(value);
+    return JSON.parse(decodeUtf8From(bytes));
+};
+//# sourceMappingURL=index.js.map

package/dist/jwt/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/jwt/index.ts"],"names":[],"mappings":"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"}

package/lib/client-assertion/create-client-assertion.ts

@@ -0,0 +1,50 @@
+import { nanoid } from 'nanoid';
+
+import { getCachedKeyMaterial } from '../internal/key-cache.js';
+import { signJwt } from '../jwt/index.js';
+
+import type { ClientAssertionPrivateJwk } from './types.js';
+
+export interface CreateClientAssertionOptions {
+	/** client id */
+	client_id: string;
+	/** authorization server issuer */
+	aud: string;
+	/** JWK thumbprint of the DPoP key to bind to (for CAB pattern) */
+	jkt?: string;
+	/** client assertion signing key */
+	key: ClientAssertionPrivateJwk;
+}
+
+/**
+ * creates a DPoP-bound client assertion per RFC 7523.
+ *
+ * @param options creation options
+ * @returns signed client assertion JWT
+ */
+export const createClientAssertion = async (options: CreateClientAssertionOptions): Promise<string> => {
+	const { client_id, aud, jkt, key } = options;
+	const { kid, alg } = key;
+	const { cryptoKey } = await getCachedKeyMaterial(key);
+
+	const now = Math.floor(Date.now() / 1000);
+	const cnf = jkt ? { jkt } : undefined;
+
+	return signJwt({
+		header: {
+			alg,
+			kid,
+		},
+		payload: {
+			iss: client_id,
+			sub: client_id,
+			aud: aud,
+			jti: nanoid(24),
+			iat: now,
+			exp: now + 60,
+			cnf,
+		},
+		key: cryptoKey,
+		alg,
+	});
+};

package/lib/client-assertion/generate-key.ts

@@ -0,0 +1,26 @@
+import { getGenerateAlgorithm } from '../internal/crypto.js';
+import { exportPrivateJwkFromKey } from '../internal/jwk.js';
+import { setCachedKeyMaterial } from '../internal/key-cache.js';
+import type { SigningAlgorithm } from '../jwk/types.js';
+
+import type { ClientAssertionPrivateJwk } from './types.js';
+
+/**
+ * generates a new client assertion private key.
+ *
+ * @param kid key id to assign
+ * @param alg signing algorithm (defaults to es256)
+ * @returns client assertion private JWK (with cache pre-warmed)
+ */
+export const generateClientAssertionKey = async (
+	kid: string,
+	alg: SigningAlgorithm = 'ES256',
+): Promise<ClientAssertionPrivateJwk> => {
+	const pair = await crypto.subtle.generateKey(getGenerateAlgorithm(alg), true, ['sign', 'verify']);
+	const jwk = (await exportPrivateJwkFromKey(pair.privateKey, alg, kid)) as ClientAssertionPrivateJwk;
+
+	// pre-populate cache so we don't re-import
+	setCachedKeyMaterial(jwk, pair.privateKey);
+
+	return jwk;
+};

package/lib/client-assertion/index.ts

@@ -0,0 +1,4 @@
+export { createClientAssertion } from './create-client-assertion.js';
+export { generateClientAssertionKey } from './generate-key.js';
+export { importClientAssertionPkcs8 } from './keys.js';
+export type { ClientAssertionPrivateJwk } from './types.js';

package/lib/client-assertion/keys.ts

@@ -0,0 +1,26 @@
+import { exportPrivateJwkFromKey, importPkcs8PrivateKey } from '../internal/jwk.js';
+import { setCachedKeyMaterial } from '../internal/key-cache.js';
+import type { SigningAlgorithm } from '../jwk/types.js';
+
+import type { ClientAssertionPrivateJwk } from './types.js';
+
+/**
+ * imports a client assertion private key from a pkcs8 pem string.
+ *
+ * @param pem pkcs8 pem string
+ * @param options import options (kid + alg)
+ * @returns client assertion private JWK (with cache pre-warmed)
+ */
+export const importClientAssertionPkcs8 = async (
+	pem: string,
+	options: { kid: string; alg: SigningAlgorithm },
+): Promise<ClientAssertionPrivateJwk> => {
+	const { kid, alg } = options;
+	const cryptoKey = await importPkcs8PrivateKey(pem, alg);
+	const jwk = (await exportPrivateJwkFromKey(cryptoKey, alg, kid)) as ClientAssertionPrivateJwk;
+
+	// pre-populate cache so we don't re-import
+	setCachedKeyMaterial(jwk, cryptoKey);
+
+	return jwk;
+};

package/lib/client-assertion/types.ts

@@ -0,0 +1,9 @@
+import type { PrivateJwk, SigningAlgorithm } from '../jwk/types.js';
+
+/**
+ * private jwk for client assertion signing.
+ */
+export type ClientAssertionPrivateJwk = PrivateJwk & {
+	alg: SigningAlgorithm;
+	kid: string;
+};

package/lib/dpop/fetch.ts

@@ -0,0 +1,140 @@
+import { sha256Base64Url } from '../hash/sha256.js';
+
+import { createDpopProofSigner } from './proof.js';
+import type { DpopPrivateJwk, DpopNonceCache } from './types.js';
+
+export interface CreateDpopFetchOptions {
+	/** DPoP private key (JWK with `alg` set) */
+	key: DpopPrivateJwk;
+	/** nonce store, keyed by origin */
+	nonces: DpopNonceCache;
+	/** server's supported DPoP signing algorithms */
+	supportedAlgs?: readonly string[];
+	/**
+	 * is the target an authorization server (true) or resource server (false)?
+	 * affects how `use_dpop_nonce` errors are detected.
+	 */
+	isAuthServer?: boolean;
+	/** custom fetch implementation */
+	fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * creates a fetch wrapper that adds DPoP proofs to requests.
+ *
+ * @param options DPoP configuration
+ * @returns fetch function with DPoP support
+ */
+export const createDpopFetch = (options: CreateDpopFetchOptions): typeof globalThis.fetch => {
+	const { key, nonces, supportedAlgs, isAuthServer, fetch = globalThis.fetch } = options;
+
+	negotiateAlg(key, supportedAlgs);
+	const sign = createDpopProofSigner(key);
+
+	return async (input, init) => {
+		const request: Request = init == null && input instanceof Request ? input : new Request(input, init);
+
+		const authHeader = request.headers.get('Authorization');
+		const ath = authHeader?.startsWith('DPoP ') ? await sha256Base64Url(authHeader.slice(5)) : undefined;
+
+		const { origin } = new URL(request.url);
+		const htm = request.method;
+		const htu = buildHtu(request.url);
+
+		let initNonce: string | undefined;
+		try {
+			initNonce = await nonces.get(origin);
+		} catch {
+			// ignore get errors
+		}
+
+		const initProof = await sign(htm, htu, initNonce, ath);
+		request.headers.set('DPoP', initProof);
+
+		const initResponse = await fetch(request);
+
+		const nextNonce = initResponse.headers.get('DPoP-Nonce');
+		if (!nextNonce || nextNonce === initNonce) {
+			return initResponse;
+		}
+
+		try {
+			await nonces.set(origin, nextNonce);
+		} catch {
+			// ignore set errors
+		}
+
+		const shouldRetry = await isUseDpopNonceError(initResponse, isAuthServer);
+		if (!shouldRetry) {
+			return initResponse;
+		}
+
+		if (input === request || init?.body instanceof ReadableStream) {
+			return initResponse;
+		}
+
+		await initResponse.body?.cancel();
+
+		const nextProof = await sign(htm, htu, nextNonce, ath);
+		const nextRequest = new Request(input, init);
+		nextRequest.headers.set('DPoP', nextProof);
+
+		const retryResponse = await fetch(nextRequest);
+
+		const retryNonce = retryResponse.headers.get('DPoP-Nonce');
+		if (retryNonce && retryNonce !== nextNonce) {
+			try {
+				await nonces.set(origin, retryNonce);
+			} catch {
+				// ignore set errors
+			}
+		}
+
+		return retryResponse;
+	};
+};
+
+const buildHtu = (url: string): string => {
+	const fragmentIdx = url.indexOf('#');
+	const queryIdx = url.indexOf('?');
+	const end = fragmentIdx === -1 ? queryIdx : queryIdx === -1 ? fragmentIdx : Math.min(fragmentIdx, queryIdx);
+
+	return end === -1 ? url : url.slice(0, end);
+};
+
+const negotiateAlg = (key: DpopPrivateJwk, supportedAlgs?: readonly string[]): string => {
+	const keyAlg = key.alg;
+
+	if (supportedAlgs?.length) {
+		if (supportedAlgs.includes(keyAlg)) {
+			return keyAlg;
+		}
+		throw new Error(`DPoP key algorithm ${keyAlg} not supported by server: ${supportedAlgs.join(', ')}`);
+	}
+
+	return keyAlg;
+};
+
+const isUseDpopNonceError = async (response: Response, isAuthServer?: boolean): Promise<boolean> => {
+	if (isAuthServer === undefined || isAuthServer === false) {
+		if (response.status === 401) {
+			const wwwAuth = response.headers.get('WWW-Authenticate');
+			if (wwwAuth?.startsWith('DPoP')) {
+				return wwwAuth.includes('error="use_dpop_nonce"');
+			}
+		}
+	}
+
+	if (isAuthServer === undefined || isAuthServer === true) {
+		if (response.status === 400) {
+			try {
+				const json = await response.clone().json();
+				return typeof json === 'object' && json?.error === 'use_dpop_nonce';
+			} catch {
+				return false;
+			}
+		}
+	}
+
+	return false;
+};

package/lib/dpop/generate-key.ts

@@ -0,0 +1,72 @@
+import { getGenerateAlgorithm } from '../internal/crypto.js';
+import { exportPrivateJwkFromKey, isSigningAlgorithm } from '../internal/jwk.js';
+import { setCachedKeyMaterial } from '../internal/key-cache.js';
+import type { SigningAlgorithm } from '../jwk/types.js';
+
+import type { DpopPrivateJwk } from './types.js';
+
+/**
+ * preferred algorithm order for DPoP key generation.
+ */
+const PREFERRED_ALGORITHMS: readonly SigningAlgorithm[] = [
+	'ES256',
+	'ES384',
+	'ES512',
+	'PS256',
+	'PS384',
+	'PS512',
+	'RS256',
+	'RS384',
+	'RS512',
+];
+
+const sortAlgorithms = (algs: readonly SigningAlgorithm[]): SigningAlgorithm[] => {
+	return [...algs].sort((a, b) => {
+		const aIdx = PREFERRED_ALGORITHMS.indexOf(a);
+		const bIdx = PREFERRED_ALGORITHMS.indexOf(b);
+
+		if (aIdx === -1 && bIdx === -1) {
+			return 0;
+		}
+		if (aIdx === -1) {
+			return 1;
+		}
+		if (bIdx === -1) {
+			return -1;
+		}
+
+		return aIdx - bIdx;
+	});
+};
+
+/**
+ * generates a new DPoP private JWK with `alg` set.
+ *
+ * @param supportedAlgs server supported algorithms (optional)
+ * @returns private JWK (with cache pre-warmed)
+ */
+export const generateDpopKey = async (supportedAlgs?: readonly string[]): Promise<DpopPrivateJwk> => {
+	const normalized = supportedAlgs?.filter(isSigningAlgorithm) ?? [];
+	if (supportedAlgs?.length && normalized.length === 0) {
+		throw new Error(`no supported algorithms provided`);
+	}
+
+	const algs: SigningAlgorithm[] = normalized.length ? sortAlgorithms(normalized) : ['ES256'];
+	const errors: unknown[] = [];
+
+	for (const alg of algs) {
+		try {
+			const pair = await crypto.subtle.generateKey(getGenerateAlgorithm(alg), true, ['sign', 'verify']);
+			const jwk = (await exportPrivateJwkFromKey(pair.privateKey, alg)) as DpopPrivateJwk;
+
+			// pre-populate cache so we don't re-import
+			setCachedKeyMaterial(jwk, pair.privateKey);
+
+			return jwk;
+		} catch (err) {
+			errors.push(err);
+		}
+	}
+
+	throw new AggregateError(errors, `failed to generate DPoP key for any of: ${algs.join(', ')}`);
+};

package/lib/dpop/index.ts

@@ -0,0 +1,11 @@
+export { createDpopFetch } from './fetch.js';
+export { generateDpopKey } from './generate-key.js';
+export { createDpopProofSigner } from './proof.js';
+export type { DpopNonceCache, DpopPrivateJwk } from './types.js';
+export {
+	DpopVerifyError,
+	verifyDpopProof,
+	type DpopClaims,
+	type DpopVerifyOptions,
+	type DpopVerifyResult,
+} from './verify.js';

package/lib/dpop/proof.ts

@@ -0,0 +1,46 @@
+import { nanoid } from 'nanoid';
+
+import type { CachedKeyMaterial } from '../internal/key-cache.js';
+import { getCachedKeyMaterial } from '../internal/key-cache.js';
+import { signJwt } from '../jwt/index.js';
+
+import type { DpopPrivateJwk } from './types.js';
+
+/**
+ * creates a DPoP proof signer.
+ *
+ * @param jwk DPoP private JWK (with `alg` set)
+ * @returns signing function for DPoP proofs
+ */
+export const createDpopProofSigner = (
+	jwk: DpopPrivateJwk,
+): ((htm: string, htu: string, nonce?: string, ath?: string) => Promise<string>) => {
+	const alg = jwk.alg;
+
+	// lazily resolve key material on first sign
+	let materialPromise: Promise<CachedKeyMaterial> | undefined;
+
+	return async (htm: string, htu: string, nonce?: string, ath?: string) => {
+		materialPromise ||= getCachedKeyMaterial(jwk);
+		const { cryptoKey, publicJwk } = await materialPromise;
+
+		const now = Math.floor(Date.now() / 1_000);
+
+		return signJwt({
+			header: {
+				typ: 'dpop+jwt',
+				jwk: publicJwk,
+			},
+			payload: {
+				htm,
+				htu,
+				iat: now,
+				jti: nanoid(24),
+				nonce,
+				ath,
+			},
+			key: cryptoKey,
+			alg,
+		});
+	};
+};

package/lib/dpop/types.ts

@@ -0,0 +1,19 @@
+import type { PrivateJwk, SigningAlgorithm } from '../jwk/types.js';
+
+export type Awaitable<T> = T | Promise<T>;
+
+/**
+ * private JWK for DPoP proofs.
+ */
+export type DpopPrivateJwk = PrivateJwk & {
+	alg: SigningAlgorithm;
+	kid?: string;
+};
+
+/**
+ * nonce cache for DPoP fetch.
+ */
+export interface DpopNonceCache {
+	get(key: string): Awaitable<string | undefined>;
+	set(key: string, value: string): Awaitable<void>;
+}