orama/TASK.md

Task: Enforce API Key/JWT and Namespace in Go Client (Auto-Resolve Namespace) and Guard All Operations

Owner: To be assigned Status: Ready to implement

Objective

Implement strict client-side access enforcement in the Go client (pkg/client) so that:

• An API key or JWT is required by default to use the client.
• The client auto-resolves the namespace from the provided API key or JWT without requiring callers to pass the namespace per call.
• Per-call namespace overrides via context are still allowed for compatibility, but must match the resolved namespace; otherwise, deny the call.
• All operations (Storage, PubSub, Database/RQLite, and NetworkInfo) are guarded and return access errors when unauthenticated or namespace-mismatched.
• No backward compatibility guarantees required.

Note: This is client-side enforcement for now. Protocol-level auth/ACL for libp2p can be added later.

High-level behavior

• ClientConfig.RequireAPIKey defaults to true. If true and neither APIKey nor JWT is present, Connect() fails.
• Namespace is automatically derived:
  • From JWT: parse claims and read Namespace claim (no network roundtrip). Verification of signature is not required for this task; parsing is enough to derive namespace. Optionally, add a TODO hook for future verification against JWKS if provided.
  • From API key: the namespace must be embedded in the key using a documented format (below). The client parses it locally and derives the namespace without any remote calls.
• All calls check that any provided per-call namespace override matches the derived namespace, else return an “access denied: namespace mismatch” error.
• All modules are guarded: Database (RQLite), Storage, PubSub, and NetworkInfo.

API key and JWT formats

• JWT: RS256 token with claim Namespace (string). We will parse claims (unverified) to obtain Namespace.
• API key: change to an encoded format that includes the namespace so the client can parse locally. Options (pick one and implement consistently):
  • Option A (dotted): ak_<random>.<namespace>
  • Option B (colon): ak_<random>:<namespace>
  • Option C (base64 JSON): base64url of { "kid": "...", "ns": "<namespace>" } prefixed by ak_

For simplicity and readability, choose Option B: ak_<random>:<namespace>.

• Parsing rules:
  • If APIKey contains a single colon, split and use the right side as namespace (trim spaces). If empty -> error.
  • If more than one colon or invalid format -> error.

Changes to implement

1) Client configuration and types

• File: pkg/client/interface.go
  • Extend ClientConfig:
    • Namespace string // optional; if empty, auto-derived from API key or JWT; if still empty, fallback to AppName.
    • RequireAPIKey bool // default true; when true, require either APIKey or JWT.
    • JWT string // optional bearer token; used for namespace derivation and future protocol auth.
  • Update DefaultClientConfig(appName string) to set:
    • RequireAPIKey: true
    • Namespace: "" (meaning auto)

2) Namespace resolution and access gating

• File: pkg/client/client.go
  • At construction or Connect() time:
    • Implement deriveNamespace():
      • If config.Namespace != "", use it.
      • Else if config.JWT != "", parse JWT claims (unverified) and read Namespace claim.
      • Else if config.APIKey != "", parse ak_<random>:<namespace> and extract namespace.
      • Else use config.AppName.
      • Store the resolved namespace back into config.Namespace.
    • Enforce presence of credentials:
      • If config.RequireAPIKey is true AND both config.APIKey and config.JWT are empty -> return error access denied: API key or JWT required.
  • Add func (c *Client) requireAccess(ctx context.Context) error that:
    • If RequireAPIKey and both APIKey and JWT are empty -> error access denied: credentials required.
    • Resolve per-call namespace override from context (via storage/pubsub helpers below). If present and override != c.config.Namespace -> error access denied: namespace mismatch.

3) Guard all operations

• File: pkg/client/implementations.go
  • At the start of each public method, call client.requireAccess(ctx) and return the error if any.
    • DatabaseClientImpl: Query, Transaction, CreateTable, DropTable, GetSchema.
    • StorageClientImpl: Get, Put, Delete, List, Exists.
    • NetworkInfoImpl: GetPeers, GetStatus, ConnectToPeer, DisconnectFromPeer.
  • For Storage operations, ensure we propagate the effective namespace:
    • If override present and equals config.Namespace, pass that context through; else use storage.WithNamespace(ctx, config.Namespace).

4) PubSub context-based namespace override (parity with Storage)

• Files: pkg/pubsub/*
  • Add:
    • type ctxKey string
    • const CtxKeyNamespaceOverride ctxKey = "pubsub_ns_override"
    • func WithNamespace(ctx context.Context, ns string) context.Context
  • Update topic naming in manager.go and subscriptions.go/publish.go:
    • Before computing namespacedTopic, check for ctx override; if present and non-empty, use it; else fall back to m.namespace.

5) Client context helper

• New file: pkg/client/context.go
  • Add func WithNamespace(ctx context.Context, ns string) context.Context that applies both storage and pubsub overrides by chaining:
    • ctx = storage.WithNamespace(ctx, ns)
    • ctx = pubsub.WithNamespace(ctx, ns)
    • return ctx

6) Documentation updates

• Files: README.md, AI_CONTEXT.md
  • Document the new client auth behavior:
    • An API key or JWT is required by default (RequireAPIKey=true).
    • Namespace auto-derived from token:
      • JWT claim Namespace.
      • API key format ak_<random>:<namespace>.
    • Per-call override via client.WithNamespace(ctx, ns) allowed but must match derived namespace.
    • All modules (Storage, PubSub, Database, NetworkInfo) are guarded.
  • Provide usage examples for constructing ClientConfig with API key or JWT and making calls.

Helper details

• JWT parsing: implement a minimal helper to split the token and base64url-decode the payload; read Namespace field from JSON. Do not verify signature for this task. If parsing fails, return a clear error.
• API key parsing: simple split on :; trim spaces; validate non-empty.

Error messages (standardize)

• Missing credentials: access denied: API key or JWT required
• Namespace mismatch: access denied: namespace mismatch
• Client not connected: keep existing client not connected error.

Acceptance criteria

• Without credentials and RequireAPIKey=true, Connect() returns error and no operations are allowed.
• With API key ak_abc123:myapp, the client auto-resolves namespace myapp; operations succeed.
• With JWT containing { "Namespace": "myapp" }, the client auto-resolves myapp; operations succeed.
• If a caller sets client.WithNamespace(ctx, "otherNS") while resolved namespace is myapp, any operation returns access denied: namespace mismatch.
• PubSub topic names use the override when present (and allowed) else the resolved namespace.
• NetworkInfo methods are also guarded and require credentials.

Out of scope (for this task)

• Protocol-level auth or verification of JWT signatures against JWKS.
• ETH payments/subscriptions and tier enforcement. (Separate design/implementation.)

Files to modify/add

• Modify:
  • pkg/client/interface.go
  • pkg/client/client.go
  • pkg/client/implementations.go
  • pkg/pubsub/manager.go
  • pkg/pubsub/subscriptions.go
  • pkg/pubsub/publish.go (if exists; add override resolution there too)
  • README.md, AI_CONTEXT.md
• Add:
  • pkg/pubsub/context.go (if not present)
  • pkg/client/context.go

Notes

• Keep logs concise and avoid leaking tokens in logs. You may log the resolved namespace at INFO level on connect.
• Ensure thread-safety when accessing Client.config fields (use existing locks if needed).