@nya-account/node-sdk 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Neko Along
+
+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,172 @@
+# @nya-account/node-sdk
+
+Official Node.js SDK for [Nya Account](https://github.com/alongw/sso) SSO system.
+
+Provides a complete OAuth 2.1 / OIDC client with PKCE, JWT verification, and Express middleware.
+
+## Installation
+
+```bash
+npm install @nya-account/node-sdk
+# or
+pnpm add @nya-account/node-sdk
+# or
+yarn add @nya-account/node-sdk
+```
+
+## Quick Start
+
+```typescript
+import { NyaAccountClient } from '@nya-account/node-sdk'
+
+const client = new NyaAccountClient({
+    issuer: 'https://account.example.com',
+    clientId: 'my-app',
+    clientSecret: 'my-secret',
+})
+
+// Create authorization URL (with PKCE)
+const { url, codeVerifier, state } = await client.createAuthorizationUrl({
+    redirectUri: 'https://myapp.com/callback',
+    scope: 'openid profile email',
+})
+
+// Exchange code for tokens
+const tokens = await client.exchangeCode({
+    code: callbackCode,
+    redirectUri: 'https://myapp.com/callback',
+    codeVerifier,
+})
+
+// Get user info
+const userInfo = await client.getUserInfo(tokens.accessToken)
+```
+
+## Express Middleware
+
+```typescript
+import express from 'express'
+import { NyaAccountClient } from '@nya-account/node-sdk'
+import { getAuth } from '@nya-account/node-sdk/express'
+
+const app = express()
+const client = new NyaAccountClient({
+    issuer: 'https://account.example.com',
+    clientId: 'my-app',
+    clientSecret: 'my-secret',
+})
+
+// Protect all /api routes
+app.use('/api', client.authenticate())
+
+app.get('/api/me', (req, res) => {
+    const auth = getAuth(req)
+    res.json({ userId: auth?.sub, scopes: auth?.scope })
+})
+
+// Require specific scopes
+app.get('/api/profile',
+    client.authenticate(),
+    client.requireScopes('profile'),
+    (req, res) => {
+        const auth = getAuth(req)
+        res.json({ name: auth?.sub })
+    }
+)
+
+// Use introspection for sensitive operations
+app.post('/api/sensitive',
+    client.authenticate({ strategy: 'introspection' }),
+    handler
+)
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `issuer` | `string` | *required* | SSO service URL (Issuer URL) |
+| `clientId` | `string` | *required* | OAuth client ID |
+| `clientSecret` | `string` | *required* | OAuth client secret |
+| `timeout` | `number` | `10000` | HTTP request timeout in milliseconds |
+| `discoveryCacheTtl` | `number` | `3600000` | Discovery document cache TTL in milliseconds (default: 1 hour) |
+| `endpoints` | `EndpointConfig` | — | Explicitly specify endpoint URLs (auto-discovered via OIDC Discovery if omitted) |
+
+## API Reference
+
+### `NyaAccountClient`
+
+#### Authorization
+
+- **`createAuthorizationUrl(options)`** — Create an OAuth authorization URL with PKCE
+
+#### Token Operations
+
+- **`exchangeCode(options)`** — Exchange an authorization code for tokens
+- **`refreshToken(refreshToken)`** — Refresh an Access Token
+- **`revokeToken(token)`** — Revoke a token (RFC 7009)
+- **`introspectToken(token)`** — Token introspection (RFC 7662)
+
+#### User Info
+
+- **`getUserInfo(accessToken)`** — Get user info via OIDC UserInfo endpoint
+
+#### JWT Verification
+
+- **`verifyAccessToken(token, options?)`** — Locally verify a JWT Access Token (RFC 9068)
+- **`verifyIdToken(token, options?)`** — Locally verify an OIDC ID Token
+
+#### Express Middleware
+
+- **`authenticate(options?)`** — Middleware to verify Bearer Token (`local` or `introspection` strategy)
+- **`requireScopes(...scopes)`** — Middleware to validate token scopes
+
+#### Cache
+
+- **`discover()`** — Fetch OIDC Discovery document (cached with TTL)
+- **`clearCache()`** — Clear Discovery and JWT verifier cache
+
+### Express Helpers
+
+Available from `@nya-account/node-sdk/express`:
+
+- **`getAuth(req)`** — Retrieve the verified Access Token payload from a request
+- **`extractBearerToken(req)`** — Extract Bearer token from the Authorization header
+- **`sendOAuthError(res, statusCode, error, errorDescription)`** — Send an OAuth-standard error response
+
+### PKCE Utilities
+
+- **`generatePkce()`** — Generate a code_verifier and code_challenge pair
+- **`generateCodeVerifier()`** — Generate a PKCE code_verifier
+- **`generateCodeChallenge(codeVerifier)`** — Generate an S256 code_challenge
+
+## Error Handling
+
+The SDK provides typed error classes:
+
+```typescript
+import {
+    NyaAccountError,       // Base error class
+    OAuthError,            // OAuth protocol errors from the server
+    TokenVerificationError, // JWT verification failures
+    DiscoveryError,        // OIDC Discovery failures
+} from '@nya-account/node-sdk'
+
+try {
+    await client.verifyAccessToken(token)
+} catch (error) {
+    if (error instanceof TokenVerificationError) {
+        console.log(error.code)        // 'token_verification_failed'
+        console.log(error.description) // Human-readable description
+    }
+}
+```
+
+## Requirements
+
+- Node.js >= 20.0.0
+- Express 4.x or 5.x (optional, for middleware features)
+
+## License
+
+[MIT](./LICENSE)

package/dist/express-BHHzodXb.js

@@ -0,0 +1,83 @@
+//#region src/middleware/express.ts
+/**
+
+* Global symbol key for storing auth payload on request objects.
+
+* Using `Symbol.for()` ensures the same symbol is shared across
+
+* multiple bundle entry points (index.js and express.js).
+
+*/
+const AUTH_KEY = Symbol.for("@nya-account/auth-payload");
+/**
+
+* Retrieve the verified Access Token payload from a request object.
+
+*
+
+* Must be used together with `client.authenticate()` middleware.
+
+*
+
+* @example
+
+* ```typescript
+
+* app.get('/api/me', (req, res) => {
+
+*     const auth = getAuth(req)
+
+*     if (auth) {
+
+*         res.json({ userId: auth.sub })
+
+*     }
+
+* })
+
+* ```
+
+*/
+function getAuth(req) {
+	return Object.getOwnPropertyDescriptor(req, AUTH_KEY)?.value;
+}
+/**
+
+* Store the auth payload on a request object (SDK internal use).
+
+*/
+function setAuth(req, payload) {
+	Object.defineProperty(req, AUTH_KEY, {
+		value: payload,
+		configurable: true,
+		enumerable: false,
+		writable: false
+	});
+}
+/**
+
+* Extract Bearer token from the Authorization request header.
+
+*/
+function extractBearerToken(req) {
+	const header = req.headers.authorization;
+	if (!header) return null;
+	const parts = header.split(" ");
+	if (parts.length !== 2 || parts[0] !== "Bearer") return null;
+	return parts[1] ?? null;
+}
+/**
+
+* Send an OAuth-standard error response.
+
+*/
+function sendOAuthError(res, statusCode, error, errorDescription) {
+	res.status(statusCode).json({
+		error,
+		error_description: errorDescription
+	});
+}
+
+//#endregion
+export { extractBearerToken, getAuth, sendOAuthError, setAuth };
+//# sourceMappingURL=express-BHHzodXb.js.map

package/dist/express-BHHzodXb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express-BHHzodXb.js","names":["req: object","payload: AccessTokenPayload","req: Request","res: Response","statusCode: number","error: string","errorDescription: string"],"sources":["../src/middleware/express.ts"],"sourcesContent":["import type { Request, Response } from 'express'\r\nimport type { AccessTokenPayload } from '@/core/schemas'\r\n\r\n/**\r\n * Global symbol key for storing auth payload on request objects.\r\n * Using `Symbol.for()` ensures the same symbol is shared across\r\n * multiple bundle entry points (index.js and express.js).\r\n */\r\nconst AUTH_KEY = Symbol.for('@nya-account/auth-payload')\r\n\r\n/**\r\n * Retrieve the verified Access Token payload from a request object.\r\n *\r\n * Must be used together with `client.authenticate()` middleware.\r\n *\r\n * @example\r\n * ```typescript\r\n * app.get('/api/me', (req, res) => {\r\n *     const auth = getAuth(req)\r\n *     if (auth) {\r\n *         res.json({ userId: auth.sub })\r\n *     }\r\n * })\r\n * ```\r\n */\r\nexport function getAuth(req: object): AccessTokenPayload | undefined {\r\n    return Object.getOwnPropertyDescriptor(req, AUTH_KEY)?.value\r\n}\r\n\r\n/**\r\n * Store the auth payload on a request object (SDK internal use).\r\n */\r\nexport function setAuth(req: object, payload: AccessTokenPayload): void {\r\n    Object.defineProperty(req, AUTH_KEY, {\r\n        value: payload,\r\n        configurable: true,\r\n        enumerable: false,\r\n        writable: false,\r\n    })\r\n}\r\n\r\n/**\r\n * Extract Bearer token from the Authorization request header.\r\n */\r\nexport function extractBearerToken(req: Request): string | null {\r\n    const header = req.headers.authorization\r\n    if (!header) return null\r\n\r\n    const parts = header.split(' ')\r\n    if (parts.length !== 2 || parts[0] !== 'Bearer') return null\r\n\r\n    return parts[1] ?? null\r\n}\r\n\r\n/**\r\n * Send an OAuth-standard error response.\r\n */\r\nexport function sendOAuthError(\r\n    res: Response,\r\n    statusCode: number,\r\n    error: string,\r\n    errorDescription: string,\r\n): void {\r\n    res.status(statusCode).json({\r\n        error,\r\n        error_description: errorDescription,\r\n    })\r\n}\r\n"],"mappings":";;;;;;;;;;AAQA,MAAM,WAAW,OAAO,IAAI,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiBxD,SAAgB,QAAQA,KAA6C;AACjE,QAAO,OAAO,yBAAyB,KAAK,SAAS,EAAE;AAC1D;;;;;;AAKD,SAAgB,QAAQA,KAAaC,SAAmC;AACpE,QAAO,eAAe,KAAK,UAAU;EACjC,OAAO;EACP,cAAc;EACd,YAAY;EACZ,UAAU;CACb,EAAC;AACL;;;;;;AAKD,SAAgB,mBAAmBC,KAA6B;CAC5D,MAAM,SAAS,IAAI,QAAQ;AAC3B,MAAK,OAAQ,QAAO;CAEpB,MAAM,QAAQ,OAAO,MAAM,IAAI;AAC/B,KAAI,MAAM,WAAW,KAAK,MAAM,OAAO,SAAU,QAAO;AAExD,QAAO,MAAM,MAAM;AACtB;;;;;;AAKD,SAAgB,eACZC,KACAC,YACAC,OACAC,kBACI;AACJ,KAAI,OAAO,WAAW,CAAC,KAAK;EACxB;EACA,mBAAmB;CACtB,EAAC;AACL"}

package/dist/express-yO7hxKKd.d.ts

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { Request, Response } from "express";
+
+//#region src/core/schemas.d.ts
+
+declare const AccessTokenPayloadSchema: z.ZodObject<{
+  iss: z.ZodString;
+  sub: z.ZodString;
+  aud: z.ZodString;
+  scope: z.ZodString;
+  ver: z.ZodString;
+  iat: z.ZodNumber;
+  exp: z.ZodNumber;
+  jti: z.ZodString;
+  cnf: z.ZodOptional<z.ZodObject<{
+    jkt: z.ZodString;
+  }, "strip", z.ZodTypeAny, {
+    jkt: string;
+  }, {
+    jkt: string;
+  }>>;
+}, "strip", z.ZodTypeAny, {
+  scope: string;
+  exp: number;
+  iat: number;
+  sub: string;
+  aud: string;
+  iss: string;
+  jti: string;
+  ver: string;
+  cnf?: {
+    jkt: string;
+  } | undefined;
+}, {
+  scope: string;
+  exp: number;
+  iat: number;
+  sub: string;
+  aud: string;
+  iss: string;
+  jti: string;
+  ver: string;
+  cnf?: {
+    jkt: string;
+  } | undefined;
+}>;
+type AccessTokenPayload = z.infer<typeof AccessTokenPayloadSchema>;
+declare const IdTokenPayloadSchema: z.ZodObject<{
+  iss: z.ZodString;
+  sub: z.ZodString;
+  aud: z.ZodString;
+  iat: z.ZodNumber;
+  exp: z.ZodNumber;
+  nonce: z.ZodOptional<z.ZodString>;
+  name: z.ZodOptional<z.ZodString>;
+  preferred_username: z.ZodOptional<z.ZodString>;
+  email: z.ZodOptional<z.ZodString>;
+  email_verified: z.ZodOptional<z.ZodBoolean>;
+  updated_at: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+  exp: number;
+  iat: number;
+  sub: string;
+  aud: string;
+  iss: string;
+  name?: string | undefined;
+  preferred_username?: string | undefined;
+  email?: string | undefined;
+  email_verified?: boolean | undefined;
+  updated_at?: number | undefined;
+  nonce?: string | undefined;
+}, {
+  exp: number;
+  iat: number;
+  sub: string;
+  aud: string;
+  iss: string;
+  name?: string | undefined;
+  preferred_username?: string | undefined;
+  email?: string | undefined;
+  email_verified?: boolean | undefined;
+  updated_at?: number | undefined;
+  nonce?: string | undefined;
+}>;
+type IdTokenPayload = z.infer<typeof IdTokenPayloadSchema>; //#endregion
+//#region src/middleware/express.d.ts
+/**
+ * Retrieve the verified Access Token payload from a request object.
+ *
+ * Must be used together with `client.authenticate()` middleware.
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/me', (req, res) => {
+ *     const auth = getAuth(req)
+ *     if (auth) {
+ *         res.json({ userId: auth.sub })
+ *     }
+ * })
+ * ```
+ */
+declare function getAuth(req: object): AccessTokenPayload | undefined;
+/**
+ * Store the auth payload on a request object (SDK internal use).
+ */
+
+/**
+ * Extract Bearer token from the Authorization request header.
+ */
+declare function extractBearerToken(req: Request): string | null;
+/**
+ * Send an OAuth-standard error response.
+ */
+declare function sendOAuthError(res: Response, statusCode: number, error: string, errorDescription: string): void;
+
+//#endregion
+export { AccessTokenPayload, IdTokenPayload, extractBearerToken as extractBearerToken$1, getAuth as getAuth$1, sendOAuthError as sendOAuthError$1 };
+//# sourceMappingURL=express-yO7hxKKd.d.ts.map

package/dist/express-yO7hxKKd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express-yO7hxKKd.d.ts","names":[],"sources":["../src/core/schemas.d.ts","../src/middleware/express.d.ts"],"sourcesContent":null,"mappings":";;;;AAWA,IAAW,2BAAW;CAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;AAAA;AACtB,IAAW,qBAAc;CAAA;CAAA,MAAA;CAAA,MAAA,EAAA;AAAA;AACzB,IAAW,uBAAM;CAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;CAAA,MAAA,EAAA;AAAA;AACjB,IAAW,iBAAiB;CAAC;CAAI,MAAA;CAAA,MAAA,EAAA;AAAA;;;;;;;;;;;;;;;;;;;ACGjC,IAAW,UAAU,CAAC,GAAG,MAAM,kBAAmB;;;;AAQlD,IAAW,qBAAqB,CAAC,GAAG,MAAM,OAAQ;;;;AAIlD,IAAW,iBAAiB,CAAC,GAAG,MAAM,QAAS"}

package/dist/express.d.ts

@@ -0,0 +1,2 @@
+import { extractBearerToken$1 as extractBearerToken, getAuth$1 as getAuth, sendOAuthError$1 as sendOAuthError } from "./express-yO7hxKKd.js";
+export { extractBearerToken, getAuth, sendOAuthError };

package/dist/express.js

@@ -0,0 +1,3 @@
+import { extractBearerToken, getAuth, sendOAuthError } from "./express-BHHzodXb.js";
+
+export { extractBearerToken, getAuth, sendOAuthError };