@venturekit/auth 0.0.0-dev.20260308002709 → 0.0.0-dev.20260311071358

package/README.md

@@ -0,0 +1,81 @@
+# @venturekit/auth
+
+> **Warning:** This package is in active development and not production-ready. APIs may change without notice.
+
+Authentication and authorization for [VentureKit](https://venturekit.dev) — Cognito integration, RBAC, scope checking, and JWT utilities.
+
+## Installation
+
+```bash
+npm install @venturekit/auth@dev
+```
+
+## Overview
+
+`@venturekit/auth` provides:
+
+- **Cognito configuration** — `createCognitoConfig()`, `buildUserPoolConfig()`
+- **Role-based access control** — define roles, check scopes, validate permissions
+- **Scope utilities** — `hasScope()`, `hasAnyScope()`, `hasAllScopes()`, `getScopesForRoles()`
+- **Session/JWT utilities** — `decodeToken()`, `extractUserFromToken()`, `isTokenExpired()`
+
+## Roles
+
+Define roles that map to OAuth scopes:
+
+```typescript
+import type { RolesConfig } from '@venturekit/auth';
+
+const roles: RolesConfig = {
+  roles: [
+    { name: 'viewer', description: 'Read only', scopes: ['users.read'] },
+    { name: 'member', description: 'Standard user', scopes: ['users.read', 'users.write'] },
+    { name: 'admin', description: 'Full access', scopes: ['users.read', 'users.write', 'admin.users'], isSystem: true },
+  ],
+  defaultRole: 'viewer',
+  superAdminRole: 'admin',
+};
+```
+
+## Scope Checking
+
+```typescript
+import { hasScope, hasAnyScope, hasAllScopes, getScopesForRoles } from '@venturekit/auth';
+
+const allScopes = getScopesForRoles(['member'], rolesConfig);
+// → ['users.read', 'users.write']
+
+hasScope(['member'], 'users.write', rolesConfig);    // true
+hasAnyScope(['viewer'], ['users.write'], rolesConfig); // false
+hasAllScopes(['admin'], ['users.read', 'admin.users'], rolesConfig); // true
+```
+
+## JWT Utilities
+
+```typescript
+import { decodeToken, extractUserFromToken, isTokenExpired, getTokenExpiry } from '@venturekit/auth';
+
+const claims = decodeToken(jwt);          // Decode WITHOUT verification
+const user = extractUserFromToken(jwt);   // Extract user from ID token
+const expired = isTokenExpired(jwt);      // Check exp claim
+const expiry = getTokenExpiry(jwt);       // Get expiry as Date
+```
+
+> **Security:** `decodeToken` does NOT verify the JWT signature. Signature verification should be handled by API Gateway's Cognito Authorizer.
+
+## Cognito Configuration
+
+```typescript
+import { createCognitoConfig, buildUserPoolConfig } from '@venturekit/auth';
+
+const cognitoConfig = createCognitoConfig(securityConfig);
+const userPoolConfig = buildUserPoolConfig(cognitoConfig);
+```
+
+## API Reference
+
+See the [API reference](https://venturekit.dev/api-reference/auth) for full documentation.
+
+## License
+
+Apache-2.0 — see [LICENSE](../../LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venturekit/auth",
-  "version": "0.0.0-dev.20260308002709",
+  "version": "0.0.0-dev.20260311071358",
   "description": "Authentication and authorization for VentureKit",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,7 +25,7 @@
     }
   },
   "dependencies": {
-    "@venturekit/core": "0.0.0-dev.20260308002709"
+    "@venturekit/core": "0.0.0-dev.20260311071358"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",