@usegraft/auth 0.0.0-canary-20260831153011

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @usegraft/auth
+
+> Graft verifies identity; it does not mint it. Turn a request into a scoped actor by verifying bearer JWTs against trusted issuers.
+
+Part of [Graft](https://github.com/AndersonDesign1/graft), a CMS built so an AI agent is the primary operator.
+
+## Install
+
+```bash
+npm i @usegraft/auth
+```
+
+## Resolve an actor
+
+```ts
+import { createActorResolver, betterAuthIssuer } from "@usegraft/auth";
+
+const resolveActor = createActorResolver({
+  issuers: [betterAuthIssuer("https://example.com")],
+});
+```
+
+Hand that to `graft serve`, the MCP handler, or the functions handler. It verifies the bearer JWT against the issuer's JWKS via OIDC discovery and returns a `FunctionActor` carrying a stable id and the scopes from the standard `scope` claim.
+
+Because it verifies rather than issues, an external IdP drops in unchanged. A Better Auth instance your app hosts and an enterprise IdP take the same path.
+
+## Require scopes
+
+```ts
+import { requireScopes } from "@usegraft/auth";
+
+export const listSubmissions = defineFunction({
+  name: "listSubmissions",
+  authorize: requireScopes("submissions:read"),
+  // …
+});
+```
+
+Being signed in earns nothing. An account gets scopes because something granted them, which is the whole point: open sign-up plus implicit scopes means one free registration reads everything.
+
+## Environment
+
+`GRAFT_TRUSTED_ISSUERS` for OIDC issuers, `GRAFT_DEV_TOKEN` and `GRAFT_DEV_SCOPES` for a static local identity. Anonymous MCP is refused unless `GRAFT_MCP_ALLOW_ANONYMOUS=1`, which nothing sets for you.
+
+---
+
+MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/main/packages/auth/CHANGELOG.md) · [Security policy](https://github.com/AndersonDesign1/graft/blob/main/SECURITY.md)

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { FunctionActor } from '@usegraft/core';
+import { JSONWebKeySet } from 'jose';
+
+interface TrustedIssuer {
+    /** Expected `iss` claim, exactly as the issuer mints it (e.g. "https://auth.example.com"). */
+    issuer: string;
+    /**
+     * Where the issuer's public keys live: a JWKS URL, or an inline JSON Web Key
+     * Set (pinned keys — no network). Omitted → OIDC discovery at
+     * `<issuer>/.well-known/openid-configuration`.
+     */
+    jwks?: string | JSONWebKeySet;
+    /** Expected `aud` claim. Unchecked when omitted. */
+    audience?: string | string[];
+    /** What kind of actor this issuer authenticates. Defaults to "agent". */
+    actorKind?: "agent" | "human";
+    /**
+     * Claim carrying scopes. Defaults to trying `scope` (space-separated string,
+     * the OAuth2 convention), then `scopes`, then `permissions` (arrays).
+     */
+    scopesClaim?: string;
+}
+/**
+ * Verifies bearer JWTs against a list of trusted issuers. The token's own
+ * `iss` claim picks the issuer config; an unlisted issuer is TOKEN_INVALID
+ * (details name the trusted ones — self-teaching, an agent learns where to go).
+ */
+declare function createOidcVerifier(issuers: readonly TrustedIssuer[]): (token: string) => Promise<FunctionActor>;
+/**
+ * TrustedIssuer preset for a Better Auth instance (its `jwt`/OAuth-provider
+ * plugins publish keys at `<basePath>/jwks` and mint `iss`/`aud` = its URL).
+ */
+declare function betterAuthIssuer(options: {
+    /** The Better Auth base URL (its `iss`), e.g. "http://localhost:3000". */
+    url: string;
+    /** Better Auth mount path. Defaults to "/api/auth". */
+    basePath?: string;
+    /** Expected audience. Defaults to `url`; pass null to skip the check. */
+    audience?: string | string[] | null;
+    actorKind?: "agent" | "human";
+}): TrustedIssuer;
+
+interface ActorResolverOptions {
+    /** OIDC issuers whose JWTs this deployment accepts. */
+    issuers?: readonly TrustedIssuer[];
+    /**
+     * Static bearer tokens → actors, for development and self-host bootstrap.
+     * Keep these out of production: no expiry, no scoping ceremony, one shared
+     * secret. Example: `{ [process.env.DEV_TOKEN!]: { kind: "human", id: "owner" } }`.
+     */
+    devTokens?: Record<string, FunctionActor>;
+}
+type ActorResolver = (request: Request) => Promise<FunctionActor>;
+declare function createActorResolver(options?: ActorResolverOptions): ActorResolver;
+
+/**
+ * requireScopes — an access rule for defineFunction that honors the scopes a
+ * trusted issuer put on the actor's token.
+ *
+ *   access: requireScopes("submissions:read")
+ *
+ * Strict: anonymous actors are denied, and a missing scopes claim counts as
+ * no scopes — trusted-but-unscoped tokens don't pass scope gates. Mint scoped
+ * tokens (or give dev tokens explicit `scopes`) for gated functions. With no
+ * arguments it degrades to "any non-anonymous actor".
+ */
+
+declare function requireScopes(...required: readonly string[]): (ctx: {
+    actor: FunctionActor;
+}) => boolean;
+
+export { type ActorResolver, type ActorResolverOptions, type TrustedIssuer, betterAuthIssuer, createActorResolver, createOidcVerifier, requireScopes };

package/dist/index.js

@@ -0,0 +1,148 @@
+// src/oidc.ts
+import { GraftError } from "@usegraft/contracts";
+import {
+  createLocalJWKSet,
+  createRemoteJWKSet,
+  decodeJwt,
+  jwtVerify
+} from "jose";
+function tokenInvalid(reason, details) {
+  return new GraftError({
+    code: "TOKEN_INVALID",
+    message: `The bearer token could not be verified: ${reason}.`,
+    fix: "Mint a fresh token from a trusted issuer and retry. Do not drop the Authorization header to fall back to anonymous \u2014 fix the token instead.",
+    details: { reason, ...details }
+  });
+}
+function readScopes(payload, scopesClaim) {
+  const claims = scopesClaim ? [scopesClaim] : ["scope", "scopes", "permissions"];
+  for (const claim of claims) {
+    const value = payload[claim];
+    if (typeof value === "string") return value.split(" ").filter(Boolean);
+    if (Array.isArray(value) && value.every((v) => typeof v === "string")) return value;
+  }
+  return void 0;
+}
+var IssuerVerifier = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  getKey;
+  async keySource() {
+    if (this.getKey) return this.getKey;
+    const { issuer, jwks } = this.config;
+    if (jwks && typeof jwks === "object") {
+      this.getKey = createLocalJWKSet(jwks);
+    } else if (typeof jwks === "string") {
+      this.getKey = createRemoteJWKSet(new URL(jwks));
+    } else {
+      const discoveryUrl = `${issuer.replace(/\/$/, "")}/.well-known/openid-configuration`;
+      const res = await fetch(discoveryUrl);
+      if (!res.ok) {
+        throw tokenInvalid(
+          `OIDC discovery for issuer "${issuer}" failed (${res.status} from ${discoveryUrl})`
+        );
+      }
+      const metadata = await res.json();
+      if (!metadata.jwks_uri) {
+        throw tokenInvalid(`issuer "${issuer}" publishes no jwks_uri in its OIDC metadata`);
+      }
+      this.getKey = createRemoteJWKSet(new URL(metadata.jwks_uri));
+    }
+    return this.getKey;
+  }
+  async verify(token) {
+    const getKey = await this.keySource();
+    let payload;
+    try {
+      ({ payload } = await jwtVerify(token, getKey, {
+        issuer: this.config.issuer,
+        audience: this.config.audience,
+        // jose treats `sub` as optional, so a signature-valid token without one
+        // used to authenticate as an actor with `id: undefined` — which then
+        // collapsed into an IP-keyed rate bucket, wrote null actor ids to the
+        // audit log, and filed approvals nobody could be held to.
+        requiredClaims: ["sub"]
+      }));
+    } catch (err) {
+      const code = err.code ?? "verification failed";
+      throw tokenInvalid(`${code} (issuer "${this.config.issuer}")`);
+    }
+    if (payload.sub === void 0) {
+      throw tokenInvalid(`token carries no "sub" claim (issuer "${this.config.issuer}")`);
+    }
+    return {
+      kind: this.config.actorKind ?? "agent",
+      id: payload.sub,
+      scopes: readScopes(payload, this.config.scopesClaim)
+    };
+  }
+};
+function createOidcVerifier(issuers) {
+  const verifiers = new Map(issuers.map((i) => [i.issuer, new IssuerVerifier(i)]));
+  return async (token) => {
+    let iss;
+    try {
+      iss = decodeJwt(token).iss;
+    } catch {
+      throw tokenInvalid("the token is not a decodable JWT");
+    }
+    if (!iss) throw tokenInvalid("the token carries no `iss` claim");
+    const verifier = verifiers.get(iss);
+    if (!verifier) {
+      throw tokenInvalid(`issuer "${iss}" is not trusted by this deployment`, {
+        trustedIssuers: [...verifiers.keys()]
+      });
+    }
+    return verifier.verify(token);
+  };
+}
+function betterAuthIssuer(options) {
+  const basePath = options.basePath ?? "/api/auth";
+  return {
+    issuer: options.url,
+    jwks: `${options.url.replace(/\/$/, "")}${basePath}/jwks`,
+    audience: options.audience === null ? void 0 : options.audience ?? options.url,
+    actorKind: options.actorKind
+  };
+}
+
+// src/resolver.ts
+import { GraftError as GraftError2 } from "@usegraft/contracts";
+var ANONYMOUS = { kind: "anonymous" };
+function createActorResolver(options = {}) {
+  const devTokens = new Map(Object.entries(options.devTokens ?? {}));
+  devTokens.delete("");
+  const verifyJwt = options.issuers?.length ? createOidcVerifier(options.issuers) : void 0;
+  return async (request) => {
+    const header = request.headers.get("authorization");
+    if (!header) return ANONYMOUS;
+    const match = /^Bearer\s+(.+)$/i.exec(header);
+    if (!match) return ANONYMOUS;
+    const token = match[1].trim();
+    const dev = devTokens.get(token);
+    if (dev) return dev;
+    if (verifyJwt) return verifyJwt(token);
+    throw new GraftError2({
+      code: "TOKEN_INVALID",
+      message: "A bearer token was sent, but this deployment has no trusted issuers configured.",
+      fix: "Configure `issuers` (or a dev token) in createActorResolver, or call without an Authorization header if anonymous access is intended."
+    });
+  };
+}
+
+// src/scopes.ts
+function requireScopes(...required) {
+  return ({ actor }) => {
+    if (actor.kind === "anonymous") return false;
+    const held = actor.scopes ?? [];
+    return required.every((scope) => held.includes(scope));
+  };
+}
+export {
+  betterAuthIssuer,
+  createActorResolver,
+  createOidcVerifier,
+  requireScopes
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@usegraft/auth",
+  "version": "0.0.0-canary-20260831153011",
+  "description": "Turn a request into a scoped actor by verifying bearer JWTs against trusted OIDC issuers. Graft verifies identity, it does not mint it.",
+  "keywords": [
+    "agent",
+    "ai",
+    "auth",
+    "better-auth",
+    "cms",
+    "graft",
+    "headless-cms",
+    "jwt",
+    "mcp",
+    "oidc",
+    "scopes",
+    "typescript"
+  ],
+  "homepage": "https://github.com/AndersonDesign1/graft#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndersonDesign1/graft.git",
+    "directory": "packages/auth"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@usegraft/contracts": "0.0.0-canary-20260831153011",
+    "@usegraft/core": "0.0.0-canary-20260831153011",
+    "jose": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=22.16"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}