@owlmeans/iam 0.1.7 → 0.1.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +46 -0
- package/agent-meta/instructions/iam.instructions.md +117 -0
- package/agent-meta/manifest.json +16 -0
- package/build/errors.d.ts +4 -0
- package/build/errors.d.ts.map +1 -1
- package/build/errors.js +8 -0
- package/build/errors.js.map +1 -1
- package/build/types.d.ts +49 -1
- package/build/types.d.ts.map +1 -1
- package/package.json +5 -5
- package/src/errors.ts +10 -0
- package/src/types.ts +60 -1
package/README.md
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# @owlmeans/iam
|
|
2
|
+
|
|
3
|
+
Provider-agnostic IAM abstraction for the OwlMeans framework — `IamService` interface, client/realm types, and permission helpers.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
- `IamService` — unified interface for provisioning clients, realms, and permissions across IAM backends (e.g. Keycloak, built-in)
|
|
8
|
+
- `IamClient` / `IamCredentialsPair` / `IamResourceSpec` — shared contract types used by server-side IAM implementations
|
|
9
|
+
- `IamPermissionArgs` — describes a named permission including resource-scope and human-readable title
|
|
10
|
+
- `hasPermission` — utility to check whether a set of grants covers a given permission/resource pair
|
|
11
|
+
- Errors: `IamError` and subtypes for client-provisioning and permission failures
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
bun add @owlmeans/iam
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Usage
|
|
20
|
+
|
|
21
|
+
```typescript
|
|
22
|
+
import type { IamService, IamClient } from '@owlmeans/iam'
|
|
23
|
+
import { hasPermission } from '@owlmeans/iam'
|
|
24
|
+
|
|
25
|
+
// Check whether an auth payload includes a required permission
|
|
26
|
+
const allowed = hasPermission(auth, { permission: 'manage-users', resourceScoped: false })
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Typically consumed via `@owlmeans/server-iam` which wires the concrete OIDC-backed implementation.
|
|
30
|
+
|
|
31
|
+
<!-- owlmeans:agent-guidance:start -->
|
|
32
|
+
## Agent guidance
|
|
33
|
+
|
|
34
|
+
This package ships embedded Claude Code skills and GitHub Copilot instructions under
|
|
35
|
+
`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
|
|
36
|
+
agent-skills installer to place them into your project's native locations
|
|
37
|
+
(`.claude/skills/` and `.github/instructions/`):
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
npx @owlmeans/agent-skills
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The embedded files are version-matched to this package release. Do not edit them
|
|
44
|
+
directly — they are regenerated on each publish. To contribute guidance edits,
|
|
45
|
+
open a PR against the source monorepo.
|
|
46
|
+
<!-- owlmeans:agent-guidance:end -->
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "IamService abstraction for provider-agnostic IAM provisioning. Load when wiring IAM operations, switching IAM mode, or implementing a new IAM provider."
|
|
3
|
+
applyTo: "**/services/iam*.ts, **/context.ts, **/types.ts"
|
|
4
|
+
---
|
|
5
|
+
<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
|
|
6
|
+
|
|
7
|
+
# Using `@owlmeans/iam`
|
|
8
|
+
|
|
9
|
+
Provider-agnostic IAM abstraction. Defines `IamService` interface and related types. Used by both the platform backend (`viable-backend`) and the agent library (`@owlmeans/viable`). Concrete implementations live in `@owlmeans/iam-keycloak` (full proxy) and `@owlmeans/iam-integrated`.
|
|
10
|
+
|
|
11
|
+
## Public API surface
|
|
12
|
+
|
|
13
|
+
| Symbol | Kind | Purpose |
|
|
14
|
+
|--------|------|---------|
|
|
15
|
+
| `IamService` | type | Unified IAM interface — all provisioning + authorization operations |
|
|
16
|
+
| `IamClient` | type | Provisioned OIDC client `{ id?, clientId, secret?, name?, realm? }` |
|
|
17
|
+
| `IamClientOptions` | type | `{ redirectUris? }` — optional `ensureClient` hardening; omit → backend keeps its wildcard default |
|
|
18
|
+
| `IamCredentialsPair` | type | `{ token: string; realm: string }` |
|
|
19
|
+
| `IamPermissionArgs` | type | `{ permission?, resourceScoped?, title? }` — `permission` absent means unscoped resource name |
|
|
20
|
+
| `IamResourceSpec` | type | `{ name: string; displayName?: string }` |
|
|
21
|
+
| `IamPermissionDefinition` | type | Declared permission `{ name, resource, action?, resourceScoped?, title? }` |
|
|
22
|
+
| `IamGrantArgs` | type | `{ resources?: string[] }` — present = resource-scoped grant form |
|
|
23
|
+
| `IamGrant` | type | `{ profileId, clientId, permission, resources? }` |
|
|
24
|
+
| `hasPermission` | fn | `(auth, permission, { scope?, resourceId? }?)` — checks `Authorization.permissions` PermissionSet[]; an unscoped set satisfies a resourceId check |
|
|
25
|
+
| `DEFAULT_ALIAS` | const | Default service alias `'iam-service'` |
|
|
26
|
+
| `IAM_MODE_KEYCLOAK` | const | `'keycloak'` |
|
|
27
|
+
| `IAM_MODE_INTEGRATED` | const | `'integrated'` |
|
|
28
|
+
| `IamMode` | type | `'keycloak' \| 'integrated'` |
|
|
29
|
+
| `IamError` | class | Base IAM error |
|
|
30
|
+
| `IamClientError` | class | Thrown when an OIDC client is missing a required field (e.g. `secret`) |
|
|
31
|
+
| `IamResourceError` | class | Thrown when a KC resource returns with no name |
|
|
32
|
+
| `IamGrantError` | class | Grant subject missing or entity mismatch |
|
|
33
|
+
| `IamUnsupported` | class | Operation not supported by the active backend (e.g. resource-scoped grants on Keycloak) |
|
|
34
|
+
|
|
35
|
+
## Permission model (two grant forms)
|
|
36
|
+
|
|
37
|
+
Permissions are declared per entity client (project) with `ensurePermission` and granted to end-user
|
|
38
|
+
subjects with `grantPermission`:
|
|
39
|
+
|
|
40
|
+
- **Unscoped (project-wide)**: `grantPermission(entityId, clientId, profileId, 'article--modify')`
|
|
41
|
+
- **Resource-scoped**: `grantPermission(entityId, clientId, profileId, 'department--modify', { resources: ['dep-123'] })` —
|
|
42
|
+
the grant only applies to the listed resource ids.
|
|
43
|
+
|
|
44
|
+
Grants materialize as OwlMeans `PermissionSet[]` (`scope` = clientId; resource-scoped grants live in a
|
|
45
|
+
dedicated set per permission carrying `resources[]`, because `resources` applies to all keys of a set).
|
|
46
|
+
|
|
47
|
+
## `IamService` interface
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
interface IamService extends InitializedService {
|
|
51
|
+
// Get the admin OIDC provider config for a tenant (used in payment provisioning, RP config)
|
|
52
|
+
getEntityAdminConfig: (entityId: string) => Promise<OidcProviderConfig>
|
|
53
|
+
|
|
54
|
+
// Get an admin { token, realm } pair for raw low-level calls (avoid unless necessary)
|
|
55
|
+
getCredentialsPair: (entityId: string) => Promise<IamCredentialsPair>
|
|
56
|
+
|
|
57
|
+
// Provision an OIDC client for a tenant and return its credentials.
|
|
58
|
+
// options.redirectUris hardens the client (production/standalone); omitted → wildcard default.
|
|
59
|
+
ensureClient: (entityId: string, clientId: string, options?: IamClientOptions) => Promise<IamClient>
|
|
60
|
+
|
|
61
|
+
// Provision a named permission on a client resource; returns the resource name
|
|
62
|
+
ensurePermission: (entityId: string, clientId: string, resource?: string, args?: IamPermissionArgs) => Promise<string>
|
|
63
|
+
|
|
64
|
+
// Provision a resource and assign it to the tenant's owner role (used in payment provisioning)
|
|
65
|
+
ensureResourceOwnership: (entityId: string, clientId: string, resource: IamResourceSpec) => Promise<void>
|
|
66
|
+
|
|
67
|
+
// --- Authorization (permission definitions & grants) ---
|
|
68
|
+
|
|
69
|
+
// List permission definitions registered for the entity's client
|
|
70
|
+
listPermissions: (entityId: string, clientId: string) => Promise<IamPermissionDefinition[]>
|
|
71
|
+
|
|
72
|
+
// Grant a permission to an end-user subject; args.resources = resource-scoped form
|
|
73
|
+
grantPermission: (entityId: string, clientId: string, profileId: string, permission: string, args?: IamGrantArgs) => Promise<IamGrant>
|
|
74
|
+
|
|
75
|
+
// Revoke; with args.resources only those ids are removed, else the whole grant
|
|
76
|
+
revokePermission: (entityId: string, clientId: string, profileId: string, permission: string, args?: IamGrantArgs) => Promise<void>
|
|
77
|
+
|
|
78
|
+
// List grants for the client, optionally for one subject
|
|
79
|
+
listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## `IamClient.realm` field
|
|
84
|
+
|
|
85
|
+
`realm` is set by the provider to the entity ID. Use it instead of accessing internal properties:
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
// ✓ correct
|
|
89
|
+
await meta.update('oidcRealm', client.realm ?? fallbackEntityId)
|
|
90
|
+
|
|
91
|
+
// ✗ never do this — internal Keycloak implementation detail
|
|
92
|
+
await meta.update('oidcRealm', (client as any)._realm)
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Selecting the IAM provider
|
|
96
|
+
|
|
97
|
+
The platform wires the correct implementation via `IAM_MODE` environment variable. Default is `'keycloak'`. Do not read `IAM_MODE` directly from feature code — it belongs in the service-factory only:
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
export const makeIamService = (mode = process.env.IAM_MODE ?? 'keycloak') => {
|
|
101
|
+
if (mode === 'integrated') return makeIamIntegratedService(VIABLE_IAM)
|
|
102
|
+
return makeIamKeycloakService(VIABLE_IAM, { oidcProductAlias: OIDC_PRODUCT })
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Rules
|
|
107
|
+
|
|
108
|
+
- Always depend on `IamService` from `@owlmeans/iam`, not on `KeycloakApiService` directly.
|
|
109
|
+
- Do not expose `getCredentialsPair` to request handlers — it returns a raw admin token.
|
|
110
|
+
- `IamClientError` means the provisioned client was invalid (missing secret, null token). The proxy already throws it; callers only need to handle it, not re-throw wrapped errors.
|
|
111
|
+
- The `realm` field on `IamClient` is guaranteed to be set by all concrete implementations.
|
|
112
|
+
|
|
113
|
+
## Related instructions
|
|
114
|
+
|
|
115
|
+
- `@owlmeans/iam-keycloak` (internal) — full proxy over Keycloak; see `iam-keycloak.instructions.md`
|
|
116
|
+
- `@owlmeans/keycloak` (internal) — low-level KC admin API; see `keycloak.instructions.md`
|
|
117
|
+
- `@owlmeans/server-iam` — IAM gate asserting both grant forms; see `server-iam.instructions.md`
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"package": "@owlmeans/iam",
|
|
4
|
+
"version": "0.1.9",
|
|
5
|
+
"generatedAt": "2026-06-14T13:34:06.145Z",
|
|
6
|
+
"canonicalRepo": "https://github.com/owlmeans/common",
|
|
7
|
+
"entries": [
|
|
8
|
+
{
|
|
9
|
+
"kind": "instruction",
|
|
10
|
+
"name": "iam",
|
|
11
|
+
"category": "package-specific",
|
|
12
|
+
"file": "instructions/iam.instructions.md",
|
|
13
|
+
"canonicalPath": ".github/instructions/iam.instructions.md"
|
|
14
|
+
}
|
|
15
|
+
]
|
|
16
|
+
}
|
package/build/errors.d.ts
CHANGED
|
@@ -19,4 +19,8 @@ export declare class IamUnsupported extends IamError {
|
|
|
19
19
|
static typeName: string;
|
|
20
20
|
constructor(message?: string);
|
|
21
21
|
}
|
|
22
|
+
export declare class IamUserError extends IamError {
|
|
23
|
+
static typeName: string;
|
|
24
|
+
constructor(message?: string);
|
|
25
|
+
}
|
|
22
26
|
//# sourceMappingURL=errors.d.ts.map
|
package/build/errors.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,QAAS,SAAQ,cAAc;IAC1C,OAAuB,QAAQ,SAAkC;gBAErD,OAAO,SAAU;CAI9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAAwC;gBAE3D,OAAO,SAAU;CAI9B;AAED,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,OAAuB,QAAQ,SAA0C;gBAE7D,OAAO,SAAU;CAI9B;AAED,qBAAa,aAAc,SAAQ,QAAQ;IACzC,OAAuB,QAAQ,SAAuC;gBAE1D,OAAO,SAAU;CAI9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAA6C;gBAEhE,OAAO,SAAU;CAI9B"}
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,QAAS,SAAQ,cAAc;IAC1C,OAAuB,QAAQ,SAAkC;gBAErD,OAAO,SAAU;CAI9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAAwC;gBAE3D,OAAO,SAAU;CAI9B;AAED,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,OAAuB,QAAQ,SAA0C;gBAE7D,OAAO,SAAU;CAI9B;AAED,qBAAa,aAAc,SAAQ,QAAQ;IACzC,OAAuB,QAAQ,SAAuC;gBAE1D,OAAO,SAAU;CAI9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAA6C;gBAEhE,OAAO,SAAU;CAI9B;AAED,qBAAa,YAAa,SAAQ,QAAQ;IACxC,OAAuB,QAAQ,SAAsC;gBAEzD,OAAO,SAAU;CAI9B"}
|
package/build/errors.js
CHANGED
|
@@ -34,9 +34,17 @@ export class IamUnsupported extends IamError {
|
|
|
34
34
|
this.type = IamUnsupported.typeName;
|
|
35
35
|
}
|
|
36
36
|
}
|
|
37
|
+
export class IamUserError extends IamError {
|
|
38
|
+
static typeName = `IamUser${ResilientError.typeName}`;
|
|
39
|
+
constructor(message = 'error') {
|
|
40
|
+
super(`user:${message}`);
|
|
41
|
+
this.type = IamUserError.typeName;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
37
44
|
ResilientError.registerErrorClass(IamError);
|
|
38
45
|
ResilientError.registerErrorClass(IamClientError);
|
|
39
46
|
ResilientError.registerErrorClass(IamResourceError);
|
|
40
47
|
ResilientError.registerErrorClass(IamGrantError);
|
|
41
48
|
ResilientError.registerErrorClass(IamUnsupported);
|
|
49
|
+
ResilientError.registerErrorClass(IamUserError);
|
|
42
50
|
//# sourceMappingURL=errors.js.map
|
package/build/errors.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,QAAS,SAAQ,cAAc;IACnC,MAAM,CAAU,QAAQ,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEjE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,OAAO,EAAE,CAAC,CAAA;QAC1C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAA;IAC/B,CAAC;;AAGH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,YAAY,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEvE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IACrC,MAAM,CAAU,QAAQ,GAAG,cAAc,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEzE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAA;IACvC,CAAC;;AAGH,MAAM,OAAO,aAAc,SAAQ,QAAQ;IAClC,MAAM,CAAU,QAAQ,GAAG,WAAW,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEtE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAA;IACpC,CAAC;;AAGH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,iBAAiB,cAAc,CAAC,QAAQ,EAAE,CAAA;IAE5E,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAA;QAC/B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH,cAAc,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;AAC3C,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA;AACnD,cAAc,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAA;AAChD,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA"}
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,QAAS,SAAQ,cAAc;IACnC,MAAM,CAAU,QAAQ,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEjE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,OAAO,EAAE,CAAC,CAAA;QAC1C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAA;IAC/B,CAAC;;AAGH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,YAAY,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEvE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IACrC,MAAM,CAAU,QAAQ,GAAG,cAAc,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEzE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAA;IACvC,CAAC;;AAGH,MAAM,OAAO,aAAc,SAAQ,QAAQ;IAClC,MAAM,CAAU,QAAQ,GAAG,WAAW,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEtE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAA;IACpC,CAAC;;AAGH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,iBAAiB,cAAc,CAAC,QAAQ,EAAE,CAAA;IAE5E,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAA;QAC/B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACjC,MAAM,CAAU,QAAQ,GAAG,UAAU,cAAc,CAAC,QAAQ,EAAE,CAAA;IAErE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAA;IACnC,CAAC;;AAGH,cAAc,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;AAC3C,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA;AACnD,cAAc,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAA;AAChD,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAA"}
|
package/build/types.d.ts
CHANGED
|
@@ -12,6 +12,15 @@ export interface IamCredentialsPair {
|
|
|
12
12
|
token: string;
|
|
13
13
|
realm: string;
|
|
14
14
|
}
|
|
15
|
+
export interface IamClientOptions {
|
|
16
|
+
/**
|
|
17
|
+
* Explicit allowed redirect URIs for the client. When omitted the backend keeps its
|
|
18
|
+
* permissive default (wildcard `*`) for back-compat. Pass concrete origins to harden a
|
|
19
|
+
* client — used for production/standalone clients whose callbacks are the production
|
|
20
|
+
* generated host, an attached custom domain, and owner-registered self-host origins.
|
|
21
|
+
*/
|
|
22
|
+
redirectUris?: string[];
|
|
23
|
+
}
|
|
15
24
|
export interface IamPermissionArgs {
|
|
16
25
|
/** Action name. When absent the permission is unscoped (project-wide). */
|
|
17
26
|
permission?: string;
|
|
@@ -47,11 +56,37 @@ export interface IamGrant {
|
|
|
47
56
|
/** Present only for resource-scoped grants. */
|
|
48
57
|
resources?: string[];
|
|
49
58
|
}
|
|
59
|
+
/** An end-user of an entity (customer-wide; shared across that entity's projects). */
|
|
60
|
+
export interface IamUser {
|
|
61
|
+
/** Backend-specific subject id: integrated = IdentityProfile.profileId, keycloak = KC user id. */
|
|
62
|
+
profileId: string;
|
|
63
|
+
/** Primary login identifier (email for the integrated OTP path). */
|
|
64
|
+
email?: string;
|
|
65
|
+
name?: string;
|
|
66
|
+
/** AuthRole value. */
|
|
67
|
+
role: string;
|
|
68
|
+
disabled?: boolean;
|
|
69
|
+
/** Convenience count of permission grants the user holds (across clients, or for one client). */
|
|
70
|
+
grantCount?: number;
|
|
71
|
+
}
|
|
72
|
+
/** Args to invite/create an end-user under an entity. */
|
|
73
|
+
export interface IamUserInvite {
|
|
74
|
+
email: string;
|
|
75
|
+
name?: string;
|
|
76
|
+
/** AuthRole value; defaults to the backend's standard end-user role. */
|
|
77
|
+
role?: string;
|
|
78
|
+
}
|
|
79
|
+
/** Args to update an existing end-user. */
|
|
80
|
+
export interface IamUserUpdate {
|
|
81
|
+
name?: string;
|
|
82
|
+
role?: string;
|
|
83
|
+
disabled?: boolean;
|
|
84
|
+
}
|
|
50
85
|
/** Unified IAM provider interface — all platform/agent code calls only this, never a backend directly */
|
|
51
86
|
export interface IamService extends InitializedService {
|
|
52
87
|
getEntityAdminConfig: (entityId: string) => Promise<OidcProviderConfig>;
|
|
53
88
|
getCredentialsPair: (entityId: string) => Promise<IamCredentialsPair>;
|
|
54
|
-
ensureClient: (entityId: string, clientId: string) => Promise<IamClient>;
|
|
89
|
+
ensureClient: (entityId: string, clientId: string, options?: IamClientOptions) => Promise<IamClient>;
|
|
55
90
|
/**
|
|
56
91
|
* Ensures a permission/resource exists in the entity's client.
|
|
57
92
|
* Returns the canonical resource name (e.g. "res--action" or "res").
|
|
@@ -76,5 +111,18 @@ export interface IamService extends InitializedService {
|
|
|
76
111
|
revokePermission: (entityId: string, clientId: string, profileId: string, permission: string, args?: IamGrantArgs) => Promise<void>;
|
|
77
112
|
/** Lists grants for the entity's client, optionally for a single subject. */
|
|
78
113
|
listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>;
|
|
114
|
+
/**
|
|
115
|
+
* Lists the entity's end-users. With clientId, narrows to users holding at least
|
|
116
|
+
* one grant for that client (per-project view).
|
|
117
|
+
*/
|
|
118
|
+
listUsers: (entityId: string, clientId?: string) => Promise<IamUser[]>;
|
|
119
|
+
/** Loads a single end-user by subject id, or null when absent. */
|
|
120
|
+
getUser: (entityId: string, profileId: string) => Promise<IamUser | null>;
|
|
121
|
+
/** Creates (or resolves, idempotently by email) an end-user under the entity. */
|
|
122
|
+
inviteUser: (entityId: string, invite: IamUserInvite) => Promise<IamUser>;
|
|
123
|
+
/** Updates an end-user's mutable fields (name, role, disabled). */
|
|
124
|
+
updateUser: (entityId: string, profileId: string, update: IamUserUpdate) => Promise<IamUser>;
|
|
125
|
+
/** Removes an end-user from the entity (their grants go with them). */
|
|
126
|
+
removeUser: (entityId: string, profileId: string) => Promise<void>;
|
|
79
127
|
}
|
|
80
128
|
//# sourceMappingURL=types.d.ts.map
|
package/build/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAExD,MAAM,WAAW,SAAS;IACxB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qFAAqF;IACrF,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,8DAA8D;AAC9D,MAAM,WAAW,uBAAuB;IACtC,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,QAAQ;IACvB,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACrB;AAED,yGAAyG;AACzG,MAAM,WAAW,UAAW,SAAQ,kBAAkB;IAEpD,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAGrE,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAA;
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@owlmeans/iam",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.9",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
@@ -22,10 +22,10 @@
|
|
|
22
22
|
}
|
|
23
23
|
},
|
|
24
24
|
"dependencies": {
|
|
25
|
-
"@owlmeans/auth": "^0.1.
|
|
26
|
-
"@owlmeans/context": "^0.1.
|
|
27
|
-
"@owlmeans/error": "^0.1.
|
|
28
|
-
"@owlmeans/oidc": "^0.1.
|
|
25
|
+
"@owlmeans/auth": "^0.1.9",
|
|
26
|
+
"@owlmeans/context": "^0.1.9",
|
|
27
|
+
"@owlmeans/error": "^0.1.9",
|
|
28
|
+
"@owlmeans/oidc": "^0.1.9"
|
|
29
29
|
},
|
|
30
30
|
"devDependencies": {
|
|
31
31
|
"@owlmeans/dep-config": "workspace:*",
|
package/src/errors.ts
CHANGED
|
@@ -45,8 +45,18 @@ export class IamUnsupported extends IamError {
|
|
|
45
45
|
}
|
|
46
46
|
}
|
|
47
47
|
|
|
48
|
+
export class IamUserError extends IamError {
|
|
49
|
+
public static override typeName = `IamUser${ResilientError.typeName}`
|
|
50
|
+
|
|
51
|
+
constructor(message = 'error') {
|
|
52
|
+
super(`user:${message}`)
|
|
53
|
+
this.type = IamUserError.typeName
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
|
|
48
57
|
ResilientError.registerErrorClass(IamError)
|
|
49
58
|
ResilientError.registerErrorClass(IamClientError)
|
|
50
59
|
ResilientError.registerErrorClass(IamResourceError)
|
|
51
60
|
ResilientError.registerErrorClass(IamGrantError)
|
|
52
61
|
ResilientError.registerErrorClass(IamUnsupported)
|
|
62
|
+
ResilientError.registerErrorClass(IamUserError)
|
package/src/types.ts
CHANGED
|
@@ -15,6 +15,16 @@ export interface IamCredentialsPair {
|
|
|
15
15
|
realm: string
|
|
16
16
|
}
|
|
17
17
|
|
|
18
|
+
export interface IamClientOptions {
|
|
19
|
+
/**
|
|
20
|
+
* Explicit allowed redirect URIs for the client. When omitted the backend keeps its
|
|
21
|
+
* permissive default (wildcard `*`) for back-compat. Pass concrete origins to harden a
|
|
22
|
+
* client — used for production/standalone clients whose callbacks are the production
|
|
23
|
+
* generated host, an attached custom domain, and owner-registered self-host origins.
|
|
24
|
+
*/
|
|
25
|
+
redirectUris?: string[]
|
|
26
|
+
}
|
|
27
|
+
|
|
18
28
|
export interface IamPermissionArgs {
|
|
19
29
|
/** Action name. When absent the permission is unscoped (project-wide). */
|
|
20
30
|
permission?: string
|
|
@@ -55,6 +65,35 @@ export interface IamGrant {
|
|
|
55
65
|
resources?: string[]
|
|
56
66
|
}
|
|
57
67
|
|
|
68
|
+
/** An end-user of an entity (customer-wide; shared across that entity's projects). */
|
|
69
|
+
export interface IamUser {
|
|
70
|
+
/** Backend-specific subject id: integrated = IdentityProfile.profileId, keycloak = KC user id. */
|
|
71
|
+
profileId: string
|
|
72
|
+
/** Primary login identifier (email for the integrated OTP path). */
|
|
73
|
+
email?: string
|
|
74
|
+
name?: string
|
|
75
|
+
/** AuthRole value. */
|
|
76
|
+
role: string
|
|
77
|
+
disabled?: boolean
|
|
78
|
+
/** Convenience count of permission grants the user holds (across clients, or for one client). */
|
|
79
|
+
grantCount?: number
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** Args to invite/create an end-user under an entity. */
|
|
83
|
+
export interface IamUserInvite {
|
|
84
|
+
email: string
|
|
85
|
+
name?: string
|
|
86
|
+
/** AuthRole value; defaults to the backend's standard end-user role. */
|
|
87
|
+
role?: string
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** Args to update an existing end-user. */
|
|
91
|
+
export interface IamUserUpdate {
|
|
92
|
+
name?: string
|
|
93
|
+
role?: string
|
|
94
|
+
disabled?: boolean
|
|
95
|
+
}
|
|
96
|
+
|
|
58
97
|
/** Unified IAM provider interface — all platform/agent code calls only this, never a backend directly */
|
|
59
98
|
export interface IamService extends InitializedService {
|
|
60
99
|
// --- Admin config (backend → OIDC RP config, payment provisioning) ---
|
|
@@ -62,7 +101,7 @@ export interface IamService extends InitializedService {
|
|
|
62
101
|
getCredentialsPair: (entityId: string) => Promise<IamCredentialsPair>
|
|
63
102
|
|
|
64
103
|
// --- Provisioning (agent → story development) ---
|
|
65
|
-
ensureClient: (entityId: string, clientId: string) => Promise<IamClient>
|
|
104
|
+
ensureClient: (entityId: string, clientId: string, options?: IamClientOptions) => Promise<IamClient>
|
|
66
105
|
|
|
67
106
|
/**
|
|
68
107
|
* Ensures a permission/resource exists in the entity's client.
|
|
@@ -116,4 +155,24 @@ export interface IamService extends InitializedService {
|
|
|
116
155
|
|
|
117
156
|
/** Lists grants for the entity's client, optionally for a single subject. */
|
|
118
157
|
listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>
|
|
158
|
+
|
|
159
|
+
// --- End-user management (customer-wide users, shared per entityId) ---
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Lists the entity's end-users. With clientId, narrows to users holding at least
|
|
163
|
+
* one grant for that client (per-project view).
|
|
164
|
+
*/
|
|
165
|
+
listUsers: (entityId: string, clientId?: string) => Promise<IamUser[]>
|
|
166
|
+
|
|
167
|
+
/** Loads a single end-user by subject id, or null when absent. */
|
|
168
|
+
getUser: (entityId: string, profileId: string) => Promise<IamUser | null>
|
|
169
|
+
|
|
170
|
+
/** Creates (or resolves, idempotently by email) an end-user under the entity. */
|
|
171
|
+
inviteUser: (entityId: string, invite: IamUserInvite) => Promise<IamUser>
|
|
172
|
+
|
|
173
|
+
/** Updates an end-user's mutable fields (name, role, disabled). */
|
|
174
|
+
updateUser: (entityId: string, profileId: string, update: IamUserUpdate) => Promise<IamUser>
|
|
175
|
+
|
|
176
|
+
/** Removes an end-user from the entity (their grants go with them). */
|
|
177
|
+
removeUser: (entityId: string, profileId: string) => Promise<void>
|
|
119
178
|
}
|