@keycardai/oauth 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Keycard
+
+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,112 @@
+# @keycardai/oauth
+
+Pure OAuth 2.0 primitives for Keycard — JWKS key management, JWT signing/verification, authorization server discovery, and token exchange. **Zero MCP dependencies.**
+
+This is the foundational layer of the [Keycard TypeScript SDK](../../README.md). If you're building an MCP server, you probably want [`@keycardai/mcp`](../mcp/) instead, which includes this package as a dependency.
+
+## Installation
+
+```bash
+npm install @keycardai/oauth
+```
+
+## Quick Start
+
+### Sign and Verify JWTs
+
+```typescript
+import { JWTSigner } from "@keycardai/oauth/jwt/signer";
+import { JWTVerifier } from "@keycardai/oauth/jwt/verifier";
+import { JWKSOAuthKeyring } from "@keycardai/oauth/keyring";
+
+// Sign a JWT
+const keyring = new JWKSOAuthKeyring();
+const signer = new JWTSigner(keyring);
+const token = await signer.sign({
+  sub: "user-123",
+  aud: "https://api.example.com",
+  scope: "read write",
+});
+
+// Verify a JWT
+const verifier = new JWTVerifier(keyring);
+const claims = await verifier.verify(token);
+```
+
+### Discover Authorization Server Metadata
+
+```typescript
+import { fetchAuthorizationServerMetadata } from "@keycardai/oauth/discovery";
+
+const metadata = await fetchAuthorizationServerMetadata(
+  "https://your-zone.keycard.cloud",
+);
+console.log(metadata.token_endpoint);
+console.log(metadata.jwks_uri);
+```
+
+### Token Exchange (RFC 8693)
+
+```typescript
+import { TokenExchangeClient } from "@keycardai/oauth/tokenExchange";
+
+const client = new TokenExchangeClient("https://your-zone.keycard.cloud", {
+  clientId: "your-client-id",
+  clientSecret: "your-client-secret",
+});
+
+const response = await client.exchangeToken({
+  subjectToken: userBearerToken,
+  resource: "https://api.github.com",
+});
+
+console.log(response.accessToken);
+```
+
+## API Overview
+
+### JWKS Key Management
+
+| Export | Import Path | Description |
+|---|---|---|
+| `JWKSOAuthKeyring` | `@keycardai/oauth/keyring` | Fetches and caches JWKS public keys from an authorization server |
+| `OAuthKeyring` (type) | `@keycardai/oauth/keyring` | Interface for public key lookup by issuer and key ID |
+| `PrivateKeyring` (type) | `@keycardai/oauth/keyring` | Interface for private key access (signing) |
+
+### JWT Signing & Verification
+
+| Export | Import Path | Description |
+|---|---|---|
+| `JWTSigner` | `@keycardai/oauth/jwt/signer` | Signs JWTs with RS256 using a private keyring |
+| `JWTVerifier` | `@keycardai/oauth/jwt/verifier` | Verifies JWT signatures against JWKS public keys |
+| `JWTClaims` (type) | `@keycardai/oauth/jwt/signer` | Standard JWT claims (iss, sub, aud, exp, etc.) |
+
+### Discovery & Token Exchange
+
+| Export | Import Path | Description |
+|---|---|---|
+| `fetchAuthorizationServerMetadata` | `@keycardai/oauth/discovery` | Fetches `.well-known/oauth-authorization-server` metadata |
+| `TokenExchangeClient` | `@keycardai/oauth/tokenExchange` | RFC 8693 token exchange client with auto-discovery |
+
+### Errors
+
+| Export | Import Path | Description |
+|---|---|---|
+| `HTTPError` | `@keycardai/oauth/errors` | Base HTTP error |
+| `BadRequestError` | `@keycardai/oauth/errors` | 400 Bad Request |
+| `UnauthorizedError` | `@keycardai/oauth/errors` | 401 Unauthorized |
+| `OAuthError` | `@keycardai/oauth/errors` | OAuth error with error code and URI |
+| `InvalidTokenError` | `@keycardai/oauth/errors` | Token validation failure |
+| `InsufficientScopeError` | `@keycardai/oauth/errors` | Missing required scopes |
+
+### Utilities
+
+| Export | Import Path | Description |
+|---|---|---|
+| `base64url` | `@keycardai/oauth/base64url` | Base64url encode/decode utilities |
+
+## Related Packages
+
+- [`@keycardai/mcp`](../mcp/) — MCP-specific OAuth integration with Express middleware, bearer auth, and delegated access
+- [`@keycardai/sdk`](../sdk/) — Aggregate package re-exporting from both oauth and mcp
+- [Keycard TypeScript SDK](../../README.md) — Root documentation with full quick start guide

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@keycardai/oauth",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Pure OAuth 2.0 primitives for Keycard — JWKS key management, JWT signing/verification, and authorization server discovery",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keycardai/typescript-sdk.git",
+    "directory": "packages/oauth"
+  },
   "type": "module",
   "exports": {
     ".": {
@@ -51,20 +56,22 @@
   ],
   "typesVersions": {
     "*": {
-      "*": ["./dist/esm/*"]
+      "*": [
+        "./dist/esm/*"
+      ]
     }
   },
+  "dependencies": {
+    "zod": "^3.25.74"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
   "scripts": {
     "build": "pnpm run build:esm && pnpm run build:cjs",
     "build:esm": "tsc -p tsconfig.prod.json && echo '{\"type\": \"module\"}' > dist/esm/package.json",
     "build:cjs": "tsc -p tsconfig.cjs.json && echo '{\"type\": \"commonjs\"}' > dist/cjs/package.json",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist"
-  },
-  "dependencies": {
-    "zod": "^3.25.74"
-  },
-  "devDependencies": {
-    "typescript": "^5.8.3"
   }
-}
+}