Support namespace scoping via JWT claims

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

Maintainers usually reply within 11 days

Nobody has claimed this yet.

Assessment

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

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.

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.

Dominant language
C
Stars
17.3k
Forks
562
Avg merge
10d 15h
Merged PRs (30d)
1

Getting set up

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.

More from tursodatabase/libsql

All issues in tursodatabase/libsql

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.