Security Model

ShrikeDB can run in a simple single-tenant mode or with multi-tenant authentication and authorization. Use multi-tenant mode when different people, services, agents, or automation jobs need different permissions.

Deployment Modes

Mode What happens Use it when

Single-tenant default

The server uses an implicit system context. Requests do not need identity setup.

Local development, isolated benchmarks, disposable demos, and trusted single-operator environments.

Multi-tenant

Requests are authenticated, resolved into a tenant context, and authorized through RBAC/ABAC.

Shared systems, service accounts, production-like demos, governed MCP/chat use, and any environment with separate principals.

Use a supplied multi-tenant server package and enable authentication in its configuration. Obtain the initial administrator credential through your deployment’s provisioning procedure before running identity-management requests.

Identity Service

The gRPC identity package is shrikedb.identity.v2. It is documented in User Administration and summarized in gRPC API.

Implemented areas:

  • tenant management,

  • user management,

  • role management,

  • policy document management,

  • API key lifecycle,

  • username/password login,

  • refresh-token rotation,

  • WhoAmI introspection.

Authentication

Registered identity-service requests require one of these credentials:

Header Use

authorization: Bearer <JWT>

JWT access token returned by Login or RefreshToken.

x-shrikedb-api-key: <key>

API-key authentication for service accounts and automation.

x-fusiondb-api-key: <key>

Legacy compatibility API-key header.

JWT access tokens are short-lived. Refresh tokens rotate: after a successful refresh, store the new refresh token and discard the old one. API keys are returned raw exactly once at creation time.

Authorization Decision

Every authenticated request is reduced to a tenant context plus a requested resource and mode. The decision path is intentionally small and predictable:

request credential
  -> TenantContext
       tenant_uid
       user_uid
       auth_method
       roles
       attributes
  -> requested PermissionScope + PermissionMode
  -> policy cache decision
       1. system principal allow
       2. matching deny rejects
       3. RBAC permission allow
       4. ABAC allow if all conditions match
       5. otherwise deny

Deny rules win over allow rules. Requests with no matching RBAC or ABAC allow are denied.

Permission Scopes

Scope Covers

Tenant

All resources inside the tenant.

KvNamespace(name)

A key-value namespace.

GraphNamespace(name)

A graph namespace.

VectorIndex(name)

A vector index.

SemanticProfile(name)

A semantic profile or profile-backed semantic workflow.

OntologyView(name)

An ontology view used for semantic or graph reasoning.

Tenant scope is broad. Prefer namespace, profile, ontology, or vector-index scopes when a role does not need tenant-wide authority.

Permission Modes

Mode Meaning

Read

Read queries, scans, semantic explain/execute, vector search, and metadata inspection.

Write

Data writes, graph writes, KV writes, vector inserts, and write-shaped query statements.

Delete

Delete or tombstone operations where supported.

Schema

Schema/profile/index management. This also covers write and read.

Grant

Permission management. This also covers schema, write, read, and delete.

Admin

Full administrative authority for the scope.

Handlers map requests to modes before execution. For example, read-only Cypher/SPARQL requires Read; write-shaped Cypher/SPARQL requires Write; schema and identity operations require stronger modes. Transaction writes are checked when they are added and again at commit.

RBAC

RBAC is role based. A role contains permissions like:

{
  "scope": "PERMISSION_SCOPE_GRAPH_NAMESPACE",
  "mode": "PERMISSION_MODE_READ",
  "namespace": "claims"
}

Use RBAC for the common cases:

  • analyst can read one graph namespace and one semantic profile,

  • ingestion worker can write one graph namespace,

  • service account can read one vector index,

  • tenant admin can manage roles and policy.

ABAC

ABAC policy documents add conditional decisions over attributes. Policies can inspect:

  • principal attributes: system flag, tenant UID, user UID, auth method, API-key UID, JWT ID, username, and roles,

  • resource attributes: tenant UID, resource kind, and resource name,

  • environment attributes supplied by the authorization request.

Supported condition operators include equals, not-equals, contains, exists, greater-than-or-equal, less-than-or-equal, all, and any.

Use ABAC when role names alone are not expressive enough. Keep policies small, explicit, and reviewed like code.

Stored Identity State

Identity state is stored in system KV namespaces under __system:*. This includes:

  • tenants,

  • users,

  • roles,

  • API-key records,

  • refresh-token records,

  • JWT signing keys,

  • tenant policy documents.

The server keeps hot policy and authentication caches for request-time speed. Security correctness should not depend on TTL alone; revocation and mutations update the relevant server-side state.

Query And MCP Boundaries

Security applies below the user interface. The frontend, MCP tools, REST semantic endpoints, Cypher, SPARQL, graph-query, and lakehouse query paths must all resolve to authorized server requests.

Important boundaries:

  • Natural-language chat uses typed semantic plans, not hidden privilege escalation.

  • Direct Cypher/SPARQL still needs the correct permission mode.

  • Lakehouse mappings and source connections are governed admin operations.

  • Query-fabric traces and benchmark artifacts must not contain credentials or raw hidden mutation paths.

  • API keys, refresh tokens, object-store credentials, and database secrets should never be checked into profile packs, guide examples, or evidence artifacts.

Recommended Role Shapes

Role Typical permissions

Reader

Read on a graph namespace, semantic profile, ontology view, and any vector index needed by that workflow.

Ingestion worker

Write on target graph/KV/vector namespaces and Read on metadata needed for validation.

Lakehouse reviewer

Read on source status and profiling evidence; Schema or Grant only if the reviewer can publish mappings.

Admin

Admin or Grant on tenant scope. Keep this rare.

Operational Checklist

  • Build with multi-tenant before relying on user separation.

  • Use TLS or a trusted private network for production endpoints.

  • Store API keys and refresh tokens in a secret manager.

  • Prefer API keys for service-to-service automation and JWT login for humans.

  • Revoke unused API keys after demos, handoffs, and incidents.

  • Use WhoAmI to verify resolved permissions after role or policy changes.

  • Keep Admin and Grant permissions out of routine chat/MCP service accounts.

  • Treat benchmark artifacts as shareable only after a no-secret review.

  • Validate feature-off behavior before enabling experimental lakehouse or write-back features.