tursodatabase / tursodatabase/libsql

Support namespace scoping via JWT claims

Open
#2,217 1 comment 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
C
Stars
17.2k
Forks
531
Avg merge
1h 12m
Merged PRs (30d)
1

Description

Problem

When running sqld with --enable-namespaces in a multi-tenant setup, there's no way to restrict a JWT token to a specific namespace (or set of namespaces) using claims. Currently:

  • A valid JWT grants access to all namespaces at the specified access level (rw or ro)
  • The namespace is selected by the client via the x-namespace header
  • A compromised token can access any namespace

Existing Work

Issue #500 proposes per-namespace signing keys, which solves key isolation but requires managing N keys for N namespaces. This proposal is complementary — it uses a single signing key with claim-based scoping.

Proposal

Add support for an optional ns (or namespace) claim in the JWT payload that restricts which namespace(s) the token can access:

// Token scoped to a single namespace
{
  "a": "rw",
  "ns": "workspace-abc123",
  "exp": 1710200000
}

// Token scoped to multiple namespaces
{
  "a": "ro",
  "ns": ["workspace-abc123", "workspace-def456"],
  "exp": 1710200000
}

// Token with no ns claim = current behavior (access all namespaces)
{
  "a": "rw",
  "exp": 1710200000
}

When ns is present, sqld would validate that the requested namespace (from x-namespace header, host header, or gRPC metadata) matches the claim. Mismatches return 403.

Use Case

We're building a platform where ephemeral VMs each own a workspace backed by a sqld namespace. An orchestrator mints short-lived JWTs for each VM. Without namespace scoping in the JWT, a compromised VM could push/pull to any workspace. With this feature, each VM's token is locked to its own namespace.

This is simpler to operate than per-namespace keys (#500) when there's a single trusted token issuer (our orchestrator) but many namespaces.

Backward Compatibility

Fully backward compatible — tokens without the ns claim behave exactly as today.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at sqld's namespace authorization and JWT validation paths, including the --enable-namespaces flow and namespace values from the x-namespace header, host header, and gRPC metadata. Define how a string or array ns claim is parsed and checked, preserve access for tokens without the claim, return 403 on mismatches, and cover both single- and multi-namespace cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
grpc, rust
Domain
authentication, backend-api-design, security
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.