@vercel/kms 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @vercel/kms
 
+## 0.2.0
+
+### Minor Changes
+
+- b6ef92b: `signMessage` now returns `{ signature, keyId, algorithm }` instead of a Flattened JWS, with `signature` as a `Uint8Array`.
+
+### Patch Changes
+
+- @vercel/oidc@3.8.8
+
+## 0.1.3
+
+### Patch Changes
+
+- @vercel/oidc@3.8.7
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -28,8 +28,8 @@ const token = await signToken({
 import { signMessage } from '@vercel/kms';
 
 // `message` is a UTF-8 string or raw bytes (Uint8Array); it is base64-encoded
-// internally. Returns a JOSE Flattened JWS.
-const signature = await signMessage({
+// internally. Returns `{ signature, keyId, algorithm }`.
+const { signature, keyId, algorithm } = await signMessage({
   issuerId: 'issuer_abc123',
   message: 'hello world',
 });
@@ -77,4 +77,4 @@ Signs a message for an issuer.
 - `region?: string` — Region for the regional KMS API host, e.g. `sfo1`, producing `https://api-<region>.vercel.com/v1`. Defaults to the `VERCEL_REGION` environment variable, falling back to `https://api.vercel.com/v1`. Ignored when `baseUrl` is set.
 - `baseUrl?: string` — Override the API base URL. Takes precedence over `region`.
 
-Returns `Promise<FlattenedJWS>` — the JOSE Flattened JWS.
+Returns `Promise<{ signature: Uint8Array, keyId: string, algorithm: string }>` — the raw signature bytes, plus the key id and algorithm of the signing key.

package/dist/index.d.ts

@@ -1,4 +1,3 @@
 export { signToken, type SignTokenOptions } from './sign-token';
-export { signMessage, type SignMessageOptions } from './sign-message';
+export { signMessage, type SignMessageOptions, type SignMessageResult, } from './sign-message';
 export { VercelKmsError } from './errors';
-export type { FlattenedJWS } from './request';

package/dist/request.d.ts

@@ -14,21 +14,6 @@ export declare function resolveBaseUrl({ region, baseUrl, }: {
     region?: string;
     baseUrl?: string;
 }): string;
-/**
- * A JOSE Flattened JWS, as returned by the message-signing endpoint.
- *
- * @see https://datatracker.ietf.org/doc/html/rfc7515#section-7.2.2
- */
-export interface FlattenedJWS {
-    /** Base64url-encoded JWS payload. */
-    payload: string;
-    /** Base64url-encoded JWS signature. */
-    signature: string;
-    /** Base64url-encoded protected header. */
-    protected?: string;
-    /** Optional unprotected JWS header. */
-    header?: Record<string, unknown>;
-}
 /**
  * Performs an authenticated POST to a Vercel KMS sign endpoint and returns the
  * parsed JSON body. Throws {@link VercelKmsError} on a non-2xx response.

package/dist/sign-message.d.ts

@@ -1,4 +1,3 @@
-import { type FlattenedJWS } from './request';
 /**
  * Options for {@link signMessage}.
  */
@@ -29,11 +28,23 @@ export interface SignMessageOptions {
      */
     baseUrl?: string;
 }
+/**
+ * Result of {@link signMessage}.
+ */
+export interface SignMessageResult {
+    /** Raw signature over the message bytes. */
+    signature: Uint8Array;
+    /** Key id of the signing key. Matches the JWKS `kid`. */
+    keyId: string;
+    /** Algorithm of the signing key. */
+    algorithm: string;
+}
 /**
  * Signs a message for an issuer using its managed signing key and returns the
- * resulting JOSE Flattened JWS. The message may be provided as raw bytes
+ * raw signature over the message bytes, plus the `keyId` and `algorithm` of
+ * the key that produced it. The message may be provided as raw bytes
  * (`Uint8Array`) or a UTF-8 `string`; it is base64-encoded before being sent.
  *
  * @throws {import('./errors').VercelKmsError} If the sign request fails.
  */
-export declare function signMessage(options: SignMessageOptions): Promise<FlattenedJWS>;
+export declare function signMessage(options: SignMessageOptions): Promise<SignMessageResult>;

package/dist/sign-message.js

@@ -30,17 +30,20 @@ async function signMessage(options) {
     baseUrl: options.baseUrl
   });
   const oidcToken = await (0, import_resolve_token.resolveOidcToken)({ token });
-  const { signature } = await (0, import_request.postJson)({
+  const { signature, keyId, algorithm } = await (0, import_request.postJson)({
     baseUrl,
     path: `/kms/issuers/${encodeURIComponent(issuerId)}/sign/message`,
     token: oidcToken,
     body: { message: toBase64(message) }
   });
-  return signature;
+  return { signature: fromBase64(signature), keyId, algorithm };
 }
 function toBase64(message) {
   return (typeof message === "string" ? Buffer.from(message, "utf-8") : Buffer.from(message)).toString("base64");
 }
+function fromBase64(value) {
+  return new Uint8Array(Buffer.from(value, "base64"));
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   signMessage

package/dist/sign-message.test.js

@@ -7,10 +7,22 @@ import_vitest.vi.mock("@vercel/oidc", () => ({
 }));
 const getVercelOidcTokenMock = import_vitest.vi.mocked(import_oidc.getVercelOidcToken);
 const OIDC_TOKEN = "oidc-token";
-const SIGNATURE = {
-  payload: "cGF5bG9hZA",
-  signature: "c2ln",
-  protected: "cHJvdGVjdGVk"
+const SIGNATURE_B64 = "c2lnbmF0dXJl";
+const SIGNATURE_BYTES = new Uint8Array([
+  115,
+  105,
+  103,
+  110,
+  97,
+  116,
+  117,
+  114,
+  101
+]);
+const SIGNED_MESSAGE = {
+  signature: SIGNATURE_B64,
+  keyId: "key_a",
+  algorithm: "EdDSA"
 };
 function fetchReturning(body, init) {
   return async () => new Response(JSON.stringify(body), { status: 200, ...init });
@@ -21,14 +33,18 @@ function fetchReturning(body, init) {
     getVercelOidcTokenMock.mockReset();
     delete process.env.VERCEL_REGION;
   });
-  (0, import_vitest.test)("signs a string message (UTF-8) and returns the flattened JWS", async () => {
+  (0, import_vitest.test)("signs a string message (UTF-8) and returns the raw signature", async () => {
     getVercelOidcTokenMock.mockResolvedValue(OIDC_TOKEN);
-    const fetchMock = import_vitest.vi.spyOn(globalThis, "fetch").mockImplementation(fetchReturning({ signature: SIGNATURE }));
+    const fetchMock = import_vitest.vi.spyOn(globalThis, "fetch").mockImplementation(fetchReturning(SIGNED_MESSAGE));
     const result = await (0, import_sign_message.signMessage)({
       issuerId: "issuer_a",
       message: "hello"
     });
-    (0, import_vitest.expect)(result).toEqual(SIGNATURE);
+    (0, import_vitest.expect)(result).toEqual({
+      signature: SIGNATURE_BYTES,
+      keyId: "key_a",
+      algorithm: "EdDSA"
+    });
     (0, import_vitest.expect)(getVercelOidcTokenMock).toHaveBeenCalledWith();
     const [url, init] = fetchMock.mock.calls[0];
     (0, import_vitest.expect)(url.toString()).toBe(
@@ -38,7 +54,7 @@ function fetchReturning(body, init) {
   });
   (0, import_vitest.test)("base64-encodes a Uint8Array message before sending", async () => {
     getVercelOidcTokenMock.mockResolvedValue(OIDC_TOKEN);
-    const fetchMock = import_vitest.vi.spyOn(globalThis, "fetch").mockImplementation(fetchReturning({ signature: SIGNATURE }));
+    const fetchMock = import_vitest.vi.spyOn(globalThis, "fetch").mockImplementation(fetchReturning(SIGNED_MESSAGE));
     await (0, import_sign_message.signMessage)({
       issuerId: "issuer_bytes",
       // Raw bytes for "hello".
@@ -49,7 +65,7 @@ function fetchReturning(body, init) {
   });
   (0, import_vitest.test)("targets the regional host when a region is provided", async () => {
     getVercelOidcTokenMock.mockResolvedValue(OIDC_TOKEN);
-    const fetchMock = import_vitest.vi.spyOn(globalThis, "fetch").mockImplementation(fetchReturning({ signature: SIGNATURE }));
+    const fetchMock = import_vitest.vi.spyOn(globalThis, "fetch").mockImplementation(fetchReturning(SIGNED_MESSAGE));
     await (0, import_sign_message.signMessage)({
       issuerId: "issuer_region",
       message: "bXNn",
@@ -61,7 +77,7 @@ function fetchReturning(body, init) {
     );
   });
   (0, import_vitest.test)("uses an explicit token without fetching an OIDC token", async () => {
-    const fetchMock = import_vitest.vi.spyOn(globalThis, "fetch").mockImplementation(fetchReturning({ signature: SIGNATURE }));
+    const fetchMock = import_vitest.vi.spyOn(globalThis, "fetch").mockImplementation(fetchReturning(SIGNED_MESSAGE));
     await (0, import_sign_message.signMessage)({
       issuerId: "issuer_explicit",
       message: "bXNn",

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "0.1.2";
+export declare const version = "0.2.0";

package/dist/version.js

@@ -21,7 +21,7 @@ __export(version_exports, {
   version: () => version
 });
 module.exports = __toCommonJS(version_exports);
-const version = "0.1.2";
+const version = "0.2.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   version

package/docs/README.md

@@ -10,8 +10,8 @@
 
 ## Interfaces
 
-- [FlattenedJWS](interfaces/FlattenedJWS.md)
 - [SignMessageOptions](interfaces/SignMessageOptions.md)
+- [SignMessageResult](interfaces/SignMessageResult.md)
 - [SignTokenOptions](interfaces/SignTokenOptions.md)
 
 ## Functions

package/docs/functions/signMessage.md

@@ -4,12 +4,13 @@
 
 # Function: signMessage()
 
-> **signMessage**(`options`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`FlattenedJWS`](../interfaces/FlattenedJWS.md)\>
+> **signMessage**(`options`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`SignMessageResult`](../interfaces/SignMessageResult.md)\>
 
-Defined in: [packages/kms/src/sign-message.ts:42](https://github.com/vercel/vercel-internal/blob/main/packages/kms/src/sign-message.ts#L42)
+Defined in: [packages/kms/src/sign-message.ts:55](https://github.com/vercel/vercel-internal/blob/main/packages/kms/src/sign-message.ts#L55)
 
 Signs a message for an issuer using its managed signing key and returns the
-resulting JOSE Flattened JWS. The message may be provided as raw bytes
+raw signature over the message bytes, plus the `keyId` and `algorithm` of
+the key that produced it. The message may be provided as raw bytes
 (`Uint8Array`) or a UTF-8 `string`; it is base64-encoded before being sent.
 
 ## Parameters
@@ -20,7 +21,7 @@ resulting JOSE Flattened JWS. The message may be provided as raw bytes
 
 ## Returns
 
-[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`FlattenedJWS`](../interfaces/FlattenedJWS.md)\>
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`SignMessageResult`](../interfaces/SignMessageResult.md)\>
 
 ## Throws
 

package/docs/interfaces/SignMessageResult.md

@@ -0,0 +1,39 @@
+[**@vercel/kms**](../README.md)
+
+---
+
+# Interface: SignMessageResult
+
+Defined in: [packages/kms/src/sign-message.ts:38](https://github.com/vercel/vercel-internal/blob/main/packages/kms/src/sign-message.ts#L38)
+
+Result of [signMessage](../functions/signMessage.md).
+
+## Properties
+
+### algorithm
+
+> **algorithm**: `string`
+
+Defined in: [packages/kms/src/sign-message.ts:44](https://github.com/vercel/vercel-internal/blob/main/packages/kms/src/sign-message.ts#L44)
+
+Algorithm of the signing key.
+
+---
+
+### keyId
+
+> **keyId**: `string`
+
+Defined in: [packages/kms/src/sign-message.ts:42](https://github.com/vercel/vercel-internal/blob/main/packages/kms/src/sign-message.ts#L42)
+
+Key id of the signing key. Matches the JWKS `kid`.
+
+---
+
+### signature
+
+> **signature**: [`Uint8Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)
+
+Defined in: [packages/kms/src/sign-message.ts:40](https://github.com/vercel/vercel-internal/blob/main/packages/kms/src/sign-message.ts#L40)
+
+Raw signature over the message bytes.

package/package.json

@@ -14,7 +14,7 @@
       "require": "./dist/index.js"
     }
   },
-  "version": "0.1.2",
+  "version": "0.2.0",
   "repository": {
     "directory": "packages/kms",
     "type": "git",
@@ -24,7 +24,7 @@
     "url": "https://github.com/vercel/vercel/issues"
   },
   "dependencies": {
-    "@vercel/oidc": "3.8.6"
+    "@vercel/oidc": "3.8.8"
   },
   "devDependencies": {
     "prettier": "3.8.3",

package/docs/interfaces/FlattenedJWS.md

@@ -1,53 +0,0 @@
-[**@vercel/kms**](../README.md)
-
----
-
-# Interface: FlattenedJWS
-
-Defined in: [packages/kms/src/request.ts:36](https://github.com/vercel/vercel-internal/blob/main/packages/kms/src/request.ts#L36)
-
-A JOSE Flattened JWS, as returned by the message-signing endpoint.
-
-## See
-
-https://datatracker.ietf.org/doc/html/rfc7515#section-7.2.2
-
-## Properties
-
-### header?
-
-> `optional` **header?**: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)\<`string`, `unknown`\>
-
-Defined in: [packages/kms/src/request.ts:44](https://github.com/vercel/vercel-internal/blob/main/packages/kms/src/request.ts#L44)
-
-Optional unprotected JWS header.
-
----
-
-### payload
-
-> **payload**: `string`
-
-Defined in: [packages/kms/src/request.ts:38](https://github.com/vercel/vercel-internal/blob/main/packages/kms/src/request.ts#L38)
-
-Base64url-encoded JWS payload.
-
----
-
-### protected?
-
-> `optional` **protected?**: `string`
-
-Defined in: [packages/kms/src/request.ts:42](https://github.com/vercel/vercel-internal/blob/main/packages/kms/src/request.ts#L42)
-
-Base64url-encoded protected header.
-
----
-
-### signature
-
-> **signature**: `string`
-
-Defined in: [packages/kms/src/request.ts:40](https://github.com/vercel/vercel-internal/blob/main/packages/kms/src/request.ts#L40)
-
-Base64url-encoded JWS signature.