Identity — the engine directory
WeaveKit runs RBAC against its own identity directory (weavekit_user / weavekit_department) — the single id space that row scopes, audit actors, and workflow a…
WeaveKit runs RBAC against its own identity directory (weavekit_user /
weavekit_department) — the single id space that row scopes, audit actors, and workflow
assignees all use. An existing customer directory is an import source: you sync it into the
engine before the engine serves scoped access. The engine only ever reads the source tables.
Why sync first
If the engine scoped rows against customer ids while RBAC also needed internal ids, every row filter, audit entry, and workflow node would have to translate across two id spaces. Syncing once up front keeps a single internal id everywhere.
// weavekit.config.ts
export default {
identity: {
source: {
name: 'crm',
users: { table: 'sales_user', id: 'id', name: 'name', email: 'email',
roles: 'role', department: 'dept_id', director: 'manager_id', enabled: 'active' },
departments: { table: 'dept', id: 'id', name: 'name', parent: 'parent_id', manager: 'lead_id', enabled: 'active' },
},
sync: { onStart: false, deactivateMissing: true },
required: true,
},
} satisfies EngineConfig;Then:
weave sync:identity # read-only against the customer tables
weave sync:identity --dry-runThe sync is idempotent (upsert on (external_source, external_id)), links departments/users in two
passes (a child may reference a parent listed later), detects department parent cycles, keeps a
cursor for incremental sources, and soft-disables (never deletes) rows missing from the snapshot.
Sources
identity.source is either a declarative pg descriptor (above) or a function-backed
IdentitySource:
import { createFunctionIdentitySource } from '@weave-kit/engine';
const source = createFunctionIdentitySource({
name: 'hr',
pull: async (cursor) => {
const rows = await hrApi.usersSince(cursor);
return { users: rows.users, departments: rows.departments, cursor: rows.cursor };
},
});Enterprise integrations (SCIM, LDAP, HRIS) implement the same IdentitySource contract and are
injected the same way — the engine core stays free of protocol dependencies.
Authentication
Either keep the static key map / custom resolver:
{ auth: { source: { 'sk-rep': { id: 'u100', roles: ['sales'], departmentId: 'd-east' } } } }…or let a verifier authenticate and the directory resolve:
{
identity: {
verifier: { verify: (header) => verifyJwt(header) }, // → { ref, claims } | null
required: true,
},
}verifier → directory → subject. A verified credential with no synced local user is rejected
with identity.notSynced (403) — run weave sync:identity first. identity.required also gates a
custom auth.source on the directory.
Built-in OIDC/JWT (auth.oidc)
For a standards-based IdP you don't need a custom verifier — point auth.oidc at it and the engine
validates bearer JWTs locally (signature via JWKS, iss/aud/exp/nbf, asymmetric algs only):
{
auth: {
oidc: {
issuer: 'https://idp.example.com', // discovery at <issuer>/.well-known/openid-configuration
// jwksUri: 'https://idp.example.com/.well-known/jwks.json', // or set JWKS directly
audience: 'weavekit-engine',
subjectClaim: 'sub', // → the external user ref (default: sub)
rolesClaim: 'roles', // also exposed as claims.roles for the directory
// scopeClaim: 'tenant',
},
},
}It composes with the identity directory exactly like a custom verifier: the resolved ref must have
a synced local user (weave sync:identity). The subjectClaim value identifies the user; roles come
from the directory. createOidcVerifier is exported for hosts that assemble the authenticator
themselves.
Managing identities
Greenfield projects (no external source) manage users directly:
weave identity:list
weave identity:create "Alice" --email alice@x --roles admin,sales
weave identity:disable <id>
weave identity:enable <id>
weave identity:set-roles <id> --roles admin
weave identity:delete <id>Or the admin REST surface (gated by adapters.rest.adminRoles):
| Route | Purpose |
|---|---|
GET /api/identity/users | list local users |
POST /api/identity/users | create a user |
PATCH /api/identity/users/:id | enable/disable and/or set roles |
DELETE /api/identity/users/:id | delete a user |
GET /api/identity/departments | list local departments |
POST /api/identity/departments | create a department |
Extending (enterprise)
The engine ships the seam and the pg/function sources plus a built-in OIDC/JWT verifier
(auth.oidc). @weave-kit/enterprise adds SAML, a SCIM 2.0 server, LDAP/HRIS directory connectors,
group→role mapping, multi-IdP and identity-event audit against the same IdentitySource /
AuthVerifier contracts. See RBAC for how the resulting subject scopes rows.