Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions .changeset/real-cobras-hide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
"@jeengbe/spiffe": major
---

refactor!: rework internals

**Breaking changes**

- `SpiffeClient` now takes a single `SpiffeClientOptions` object. Pass the socket or transport as `connection` and retry options as `retry`:

```diff
- new SpiffeClient('unix:///path/to/api.sock', { maxAttempts: 3 });
+ new SpiffeClient({ connection: 'unix:///path/to/api.sock', retry: { maxAttempts: 3 } });
```

- `getJwt()`, `getJwtSvid()`, `createKafkajsSaslMechanism()`, and `createKafkajsAuthMiddleware()` take an `SvidFilter` instead of a `hint` string:

```diff
- spiffe.getJwt('orders-api', 'public');
+ spiffe.getJwt('orders-api', { hint: 'public' });
```

- `getJwtSvid()` returns `null` instead of throwing `NoSvidError` when the workload has no SVID. `getJwt()` still throws.
- `ParsedJwtSvid` was removed. `getJwtSvid()` returns `JwtSvid`, which now includes `hint` and `expiresAtMs`.
- `NoSvidError` takes the `SvidFilter` that was used, exposed as `filter`, instead of an SVID type and hint.

**Features**

- Filter SVIDs by SPIFFE ID with `{ spiffeId }`.
- Pass custom caches via `jwtSvidCache` and `validatedJwtCache`, either a configured `SpiffeCacheImpl` or your own `SpiffeCache` implementation.
- Disable retries with `retry.enabled: false`.

**Fixes**

- `validateJwt()` now retries while the Workload API is unavailable.
- Fetched JWT-SVIDs are cached for at most 60 seconds and 1,000 entries.
- `close()` now closes the connection the client opened itself. A transport passed in by the caller is left open.
- Removed the `lru-cache` dependency.
4 changes: 1 addition & 3 deletions codecov.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,7 @@ coverage:
default:
target: auto
threshold: 1%
patch:
default:
target: auto
patch: off
component_management:
default_rules:
statuses:
Expand Down
107 changes: 86 additions & 21 deletions packages/spiffe/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ SPIFFE Workload API client for Node.js, Deno, and Bun. Fetch and validate JWT-SV
`@jeengbe/spiffe` is a SPIFFE SDK for TypeScript and JavaScript. It speaks with the [SPIFFE Workload API](https://spiffe.io/docs/latest/spiffe-about/spiffe-concepts/#spiffe-workload-api) exposed by a [SPIRE](https://spiffe.io/docs/latest/spire-about/) agent.

- **Fetch JWT-SVIDs** for a given audience, with automatic caching and request deduplication.
- **Validate incoming JWT-SVIDs** on the server, with a bounded LRU cache that never outlives a token's `exp`.
- **Validate incoming JWT-SVIDs** on the server, with a bounded cache that never outlives a token's `exp`.
- **Retry with exponential backoff** while the SPIRE agent socket isn't ready or the workload isn't registered yet.
- **KafkaJS integration**: SASL `OAuthBearer` authentication and Confluent Schema Registry auth, driven by SPIFFE identity.
- **Runs on Node.js, Deno, and Bun.** Fully typed, `AsyncDisposable`, zero configuration in a standard SPIRE deployment.
Expand Down Expand Up @@ -58,25 +58,25 @@ This assumes a SPIRE agent is running on the node and its Workload API socket is

### Connecting to the Workload API

The client connects to the SPIFFE Workload API over gRPC. If no socket is provided, the client will attempt to connect to `process.env.SPIFFE_ENDPOINT_SOCKET`, or fall back to `unix:///tmp/spire-agent/public/api.sock`.
The client connects to the SPIFFE Workload API over gRPC. If no `connection` is provided, the client will attempt to connect to `process.env.SPIFFE_ENDPOINT_SOCKET`, or fall back to `unix:///tmp/spire-agent/public/api.sock`.

```ts
const spiffe = new SpiffeClient();
```

To specify a socket explicitly:
To specify a socket explicitly, pass a `unix://` or `tcp://` address:

```ts
const spiffe = new SpiffeClient('unix:///path/to/api.sock');
const spiffe = new SpiffeClient({ connection: 'unix:///path/to/api.sock' });
```

For advanced gRPC configuration (e.g. custom channel credentials), construct your own `@connectrpc/connect` `Transport` and pass it instead. Make sure to set the `workload.spiffe.io` metadata header to `'true'`, as the Workload API requires it:
For advanced gRPC configuration (e.g. custom channel credentials), construct your own `@connectrpc/connect` `Transport` and pass it as `connection` instead. Make sure to set the `workload.spiffe.io` metadata header to `'true'`, as the Workload API requires it:

```ts
import { createGrpcTransport } from '@connectrpc/connect-node';

const spiffe = new SpiffeClient(
createGrpcTransport({
const spiffe = new SpiffeClient({
connection: createGrpcTransport({
baseUrl: 'https://spire-agent.internal:8081',
interceptors: [
(next) => (req) => {
Expand All @@ -85,19 +85,32 @@ const spiffe = new SpiffeClient(
},
],
}),
);
});
```

Both forms accept an optional `SpiffeClientRetryOptions` as the last argument, to configure retries while fetching SVIDs (e.g. while the SPIRE agent socket isn't ready yet, or the workload isn't yet registered):
When you pass your own transport, the client does not own it: `close()` leaves the transport's connection open.

### Client options

The constructor takes an optional `SpiffeClientOptions` object:

```ts
const spiffe = new SpiffeClient(undefined, {
maxAttempts: 6,
initialDelayMs: 1_000,
maxDelayMs: 30_000,
const spiffe = new SpiffeClient({
retry: {
maxAttempts: 6,
initialDelayMs: 1_000,
maxDelayMs: 30_000,
},
});
```

| Option | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------- |
| `connection` | Socket address or `Transport`. See [Connecting to the Workload API](#connecting-to-the-workload-api). |
| `retry` | `SpiffeClientRetryOptions` for Workload API calls. See [Retries](#retries). |
| `jwtSvidCache` | Cache for fetched JWT-SVIDs. See [Caching and Rotation](#caching-and-rotation). |
| `validatedJwtCache` | Cache for validated JWT-SVIDs. See [Caching and Rotation](#caching-and-rotation). |

`SpiffeClient` implements `AsyncDisposable`, so you can use `await using`:

```ts
Expand All @@ -122,19 +135,28 @@ async function fetchData(url: string) {
}
```

Use `getJwtSvid()` instead to also get the SPIFFE ID and expiration time:
Use `getJwtSvid()` instead to also get the SPIFFE ID, hint, and expiration time. Unlike `getJwt()`, it returns `null` instead of throwing when the workload has no SVID:

```ts
const svid = await spiffe.getJwtSvid('orders-api');
console.log(svid.spiffeId, svid.token, svid.expiresAtMs);

if (svid) {
console.log(svid.spiffeId, svid.token, svid.hint, svid.expiresAtMs);
}
```

Both `getJwt()` and `getJwtSvid()` accept an optional `hint` parameter to select a specific SVID when the agent issues more than one:
Both `getJwt()` and `getJwtSvid()` accept an optional `SvidFilter` to select a specific SVID when the workload is entitled to more than one. Filter by the SVID's `hint`, its `spiffeId`, or both. When several SVIDs match, the first one returned by the Workload API is used:

```ts
const token = await spiffe.getJwt('orders-api', 'public');
const token = await spiffe.getJwt('orders-api', { hint: 'public' });

const svid = await spiffe.getJwtSvid('orders-api', {
spiffeId: 'spiffe://example.org/orders-client',
});
```

All methods accept an optional `AbortSignal` as the last argument.

### Validating a JWT-SVID

On the server, use `validateJwt()` to validate an incoming JWT-SVID bearer token. Returns `null` if the token is invalid.
Expand All @@ -156,13 +178,46 @@ async function authenticateRequest(req: Request) {

### Caching and Rotation

SVIDs are cached for half of their remaining TTL and concurrent requests for the same audience are deduplicated.
Fetched SVIDs are cached for half of their remaining lifetime, capped at 60 seconds, and concurrent requests for the same audience and filter are deduplicated.

Validated tokens are cached too, so a burst of requests carrying the same bearer token only hits the Workload API once. The cache is keyed by token and expected audience, and an entry never outlives the `exp` claim of its token, capped at 60 seconds. Invalid tokens are never cached.

Both caches hold at most 1,000 entries by default.

#### Custom caches

Validated tokens are cached too, so a burst of requests carrying the same bearer token only hits the Workload API once. The cache is keyed by token and expected audience, bounded in size with least-recently-used eviction, and an entry never outlives the `exp` claim of its token. Invalid tokens are never cached.
To change the limits, pass your own `SpiffeCacheImpl`:

```ts
import { SpiffeCacheImpl, SpiffeClient } from '@jeengbe/spiffe';

const spiffe = new SpiffeClient({
jwtSvidCache: new SpiffeCacheImpl({ maxEntries: 100, maxTtlMs: 30_000 }),
validatedJwtCache: new SpiffeCacheImpl({ maxEntries: 10_000 }),
});
```

### Retries

Workload API calls are retried with exponential backoff while the SPIRE agent isn't ready yet:

- `getJwt()` and `getJwtSvid()` retry on `UNAVAILABLE` (the agent socket isn't ready) and `PERMISSION_DENIED` (the workload isn't registered yet, common at pod startup). If `PERMISSION_DENIED` persists after the last attempt, the workload is treated as having no SVID.
- `validateJwt()` retries on `UNAVAILABLE` only.

Configure retries with the `retry` option:

| Option | Default | Description |
| ---------------- | -------- | ------------------------------------------------ |
| `enabled` | `true` | Set to `false` to disable retries. |
| `maxAttempts` | `6` | Maximum number of attempts, including the first. |
| `initialDelayMs` | `1_000` | Delay before the first retry. |
| `maxDelayMs` | `30_000` | Upper bound for the delay between retries. |

The delay doubles after each attempt, up to `maxDelayMs`.

### Error handling

`getJwt()` and `getJwtSvid()` throw `NoSvidError` when the Workload API returns no SVIDs:
`getJwt()` throws `NoSvidError` when the Workload API returns no SVID matching the filter. The error's `filter` property holds the filter that was used:

```ts
import { NoSvidError } from '@jeengbe/spiffe';
Expand All @@ -176,7 +231,7 @@ try {
}
```

`validateJwt()` returns `null` for invalid tokens rather than throwing.
`getJwtSvid()` returns `null` in that case instead, and `validateJwt()` returns `null` for invalid or expired tokens. Other errors, such as a Workload API that stays unavailable after all retries, are thrown as `ConnectError`.

## KafkaJS Integration

Expand Down Expand Up @@ -205,6 +260,16 @@ createKafkajsSaslMechanism('kafka-cluster', {
});
```

### Selecting an SVID and Client

Both KafkaJS helpers take an optional `SvidFilter` as the third argument and a `SpiffeJwtClient` (or a function that creates one) as the fourth. By default, each helper creates its own `SpiffeClient`. Pass an existing client to share its connection and caches:

```ts
declare const spiffe: SpiffeClient;

createKafkajsSaslMechanism('kafka-cluster', undefined, { hint: 'kafka' }, spiffe);
```

### Confluent Schema Registry SPIFFE Authentication

Use `createKafkajsAuthMiddleware()` to create a [Mappersmith](https://github.com/tulios/mappersmith) middleware that attaches a SPIFFE JWT-SVID as a bearer `Authorization` token on outgoing requests:
Expand Down
2 changes: 1 addition & 1 deletion packages/spiffe/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@
"@connectrpc/connect": "^2.1.2",
"@connectrpc/connect-node": "^2.1.2",
"@isaacs/ttlcache": "^2.1.4",
"lru-cache": "^11.5.2"
"p-retry": "^8.0.1"
},
"devDependencies": {
"@bufbuild/protoc-gen-es": "^2.13.0",
Expand Down
Loading
Loading