@gnldev/auth weekly downloads statistics

@gnldev/auth

The auth contract the rest of the framework speaks, plus a role-based default you can use as-is.

Auth is opt-in: leave it out and the REST API and Studio stay open (fine for local work). Wire a provider in and every route is gated. In production, a missing provider is an error rather than a silent open door.

Install

Install: pnpm add @gnldev/auth — or use it from a repo clone: pnpm install && pnpm -r build.

Four credential classes

Pick the class by who holds the token, not by how much it needs to do. Credentials can be a bearer token or a user/password pair for basic auth — comparison is constant-time.

| Class | Who holds it | Organization | Can |

| superAdmin | you, running the platform | none, by design | everything, across every organization | | admin | a customer's operator | bound | manage that organization: Studio, budgets, users, workflows | | client | a customer's backend server | bound | run agents, cancel runs, read — nothing else | | viewer | a read-only operator | bound | read |

roleAuth returns undefined when no class is configured — that is what keeps auth opt-in.

Give your application client, not admin

admin is an operator credential: it cancels runs, edits budgets, manages users and reads the whole organization's history. An application that only needs to run an agent has no business holding that, and if it leaks, none of those are things you wanted a leaked key to reach.

client is a whitelist — agents:run, workflow:run, run:cancel, plus reads. Anything else is refused, including routes added in later versions. That is the direction you want the default to fail.

A client names the end user it acts for

One application credential serves many end users, so the request says which one:

resourceId is what separates one end user's conversation, memory and runs from another's. A client request that omits it is refused (400) rather than served unscoped — without a subject there is nothing to keep two of your users apart. Operator classes may omit it: they work across the organization by design.

You can then ask for one user's data, and have ownership checked:

Keep the client token on your server. It is trusted to say who it acts for, so anyone holding it can claim any resourceId. That is safe in your backend, where you already know who your user is. It is not safe in a browser or a mobile app — ship neither the token nor a proxy that forwards a caller-supplied resourceId unchecked. To let a browser call GNL directly, give it an end-user token instead (next section).

An end user can carry its own token

When your user logs in, your backend signs a short-lived token for that one user. The browser or app calls GNL with it. The holder is that user and nobody else:

Only sub is read. The holder is always a subject, with the organization from orgId above. A kind, roles or orgId claim in the token is ignored, so a token cannot make its holder staff or move it to another organization. Writes are the same whitelist as client.

A token signed with a different key, an expired one, or one without sub is nobody (401). Tokens last 15 minutes by default. Use publicKey instead of secret if you sign with RS256 or Ed25519, and issuer/audience to pin those claims.

Rules a token must meet. The secret is at least 32 bytes; a shorter one is a startup error. The sub follows the same rules as a resourceId (1–200 characters, no control characters) and may not start with operator:, application:, role: or token:, which name staff and synthetic ids.

How long a token may live. At most 1 hour (maxTtlSec, default 3600). A token claiming a later exp is refused. If you can take tokens back, pass isRevoked and you may allow up to 30 days: for a credential pasted into an MCP client's config, or a link in an email.…

Description from the npm listing.