@stripe/workload-identity 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,20 @@
+Copyright (C) 2011 Ask Bjørn Hansen
+Copyright (C) 2013 Stripe, Inc. (https://stripe.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# @stripe/workload-identity
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Private preview.** This package and the Stripe workload identity API it
+> depends on are in private preview and may change.
+
+Workload identity adapter for [stripe-node](https://github.com/stripe/stripe-node).
+
+Currently, it lets an application running on AWS authenticate to Stripe without holding a
+long-lived Stripe secret key. The application proves where it is running instead
+of storing a credential.
+
+## Installation
+
+```sh
+npm install stripe @stripe/workload-identity
+```
+
+### Node.js version
+
+This package requires **Node.js 20 or newer**.
+
+```json
+{"dependencies": {"@aws-sdk/client-sts": "3.952.x"}}
+```
+
+
+## Usage
+
+```js
+import Stripe from 'stripe';
+import {awsWorkloadIdentity} from '@stripe/workload-identity';
+
+const client = Stripe.forWorkloadIdentity(
+  'oacli_live_...',
+  awsWorkloadIdentity()
+);
+
+const customers = await client.customers.list();
+```
+
+Once constructed, the client behaves like any other Stripe client: resources,
+request options, retries, idempotency, and error handling all work the same way.
+
+## What it does
+
+`awsWorkloadIdentity()` returns a provider object that Stripe's SDK calls when it
+needs a credential. On each call it asks AWS STS for a freshly signed JSON Web
+Token via `sts:GetWebIdentityToken`, using:
+
+| | |
+| --- | --- |
+| Audience | `https://access.stripe.com/wif` |
+| Signing algorithm | `ES384` |
+
+Stripe exchanges that token for a short-lived restricted key. This package never
+sees the Stripe credential — it only produces the AWS assertion.
+
+Both values can be overridden, e.g. if Stripe asks you to use a different one
+before you've upgraded to a version of this package with a new default:
+
+```js
+awsWorkloadIdentity({audience: '...', signingAlgorithm: '...'});
+```
+
+AWS region and credentials come from the AWS SDK's normal resolution. Any other
+STS client configuration can be passed through the same object:
+
+```js
+awsWorkloadIdentity({region: 'us-west-2'});
+```
+
+Note that `GetWebIdentityToken` is not available on the STS global endpoint, so a
+region must be resolvable.
+
+## Local development, tests, and CI
+
+`GetWebIdentityToken` only works on AWS infrastructure with an identity allowed to
+call it. Anywhere else — a laptop, a unit test, a CI runner that is not on AWS —
+use a normal Stripe test API key or a fully mocked Stripe client instead:
+
+```js
+const client = new Stripe(process.env.STRIPE_TEST_API_KEY);
+```
+
+## Troubleshooting
+
+| Error | What to check |
+| --- | --- |
+| `sts:GetWebIdentityToken failed (CredentialsProviderError: ...)` | The process is not running on AWS, or no credentials are resolvable. |
+| `sts:GetWebIdentityToken failed (AccessDeniedException: ...)` | The AWS identity is not allowed to call `sts:GetWebIdentityToken`. |
+| `returned no WebIdentityToken` | AWS answered without a token. Retry; if it persists, contact Stripe support. |
+| `Stripe rejected the workload identity token exchange` | The Stripe client ID is wrong or not enabled for workload identity, or the Dashboard configuration does not trust this workload. |
+
+See the [workload identity documentation](../../docs/workload-identity.md) for the
+full guide.
+
+## Releasing
+
+This package is versioned and released independently of the core `stripe` package,
+so core releases never republish it and a fix here does not require a core release.
+
+1. Bump `version` in this directory's `package.json` and merge that PR.
+2. Push a matching tag: `wif-v<version>`, e.g.
+
+   ```sh
+   git tag wif-v0.1.0-alpha.1
+   git push origin wif-v0.1.0-alpha.1
+   ```
+
+CI then builds, typechecks, tests, and publishes. The job refuses to publish if the
+tag and `package.json` versions disagree, and is a no-op if that version is already
+on npm, so re-running it is safe. An `alpha` version publishes under the
+`private-preview` dist-tag, `beta` under `public-preview`, anything else `latest`.
+
+## License
+
+MIT

package/cjs/index.d.ts

@@ -0,0 +1,40 @@
+import { STSClientConfig } from '@aws-sdk/client-sts';
+export declare const STRIPE_WORKLOAD_IDENTITY_AUDIENCE = "https://access.stripe.com/wif";
+export declare const STRIPE_WORKLOAD_IDENTITY_SIGNING_ALGORITHM = "ES384";
+/**
+ * The structural contract the Stripe SDK consumes. It is duplicated here rather
+ * than imported so that this package does not depend on `stripe`, and `stripe`
+ * does not depend on the AWS SDK.
+ */
+export interface WorkloadIdentityProvider {
+    readonly provider: 'aws';
+    getIdentityAssertion(): Promise<string>;
+}
+/** Raised when AWS would not produce a usable workload identity assertion. */
+export declare class AwsWorkloadIdentityError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+export interface AwsWorkloadIdentityConfig extends STSClientConfig {
+    /**
+     * Overrides the JWT audience requested from AWS STS. Defaults to
+     * `STRIPE_WORKLOAD_IDENTITY_AUDIENCE`. Only set this if Stripe has told you
+     * to use a different value -- an audience Stripe does not expect will cause
+     * every token exchange to be rejected.
+     */
+    audience?: string;
+    /**
+     * Overrides the JWT signing algorithm requested from AWS STS. Defaults to
+     * `STRIPE_WORKLOAD_IDENTITY_SIGNING_ALGORITHM`. Only set this if Stripe has
+     * told you to use a different value.
+     */
+    signingAlgorithm?: string;
+}
+/**
+ * Builds the AWS workload identity provider for `Stripe.forWorkloadIdentity`.
+ *
+ * Each call to `getIdentityAssertion()` asks AWS STS for a freshly signed JWT
+ * that proves the calling AWS identity. Stripe exchanges that assertion for a
+ * short-lived restricted key; this package never sees the Stripe credential.
+ *
+ */
+export declare function awsWorkloadIdentity(config?: AwsWorkloadIdentityConfig): WorkloadIdentityProvider;

package/cjs/index.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AwsWorkloadIdentityError = exports.STRIPE_WORKLOAD_IDENTITY_SIGNING_ALGORITHM = exports.STRIPE_WORKLOAD_IDENTITY_AUDIENCE = void 0;
+exports.awsWorkloadIdentity = awsWorkloadIdentity;
+const client_sts_1 = require("@aws-sdk/client-sts");
+exports.STRIPE_WORKLOAD_IDENTITY_AUDIENCE = 'https://access.stripe.com/wif';
+exports.STRIPE_WORKLOAD_IDENTITY_SIGNING_ALGORITHM = 'ES384';
+/** Raised when AWS would not produce a usable workload identity assertion. */
+class AwsWorkloadIdentityError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = 'AwsWorkloadIdentityError';
+        this.cause = cause;
+    }
+}
+exports.AwsWorkloadIdentityError = AwsWorkloadIdentityError;
+const SETUP_GUIDANCE = 'Check that the process is running on AWS infrastructure with an identity that is allowed to call ' +
+    'sts:GetWebIdentityToken, and that a region is configured (the operation is not available on the STS global endpoint). ' +
+    'For local development, unit tests, and CI that are not running on AWS, use a normal Stripe test API key with ' +
+    '`new Stripe(apiKey)` or a fully mocked Stripe client instead.';
+/**
+ * Builds the AWS workload identity provider for `Stripe.forWorkloadIdentity`.
+ *
+ * Each call to `getIdentityAssertion()` asks AWS STS for a freshly signed JWT
+ * that proves the calling AWS identity. Stripe exchanges that assertion for a
+ * short-lived restricted key; this package never sees the Stripe credential.
+ *
+ */
+function awsWorkloadIdentity(config = {}) {
+    const { audience = exports.STRIPE_WORKLOAD_IDENTITY_AUDIENCE, signingAlgorithm = exports.STRIPE_WORKLOAD_IDENTITY_SIGNING_ALGORITHM, ...stsClientConfig } = config;
+    const client = new client_sts_1.STSClient(stsClientConfig);
+    return {
+        provider: 'aws',
+        async getIdentityAssertion() {
+            let response;
+            try {
+                response = await client.send(new client_sts_1.GetWebIdentityTokenCommand({
+                    Audience: [audience],
+                    SigningAlgorithm: signingAlgorithm,
+                }));
+            }
+            catch (err) {
+                throw new AwsWorkloadIdentityError(`Unable to obtain an AWS workload identity assertion: sts:GetWebIdentityToken failed. ${SETUP_GUIDANCE}`, err);
+            }
+            const token = response?.WebIdentityToken;
+            if (typeof token !== 'string' || !token) {
+                throw new AwsWorkloadIdentityError('Unable to obtain an AWS workload identity assertion: sts:GetWebIdentityToken returned no WebIdentityToken. ' +
+                    SETUP_GUIDANCE);
+            }
+            return token;
+        },
+    };
+}

package/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/esm/index.d.ts

@@ -0,0 +1,40 @@
+import { STSClientConfig } from '@aws-sdk/client-sts';
+export declare const STRIPE_WORKLOAD_IDENTITY_AUDIENCE = "https://access.stripe.com/wif";
+export declare const STRIPE_WORKLOAD_IDENTITY_SIGNING_ALGORITHM = "ES384";
+/**
+ * The structural contract the Stripe SDK consumes. It is duplicated here rather
+ * than imported so that this package does not depend on `stripe`, and `stripe`
+ * does not depend on the AWS SDK.
+ */
+export interface WorkloadIdentityProvider {
+    readonly provider: 'aws';
+    getIdentityAssertion(): Promise<string>;
+}
+/** Raised when AWS would not produce a usable workload identity assertion. */
+export declare class AwsWorkloadIdentityError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+export interface AwsWorkloadIdentityConfig extends STSClientConfig {
+    /**
+     * Overrides the JWT audience requested from AWS STS. Defaults to
+     * `STRIPE_WORKLOAD_IDENTITY_AUDIENCE`. Only set this if Stripe has told you
+     * to use a different value -- an audience Stripe does not expect will cause
+     * every token exchange to be rejected.
+     */
+    audience?: string;
+    /**
+     * Overrides the JWT signing algorithm requested from AWS STS. Defaults to
+     * `STRIPE_WORKLOAD_IDENTITY_SIGNING_ALGORITHM`. Only set this if Stripe has
+     * told you to use a different value.
+     */
+    signingAlgorithm?: string;
+}
+/**
+ * Builds the AWS workload identity provider for `Stripe.forWorkloadIdentity`.
+ *
+ * Each call to `getIdentityAssertion()` asks AWS STS for a freshly signed JWT
+ * that proves the calling AWS identity. Stripe exchanges that assertion for a
+ * short-lived restricted key; this package never sees the Stripe credential.
+ *
+ */
+export declare function awsWorkloadIdentity(config?: AwsWorkloadIdentityConfig): WorkloadIdentityProvider;

package/esm/index.js

@@ -0,0 +1,48 @@
+import { GetWebIdentityTokenCommand, STSClient, } from '@aws-sdk/client-sts';
+export const STRIPE_WORKLOAD_IDENTITY_AUDIENCE = 'https://access.stripe.com/wif';
+export const STRIPE_WORKLOAD_IDENTITY_SIGNING_ALGORITHM = 'ES384';
+/** Raised when AWS would not produce a usable workload identity assertion. */
+export class AwsWorkloadIdentityError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = 'AwsWorkloadIdentityError';
+        this.cause = cause;
+    }
+}
+const SETUP_GUIDANCE = 'Check that the process is running on AWS infrastructure with an identity that is allowed to call ' +
+    'sts:GetWebIdentityToken, and that a region is configured (the operation is not available on the STS global endpoint). ' +
+    'For local development, unit tests, and CI that are not running on AWS, use a normal Stripe test API key with ' +
+    '`new Stripe(apiKey)` or a fully mocked Stripe client instead.';
+/**
+ * Builds the AWS workload identity provider for `Stripe.forWorkloadIdentity`.
+ *
+ * Each call to `getIdentityAssertion()` asks AWS STS for a freshly signed JWT
+ * that proves the calling AWS identity. Stripe exchanges that assertion for a
+ * short-lived restricted key; this package never sees the Stripe credential.
+ *
+ */
+export function awsWorkloadIdentity(config = {}) {
+    const { audience = STRIPE_WORKLOAD_IDENTITY_AUDIENCE, signingAlgorithm = STRIPE_WORKLOAD_IDENTITY_SIGNING_ALGORITHM, ...stsClientConfig } = config;
+    const client = new STSClient(stsClientConfig);
+    return {
+        provider: 'aws',
+        async getIdentityAssertion() {
+            let response;
+            try {
+                response = await client.send(new GetWebIdentityTokenCommand({
+                    Audience: [audience],
+                    SigningAlgorithm: signingAlgorithm,
+                }));
+            }
+            catch (err) {
+                throw new AwsWorkloadIdentityError(`Unable to obtain an AWS workload identity assertion: sts:GetWebIdentityToken failed. ${SETUP_GUIDANCE}`, err);
+            }
+            const token = response?.WebIdentityToken;
+            if (typeof token !== 'string' || !token) {
+                throw new AwsWorkloadIdentityError('Unable to obtain an AWS workload identity assertion: sts:GetWebIdentityToken returned no WebIdentityToken. ' +
+                    SETUP_GUIDANCE);
+            }
+            return token;
+        },
+    };
+}

package/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@stripe/workload-identity",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.1",
+  "description": "AWS workload identity adapter for the Stripe Node.js SDK",
+  "keywords": [
+    "stripe",
+    "workload identity",
+    "aws",
+    "authentication"
+  ],
+  "homepage": "https://github.com/stripe/stripe-node/tree/master/packages/workload-identity",
+  "author": "Stripe <support@stripe.com> (https://stripe.com/)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stripe/stripe-node",
+    "directory": "packages/workload-identity"
+  },
+  "bugs": "https://github.com/stripe/stripe-node/issues",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "cjs/index.js",
+  "module": "esm/index.js",
+  "types": "cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./esm/index.d.ts",
+        "default": "./esm/index.js"
+      },
+      "require": {
+        "types": "./cjs/index.d.ts",
+        "default": "./cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "cjs/**/*",
+    "esm/**/*",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-sts": "^3.952.0"
+  },
+  "devDependencies": {
+    "@types/chai": "^4.3.4",
+    "@types/mocha": "^10.0.1",
+    "@types/node": "~22",
+    "chai": "^4.3.6",
+    "chai-as-promised": "~7.1.1",
+    "mocha": "^8.4.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "clean": "node -e \"for (const d of ['cjs','esm']) require('fs').rmSync(d, {recursive: true, force: true})\"",
+    "build": "npm run clean && npm run build:cjs && npm run build:esm",
+    "build:cjs": "tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('cjs/package.json', JSON.stringify({type:'commonjs'}))\"",
+    "build:esm": "tsc -p tsconfig.esm.json && node -e \"require('fs').writeFileSync('esm/package.json', JSON.stringify({type:'module'}))\"",
+    "typecheck": "tsc -p tsconfig.cjs.json --noEmit",
+    "test": "mocha",
+    "prepack": "npm run build"
+  }
 }