{
  "schema": "leumas.docs.page/1",
  "id": "pkg:@leumas/auth",
  "slug": "packages/auth",
  "kind": "capabilities",
  "bucket": "package",
  "title": "@leumas/auth",
  "name": "@leumas/auth",
  "eyebrow": null,
  "chip": null,
  "summary": "The ONE Leumas gate — clean-room login + JWT session + RBAC (roles/permissions) + Stripe membership + PassNode token wallet + API keys.",
  "keywords": [
    "auth",
    "clean-room",
    "guards protect necessary",
    "stripe",
    "login",
    "auth api",
    "leumas auth",
    "auth schemas"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# @leumas/auth\n\nThe **one gate** every Leumas resource routes through. Clean-room (does not port the legacy login) but\nreproduces its shapes + security. Server-side; built on [`@leumas/db`](../db) + [`@leumas/schemas`](../schemas).\n\n## Surface\n\n| Group | Endpoints |\n|---|---|\n| **Auth** | `POST /auth/signup` · `POST /auth/verify` · `POST /auth/login` · `POST /auth/logout` · `GET /auth/session` · `GET /auth/me` |\n| **Membership** (Stripe) | `GET /membership/plans` · `GET /membership` · `POST /membership/checkout` · `/portal` · `/cancel` · `/grant` (admin) · `POST /membership/webhook` |\n| **Tokens** (PassNode) | `GET /tokens/balance` · `POST /tokens/spend` · `GET /tokens/history` · `POST /tokens/grant` (admin) |\n| **API keys** | `POST /keys` (developer) · `GET /keys` · `DELETE /keys/:id` · `POST /keys/verify` |\n\n## Guards (\"protect when necessary\")\n\n```js\nimport { requireAuth, requireRole, requirePermission, requireMembership, requireDeveloper } from '@leumas/auth';\nrouter.post('/admin-thing', requireRole('admin'), handler);\nrouter.post('/paid-thing', requirePermission('run_adapter'), handler);\n```\n\nOwnership guards (`canRead`/`canWrite`/`canClone`) live in `@leumas/db` and are applied inside handlers.\n\n## Mount\n\n```js\nimport express from 'express';\nimport { mountAuth } from '@leumas/auth';\nconst app = express();\n// skip json parsing for the Stripe webhook (it needs the raw body):\napp.use((req, res, next) => req.path === '/membership/webhook' ? next() : express.json()(req, res, next));\nmountAuth(app);   // attaches req.user + mounts /auth /membership /tokens /keys\n```\n\n## Config (env)\n\n`JWT_SECRET`, `LEUMAS_COOKIE_NAME`/`_DOMAIN`, `AUTH_AUTO_VERIFY` (dev), `LEUMAS_APIKEY_PEPPER`,\n`STRIPE_SECRET_KEY`/`STRIPE_WEBHOOK_SECRET`, `STRIPE_PRICE_{STARTER,PRO,UNLIMITED}`, `SEED_ADMIN_*`.\nSensible dev defaults keep P1 runnable offline; Stripe endpoints return 501 until configured, while\n`/membership/grant` + `/tokens/grant` give an offline path for testing entitlements.\n",
  "source": {
    "path": "shared/packages/auth/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 2207,
    "hash": "fd4707d0cbffb7ded16e4532473541487e6fe91d"
  },
  "urls": {
    "html": "/p/packages/auth",
    "json": "/docs/packages/auth.json",
    "md": "/docs/packages/auth.md"
  },
  "links": {
    "composes": [
      "pkg:@leumas/db",
      "pkg:@leumas/schemas",
      "pkg:@leumas/security"
    ],
    "usedBy": [
      "pkg:@leumas/apps",
      "pkg:@leumas/control",
      "pkg:@leumas/router-kit",
      "pkg:@leumas/social-service",
      "pkg:@leumas/variables"
    ],
    "product": [
      "pkg:@leumas/admin",
      "pkg:@leumas/studio"
    ],
    "howTo": [],
    "skills": []
  },
  "exports": {
    "total": 73,
    "component": 9,
    "hook": 0,
    "helper": 64,
    "names": [
      {
        "n": "GOOGLE_ENDPOINTS",
        "k": "component"
      },
      {
        "n": "MAX_TOPUP_TOKENS",
        "k": "component"
      },
      {
        "n": "MODES_ALLOW",
        "k": "component"
      },
      {
        "n": "PAYOUT_POLICY",
        "k": "component"
      },
      {
        "n": "PLAN_CATALOG",
        "k": "component"
      },
      {
        "n": "SESSION_DEFAULTS",
        "k": "component"
      },
      {
        "n": "SIGNIN_SCOPES",
        "k": "component"
      },
      {
        "n": "SITES_ALLOW",
        "k": "component"
      },
      {
        "n": "TOKEN_PACKS",
        "k": "component"
      },
      {
        "n": "adminAudit",
        "k": "helper"
      },
      {
        "n": "adminRouter",
        "k": "helper"
      },
      {
        "n": "apiKeyFromRequest",
        "k": "helper"
      },
      {
        "n": "apiKeysRouter",
        "k": "helper"
      },
      {
        "n": "attachApiKeyUser",
        "k": "helper"
      },
      {
        "n": "attachUser",
        "k": "helper"
      },
      {
        "n": "auditSlice",
        "k": "helper"
      },
      {
        "n": "authEvents",
        "k": "helper"
      },
      {
        "n": "authRouter",
        "k": "helper"
      },
      {
        "n": "builtinPassnodeTypes",
        "k": "helper"
      },
      {
        "n": "byUserThenIp",
        "k": "helper"
      },
      {
        "n": "clearRbacCache",
        "k": "helper"
      },
      {
        "n": "clientIp",
        "k": "helper"
      },
      {
        "n": "config",
        "k": "helper"
      },
      {
        "n": "connectConfigured",
        "k": "helper"
      },
      {
        "n": "createAgentKeysRouter",
        "k": "helper"
      },
      {
        "n": "createAuthRouter",
        "k": "helper"
      },
      {
        "n": "createAvatarRouter",
        "k": "helper"
      },
      {
        "n": "createGoogleSignIn",
        "k": "helper"
      },
      {
        "n": "createPassnode",
        "k": "helper"
      },
      {
        "n": "createPassnodeGuard",
        "k": "helper"
      },
      {
        "n": "createPassnodeRules",
        "k": "helper"
      },
      {
        "n": "createTypeRegistry",
        "k": "helper"
      },
      {
        "n": "definePassnodeType",
        "k": "helper"
      },
      {
        "n": "deployTokenGuard",
        "k": "helper"
      },
      {
        "n": "deployWriteAllowed",
        "k": "helper"
      },
      {
        "n": "emitAuthEvent",
        "k": "helper"
      },
      {
        "n": "envPinnedSessionFields",
        "k": "helper"
      },
      {
        "n": "googleSignIn",
        "k": "helper"
      },
      {
        "n": "hasRole",
        "k": "helper"
      },
      {
        "n": "hasScope",
        "k": "helper"
      },
      {
        "n": "invalidateUserRbac",
        "k": "helper"
      },
      {
        "n": "listConnectHandlers",
        "k": "helper"
      },
      {
        "n": "liveUsers",
        "k": "helper"
      },
      {
        "n": "loadUserRbac",
        "k": "helper"
      },
      {
        "n": "markSeen",
        "k": "helper"
      },
      {
        "n": "matchScore",
        "k": "helper"
      },
      {
        "n": "membershipRouter",
        "k": "helper"
      },
      {
        "n": "mountAuth",
        "k": "helper"
      },
      {
        "n": "normalizeSessionPolicy",
        "k": "helper"
      },
      {
        "n": "rateLimit",
        "k": "helper"
      },
      {
        "n": "rateLimitMemoryStore",
        "k": "helper"
      },
      {
        "n": "registerConnectHandler",
        "k": "helper"
      },
      {
        "n": "reloadSecurityConfig",
        "k": "helper"
      },
      {
        "n": "requireAuth",
        "k": "helper"
      },
      {
        "n": "requireDeveloper",
        "k": "helper"
      },
      {
        "n": "requireMembership",
        "k": "helper"
      },
      {
        "n": "requirePermission",
        "k": "helper"
      },
      {
        "n": "requireRole",
        "k": "helper"
      },
      {
        "n": "requireStaff",
        "k": "helper"
      },
      {
        "n": "resolveApiKeyUser",
        "k": "helper"
      },
      {
        "n": "resolveUser",
        "k": "helper"
      },
      {
        "n": "saveSessionPolicy",
        "k": "helper"
      },
      {
        "n": "securityConfig",
        "k": "helper"
      },
      {
        "n": "securityConfigPaths",
        "k": "helper"
      },
      {
        "n": "sessionPolicy",
        "k": "helper"
      },
      {
        "n": "signDeployToken",
        "k": "helper"
      },
      {
        "n": "startPresenceFlusher",
        "k": "helper"
      },
      {
        "n": "stopPresenceFlusher",
        "k": "helper"
      },
      {
        "n": "stripe",
        "k": "helper"
      },
      {
        "n": "stripeConfigured",
        "k": "helper"
      },
      {
        "n": "tokenPackByKey",
        "k": "helper"
      },
      {
        "n": "tokensRouter",
        "k": "helper"
      },
      {
        "n": "verifyKey",
        "k": "helper"
      }
    ]
  }
}