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
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
32 changes: 16 additions & 16 deletions en/api/@connectum/auth/classes/AuthzDeniedError.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

# Class: AuthzDeniedError

Defined in: [packages/auth/src/errors.ts:26](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/errors.ts#L26)
Defined in: [packages/auth/src/errors.ts:26](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/errors.ts#L26)

Authorization denied error.

Expand All @@ -23,7 +23,7 @@ exposing only "Access denied" to the client via SanitizableError protocol.

> **new AuthzDeniedError**(`details`): `AuthzDeniedError`

Defined in: [packages/auth/src/errors.ts:39](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/errors.ts#L39)
Defined in: [packages/auth/src/errors.ts:39](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/errors.ts#L39)

#### Parameters

Expand All @@ -45,15 +45,15 @@ Defined in: [packages/auth/src/errors.ts:39](https://github.com/Connectum-Framew

> `readonly` **authzDetails**: [`AuthzDeniedDetails`](../interfaces/AuthzDeniedDetails.md)

Defined in: [packages/auth/src/errors.ts:29](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/errors.ts#L29)
Defined in: [packages/auth/src/errors.ts:29](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/errors.ts#L29)

***

### cause

> **cause**: `unknown`

Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.0/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:46
Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.1/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:46

The underlying cause of this error, if any. In cases where the actual cause
is elided with the error message, the cause is specified here so that we
Expand All @@ -69,7 +69,7 @@ don't leak the underlying error, but instead make it available for logging.

> `readonly` **clientMessage**: `"Access denied"` = `"Access denied"`

Defined in: [packages/auth/src/errors.ts:27](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/errors.ts#L27)
Defined in: [packages/auth/src/errors.ts:27](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/errors.ts#L27)

#### Implementation of

Expand All @@ -81,7 +81,7 @@ Defined in: [packages/auth/src/errors.ts:27](https://github.com/Connectum-Framew

> `readonly` **code**: `Code`

Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.0/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:20
Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.1/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:20

The Code for this error.

Expand All @@ -95,7 +95,7 @@ The Code for this error.

> **details**: (`OutgoingDetail` \| `IncomingDetail`)[]

Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.0/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:32
Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.1/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:32

When an error is parsed from the wire, incoming error details are stored
in this property. They can be retrieved using findDetails().
Expand Down Expand Up @@ -125,7 +125,7 @@ Defined in: node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/li

> `readonly` **metadata**: `Headers`

Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.0/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:24
Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.1/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:24

A union of response headers and trailers associated with this error.

Expand All @@ -139,7 +139,7 @@ A union of response headers and trailers associated with this error.

> **name**: `string`

Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.0/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:40
Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.1/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:40

#### Inherited from

Expand All @@ -151,7 +151,7 @@ Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.

> `readonly` **rawMessage**: `string`

Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.0/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:39
Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.1/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:39

The error message, but without a status code in front.

Expand All @@ -168,7 +168,7 @@ the message `[not found] hello`, and the rawMessage `hello`.

> `readonly` **ruleName**: `string`

Defined in: [packages/auth/src/errors.ts:28](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/errors.ts#L28)
Defined in: [packages/auth/src/errors.ts:28](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/errors.ts#L28)

***

Expand Down Expand Up @@ -212,7 +212,7 @@ not capture any frames.

> **get** **serverDetails**(): `Readonly`\<`Record`\<`string`, `unknown`\>\>

Defined in: [packages/auth/src/errors.ts:31](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/errors.ts#L31)
Defined in: [packages/auth/src/errors.ts:31](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/errors.ts#L31)

##### Returns

Expand All @@ -230,7 +230,7 @@ Defined in: [packages/auth/src/errors.ts:31](https://github.com/Connectum-Framew

> **findDetails**\<`Desc`\>(`desc`): `MessageShape`\<`Desc`\>[]

Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.0/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:77
Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.1/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:77

Retrieve error details from a ConnectError. On the wire, error details are
wrapped with google.protobuf.Any, so that a server or middleware can attach
Expand Down Expand Up @@ -263,7 +263,7 @@ omitted from the list.

> **findDetails**(`registry`): `Message`[]

Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.0/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:78
Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.1/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:78

Retrieve error details from a ConnectError. On the wire, error details are
wrapped with google.protobuf.Any, so that a server or middleware can attach
Expand Down Expand Up @@ -292,7 +292,7 @@ omitted from the list.

> `static` **\[hasInstance\]**(`v`): `boolean`

Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.0/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:68
Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.1/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:68

#### Parameters

Expand Down Expand Up @@ -384,7 +384,7 @@ a();

> `static` **from**(`reason`, `code?`): `ConnectError`

Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.0/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:67
Defined in: node\_modules/.pnpm/@connectrpc+connect@2.1.2\_@bufbuild+protobuf@2.12.1/node\_modules/@connectrpc/connect/dist/esm/connect-error.d.ts:67

Convert any value - typically a caught error into a ConnectError,
following these rules:
Expand Down
12 changes: 6 additions & 6 deletions en/api/@connectum/auth/classes/LruCache.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

# Class: LruCache\<T\>

Defined in: [packages/auth/src/cache.ts:13](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/cache.ts#L13)
Defined in: [packages/auth/src/cache.ts:13](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/cache.ts#L13)

## Type Parameters

Expand All @@ -16,7 +16,7 @@ Defined in: [packages/auth/src/cache.ts:13](https://github.com/Connectum-Framewo

> **new LruCache**\<`T`\>(`options`): `LruCache`\<`T`\>

Defined in: [packages/auth/src/cache.ts:18](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/cache.ts#L18)
Defined in: [packages/auth/src/cache.ts:18](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/cache.ts#L18)

#### Parameters

Expand All @@ -42,7 +42,7 @@ Defined in: [packages/auth/src/cache.ts:18](https://github.com/Connectum-Framewo

> **get** **size**(): `number`

Defined in: [packages/auth/src/cache.ts:63](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/cache.ts#L63)
Defined in: [packages/auth/src/cache.ts:63](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/cache.ts#L63)

##### Returns

Expand All @@ -54,7 +54,7 @@ Defined in: [packages/auth/src/cache.ts:63](https://github.com/Connectum-Framewo

> **clear**(): `void`

Defined in: [packages/auth/src/cache.ts:59](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/cache.ts#L59)
Defined in: [packages/auth/src/cache.ts:59](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/cache.ts#L59)

#### Returns

Expand All @@ -66,7 +66,7 @@ Defined in: [packages/auth/src/cache.ts:59](https://github.com/Connectum-Framewo

> **get**(`key`): `T` \| `undefined`

Defined in: [packages/auth/src/cache.ts:26](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/cache.ts#L26)
Defined in: [packages/auth/src/cache.ts:26](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/cache.ts#L26)

#### Parameters

Expand All @@ -84,7 +84,7 @@ Defined in: [packages/auth/src/cache.ts:26](https://github.com/Connectum-Framewo

> **set**(`key`, `value`): `void`

Defined in: [packages/auth/src/cache.ts:41](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/cache.ts#L41)
Defined in: [packages/auth/src/cache.ts:41](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/cache.ts#L41)

#### Parameters

Expand Down
2 changes: 1 addition & 1 deletion en/api/@connectum/auth/functions/createAuthInterceptor.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

> **createAuthInterceptor**(`options`): `Interceptor`

Defined in: [packages/auth/src/auth-interceptor.ts:81](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/auth-interceptor.ts#L81)
Defined in: [packages/auth/src/auth-interceptor.ts:81](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/auth-interceptor.ts#L81)

Create a generic authentication interceptor.

Expand Down
2 changes: 1 addition & 1 deletion en/api/@connectum/auth/functions/createAuthzInterceptor.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

> **createAuthzInterceptor**(`options?`): `Interceptor`

Defined in: [packages/auth/src/authz-interceptor.ts:85](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/authz-interceptor.ts#L85)
Defined in: [packages/auth/src/authz-interceptor.ts:85](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/authz-interceptor.ts#L85)

Create an authorization interceptor.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

> **createClientBearerInterceptor**(`options`): `Interceptor`

Defined in: [packages/auth/src/client-bearer-interceptor.ts:51](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/client-bearer-interceptor.ts#L51)
Defined in: [packages/auth/src/client-bearer-interceptor.ts:51](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/client-bearer-interceptor.ts#L51)

Create a client interceptor that attaches a Bearer token to outgoing requests.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

> **createClientGatewayInterceptor**(`options`): `Interceptor`

Defined in: [packages/auth/src/client-gateway-interceptor.ts:52](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/client-gateway-interceptor.ts#L52)
Defined in: [packages/auth/src/client-gateway-interceptor.ts:52](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/client-gateway-interceptor.ts#L52)

Create a client interceptor that attaches gateway auth headers to outgoing requests.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

> **createGatewayAuthInterceptor**(`options`): `Interceptor`

Defined in: [packages/auth/src/gateway-auth-interceptor.ts:92](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/gateway-auth-interceptor.ts#L92)
Defined in: [packages/auth/src/gateway-auth-interceptor.ts:92](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/gateway-auth-interceptor.ts#L92)

Create a gateway authentication interceptor.

Expand Down
73 changes: 73 additions & 0 deletions en/api/@connectum/auth/functions/createInternalAuthInterceptor.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
[Connectum API Reference](../../../index.md) / [@connectum/auth](../index.md) / createInternalAuthInterceptor

# Function: createInternalAuthInterceptor()

> **createInternalAuthInterceptor**(`options`): `Interceptor`

Defined in: [packages/auth/src/internal-auth-interceptor.ts:89](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/internal-auth-interceptor.ts#L89)

Create an internal (service-to-service) authentication interceptor.

For methods matched by `internalMethods`, the configured `trustSource`
authorizes the call and sets an `AuthContext`. A trust source returning
`null` (or throwing) is rejected as `Code.Unauthenticated`. Non-internal
methods are a no-op pass-through.

MUST run BEFORE `createProtoAuthzInterceptor`: the internal interceptor
populates the `AuthContext` that proto-authz's `internal` rule consumes.

Each trust-source factory strips its own trust header after extraction on the
internal path (accept and reject), to prevent a spoofed marker from being
propagated downstream. NOTE: for NON-internal methods this interceptor is a
pure pass-through and does NOT strip any trust headers — a request to a
`public`/gated method carrying a forged identity header passes through
untouched. In the supported deployments the mesh sidecar (or an upstream
gateway) terminates the trust boundary and scrubs these headers on every
route; do not rely on this interceptor to sanitize non-internal routes.

## Parameters

### options

[`InternalAuthInterceptorOptions`](../interfaces/InternalAuthInterceptorOptions.md)

Internal auth configuration.

## Returns

`Interceptor`

ConnectRPC interceptor.

## Examples

**Mesh deployment (production default)**

```typescript
import { createInternalAuthInterceptor, meshIdentityTrust, getInternalMethods } from '@connectum/auth';

const internalAuth = createInternalAuthInterceptor({
internalMethods: getInternalMethods(services),
trustSource: meshIdentityTrust({
allowlist: [
{ principal: 'cluster.local/ns/default/sa/trips', roles: ['worker'] },
],
}),
});
```

**Non-mesh, per-service signed tokens**

```typescript
import { createInternalAuthInterceptor, signedTokenTrust, getInternalMethods } from '@connectum/auth';

const internalAuth = createInternalAuthInterceptor({
internalMethods: getInternalMethods(services),
trustSource: signedTokenTrust({
issuers: {
'trips-service': { jwksUri: 'https://trips/.well-known/jwks.json', claimsMapping: { roles: 'roles' } },
'billing-service': { jwksUri: 'https://billing/.well-known/jwks.json' },
},
}),
});
```
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

> **createJwtAuthInterceptor**(`options`): `Interceptor`

Defined in: [packages/auth/src/jwt-auth-interceptor.ts:168](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/jwt-auth-interceptor.ts#L168)
Defined in: [packages/auth/src/jwt-auth-interceptor.ts:168](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/jwt-auth-interceptor.ts#L168)

Create a JWT authentication interceptor.

Expand Down
31 changes: 19 additions & 12 deletions en/api/@connectum/auth/functions/createProtoAuthzInterceptor.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

> **createProtoAuthzInterceptor**(`options?`): `Interceptor`

Defined in: [packages/auth/src/proto/proto-authz-interceptor.ts:125](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/proto/proto-authz-interceptor.ts#L125)
Defined in: [packages/auth/src/proto/proto-authz-interceptor.ts:132](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/proto/proto-authz-interceptor.ts#L132)

Create a proto-based authorization interceptor.

Expand All @@ -14,21 +14,28 @@ falls back to programmatic rules and an authorize callback.

Authorization decision flow:
```
1. resolveMethodAuth(req.method) -- read proto options
2. public = true --> skip (allow without authn)
3. Get auth context -- lazy: don't throw yet
4. requires defined, no context --> throw Unauthenticated
4b. requires defined, has context --> satisfiesRequirements? allow : deny
5. policy = "allow" --> allow
6. policy = "deny" --> deny
7. Evaluate programmatic rules -- unconditional rules work without context
8. Fallback: authorize callback --> requires auth context
9. Apply defaultPolicy --> deny without context = Unauthenticated
1. resolveMethodAuth(req.method) -- read proto options
2. public = true --> skip (allow without authn)
3. Get auth context -- lazy: don't throw yet
3b. internal = true: -- service-to-service (ADR-029)
no context --> throw Unauthenticated
no requires --> allow (any trusted internal caller)
has requires --> fall through to step 4 (inclusive roles)
4. requires defined, no context --> throw Unauthenticated
4b. requires defined, has context --> satisfiesRequirements? allow : deny
5. policy = "allow" --> allow
6. policy = "deny" --> deny
7. Evaluate programmatic rules -- unconditional rules work without context
8. Fallback: authorize callback --> requires auth context
9. Apply defaultPolicy --> deny without context = Unauthenticated
```

IMPORTANT: This interceptor MUST run AFTER an authentication interceptor
in the chain (except for methods marked as `public` in proto options
or matched by unconditional programmatic rules).
or matched by unconditional programmatic rules). For `internal` methods the
upstream interceptor is [createInternalAuthInterceptor](createInternalAuthInterceptor.md); the chain order
is `errorHandler -> (jwtAuth | internalAuth) -> protoAuthz` — the auth
interceptors populate the `AuthContext` that this interceptor consumes.

## Parameters

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

> **createSessionAuthInterceptor**(`options`): `Interceptor`

Defined in: [packages/auth/src/session-auth-interceptor.ts:60](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/session-auth-interceptor.ts#L60)
Defined in: [packages/auth/src/session-auth-interceptor.ts:60](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/session-auth-interceptor.ts#L60)

Create a session-based authentication interceptor.

Expand Down
2 changes: 1 addition & 1 deletion en/api/@connectum/auth/functions/getAuthContext.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

> **getAuthContext**(): [`AuthContext`](../interfaces/AuthContext.md) \| `undefined`

Defined in: [packages/auth/src/context.ts:111](https://github.com/Connectum-Framework/connectum/blob/a01886190a74a7110bf96486238bdcb7740ecf6e/packages/auth/src/context.ts#L111)
Defined in: [packages/auth/src/context.ts:111](https://github.com/Connectum-Framework/connectum/blob/main/packages/auth/src/context.ts#L111)

Get the current auth context.

Expand Down
Loading
Loading