@atcute/oauth-keyset 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2025 Mary
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @atcute/oauth-keyset
+
+keyset management for AT Protocol OAuth.
+
+```sh
+npm install @atcute/oauth-keyset
+```
+
+## usage
+
+### generating keys
+
+```ts
+import { generateClientAssertionKey } from '@atcute/oauth-crypto';
+import { Keyset } from '@atcute/oauth-keyset';
+
+// generate a new ES256 key
+const key = await generateClientAssertionKey('my-key-id');
+
+// create a keyset with the key
+const keyset = new Keyset([key]);
+```
+
+### using JWKs directly
+
+```ts
+import type { ClientAssertionPrivateJwk } from '@atcute/oauth-crypto';
+import { Keyset } from '@atcute/oauth-keyset';
+
+// JWKs can be used directly - no import step needed
+const jwk: ClientAssertionPrivateJwk = {
+	kty: 'EC',
+	crv: 'P-256',
+	kid: 'my-key',
+	alg: 'ES256',
+	// ... private key parameters (x, y, d)
+};
+
+const keyset = new Keyset([jwk]);
+```
+
+### importing from PKCS#8
+
+```ts
+import { importClientAssertionPkcs8 } from '@atcute/oauth-crypto';
+import { Keyset } from '@atcute/oauth-keyset';
+
+// import from PKCS#8 PEM - returns a JWK
+const jwk = await importClientAssertionPkcs8(pemString, {
+	kid: 'my-key',
+	alg: 'ES256',
+});
+
+const keyset = new Keyset([jwk]);
+```
+
+### using the keyset
+
+```ts
+// get public JWKS (for serving at jwks_uri)
+const jwks = keyset.publicJwks;
+
+// find a key by criteria
+const key = keyset.find({ kid: 'my-key' });
+const key = keyset.find({ alg: 'ES256' });
+
+// find a key for signing with server negotiation
+const { key, alg } = keyset.findForSigning(['ES256', 'ES384']);
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Keyset } from './keyset.js';
+export type { KeySearchOptions } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Keyset } from './keyset.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/keyset.d.ts

@@ -0,0 +1,59 @@
+import type { ClientAssertionPrivateJwk, PublicJwk } from '@atcute/oauth-crypto';
+import type { KeySearchOptions } from './types.js';
+/**
+ * a collection of private keys for client authentication.
+ */
+export declare class Keyset {
+    private readonly keys;
+    private _publicJwks;
+    /**
+     * creates a new keyset from an array of private JWKs.
+     *
+     * @param keys array of private JWKs (at least one required, each with `kid` and `alg` set)
+     * @throws if keyset is empty or contains duplicate key IDs
+     */
+    constructor(keys: ClientAssertionPrivateJwk[]);
+    /** number of keys in the keyset */
+    get size(): number;
+    /**
+     * public JWKS for serving at client metadata or jwks_uri.
+     * derived lazily on first access, then cached.
+     */
+    get publicJwks(): {
+        keys: readonly PublicJwk[];
+    };
+    /**
+     * finds the first key matching the given criteria.
+     *
+     * @param options search criteria (kid and/or alg)
+     * @returns matching key or undefined
+     */
+    find(options?: KeySearchOptions): ClientAssertionPrivateJwk | undefined;
+    /**
+     * gets a key matching the given criteria.
+     *
+     * @param options search criteria (kid and/or alg)
+     * @returns matching key
+     * @throws if no matching key is found
+     */
+    get(options?: KeySearchOptions): ClientAssertionPrivateJwk;
+    /**
+     * iterates over keys matching the given criteria, in preference order.
+     *
+     * @param options search criteria (kid and/or alg)
+     */
+    list(options?: KeySearchOptions): Generator<ClientAssertionPrivateJwk>;
+    /**
+     * finds a key for signing, negotiating algorithm with server's supported list.
+     *
+     * @param serverAlgs algorithms supported by the server (from metadata)
+     * @returns key and negotiated algorithm
+     * @throws if no compatible key is found
+     */
+    findForSigning(serverAlgs?: readonly string[]): {
+        key: ClientAssertionPrivateJwk;
+        alg: string;
+    };
+    [Symbol.iterator](): Iterator<ClientAssertionPrivateJwk>;
+}
+//# sourceMappingURL=keyset.d.ts.map

package/dist/keyset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyset.d.ts","sourceRoot":"","sources":["../lib/keyset.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAkBnD;;GAEG;AACH,qBAAa,MAAM;IAClB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuC;IAC5D,OAAO,CAAC,WAAW,CAA6C;IAEhE;;;;;OAKG;IACH,YAAY,IAAI,EAAE,yBAAyB,EAAE,EAe5C;IAED,mCAAmC;IACnC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,IAAI,UAAU,IAAI;QAAE,IAAI,EAAE,SAAS,SAAS,EAAE,CAAA;KAAE,CAG/C;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,yBAAyB,GAAG,SAAS,CAKtE;IAED;;;;;;OAMG;IACH,GAAG,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,yBAAyB,CAOzD;IAED;;;;OAIG;IACF,IAAI,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC,yBAAyB,CAAC,CAoBtE;IAED;;;;;;OAMG;IACH,cAAc,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG;QAAE,GAAG,EAAE,yBAAyB,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAU9F;IAED,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,yBAAyB,CAAC,CAEvD;CACD"}

package/dist/keyset.js

@@ -0,0 +1,126 @@
+import { derivePublicJwk } from '@atcute/oauth-crypto';
+/**
+ * preferred algorithm order for signing.
+ * EC algorithms first (smaller, faster), then PSS, then PKCS#1 v1.5.
+ */
+const PREFERRED_ALGORITHMS = [
+    'ES256',
+    'ES384',
+    'ES512',
+    'PS256',
+    'PS384',
+    'PS512',
+    'RS256',
+    'RS384',
+    'RS512',
+];
+/**
+ * a collection of private keys for client authentication.
+ */
+export class Keyset {
+    keys;
+    _publicJwks;
+    /**
+     * creates a new keyset from an array of private JWKs.
+     *
+     * @param keys array of private JWKs (at least one required, each with `kid` and `alg` set)
+     * @throws if keyset is empty or contains duplicate key IDs
+     */
+    constructor(keys) {
+        if (keys.length === 0) {
+            throw new Error(`keyset must contain at least one key`);
+        }
+        // check for duplicate kids
+        const kids = new Set();
+        for (const key of keys) {
+            if (kids.has(key.kid)) {
+                throw new Error(`duplicate key ID: ${key.kid}`);
+            }
+            kids.add(key.kid);
+        }
+        this.keys = Object.freeze([...keys]);
+    }
+    /** number of keys in the keyset */
+    get size() {
+        return this.keys.length;
+    }
+    /**
+     * public JWKS for serving at client metadata or jwks_uri.
+     * derived lazily on first access, then cached.
+     */
+    get publicJwks() {
+        this._publicJwks ||= { keys: this.keys.map((k) => derivePublicJwk(k, k.kid, k.alg)) };
+        return this._publicJwks;
+    }
+    /**
+     * finds the first key matching the given criteria.
+     *
+     * @param options search criteria (kid and/or alg)
+     * @returns matching key or undefined
+     */
+    find(options) {
+        for (const key of this.list(options)) {
+            return key;
+        }
+        return undefined;
+    }
+    /**
+     * gets a key matching the given criteria.
+     *
+     * @param options search criteria (kid and/or alg)
+     * @returns matching key
+     * @throws if no matching key is found
+     */
+    get(options) {
+        const key = this.find(options);
+        if (!key) {
+            const desc = options?.kid ?? options?.alg ?? 'any';
+            throw new Error(`no key found matching: ${desc}`);
+        }
+        return key;
+    }
+    /**
+     * iterates over keys matching the given criteria, in preference order.
+     *
+     * @param options search criteria (kid and/or alg)
+     */
+    *list(options) {
+        const { kid, alg } = options ?? {};
+        const algSet = alg == null ? null : new Set(Array.isArray(alg) ? alg : [alg]);
+        // sort keys by algorithm preference
+        const sorted = [...this.keys].sort((a, b) => {
+            const aIdx = PREFERRED_ALGORITHMS.indexOf(a.alg);
+            const bIdx = PREFERRED_ALGORITHMS.indexOf(b.alg);
+            return aIdx - bIdx;
+        });
+        for (const key of sorted) {
+            if (kid != null && key.kid !== kid) {
+                continue;
+            }
+            if (algSet != null && !algSet.has(key.alg)) {
+                continue;
+            }
+            yield key;
+        }
+    }
+    /**
+     * finds a key for signing, negotiating algorithm with server's supported list.
+     *
+     * @param serverAlgs algorithms supported by the server (from metadata)
+     * @returns key and negotiated algorithm
+     * @throws if no compatible key is found
+     */
+    findForSigning(serverAlgs) {
+        // if server doesn't specify, default to ES256 per atproto spec
+        const algs = serverAlgs ?? ['ES256'];
+        const key = this.find({ alg: algs });
+        if (!key) {
+            throw new Error(`no key found compatible with server algorithms: ${algs.join(', ')}`);
+        }
+        return { key, alg: key.alg };
+    }
+    [Symbol.iterator]() {
+        return this.keys[Symbol.iterator]();
+    }
+}
+//# sourceMappingURL=keyset.js.map

package/dist/keyset.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+/** criteria for finding a key in a keyset */
+export interface KeySearchOptions {
+    /** find by specific key ID */
+    kid?: string;
+    /** find by algorithm (single or array of acceptable algs) */
+    alg?: string | readonly string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAChC,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;CACjC"}

package/dist/types.js

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

package/dist/types.js.map

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

package/lib/index.ts

@@ -0,0 +1,2 @@
+export { Keyset } from './keyset.js';
+export type { KeySearchOptions } from './types.js';

package/lib/keyset.ts

@@ -0,0 +1,144 @@
+import type { ClientAssertionPrivateJwk, PublicJwk } from '@atcute/oauth-crypto';
+import { derivePublicJwk } from '@atcute/oauth-crypto';
+
+import type { KeySearchOptions } from './types.js';
+
+/**
+ * preferred algorithm order for signing.
+ * EC algorithms first (smaller, faster), then PSS, then PKCS#1 v1.5.
+ */
+const PREFERRED_ALGORITHMS = [
+	'ES256',
+	'ES384',
+	'ES512',
+	'PS256',
+	'PS384',
+	'PS512',
+	'RS256',
+	'RS384',
+	'RS512',
+] as const;
+
+/**
+ * a collection of private keys for client authentication.
+ */
+export class Keyset {
+	private readonly keys: readonly ClientAssertionPrivateJwk[];
+	private _publicJwks: { keys: readonly PublicJwk[] } | undefined;
+
+	/**
+	 * creates a new keyset from an array of private JWKs.
+	 *
+	 * @param keys array of private JWKs (at least one required, each with `kid` and `alg` set)
+	 * @throws if keyset is empty or contains duplicate key IDs
+	 */
+	constructor(keys: ClientAssertionPrivateJwk[]) {
+		if (keys.length === 0) {
+			throw new Error(`keyset must contain at least one key`);
+		}
+
+		// check for duplicate kids
+		const kids = new Set<string>();
+		for (const key of keys) {
+			if (kids.has(key.kid)) {
+				throw new Error(`duplicate key ID: ${key.kid}`);
+			}
+			kids.add(key.kid);
+		}
+
+		this.keys = Object.freeze([...keys]);
+	}
+
+	/** number of keys in the keyset */
+	get size(): number {
+		return this.keys.length;
+	}
+
+	/**
+	 * public JWKS for serving at client metadata or jwks_uri.
+	 * derived lazily on first access, then cached.
+	 */
+	get publicJwks(): { keys: readonly PublicJwk[] } {
+		this._publicJwks ||= { keys: this.keys.map((k) => derivePublicJwk(k, k.kid, k.alg)) };
+		return this._publicJwks;
+	}
+
+	/**
+	 * finds the first key matching the given criteria.
+	 *
+	 * @param options search criteria (kid and/or alg)
+	 * @returns matching key or undefined
+	 */
+	find(options?: KeySearchOptions): ClientAssertionPrivateJwk | undefined {
+		for (const key of this.list(options)) {
+			return key;
+		}
+		return undefined;
+	}
+
+	/**
+	 * gets a key matching the given criteria.
+	 *
+	 * @param options search criteria (kid and/or alg)
+	 * @returns matching key
+	 * @throws if no matching key is found
+	 */
+	get(options?: KeySearchOptions): ClientAssertionPrivateJwk {
+		const key = this.find(options);
+		if (!key) {
+			const desc = options?.kid ?? options?.alg ?? 'any';
+			throw new Error(`no key found matching: ${desc}`);
+		}
+		return key;
+	}
+
+	/**
+	 * iterates over keys matching the given criteria, in preference order.
+	 *
+	 * @param options search criteria (kid and/or alg)
+	 */
+	*list(options?: KeySearchOptions): Generator<ClientAssertionPrivateJwk> {
+		const { kid, alg } = options ?? {};
+		const algSet = alg == null ? null : new Set(Array.isArray(alg) ? alg : [alg]);
+
+		// sort keys by algorithm preference
+		const sorted = [...this.keys].sort((a, b) => {
+			const aIdx = PREFERRED_ALGORITHMS.indexOf(a.alg as (typeof PREFERRED_ALGORITHMS)[number]);
+			const bIdx = PREFERRED_ALGORITHMS.indexOf(b.alg as (typeof PREFERRED_ALGORITHMS)[number]);
+			return aIdx - bIdx;
+		});
+
+		for (const key of sorted) {
+			if (kid != null && key.kid !== kid) {
+				continue;
+			}
+			if (algSet != null && !algSet.has(key.alg)) {
+				continue;
+			}
+			yield key;
+		}
+	}
+
+	/**
+	 * finds a key for signing, negotiating algorithm with server's supported list.
+	 *
+	 * @param serverAlgs algorithms supported by the server (from metadata)
+	 * @returns key and negotiated algorithm
+	 * @throws if no compatible key is found
+	 */
+	findForSigning(serverAlgs?: readonly string[]): { key: ClientAssertionPrivateJwk; alg: string } {
+		// if server doesn't specify, default to ES256 per atproto spec
+		const algs = serverAlgs ?? ['ES256'];
+
+		const key = this.find({ alg: algs });
+		if (!key) {
+			throw new Error(`no key found compatible with server algorithms: ${algs.join(', ')}`);
+		}
+
+		return { key, alg: key.alg };
+	}
+
+	[Symbol.iterator](): Iterator<ClientAssertionPrivateJwk> {
+		return this.keys[Symbol.iterator]();
+	}
+}

package/lib/types.ts

@@ -0,0 +1,7 @@
+/** criteria for finding a key in a keyset */
+export interface KeySearchOptions {
+	/** find by specific key ID */
+	kid?: string;
+	/** find by algorithm (single or array of acceptable algs) */
+	alg?: string | readonly string[];
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@atcute/oauth-keyset",
+  "version": "0.1.0",
+  "description": "keyset management for AT Protocol OAuth",
+  "license": "0BSD",
+  "repository": {
+    "url": "https://github.com/mary-ext/atcute",
+    "directory": "packages/oauth/keyset"
+  },
+  "files": [
+    "dist/",
+    "lib/",
+    "!lib/**/*.bench.ts",
+    "!lib/**/*.test.ts"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@atcute/oauth-crypto": "^0.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.16"
+  },
+  "scripts": {
+    "build": "tsgo --project tsconfig.build.json",
+    "test": "vitest",
+    "prepublish": "rm -rf dist; pnpm run build"
+  }
+}